seampact-codegen 1.0.0__py3-none-any.whl

seampact/codegen/__init__.py

@@ -0,0 +1,2 @@
+"""The neutral code generation of the Python targets: the plan every target shares (names, layout, refusals by name,
+the route table and the route helpers), the line printer, and the Pydantic emitter FastAPI and Ninja share."""

seampact/codegen/boot_check_hooks.py

@@ -0,0 +1,38 @@
+"""The `artefacts.bootCheck.hooks` value, read the same on every Python target: `error` (default) or `off`; `warn`
+is refused by name until a consumer needs it, any other value as invalid."""
+
+from typing import Final
+
+from seampact.codegen.refusals import Delivery, IrPlace, Refusals
+from seampact.ir.config.json_value import JsonValue
+
+HOOKS_ERROR: Final = "error"
+HOOKS_OFF: Final = "off"
+_HOOKS_WARN: Final = "warn"
+_NAME: Final = "bootCheck.hooks"
+
+
+def read_boot_check_hooks(value: JsonValue, at: IrPlace, refusals: Refusals) -> bool:
+    """Whether a missing hook fails the boot; a refused value reads as the default, `error`."""
+    if value == HOOKS_OFF:
+        return False
+
+    if value == HOOKS_ERROR:
+        return True
+
+    if value == _HOOKS_WARN:
+        refusals.waiting(
+            f"artefacts.{_NAME}.{_HOOKS_WARN}",
+            "'bootCheck.hooks: warn' (start with hooks missing)",
+            at,
+            Delivery.CONSUMER,
+        )
+        return True
+
+    refusals.add(
+        f"artefacts.{_NAME}.invalid",
+        f"The artefact '{_NAME}' is {value!r}, not '{HOOKS_ERROR}', '{HOOKS_OFF}' or '{_HOOKS_WARN}'.",
+        f"Set '{_NAME}' to one of the listed values, or remove it for its default.",
+        at,
+    )
+    return True

seampact/codegen/contract_module.py

