tigrcorn-contract 0.3.16__py3-none-any.whl

tigrcorn_contract/__init__.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from .classification import (
+    BindingClassification,
+    FamilyCapability,
+    ProductSurfaceStatus,
+    classify_binding,
+    family_capability,
+    product_surface_excluded,
+    product_surface_status,
+    require_product_boundary_exclusion,
+    require_product_runtime_available,
+    runtime_interface_available,
+    validate_binding_legality,
+)
+from .compat import (
+    CompatibilityParityRow,
+    HTTPFeatureContractMap,
+    alt_svc_contract_map,
+    asgi3_compat_scope,
+    asgi_extension_bridge,
+    compatibility_feature_parity,
+    content_coding_contract_map,
+    early_hints_contract_map,
+    http_feature_contract_map,
+    observability_contract_metadata,
+    proxy_normalization_contract_map,
+    static_delivery_contract_map,
+    trailers_contract_map,
+)
+from .events import (
+    CompletionLevel,
+    CompletionStatus,
+    GenericDatagramRuntime,
+    GenericStreamRuntime,
+    datagram_receive,
+    datagram_send,
+    emit_complete,
+    http_disconnect,
+    http_request,
+    http_response_body,
+    http_response_pathsend,
+    http_response_start,
+    lifespan_shutdown,
+    lifespan_shutdown_complete,
+    lifespan_shutdown_failed,
+    lifespan_startup,
+    lifespan_startup_complete,
+    lifespan_startup_failed,
+    map_contract_event,
+    stream_receive,
+    stream_send,
+    validate_datagram_event,
+    validate_event_order,
+    validate_stream_event,
+    websocket_accept,
+    websocket_close,
+    websocket_connect,
+    websocket_disconnect,
+    websocket_receive,
+    websocket_send,
+    webtransport_accept,
+    webtransport_close,
+    webtransport_connect,
+    webtransport_datagram_receive,
+    webtransport_datagram_send,
+    webtransport_disconnect,
+    webtransport_stream_receive,
+    webtransport_stream_send,
+)
+from .metadata import (
+    ConnectionIdentity,
+    EndpointMetadata,
+    SecurityMetadata,
+    StreamIdentity,
+    UnitIdentity,
+    asgi3_extensions,
+    datagram_identity,
+    endpoint_metadata,
+    require_lossless_metadata,
+    security_metadata,
+    stream_identity,
+    transport_identity,
+    unit_identity,
+    validate_connection_identity,
+    validate_endpoint_metadata,
+    validate_security_metadata,
+    validate_stream_identity,
+)
+from .projection import (
+    EventProjection,
+    ScopeProjection,
+    project_event_classification,
+    project_receive_event,
+    project_scope_classification,
+    project_send_event,
+    validate_projected_event,
+)
+from .scopes import SUPPORTED_SCOPE_TYPES, contract_scope, validate_scope
+
+__all__ = [
+    "BindingClassification",
+    "CompletionLevel",
+    "CompletionStatus",
+    "ConnectionIdentity",
+    "EndpointMetadata",
+    "FamilyCapability",
+    "GenericDatagramRuntime",
+    "GenericStreamRuntime",
+    "ProductSurfaceStatus",
+    "CompatibilityParityRow",
+    "HTTPFeatureContractMap",
+    "SUPPORTED_SCOPE_TYPES",
+    "SecurityMetadata",
+    "EventProjection",
+    "ScopeProjection",
+    "StreamIdentity",
+    "UnitIdentity",
+    "alt_svc_contract_map",
+    "asgi3_extensions",
+    "asgi3_compat_scope",
+    "asgi_extension_bridge",
+    "classify_binding",
+    "compatibility_feature_parity",
+    "contract_scope",
+    "content_coding_contract_map",
+    "datagram_identity",
+    "datagram_receive",
+    "datagram_send",
+    "emit_complete",
+    "endpoint_metadata",
+    "early_hints_contract_map",
+    "family_capability",
+    "http_disconnect",
+    "http_feature_contract_map",
+    "http_request",
+    "http_response_body",
+    "http_response_pathsend",
+    "http_response_start",
+    "lifespan_shutdown",
+    "lifespan_shutdown_complete",
+    "lifespan_shutdown_failed",
+    "lifespan_startup",
+    "lifespan_startup_complete",
+    "lifespan_startup_failed",
+    "map_contract_event",
+    "observability_contract_metadata",
+    "proxy_normalization_contract_map",
+    "product_surface_status",
+    "product_surface_excluded",
+    "project_event_classification",
+    "project_receive_event",
+    "project_scope_classification",
+    "project_send_event",
+    "require_lossless_metadata",
+    "require_product_boundary_exclusion",
+    "require_product_runtime_available",
+    "runtime_interface_available",
+    "security_metadata",
+    "static_delivery_contract_map",
+    "stream_identity",
+    "stream_receive",
+    "stream_send",
+    "transport_identity",
+    "trailers_contract_map",
+    "unit_identity",
+    "validate_binding_legality",
+    "validate_connection_identity",
+    "validate_datagram_event",
+    "validate_endpoint_metadata",
+    "validate_event_order",
+    "validate_projected_event",
+    "validate_security_metadata",
+    "validate_scope",
+    "validate_stream_event",
+    "validate_stream_identity",
+    "websocket_accept",
+    "websocket_close",
+    "websocket_connect",
+    "websocket_disconnect",
+    "websocket_receive",
+    "websocket_send",
+    "webtransport_accept",
+    "webtransport_close",
+    "webtransport_connect",
+    "webtransport_datagram_receive",
+    "webtransport_datagram_send",
+    "webtransport_disconnect",
+    "webtransport_stream_receive",
+    "webtransport_stream_send",
+]

