seampact-codegen 1.0.0__py3-none-any.whl

seampact/codegen/runtime/templates.py

@@ -0,0 +1,132 @@
+"""Renders an IR template (ADR 0004 section 8) over its slots: the format's error body, a role's params and a
+success envelope. A slot with no value renders as missing; an object member that renders as missing is left out, or
+written as null when the format says `absent: null`."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Final
+
+from seampact.codegen.runtime.ir_view import IrMap, ir_list, ir_map, ir_maps, ir_string, ir_strings
+
+_ITEM_SLOT: Final = "item"
+
+
+@dataclass(frozen=True, slots=True)
+class Rendered:
+    present: bool
+    value: object = None
+
+
+_MISSING: Final = Rendered(False)
+
+
+def render(template: object, slots: Mapping[str, object], write_nulls: bool) -> Rendered:
+    """Raises `LookupError` for a template kind the boundary does not render."""
+    kind = ir_string(template, "kind")
+
+    if kind == "object":
+        return _object(template if isinstance(template, Mapping) else {}, slots, write_nulls)
+
+    if kind == "array":
+        items = [render(item, slots, write_nulls) for item in ir_list(template, "items")]
+        return Rendered(True, [item.value for item in items if item.present])
+
+    if kind == "each":
+        return _each(template, slots, write_nulls)
+
+    if kind == "slot":
+        return _slot(template, slots)
+
+    if kind == "text":
+        return _text(template, slots)
+
+    if kind == "literal":
+        return Rendered(True, template.get("value") if isinstance(template, Mapping) else None)
+
+    raise LookupError(f"seampact: the template kind {kind!r} is not one the boundary renders.")
+
+
+def _object(template: IrMap, slots: Mapping[str, object], write_nulls: bool) -> Rendered:
+    rendered: dict[str, object] = {}
+
+    for member in ir_maps(template, "members"):
+        name = _member_name(ir_map(member, "name"), slots)
+
+        if name is None:
+            continue
+
+        value = render(member.get("value"), slots, write_nulls)
+
+        if value.present:
+            rendered[name] = value.value
+        elif write_nulls:
+            rendered[name] = None
+
+    merged = slots.get(ir_string(template, "merge") or "")
+
+    if isinstance(merged, Mapping):
+        rendered.update({str(key): value for key, value in merged.items()})
+
+    return Rendered(True, rendered) if rendered else _MISSING
+
+
+def _member_name(name: IrMap, slots: Mapping[str, object]) -> str | None:
+    if ir_string(name, "kind") == "text":
+        return ir_string(name, "text")
+
+    value = slots.get(ir_string(name, "slot") or "")
+
+    return str(value) if isinstance(value, str | int) and not isinstance(value, bool) else None
+
+
+def _each(template: object, slots: Mapping[str, object], write_nulls: bool) -> Rendered:
+    source = slots.get(ir_string(template, "of") or "")
+
+    if not isinstance(source, list | tuple):
+        return _MISSING
+
+    items = [render(ir_map(template, "as"), {**slots, _ITEM_SLOT: item}, write_nulls) for item in source]
+
+    return Rendered(True, [item.value for item in items if item.present])
+
+
+def _text(template: object, slots: Mapping[str, object]) -> Rendered:
+    text = ""
+
+    for part in ir_maps(template, "parts"):
+        if ir_string(part, "kind") == "text":
+            text += ir_string(part, "text") or ""
+            continue
+
+        value = _slot(part, slots)
+
+        if not value.present or not isinstance(value.value, str | int | float | bool):
+            return _MISSING
+
+        text += _scalar_text(value.value)
+
+    return Rendered(True, text)
+
+
+def _scalar_text(value: str | int | float | bool) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+
+    return str(value)
+
+
+def _slot(template: object, slots: Mapping[str, object]) -> Rendered:
+    name = ir_string(template, "slot") or ""
+
+    if name not in slots:
+        return _MISSING
+
+    value = slots[name]
+
+    for key in ir_strings(template, "path"):
+        if not isinstance(value, Mapping) or key not in value:
+            return _MISSING
+
+        value = value[key]
+
+    return _MISSING if value is None else Rendered(True, value)

seampact/codegen/runtime/uuid_text.py

@@ -0,0 +1,7 @@
+"""The text of a UUID as the contract's `uuid` format takes it: 8-4-4-4-12 hexadecimal digits in either case, shared
+by the access steps' type gate and the Pydantic type layer."""
+
+import re
+from typing import Final
+
+UUID_TEXT: Final = re.compile(r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}")

