offering-protocol 0.1.0__py3-none-any.whl

offering_protocol/agent/details.py

@@ -0,0 +1,227 @@
+"""Agent-friendly Offering details and Action resolution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from urllib.parse import urljoin, urlsplit
+
+from offering_protocol.agent.client import AgentError, ServiceClient
+from offering_protocol.agent.schema import resolve_schema
+from offering_protocol.core import (
+    Action,
+    ActionRelation,
+    ActionRequest,
+    AuthenticationRequirement,
+    Offering,
+)
+
+_MAXIMUM_OPENAPI_BYTES = 1_048_576
+
+
+class OfferingIssueScope(StrEnum):
+    ACTION = "action"
+    ATTRIBUTE_SCHEMA = "attribute_schema"
+    ATTRIBUTES = "attributes"
+
+
+@dataclass(frozen=True, slots=True)
+class OfferingIssue:
+    scope: OfferingIssueScope
+    message: str
+    action_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveredHttpAction:
+    method: str
+    request: ActionRequest | None
+    response_content_types: tuple[str, ...]
+    url: str
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveredOpenApiAction:
+    operation_id: str
+    url: str
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveredAction:
+    authentication: AuthenticationRequirement
+    description: str
+    http: DiscoveredHttpAction | None
+    id: str
+    openapi: DiscoveredOpenApiAction | None
+    rel: ActionRelation
+
+
+@dataclass(frozen=True, slots=True)
+class OfferingDetails:
+    actions: tuple[DiscoveredAction, ...]
+    attribute_schema: dict[str, object] | None
+    issues: tuple[OfferingIssue, ...]
+    offering: Offering
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedAction:
+    action: DiscoveredAction
+    openapi_document: dict[str, object] | None = None
+    operation: dict[str, object] | None = None
+    request_schema: dict[str, object] | None = None
+
+
+async def get_offering_details(client: ServiceClient, identifier: str) -> OfferingDetails:
+    inspection = await client.inspect()
+    offering = await client.get_offering(identifier)
+    service_openapi = (
+        inspection.document.http.openapi.url if inspection.document.http.openapi is not None else ""
+    )
+    actions, issues = _normalize_actions(offering.actions, client.service_origin, service_openapi)
+    attribute_schema: dict[str, object] | None = None
+    if offering.schema_ is not None:
+        try:
+            target = _resolve_https_reference(offering.schema_.url, client.service_origin)
+            resolved_schema = await resolve_schema(client, target)
+            attribute_schema = resolved_schema.schema
+            if not resolved_schema.validator.is_valid(offering.attributes):
+                offering = offering.model_copy(update={"attributes": {}})
+                issues.append(
+                    OfferingIssue(
+                        OfferingIssueScope.ATTRIBUTES,
+                        "Offering attributes do not match their Attribute Schema",
+                    )
+                )
+        except (AgentError, ValueError) as error:
+            offering = offering.model_copy(update={"attributes": {}})
+            issues.append(OfferingIssue(OfferingIssueScope.ATTRIBUTE_SCHEMA, str(error)))
+    return OfferingDetails(tuple(actions), attribute_schema, tuple(issues), offering)
+
+
+async def resolve_action(client: ServiceClient, offering_id: str, action_id: str) -> ResolvedAction:
+    details = await get_offering_details(client, offering_id)
+    action = next((item for item in details.actions if item.id == action_id), None)
+    if action is None:
+        raise AgentError(f"ODP Offering does not expose usable Action {action_id}")
+    if action.http is not None:
+        request_schema = None
+        if action.http.request is not None and action.http.request.schema_ is not None:
+            target = _resolve_https_reference(
+                action.http.request.schema_.url, client.service_origin
+            )
+            request_schema = (await resolve_schema(client, target)).schema
+        return ResolvedAction(action=action, request_schema=request_schema)
+    if action.openapi is None:
+        raise AgentError("ODP Action has no usable target")
+    document = await client._supporting_json(
+        action.openapi.url,
+        "openapi",
+        "application/vnd.oai.openapi+json;version=3.1, application/json;q=0.9",
+        {"application/vnd.oai.openapi+json", "application/json"},
+        _MAXIMUM_OPENAPI_BYTES,
+    )
+    version = document.get("openapi")
+    if not isinstance(version, str) or not version.startswith("3.1."):
+        raise AgentError("ODP Action requires an OpenAPI 3.1 document")
+    matches = _openapi_operations(document, action.openapi.operation_id)
+    if len(matches) != 1:
+        raise AgentError(
+            f"ODP Action operation_id {action.openapi.operation_id} must resolve exactly once"
+        )
+    return ResolvedAction(action=action, openapi_document=document, operation=matches[0])
+
+
+def _normalize_actions(
+    actions: list[Action], service_origin: str, service_openapi: str
+) -> tuple[list[DiscoveredAction], list[OfferingIssue]]:
+    counts: dict[str, int] = {}
+    for action in actions:
+        counts[action.id] = counts.get(action.id, 0) + 1
+    discovered: list[DiscoveredAction] = []
+    issues: list[OfferingIssue] = []
+    reported: set[str] = set()
+    for action in actions:
+        if counts[action.id] > 1:
+            if action.id not in reported:
+                reported.add(action.id)
+                issues.append(
+                    OfferingIssue(
+                        OfferingIssueScope.ACTION,
+                        f"Duplicate Action identifier {action.id}",
+                        action.id,
+                    )
+                )
+            continue
+        try:
+            value = _normalize_action(action, service_origin, service_openapi)
+            if value is not None:
+                discovered.append(value)
+        except AgentError as error:
+            issues.append(OfferingIssue(OfferingIssueScope.ACTION, str(error), action.id))
+    return discovered, issues
+
+
+def _normalize_action(
+    action: Action, service_origin: str, service_openapi: str
+) -> DiscoveredAction | None:
+    if action.http is not None:
+        return DiscoveredAction(
+            authentication=action.authentication,
+            description=action.description,
+            http=DiscoveredHttpAction(
+                method=action.http.method,
+                request=action.http.request,
+                response_content_types=tuple(action.http.response_content_types),
+                url=_resolve_http_reference(action.http.href, service_origin),
+            ),
+            id=action.id,
+            openapi=None,
+            rel=action.rel,
+        )
+    if action.openapi is not None:
+        target = action.openapi.url or service_openapi
+        if not target:
+            raise AgentError("OpenAPI Action has no OpenAPI document URL")
+        return DiscoveredAction(
+            authentication=action.authentication,
+            description=action.description,
+            http=None,
+            id=action.id,
+            openapi=DiscoveredOpenApiAction(
+                action.openapi.operation_id,
+                _resolve_https_reference(target, service_origin),
+            ),
+            rel=action.rel,
+        )
+    return None
+
+
+def _resolve_http_reference(reference: str, base: str) -> str:
+    target = urljoin(f"{base}/", reference)
+    parsed = urlsplit(target)
+    if parsed.scheme not in {"http", "https"} or parsed.hostname is None:
+        raise AgentError("ODP Action target must use HTTP or HTTPS")
+    return target
+
+
+def _resolve_https_reference(reference: str, base: str) -> str:
+    target = _resolve_http_reference(reference, base)
+    if urlsplit(target).scheme != "https":
+        raise AgentError("ODP supporting document URL must use HTTPS")
+    return target
+
+
+def _openapi_operations(document: dict[str, object], operation_id: str) -> list[dict[str, object]]:
+    paths = document.get("paths")
+    if not isinstance(paths, dict):
+        raise AgentError("ODP OpenAPI document must contain paths")
+    matches: list[dict[str, object]] = []
+    for path in paths.values():
+        if not isinstance(path, dict):
+            continue
+        for method in ("delete", "get", "head", "options", "patch", "post", "put", "trace"):
+            operation = path.get(method)
+            if isinstance(operation, dict) and operation.get("operationId") == operation_id:
+                matches.append(operation)
+    return matches

offering_protocol/agent/schema.py

@@ -0,0 +1,129 @@
+"""Bounded Attribute Schema resolution."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Protocol
+from urllib.parse import urldefrag, urljoin, urlsplit
+
+from jsonschema.validators import validator_for
+from referencing import Registry, Resource
+
+from offering_protocol.agent.client import AgentError, ServiceClient
+
+_DIALECT = "https://json-schema.org/draft/2020-12/schema"
+_MAXIMUM_DOCUMENT_BYTES = 262_144
+_MAXIMUM_DOCUMENTS = 16
+_MAXIMUM_DEPTH = 8
+_MAXIMUM_GRAPH_BYTES = 1_048_576
+_STANDARD_VOCABULARY = "https://json-schema.org/draft/2020-12/vocab/"
+
+
+class SchemaValidator(Protocol):
+    def is_valid(self, instance: Any) -> bool: ...
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedSchema:
+    schema: dict[str, object]
+    validator: SchemaValidator
+
+
+async def resolve_schema(client: ServiceClient, target: str) -> ResolvedSchema:
+    root_url = _document_url(target)
+    documents: dict[str, dict[str, object]] = {}
+    graph_bytes = 0
+
+    async def load(document_url: str, depth: int) -> None:
+        nonlocal graph_bytes
+        if document_url in documents:
+            return
+        if len(documents) >= _MAXIMUM_DOCUMENTS:
+            raise AgentError("ODP Attribute Schema graph exceeds 16 documents")
+        if depth > _MAXIMUM_DEPTH:
+            raise AgentError("ODP Attribute Schema graph exceeds eight reference levels")
+        document = await client._supporting_json(
+            document_url,
+            "attribute-schema",
+            "application/schema+json",
+            {"application/schema+json"},
+            _MAXIMUM_DOCUMENT_BYTES,
+        )
+        _require_schema(document)
+        encoded = json.dumps(document, separators=(",", ":")).encode()
+        graph_bytes += len(encoded)
+        if graph_bytes > _MAXIMUM_GRAPH_BYTES:
+            raise AgentError("ODP Attribute Schema graph exceeds its byte limit")
+        documents[document_url] = document
+        for reference_url in _schema_references(document, document_url):
+            await load(reference_url, depth + 1)
+
+    await load(root_url, 0)
+    root = documents[root_url]
+    registry: Registry[Any] = Registry().with_resources(
+        (url, Resource.from_contents(document)) for url, document in documents.items()
+    )
+    validation_root = {"$id": root_url, **root}
+    validator_type = validator_for(validation_root)
+    validator_type.check_schema(validation_root)
+    return ResolvedSchema(root, validator_type(validation_root, registry=registry))
+
+
+def _document_url(value: str) -> str:
+    target, _ = urldefrag(value)
+    parsed = urlsplit(target)
+    if (
+        parsed.scheme != "https"
+        or parsed.hostname is None
+        or parsed.username is not None
+        or parsed.password is not None
+    ):
+        raise AgentError("ODP Attribute Schema references must use HTTPS")
+    return target
+
+
+def _require_schema(document: dict[str, object]) -> None:
+    if document.get("$schema") != _DIALECT:
+        raise AgentError("ODP Attribute Schema must declare JSON Schema Draft 2020-12")
+    pending: list[object] = [document]
+    while pending:
+        value = pending.pop()
+        if isinstance(value, list):
+            pending.extend(value)
+        elif isinstance(value, dict):
+            if "$dynamicRef" in value:
+                reference = value["$dynamicRef"]
+                if not isinstance(reference, str) or not reference.startswith("#"):
+                    raise AgentError(
+                        "ODP Attribute Schema $dynamicRef must be a fragment-only reference"
+                    )
+            vocabulary = value.get("$vocabulary")
+            if isinstance(vocabulary, dict):
+                for uri, required in vocabulary.items():
+                    if required is True and not str(uri).startswith(_STANDARD_VOCABULARY):
+                        raise AgentError(
+                            f"ODP Attribute Schema requires unsupported vocabulary {uri}"
+                        )
+            pending.extend(value.values())
+
+
+def _schema_references(document: object, retrieval_url: str) -> tuple[str, ...]:
+    references: list[str] = []
+    local_resources = {_document_url(retrieval_url)}
+    pending = [(document, retrieval_url)]
+    while pending:
+        value, inherited_base = pending.pop()
+        if isinstance(value, list):
+            pending.extend((child, inherited_base) for child in value)
+        elif isinstance(value, dict):
+            base = inherited_base
+            identifier = value.get("$id")
+            if isinstance(identifier, str):
+                base = urljoin(inherited_base, identifier)
+                local_resources.add(_document_url(base))
+            reference = value.get("$ref")
+            if isinstance(reference, str):
+                references.append(_document_url(urljoin(base, reference)))
+            pending.extend((child, base) for keyword, child in value.items() if keyword != "$ref")
+    return tuple(reference for reference in references if reference not in local_resources)

