httk-serve 2.1.0__py3-none-any.whl

httk/registry/cli/serve/__init__.py

@@ -0,0 +1,9 @@
+"""Register the :command:`httk serve web` umbrella command."""
+
+from httk.core.register import register_cli_command
+
+register_cli_command(
+    "serve",
+    "httk.serve.web.cli:command",
+    "serve and validate httk-serve sites",
+)

httk/registry/cli/serve/py.typed

@@ -0,0 +1 @@
+

httk/registry/entries/serve/__init__.py

@@ -0,0 +1,13 @@
+"""Register httk-serve's durable, non-OPTIMADE publication family."""
+
+from httk.core import register_entry_family, register_entry_record
+
+register_entry_family(
+    name="dsp-publications",
+    family="httk.serve.dsp.config:DspPublicationEntry",
+)
+register_entry_record(
+    name="serve-dsp-publication",
+    record="httk.serve.dsp.config:DspPublicationRecord",
+    family="dsp-publications",
+)

httk/registry/entries/serve/py.typed

@@ -0,0 +1 @@
+

httk/serve/__init__.py

@@ -0,0 +1,16 @@
+"""Provide unified web-serving, application-composition, and OPTIMADE capabilities."""
+
+from .composition import ASGIAppMount, compose_asgi_apps
+from .http.apptypes import ServeApp
+from .jsondata import FrozenJsonValue, JsonScalar, JsonValue, freeze_json, thaw_json
+
+__all__ = [
+    "ASGIAppMount",
+    "FrozenJsonValue",
+    "JsonScalar",
+    "JsonValue",
+    "ServeApp",
+    "compose_asgi_apps",
+    "freeze_json",
+    "thaw_json",
+]

httk/serve/composition.py

