seampact-codegen 1.0.0__py3-none-any.whl

seampact/codegen/runtime/replies.py

@@ -0,0 +1,144 @@
+"""Writes every contract reply as status, headers and bytes: a contract error in the api's format, a role's code, the
+api's 500, and a declared success body in its format's envelope, serialized by the boundary's own JSON encoding,
+never a framework's renderer."""
+
+import json
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Final
+
+from seampact.codegen.runtime.contract import INTERNAL_STATUS, UNDECLARED_STATUS_ROLE, ApiContract
+from seampact.codegen.runtime.ir_view import IrMap, ir_list, ir_map, ir_string
+from seampact.codegen.runtime.templates import render
+
+JSON_MEDIA: Final = "application/json"
+CONTENT_TYPE: Final = "content-type"
+CACHE_CONTROL: Final = "cache-control"
+NO_STORE: Final = "no-store"
+
+_NULL_ABSENT: Final = "null"
+_PAYLOAD_SLOT: Final = "payload"
+_SECONDS_UNIT: Final = "s"
+_MILLISECONDS_PER_SECOND: Final = 1000
+
+
+@dataclass(frozen=True, slots=True)
+class Reply:
+    """A reply the boundary writes; header names are lower case."""
+
+    status: int
+    headers: tuple[tuple[str, str], ...]
+    body: bytes
+
+    def header(self, name: str) -> str | None:
+        lowered = name.lower()
+
+        return next((value for key, value in self.headers if key == lowered), None)
+
+
+def json_bytes(value: object) -> bytes:
+    """The boundary's JSON: UTF-8, no escaped slashes or non-ASCII, `1.0` kept; NaN and infinities refused. A lone
+    surrogate echoed from a request can only sit in a JSON string, so it is written as its `\\uXXXX` escape."""
+    text = json.dumps(value, ensure_ascii=False, separators=(",", ":"), allow_nan=False)
+
+    return text.encode("utf-8", errors="backslashreplace")
+
+
+def error_reply(
+    contract: ApiContract, operation_id: str | None, code: str, params: Mapping[str, object] | None = None
+) -> Reply:
+    """The reply of `code` in the operation's format, or the api's format when no operation matched."""
+    format_ = contract.format(operation_id)
+    catalogued = contract.catalog_entry(code)
+    status = contract.status_of(code)
+    slots: dict[str, object] = {"code": code, "status": status, "nature": ir_string(catalogued, "nature")}
+    title = ir_string(catalogued, "title")
+
+    if title is not None:
+        slots["title"] = title
+
+    if params is not None:
+        slots["params"] = params
+
+    error = ir_map(format_, "error")
+    body = render(error.get("body"), slots, ir_string(format_, "absent") == _NULL_ABSENT)
+    headers = [(CONTENT_TYPE, ir_string(error, "media") or JSON_MEDIA)]
+
+    if catalogued.get("noStore") is True:
+        headers.append((CACHE_CONTROL, NO_STORE))
+
+    if operation_id is not None:
+        headers.extend(_retry_header(contract.error_declaration(operation_id, code), params))
+
+    return Reply(status, tuple(headers), json_bytes(body.value if body.present else {}))
+
+
+def role_params(
+    contract: ApiContract, operation_id: str, code: str, role: str, slots: Mapping[str, object]
+) -> Mapping[str, object] | None:
+    """The params a role's template renders from `slots` (`issues`, `limitBytes`), None when the code binds none."""
+    template = contract.role_params(operation_id, code, role)
+
+    if template is None:
+        return None
+
+    rendered = render(template, slots, write_nulls=False)
+
+    return rendered.value if isinstance(rendered.value, Mapping) else None
+
+
+def role_reply(contract: ApiContract, operation_id: str | None, role: str, bare_status: int) -> Reply:
+    """The role's code in the api's format, or a bare status when the api declares no code for the role."""
+    code = contract.role_code(operation_id, role)
+
+    return Reply(bare_status, (), b"") if code is None else error_reply(contract, operation_id, code)
+
+
+def internal_error_reply(contract: ApiContract, operation_id: str | None) -> Reply:
+    """The api's 500; the placement logs the cause and tells the unexpected-error listener."""
+    return role_reply(contract, operation_id, UNDECLARED_STATUS_ROLE, INTERNAL_STATUS)
+
+
+def success_body(format_: IrMap, shape: str, payload: object, status: int, path: str) -> object:
+    """The success body in its format's envelope (ADR 0002 section 13): the payload itself under a bare format.
+
+    Raises `LookupError` when the envelope renders nothing, which generation refuses."""
+    template = ir_map(ir_map(format_, "success"), shape).get("body")
+
+    if template is None or _is_bare_payload(template):
+        return payload
+
+    slots = {_PAYLOAD_SLOT: payload, "status": status, "path": path}
+    rendered = render(template, slots, ir_string(format_, "absent") == _NULL_ABSENT)
+
+    if not rendered.present:
+        raise LookupError(
+            f"seampact: the format's '{shape}' success envelope rendered nothing; regenerate the api, whose "
+            "generation refuses an envelope that does not write the payload under named members."
+        )
+
+    return rendered.value
+
+
+def _is_bare_payload(template: object) -> bool:
+    return (
+        ir_string(template, "kind") == "slot"
+        and ir_string(template, "slot") == _PAYLOAD_SLOT
+        and not ir_list(template, "path")
+    )
+
+
+def _retry_header(declared: IrMap, params: Mapping[str, object] | None) -> list[tuple[str, str]]:
+    """The delay param of a refusal, in integer milliseconds, written in its retry header's unit."""
+    retry = ir_map(declared, "retryHeader")
+    name = ir_string(retry, "name")
+    delay_ms = None if params is None else params.get(ir_string(retry, "param") or "")
+
+    if name is None or isinstance(delay_ms, bool) or not isinstance(delay_ms, int | float):
+        return []
+
+    if ir_string(retry, "unit") == _SECONDS_UNIT:
+        return [(name.lower(), str(math.ceil(delay_ms / _MILLISECONDS_PER_SECOND)))]
+
+    return [(name.lower(), str(int(delay_ms)))]

