seampact-codegen 1.0.0__py3-none-any.whl

seampact/codegen/runtime/pydantic/__init__.py

@@ -0,0 +1,165 @@
+"""The type layer of the generated Pydantic models FastAPI and Ninja share: annotated types whose `BeforeValidator`
+turns a decoded wire value into the Python object Pydantic's strict mode expects (a whole-number float into an
+`int`; `date-time`, `date`, `uuid` and decimal strings, and enum values, into their objects), and the validators of
+`rules: seampact-consistent`, each failing with the contract rule's name as its Pydantic error type."""
+
+from collections.abc import Callable
+from datetime import date, datetime
+from decimal import Decimal
+from enum import Enum
+from typing import Annotated, Final, TypeVar
+from uuid import UUID
+
+from pydantic import AfterValidator, BeforeValidator, JsonValue
+from pydantic_core import PydanticCustomError
+
+from seampact.codegen.runtime import value_rules
+from seampact.codegen.runtime.pattern import contract_pattern
+from seampact.codegen.runtime.value_rules import ValueRuleError
+
+_FORMAT_RULE: Final = "format"
+_TYPE_RULE: Final = "type"
+_ENUM_RULE: Final = "enum"
+
+
+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 strict type rule to refuse. An `int` outside the safe range is refused: it needs `int64`."""
+    try:
+        return value_rules.whole_number(value)
+    except ValueRuleError as refused:
+        raise _rule_error(refused.rule, refused.message) from None
+
+
+def refuse_null(value: object) -> object:
+    """A wire `null` on an optional member that is not nullable (ADR 0003 section 5: absent and null differ)."""
+    if value is None:
+        raise PydanticCustomError(_TYPE_RULE, "null on a member that is not nullable")
+
+    return value
+
+
+def date_time_from_wire(value: object) -> object:
+    """An RFC 3339 date-time string as an aware `datetime`, kept with the offset it was sent with."""
+    return _from_text(value, value_rules.date_time_from_text, "date-time")
+
+
+def date_from_wire(value: object) -> object:
+    return _from_text(value, value_rules.date_from_text, "date")
+
+
+def uuid_from_wire(value: object) -> object:
+    return _from_text(value, value_rules.uuid_from_text, "uuid")
+
+
+def decimal_from_wire(value: object) -> object:
+    return _from_text(value, value_rules.decimal_from_text, "decimal")
+
+
+def enum_from_wire[E: Enum](enum_type: type[E]) -> BeforeValidator:
+    """A string that is one of the enum's values as its member, another string refused by the `enum` rule; a value
+    that is no string stays, for the strict type rule."""
+
+    def member(value: object) -> object:
+        if not isinstance(value, str):
+            return value
+
+        listed = next((item for item in enum_type if item.value == value), None)
+
+        if listed is None:
+            raise PydanticCustomError(_ENUM_RULE, "a value the enum does not list")
+
+        return listed
+
+    return BeforeValidator(member)
+
+
+WholeNumber = Annotated[int, BeforeValidator(whole_number)]
+WireDateTime = Annotated[datetime, BeforeValidator(date_time_from_wire)]
+WireDate = Annotated[date, BeforeValidator(date_from_wire)]
+WireUuid = Annotated[UUID, BeforeValidator(uuid_from_wire)]
+WireDecimal = Annotated[Decimal, BeforeValidator(decimal_from_wire)]
+
+_T = TypeVar("_T")
+
+# An optional member that is not nullable: absent, it takes the default None, which Pydantic does not validate; a
+# wire `null` meets `refuse_null` (ADR 0003 section 5: absent and null differ). A generic `Annotated` alias, not a
+# `type` statement: Pydantic 2.9, FastAPI 0.162's floor, builds no schema from a subscripted PEP 695 alias.
+Omittable = Annotated[_T | None, BeforeValidator(refuse_null)]
+
+# An opaque value, any JSON but a wire `null`, which only a nullable use takes (ADR 0003 section 5).
+Opaque = Annotated[JsonValue, BeforeValidator(refuse_null)]
+
+
+def length(min_length: int | None = None, max_length: int | None = None) -> AfterValidator:
+    """`minLength` and `maxLength` of a string or a list, counted in code points for a string."""
+
+    def check[V: str | list[object]](value: V) -> V:
+        _checked(lambda: value_rules.check_length(value, min_length, max_length))
+
+        return value
+
+    return AfterValidator(check)
+
+
+def bounds(
+    minimum: str | None = None,
+    maximum: str | None = None,
+    exclusive_minimum: str | None = None,
+    exclusive_maximum: str | None = None,
+) -> AfterValidator:
+    """The bounds of ADR 0003, compared exactly as decimals; each bound is the IR's decimal literal."""
+
+    def check[N: int | float | Decimal](value: N) -> N:
+        _checked(lambda: value_rules.check_bounds(value, minimum, maximum, exclusive_minimum, exclusive_maximum))
+
+        return value
+
+    return AfterValidator(check)
+
+
+def multiple_of(divisor: str) -> AfterValidator:
+    def check[N: int | float | Decimal](value: N) -> N:
+        _checked(lambda: value_rules.check_multiple_of(value, divisor))
+
+        return value
+
+    return AfterValidator(check)
+
+
+def pattern(normalized: str) -> AfterValidator:
+    """The contract pattern, checked by the framework-free pattern check on Python's `re`."""
+    compiled = contract_pattern(normalized)
+
+    def check(value: str) -> str:
+        if not compiled.matches(value):
+            raise _rule_error("pattern", "does not match the contract pattern")
+
+        return value
+
+    return AfterValidator(check)
+
+
+def _from_text(value: object, convert: Callable[[str], object], format_: str) -> object:
+    if not isinstance(value, str):
+        return value
+
+    try:
+        return convert(value)
+    except ValueRuleError:
+        raise _format_error(format_) from None
+
+
+def _checked(check: Callable[[], None]) -> None:
+    try:
+        check()
+    except ValueRuleError as refused:
+        raise _rule_error(refused.rule, refused.message) from None
+
+
+def _format_error(format_: str) -> PydanticCustomError:
+    return PydanticCustomError(_FORMAT_RULE, "not a {format}", {"format": format_})
+
+
+def _rule_error(rule: str, message: str) -> PydanticCustomError:
+    return PydanticCustomError(rule, message)