@@ -0,0 +1,141 @@
+"""Compose caller-owned Starlette applications at explicit URL paths."""
+
+from collections.abc import Iterable
+from contextlib import AsyncExitStack, asynccontextmanager
+from dataclasses import dataclass
+from typing import Any
+
+from starlette.applications import Starlette
+from starlette.routing import BaseRoute, Mount
+from starlette.types import Receive, Scope, Send
+
+
+def _validate_mount_path(path: object) -> str:
+    """Validate and return a canonical absolute mount path."""
+    if not isinstance(path, str) or not path:
+        raise ValueError("mount paths must be non-empty strings")
+    if path == "/":
+        return path
+    if (
+        not path.startswith("/")
+        or path.endswith("/")
+        or "//" in path
+        or "\\" in path
+        or "?" in path
+        or "#" in path
+        or any(ord(character) < 32 or ord(character) == 127 for character in path)
+    ):
+        raise ValueError("mount paths must be canonical absolute paths")
+    segments = path.split("/")
+    if any(segment in ("", ".", "..") for segment in segments[1:]):
+        raise ValueError("mount paths must be canonical absolute paths")
+    return path
+
+
+@dataclass(frozen=True, slots=True)
+class ASGIAppMount:
+    """Associate a Starlette application with an explicit absolute path.
+
+    :param path: Canonical absolute URL path, with ``/`` reserved for a root
+        fallback.
+    :param app: Starlette application to mount.
+
+    The composed application owns the mounted applications for the duration of
+    its lifespan and enters each distinct child's Starlette lifespan once.
+    Constructing a mount or a composition does not close or otherwise mutate
+    caller-owned applications when validation fails.
+    """
+
+    path: str
+    app: Starlette
+
+    def __post_init__(self) -> None:
+        _validate_mount_path(self.path)
+        if not isinstance(self.app, Starlette):
+            raise TypeError("ASGIAppMount.app must be a Starlette application")
+
+
+class _MountedChild:
+    """Own one child's yielded lifespan state and route calls to that child."""
+
+    def __init__(self, app: Starlette) -> None:
+        self.app = app
+        self.state: dict[str, Any] = {}
+
+    @property
+    def routes(self) -> list[BaseRoute]:
+        """Return the live child route table for Starlette reverse routing."""
+        return self.app.routes
+
+    @asynccontextmanager
+    async def lifespan(self):
+        try:
+            async with self.app.router.lifespan_context(self.app) as state:
+                self.state = dict(state or {})
+                yield
+        finally:
+            self.state.clear()
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        child_scope = dict(scope)
+        if scope["type"] in {"http", "websocket"}:
+            child_scope["state"] = {**dict(scope.get("state") or {}), **self.state}
+        await self.app(child_scope, receive, send)
+
+
+def _ordered_mounts(mounts: Iterable[ASGIAppMount], root: ASGIAppMount | None) -> list[ASGIAppMount]:
+    """Validate mount ownership and return routes from specific to broad."""
+    supplied = list(mounts)
+    if any(not isinstance(mount, ASGIAppMount) for mount in supplied):
+        raise TypeError("mounts must contain ASGIAppMount instances")
+    if root is not None and not isinstance(root, ASGIAppMount):
+        raise TypeError("root must be an ASGIAppMount instance or None")
+
+    paths = [mount.path for mount in supplied]
+    if "/" in paths:
+        raise ValueError("the root mount must be supplied with root=, not among mounts")
+    if root is not None and root.path != "/":
+        raise ValueError("root mount path must be '/'")
+    if len(paths) != len(set(paths)):
+        raise ValueError("mount paths must be unique")
+
+    return sorted(supplied, key=lambda mount: (-mount.path.count("/"), mount.path))
+
+
+def compose_asgi_apps(mounts: Iterable[ASGIAppMount], *, root: ASGIAppMount | None = None) -> Starlette:
+    """Compose Starlette applications at caller-selected URL paths.
+
+    More-specific paths are routed before their ancestors regardless of caller
+    order. At application startup, each distinct mounted child is entered in
+    that deterministic route order and is exited in reverse order; a failed
+    startup unwinds children that already started. The returned parent owns
+    lifespan coordination but not application configuration or data.
+
+    :param mounts: Service mounts with paths other than ``/``.
+    :param root: Optional ``ASGIAppMount`` at ``/`` used as the fallback route.
+    :return: Parent Starlette application containing the requested mounts.
+    :raises TypeError: If a descriptor or application has the wrong type.
+    :raises ValueError: If paths are malformed, noncanonical, or duplicated.
+    """
+    ordered = _ordered_mounts(mounts, root)
+    all_mounts = ordered + ([root] if root is not None else [])
+    children_by_id: dict[int, _MountedChild] = {}
+    children: list[_MountedChild] = []
+    routes: list[Mount] = []
+    for mount in all_mounts:
+        app_id = id(mount.app)
+        child = children_by_id.get(app_id)
+        if child is None:
+            child = _MountedChild(mount.app)
+            children_by_id[app_id] = child
+            children.append(child)
+        routes.append(Mount(mount.path, app=child))
+
+    @asynccontextmanager
+    async def lifespan(_app: Starlette):
+        async with AsyncExitStack() as stack:
+            for child in children:
+                await stack.enter_async_context(child.lifespan())
+            yield
+
+    return Starlette(routes=routes, lifespan=lifespan)

httk/serve/dsp/__init__.py