seampact/codegen/runtime/reply_verdict.py

@@ -0,0 +1,215 @@
+"""Step 10, the outgoing response check (ADR 0016), on a reply the placement has in hand: a reply the boundary wrote
+passes; a success it did not write is a violation; a declared error status from another writer is held up to
+`MAX_CHECKED_ERROR_BODY_BYTES` and must carry one of the operation's codes for that status in the api's format; any
+other status is a violation. The verdict strips an ETag the boundary did not set and applies the `responses` mode."""
+
+import hashlib
+import json
+import zlib
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Final
+
+from seampact.codegen.runtime.contract import ApiContract
+from seampact.codegen.runtime.ir_view import ir_list, ir_map, ir_maps, ir_string
+from seampact.codegen.runtime.replies import CONTENT_TYPE, JSON_MEDIA, Reply, internal_error_reply
+
+MAX_CHECKED_ERROR_BODY_BYTES: Final = 65536
+
+_ERROR_FLOOR: Final = 400
+_ETAG: Final = "etag"
+_CONTENT_ENCODING: Final = "content-encoding"
+_HEAD: Final = "HEAD"
+# `wbits` of zlib: a gzip header, and a zlib header for HTTP's `deflate`.
+_GZIP_WINDOW: Final = 16 + zlib.MAX_WBITS
+_DEFLATE_WINDOW: Final = zlib.MAX_WBITS
+
+
+class ResponsesMode(StrEnum):
+    STRICT = "strict"
+    WARN = "warn"
+
+
+class FrameworkEtagMode(StrEnum):
+    STRIP = "strip"
+    KEEP = "keep"
+
+
+@dataclass(frozen=True, slots=True)
+class OutgoingReply:
+    """A reply as it leaves the app: lower-case header names; `body` None when it was not held (a stream, or past
+    `MAX_CHECKED_ERROR_BODY_BYTES`)."""
+
+    status: int
+    headers: tuple[tuple[str, str], ...]
+    body: bytes | None
+
+    def header(self, name: str) -> str | None:
+        return next((value for key, value in self.headers if key == name), None)
+
+
+@dataclass(frozen=True, slots=True)
+class AuthoredReply:
+    status: int
+    body_digest: bytes
+    etag: str | None
+
+
+@dataclass(slots=True)
+class AuthoredReplies:
+    """The replies the boundary wrote for one request, kept in the request's state."""
+
+    replies: list[AuthoredReply] = field(default_factory=list)
+
+    def author(self, reply: Reply) -> Reply:
+        self.replies.append(AuthoredReply(reply.status, _digest(reply.body), reply.header(_ETAG)))
+
+        return reply
+
+    def find(self, reply: OutgoingReply, method: str) -> AuthoredReply | None:
+        """The written reply with this status and body; a HEAD reply whose body the server emptied matches too."""
+        if reply.body is None:
+            return None
+
+        digest = _digest(reply.body)
+
+        for written in self.replies:
+            body_kept = written.body_digest == digest or (reply.body == b"" and method.upper() == _HEAD)
+
+            if written.status == reply.status and body_kept:
+                return written
+
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class Verdict:
+    """The reply to send; `violation` names what the check found, `replaced` tells the api's 500 took its place."""
+
+    reply: OutgoingReply
+    violation: str | None
+    replaced: bool
+
+
+def verdict(
+    contract: ApiContract,
+    operation_id: str,
+    reply: OutgoingReply,
+    *,
+    authored: AuthoredReplies,
+    method: str,
+    admitted: bool,
+    responses: ResponsesMode,
+    framework_etag: FrameworkEtagMode,
+) -> Verdict:
+    """Strips a foreign ETag, then judges the reply: under `strict` a violation is replaced by the api's 500, under
+    `warn` it goes out as written. The placement logs a violation and tells the unexpected-error listener."""
+    written = authored.find(reply, method)
+    checked = _without_foreign_etag(reply, written, framework_etag)
+    violation = None if written is not None else foreign_reply_violation(contract, operation_id, checked, admitted)
+
+    if violation is None or responses is ResponsesMode.WARN:
+        return Verdict(checked, violation, replaced=False)
+
+    internal = internal_error_reply(contract, operation_id)
+
+    return Verdict(OutgoingReply(internal.status, internal.headers, internal.body), violation, replaced=True)
+
+
+def foreign_reply_violation(
+    contract: ApiContract, operation_id: str, reply: OutgoingReply, admitted: bool
+) -> str | None:
+    """The violation of a reply the boundary did not write, None when it passes."""
+    status = reply.status
+
+    if status < _ERROR_FLOOR:
+        return f"a {status} reply the boundary did not write"
+
+    codes = contract.declared_codes(operation_id, status)
+
+    if not codes:
+        return f"the undeclared status {status}"
+
+    # Once admitted, only the boundary or a contract exception's rendering writes the reply.
+    if admitted:
+        return f"a {status} reply written after the boundary's access step admitted the request"
+
+    return _error_body_violation(contract, operation_id, reply, codes)
+
+
+def _error_body_violation(
+    contract: ApiContract, operation_id: str, reply: OutgoingReply, codes: Sequence[str]
+) -> str | None:
+    status = reply.status
+    error_format = ir_map(contract.format(operation_id), "error")
+    error_media = (ir_string(error_format, "media") or JSON_MEDIA).lower()
+    media = (reply.header(CONTENT_TYPE) or "").split(";", 1)[0].strip().lower()
+
+    if reply.body is None:
+        return f"a {status} error body that cannot be checked"
+
+    if media != error_media:
+        return f"a {status} error body that is not {error_media}"
+
+    coding = (reply.header(_CONTENT_ENCODING) or "").strip().lower()
+    content = _decoded(reply.body, coding)
+
+    if content is None:
+        return f"a {status} error body in the content coding '{coding}', which the boundary cannot decode"
+
+    try:
+        body = json.loads(content)
+    except ValueError:
+        return f"a {status} error body that is not JSON"
+
+    code_member = _code_member(error_format)
+    code = body.get(code_member) if isinstance(body, dict) and code_member is not None else None
+
+    return None if isinstance(code, str) and code in codes else f"a {status} error body without a declared code"
+
+
+def _code_member(error_format: object) -> str | None:
+    """The top-level member of the format's error body that the `code` slot fills."""
+    for member in ir_maps(ir_map(error_format, "body"), "members"):
+        value = ir_map(member, "value")
+
+        if ir_string(value, "kind") == "slot" and ir_string(value, "slot") == "code" and not ir_list(value, "path"):
+            return ir_string(ir_map(member, "name"), "text")
+
+    return None
+
+
+def _decoded(body: bytes, coding: str) -> bytes | None:
+    """The body without its content coding; None for a coding the standard library cannot decode (`br`) or a
+    corrupt body."""
+    if coding in ("", "identity"):
+        return body
+
+    window = {"gzip": _GZIP_WINDOW, "x-gzip": _GZIP_WINDOW, "deflate": _DEFLATE_WINDOW}.get(coding)
+
+    if window is None:
+        return None
+
+    try:
+        return zlib.decompress(body, window)
+    except zlib.error:
+        return None
+
+
+def _without_foreign_etag(
+    reply: OutgoingReply, written: AuthoredReply | None, mode: FrameworkEtagMode
+) -> OutgoingReply:
+    etag = reply.header(_ETAG)
+    own_etag = None if written is None else written.etag
+
+    if etag is None or etag == own_etag or mode is FrameworkEtagMode.KEEP:
+        return reply
+
+    headers = tuple((name, value) for name, value in reply.headers if name != _ETAG)
+
+    return OutgoingReply(reply.status, headers, reply.body)
+
+
+def _digest(body: bytes) -> bytes:
+    return hashlib.sha256(body).digest()