seampact/codegen/runtime/pydantic/checked_input.py

@@ -0,0 +1,52 @@
+"""The operation features around steps 6 to 8 of one contract request, in the order every target runs them: the sent
+version first, so a missing `If-Match` answers `preconditionRequired` and never `schemaInvalid`; the typed input as
+sent; the paged list's limit filled in and the input field rights, which leave out or refuse a restricted member;
+then the deadline. The idempotency claim comes next, in the placement, which holds the store."""
+
+import dataclasses
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from seampact.codegen.runtime.access_steps import AccessHooks, AccessState, HookCaller
+from seampact.codegen.runtime.contract import ApiContract
+from seampact.codegen.runtime.deadline import request_deadline
+from seampact.codegen.runtime.field_rights import checked_input_fields
+from seampact.codegen.runtime.input_decoding import DecodedInput
+from seampact.codegen.runtime.page_reply import filled_page_query
+from seampact.codegen.runtime.pydantic.contract_input import InputBuilder
+from seampact.codegen.runtime.version_token import with_sent_version
+
+
+@dataclass(frozen=True, slots=True)
+class CheckedInput:
+    """The typed request the handler receives, and the decoded input it was built from: the filled page limit and
+    the body its field rights leave."""
+
+    typed: object
+    decoded: DecodedInput
+
+
+async def checked_input(
+    contract: ApiContract,
+    operation_id: str,
+    decoded: DecodedInput,
+    raw_query: str,
+    access: AccessState,
+    hooks: AccessHooks,
+    builder: InputBuilder,
+    call: HookCaller,
+) -> CheckedInput:
+    """Raises `ContractRefusal` for a refused input and `BoundaryFailureError` for a hook's undeclared answer."""
+    sent = with_sent_version(contract, operation_id, decoded)
+    typed = builder.build(sent, access, raw_query)
+    filled_query = filled_page_query(contract, operation_id, sent.query)
+    checked_body = await checked_input_fields(access, hooks, call)
+    handed = dataclasses.replace(sent, query=filled_query, body=checked_body)
+
+    # The input as sent was checked; the handler receives the filled limit and the body its field rights leave.
+    if filled_query != sent.query or checked_body != sent.body:
+        typed = builder.build(handed, access, raw_query)
+
+    request_deadline(contract, operation_id, handed, datetime.now(UTC))
+
+    return CheckedInput(typed, handed)