@@ -0,0 +1,92 @@
+"""Serve the DSP 2025-1 minimal public-catalogue profile."""
+
+from .api import create_dsp_app
+from .callbacks import CallbackSender, CallbackTransportError, DefaultCallbackSender, callback_url
+from .catalogue import (
+    DCAT_MEDIA_TYPE,
+    DCAT_PROFILE,
+    DspCataloguePolicy,
+    DspCatalogueRepresentation,
+    MinimalDspCataloguePolicy,
+)
+from .config import (
+    DCAT_AP_3_0_1_PROFILE,
+    DCAT_AP_MINIMAL_CONTENT_NEGOTIATION,
+    DCAT_AP_MINIMAL_PROFILE,
+    DSP_2025_1_SPECIFICATION,
+    DSP_CONTEXT,
+    DSP_MINIMAL_PROFILE,
+    DSP_VERSION,
+    EU_FILE_TYPE_CSV,
+    EU_FILE_TYPE_JSON,
+    HTTP_ENDPOINT_TYPE,
+    IANA_MEDIA_TYPE_CSV,
+    IANA_MEDIA_TYPE_JSON,
+    SPDX_SHA256,
+    DspDatasetPublication,
+    DspProviderConfig,
+    DspPublicationEntry,
+    DspPublicationRecord,
+)
+from .models import (
+    AgreementRecord,
+    CatalogueProfile,
+    DataServiceProfile,
+    DatasetProfile,
+    DcatDataServiceProfile,
+    DeliveryStatus,
+    DistributionProfile,
+    DspProtocolError,
+    DspTransitionSuperseded,
+    JsonValue,
+    NegotiationRecord,
+    OfferProfile,
+    TransferRecord,
+)
+from .provider import DspProvider, UtcClock, UuidFactory
+
+__all__ = [
+    "DCAT_AP_3_0_1_PROFILE",
+    "DCAT_AP_MINIMAL_CONTENT_NEGOTIATION",
+    "DCAT_AP_MINIMAL_PROFILE",
+    "DCAT_MEDIA_TYPE",
+    "DCAT_PROFILE",
+    "DSP_2025_1_SPECIFICATION",
+    "DSP_CONTEXT",
+    "DSP_MINIMAL_PROFILE",
+    "DSP_VERSION",
+    "EU_FILE_TYPE_CSV",
+    "EU_FILE_TYPE_JSON",
+    "HTTP_ENDPOINT_TYPE",
+    "IANA_MEDIA_TYPE_CSV",
+    "IANA_MEDIA_TYPE_JSON",
+    "SPDX_SHA256",
+    "AgreementRecord",
+    "CallbackSender",
+    "CallbackTransportError",
+    "CatalogueProfile",
+    "DataServiceProfile",
+    "DatasetProfile",
+    "DcatDataServiceProfile",
+    "DefaultCallbackSender",
+    "DeliveryStatus",
+    "DistributionProfile",
+    "DspCataloguePolicy",
+    "DspCatalogueRepresentation",
+    "DspDatasetPublication",
+    "DspProtocolError",
+    "DspProvider",
+    "DspProviderConfig",
+    "DspPublicationEntry",
+    "DspPublicationRecord",
+    "DspTransitionSuperseded",
+    "JsonValue",
+    "MinimalDspCataloguePolicy",
+    "NegotiationRecord",
+    "OfferProfile",
+    "TransferRecord",
+    "UtcClock",
+    "UuidFactory",
+    "callback_url",
+    "create_dsp_app",
+]

httk/serve/dsp/api.py