tigrcorn_contract/classification.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from tigrcorn_core.errors import ConfigError
+
+BindingKind = Literal["http", "http.stream", "websocket", "lifespan", "webtransport", "stream", "datagram", "rest", "jsonrpc", "sse"]
+ProductSurfaceKind = Literal[
+    "auto",
+    "tigr-asgi-contract",
+    "asgi3",
+    "asgi2",
+    "wsgi",
+    "rsgi",
+    "rest",
+    "jsonrpc",
+]
+
+_SERVER_OWNED_RUNTIMES = {"http", "http.stream", "websocket", "lifespan", "webtransport", "stream", "datagram"}
+_CLASSIFICATION_ONLY = {"rest", "jsonrpc", "sse"}
+_SUPPORTED_APP_INTERFACES = {"auto", "tigr-asgi-contract", "asgi3"}
+_UNSUPPORTED_COMPAT_INTERFACES = {"asgi2", "wsgi", "rsgi"}
+_RUNTIME_EXCLUDED_CLASSIFICATIONS = {"rest", "jsonrpc"}
+
+
+@dataclass(frozen=True, slots=True)
+class BindingClassification:
+    kind: BindingKind
+    runtime_owned: bool
+    classification_only: bool
+    dispatch_runtime: str
+    scope_type: str
+    family: str
+    exchange: str
+    framing: str | None = None
+    allowed_framings: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class FamilyCapability:
+    family: str
+    bindings: tuple[str, ...]
+    subevents: tuple[str, ...]
+    exchanges: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ProductSurfaceStatus:
+    kind: ProductSurfaceKind
+    runtime_available: bool
+    classification_only: bool
+    compatibility_exclusion: bool
+    reason: str
+
+
+_FAMILY_CAPABILITIES = {
+    "request": FamilyCapability(
+        family="request",
+        bindings=("http", "http.stream", "rest", "jsonrpc"),
+        subevents=("request.open", "request.body_in", "request.chunk_in", "request.close", "request.disconnect"),
+        exchanges=("unary", "server_stream"),
+    ),
+    "session": FamilyCapability(
+        family="session",
+        bindings=("websocket", "webtransport", "lifespan"),
+        subevents=("session.open", "session.accept", "session.ready", "session.heartbeat", "session.close", "session.disconnect"),
+        exchanges=("duplex",),
+    ),
+    "message": FamilyCapability(
+        family="message",
+        bindings=("websocket",),
+        subevents=("message.in", "message.decode", "message.handle", "message.out", "message.ack", "message.nack"),
+        exchanges=("duplex",),
+    ),
+    "stream": FamilyCapability(
+        family="stream",
+        bindings=("http.stream", "webtransport", "stream", "sse"),
+        subevents=("stream.open", "stream.chunk_in", "stream.chunk_out", "stream.flush", "stream.finalize", "stream.abort", "stream.close"),
+        exchanges=("server_stream", "duplex"),
+    ),
+    "datagram": FamilyCapability(
+        family="datagram",
+        bindings=("webtransport", "datagram"),
+        subevents=("datagram.in", "datagram.handle", "datagram.out", "datagram.ack", "datagram.close"),
+        exchanges=("duplex",),
+    ),
+}
+
+_BINDING_SHAPES: dict[str, tuple[str, str, str, str | None, tuple[str, ...]]] = {
+    "http": ("http", "request", "unary", None, ()),
+    "http.stream": ("http", "stream", "server_stream", None, ()),
+    "websocket": ("websocket", "message", "duplex", None, ()),
+    "lifespan": ("lifespan", "session", "duplex", None, ()),
+    "webtransport": ("webtransport", "session", "duplex", None, ()),
+    "stream": ("tigrcorn.stream", "stream", "duplex", None, ()),
+    "datagram": ("tigrcorn.datagram", "datagram", "duplex", None, ()),
+    "rest": ("http", "request", "unary", "json", ("json",)),
+    "jsonrpc": ("http", "request", "unary", "jsonrpc", ("jsonrpc",)),
+    "sse": ("http", "stream", "server_stream", "sse", ("sse",)),
+}
+
+
+def classify_binding(kind: str) -> BindingClassification:
+    normalized = kind.strip().lower().replace("_", "-")
+    if normalized == "json-rpc":
+        normalized = "jsonrpc"
+    if normalized not in _SERVER_OWNED_RUNTIMES | _CLASSIFICATION_ONLY:
+        raise ConfigError(f"unsupported binding classification: {kind!r}")
+    scope_type, family, exchange, framing, allowed_framings = _BINDING_SHAPES[normalized]
+    return BindingClassification(
+        kind=normalized,  # type: ignore[arg-type]
+        runtime_owned=normalized in _SERVER_OWNED_RUNTIMES,
+        classification_only=normalized in _CLASSIFICATION_ONLY,
+        dispatch_runtime="application" if normalized in _CLASSIFICATION_ONLY else "tigrcorn",
+        scope_type=scope_type,
+        family=family,
+        exchange=exchange,
+        framing=framing,
+        allowed_framings=allowed_framings,
+    )
+
+
+def runtime_interface_available(interface: str) -> bool:
+    return product_surface_status(interface).runtime_available
+
+
+def _normalize_product_surface(value: str) -> ProductSurfaceKind:
+    try:
+        normalized = value.strip().lower().replace("_", "-")
+    except AttributeError as exc:
+        raise ConfigError(f"unsupported product surface: {value!r}") from exc
+    if normalized == "json-rpc":
+        normalized = "jsonrpc"
+    if normalized not in _SUPPORTED_APP_INTERFACES | _UNSUPPORTED_COMPAT_INTERFACES | _RUNTIME_EXCLUDED_CLASSIFICATIONS:
+        raise ConfigError(f"unsupported product surface: {value!r}")
+    return normalized  # type: ignore[return-value]
+
+
+def product_surface_status(surface: str) -> ProductSurfaceStatus:
+    normalized = _normalize_product_surface(surface)
+    if normalized in _SUPPORTED_APP_INTERFACES:
+        return ProductSurfaceStatus(
+            kind=normalized,
+            runtime_available=True,
+            classification_only=False,
+            compatibility_exclusion=False,
+            reason="supported app interface",
+        )
+    if normalized in _RUNTIME_EXCLUDED_CLASSIFICATIONS:
+        return ProductSurfaceStatus(
+            kind=normalized,
+            runtime_available=False,
+            classification_only=True,
+            compatibility_exclusion=False,
+            reason="classification-only binding; runtime belongs to the application layer",
+        )
+    return ProductSurfaceStatus(
+        kind=normalized,
+        runtime_available=False,
+        classification_only=False,
+        compatibility_exclusion=True,
+        reason="unsupported compatibility interface",
+    )
+
+
+def require_product_runtime_available(surface: str) -> ProductSurfaceStatus:
+    status = product_surface_status(surface)
+    if not status.runtime_available:
+        raise ConfigError(f"unsupported runtime product surface: {surface!r} ({status.reason})")
+    return status
+
+
+def product_surface_excluded(surface: str) -> bool:
+    return not product_surface_status(surface).runtime_available
+
+
+def require_product_boundary_exclusion(surface: str) -> ProductSurfaceStatus:
+    status = product_surface_status(surface)
+    if status.runtime_available:
+        raise ConfigError(f"product surface is supported, not excluded: {surface!r}")
+    return status
+
+
+def family_capability(family: str) -> FamilyCapability:
+    normalized = family.strip().lower()
+    try:
+        return _FAMILY_CAPABILITIES[normalized]
+    except KeyError as exc:
+        raise ConfigError(f"unsupported contract family: {family!r}") from exc
+
+
+def validate_binding_legality(*, binding: str, family: str, subevent: str | None = None, exchange: str | None = None) -> None:
+    normalized_binding = binding.strip().lower().replace("_", "-")
+    if normalized_binding == "json-rpc":
+        normalized_binding = "jsonrpc"
+    classification = classify_binding(normalized_binding)
+    normalized_family = family.strip().lower()
+    if classification.classification_only and normalized_family != classification.family:
+        raise ConfigError(f"binding {binding!r} is illegal for family {family!r}")
+    capability = family_capability(family)
+    if normalized_binding not in capability.bindings:
+        raise ConfigError(f"binding {binding!r} is illegal for family {family!r}")
+    if subevent is not None and subevent not in capability.subevents and not subevent.endswith(".emit_complete"):
+        raise ConfigError(f"subevent {subevent!r} is illegal for family {family!r}")
+    if classification.classification_only and exchange is not None and exchange != classification.exchange:
+        raise ConfigError(f"exchange {exchange!r} is illegal for binding {binding!r}")
+    if exchange is not None and exchange not in capability.exchanges:
+        raise ConfigError(f"exchange {exchange!r} is illegal for family {family!r}")