@@ -0,0 +1,146 @@
+"""The `contract` module of an api's package, the same on every Python target (ADR 0026 "Placement", ADR 0027): the
+`ApiContract` the runtime reads per operation. It holds the IR of the kept operations whole (security and access,
+idempotency, paging, relay, cache, the unknown-key and unknown-query policies, the body's rule proofs) and the
+declarations they read, then the Python attribute of each member's wire name: per object schema, and per operation for
+its path, query and header parameters and its body's rule proofs."""
+
+from collections.abc import Mapping, Sequence
+from typing import Final
+
+from seampact.codegen.kept_forms import handler_headers
+from seampact.codegen.names import ApiNames, member_identifier, part_attributes
+from seampact.codegen.printer import INDENT, PythonModule, literal_lines, string_literal
+from seampact.codegen.refusals import IrPlace, Refusals
+from seampact.codegen.runtime.contract import HEADER_PART, PATH_PART, PROOFS_PART, QUERY_PART
+from seampact.codegen.runtime.version import RUNTIME_VERSION
+from seampact.ir.model import ContractIR, Operation, Param
+
+# The IR members the runtime reads beside the operations; the others stay out of the module.
+IR_VIEW_MEMBERS: Final = (
+    "api",
+    "errors",
+    "formats",
+    "identities",
+    "schemes",
+    "scopes",
+    "rights",
+    "rules",
+    "buckets",
+    "pagings",
+    "schemas",
+    "enums",
+)
+CONTRACT_NAME: Final = "CONTRACT"
+_SCHEMAS_MODULE: Final = ".schemas"
+_SCHEMAS_ALIAS: Final = "_schemas"
+
+
+def contract_module(ir: ContractIR, names: ApiNames, mount: str, refusals: Refusals) -> str:
+    """`names` may hold more schemas than `ir` (a target's own input models): only the IR's schemas are written."""
+    module = PythonModule(f"The contract of api '{ir.api.id}' as its boundary reads it.")
+    typing = module.imported("typing", "_typing")
+    runtime = module.imported("seampact.codegen.runtime.contract", "_contract")
+    arguments: list[tuple[str, object]] = [
+        ("api", ir.api.id),
+        ("generated_by", RUNTIME_VERSION),
+        ("mount", mount),
+        ("ir_view", ir_view(ir)),
+        ("members", {schema_id: names.members[schema_id] for schema_id in ir.schemas if schema_id in names.members}),
+        ("operation_members", _operation_members(ir, refusals)),
+    ]
+    lines = [f"{CONTRACT_NAME}: {typing}.Final = {runtime}.ApiContract("]
+
+    for name, value in arguments:
+        lines += literal_lines(INDENT, f"{name}=", value, ",")
+
+    lines += _params_models(module, _params_classes(ir, names, refusals))
+    module.add_block([*lines, ")"])
+
+    return module.text()
+
+
+def ir_view(ir: ContractIR) -> dict[str, object]:
+    """The IR members the runtime reads, as the IR's JSON writes them."""
+    document = ir.to_json()
+    view: dict[str, object] = {member: document.get(member, {}) for member in IR_VIEW_MEMBERS}
+    view["operations"] = document["operations"]
+
+    return view
+
+
+def _params_classes(ir: ContractIR, names: ApiNames, refusals: Refusals) -> dict[str, str]:
+    """The generated class of each params schema a right or rule declares, by schema id."""
+    declared = [(f"/rights/{name}/params", right.params) for name, right in sorted(ir.rights.items())]
+    declared += [(f"/rules/{name}/params", rule.params) for name, rule in sorted(ir.rules.items())]
+    classes: dict[str, str] = {}
+
+    for pointer, schema_id in declared:
+        if schema_id is None:
+            continue
+
+        class_name = names.schema_classes.get(schema_id)
+
+        if class_name is None:
+            refusals.inconsistent(
+                "params.class.missing", f"The params '{schema_id}' have no generated class", IrPlace(pointer)
+            )
+            continue
+
+        classes[schema_id] = class_name
+
+    return dict(sorted(classes.items()))
+
+
+def _params_models(module: PythonModule, classes: Mapping[str, str]) -> list[str]:
+    """The `params_models=` argument; none when no right or rule declares params."""
+    if not classes:
+        return []
+
+    schemas = module.imported(_SCHEMAS_MODULE, _SCHEMAS_ALIAS)
+    entries = [f"{INDENT * 2}{string_literal(schema_id)}: {schemas}.{name}," for schema_id, name in classes.items()]
+
+    return [f"{INDENT}params_models={{", *entries, f"{INDENT}}},"]
+
+
+def _operation_members(ir: ContractIR, refusals: Refusals) -> dict[str, dict[str, Mapping[str, str]]]:
+    members: dict[str, dict[str, Mapping[str, str]]] = {}
+
+    for index, operation in enumerate(ir.operations):
+        at = IrPlace(f"/operations/{index}", operation.id)
+        parts = {
+            PATH_PART: _part(operation.params.path, at.below("params", "path"), refusals),
+            QUERY_PART: _part(operation.params.query, at.below("params", "query"), refusals),
+            HEADER_PART: _part(handler_headers(operation), at.below("params", "header"), refusals),
+            PROOFS_PART: _proofs(operation, at.below("input", "proofs"), refusals),
+        }
+        members[operation.id] = {part: attributes for part, attributes in parts.items() if attributes}
+
+    return members
+
+
+def _part(params: Sequence[Param], at: IrPlace, refusals: Refusals) -> dict[str, str]:
+    return {param.name: attribute for _, param, attribute in part_attributes(params, at, refusals)}
+
+
+def _proofs(operation: Operation, at: IrPlace, refusals: Refusals) -> dict[str, str]:
+    proofs = operation.input.proofs if operation.input is not None else None
+    attributes: dict[str, str] = {}
+
+    for index, proof in enumerate(proofs or ()):
+        attribute = member_identifier(proof.name)
+
+        if attribute is None:
+            refusals.inconsistent("name.segment.missing", f"The body proof '{proof.name}' has no name segment", at)
+            continue
+
+        if attribute in attributes.values():
+            refusals.add(
+                "name.collision",
+                f"Two body proofs of operation '{operation.id}' give the Python name '{attribute}'.",
+                "Rename one of the proofs in the contract.",
+                at.below(index),
+            )
+
+        attributes[proof.name] = attribute
+
+    return attributes

seampact/codegen/credentials_classes.py