seampact/codegen/runtime/pydantic/contract_input.py

@@ -0,0 +1,183 @@
+"""Steps 6 to 8 of one operation (ADR 0026 "Types and validation"): its path, query and header parts and its body,
+decoded by the boundary, validated by the generated models in Pydantic's strict mode; every issue of every part is
+reported together as the operation's `schemaInvalid` refusal. Then the typed request: the input, the principal the
+access steps admitted and the scopes they resolved, one attribute per scope in declared order."""
+
+import dataclasses
+import typing
+from collections.abc import Mapping
+from typing import Final, TypeGuard
+
+import pydantic
+
+from seampact.codegen.runtime.access_steps import AccessState
+from seampact.codegen.runtime.contract import HEADER_PART, PATH_PART, PROOFS_PART, QUERY_PART, ApiContract
+from seampact.codegen.runtime.failures import BoundaryFailureError
+from seampact.codegen.runtime.input_decoding import DecodedInput, Issue, schema_invalid
+from seampact.codegen.runtime.ir_view import ir_map, ir_maps, ir_string
+from seampact.codegen.runtime.page_reply import cursor_issues
+from seampact.codegen.runtime.pydantic.issues import MAX_RENDERED_ISSUES, body_issues, part_issues, proof_issues
+from seampact.codegen.runtime.run_settings import OperationTypes
+from seampact.codegen.runtime.wire_codec import WireCodec
+from seampact.codegen.runtime.wire_values import raw_query
+
+_INPUT_FIELD: Final = "input"
+_PRINCIPAL_FIELD: Final = "principal"
+_SCOPES_FIELD: Final = "scopes"
+_BODY_FIELD: Final = "body"
+_UNKNOWN_KEYS_RULE: Final = "unknownKeys"
+_REFUSE: Final = "refuse"
+_IGNORE: Final = "ignore"
+# The input attribute of each part and where its issues are reported.
+_PARTS: Final = (("path", PATH_PART), ("query", QUERY_PART), ("headers", HEADER_PART))
+
+
+class InputBuilder:
+    """Built once per operation, when its route is added; reads the generated types' annotations."""
+
+    def __init__(self, contract: ApiContract, operation_id: str, types: OperationTypes) -> None:
+        self._contract = contract
+        self._operation_id = operation_id
+        self._request_type = types.request
+        request_fields = typing.get_type_hints(types.request)
+        self._input_type = request_fields.get(_INPUT_FIELD)
+        self._scopes_type = request_fields.get(_SCOPES_FIELD)
+        self._has_principal = _PRINCIPAL_FIELD in request_fields
+        input_fields = {} if self._input_type is None else typing.get_type_hints(self._input_type)
+        self._part_models = {
+            attribute: model
+            for attribute, _ in _PARTS
+            if isinstance(model := input_fields.get(attribute), type) and issubclass(model, pydantic.BaseModel)
+        }
+        body_type = input_fields.get(_BODY_FIELD)
+        self._body = None if body_type is None else pydantic.TypeAdapter[object](body_type)
+        self._proofs_model = types.proofs if _is_model(types.proofs) else None
+        self._proof_types = {
+            ir_string(proof, "name") or "": ir_map(proof, "schema")
+            for proof in ir_maps(ir_map(contract.operation(operation_id), "input"), "proofs")
+        }
+
+    def build(self, decoded: DecodedInput, access: AccessState, raw_query_string: str) -> object:
+        """Raises the operation's `schemaInvalid` refusal with every issue at once."""
+        issues: list[Issue] = []
+        values: dict[str, object] = {}
+        wire_parts = {"path": decoded.path, "query": decoded.query, "headers": decoded.headers}
+
+        for attribute, part in _PARTS:
+            model = self._part_models.get(attribute)
+            members = self._contract.part_members(self._operation_id, part)
+
+            if part == QUERY_PART:
+                issues += self._unknown_query(members, raw_query_string)
+
+            if model is None:
+                continue
+
+            renamed = {members[name]: value for name, value in wire_parts[attribute].items() if name in members}
+
+            try:
+                values[attribute] = model.model_validate(renamed, strict=True)
+            except pydantic.ValidationError as error:
+                issues += part_issues(part, members, error)
+
+        if self._body is not None:
+            issues += self._validate_body(decoded.body, values)
+
+        issues += cursor_issues(self._contract, self._operation_id, decoded.query)
+
+        if issues:
+            raise schema_invalid(self._contract, self._operation_id, issues[:MAX_RENDERED_ISSUES])
+
+        return self._typed_request(values, access)
+
+    def _unknown_query(self, members: Mapping[str, str], raw_query_string: str) -> list[Issue]:
+        if self._contract.ignores_unknown_query(self._operation_id):
+            return []
+
+        return [
+            Issue(QUERY_PART, f"/{name}", _UNKNOWN_KEYS_RULE)
+            for name in raw_query(raw_query_string)
+            if name not in members
+        ]
+
+    def _validate_body(self, tree: object, values: dict[str, object]) -> list[Issue]:
+        if self._body is None:
+            return []
+
+        type_use = ir_map(ir_map(self._contract.operation(self._operation_id), "input"), "schema")
+        policy = self._contract.unknown_keys_policy(self._operation_id)
+
+        if policy not in (_REFUSE, _IGNORE):
+            raise BoundaryFailureError(
+                f"seampact: operation '{self._operation_id}' keeps unknown body keys, which this seampact-fastapi "
+                "release does not serve; leave the operation out with the entry's `operations` filter."
+            )
+
+        issues = self._proof_issues(tree)
+        python_tree = WireCodec(self._contract).to_python(type_use, self._without_proofs(tree))
+
+        if policy == _REFUSE:
+            issues += [Issue(_BODY_FIELD, pointer, _UNKNOWN_KEYS_RULE) for pointer in python_tree.unknown_keys]
+
+        try:
+            values[_BODY_FIELD] = self._body.validate_python(python_tree.value, strict=True)
+        except pydantic.ValidationError as error:
+            issues += body_issues(self._contract, type_use, error)
+
+        return issues
+
+    def _proof_issues(self, tree: object) -> list[Issue]:
+        """Each rule proof checked by its full type (enum, pattern, bounds, nested members), as the body's other
+        members are; the access steps only checked its scalar type before the decider read it."""
+        if self._proofs_model is None or not isinstance(tree, dict):
+            return []
+
+        members = self._contract.part_members(self._operation_id, PROOFS_PART)
+        codec = WireCodec(self._contract)
+        renamed = {
+            members[name]: codec.to_python(type_use, tree[name]).value
+            for name, type_use in self._proof_types.items()
+            if name in tree and name in members
+        }
+
+        try:
+            self._proofs_model.model_validate(renamed, strict=True)
+        except pydantic.ValidationError as error:
+            return proof_issues(self._contract, self._proof_types, members, error)
+
+        return []
+
+    def _without_proofs(self, tree: object) -> object:
+        """The body without the rule proofs, which the access steps read and the handler never sees."""
+        if not isinstance(tree, dict) or not self._proof_types:
+            return tree
+
+        return {name: value for name, value in tree.items() if name not in self._proof_types}
+
+    def _typed_request(self, values: dict[str, object], access: AccessState) -> object:
+        if self._input_type is None:
+            raise BoundaryFailureError(
+                f"seampact: the request type of operation '{self._operation_id}' has no input; regenerate the api."
+            )
+
+        arguments: dict[str, object] = {_INPUT_FIELD: self._input_type(**values)}
+
+        if self._has_principal:
+            arguments[_PRINCIPAL_FIELD] = access.principal
+
+        if self._scopes_type is not None:
+            names = [field.name for field in dataclasses.fields(self._scopes_type)]
+            resolved = {scope.scope: scope for scope in access.scopes}
+            scope_ids = [
+                ir_string(entry, "scope") or ""
+                for entry in ir_maps(self._contract.operation(self._operation_id), "scopes")
+            ]
+            arguments[_SCOPES_FIELD] = self._scopes_type(
+                **{name: resolved[scope_id] for name, scope_id in zip(names, scope_ids, strict=True)}
+            )
+
+        return self._request_type(**arguments)
+
+
+def _is_model(candidate: type | None) -> TypeGuard[type[pydantic.BaseModel]]:
+    return isinstance(candidate, type) and issubclass(candidate, pydantic.BaseModel)