tigrcorn_contract/compat.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from tigrcorn_core.errors import ProtocolError
+
+from .metadata import UnitIdentity, asgi3_extensions
+from .scopes import validate_scope
+
+HTTPFeatureKind = Literal[
+    "alt-svc",
+    "content-coding",
+    "early-hints",
+    "proxy-normalization",
+    "static-delivery",
+    "trailers",
+]
+
+_HTTP_FEATURE_EVENTS = {
+    "alt-svc": ("http.response.start",),
+    "content-coding": ("http.response.start", "http.response.body"),
+    "early-hints": ("http.response.start",),
+    "proxy-normalization": ("http.request",),
+    "static-delivery": ("http.response.pathsend", "http.response.body"),
+    "trailers": ("http.request.trailers", "http.response.trailers"),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class CompatibilityParityRow:
+    feature_id: str
+    native_contract: bool
+    asgi3_compat: bool
+    notes: str = ""
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "feature_id": self.feature_id,
+            "native_contract": self.native_contract,
+            "asgi3_compat": self.asgi3_compat,
+            "notes": self.notes,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class HTTPFeatureContractMap:
+    feature: HTTPFeatureKind
+    contract_events: tuple[str, ...]
+    asgi_extensions: tuple[str, ...] = ()
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "feature": self.feature,
+            "contract_events": list(self.contract_events),
+            "asgi_extensions": list(self.asgi_extensions),
+            "metadata": dict(self.metadata),
+        }
+
+
+def asgi3_compat_scope(scope: dict[str, Any], *, extensions: dict[str, Any] | None = None) -> dict[str, Any]:
+    validate_scope(scope)
+    compat_scope = dict(scope)
+    merged_extensions = dict(scope.get("extensions") or {})
+    merged_extensions.update(extensions or {})
+    merged_extensions.setdefault("tigrcorn.compat", {"interface": "asgi3", "native_contract": False})
+    compat_scope["extensions"] = merged_extensions
+    return compat_scope
+
+
+def asgi_extension_bridge(
+    *,
+    unit: UnitIdentity | None = None,
+    capabilities: dict[str, Any] | None = None,
+    feature_maps: list[HTTPFeatureContractMap] | None = None,
+    **extension_parts: Any,
+) -> dict[str, Any]:
+    bridge = asgi3_extensions(unit=unit, **extension_parts)
+    bridge["tigrcorn.capabilities"] = dict(capabilities or {})
+    bridge["tigrcorn.http_features"] = [item.as_dict() for item in feature_maps or []]
+    return bridge
+
+
+def compatibility_feature_parity(feature_id: str, *, native_contract: bool, asgi3_compat: bool, notes: str = "") -> CompatibilityParityRow:
+    if not feature_id.startswith("feat:"):
+        raise ProtocolError("compatibility parity rows require a feature id")
+    return CompatibilityParityRow(
+        feature_id=feature_id,
+        native_contract=native_contract,
+        asgi3_compat=asgi3_compat,
+        notes=notes,
+    )
+
+
+def http_feature_contract_map(
+    feature: str,
+    *,
+    asgi_extensions: tuple[str, ...] = (),
+    metadata: dict[str, Any] | None = None,
+) -> HTTPFeatureContractMap:
+    normalized = feature.strip().lower().replace("_", "-")
+    if normalized not in _HTTP_FEATURE_EVENTS:
+        raise ProtocolError(f"unsupported HTTP contract feature map: {feature!r}")
+    return HTTPFeatureContractMap(
+        feature=normalized,  # type: ignore[arg-type]
+        contract_events=_HTTP_FEATURE_EVENTS[normalized],
+        asgi_extensions=asgi_extensions,
+        metadata=dict(metadata or {}),
+    )
+
+
+def alt_svc_contract_map(value: str, *, max_age: int | None = None, persist: bool = False) -> HTTPFeatureContractMap:
+    if not value:
+        raise ProtocolError("Alt-Svc contract map requires a header value")
+    metadata: dict[str, Any] = {"header": value, "persist": persist}
+    if max_age is not None:
+        metadata["max_age"] = max_age
+    return http_feature_contract_map("alt-svc", metadata=metadata)
+
+
+def content_coding_contract_map(codings: tuple[str, ...]) -> HTTPFeatureContractMap:
+    if not codings:
+        raise ProtocolError("content-coding contract map requires at least one coding")
+    return http_feature_contract_map("content-coding", metadata={"codings": list(codings)})
+
+
+def early_hints_contract_map(headers: list[tuple[bytes, bytes]]) -> HTTPFeatureContractMap:
+    if not headers:
+        raise ProtocolError("early-hints contract map requires headers")
+    return http_feature_contract_map("early-hints", metadata={"status": 103, "headers": headers})
+
+
+def proxy_normalization_contract_map(*, trusted: bool, forwarded_for: str | None = None, scheme: str | None = None) -> HTTPFeatureContractMap:
+    metadata = {"trusted": trusted}
+    if forwarded_for is not None:
+        metadata["forwarded_for"] = forwarded_for
+    if scheme is not None:
+        metadata["scheme"] = scheme
+    return http_feature_contract_map("proxy-normalization", metadata=metadata)
+
+
+def static_delivery_contract_map(path: str, *, pathsend: bool = True, range_request: bool = False, etag: str | None = None) -> HTTPFeatureContractMap:
+    if not path.startswith("/"):
+        raise ProtocolError("static delivery contract path must be absolute")
+    metadata: dict[str, Any] = {"path": path, "pathsend": pathsend, "range_request": range_request}
+    if etag is not None:
+        metadata["etag"] = etag
+    return http_feature_contract_map(
+        "static-delivery",
+        asgi_extensions=("http.response.pathsend",) if pathsend else (),
+        metadata=metadata,
+    )
+
+
+def trailers_contract_map(*, request: bool = False, response: bool = False) -> HTTPFeatureContractMap:
+    if not request and not response:
+        raise ProtocolError("trailers contract map requires request or response trailers")
+    extensions = []
+    if request:
+        extensions.append("tigrcorn.http.request_trailers")
+    if response:
+        extensions.append("http.response.trailers")
+    return http_feature_contract_map("trailers", asgi_extensions=tuple(extensions), metadata={"request": request, "response": response})
+
+
+def observability_contract_metadata(
+    *,
+    unit_id: str,
+    feature_id: str,
+    boundary_id: str,
+    attributes: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    if not unit_id or not feature_id.startswith("feat:") or not boundary_id.startswith("bnd:"):
+        raise ProtocolError("observability contract metadata requires unit, feature, and boundary ids")
+    return {
+        "tigrcorn.observability": {
+            "unit_id": unit_id,
+            "feature_id": feature_id,
+            "boundary_id": boundary_id,
+            "attributes": dict(attributes or {}),
+        }
+    }