seampact/codegen/runtime/value_rules.py

@@ -0,0 +1,218 @@
+"""The framework-free type layer and value rules of ADR 0003: a decoded wire value checked against its scalar type and
+turned into the Python object the handler reads (a whole-number float into an `int`; `date-time`, `date`, `uuid`
+and decimal strings into their objects), and the length, bound and `multipleOf` rules of `rules:
+seampact-consistent`. Each refusal raises `ValueRuleError` with the contract rule's name; a placement turns it into
+its framework's error (Pydantic's, DRF's) or an issue of the boundary's `schemaInvalid`."""
+
+import math
+import re
+from collections.abc import Callable
+from datetime import date, datetime
+from decimal import Decimal, InvalidOperation
+from fractions import Fraction
+from typing import Final
+from uuid import UUID
+
+from seampact.codegen.runtime.ir_view import ir_int, ir_map, ir_string
+from seampact.codegen.runtime.pattern import contract_pattern
+from seampact.codegen.runtime.uuid_text import UUID_TEXT
+
+MAX_SAFE_INTEGER: Final = 2**53 - 1
+TYPE_RULE: Final = "type"
+FORMAT_RULE: Final = "format"
+
+_DATE_TIME: Final = re.compile(
+    r"(\d{4}-\d{2}-\d{2})[Tt]((?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d)"
+    r"(?:\.(\d{1,9}))?([Zz]|[+-](?:[01]\d|2[0-3]):[0-5]\d)",
+    re.ASCII,
+)
+_DATE: Final = re.compile(r"\d{4}-\d{2}-\d{2}", re.ASCII)
+_DECIMAL: Final = re.compile(r"-?(0|[1-9][0-9]*)(\.[0-9]+)?", re.ASCII)
+_MICROSECOND_DIGITS: Final = 6
+
+
+class ValueRuleError(ValueError):
+    """A value the contract refuses; `rule` is the contract rule's name (`type`, `format`, `minLength`, ...)."""
+
+    def __init__(self, rule: str, message: str) -> None:
+        super().__init__(message)
+        self.rule = rule
+        self.message = message
+
+
+def whole_number(value: object) -> object:
+    """A whole-number float in the safe range as an `int` (ADR 0003: `1.0` is an integer); `1.5`, `true` and `"1"`
+    stay, for the type rule to refuse. An `int` outside the safe range is refused: it needs `int64`."""
+    if isinstance(value, float) and value.is_integer() and abs(value) <= MAX_SAFE_INTEGER:
+        return int(value)
+
+    if isinstance(value, int) and not isinstance(value, bool) and abs(value) > MAX_SAFE_INTEGER:
+        raise ValueRuleError(TYPE_RULE, "an integer outside the safe range")
+
+    return value
+
+
+def date_time_from_text(text: str) -> datetime:
+    """An RFC 3339 date-time as an aware `datetime`, kept with the offset it was sent with."""
+    matched = _DATE_TIME.fullmatch(text)
+
+    if matched is None:
+        raise _format_error("date-time")
+
+    day, time, fraction, offset = matched.groups()
+    microseconds = "" if fraction is None else "." + fraction[:_MICROSECOND_DIGITS].ljust(_MICROSECOND_DIGITS, "0")
+    offset = "+00:00" if offset in ("Z", "z") else offset
+
+    try:
+        return datetime.fromisoformat(f"{day}T{time}{microseconds}{offset}")
+    except ValueError:
+        raise _format_error("date-time") from None
+
+
+def date_from_text(text: str) -> date:
+    try:
+        if _DATE.fullmatch(text) is None:
+            raise ValueError(text)
+
+        return date.fromisoformat(text)
+    except ValueError:
+        raise _format_error("date") from None
+
+
+def uuid_from_text(text: str) -> UUID:
+    if UUID_TEXT.fullmatch(text) is None:
+        raise _format_error("uuid")
+
+    return UUID(text)
+
+
+def decimal_from_text(text: str) -> Decimal:
+    try:
+        if _DECIMAL.fullmatch(text) is None:
+            raise InvalidOperation(text)
+
+        return Decimal(text)
+    except InvalidOperation:
+        raise _format_error("decimal") from None
+
+
+_FORMATS: Final[dict[str, Callable[[str], object]]] = {
+    "date-time": date_time_from_text,
+    "date": date_from_text,
+    "uuid": uuid_from_text,
+    "decimal": decimal_from_text,
+}
+
+
+def scalar_from_wire(type_use: object, value: object) -> object:
+    """A decoded value of a `scalar`, `enum` or `opaque` type use, checked by its type and converted by its format;
+    an enum value stays its wire text, which the placement turns into its generated member. Raises
+    `ValueRuleError`."""
+    kind = ir_string(type_use, "kind")
+
+    if kind == "enum":
+        return _checked(value, isinstance(value, str))
+
+    if kind != "scalar":
+        return value
+
+    scalar_type = ir_string(type_use, "type")
+
+    if scalar_type == "integer":
+        number = whole_number(value)
+        return _checked(number, isinstance(number, int) and not isinstance(number, bool))
+
+    if scalar_type == "number":
+        finite = isinstance(value, int | float) and not isinstance(value, bool) and math.isfinite(value)
+        return _checked(value, finite)
+
+    if scalar_type == "boolean":
+        return _checked(value, isinstance(value, bool))
+
+    if not isinstance(value, str):
+        raise ValueRuleError(TYPE_RULE, "not a string")
+
+    convert = _FORMATS.get(ir_string(type_use, "format") or "")
+
+    return value if convert is None else convert(value)
+
+
+def checked_scalar(type_use: object, value: object) -> object:
+    """`scalar_from_wire`, then every refinement of the type use with ADR 0003's meaning; a framework-free check for
+    the values the boundary reads itself (a scope id, a subject id, a rule proof)."""
+    converted = scalar_from_wire(type_use, value)
+    refinements = ir_map(type_use, "refinements")
+
+    if isinstance(converted, str):
+        check_length(converted, ir_int(refinements, "minLength"), ir_int(refinements, "maxLength"))
+        normalized = ir_string(ir_map(refinements, "pattern"), "normalized")
+
+        if normalized is not None and not contract_pattern(normalized).matches(converted):
+            raise ValueRuleError("pattern", "does not match the contract pattern")
+
+    if isinstance(converted, int | float | Decimal) and not isinstance(converted, bool):
+        check_bounds(
+            converted,
+            ir_string(refinements, "minimum"),
+            ir_string(refinements, "maximum"),
+            ir_string(refinements, "exclusiveMinimum"),
+            ir_string(refinements, "exclusiveMaximum"),
+        )
+        divisor = ir_string(refinements, "multipleOf")
+
+        if divisor is not None:
+            check_multiple_of(converted, divisor)
+
+    return converted
+
+
+def check_length(value: str | list[object], min_length: int | None, max_length: int | None) -> None:
+    """`minLength` and `maxLength`, counted in code points for a string."""
+    if min_length is not None and len(value) < min_length:
+        raise ValueRuleError("minLength", f"at least {min_length} long")
+
+    if max_length is not None and len(value) > max_length:
+        raise ValueRuleError("maxLength", f"at most {max_length} long")
+
+
+def check_bounds(
+    value: int | float | Decimal,
+    minimum: str | None = None,
+    maximum: str | None = None,
+    exclusive_minimum: str | None = None,
+    exclusive_maximum: str | None = None,
+) -> None:
+    """The bounds of ADR 0003, compared exactly as decimals; each bound is the IR's decimal literal."""
+    exact = exact_decimal(value)
+    rules: tuple[tuple[str, str | None, Callable[[Decimal, Decimal], bool]], ...] = (
+        ("minimum", minimum, Decimal.__ge__),
+        ("maximum", maximum, Decimal.__le__),
+        ("exclusiveMinimum", exclusive_minimum, Decimal.__gt__),
+        ("exclusiveMaximum", exclusive_maximum, Decimal.__lt__),
+    )
+
+    for rule, bound, holds in rules:
+        if bound is not None and not holds(exact, Decimal(bound)):
+            raise ValueRuleError(rule, f"outside the bound {bound}")
+
+
+def check_multiple_of(value: int | float | Decimal, divisor: str) -> None:
+    """Compared as exact fractions: a decimal remainder raises past the context's precision on a large value."""
+    if Fraction(exact_decimal(value)) % Fraction(Decimal(divisor)) != 0:
+        raise ValueRuleError("multipleOf", f"not a multiple of {divisor}")
+
+
+def exact_decimal(value: int | float | Decimal) -> Decimal:
+    """A float as the shortest decimal that reads back to it, the text the wire wrote, never its binary expansion."""
+    return Decimal(repr(value)) if isinstance(value, float) else Decimal(value)
+
+
+def _checked(value: object, holds: bool) -> object:
+    if not holds:
+        raise ValueRuleError(TYPE_RULE, "not a value of the contract's type")
+
+    return value
+
+
+def _format_error(format_: str) -> ValueRuleError:
+    return ValueRuleError(FORMAT_RULE, f"not a {format_}")

