unstructured-platform-plugins 0.0.46__tar.gz → 0.1.1.dev1__tar.gz

{unstructured_platform_plugins-0.0.46 → unstructured_platform_plugins-0.1.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unstructured_platform_plugins
-Version: 0.0.46
+Version: 0.1.1.dev1
 Summary: Wrapper to convert arbitrary code into a uvicorn/fastapi implementation for Unstructured Platform
 License-File: LICENSE.md
 Classifier: Development Status :: 4 - Beta
@@ -10,12 +10,11 @@ Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Requires-Dist: click
 Requires-Dist: dataclasses-json
 Requires-Dist: fastapi
@@ -23,6 +22,7 @@ Requires-Dist: opentelemetry-exporter-otlp-proto-grpc
 Requires-Dist: opentelemetry-instrumentation-fastapi
 Requires-Dist: requests
 Requires-Dist: unstructured-ingest
+Requires-Dist: utic-invocation-settings<1.0.0,>=0.5.0
 Requires-Dist: uvicorn
 Description-Content-Type: text/markdown
 

{unstructured_platform_plugins-0.0.46 → unstructured_platform_plugins-0.1.1.dev1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "unstructured_platform_plugins"
 description = "Wrapper to convert arbitrary code into a uvicorn/fastapi implementation for Unstructured Platform"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -10,7 +10,6 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -24,6 +23,7 @@ dependencies = [
     "fastapi",
     "click",
     "unstructured-ingest",
+    "utic-invocation-settings>=0.5.0,<1.0.0",
     "opentelemetry-instrumentation-fastapi",
     "opentelemetry-exporter-otlp-proto-grpc",
     "dataclasses-json"

unstructured_platform_plugins-0.1.1.dev1/unstructured_platform_plugins/__init__.py

@@ -0,0 +1,13 @@
+from unstructured_platform_plugins.invocation_scope import (
+    InvocationIdentity,
+    current_invocation_identity,
+    invocation_scratch_dir,
+)
+from unstructured_platform_plugins.invocation_settings import current_invocation_context
+
+__all__ = [
+    "InvocationIdentity",
+    "current_invocation_context",
+    "current_invocation_identity",
+    "invocation_scratch_dir",
+]

unstructured_platform_plugins-0.1.1.dev1/unstructured_platform_plugins/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1.dev1"  # pragma: no cover

{unstructured_platform_plugins-0.0.46 → unstructured_platform_plugins-0.1.1.dev1}/unstructured_platform_plugins/etl_uvicorn/api_generator.py

@@ -3,6 +3,7 @@ import hashlib
 import inspect
 import json
 import logging
+import re
 from typing import Any, Callable, Optional, Union, get_origin
 
 from fastapi import FastAPI, HTTPException, status
@@ -12,7 +13,7 @@ from pydantic import BaseModel, Field, create_model
 from starlette.responses import RedirectResponse
 from typing_extensions import deprecated
 from unstructured_ingest.data_types.file_data import BatchFileData, FileData, file_data_from_dict
-from unstructured_ingest.error import UnstructuredIngestError
+from unstructured_ingest.error import RateLimitError, UnstructuredIngestError, UserError
 from uvicorn.config import LOG_LEVELS
 from uvicorn.importer import import_from_string
 
@@ -25,6 +26,14 @@ from unstructured_platform_plugins.etl_uvicorn.utils import (
     get_schema_dict,
     map_inputs,
 )
+from unstructured_platform_plugins.generated.error_audience_v1 import ErrorAudience
+from unstructured_platform_plugins.invocation_settings import (
+    add_metadata_route,
+    current_invocation_context,
+    current_invocation_settings,
+    install_invocation_envelope,
+    invocation_envelope,
+)
 from unstructured_platform_plugins.schema import FileDataMeta, NewRecord, UsageData
 from unstructured_platform_plugins.schema.json_schema import (
     schema_to_base_model,
@@ -45,6 +54,16 @@ class MessageChannels(BaseModel):
     warnings: list[str] = Field(default_factory=list)
 
 
+class PluginErrorMetadata(BaseModel):
+    """Canonical metadata nested at ``plugin_error`` on a failed legacy response."""
+
+    error_type: str
+    error_reason: str
+    dependency: Optional[str] = None
+    audience: Optional[ErrorAudience] = None
+    retryable: bool = False
+
+
 def log_func_and_body(func: Callable, body: Optional[str] = None) -> None:
     msg = None
     if logger.level == LOG_LEVELS.get("debug", logging.NOTSET):
@@ -93,6 +112,57 @@ def failure_category_of(error: BaseException) -> Optional[str]:
     return category if isinstance(category, str) else None
 
 
+def _as_error_reason(category: Optional[str]) -> Optional[str]:
+    """Render a failure_category as an ``error.reason`` token, or None when it cannot be.
+
+    ``failure_category`` and ``error.reason`` are two vocabularies, not one: the preflight
+    categories are SCREAMING_SNAKE (``AUTH_PERMISSION_DENIED``) while ``error.reason`` is
+    specified lower_snake_case. ``failure_category`` still rides its own top-level response
+    field verbatim, so nothing is lost by normalizing the copy that lands here.
+
+    The category is plugin-supplied free text rather than a closed enum, so lowercasing
+    alone would not produce a snake_case token; punctuation and whitespace collapse to
+    single underscores and a category with no usable characters yields None.
+    """
+    if category is None:
+        return None
+    # -- str.lower, not category.lower: the isinstance check upstream admits str SUBCLASSES,
+    # -- and this renders an error response, where raising is the one thing it must not do --
+    reason = re.sub(r"[^a-z0-9]+", "_", str.lower(category)).strip("_")
+    return reason or None
+
+
+def plugin_error_of(error: BaseException) -> Optional[PluginErrorMetadata]:
+    """Map the legacy UserError family onto the canonical plugin-error envelope.
+
+    The ratified ErrorAudience vocabulary owns the wire spelling. A non-user failure remains
+    unclassified: orchestrators must not infer actionability from its HTTP status.
+
+    Terminal is the safe default, so a transient condition has to declare itself: a provider
+    rate limit is the one member of this family that clears on its own, and it mirrors the
+    utic_plugin_base ``RateLimitError`` declaration (platform-libs #889) field for field.
+    Retryability is orthogonal to audience -- a throttled request is still the caller's
+    quota, so the audience stays ``user``.
+
+    The class picks the DEFAULT reason; an explicit ``failure_category`` still wins, on this
+    branch as on every other. A plugin that declares a category has said something more
+    specific than the class did (a rate limit raised as ``PROVIDER_RATE_LIMITED``), and
+    dropping it here would discard the more precise of the two.
+    """
+    if not isinstance(error, UserError):
+        return None
+    if isinstance(error, RateLimitError):
+        error_type, default_reason, retryable = "dependency", "rate_limited", True
+    else:
+        error_type, default_reason, retryable = "configuration", "invalid_input", False
+    return PluginErrorMetadata(
+        error_type=error_type,
+        error_reason=_as_error_reason(failure_category_of(error)) or default_reason,
+        audience=ErrorAudience.USER,
+        retryable=retryable,
+    )
+
+
 def status_code_of(error: BaseException) -> int:
     """Return the error's status_code only when it is an int in the HTTP range, else 500."""
     status_code = _error_attr(error, "status_code")
@@ -169,9 +239,15 @@ def wrap_in_fastapi(
     func: Callable,
     plugin_id: str,
     precheck_func: Optional[Callable] = None,
+    invoke_with_sealed_dag_node_settings_v2: bool = False,
 ) -> FastAPI:
     try:
-        return _wrap_in_fastapi(func=func, plugin_id=plugin_id, precheck_func=precheck_func)
+        return _wrap_in_fastapi(
+            func=func,
+            plugin_id=plugin_id,
+            precheck_func=precheck_func,
+            invoke_with_sealed_dag_node_settings_v2=invoke_with_sealed_dag_node_settings_v2,
+        )
     except Exception as e:
         logger.error(f"failed to wrap function in FastAPI: {e}", exc_info=True)
         raise EtlApiException(e) from e
@@ -181,6 +257,7 @@ def _wrap_in_fastapi(
     func: Callable,
     plugin_id: str,
     precheck_func: Optional[Callable] = None,
+    invoke_with_sealed_dag_node_settings_v2: bool = False,
 ) -> FastAPI:
     if precheck_func is not None:
         check_precheck_func(precheck_func=precheck_func)
@@ -191,6 +268,8 @@ def _wrap_in_fastapi(
         logger.warning("usage data not an expected parameter, omitting")
 
     fastapi_app = FastAPI()
+    # Installation contributes a public router dependency, so it must happen before /invoke.
+    install_invocation_envelope(fastapi_app)
 
     response_type = get_output_sig(func)
     filedata_meta_model = update_filedata_model(response_type)
@@ -202,6 +281,7 @@ def _wrap_in_fastapi(
         filedata_meta: Optional[filedata_meta_model] = None
         status_code_text: Optional[str] = None
         failure_category: Optional[str] = None
+        plugin_error: Optional[PluginErrorMetadata] = None
         output: Optional[response_type] = None
         message_channels: MessageChannels = Field(default_factory=MessageChannels)
 
@@ -226,10 +306,34 @@ def _wrap_in_fastapi(
             request_dict["filedata_meta"] = filedata_meta
         try:
             if inspect.isasyncgenfunction(func):
+                bound_settings = current_invocation_settings()
+                bound_context = current_invocation_context()
+
                 # Stream response if function is an async generator
                 async def _stream_response():
-                    try:
-                        async for output in func(**(request_dict or {})):
+                    # FastAPI 0.117 closes yield dependencies before iterating a
+                    # StreamingResponse. Re-enter the captured binding inside the generator so the
+                    # plugin sees the right request regardless of dependency-cleanup timing.
+                    with invocation_envelope(bound_settings, bound_context):
+                        try:
+                            async for output in func(**(request_dict or {})):
+                                yield (
+                                    InvokeResponse(
+                                        usage=usage,
+                                        message_channels=message_channels,
+                                        filedata_meta=filedata_meta_model.model_validate(
+                                            filedata_meta.model_dump()
+                                        ),
+                                        status_code=status.HTTP_200_OK,
+                                        output=output,
+                                        file_data=request_dict.get("file_data", None),
+                                    ).model_dump_json()
+                                    + "\n"
+                                )
+                        except Exception as e:
+                            logger.error(
+                                f"Failure streaming response: {_safe_str(e)}", exc_info=True
+                            )
                             yield (
                                 InvokeResponse(
                                     usage=usage,
@@ -237,27 +341,13 @@ def _wrap_in_fastapi(
                                     filedata_meta=filedata_meta_model.model_validate(
                                         filedata_meta.model_dump()
                                     ),
-                                    status_code=status.HTTP_200_OK,
-                                    output=output,
-                                    file_data=request_dict.get("file_data", None),
+                                    status_code=status_code_of(e),
+                                    status_code_text=f"[{type(e).__name__}] {_safe_str(e)}",
+                                    failure_category=failure_category_of(e),
+                                    plugin_error=plugin_error_of(e),
                                 ).model_dump_json()
                                 + "\n"
                             )
-                    except Exception as e:
-                        logger.error(f"Failure streaming response: {_safe_str(e)}", exc_info=True)
-                        yield (
-                            InvokeResponse(
-                                usage=usage,
-                                message_channels=message_channels,
-                                filedata_meta=filedata_meta_model.model_validate(
-                                    filedata_meta.model_dump()
-                                ),
-                                status_code=status_code_of(e),
-                                status_code_text=f"[{type(e).__name__}] {_safe_str(e)}",
-                                failure_category=failure_category_of(e),
-                            ).model_dump_json()
-                            + "\n"
-                        )
 
                 return StreamingResponse(_stream_response(), media_type="application/x-ndjson")
             else:
@@ -299,6 +389,7 @@ def _wrap_in_fastapi(
                 status_code=status_code_of(exc),
                 status_code_text=_safe_str(exc),
                 failure_category=failure_category_of(exc),
+                plugin_error=plugin_error_of(exc),
                 file_data=request_dict.get("file_data", None),
             )
         except Exception as invoke_error:
@@ -376,6 +467,7 @@ def _wrap_in_fastapi(
         status_code: int
         status_code_text: Optional[str] = None
         failure_category: Optional[str] = None
+        plugin_error: Optional[PluginErrorMetadata] = None
 
     @fastapi_app.get("/schema")
     async def get_schema() -> SchemaOutputResponse:
@@ -391,6 +483,7 @@ def _wrap_in_fastapi(
                 status_code=fn_response.status_code,
                 status_code_text=fn_response.status_code_text,
                 failure_category=fn_response.failure_category,
+                plugin_error=fn_response.plugin_error,
                 usage=fn_response.usage,
             )
         else:
@@ -406,6 +499,13 @@ def _wrap_in_fastapi(
     except TypeError as e:
         raise TypeError(f"failed to validate function schema: {e}") from e
 
+    # Registered last so add_metadata_route replaces any /metadata the plugin registered itself.
+    add_metadata_route(
+        fastapi_app,
+        identifier=plugin_id,
+        invoke_with_sealed_dag_node_settings_v2=invoke_with_sealed_dag_node_settings_v2,
+    )
+
     FastAPIInstrumentor.instrument_app(
         fastapi_app, tracer_provider=get_trace_provider(), meter_provider=get_metric_provider()
     )
@@ -420,6 +520,7 @@ def generate_fast_api(
     id_method: Optional[str] = None,
     precheck_str: Optional[str] = None,
     precheck_method: Optional[str] = None,
+    invoke_with_sealed_dag_node_settings_v2: bool = False,
 ) -> FastAPI:
     instance = import_from_string(app)
     func = get_func(instance, method_name)
@@ -438,4 +539,9 @@ def generate_fast_api(
     elif precheck_method:
         precheck_func = get_func(instance, precheck_method)
 
-    return wrap_in_fastapi(func=func, plugin_id=plugin_id, precheck_func=precheck_func)
+    return wrap_in_fastapi(
+        func=func,
+        plugin_id=plugin_id,
+        precheck_func=precheck_func,
+        invoke_with_sealed_dag_node_settings_v2=invoke_with_sealed_dag_node_settings_v2,
+    )

{unstructured_platform_plugins-0.0.46 → unstructured_platform_plugins-0.1.1.dev1}/unstructured_platform_plugins/etl_uvicorn/main.py

@@ -56,6 +56,7 @@ def get_command() -> click.Command:
         plugin_id_method: Optional[str] = None,
         precheck_app: Optional[str] = None,
         precheck_app_method: Optional[str] = None,
+        sealed_dag_node_settings_v2: bool = False,
         **kwargs,
     ):
         # Make sure logging is configured before the call to run() so any setup has the same format
@@ -73,6 +74,7 @@ def get_command() -> click.Command:
             id_method=plugin_id_method,
             precheck_str=precheck_app,
             precheck_method=precheck_app_method,
+            invoke_with_sealed_dag_node_settings_v2=sealed_dag_node_settings_v2,
         )
         # Explicitly map values that are manipulated in the original
         # call to run(), preventing **kwargs reference
@@ -130,6 +132,14 @@ def get_command() -> click.Command:
                 "If precheck-app not provided, assumes method "
                 "lives on main class passes in.",
             ),
+            click.Option(
+                ["--sealed-dag-node-settings-v2"],
+                is_flag=True,
+                default=False,
+                help="Advertise the invoke_with_sealed_dag_node_settings_v2 capability on "
+                "/metadata. Set only for a plugin that consumes per-invoke settings "
+                "through current_invocation_settings().",
+            ),
         ]
     )
     return cmd

unstructured_platform_plugins-0.1.1.dev1/unstructured_platform_plugins/generated/__init__.py

@@ -0,0 +1 @@
+"""Schema-generated local wire-contract bindings."""

unstructured_platform_plugins-0.1.1.dev1/unstructured_platform_plugins/generated/error_audience_v1.py

@@ -0,0 +1,28 @@
+# Generated by scripts/generate_invocation_contracts.py; do not edit by hand.
+# ruff: noqa: E501
+# Source: https://schemas.u10d.dev/errors/audience/v1.json
+"""Error Audience — generated from the ratified JSON Schema.
+https://schemas.u10d.dev/errors/audience/v1
+
+Non-null actionability audience carried by plugin_error.audience; distinct from technical fault-
+source classifications such as utic_invocation_settings.Blame
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ErrorAudienceValue(str, Enum):
+    """Who can act to resolve an error."""
+    USER = "user"
+    PLATFORM = "platform"
+
+
+# Non-null actionability audience carried by plugin_error.audience; distinct from technical
+# fault-source classifications such as utic_invocation_settings.Blame
+ErrorAudience = ErrorAudienceValue
+
+# Generation provenance used by drift tests and reviewers.
+SCHEMA_ID = 'https://schemas.u10d.dev/errors/audience/v1.json'
+SCHEMA_SHA256 = '36d017a1b132d0c06ded5a60376c425e8d5a5e681f134cfdc4dcb1fa4c9498d8'

unstructured_platform_plugins-0.1.1.dev1/unstructured_platform_plugins/generated/invocation_context_v1.py

@@ -0,0 +1,89 @@
+# Generated by scripts/generate_invocation_contracts.py; do not edit by hand.
+# ruff: noqa: E501
+# Source: https://schemas.u10d.dev/invocation-context/v1.json
+"""Invocation Context — generated from the ratified JSON Schema.
+https://schemas.u10d.dev/invocation-context/v1
+
+Versioned request-scoped identity and correlation context carried in the reserved
+invocation_context field of a plugin /invoke body
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class InvocationContext(BaseModel):
+    """
+    Versioned request-scoped identity and correlation context carried in the reserved
+    invocation_context field of a plugin /invoke body
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    schema_version: Literal["1"] = Field(
+        default="1",
+        description="Payload contract version. A missing value defaults to v1; consumers reject an unknown value rather than silently dropping attribution. Additive fields do not change this value.",
+    )
+    invocation_id: str | None = Field(
+        default=None,
+        description="Correlation identifier for this individual invocation.",
+    )
+    job_id: str | None = Field(default=None, description="Job that owns the invocation.")
+    workflow_id: str | None = Field(
+        default=None,
+        description="Workflow that owns the job, when known.",
+    )
+    attribution_id: str | None = Field(
+        default=None,
+        description="Platform attribution identifier associated with the invocation.",
+    )
+    tenant_id: str | None = Field(
+        default=None,
+        description="Tenant identity to which the invocation is attributed.",
+    )
+    org_id: str | None = Field(
+        default=None,
+        description="Organization identity to which the invocation is attributed.",
+    )
+    dag_node_id: str | None = Field(
+        default=None,
+        description="Identifier of the DAG node being invoked.",
+    )
+    dag_node_type: str | None = Field(
+        default=None,
+        description="Plugin type of the DAG node being invoked.",
+    )
+    dag_node_subtype: str | None = Field(
+        default=None,
+        description="Plugin subtype of the DAG node being invoked.",
+    )
+    record_id: str | None = Field(
+        default=None,
+        description="Record being processed by a single-record invocation.",
+    )
+    attempt: int | None = Field(
+        default=None,
+        description="Attempt number associated with the claimed work.",
+    )
+    job_created_timestamp: str | None = Field(
+        default=None,
+        description="Job creation timestamp forwarded for lifecycle timing. It is context metadata, not a telemetry dimension.",
+    )
+    record_ids: list[str] | None = Field(
+        default=None,
+        description="Record identifiers in a batch invocation. When invocation_ids is also present, the two arrays are index-aligned.",
+    )
+    invocation_ids: list[str | None] | None = Field(
+        default=None,
+        description="Per-record invocation identifiers for a batch invocation. Entry i identifies record_ids[i]; null means that record carried no invocation identifier.",
+    )
+
+# Generation provenance used by drift tests and reviewers.
+SCHEMA_ID = 'https://schemas.u10d.dev/invocation-context/v1.json'
+SCHEMA_SHA256 = 'ca64be22a104acc697b7aff0fb47633ad75fa30cd88a0c92259af732fa1023c0'
+RESERVED_CONTEXT_KEY = 'invocation_context'
+SUPPORTED_CONTEXT_VERSIONS = frozenset(['1'])
+DIMENSION_FIELDS = ('invocation_id', 'tenant_id', 'org_id', 'job_id', 'workflow_id', 'attribution_id', 'dag_node_id', 'dag_node_type', 'dag_node_subtype', 'record_id', 'attempt')

unstructured_platform_plugins-0.1.1.dev1/unstructured_platform_plugins/invocation_context.py

@@ -0,0 +1,125 @@
+"""The ``invocation_context`` companion to the settings envelope.
+
+Where ``invocation_settings`` carries *what* a plugin should be configured with, the context
+carries *who* the invocation is for: the identity facets a shared-tenancy pod can no longer read
+from its process environment. It travels in a second reserved, out-of-schema field of the
+``/invoke`` body, extracted by the same route dependency that resolves the settings field.
+
+The context is `/invoke` protocol identity, not settings security: it touches no crypto and no
+secrets, and it evolves with the plugin protocol this package defines. The errors it raises come
+from the shared ``InvocationSettingsError`` taxonomy so hosts classify context failures with the
+same ``reason``/``blame`` machinery as settings failures.
+
+The model below is the **consumer** view of that contract, deliberately lenient: unknown keys are
+preserved for additive forward compatibility, and every identity field is optional so a
+partially-populated context degrades to "less telemetry" rather than a failed invoke. The one thing
+it is strict about is ``schema_version`` — that field makes incompatible producer and consumer
+contracts detectable. The payload carries the version, so evolving the contract does not require
+adding endpoints.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+import pydantic
+from utic_invocation_settings import Blame, InvocationSettingsError, MalformedEnvelopeError
+
+from unstructured_platform_plugins.generated.invocation_context_v1 import (
+    DIMENSION_FIELDS,
+    RESERVED_CONTEXT_KEY,
+    SUPPORTED_CONTEXT_VERSIONS,
+)
+from unstructured_platform_plugins.generated.invocation_context_v1 import (
+    InvocationContext as _GeneratedInvocationContext,
+)
+
+# Sentinel distinguishing a truly-absent reserved key from one present with a ``None`` value.
+_ABSENT = object()
+
+
+class UnsupportedContextVersionError(InvocationSettingsError):
+    """The ``invocation_context`` declares a ``schema_version`` this package does not understand.
+
+    This indicates deployment skew between platform components, not a fault in the request.
+    ``CONTENT`` (a 5xx) rather than ``CALLER``: contexts are produced by the platform's own claim
+    pipeline, and a 422 would make an upstream blame classifier pin a version-skew failure on the
+    customer. Failing the request prevents an unreadable context from silently removing telemetry
+    dimensions.
+    """
+
+    reason = "unsupported_context_version"
+    blame = Blame.CONTENT
+
+
+class InvocationContext(_GeneratedInvocationContext):
+    """Request-scoped identity delivered alongside one claimed unit of work.
+
+    The field shape, version literal, extra-field policy, reserved key, and dimensions are generated
+    from the ratified schema. This adapter retains the cross-field invariant JSON Schema cannot
+    express.
+    """
+
+    @pydantic.model_validator(mode="after")
+    def _batch_lists_stay_index_aligned(self) -> "InvocationContext":
+        if (
+            self.record_ids is not None
+            and self.invocation_ids is not None
+            and len(self.record_ids) != len(self.invocation_ids)
+        ):
+            raise ValueError(
+                "record_ids and invocation_ids must be the same length: "
+                "entry i of invocation_ids describes record i"
+            )
+        return self
+
+def extract_context(payload: Mapping[str, Any]) -> InvocationContext | None:
+    """Return the :class:`InvocationContext` from ``payload[RESERVED_CONTEXT_KEY]``.
+
+    Returns ``None`` only when the producer omitted the reserved key. A present-but-invalid value
+    fails closed rather than degrading to "no context", because a context that silently vanishes
+    takes a pod's tenant attribution with it.
+
+    A recognizable context carrying an unknown ``schema_version`` raises
+    :class:`UnsupportedContextVersionError` so an incompatible contract cannot be mistaken for
+    absent context.
+    """
+    raw = payload.get(RESERVED_CONTEXT_KEY, _ABSENT)
+    if raw is _ABSENT:
+        return None
+    if isinstance(raw, InvocationContext):
+        return raw
+    try:
+        return InvocationContext.model_validate(raw)
+    except pydantic.ValidationError as exc:
+        errors = exc.errors()
+        # Only a well-typed version string this package does not know reads as deployment skew; a
+        # schema_version of the wrong type is the caller's malformed context like any other field.
+        reported = _reported_version(raw)
+        if isinstance(reported, str) and any(
+            error["loc"] == ("schema_version",) for error in errors
+        ):
+            raise UnsupportedContextVersionError(
+                f"unsupported invocation_context schema_version: "
+                f"{_reported_version(raw)!r}; expected one of {sorted(SUPPORTED_CONTEXT_VERSIONS)}"
+            ) from None
+        # `from None` so the pydantic error tree does not cross the domain-error boundary; a count
+        # plus the first message is enough signal. Mirrors the envelope extraction.
+        raise MalformedEnvelopeError(
+            f"invalid invocation_context: {exc.error_count()} validation error(s), "
+            f"first: {errors[0]['msg']}"
+        ) from None
+
+
+def _reported_version(raw: Any) -> Any:
+    """The offending ``schema_version``, for the error message only. Never trusted."""
+    return raw.get("schema_version") if isinstance(raw, Mapping) else None
+
+
+def dimensions(context: InvocationContext | None) -> dict[str, Any]:
+    """The context's populated identity facets, ready to bind as telemetry dimensions."""
+    if context is None:
+        return {}
+    return {
+        field: value for field in DIMENSION_FIELDS if (value := getattr(context, field)) is not None
+    }

unstructured_platform_plugins-0.1.1.dev1/unstructured_platform_plugins/invocation_scope.py

@@ -0,0 +1,63 @@
+"""Identity and filesystem scope for the current invocation."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+from dataclasses import dataclass, fields
+from pathlib import Path
+from uuid import uuid4
+
+from unstructured_platform_plugins.invocation_settings import current_invocation_context
+
+
+@dataclass(frozen=True)
+class InvocationIdentity:
+    job_id: str | None
+    tenant_id: str | None
+    org_id: str | None
+    workflow_id: str | None
+    attribution_id: str | None
+    dag_node_id: str | None
+    dag_node_type: str | None
+    dag_node_subtype: str | None
+
+
+def current_invocation_identity() -> InvocationIdentity:
+    """Read identity from the bound context, or the environment when no context is bound."""
+    context = current_invocation_context()
+    values = {}
+    for field in fields(InvocationIdentity):
+        values[field.name] = (
+            getattr(context, field.name, None)
+            if context is not None
+            else os.getenv(field.name.upper())
+        )
+    return InvocationIdentity(**values)
+
+
+def _segment(value: str | None) -> str:
+    if not value:
+        return "unknown"
+    safe = re.sub(r"[^a-zA-Z0-9_.-]", "_", value)
+    if safe in {".", ".."} or safe != value or len(safe) > 96:
+        digest = hashlib.sha256(value.encode()).hexdigest()[:16]
+        safe = f"{safe[:79].strip('.') or 'unknown'}-{digest}"
+    return safe
+
+
+def invocation_scratch_dir(root: str | os.PathLike[str], *, create: bool = True) -> Path:
+    """Return an invocation directory, or the unchanged root when no context is bound."""
+    path = Path(root)
+    context = current_invocation_context()
+    if context is not None:
+        identity = current_invocation_identity()
+        invocation_id = context.invocation_id
+        if not invocation_id and context.record_ids is None and context.invocation_ids is None:
+            invocation_id = context.record_id
+        path = path / _segment(identity.job_id) / _segment(identity.dag_node_id)
+        path = path / _segment(invocation_id or uuid4().hex)
+    if create:
+        path.mkdir(parents=True, exist_ok=True)
+    return path

unstructured_platform_plugins-0.1.1.dev1/unstructured_platform_plugins/invocation_settings.py

@@ -0,0 +1,536 @@
+"""Transport for the reserved `/invoke` fields: request dependency, `/metadata`, optional body cap.
+
+The *settings contract* — including the only accepted sealed `/invoke` shape (the v2 settings
+document), field-level resolution, and what an absent field is allowed to mean — lives in
+`utic_invocation_settings`, next to the crypto it governs; every decision about a settings payload
+is delegated there. The *identity contract* —
+the `invocation_context` model — is
+`/invoke` protocol rather than settings security and lives in this package's
+`invocation_context` module. This module is the delivery mechanism for both: getting the payloads
+off the wire and the results to the handler, and spelling the shared `blame` taxonomy as HTTP
+statuses.
+
+The reserved fields are a first-class HTTP contract independent of the generated input schema.
+They never appear in a plugin's declared signature, so `wrap_in_fastapi` keeps producing a handler
+model built purely from the wrapped function, and a plugin reads the fields through
+`current_invocation_settings()` / `current_invocation_context()` instead.
+
+Well-formed extraction runs in a route dependency (`bind_invocation_envelope`), so the `/invoke`
+body is buffered and parsed exactly once: Starlette caches both the bytes and the parsed JSON on
+the `Request`, and the dependency reads that cached parse. Generated routes can reject malformed
+JSON while validating their typed body before dependencies run, so the installer normalizes that
+specific validation failure to the same transport error. Hosts that have established a safe
+request ceiling may opt into `InvokeBodyLimitMiddleware`, which counts bytes as they stream through
+without buffering. Wrapped plugins do not acquire a fleet-wide limit merely by upgrading this
+package.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import inspect
+import json
+import logging
+import threading
+import time
+from collections import OrderedDict
+from collections.abc import AsyncIterator, Callable, Iterator, Mapping
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any, Optional, TypeVar
+
+from fastapi import Depends, FastAPI, Request
+from fastapi.exception_handlers import request_validation_exception_handler
+from fastapi.exceptions import RequestValidationError
+from opentelemetry import trace
+from starlette.requests import ClientDisconnect
+from starlette.responses import JSONResponse
+from starlette.routing import get_route_path
+from starlette.types import ASGIApp, Receive, Scope, Send
+from utic_invocation_settings import (
+    INVOKE_WITH_SEALED_DAG_NODE_SETTINGS_V2_CAPABILITY,
+    RESERVED_ENVELOPE_KEY,
+    Blame,
+    InvocationSettingsError,
+    MalformedEnvelopeError,
+    resolve_invocation_settings,
+)
+
+from unstructured_platform_plugins.invocation_context import (
+    RESERVED_CONTEXT_KEY,
+    InvocationContext,
+    dimensions,
+    extract_context,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def http_status_for(error: BaseException) -> int:
+    """The HTTP status this transport answers for a failed resolution, from ``blame``.
+
+    One rule, the one the library README states normatively: ``Blame.CALLER`` -> 422, everything
+    else -> 500. The line it draws is whether a different request would work. Sealing drift, an
+    envelope for another recipient and a broken local mount are all 5xx, which keeps a controller's
+    blame classification off the customer, whose request was fine. Anything that is not a
+    classified error is a 500: an unclassified failure is not the caller's.
+    """
+    return 422 if getattr(error, "blame", None) is Blame.CALLER else 500
+
+
+T = TypeVar("T")
+
+_METADATA_PATH = "/metadata"
+_INVOKE_PATH = "/invoke"
+
+# A convenient opt-in ceiling for hosts that have verified it against their request distribution.
+# It is deliberately not the install default: batch invokes carry arrays of file_data payloads,
+# and a wrapper upgrade must not reject previously valid fleet traffic without an explicit choice.
+MAX_INVOKE_BODY_BYTES = 64 * 1024 * 1024
+
+_INVOCATION: ContextVar[tuple[Optional[dict], Optional[InvocationContext]]] = ContextVar(
+    "invocation", default=(None, None)
+)
+
+
+def current_invocation_settings() -> Optional[dict]:
+    """Reserved `invocation_settings` field bound for the current request, if any.
+
+    `None` means the field was genuinely absent — the only case in which a plugin may fall back to
+    its boot-time settings. A field that arrived and could not be opened never reaches a handler:
+    the binding dependency fails the request first.
+    """
+    return _INVOCATION.get()[0]
+
+
+def current_invocation_context() -> Optional[InvocationContext]:
+    """Reserved `invocation_context` field bound for the current request, if any."""
+    return _INVOCATION.get()[1]
+
+
+@contextmanager
+def invocation_envelope(
+    invocation_settings: Optional[dict], invocation_context: Optional[InvocationContext]
+) -> Iterator[None]:
+    """Bind the reserved /invoke fields for the current context."""
+    token = _INVOCATION.set((invocation_settings, invocation_context))
+    try:
+        yield
+    finally:
+        _INVOCATION.reset(token)
+
+
+def add_metadata_route(
+    app: FastAPI,
+    identifier: Optional[str] = None,
+    invoke_with_sealed_dag_node_settings_v2: bool = False,
+) -> None:
+    """Register GET /metadata advertising the reserved /invoke fields this plugin accepts.
+
+    `/metadata` is the plugin API spec's own discovery surface (`PluginMetadataOutput`): capability
+    flags are strings in its `capabilities` list, which is where the controller looks before
+    forwarding the reserved fields — no controller-private probe route.
+
+    `invocation_settings` and `invocation_context` are transport capabilities: installing the
+    dependency makes the host receive, resolve, and bind those fields. The sealed-settings
+    capability is stronger: it tells the controller that the plugin handler consumes the resolved
+    field-level v2 settings in place of boot-time state. The controller may therefore send the
+    versioned v2 document, so this remains an explicit opt-in.
+
+    Last call wins: the payload lives on `app.state` and every call overwrites it, while the route
+    is registered once. A host wrapper may register at app construction and a plugin can still
+    re-register with its own identifier afterwards, with no route-order dependence.
+    """
+    capabilities = [RESERVED_ENVELOPE_KEY, RESERVED_CONTEXT_KEY]
+    if invoke_with_sealed_dag_node_settings_v2:
+        capabilities.append(INVOKE_WITH_SEALED_DAG_NODE_SETTINGS_V2_CAPABILITY)
+    app.state.plugin_metadata_payload = {
+        "api_version": "3",
+        "identifier": identifier,
+        "capabilities": capabilities,
+    }
+    if getattr(app.state, "plugin_metadata_route_installed", False):
+        return
+    app.state.plugin_metadata_route_installed = True
+
+    # A /metadata route registered by the application itself would win by route order and pin its
+    # own stale payload; drop it so the last add_metadata_route call is the one that answers.
+    app.router.routes = [r for r in app.router.routes if getattr(r, "path", None) != _METADATA_PATH]
+
+    @app.get(_METADATA_PATH)
+    async def plugin_metadata() -> dict:
+        return app.state.plugin_metadata_payload
+
+
+class UnusableInvocationEnvelope(Exception):
+    """A reserved /invoke field arrived but cannot be used.
+
+    Raised by `bind_invocation_envelope` and answered by the handler
+    `install_invocation_envelope` registers, so the response shape — `detail` plus the library's
+    stable `reason` code as top-level siblings — stays what orchestrators parse, independent of
+    FastAPI's own error envelope.
+    """
+
+    def __init__(self, status_code: int, payload: dict):
+        super().__init__(payload.get("detail"))
+        self.status_code = status_code
+        self.payload = payload
+
+
+async def _unusable_envelope_response(
+    _request: Request, exc: UnusableInvocationEnvelope
+) -> JSONResponse:
+    return JSONResponse(status_code=exc.status_code, content=exc.payload)
+
+
+def _is_malformed_json_validation(exc: RequestValidationError) -> bool:
+    """Whether FastAPI rejected the request body before route dependencies could run."""
+    # A top-level JSONDecodeError stores the raw document and reports its integer parser offset as
+    # exactly ("body", offset). Pydantic's Json fields also emit `json_invalid`, but by then the
+    # outer request has been decoded into a mapping/list and the location continues through the
+    # model field. Those are ordinary schema-validation errors and must retain FastAPI's detail.
+    if not isinstance(exc.body, (str, bytes, bytearray)):
+        return False
+    return any(
+        error.get("type") == "json_invalid"
+        and len(location := tuple(error.get("loc", ()))) == 2
+        and location[0] == "body"
+        and isinstance(location[1], int)
+        for error in exc.errors()
+    )
+
+
+async def bind_invocation_envelope(request: Request) -> AsyncIterator[None]:
+    """Resolve the reserved /invoke fields and bind them for the duration of the request.
+
+    Runs as a route dependency, after the framework has read the body: `request.json()` is
+    Starlette-cached, so the parse is shared with the framework's own body handling.
+    A reserved field that is present but unusable fails the request rather than being
+    treated as absent, because absence is the signal to fall back to the boot-time settings file:
+    degrading a malformed field to absence would quietly answer a request configured for one
+    tenant with whatever the pod happened to boot with. Under
+    `FF_INVOCATION_SETTINGS` there is no settings file to fall back to,
+    so absent or plaintext settings fail too — as does any /invoke whose body is not a JSON
+    object, since such a body cannot carry the envelope a native pod requires.
+    """
+    # ASGI `path` includes any deployment root_path; get_route_path strips it, which is how the
+    # router itself matches, so binding fires exactly when the /invoke route does.
+    if request.method != "POST" or get_route_path(request.scope) != _INVOKE_PATH:
+        yield
+        return
+
+    try:
+        parsed = await request.json()
+    except ValueError:
+        # request.json() reads through Starlette's cached body, so this does not consume or buffer
+        # the stream a second time. A truly empty body is absence and remains subject to the
+        # native-pod policy below. Any bytes that fail JSON parsing are a malformed request, not
+        # absence: collapsing them would turn a caller-fixable syntax error into a native pod's
+        # SealedDagNodeSettingsRequiredError (RECIPIENT -> 500).
+        if await request.body():
+            raise UnusableInvocationEnvelope(
+                422,
+                {
+                    "detail": "Invalid JSON body",
+                    "reason": MalformedEnvelopeError.reason,
+                },
+            ) from None
+        parsed = None
+
+    raw_settings: Optional[Any] = None
+    if isinstance(parsed, dict):
+        raw_settings = parsed.get(RESERVED_ENVELOPE_KEY)
+        if RESERVED_ENVELOPE_KEY in parsed and not isinstance(raw_settings, dict):
+            raise UnusableInvocationEnvelope(
+                422,
+                {
+                    "detail": f"Invalid field: {RESERVED_ENVELOPE_KEY}",
+                    "reason": MalformedEnvelopeError.reason,
+                },
+            )
+    try:
+        # Off the event loop: resolution may perform blocking cryptography for independently
+        # sealed fields, and this dependency fronts every invoke on the pod.
+        invocation_settings = await asyncio.to_thread(resolve_invocation_settings, raw_settings)
+    except Exception as exc:
+        # Class name only — never envelope contents, and never the exception's own message,
+        # which can embed request-controlled values.
+        logger.warning("unusable %s payload: %s", RESERVED_ENVELOPE_KEY, type(exc).__name__)
+        payload = {"detail": f"Unusable invocation settings: {type(exc).__name__}"}
+        reason = getattr(exc, "reason", None)
+        if isinstance(reason, str):
+            payload["reason"] = reason
+        raise UnusableInvocationEnvelope(http_status_for(exc), payload) from exc
+
+    invocation_context: Optional[InvocationContext] = None
+    if isinstance(parsed, dict):
+        try:
+            invocation_context = extract_context(parsed)
+        except InvocationSettingsError as exc:
+            # A context this plugin cannot read fails loudly here rather than running with
+            # silently absent identity. Status comes from the blame taxonomy: a malformed
+            # field is the caller's 422, but an unreadable schema_version is deployment skew
+            # between platform components and must not read as a caller fault. The log line is
+            # truncated because the message can embed request-controlled values.
+            logger.warning("rejecting invalid %s: %.200s", RESERVED_CONTEXT_KEY, exc)
+            status = http_status_for(exc)
+            detail = (
+                f"Invalid field: {RESERVED_CONTEXT_KEY}"
+                if status == 422
+                else f"Unusable {RESERVED_CONTEXT_KEY}: {type(exc).__name__}"
+            )
+            raise UnusableInvocationEnvelope(
+                status, {"detail": detail, "reason": exc.reason}
+            ) from exc
+
+    # Keep plugin-side request spans aligned with the controller's wide-event dimensions. The
+    # ratified DIMENSION_FIELDS list deliberately excludes batch correlation and unknown additive
+    # fields, so only the shared invocation identity is promoted to indexed telemetry.
+    invocation_dimensions = dimensions(invocation_context)
+    if invocation_dimensions:
+        span = trace.get_current_span()
+        for key, value in invocation_dimensions.items():
+            span.set_attribute(key, value)
+
+    with invocation_envelope(invocation_settings, invocation_context):
+        yield
+
+
+async def _send_json(send: Send, status_code: int, payload: dict) -> None:
+    body = json.dumps(payload).encode()
+    await send(
+        {
+            "type": "http.response.start",
+            "status": status_code,
+            "headers": [
+                (b"content-type", b"application/json"),
+                (b"content-length", str(len(body)).encode()),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": body})
+
+
+class InvokeBodyLimitMiddleware:
+    """Reject a POST /invoke body over ``max_body_bytes`` with 413.
+
+    Counts bytes as the framework consumes them; nothing is buffered here. When the count crosses
+    the cap the downstream read is answered with ``http.disconnect``, which aborts the framework's
+    body read before another byte is held, and the 413 is sent once the application has unwound.
+    This has to sit below the framework because neither Starlette nor uvicorn bounds request-body
+    size.
+    """
+
+    def __init__(self, app: ASGIApp, max_body_bytes: int = MAX_INVOKE_BODY_BYTES):
+        self.app = app
+        self.max_body_bytes = max_body_bytes
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if (
+            scope["type"] != "http"
+            or scope.get("method") != "POST"
+            or get_route_path(scope) != _INVOKE_PATH
+        ):
+            await self.app(scope, receive, send)
+            return
+
+        seen = 0
+        exceeded = False
+        response_started = False
+
+        async def counting_receive() -> dict:
+            nonlocal seen, exceeded
+            message = await receive()
+            if message["type"] == "http.request":
+                seen += len(message.get("body", b""))
+                if seen > self.max_body_bytes:
+                    exceeded = True
+                    return {"type": "http.disconnect"}
+            return message
+
+        async def guarded_send(message: dict) -> None:
+            nonlocal response_started
+            if exceeded and not response_started:
+                # A response computed after the body was cut is answering a truncated request;
+                # drop it so the 413 below is what the caller sees. A response that started
+                # before the cap tripped keeps streaming — its start is already on the wire.
+                return
+            if message["type"] == "http.response.start":
+                response_started = True
+            await send(message)
+
+        try:
+            await self.app(scope, counting_receive, guarded_send)
+        except ClientDisconnect:
+            if not exceeded:
+                raise
+        except Exception as exc:
+            # The cut body stream can surface downstream as something other than
+            # ClientDisconnect; once the cap is the cause, the 413 below is the answer. Retain a
+            # type-only diagnostic for a coincident downstream bug without rendering its message,
+            # which may contain request data or credentials.
+            if not exceeded:
+                raise
+            logger.debug(
+                "downstream raised after /invoke body limit was exceeded: %s",
+                type(exc).__name__,
+            )
+        if exceeded and not response_started:
+            await _send_json(send, 413, {"detail": "Request body too large"})
+
+
+def install_invocation_envelope(app: FastAPI, max_body_bytes: int | None = None) -> None:
+    """Install reserved-field binding before registering a FastAPI app's routes.
+
+    Adds `bind_invocation_envelope` through the router's public dependency list and registers the
+    failure response shape. FastAPI parses a generated route's typed body before dependencies run,
+    so malformed JSON validation is normalized to that same response shape at the app boundary;
+    every other validation error retains the handler the app already had. When ``max_body_bytes``
+    is supplied, also installs the body-size cap beneath the framework. The cap is opt-in because
+    a wrapper upgrade must not impose an unvalidated fleet-wide request limit. The dependency is a
+    path/method-aware no-op outside POST /invoke, so routes registered after this call can all
+    inherit it without private dependency-graph mutation. Calling after routes have already been
+    registered raises rather than silently leaving those routes uncovered.
+
+    Idempotent per app because both host-wrapper and plugin setup may call this function, while a
+    double installation would resolve settings twice per request. A repeated call asking for a
+    different ``max_body_bytes`` raises because the installed configuration cannot be changed and
+    silently keeping the first value would misrepresent the limit actually enforced.
+    """
+    if getattr(app.state, "invocation_envelope_installed", False):
+        installed_max = app.state.invocation_envelope_max_body_bytes
+        if max_body_bytes != installed_max:
+            raise ValueError(
+                "install_invocation_envelope already installed with "
+                f"max_body_bytes={installed_max}; cannot reinstall with {max_body_bytes}"
+            )
+        return
+    if any(
+        getattr(route, "path", None) == _INVOKE_PATH
+        and "POST" in (getattr(route, "methods", None) or set())
+        for route in app.router.routes
+    ):
+        raise RuntimeError(
+            "install_invocation_envelope must be called before the POST /invoke route is registered"
+        )
+    app.state.invocation_envelope_installed = True
+    app.state.invocation_envelope_max_body_bytes = max_body_bytes
+    app.router.dependencies.append(Depends(bind_invocation_envelope))
+    if max_body_bytes is not None:
+        app.add_middleware(InvokeBodyLimitMiddleware, max_body_bytes=max_body_bytes)
+    app.add_exception_handler(UnusableInvocationEnvelope, _unusable_envelope_response)
+
+    previous_validation_handler = app.exception_handlers.get(
+        RequestValidationError, request_validation_exception_handler
+    )
+
+    async def invocation_request_validation_response(request: Request, exc: RequestValidationError):
+        if (
+            request.method == "POST"
+            and get_route_path(request.scope) == _INVOKE_PATH
+            and _is_malformed_json_validation(exc)
+        ):
+            return JSONResponse(
+                status_code=422,
+                content={
+                    "detail": "Invalid JSON body",
+                    "reason": MalformedEnvelopeError.reason,
+                },
+            )
+        response = previous_validation_handler(request, exc)
+        return await response if inspect.isawaitable(response) else response
+
+    app.add_exception_handler(RequestValidationError, invocation_request_validation_response)
+
+
+def settings_cache_key(invocation_settings: Mapping[str, Any]) -> str:
+    """Digest of an ordinary resolved settings mapping, safe for secret-bearing values."""
+    return hashlib.sha256(json.dumps(invocation_settings, sort_keys=True).encode()).hexdigest()
+
+
+class SettingsScopedCache:
+    """Bind expensive derived state (clients, models, handlers) to the settings that built it.
+
+    A plugin consuming ``current_invocation_settings()`` derives a handler from each distinct
+    resolved mapping. Construction typically performs network work (model resolution, prechecks),
+    so results are memoized by ``settings_cache_key``. Raw field envelopes never reach this cache:
+    the public settings library resolves and caches them at the field boundary before this
+    transport binds the result. Both bounds matter under shared tenancy: size caps how many
+    distinct mappings stay live, and age evicts state after credential rotation. Eviction driven
+    only by the count of distinct mappings can take arbitrarily long on a quiet pod.
+
+    Thread-safe for lookups and inserts. Concurrent misses for the same settings may build twice;
+    the extra build is wasted work, never wrong state.
+    """
+
+    def __init__(
+        self,
+        *,
+        ttl_seconds: float = 15 * 60,
+        maxsize: int = 32,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if ttl_seconds <= 0:
+            raise ValueError("ttl_seconds must be positive")
+        if maxsize < 1:
+            raise ValueError("maxsize must be at least 1")
+        self._ttl_seconds = float(ttl_seconds)
+        self._maxsize = maxsize
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._entries: OrderedDict[str, tuple[float, Any]] = OrderedDict()
+
+    def get_or_build(self, invocation_settings: Mapping[str, Any], build: Callable[[], T]) -> T:
+        """Return the cached value for these settings, building it on a miss."""
+        key = settings_cache_key(invocation_settings)
+        now = self._clock()
+        with self._lock:
+            entry = self._entries.get(key)
+            if entry is not None:
+                expires_at, value = entry
+                if now < expires_at:
+                    self._entries.move_to_end(key)
+                    return value
+                del self._entries[key]
+        value = build()
+        with self._lock:
+            # Every insert also sweeps entries whose TTL has lapsed, so a tenant that stops
+            # sending requests does not keep its credential-bearing handler live while the pod
+            # stays busy for others; per-key expiry alone only fires on that tenant's next hit.
+            # Re-read the clock: build() may take long enough for more entries to lapse.
+            now = self._clock()
+            for stale_key, (expires_at, _) in list(self._entries.items()):
+                if now >= expires_at:
+                    del self._entries[stale_key]
+            self._entries[key] = (now + self._ttl_seconds, value)
+            self._entries.move_to_end(key)
+            while len(self._entries) > self._maxsize:
+                self._entries.popitem(last=False)
+        return value
+
+    def handler_for(
+        self,
+        resolved_settings: Optional[Mapping[str, Any]],
+        *,
+        boot: Callable[[], Optional[T]],
+        build: Callable[[], T],
+    ) -> T:
+        """The handler for a request: cached per distinct resolved mapping, or the boot fallback.
+
+        Absent settings select the single handler configured by the boot-time settings file.
+        ``boot`` returning ``None`` means the pod has no boot configuration and sealed per-invoke
+        settings are required, so the request fails rather than running an unconfigured handler.
+        """
+        if resolved_settings is None:
+            handler = boot()
+            if handler is None:
+                raise ValueError(
+                    "no boot-time handler on this pod: sealed per-invoke settings are required"
+                )
+            return handler
+        return self.get_or_build(resolved_settings, build)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._entries.clear()

unstructured_platform_plugins-0.0.46/unstructured_platform_plugins/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.0.46"  # pragma: no cover