@@ -0,0 +1,99 @@
+"""The credentials class of each security identity, shared by the Python targets: its name, its attribute per scheme
+the kept operations read, and the frozen class itself, one `str | None` per scheme, hidden from `repr`. The authenticate
+hook receives an instance; the runtime builds it through `CredentialsType`."""
+
+from collections.abc import Callable, Collection, Mapping
+from dataclasses import dataclass
+from typing import Final
+
+from seampact.codegen.names import member_identifier
+from seampact.codegen.printer import INDENT, string_literal
+from seampact.codegen.refusals import IrPlace, Refusals
+from seampact.ir.model import ContractIR, IdentityAccess, OptionalAccess
+from seampact.ir.naming import IrName, NameSource, NamingRole, python_identifier, segments_of
+
+_REDACTED: Final = "[redacted]"
+_CREDENTIALS_DOC: Final = (
+    "The credentials a request presents for identity '{identity}', one per scheme, None when absent."
+)
+
+# How a generator claims a class name of its module: the name, what takes it, and where; it answers the name.
+type ClaimName = Callable[[str, str, IrPlace], str]
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialsNames:
+    """The credentials class of one identity and its attribute per scheme, in scheme order."""
+
+    class_name: str
+    attributes: Mapping[str, str]
+
+
+def identity_credentials(
+    ir: ContractIR, kept_operations: Collection[str], claim: ClaimName, refusals: Refusals
+) -> dict[str, CredentialsNames]:
+    """Per identity the kept operations read, its credentials class and the schemes those operations read it through."""
+    schemes_by_identity: dict[str, dict[str, IrPlace]] = {}
+
+    for index, operation in enumerate(ir.operations):
+        access = operation.access
+
+        if operation.id in kept_operations and isinstance(access, IdentityAccess | OptionalAccess):
+            at = IrPlace(f"/operations/{index}", operation.id).below("access")
+            schemes = schemes_by_identity.setdefault(access.identity, {})
+            schemes.update({scheme: at.below("schemes") for scheme in access.schemes if scheme not in schemes})
+
+    credentials: dict[str, CredentialsNames] = {}
+
+    for identity, schemes in sorted(schemes_by_identity.items()):
+        segments = segments_of(identity, NameSource.NAME) or [identity]
+        class_name = claim(
+            python_identifier(IrName((*segments, "credentials"), NamingRole.SCHEMA)),
+            f"the credentials of identity '{identity}'",
+            IrPlace(f"/identities/{identity}"),
+        )
+        credentials[identity] = CredentialsNames(class_name, _scheme_attributes(identity, schemes, refusals))
+
+    return credentials
+
+
+def credentials_class(decorator: str, identity: str, names: CredentialsNames) -> list[str]:
+    """The class block, under the generator's frozen dataclass `decorator` line."""
+    lines = [decorator, f"class {names.class_name}:", f'{INDENT}"""{_CREDENTIALS_DOC.format(identity=identity)}"""']
+    attributes = list(names.attributes.values())
+
+    if not attributes:
+        return lines
+
+    members = [f"{INDENT}{attribute}: str | None = None" for attribute in attributes]
+    rendered = ", ".join(f"{attribute}={_REDACTED}" for attribute in attributes)
+    redacted_repr = [
+        f"{INDENT}def __repr__(self) -> str:",
+        f"{INDENT * 2}return {string_literal(f'{names.class_name}({rendered})')}",
+    ]
+
+    return [*lines, "", *members, "", *redacted_repr]
+
+
+def _scheme_attributes(identity: str, schemes: Mapping[str, IrPlace], refusals: Refusals) -> dict[str, str]:
+    attributes: dict[str, str] = {}
+
+    for scheme, at in sorted(schemes.items()):
+        attribute = member_identifier(scheme)
+
+        if attribute is None:
+            refusals.inconsistent("scheme.no-segment", f"The scheme '{scheme}' yields no name segment", at)
+            continue
+
+        if attribute in attributes.values():
+            refusals.add(
+                "name.collision",
+                f"The credentials of identity '{identity}' would hold two schemes as '{attribute}'.",
+                "Rename one of the schemes in the contract.",
+                at,
+            )
+            continue
+
+        attributes[scheme] = attribute
+
+    return attributes

seampact/codegen/handler_forms.py