seampact/codegen/runtime/requirement_params.py

@@ -0,0 +1,170 @@
+"""The params a decide request carries: the use site's values as the right's or rule's generated params class, a
+Pydantic model validated in strict mode, or a frozen dataclass built from the values checked against the params schema
+(types, enum values, refinements, item counts, required and unknown members); None for a right or rule that declares
+no params. Values the class does not hold fail the boundary before the decider runs."""
+
+import copy
+import dataclasses
+from typing import Final, Protocol, runtime_checkable
+
+from seampact.codegen.runtime.contract import ApiContract
+from seampact.codegen.runtime.failures import BoundaryFailureError
+from seampact.codegen.runtime.hinted_values import built_dataclass
+from seampact.codegen.runtime.ir_view import IrMap, ir_int, ir_map, ir_maps, ir_string, ir_strings, ir_true
+from seampact.codegen.runtime.value_rules import TYPE_RULE, ValueRuleError, check_length, checked_scalar
+from seampact.codegen.runtime.wire_codec import WireCodec
+from seampact.hooks import RequirementKind
+
+_DECLARATIONS: Final = {RequirementKind.RIGHT: "rights", RequirementKind.RULE: "rules"}
+_OBJECT_SCHEMA: Final = "object"
+_UNKNOWN_KEYS_RULE: Final = "unknownKeys"
+_REGENERATE: Final = "regenerate the api."
+# An array's item counts, checked as lengths: each length rule names its item rule.
+_ITEM_RULES: Final = {"minLength": "minItems", "maxLength": "maxItems"}
+
+
+@runtime_checkable
+class _ValidatingModel(Protocol):
+    """A generated Pydantic model, read without importing Pydantic, which the DRF target does not install."""
+
+    @classmethod
+    def model_validate(cls, obj: object, /, *, strict: bool | None = None) -> object: ...
+
+
+def requirement_params(contract: ApiContract, kind: RequirementKind, name: str, use_site: IrMap) -> object | None:
+    """`use_site` is the requirement or the field right of the IR. Raises `BoundaryFailureError` for params the right or
+    rule does not declare, a params schema the contract has no generated class for, or values its class refuses."""
+    schema_id = ir_string(contract.declaration(_DECLARATIONS[kind], name), "params")
+    values = copy.deepcopy(dict(ir_map(use_site, "params")))
+
+    if schema_id is None and values:
+        raise BoundaryFailureError(
+            f"seampact: a use of '{name}' in the api '{contract.api}' gives params '{name}' does not declare; "
+            f"{_REGENERATE}"
+        )
+
+    if schema_id is None:
+        return None
+
+    model = contract.params_models.get(schema_id)
+
+    if model is None:
+        raise BoundaryFailureError(
+            f"seampact: the api '{contract.api}' has no generated class for the params '{schema_id}' of '{name}'; "
+            f"{_REGENERATE}"
+        )
+
+    try:
+        return _params_instance(contract, name, schema_id, model, values)
+    except (ValueError, TypeError) as refused:
+        raise BoundaryFailureError(
+            f"seampact: the params of '{name}' in the api '{contract.api}' do not match '{schema_id}' ({refused}); "
+            f"{_REGENERATE}"
+        ) from refused
+
+
+def _params_instance(
+    contract: ApiContract, name: str, schema_id: str, model: type, values: dict[str, object]
+) -> object:
+    if dataclasses.is_dataclass(model):
+        return built_dataclass(model, _ParamsCheck(contract).object_tree(schema_id, values, ""))
+
+    if not isinstance(model, _ValidatingModel):
+        raise BoundaryFailureError(
+            f"seampact: the params class '{model.__qualname__}' of '{name}' is neither a Pydantic model nor a "
+            f"dataclass; {_REGENERATE}"
+        )
+
+    tree = WireCodec(contract).to_python({"kind": "ref", "schema": schema_id}, values)
+
+    if tree.unknown_keys:
+        raise ValueRuleError(_UNKNOWN_KEYS_RULE, f"the members {', '.join(tree.unknown_keys)} are not declared")
+
+    return model.model_validate(tree.value, strict=True)
+
+
+class _ParamsCheck:
+    """The params values checked against their schema and renamed to Python attributes, scalars converted; each
+    refusal raises `ValueRuleError` naming its pointer."""
+
+    def __init__(self, contract: ApiContract) -> None:
+        self._contract = contract
+
+    def object_tree(self, schema_id: str, value: object, pointer: str) -> dict[str, object]:
+        schema = self._contract.declaration("schemas", schema_id)
+
+        if ir_string(schema, "kind") != _OBJECT_SCHEMA:
+            raise ValueRuleError("kind", f"'{schema_id}' at '{pointer}' is not an object schema, which params hold")
+
+        if not isinstance(value, dict):
+            raise ValueRuleError(TYPE_RULE, f"'{pointer}' is not an object")
+
+        attributes = self._contract.members.get(schema_id, {})
+        properties = {ir_string(member, "name") or "": member for member in ir_maps(schema, "properties")}
+        unknown = [f"{pointer}/{key}" for key in value if key not in properties or key not in attributes]
+
+        if unknown:
+            raise ValueRuleError(_UNKNOWN_KEYS_RULE, f"the members {', '.join(unknown)} are not declared")
+
+        renamed: dict[str, object] = {}
+
+        for member_name, member in properties.items():
+            member_pointer = f"{pointer}/{member_name}"
+
+            if member_name not in value:
+                if not ir_true(member, "optional"):
+                    raise ValueRuleError("required", f"'{member_pointer}' is missing")
+                continue
+
+            renamed[attributes[member_name]] = self._member(member, value[member_name], member_pointer)
+
+        return renamed
+
+    def _member(self, member: IrMap, value: object, pointer: str) -> object:
+        if value is None and not ir_true(member, "nullable"):
+            raise ValueRuleError(TYPE_RULE, f"'{pointer}' is null")
+
+        return None if value is None else self._typed(ir_map(member, "type"), value, pointer)
+
+    def _typed(self, type_use: IrMap, value: object, pointer: str) -> object:
+        kind = ir_string(type_use, "kind")
+
+        if kind == "ref":
+            return self.object_tree(ir_string(type_use, "schema") or "", value, pointer)
+
+        if kind == "array":
+            return self._array(type_use, value, pointer)
+
+        if kind == "enum":
+            return self._enum_value(type_use, value, pointer)
+
+        if kind == "opaque":
+            return value
+
+        try:
+            return checked_scalar(type_use, value)
+        except ValueRuleError as refused:
+            raise ValueRuleError(refused.rule, f"'{pointer}' breaks '{refused.rule}'") from refused
+
+    def _array(self, type_use: IrMap, value: object, pointer: str) -> list[object]:
+        if not isinstance(value, list):
+            raise ValueRuleError(TYPE_RULE, f"'{pointer}' is not an array")
+
+        try:
+            check_length(value, ir_int(type_use, "minItems"), ir_int(type_use, "maxItems"))
+        except ValueRuleError as refused:
+            rule = _ITEM_RULES[refused.rule]
+            raise ValueRuleError(rule, f"'{pointer}' breaks '{rule}'") from refused
+
+        items = ir_map(type_use, "items")
+
+        return [self._typed(items, item, f"{pointer}/{index}") for index, item in enumerate(value)]
+
+    def _enum_value(self, type_use: IrMap, value: object, pointer: str) -> str:
+        enum = self._contract.declaration("enums", ir_string(type_use, "enum") or "")
+        allowed = ir_strings(ir_map(type_use, "narrowedTo"), "values") or ir_strings(enum, "values")
+
+        if not isinstance(value, str) or value not in allowed:
+            raise ValueRuleError("enum", f"'{pointer}' is not one of {', '.join(allowed)}")
+
+        return value