seampact/codegen/runtime/pydantic/issues.py

@@ -0,0 +1,142 @@
+"""Step 6's issues from a Pydantic `ValidationError`: each error's location read back to the wire's JSON pointer through
+the api's member tables, and its type to the contract rule name (ADR 0026 "Types and validation"), bounded by
+`MAX_RENDERED_ISSUES`. FastAPI and Ninja share it."""
+
+from collections.abc import Mapping, Sequence
+from typing import Final
+
+from pydantic import ValidationError
+
+from seampact.codegen.runtime.contract import HEADER_PART, ApiContract
+from seampact.codegen.runtime.input_decoding import Issue
+from seampact.codegen.runtime.ir_view import IrMap, ir_map, ir_string
+
+MAX_RENDERED_ISSUES: Final = 100
+
+_CONTRACT_RULES: Final = frozenset(
+    {
+        "required",
+        "type",
+        "format",
+        "minLength",
+        "maxLength",
+        "minItems",
+        "maxItems",
+        "minimum",
+        "maximum",
+        "exclusiveMinimum",
+        "exclusiveMaximum",
+        "multipleOf",
+        "pattern",
+        "enum",
+        "const",
+        "unknownKeys",
+    }
+)
+_PYDANTIC_RULES: Final = {
+    "missing": "required",
+    "string_too_short": "minLength",
+    "string_too_long": "maxLength",
+    "too_short": "minItems",
+    "too_long": "maxItems",
+    "greater_than_equal": "minimum",
+    "greater_than": "exclusiveMinimum",
+    "less_than_equal": "maximum",
+    "less_than": "exclusiveMaximum",
+    "multiple_of": "multipleOf",
+    "string_pattern_mismatch": "pattern",
+    "enum": "enum",
+    "literal_error": "enum",
+    "extra_forbidden": "unknownKeys",
+}
+_TYPE_RULE: Final = "type"
+
+
+def part_issues(in_: str, members: Mapping[str, str], error: ValidationError) -> list[Issue]:
+    """The issues of a path, query or header model, whose members `members` maps from wire name to attribute."""
+    wire_names = {attribute: wire_name for wire_name, attribute in members.items()}
+    issues: list[Issue] = []
+
+    for detail in error.errors():
+        location = detail["loc"]
+        first = str(location[0]) if location else ""
+        rest = "".join(f"/{_escaped(str(step))}" for step in location[1:])
+        wire_name = wire_names.get(first, first)
+        # Header names are case-insensitive: a header issue names its header in lower case, as the wire reads it.
+        named = wire_name.lower() if in_ == HEADER_PART else wire_name
+        issues.append(Issue(in_, f"/{_escaped(named)}{rest}", contract_rule(detail["type"])))
+
+    return issues[:MAX_RENDERED_ISSUES]
+
+
+def body_issues(contract: ApiContract, type_use: IrMap, error: ValidationError) -> list[Issue]:
+    """The issues of a body validated as `type_use`, their pointers in wire names."""
+    return [
+        Issue("body", body_pointer(contract, type_use, detail["loc"]), contract_rule(detail["type"]))
+        for detail in error.errors()
+    ][:MAX_RENDERED_ISSUES]
+
+
+def proof_issues(
+    contract: ApiContract, proofs: Mapping[str, IrMap], members: Mapping[str, str], error: ValidationError
+) -> list[Issue]:
+    """The issues of a body's rule proofs validated as one model: `proofs` holds each proof's type use by wire name,
+    `members` maps each wire name to its attribute; a pointer starts at the proof's body member."""
+    wire_names = {attribute: wire_name for wire_name, attribute in members.items()}
+    issues: list[Issue] = []
+
+    for detail in error.errors():
+        location = detail["loc"]
+        attribute = str(location[0]) if location else ""
+        wire_name = wire_names.get(attribute, attribute)
+        inner = body_pointer(contract, proofs.get(wire_name, {}), location[1:])
+        issues.append(Issue("body", f"/{_escaped(wire_name)}{inner}", contract_rule(detail["type"])))
+
+    return issues[:MAX_RENDERED_ISSUES]
+
+
+def contract_rule(error_type: str) -> str:
+    """The contract rule a Pydantic error type stands for; the type layer's own errors are named after their rule."""
+    if error_type in _CONTRACT_RULES:
+        return error_type
+
+    return _PYDANTIC_RULES.get(error_type, _TYPE_RULE)
+
+
+def body_pointer(contract: ApiContract, type_use: IrMap, location: Sequence[int | str]) -> str:
+    """The JSON pointer of a Pydantic location in a body of `type_use`, attributes read back to wire names."""
+    pointer = ""
+    current = type_use
+
+    for step in location:
+        kind = ir_string(current, "kind")
+
+        if kind == "ref" and isinstance(step, str):
+            schema_id = ir_string(current, "schema") or ""
+            wire_names = {attribute: wire for wire, attribute in contract.members.get(schema_id, {}).items()}
+            wire_name = wire_names.get(step, step)
+            pointer += f"/{_escaped(wire_name)}"
+            current = _member_type(contract, schema_id, wire_name)
+            continue
+
+        if kind == "array":
+            current = ir_map(current, "items")
+
+        pointer += f"/{_escaped(str(step))}"
+
+    return pointer
+
+
+def _member_type(contract: ApiContract, schema_id: str, wire_name: str) -> IrMap:
+    schema = contract.declaration("schemas", schema_id)
+    properties = schema.get("properties")
+
+    for member in properties if isinstance(properties, list) else []:
+        if isinstance(member, Mapping) and ir_string(member, "name") == wire_name:
+            return ir_map(member, "type")
+
+    return {}
+
+
+def _escaped(name: str) -> str:
+    return name.replace("~", "~0").replace("/", "~1")