@@ -0,0 +1,132 @@
+"""The forms the generated boundary validates but does not enforce, which the handler owes: each is named with a
+warning at generation, as on the Node servers (ADR 0016 "Left to the handler"), never dropped silently. An identity's
+request `headers` are validated as declared headers only, so the handler reads them. An identity header the server
+would write on a response (a versionToken, or a header declared `in: response`) has no value a handler can write, a
+reply carrying only a body, so it is refused by name at its declaration rather than dropped."""
+
+from dataclasses import dataclass
+from typing import Final
+
+from seampact.codegen.refusals import Delivery, IrPlace, Refusals, place_in_entry
+from seampact.ir.config.problem import ConfigProblem
+from seampact.ir.model import (
+    ContractIR,
+    CredentialIdentity,
+    HeaderDecl,
+    HeaderSemantic,
+    HeaderSide,
+    HeaderUseFor,
+    IdentityAccess,
+    IdentityHeaderUse,
+    Operation,
+    OptionalAccess,
+    SignedIdentity,
+)
+
+IDENTITY_HEADERS_HANDLER: Final = "identity.headers.handler"
+IDENTITY_RESPONSE_HEADER: Final = "identity.response.header"
+_IDENTITY_HEADERS_FIX: Final = "Read the identity headers the boundary validated in the handler."
+
+
+@dataclass(frozen=True, slots=True)
+class _ResponseHeader:
+    header_id: str
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class _IdentityHeaders:
+    identity_id: str
+    request_side_uses: int
+    response_side: tuple[_ResponseHeader, ...]
+
+
+def handler_warnings(ir: ContractIR, entry_id: str, api: str) -> list[ConfigProblem]:
+    """One warning per operation whose identity declares request headers."""
+    warnings: list[ConfigProblem] = []
+
+    for index, operation in enumerate(ir.operations):
+        headers = _identity_headers(ir, operation)
+
+        if headers is None or headers.request_side_uses == 0:
+            continue
+
+        identity_id = headers.identity_id
+
+        place = IrPlace(f"/operations/{index}", operation.id).below("access")
+        warnings.append(
+            ConfigProblem(
+                IDENTITY_HEADERS_HANDLER,
+                f"The headers of the identity '{identity_id}' in operation '{operation.id}' at {place.pointer} is not "
+                "enforced by the generated boundary.",
+                _IDENTITY_HEADERS_FIX,
+                place_in_entry(entry_id, place, api),
+            )
+        )
+
+    return warnings
+
+
+def refuse_identity_response_headers(ir: ContractIR, refusals: Refusals) -> None:
+    """Refuses by name each identity header an operation would write on its responses, at the header's declaration."""
+    for operation in ir.operations:
+        headers = _identity_headers(ir, operation)
+
+        if headers is None:
+            continue
+
+        for header in headers.response_side:
+            refusals.waiting(
+                IDENTITY_RESPONSE_HEADER,
+                f"The response header '{header.name}' of the identity '{headers.identity_id}'",
+                IrPlace(f"/headers/{header.header_id}", operation.id),
+                Delivery.AFTER_V1,
+            )
+
+
+def _identity_headers(ir: ContractIR, operation: Operation) -> _IdentityHeaders | None:
+    access = operation.access
+
+    if not isinstance(access, IdentityAccess | OptionalAccess):
+        return None
+
+    identity = ir.identities.get(access.identity)
+
+    if not isinstance(identity, CredentialIdentity | SignedIdentity) or not identity.headers:
+        return None
+
+    request_side_uses = 0
+    response_side: list[_ResponseHeader] = []
+
+    for use in identity.headers:
+        declaration = ir.headers.get(use.header)
+
+        if declaration is None or not _is_response_side(declaration):
+            request_side_uses += 1
+            continue
+
+        name = _response_header_name(declaration, use, operation)
+
+        if name is not None:
+            response_side.append(_ResponseHeader(use.header, name))
+
+    return _IdentityHeaders(access.identity, request_side_uses, tuple(response_side))
+
+
+def _is_response_side(declaration: HeaderDecl) -> bool:
+    return declaration.semantic == HeaderSemantic.VERSION_TOKEN or declaration.in_ == HeaderSide.RESPONSE
+
+
+def _response_header_name(declaration: HeaderDecl, use: IdentityHeaderUse, operation: Operation) -> str | None:
+    """A versionToken answers on every success of the identity; another semantic only where its `for` applies. An
+    unknown `for` is taken to apply, so nothing is dropped unnamed."""
+    if declaration.semantic == HeaderSemantic.VERSION_TOKEN:
+        return declaration.response
+
+    if use.for_ == HeaderUseFor.READS and not operation.safe:
+        return None
+
+    if use.for_ == HeaderUseFor.WRITES and operation.safe:
+        return None
+
+    return declaration.name

seampact/codegen/input_schemas.py

