tigrcorn-contract 0.3.16.dev5__py3-none-any.whl

tigrcorn_contract/events.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+from tigrcorn_core.errors import ProtocolError
+
+HTTP_EVENT_MAP = {
+    "request.open": "http.request",
+    "request.body_in": "http.request",
+    "request.disconnect": "http.disconnect",
+    "response.open": "http.response.start",
+    "response.body_out": "http.response.body",
+    "response.close": "http.response.body",
+    "response.emit_complete": "transport.emit.complete",
+}
+WEBSOCKET_EVENT_MAP = {
+    "session.open": "websocket.connect",
+    "message.in": "websocket.receive",
+    "message.out": "websocket.send",
+    "session.accept": "websocket.accept",
+    "session.close": "websocket.close",
+    "session.disconnect": "websocket.disconnect",
+    "session.emit_complete": "transport.emit.complete",
+}
+LIFESPAN_EVENT_MAP = {
+    "session.open": "lifespan.startup",
+    "session.ready": "lifespan.startup.complete",
+    "session.close": "lifespan.shutdown",
+    "session.disconnect": "lifespan.shutdown.complete",
+}
+WEBTRANSPORT_EVENT_MAP = {
+    "session.open": "webtransport.connect",
+    "session.accept": "webtransport.accept",
+    "session.close": "webtransport.close",
+    "session.disconnect": "webtransport.disconnect",
+    "stream.chunk_in": "webtransport.stream.receive",
+    "stream.chunk_out": "webtransport.stream.send",
+    "datagram.in": "webtransport.datagram.receive",
+    "datagram.out": "webtransport.datagram.send",
+    "stream.emit_complete": "transport.emit.complete",
+    "datagram.emit_complete": "transport.emit.complete",
+    "session.emit_complete": "transport.emit.complete",
+}
+
+
+class CompletionLevel(StrEnum):
+    ACCEPTED_BY_RUNTIME = "accepted_by_runtime"
+    FLUSHED_TO_TRANSPORT = "flushed_to_transport"
+
+
+class CompletionStatus(StrEnum):
+    OK = "ok"
+    REJECTED = "rejected"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True, slots=True)
+class EventOrderRule:
+    required_first: str
+    allowed_after_close: tuple[str, ...] = ()
+
+
+def _event(event_type: str, **payload: Any) -> dict[str, Any]:
+    return {"type": event_type, **payload}
+
+
+def _require_unit_id(unit_id: str) -> str:
+    if not unit_id:
+        raise ProtocolError("contract event requires unit_id")
+    return unit_id
+
+
+def http_request(unit_id: str, *, body: bytes = b"", more_body: bool = False) -> dict[str, Any]:
+    return _event("http.request", unit_id=_require_unit_id(unit_id), body=body, more_body=more_body)
+
+
+def http_disconnect(unit_id: str) -> dict[str, Any]:
+    return _event("http.disconnect", unit_id=_require_unit_id(unit_id))
+
+
+def http_response_start(unit_id: str, *, status: int, headers: list[tuple[bytes, bytes]] | None = None) -> dict[str, Any]:
+    if not 100 <= status <= 599:
+        raise ProtocolError(f"invalid HTTP response status: {status!r}")
+    return _event("http.response.start", unit_id=_require_unit_id(unit_id), status=status, headers=headers or [])
+
+
+def http_response_body(unit_id: str, *, body: bytes = b"", more_body: bool = False) -> dict[str, Any]:
+    return _event("http.response.body", unit_id=_require_unit_id(unit_id), body=body, more_body=more_body)
+
+
+def http_response_pathsend(
+    unit_id: str,
+    *,
+    path: str,
+    headers: list[tuple[bytes, bytes]] | None = None,
+    stat_result: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    if not path:
+        raise ProtocolError("pathsend event requires path")
+    event = _event("http.response.pathsend", unit_id=_require_unit_id(unit_id), path=path)
+    if headers is not None:
+        event["headers"] = headers
+    if stat_result is not None:
+        event["stat_result"] = stat_result
+    return event
+
+
+def websocket_connect(unit_id: str) -> dict[str, Any]:
+    return _event("websocket.connect", unit_id=_require_unit_id(unit_id))
+
+
+def websocket_receive(unit_id: str, *, text: str | None = None, bytes_: bytes | None = None) -> dict[str, Any]:
+    if text is None and bytes_ is None:
+        raise ProtocolError("websocket receive requires text or bytes")
+    return _event("websocket.receive", unit_id=_require_unit_id(unit_id), text=text, bytes=bytes_)
+
+
+def websocket_send(unit_id: str, *, text: str | None = None, bytes_: bytes | None = None) -> dict[str, Any]:
+    if text is None and bytes_ is None:
+        raise ProtocolError("websocket send requires text or bytes")
+    return _event("websocket.send", unit_id=_require_unit_id(unit_id), text=text, bytes=bytes_)
+
+
+def websocket_accept(unit_id: str, *, subprotocol: str | None = None) -> dict[str, Any]:
+    event = _event("websocket.accept", unit_id=_require_unit_id(unit_id))
+    if subprotocol is not None:
+        event["subprotocol"] = subprotocol
+    return event
+
+
+def websocket_disconnect(unit_id: str, *, code: int = 1005, reason: str = "") -> dict[str, Any]:
+    return _event("websocket.disconnect", unit_id=_require_unit_id(unit_id), code=code, reason=reason)
+
+
+def websocket_close(unit_id: str, *, code: int = 1000, reason: str = "") -> dict[str, Any]:
+    return _event("websocket.close", unit_id=_require_unit_id(unit_id), code=code, reason=reason)
+
+
+def lifespan_startup(unit_id: str) -> dict[str, Any]:
+    return _event("lifespan.startup", unit_id=_require_unit_id(unit_id))
+
+
+def lifespan_startup_complete(unit_id: str) -> dict[str, Any]:
+    return _event("lifespan.startup.complete", unit_id=_require_unit_id(unit_id))
+
+
+def lifespan_startup_failed(unit_id: str, *, message: str) -> dict[str, Any]:
+    return _event("lifespan.startup.failed", unit_id=_require_unit_id(unit_id), message=message)
+
+
+def lifespan_shutdown(unit_id: str) -> dict[str, Any]:
+    return _event("lifespan.shutdown", unit_id=_require_unit_id(unit_id))
+
+
+def lifespan_shutdown_complete(unit_id: str) -> dict[str, Any]:
+    return _event("lifespan.shutdown.complete", unit_id=_require_unit_id(unit_id))
+
+
+def lifespan_shutdown_failed(unit_id: str, *, message: str) -> dict[str, Any]:
+    return _event("lifespan.shutdown.failed", unit_id=_require_unit_id(unit_id), message=message)
+
+
+def map_contract_event(binding: str, subevent: str) -> str:
+    maps = {
+        "http": HTTP_EVENT_MAP,
+        "http.stream": HTTP_EVENT_MAP,
+        "websocket": WEBSOCKET_EVENT_MAP,
+        "lifespan": LIFESPAN_EVENT_MAP,
+        "webtransport": WEBTRANSPORT_EVENT_MAP,
+    }
+    event_map = maps.get(binding)
+    if event_map is None:
+        raise ProtocolError(f"unsupported contract event binding: {binding!r}")
+    try:
+        return event_map[subevent]
+    except KeyError as exc:
+        raise ProtocolError(f"illegal subevent {subevent!r} for binding {binding!r}") from exc
+
+
+def stream_receive(stream_id: str, data: bytes, *, more: bool = False) -> dict[str, Any]:
+    return _event("transport.stream.receive", stream_id=stream_id, data=data, more=more)
+
+
+def stream_send(stream_id: str, data: bytes, *, more: bool = False) -> dict[str, Any]:
+    return _event("transport.stream.send", stream_id=stream_id, data=data, more=more)
+
+
+def datagram_receive(datagram_id: str, data: bytes, *, flow_controlled: bool = False) -> dict[str, Any]:
+    return _event("transport.datagram.receive", datagram_id=datagram_id, data=data, flow_controlled=flow_controlled)
+
+
+def datagram_send(datagram_id: str, data: bytes, *, flow_controlled: bool = False) -> dict[str, Any]:
+    return _event("transport.datagram.send", datagram_id=datagram_id, data=data, flow_controlled=flow_controlled)
+
+
+def webtransport_connect(session_id: str) -> dict[str, Any]:
+    return _event("webtransport.connect", session_id=session_id)
+
+
+def webtransport_accept(session_id: str) -> dict[str, Any]:
+    return _event("webtransport.accept", session_id=session_id)
+
+
+def webtransport_disconnect(session_id: str, *, code: int = 0, reason: str = "") -> dict[str, Any]:
+    return _event("webtransport.disconnect", session_id=session_id, code=code, reason=reason)
+
+
+def webtransport_close(session_id: str, *, code: int = 0, reason: str = "") -> dict[str, Any]:
+    return _event("webtransport.close", session_id=session_id, code=code, reason=reason)
+
+
+def webtransport_stream_receive(session_id: str, stream_id: str, data: bytes, *, more: bool = False) -> dict[str, Any]:
+    return _event("webtransport.stream.receive", session_id=session_id, stream_id=stream_id, data=data, more=more)
+
+
+def webtransport_stream_send(session_id: str, stream_id: str, data: bytes, *, more: bool = False) -> dict[str, Any]:
+    return _event("webtransport.stream.send", session_id=session_id, stream_id=stream_id, data=data, more=more)
+
+
+def webtransport_datagram_receive(session_id: str, datagram_id: str, data: bytes) -> dict[str, Any]:
+    return _event("webtransport.datagram.receive", session_id=session_id, datagram_id=datagram_id, data=data)
+
+
+def webtransport_datagram_send(session_id: str, datagram_id: str, data: bytes) -> dict[str, Any]:
+    return _event("webtransport.datagram.send", session_id=session_id, datagram_id=datagram_id, data=data)
+
+
+def emit_complete(
+    unit_id: str,
+    *,
+    level: str | CompletionLevel = CompletionLevel.FLUSHED_TO_TRANSPORT,
+    status: str | CompletionStatus = CompletionStatus.OK,
+    detail: str | None = None,
+) -> dict[str, Any]:
+    try:
+        completion_level = CompletionLevel(_normalize_completion_level(str(level)))
+    except ValueError as exc:
+        raise ProtocolError(f"unsupported completion level: {level!r}") from exc
+    try:
+        completion_status = CompletionStatus(str(status))
+    except ValueError as exc:
+        raise ProtocolError(f"unsupported completion status: {status!r}") from exc
+    event = _event("transport.emit.complete", unit_id=unit_id, level=completion_level.value, status=completion_status.value)
+    if detail:
+        event["detail"] = detail
+    return event
+
+
+def _normalize_completion_level(level: str) -> str:
+    aliases = {
+        "buffered": CompletionLevel.ACCEPTED_BY_RUNTIME.value,
+        "accepted": CompletionLevel.ACCEPTED_BY_RUNTIME.value,
+        "flushed": CompletionLevel.FLUSHED_TO_TRANSPORT.value,
+        "transport": CompletionLevel.FLUSHED_TO_TRANSPORT.value,
+        "acknowledged": CompletionLevel.FLUSHED_TO_TRANSPORT.value,
+    }
+    return aliases.get(level, level)
+
+
+def validate_event_order(events: list[dict[str, Any]], *, required_first: str, terminal_prefixes: tuple[str, ...]) -> None:
+    if not events:
+        raise ProtocolError("contract event sequence is empty")
+    if events[0].get("type") != required_first:
+        raise ProtocolError(f"first contract event must be {required_first}")
+    closed = False
+    for event in events:
+        event_type = str(event.get("type", ""))
+        if closed:
+            raise ProtocolError("contract event emitted after terminal event")
+        if event_type.startswith(terminal_prefixes):
+            closed = True

tigrcorn_contract/metadata.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from tigrcorn_core.errors import ProtocolError
+
+EndpointKind = Literal["tcp", "uds", "fd", "pipe", "inproc"]
+IdentityKind = Literal["tcp", "unix", "quic", "http2", "http3", "webtransport-session", "webtransport-stream", "datagram"]
+
+
+@dataclass(frozen=True, slots=True)
+class EndpointMetadata:
+    kind: EndpointKind
+    address: str | None = None
+    port: int | None = None
+    fd: int | None = None
+    pipe_name: str | None = None
+    inproc_name: str | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        return {key: value for key, value in {
+            "kind": self.kind,
+            "address": self.address,
+            "port": self.port,
+            "fd": self.fd,
+            "pipe_name": self.pipe_name,
+            "inproc_name": self.inproc_name,
+        }.items() if value is not None}
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionIdentity:
+    kind: IdentityKind
+    connection_id: str
+    peer: str | None = None
+    local: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, Any]:
+        payload = {"kind": self.kind, "connection_id": self.connection_id, **self.metadata}
+        if self.peer is not None:
+            payload["peer"] = self.peer
+        if self.local is not None:
+            payload["local"] = self.local
+        return payload
+
+
+@dataclass(frozen=True, slots=True)
+class StreamIdentity:
+    kind: IdentityKind
+    connection_id: str
+    stream_id: str
+    session_id: str | None = None
+    datagram_id: str | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        payload = {"kind": self.kind, "connection_id": self.connection_id, "stream_id": self.stream_id}
+        if self.session_id is not None:
+            payload["session_id"] = self.session_id
+        if self.datagram_id is not None:
+            payload["datagram_id"] = self.datagram_id
+        return payload
+
+
+@dataclass(frozen=True, slots=True)
+class UnitIdentity:
+    unit_id: str
+    family: str
+    binding: str
+    connection_id: str | None = None
+    stream_id: str | None = None
+    session_id: str | None = None
+    datagram_id: str | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        payload = {"unit_id": self.unit_id, "family": self.family, "binding": self.binding}
+        for key in ("connection_id", "stream_id", "session_id", "datagram_id"):
+            value = getattr(self, key)
+            if value is not None:
+                payload[key] = value
+        return payload
+
+
+@dataclass(frozen=True, slots=True)
+class SecurityMetadata:
+    tls: bool = False
+    mtls: bool = False
+    alpn: str | None = None
+    sni: str | None = None
+    peer_certificate: str | None = None
+    ocsp_status: str | None = None
+    crl_status: str | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        return {key: value for key, value in {
+            "tls": self.tls,
+            "mtls": self.mtls,
+            "alpn": self.alpn,
+            "sni": self.sni,
+            "peer_certificate": self.peer_certificate,
+            "ocsp_status": self.ocsp_status,
+            "crl_status": self.crl_status,
+        }.items() if value not in (None, False)}
+
+
+def endpoint_metadata(kind: str, **fields: Any) -> EndpointMetadata:
+    try:
+        endpoint_kind = kind.strip().lower()  # type: ignore[assignment]
+    except AttributeError as exc:
+        raise ProtocolError("endpoint kind must be a string") from exc
+    if endpoint_kind not in {"tcp", "uds", "fd", "pipe", "inproc"}:
+        raise ProtocolError(f"unsupported endpoint kind: {kind!r}")
+    metadata = EndpointMetadata(kind=endpoint_kind, **fields)  # type: ignore[arg-type]
+    validate_endpoint_metadata(metadata)
+    return metadata
+
+
+def validate_endpoint_metadata(metadata: EndpointMetadata) -> None:
+    if metadata.kind == "tcp" and (not metadata.address or metadata.port is None):
+        raise ProtocolError("tcp endpoint metadata requires address and port")
+    if metadata.kind == "uds" and not metadata.address:
+        raise ProtocolError("uds endpoint metadata requires socket path")
+    if metadata.kind == "fd" and metadata.fd is None:
+        raise ProtocolError("fd endpoint metadata requires fd")
+    if metadata.kind == "pipe" and not metadata.pipe_name:
+        raise ProtocolError("pipe endpoint metadata requires pipe_name")
+    if metadata.kind == "inproc" and not metadata.inproc_name:
+        raise ProtocolError("inproc endpoint metadata requires inproc_name")
+
+
+def transport_identity(kind: str, connection_id: str, **fields: Any) -> ConnectionIdentity:
+    normalized = kind.strip().lower()
+    if normalized not in {"tcp", "unix", "quic"}:
+        raise ProtocolError(f"unsupported connection identity kind: {kind!r}")
+    if not connection_id:
+        raise ProtocolError("connection identity requires connection_id")
+    return ConnectionIdentity(kind=normalized, connection_id=connection_id, **fields)  # type: ignore[arg-type]
+
+
+def stream_identity(kind: str, connection_id: str, stream_id: str, **fields: Any) -> StreamIdentity:
+    normalized = kind.strip().lower()
+    if normalized not in {"http2", "http3", "webtransport-session", "webtransport-stream"}:
+        raise ProtocolError(f"unsupported stream identity kind: {kind!r}")
+    if not connection_id or not stream_id:
+        raise ProtocolError("stream identity requires connection_id and stream_id")
+    return StreamIdentity(kind=normalized, connection_id=connection_id, stream_id=stream_id, **fields)  # type: ignore[arg-type]
+
+
+def datagram_identity(connection_id: str, datagram_id: str, *, session_id: str | None = None) -> StreamIdentity:
+    if not connection_id or not datagram_id:
+        raise ProtocolError("datagram identity requires connection_id and datagram_id")
+    return StreamIdentity(kind="datagram", connection_id=connection_id, stream_id=datagram_id, datagram_id=datagram_id, session_id=session_id)
+
+
+def unit_identity(unit_id: str, *, family: str, binding: str, **fields: Any) -> UnitIdentity:
+    if not unit_id:
+        raise ProtocolError("unit identity requires unit_id")
+    normalized_family = family.strip().lower()
+    if normalized_family not in {"request", "session", "message", "stream", "datagram"}:
+        raise ProtocolError(f"unsupported unit family: {family!r}")
+    normalized_binding = binding.strip().lower()
+    if normalized_binding not in {"http", "http.stream", "websocket", "lifespan", "webtransport", "stream", "datagram"}:
+        raise ProtocolError(f"unsupported unit binding: {binding!r}")
+    return UnitIdentity(unit_id=unit_id, family=normalized_family, binding=normalized_binding, **fields)
+
+
+def security_metadata(**fields: Any) -> SecurityMetadata:
+    metadata = SecurityMetadata(**fields)
+    if metadata.mtls and not metadata.tls:
+        raise ProtocolError("mTLS metadata requires TLS metadata")
+    return metadata
+
+
+def require_lossless_metadata(name: str, value: Any) -> Any:
+    if value in (None, "", (), [], {}):
+        raise ProtocolError(f"required metadata would be lossy: {name}")
+    return value
+
+
+def asgi3_extensions(
+    *,
+    endpoint: EndpointMetadata | None = None,
+    transport: ConnectionIdentity | StreamIdentity | None = None,
+    security: SecurityMetadata | None = None,
+    stream: StreamIdentity | None = None,
+    datagram: StreamIdentity | None = None,
+    completion: dict[str, Any] | None = None,
+    unit: UnitIdentity | None = None,
+) -> dict[str, Any]:
+    extensions: dict[str, Any] = {}
+    if endpoint is not None:
+        extensions["tigrcorn.endpoint"] = endpoint.as_dict()
+    if transport is not None:
+        extensions["tigrcorn.transport"] = transport.as_dict()
+    if security is not None:
+        extensions["tigrcorn.security"] = security.as_dict()
+    if stream is not None:
+        extensions["tigrcorn.stream"] = stream.as_dict()
+    if datagram is not None:
+        extensions["tigrcorn.datagram"] = datagram.as_dict()
+    if completion is not None:
+        extensions["tigrcorn.emit_completion"] = completion
+    if unit is not None:
+        extensions["tigrcorn.unit"] = unit.as_dict()
+    return extensions