seampact/codegen/runtime/raw_target.py

@@ -0,0 +1,103 @@
+"""The raw request target as the client sent it, without its query: the ASGI `raw_path` (minus a raw prefix equal to
+`root_path`), or the WSGI `RAW_URI` or `REQUEST_URI` (minus `SCRIPT_NAME`). A server that gives no raw target leaves
+the decoded path, marked so the boundary logs once which raw-path rules it cannot apply."""
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Final
+
+# An absolute-form request target (`http://host/path`) keeps only its path.
+_ORIGIN: Final = re.compile(r"^[a-z][a-z0-9+.-]*://[^/]*", re.IGNORECASE)
+# ASGI and WSGI carry raw bytes as Latin-1 text, one character per byte.
+_BYTES_AS_TEXT: Final = "latin-1"
+
+
+@dataclass(frozen=True, slots=True)
+class RawTarget:
+    """`path` starts with `/`; `query` is the raw query string; `raw` is False when the server gave no raw target
+    and `path` is the decoded one."""
+
+    path: str
+    query: str
+    raw: bool
+
+
+def asgi_raw_target(scope: Mapping[str, object]) -> RawTarget | None:
+    """None when `root_path` is set and the target does not start with it: the request is not a contract request."""
+    raw_path = scope.get("raw_path")
+    query = scope.get("query_string")
+    query_text = query.decode(_BYTES_AS_TEXT) if isinstance(query, bytes) else ""
+
+    if isinstance(raw_path, bytes):
+        path = _without_query(raw_path.decode(_BYTES_AS_TEXT))
+        root = _raw_text(_text(scope, "root_path"))
+        raw = True
+    else:
+        path = _text(scope, "path")
+        root = _text(scope, "root_path")
+        raw = False
+
+    path = without_origin(path)
+
+    if root == "":
+        return RawTarget(_rooted(path), query_text, raw)
+
+    stripped = _stripped_prefix(path, root)
+
+    return None if stripped is None else RawTarget(_rooted(stripped), query_text, raw)
+
+
+def wsgi_raw_target(environ: Mapping[str, object]) -> RawTarget | None:
+    """The raw target minus `SCRIPT_NAME`, None (not a contract request) when it does not start with a non-empty
+    `SCRIPT_NAME`, as `asgi_raw_target` treats `root_path`; under a server that gives no `RAW_URI` or `REQUEST_URI`
+    (Django's `runserver`), the decoded `PATH_INFO`."""
+    query = _text(environ, "QUERY_STRING")
+    uri = _text(environ, "RAW_URI") or _text(environ, "REQUEST_URI")
+
+    if uri == "":
+        return RawTarget(_rooted(_text(environ, "PATH_INFO")), query, raw=False)
+
+    path = without_origin(_without_query(uri))
+    script = _raw_text(_text(environ, "SCRIPT_NAME").rstrip("/"))
+
+    if script == "":
+        return RawTarget(_rooted(path), query, raw=True)
+
+    stripped = _stripped_prefix(path, script)
+
+    return None if stripped is None else RawTarget(_rooted(stripped), query, raw=True)
+
+
+def _text(values: Mapping[str, object], key: str) -> str:
+    value = values.get(key)
+
+    return value if isinstance(value, str) else ""
+
+
+def _raw_text(decoded: str) -> str:
+    """A decoded prefix as the raw bytes of a target spell it when sent unescaped."""
+    return decoded.encode("utf-8").decode(_BYTES_AS_TEXT)
+
+
+def _without_query(target: str) -> str:
+    return target.split("?", 1)[0]
+
+
+def without_origin(path: str) -> str:
+    """The path of an absolute-form target (RFC 9112 section 3.2.2) without its `scheme://authority`."""
+    origin = _ORIGIN.match(path)
+
+    return path if origin is None else path[origin.end() :]
+
+
+def _stripped_prefix(path: str, prefix: str) -> str | None:
+    """`path` after `prefix` when the prefix ends at a segment boundary, else None."""
+    if path == prefix:
+        return ""
+
+    return path[len(prefix) :] if path.startswith(prefix + "/") else None
+
+
+def _rooted(path: str) -> str:
+    return path if path.startswith("/") else "/" + path