offering_protocol/core/__init__.py

@@ -0,0 +1,64 @@
+"""Protocol models, validation, identities, references, and pagination."""
+
+from offering_protocol.core.models import *  # noqa: F403
+from offering_protocol.core.models import __all__ as _models_all
+from offering_protocol.core.references import (
+    ReferenceError,
+    build_operation_url,
+    create_resource_identity,
+    derive_service_origin,
+    is_local_resource_identifier,
+    operation_method,
+    operation_path,
+    resolve_continuation,
+    resolve_resource_reference,
+)
+from offering_protocol.core.validation import (
+    OdpValidationError,
+    ValidationIssue,
+    parse_collection,
+    parse_collection_page,
+    parse_collection_search_request,
+    parse_filter_definition,
+    parse_filter_definition_page,
+    parse_offering,
+    parse_offering_page,
+    parse_offering_search_request,
+    parse_problem_details,
+    parse_problem_response,
+    parse_resource_identity,
+    parse_service_document,
+    parse_sort_definition,
+    parse_sort_definition_page,
+    validate_value,
+)
+
+__all__ = [
+    *_models_all,
+    "OdpValidationError",
+    "ReferenceError",
+    "ValidationIssue",
+    "build_operation_url",
+    "create_resource_identity",
+    "derive_service_origin",
+    "is_local_resource_identifier",
+    "operation_method",
+    "operation_path",
+    "parse_collection",
+    "parse_collection_page",
+    "parse_collection_search_request",
+    "parse_filter_definition",
+    "parse_filter_definition_page",
+    "parse_offering",
+    "parse_offering_page",
+    "parse_offering_search_request",
+    "parse_problem_details",
+    "parse_problem_response",
+    "parse_resource_identity",
+    "parse_service_document",
+    "parse_sort_definition",
+    "parse_sort_definition_page",
+    "resolve_continuation",
+    "resolve_resource_reference",
+    "validate_value",
+]