tigrcorn_contract/py.typed

@@ -0,0 +1 @@
+

tigrcorn_contract/scopes.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+
+from tigrcorn_asgi.scopes.custom import build_custom_scope
+from tigrcorn_core.errors import ProtocolError
+
+SUPPORTED_SCOPE_TYPES = ("http", "websocket", "lifespan", "webtransport", "tigrcorn.stream", "tigrcorn.datagram")
+_PATH_SCOPE_TYPES = {"http", "websocket", "webtransport", "tigrcorn.stream"}
+
+
+def validate_scope(scope: dict[str, Any]) -> None:
+    scope_type = scope.get("type")
+    if scope_type not in SUPPORTED_SCOPE_TYPES:
+        raise ProtocolError(f"unsupported contract scope type: {scope_type!r}")
+    if scope_type in _PATH_SCOPE_TYPES and not isinstance(scope.get("path", "/"), str):
+        raise ProtocolError(f"{scope_type} scope path must be a string")
+    if scope_type == "http" and scope.get("method") is not None and not isinstance(scope["method"], str):
+        raise ProtocolError("http scope method must be a string")
+    if scope_type == "websocket" and scope.get("subprotocols") is not None and not isinstance(scope["subprotocols"], list):
+        raise ProtocolError("websocket scope subprotocols must be a list")
+    if scope_type == "lifespan" and scope.get("state") is not None and not isinstance(scope["state"], dict):
+        raise ProtocolError("lifespan scope state must be a mapping")
+    if scope_type == "webtransport":
+        extensions = scope.get("extensions", {})
+        if "h3" not in extensions or "quic" not in extensions:
+            raise ProtocolError("webtransport scope requires h3 and quic extension metadata")
+    if scope_type == "tigrcorn.datagram" and "datagram_id" in scope and not scope["datagram_id"]:
+        raise ProtocolError("datagram scope datagram_id must not be empty")
+
+
+def contract_scope(scope_type: str, **fields: Any) -> dict[str, Any]:
+    scope = build_custom_scope(scope_type, **fields)
+    validate_scope(scope)
+    return scope