seampact/codegen/runtime/version.py

@@ -0,0 +1,59 @@
+"""The version of the installed runtime and of the generator shipped with it (ADR 0025 "Version guards", G3): the
+generator stamps it into each api's code as `GENERATED_BY`, and the boot check, first of all, refuses code stamped for
+another `major.minor` or a higher patch. The release pipeline stamps the constant; unreleased, it holds the
+development version, which matches only itself."""
+
+import re
+from typing import Final
+
+RUNTIME_VERSION: Final = "1.0.0"
+GENERATED_FOR_OTHER_VERSION: Final = "runtime.generated-for-other-version"
+
+_VERSION: Final = re.compile(r"(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?")
+
+
+class RuntimeVersionError(RuntimeError):
+    """The api's generated code was written for another runtime; the message names both versions and the fix."""
+
+    code = GENERATED_FOR_OTHER_VERSION
+
+
+def accepts(generated_by: str, installed: str = RUNTIME_VERSION) -> bool:
+    """The same version, or the same `major.minor` with an installed patch at or above the generator's; a
+    pre-release matches only itself."""
+    if generated_by == installed:
+        return True
+
+    generated = _VERSION.fullmatch(generated_by)
+    runtime = _VERSION.fullmatch(installed)
+
+    if generated is None or runtime is None or generated.group(1, 2) != runtime.group(1, 2):
+        return False
+
+    generated_patch = int(generated.group(3))
+    runtime_patch = int(runtime.group(3))
+
+    if generated_patch != runtime_patch:
+        return runtime_patch > generated_patch and generated.group(4) is None and runtime.group(4) is None
+
+    return generated.group(4) == runtime.group(4)
+
+
+def other_version_problem(api: str, generated_by: str, installed: str = RUNTIME_VERSION) -> str | None:
+    """The boot check's first line, or None when the runtime accepts the generated code."""
+    if accepts(generated_by, installed):
+        return None
+
+    return (
+        f"seampact {GENERATED_FOR_OTHER_VERSION}: The '{api}' boundary was generated by seampact {generated_by}; "
+        f"the installed runtime is {installed}. Run seampact generate again with the generator at {installed}, "
+        f"or install the runtime at {generated_by} or a later patch of it."
+    )
+
+
+def refuse_other_version(api: str, generated_by: str, installed: str = RUNTIME_VERSION) -> None:
+    """Raises `RuntimeVersionError` when the runtime does not accept the generated code."""
+    problem = other_version_problem(api, generated_by, installed)
+
+    if problem is not None:
+        raise RuntimeVersionError(problem)