@@ -0,0 +1,169 @@
+"""Adapt the bundled DSP OpenAPI contract through the public OpenAPI adapter."""
+
+from collections.abc import Callable, Mapping
+from contextlib import asynccontextmanager
+from functools import partial
+from typing import Any
+
+from httk.serve.http import ServeApp
+from httk.serve.http.openapi import (
+    OpenAPIRequest,
+    OpenAPIRequestError,
+    OpenAPIResponse,
+    OperationBinding,
+    OperationContext,
+    create_openapi_app,
+    operation,
+)
+
+from .catalogue import DCAT_MEDIA_TYPE, DCAT_PROFILE
+from .models import DspProtocolError, ErrorKind
+from .provider import DspProvider
+from .validation import dsp_contract
+
+_OPERATIONS: Mapping[str, OperationBinding] = {
+    "version_discovery": operation(DspProvider.version_document),
+    "catalog_request": operation(DspProvider.catalogue, aliases={"body": "request"}, extras=("representation",)),
+    "dataset_request": operation(DspProvider.dsp_dataset, aliases={"id": "dataset_id"}),
+    "negotiation_state": operation(DspProvider.get_negotiation),
+    "negotiation_request": operation(
+        DspProvider.request_negotiation, aliases={"body": "message"}, extras=("_automatic_batch",)
+    ),
+    "negotiation_counter_request": operation(DspProvider.counter_request, aliases={"body": "message"}),
+    "negotiation_event": operation(DspProvider.negotiation_event, aliases={"body": "message"}),
+    "agreement_verification": operation(
+        DspProvider.verify_agreement, aliases={"body": "message"}, extras=("_automatic_batch",)
+    ),
+    "negotiation_termination": operation(DspProvider.receive_negotiation_termination, aliases={"body": "message"}),
+    "transfer_state": operation(DspProvider.get_transfer),
+    "transfer_request": operation(
+        DspProvider.request_transfer, aliases={"body": "message"}, extras=("_automatic_batch",)
+    ),
+    "transfer_start": operation(DspProvider.resume_transfer, aliases={"body": "message"}),
+    "transfer_suspension": operation(DspProvider.receive_transfer_suspension, aliases={"body": "message"}),
+    "transfer_completion": operation(DspProvider.receive_transfer_completion, aliases={"body": "message"}),
+    "transfer_termination": operation(DspProvider.receive_transfer_termination, aliases={"body": "message"}),
+}
+
+
+def _error_kind(operation_id: str) -> ErrorKind:
+    """Classify an operation for its official DSP error document."""
+    if operation_id.startswith("catalog") or operation_id == "dataset_request":
+        return "catalog"
+    if operation_id.startswith("negotiation") or operation_id == "agreement_verification":
+        return "negotiation"
+    return "transfer"
+
+
+def _schema_error(operation_id: str, detail: str, path: Mapping[str, str], body: object) -> DspProtocolError:
+    """Convert adapter validation errors into official protocol error objects."""
+    mapping = body if isinstance(body, Mapping) else {}
+    provider_pid = path.get("providerPid") or mapping.get("providerPid")
+    consumer_pid = mapping.get("consumerPid")
+    return DspProtocolError(
+        _error_kind(operation_id),
+        400,
+        detail,
+        code="invalid-message",
+        provider_pid=provider_pid if isinstance(provider_pid, str) else None,
+        consumer_pid=consumer_pid if isinstance(consumer_pid, str) else None,
+    )
+
+
+def _complete_error_document(error: DspProtocolError, path: Mapping[str, str], body: object) -> dict[str, Any]:
+    """Fill mandatory process correlation fields when malformed input omitted them."""
+    document = error.as_document()
+    if error.kind in {"negotiation", "transfer"}:
+        mapping = body if isinstance(body, Mapping) else {}
+        document.setdefault("providerPid", path.get("providerPid") or mapping.get("providerPid") or "")
+        document.setdefault("consumerPid", mapping.get("consumerPid") or "")
+        for field_name in ("providerPid", "consumerPid"):
+            value = document[field_name]
+            if not isinstance(value, str) or any(0xD800 <= ord(character) <= 0xDFFF for character in value):
+                document[field_name] = ""
+    return document
+
+
+@asynccontextmanager
+async def _scope(provider: DspProvider, request: OpenAPIRequest):
+    """Supply per-request DSP inputs and defer automatic callbacks past a clean response."""
+    batch = provider.automatic_batch()
+    context = OperationContext(extras={"_automatic_batch": batch})
+    if request.operation.operation_id == "catalog_request":
+        representation = provider.select_catalogue_representation(request.header("accept"))
+        context.extras["representation"] = representation
+        context.media_type = representation.media_type
+        context.headers = dict(representation.headers)
+    yield context
+    if provider.has_automatic_actions(batch):
+        context.after_response = partial(provider.release_automatic, batch)
+
+
+def _request_error(error: OpenAPIRequestError) -> OpenAPIResponse:
+    """Convert neutral request failures to DSP's schema-validated error response."""
+    protocol_error = _schema_error(
+        error.operation.operation_id, error.detail, error.request.path_params, error.request.body
+    )
+    return _protocol_error(protocol_error, error.request)
+
+
+def _protocol_error(error: DspProtocolError, request: OpenAPIRequest) -> OpenAPIResponse:
+    """Convert a DSP protocol exception to the neutral response contract."""
+    return OpenAPIResponse(
+        error.status_code,
+        _complete_error_document(error, request.path_params, request.body),
+        media_type="application/json",
+    )
+
+
+def _adapt_protocol_error(error: Exception, request: OpenAPIRequest) -> OpenAPIResponse:
+    """Narrow the generic exception hook to DSP protocol exceptions."""
+    if not isinstance(error, DspProtocolError):
+        raise TypeError("DSP exception adapter received a non-DSP exception")
+    return _protocol_error(error, request)
+
+
+def create_dsp_app(provider: DspProvider, *, debug: bool = False) -> ServeApp:
+    """Create a mountable serving application for one DSP provider.
+
+    Routes, methods, body schemas, status codes, and media types are loaded from
+    the packaged OpenAPI 3.1 contract. Request and response validation resolves
+    only the packaged offline schema registry.
+
+    :param provider: In-memory provider whose business operations are exposed.
+    :param debug: Whether Starlette debug responses are enabled for unexpected failures.
+    :return: Mountable serving application with the provider on ``app.state``.
+    :raises TypeError: If ``provider`` is not a :class:`DspProvider`.
+    :raises RuntimeError: If the packaged contract uses an unsupported construct.
+    """
+    if not isinstance(provider, DspProvider):
+        raise TypeError("provider must be a DspProvider")
+
+    @asynccontextmanager
+    async def lifespan(_app: ServeApp):
+        try:
+            yield
+        finally:
+            await provider.cancel_automatic()
+
+    contract = dsp_contract()
+    exception_handlers: Mapping[type[Exception], Callable[[Exception, OpenAPIRequest], OpenAPIResponse]] = {
+        DspProtocolError: _adapt_protocol_error
+    }
+    app = create_openapi_app(
+        contract,
+        _OPERATIONS,
+        implementation=provider,
+        request_error_handler=_request_error,
+        exception_handlers=exception_handlers,
+        request_scope=partial(_scope, provider),
+        scope_names=("_automatic_batch", "representation"),
+        lifespan=lifespan,
+        debug=debug,
+        path_converters={"id": "path"},
+    )
+    app.state.dsp_provider = provider
+    return app
+
+
+__all__ = ["DCAT_MEDIA_TYPE", "DCAT_PROFILE", "create_dsp_app"]

httk/serve/dsp/callbacks.py

@@ -0,0 +1,24 @@
+"""DSP-facing names for the hardened outbound webhook transport.
+
+The implementation moved to :mod:`httk.serve.http.webhook`. These names are
+retained as the DSP-facing spelling of the generic transport and resolve to the
+same objects, so identity and :func:`isinstance` checks continue to hold.
+"""
+
+from httk.serve.http.webhook import (
+    PinnedHttpsJsonPoster,
+    WebhookSender,
+    WebhookTransportError,
+    _ResolvedAddress,  # noqa: F401  # re-exported for the DSP test seam.
+    _validate_callback_url,  # noqa: F401  # re-exported for the DSP test seam.
+    _WebhookTarget,
+    join_url_path,
+)
+
+CallbackSender = WebhookSender
+CallbackTransportError = WebhookTransportError
+DefaultCallbackSender = PinnedHttpsJsonPoster
+callback_url = join_url_path
+_CallbackTarget = _WebhookTarget
+
+__all__ = ["CallbackSender", "CallbackTransportError", "DefaultCallbackSender", "callback_url"]