Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@
SyncPageFetcher,
)
from nemo_platform_plugin.client.types import (
DEFAULT_RETRY_POLICY,
BinaryContent,
OffsetPagination,
Paginated,
Expand Down Expand Up @@ -117,7 +118,7 @@ def __init__(
base_url: str,
workspace: str | None = None,
auth: TokenProvider | str | None = None,
retry: RetryPolicy | None = None,
retry: RetryPolicy = DEFAULT_RETRY_POLICY,
default_headers: Mapping[str, str] | None = None,
) -> None:
self._base_url = base_url.rstrip("/")
Expand All @@ -136,7 +137,7 @@ def workspace(self) -> str | None:
return self._workspace

@property
def retry(self) -> RetryPolicy | None:
def retry(self) -> RetryPolicy:
return self._retry

def _resolve_retry(self, retry: RetryPolicy | None) -> RetryPolicy | None:
Expand Down Expand Up @@ -240,7 +241,7 @@ def __init__(
auth: TokenProvider | str | None = None,
default_headers: Mapping[str, str] | None = None,
timeout: float = DEFAULT_TIMEOUT,
retry: RetryPolicy | None = None,
retry: RetryPolicy = DEFAULT_RETRY_POLICY,
http_client: httpx.Client | None = None,
) -> None:
super().__init__(
Expand Down Expand Up @@ -452,7 +453,7 @@ def __init__(
auth: TokenProvider | str | None = None,
default_headers: Mapping[str, str] | None = None,
timeout: float = DEFAULT_TIMEOUT,
retry: RetryPolicy | None = None,
retry: RetryPolicy = DEFAULT_RETRY_POLICY,
http_client: httpx.AsyncClient | None = None,
) -> None:
super().__init__(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -328,6 +328,7 @@ def __init__(
self.request = request
self._fetch_page = fetch_page
self._strategy: type[PaginationStrategy] = strategy or OffsetPagination
self._first_page: PageResult[ModelT] | None = None

@property
def http_response(self) -> httpx.Response:
Expand All @@ -340,37 +341,48 @@ def _parse_page(self, raw: httpx.Response) -> tuple[list[ModelT], dict]:
items = [self._model_type.model_validate(item) for item in self._strategy.extract_items(body)]
return items, body

def _next_page(self, items: list[ModelT], body: dict) -> Any | None:
"""Compute the next page marker, or ``None`` to stop.

Stops when the current page returned zero items (guards against a
server reporting more pages than it can actually serve), and advances
from the page number echoed in the response body rather than a
client-side counter.
"""
if not items:
return None
current = self._strategy.extract_metadata(body).get("page") or 1
return self._strategy.next_page(body, current)

def page(self) -> PageResult[ModelT]:
"""Return the first page as a :class:`PageResult` with metadata."""
items, body = self._parse_page(self._first_response)
metadata = self._strategy.extract_metadata(body)
return PageResult(items=items, **metadata)
if self._first_page is None:
items, body = self._parse_page(self._first_response)
metadata = self._strategy.extract_metadata(body)
self._first_page = PageResult(items=items, **metadata)
return self._first_page

def items(self) -> Iterator[ModelT]:
"""Iterate all items across all pages, fetching subsequent pages lazily."""
items, body = self._parse_page(self._first_response)
yield from items

next_page = self._strategy.next_page(body, 1)
next_page = self._next_page(items, body)
while next_page is not None:
items, body = self._parse_page(self._fetch_page(self.request, next_page))
yield from items
current = next_page
next_page = self._strategy.next_page(body, current)
next_page = self._next_page(items, body)

def pages(self) -> Iterator[PageResult[ModelT]]:
"""Iterate page by page, yielding :class:`PageResult` objects with metadata."""
items, body = self._parse_page(self._first_response)
metadata = self._strategy.extract_metadata(body)
yield PageResult(items=items, **metadata)
yield PageResult(items=items, **self._strategy.extract_metadata(body))

next_page = self._strategy.next_page(body, 1)
next_page = self._next_page(items, body)
while next_page is not None:
items, body = self._parse_page(self._fetch_page(self.request, next_page))
metadata = self._strategy.extract_metadata(body)
yield PageResult(items=items, **metadata)
current = next_page
next_page = self._strategy.next_page(body, current)
yield PageResult(items=items, **self._strategy.extract_metadata(body))
next_page = self._next_page(items, body)


class AsyncNemoPaginatedResponse(Generic[ModelT]):
Expand Down Expand Up @@ -398,6 +410,7 @@ def __init__(
self.request = request
self._fetch_page = fetch_page
self._strategy: type[PaginationStrategy] = strategy or OffsetPagination
self._first_page: PageResult[ModelT] | None = None

@property
def http_response(self) -> httpx.Response:
Expand All @@ -410,38 +423,49 @@ def _parse_page(self, raw: httpx.Response) -> tuple[list[ModelT], dict]:
items = [self._model_type.model_validate(item) for item in self._strategy.extract_items(body)]
return items, body

def _next_page(self, items: list[ModelT], body: dict) -> Any | None:
"""Compute the next page marker, or ``None`` to stop.

Stops when the current page returned zero items (guards against a
server reporting more pages than it can actually serve), and advances
from the page number echoed in the response body rather than a
client-side counter.
"""
if not items:
return None
current = self._strategy.extract_metadata(body).get("page") or 1
return self._strategy.next_page(body, current)

def page(self) -> PageResult[ModelT]:
"""Return the first page as a :class:`PageResult` with metadata."""
items, body = self._parse_page(self._first_response)
metadata = self._strategy.extract_metadata(body)
return PageResult(items=items, **metadata)
if self._first_page is None:
items, body = self._parse_page(self._first_response)
metadata = self._strategy.extract_metadata(body)
self._first_page = PageResult(items=items, **metadata)
return self._first_page

async def items(self) -> AsyncIterator[ModelT]:
"""Iterate all items across all pages, fetching subsequent pages lazily."""
items, body = self._parse_page(self._first_response)
for item in items:
yield item

next_page = self._strategy.next_page(body, 1)
next_page = self._next_page(items, body)
while next_page is not None:
raw = await self._fetch_page(self.request, next_page)
items, body = self._parse_page(raw)
for item in items:
yield item
current = next_page
next_page = self._strategy.next_page(body, current)
next_page = self._next_page(items, body)

async def pages(self) -> AsyncIterator[PageResult[ModelT]]:
"""Iterate page by page, yielding :class:`PageResult` objects with metadata."""
items, body = self._parse_page(self._first_response)
metadata = self._strategy.extract_metadata(body)
yield PageResult(items=items, **metadata)
yield PageResult(items=items, **self._strategy.extract_metadata(body))

next_page = self._strategy.next_page(body, 1)
next_page = self._next_page(items, body)
while next_page is not None:
raw = await self._fetch_page(self.request, next_page)
items, body = self._parse_page(raw)
metadata = self._strategy.extract_metadata(body)
yield PageResult(items=items, **metadata)
current = next_page
next_page = self._strategy.next_page(body, current)
yield PageResult(items=items, **self._strategy.extract_metadata(body))
next_page = self._next_page(items, body)
Original file line number Diff line number Diff line change
Expand Up @@ -204,6 +204,13 @@ class RetryPolicy:
retryable_status_codes: tuple[int, ...] = (502, 503, 504, 429)


# Shared default: retries transient failures out of the box. The retryable set
# is deliberately conservative (pre-processing failures only), so replaying a
# non-safe method is safe — notably 409 is excluded because it carries the
# entity store's optimistic-lock conflict, which must never be retried blindly.
DEFAULT_RETRY_POLICY = RetryPolicy()
Comment on lines +207 to +211

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Don’t default-retry write requests without an idempotency guard.

This policy is now the default, and the retry loop replays request bodies. 502/503/504/429 can occur after backend processing, so POST/PATCH/PUT may be duplicated or surface false conflicts. Gate default retries to safe/idempotent methods, or require an Idempotency-Key before retrying writes.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/nemo_platform_plugin/src/nemo_platform_plugin/client/types.py`
around lines 207 - 211, The default retry policy in the
RetryPolicy/DEFAULT_RETRY_POLICY path is currently applied too broadly and can
replay write request bodies without protection. Update the retry logic so it
only retries safe/idempotent methods by default, and only allows POST/PATCH/PUT
retries when an Idempotency-Key guard is present or equivalent idempotency check
exists. Make the change in the retry-policy setup and any request-classification
helper used by the Nemo platform client types so transient errors like
502/503/504/429 are not blindly retried for non-idempotent writes.



@dataclass(frozen=True, slots=True)
class PreparedRequest(Generic[ResponseT]):
"""A request ready to be sent — carries the endpoint metadata and payload.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
if TYPE_CHECKING:
from nemo_platform import AsyncNeMoPlatform
from nemo_platform_plugin.config import PlatformConfig
from nemo_platform_plugin.entities import EntityClient
from nemo_platform_plugin.entities import EntityClient, EntityStoreResource


def get_platform_config() -> "PlatformConfig":
Expand Down Expand Up @@ -62,3 +62,24 @@ def get_entity_client() -> "EntityClient":
"Ensure your Service subclass calls super().create_app() or "
"configure entity_client in the service."
)


def get_entity_store_resource() -> "EntityStoreResource":
"""Return a NemoClient-backed :class:`EntityStoreResource`.

Unlike the sibling placeholders (``get_sdk_client``, ``get_entity_client``,
``get_platform_config``), this has a real default implementation because
everything it needs lives in ``nemo_platform_plugin``: the client transport,
the env-based context/header builder (``client_provider``), and the entity
client itself — no ``nmp-core`` bits required.

The default builds an env-scoped client (``NMP_BASE_URL`` / ``NMP_PRINCIPAL``
via ``client_provider.get_async_nemo_client``), which is the correct context
for task containers, background jobs, and controllers. For request handling,
``Service`` still overrides this via ``app.dependency_overrides`` with a
request-scoped client (service-principal + on-behalf-of headers).
"""
from nemo_platform_plugin.client_provider import get_async_nemo_client
from nemo_platform_plugin.entities import EntityStoreResource

return EntityStoreResource.from_client(get_async_nemo_client())
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

"""Entity Store client package.

Re-exports the legacy Stainless-backed :class:`EntityClient` and shared entity
types (``entities.legacy``) so existing ``from nemo_platform_plugin.entities
import ...`` imports keep working, alongside the new NemoClient-backed
:class:`EntityStoreResource` (``entities.resource``) and its low-level
:class:`EntitiesClient` (``entities.client``).
"""

from nemo_platform_plugin.entities.client import AsyncEntitiesClient as AsyncEntitiesClient
from nemo_platform_plugin.entities.client import EntitiesClient as EntitiesClient
from nemo_platform_plugin.entities.legacy import EntityBase as EntityBase
from nemo_platform_plugin.entities.legacy import EntityClient as EntityClient
from nemo_platform_plugin.entities.legacy import EntityClientProtocol as EntityClientProtocol
from nemo_platform_plugin.entities.legacy import EntityConflictError as EntityConflictError
from nemo_platform_plugin.entities.legacy import EntityNotFoundError as EntityNotFoundError
from nemo_platform_plugin.entities.legacy import EntityStoreError as EntityStoreError
from nemo_platform_plugin.entities.legacy import EntityT as EntityT
from nemo_platform_plugin.entities.legacy import EntityToken as EntityToken
from nemo_platform_plugin.entities.legacy import EntityTypeDefault as EntityTypeDefault
from nemo_platform_plugin.entities.legacy import EntityTypeLike as EntityTypeLike
from nemo_platform_plugin.entities.legacy import EntityValidationError as EntityValidationError
from nemo_platform_plugin.entities.legacy import ListResponse as ListResponse
from nemo_platform_plugin.entities.legacy import PaginationInfo as PaginationInfo
from nemo_platform_plugin.entities.legacy import _convert_filter_obj_to_filter_str as _convert_filter_obj_to_filter_str
from nemo_platform_plugin.entities.legacy import _convert_sort_to_api_sort as _convert_sort_to_api_sort
from nemo_platform_plugin.entities.legacy import _get_entity_type as _get_entity_type
from nemo_platform_plugin.entities.legacy import parse_qualified_name as parse_qualified_name
from nemo_platform_plugin.entities.resource import EntityStoreResource as EntityStoreResource
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

"""Low-level typed HTTP clients for the Entity Store service.

Wraps the endpoint functions from ``entities.endpoints`` as direct methods via
the ``method()`` descriptor, following the files-service ``FilesClient`` pattern.
These are the transport layer; the ergonomic, entity-model-aware wrapper is
``EntityStoreResource`` in ``entities.resource``.
"""

from nemo_platform_plugin.client.client import AsyncNemoClient, NemoClient
from nemo_platform_plugin.client.method import method
from nemo_platform_plugin.entities import endpoints


class _EntitiesMethods:
create_entity = method(endpoints.create_entity)
list_entities = method(endpoints.list_entities)
get_entity_by_name = method(endpoints.get_entity_by_name)
get_entity_by_id = method(endpoints.get_entity_by_id)
update_entity_by_name = method(endpoints.update_entity_by_name)
delete_entity_by_name = method(endpoints.delete_entity_by_name)


class EntitiesClient(_EntitiesMethods, NemoClient):
"""Sync low-level client for the Entity Store API."""


class AsyncEntitiesClient(_EntitiesMethods, AsyncNemoClient):
"""Async low-level client for the Entity Store API."""
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

"""Typed endpoint definitions for the Entity Store service (generic routes).

Single source of truth for the HTTP contract of the generic entity routes.
Projects and workspaces routers are out of scope — the entity client only
uses the generic ``/entities`` routes.
"""

from __future__ import annotations

from abc import abstractmethod

from nemo_platform_plugin.client.endpoint import delete, get, post, put
from nemo_platform_plugin.client.types import Paginated
from nemo_platform_plugin.entities.types import (
DeleteResponse,
EntityCreateInput,
EntityResponse,
EntityUpdate,
ListEntitiesQueryParams,
ParentQueryParams,
)


@post("/apis/entities/v2/workspaces/{workspace}/entities/{entity_type}")
@abstractmethod
def create_entity(*, workspace: str | None = None, entity_type: str, body: EntityCreateInput) -> EntityResponse: ...


@get("/apis/entities/v2/workspaces/{workspace}/entities/{entity_type}")
@abstractmethod
def list_entities(
*, workspace: str | None = None, entity_type: str, query_params: ListEntitiesQueryParams | None = None
) -> Paginated[EntityResponse]: ...


@get("/apis/entities/v2/workspaces/{workspace}/entities/{entity_type}/{name}")
@abstractmethod
def get_entity_by_name(
*, workspace: str | None = None, entity_type: str, name: str, query_params: ParentQueryParams | None = None
) -> EntityResponse: ...


@get("/apis/entities/v2/entities/{id}")
@abstractmethod
def get_entity_by_id(*, id: str) -> EntityResponse: ...


@put("/apis/entities/v2/workspaces/{workspace}/entities/{entity_type}/{name}")
@abstractmethod
def update_entity_by_name(
*,
workspace: str | None = None,
entity_type: str,
name: str,
body: EntityUpdate,
query_params: ParentQueryParams | None = None,
) -> EntityResponse: ...


@delete("/apis/entities/v2/workspaces/{workspace}/entities/{entity_type}/{name}")
@abstractmethod
def delete_entity_by_name(
*, workspace: str | None = None, entity_type: str, name: str, query_params: ParentQueryParams | None = None
) -> DeleteResponse: ...
Loading