seampact/codegen/runtime/version_token.py

@@ -0,0 +1,108 @@
+"""The version check of an operation with `concurrency` (grammar section 6): the client sends the version it last
+read in the declared source, which the input step decoded and checked; the handler compares it with the stored one
+and answers the stale role's code when they differ: `stateConflict` (409) for a body or query version,
+`preconditionFailed` (412) for a header one, whose absence is `preconditionRequired` (428). `If-Match` carries the
+version as an entity tag, strong or weak (a compressing server or proxy weakens the tag it read, and the version is
+the same), which the boundary unquotes. The boundary reads the version and builds those
+refusals; it never stores a version."""
+
+import dataclasses
+from collections.abc import Mapping
+from typing import Final
+
+from seampact.codegen.runtime.contract import ApiContract
+from seampact.codegen.runtime.failures import BoundaryFailureError, ContractRefusal
+from seampact.codegen.runtime.input_decoding import DecodedInput, role_refusal
+from seampact.codegen.runtime.ir_view import ir_map, ir_string
+
+STATE_CONFLICT_ROLE: Final = "stateConflict"
+PRECONDITION_FAILED_ROLE: Final = "preconditionFailed"
+PRECONDITION_REQUIRED_ROLE: Final = "preconditionRequired"
+_HEADER_SOURCE: Final = "header"
+_IF_MATCH: Final = "if-match"
+_TAG_QUOTE: Final = '"'
+_WEAK_TAG_PREFIX: Final = "W/"
+_ANY_TAG: Final = "*"
+
+
+def sent_version(contract: ApiContract, operation_id: str, decoded: DecodedInput) -> object:
+    """The version the request carries, None when the client sent none in a body or query source.
+
+    A placement calls it before the input check of the version parameter, so a missing header is never
+    `schemaInvalid`. Raises `ContractRefusal` with the `preconditionRequired` role for a header version the client did
+    not send or sent empty, `If-Match: *` included (it carries no version), and with the `preconditionFailed` role
+    for an `If-Match` value that is not one entity tag (it can match no version). Raises `BoundaryFailureError` for an
+    operation without `concurrency`, or a version source the boundary does not read."""
+    source = ir_map(ir_map(contract.operation(operation_id), "concurrency"), "version")
+    where = ir_string(source, "in")
+    name = ir_string(source, "name") or ""
+    parts: Mapping[str, object] = {
+        "path": decoded.path,
+        "query": decoded.query,
+        "header": decoded.headers,
+        "body": decoded.body,
+    }
+    part = parts.get(where or "")
+
+    if where is None or where not in parts:
+        raise BoundaryFailureError(
+            f"seampact: operation '{operation_id}' reads its version from {where!r}, which is not a request part the "
+            "boundary reads; regenerate the api."
+        )
+
+    version = part.get(name) if isinstance(part, Mapping) else None
+
+    if where != _HEADER_SOURCE:
+        return version
+
+    if version is None or (isinstance(version, str) and version.strip() == ""):
+        raise role_refusal(contract, operation_id, PRECONDITION_REQUIRED_ROLE)
+
+    if name.lower() != _IF_MATCH:
+        return version
+
+    if isinstance(version, str) and version.strip() == _ANY_TAG:
+        raise role_refusal(contract, operation_id, PRECONDITION_REQUIRED_ROLE)
+
+    return _tag_value(contract, operation_id, version)
+
+
+def with_sent_version(contract: ApiContract, operation_id: str, decoded: DecodedInput) -> DecodedInput:
+    """The decoded input after the version check, a header version unquoted (`If-Match: "7"` or `W/"7"` reads `7`),
+    as the handler compares it; the input itself for an operation without `concurrency`. Raises as `sent_version`."""
+    concurrency = ir_map(contract.operation(operation_id), "concurrency")
+
+    if not concurrency:
+        return decoded
+
+    version = sent_version(contract, operation_id, decoded)
+    source = ir_map(concurrency, "version")
+
+    if ir_string(source, "in") != _HEADER_SOURCE:
+        return decoded
+
+    headers = {**decoded.headers, ir_string(source, "name") or "": version}
+
+    return dataclasses.replace(decoded, headers=headers)
+
+
+def stale_version(contract: ApiContract, operation_id: str) -> ContractRefusal:
+    """The refusal a handler raises when the sent version is not the stored one."""
+    source = ir_map(ir_map(contract.operation(operation_id), "concurrency"), "version")
+    role = PRECONDITION_FAILED_ROLE if ir_string(source, "in") == _HEADER_SOURCE else STATE_CONFLICT_ROLE
+
+    return role_refusal(contract, operation_id, role)
+
+
+def _tag_value(contract: ApiContract, operation_id: str, tag: object) -> str:
+    """The version inside `"7"` or `W/"7"`; a list or bare text names no version, so it is stale."""
+    if not isinstance(tag, str):
+        raise role_refusal(contract, operation_id, PRECONDITION_FAILED_ROLE)
+
+    value = tag.strip().removeprefix(_WEAK_TAG_PREFIX)
+    quoted = len(value) >= 2 and value.startswith(_TAG_QUOTE) and value.endswith(_TAG_QUOTE)
+
+    if not quoted or _TAG_QUOTE in value[1:-1]:
+        raise role_refusal(contract, operation_id, PRECONDITION_FAILED_ROLE)
+
+    return value[1:-1]