@@ -0,0 +1,130 @@
+"""The parameter parts of each operation's input (ADR 0026 "Types and validation"), as object schemas the shared
+Pydantic emitter writes beside the api's own: `<Op>Path`, `<Op>Query` and `<Op>Headers` hold the parameters the
+handler reads, and `<Op>Proofs` the body's rule proofs, which the handler never reads. The placement runtime validates
+each part of the boundary's decoded tree with its model in strict mode, and the runtime renames members through the
+contract module's per-operation tables. Their ids (`<operationId>.path`) cannot be the id of a declared schema; a
+class name taken twice is refused as `name.collision`."""
+
+import dataclasses
+from collections.abc import Sequence
+
+from seampact.codegen.kept_forms import handler_headers
+from seampact.codegen.names import ApiNames
+from seampact.codegen.pydantic_layout import ApiLayout
+from seampact.ir.model import (
+    ContractIR,
+    Direction,
+    Docs,
+    Name,
+    NameRole,
+    ObjectSchema,
+    Operation,
+    Origin,
+    Param,
+    Property,
+    Schema,
+    TypeUse,
+)
+
+INPUT_PARTS = (("path", NameRole.PATH), ("query", NameRole.QUERY), ("headers", NameRole.HEADERS))
+PROOFS_PART = "proofs"
+
+
+def input_schema_id(operation_id: str, part: str) -> str:
+    return f"{operation_id}.{part}"
+
+
+def with_input_schemas(ir: ContractIR, layout: ApiLayout) -> ContractIR:
+    """A copy of `ir` whose schemas also hold each operation's parameter parts."""
+    schemas: dict[str, Schema] = dict(ir.schemas)
+
+    for index, operation in enumerate(ir.operations):
+        if operation.id not in layout.operations:
+            continue
+
+        origin = Origin(layer="api", pointer=f"/operations/{index}")
+
+        for part, role in INPUT_PARTS:
+            params = _part_params(operation, part)
+
+            if params:
+                part_id = input_schema_id(operation.id, part)
+                members = [_param_member(param, origin) for param in params]
+                schemas[part_id] = _object(part_id, operation, role, members, origin)
+
+        proofs = _proofs_object(operation, origin)
+
+        if proofs is not None:
+            schemas[proofs.id] = proofs
+
+    return dataclasses.replace(ir, schemas=schemas)
+
+
+def _proofs_object(operation: Operation, origin: Origin) -> ObjectSchema | None:
+    """`<Op>Proofs`: the body's rule proofs, which step 6 validates beside the typed body and the handler never reads.
+    Every proof is required and sensitive (docs/ir section 13)."""
+    proofs = operation.input.proofs if operation.input is not None else None
+
+    if not proofs:
+        return None
+
+    members = [
+        dataclasses.replace(_member(proof.name, proof.schema, origin, optional=False), sensitive=True)
+        for proof in proofs
+    ]
+    proofs_id = input_schema_id(operation.id, PROOFS_PART)
+    name = Name(segments=(*operation.name.segments, PROOFS_PART), role=NameRole.SCHEMA)
+
+    return dataclasses.replace(_object(proofs_id, operation, NameRole.SCHEMA, members, origin), name=name)
+
+
+def _part_params(operation: Operation, part: str) -> Sequence[Param]:
+    if part == "path":
+        return operation.params.path
+
+    return operation.params.query if part == "query" else handler_headers(operation)
+
+
+def _object(
+    schema_id: str, operation: Operation, role: NameRole, members: list[Property], origin: Origin
+) -> ObjectSchema:
+    return ObjectSchema(
+        properties=tuple(members),
+        id=schema_id,
+        name=Name(segments=tuple(operation.name.segments), role=role),
+        directions=(Direction.INPUT,),
+        examples=(),
+        docs=Docs(),
+        extensions={},
+        origin=origin,
+    )
+
+
+def _param_member(param: Param, origin: Origin) -> Property:
+    # A parameter's default goes to the emitter, which refuses a member default by name.
+    return dataclasses.replace(
+        _member(param.name, param.type, origin, optional=not param.required), default=param.default
+    )
+
+
+def _member(name: str, type_use: TypeUse, origin: Origin, *, optional: bool) -> Property:
+    return Property(
+        name=name,
+        type=type_use,
+        optional=optional,
+        nullable=False,
+        sensitive=False,
+        deprecated=False,
+        docs=Docs(),
+        extensions={},
+        origin=origin,
+    )
+
+
+def proof_models(layout: ApiLayout, names: ApiNames) -> dict[str, str]:
+    """The `<Op>Proofs` class of each kept operation whose body carries rule proofs."""
+    return {
+        operation_id: names.schema_classes[input_schema_id(operation_id, PROOFS_PART)]
+        for operation_id in layout.operations
+        if input_schema_id(operation_id, PROOFS_PART) in names.schema_classes
+    }