seampact-codegen 1.0.0__py3-none-any.whl

seampact/codegen/runtime/page_facts.py

@@ -0,0 +1,33 @@
+"""The fact table of a generated page class: the paging style's fact name of each attribute, written by the generator
+so the runtime never rebuilds a fact name from an attribute name."""
+
+from collections.abc import Mapping
+from typing import Final
+
+from seampact.codegen.runtime.failures import BoundaryFailureError
+
+# The class attribute of a generated page that holds its table, attribute name to fact name.
+PAGE_FACTS: Final = "_FACTS"
+
+
+def page_facts(operation_id: str, page: object, attributes: Mapping[str, object]) -> dict[str, object]:
+    """The page's attribute values by fact name, read through its class's fact table.
+
+    Raises `BoundaryFailureError` when the class has no table or an attribute is not in it."""
+    table = getattr(type(page), PAGE_FACTS, None)
+
+    if not isinstance(table, Mapping):
+        raise BoundaryFailureError(
+            f"seampact: the page of operation '{operation_id}' is a {type(page).__qualname__} without the fact table "
+            f"'{PAGE_FACTS}' of a generated page class; return the generated page."
+        )
+
+    unknown = sorted(set(attributes) - set(table))
+
+    if unknown:
+        raise BoundaryFailureError(
+            f"seampact: the page of operation '{operation_id}' has the attributes {unknown}, which its fact table "
+            "does not name; generate the page class again."
+        )
+
+    return {str(table[attribute]): value for attribute, value in attributes.items()}

seampact/codegen/runtime/page_reply.py

@@ -0,0 +1,396 @@
+"""The page a paged list answers (ADR 0002 section 14): the limit the handler receives, then the body, headers and
+`Link` relations the paging style writes from the handler's page facts and the request's position. Links are
+query-only references under relative URLs (`api.wire.urls: relative`), and start with the public origin and the
+request path under absolute ones."""
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Final, TypeGuard
+
+from seampact.codegen.runtime.contract import QUERY_PART, ApiContract
+from seampact.codegen.runtime.failures import BoundaryFailureError
+from seampact.codegen.runtime.input_decoding import Issue
+from seampact.codegen.runtime.ir_view import IrMap, ir_int, ir_map, ir_maps, ir_string, ir_strings
+from seampact.codegen.runtime.public_origin import writes_absolute_urls
+from seampact.codegen.runtime.templates import render
+from seampact.codegen.runtime.wire_values import component_encoded, kept_query_pairs, path_link_safe, scalar_text
+
+LINK: Final = "link"
+
+_LIMIT_ROLE: Final = "limit"
+_BEFORE_ROLE: Final = "before"
+_AFTER_ROLE: Final = "after"
+_CLAMP: Final = "clamp"
+_EXCLUSIVE_CURSORS_RULE: Final = "exclusiveCursors"
+_NULL_ABSENT: Final = "null"
+_PAGE: Final = "page"
+_OFFSET: Final = "offset"
+_SINCE: Final = "since"
+_CURSOR: Final = "cursor"
+_MORE: Final = "more"
+_TOTAL: Final = "total"
+_DEFAULT_PAGE_BASE: Final = 1
+_FIRST_OFFSET: Final = 0
+# The largest position the contract's int64 page and offset parameters carry.
+_INT64_MAX: Final = 2**63 - 1
+
+
+@dataclass(frozen=True, slots=True)
+class _PageLinks:
+    """The query the client sent and what each link starts with: nothing under relative URLs, the public origin and
+    the request path under absolute ones."""
+
+    raw_query: str
+    url_base: str
+
+    def with_member(self, name: str, value: str) -> str:
+        return _page_url(self.url_base, _with_query_member(self.raw_query, name, value))
+
+    def without_members(self, names: Sequence[str]) -> str:
+        return _page_url(self.url_base, _without_query_members(self.raw_query, names))
+
+
+@dataclass(frozen=True, slots=True)
+class PageParts:
+    """The page body (`{}` when the template writes none) and the headers its style writes, names in lower case."""
+
+    body: object
+    headers: tuple[tuple[str, str], ...]
+
+
+def filled_page_query(contract: ApiContract, operation_id: str, query: Mapping[str, object]) -> dict[str, object]:
+    """The query the handler receives: the route's default limit when the client sent none, and the route's
+    `maxLimit` for a larger one under `overLimit: clamp` (a larger one under `reject` was refused by the input
+    step)."""
+    paging = ir_map(contract.operation(operation_id), "paging")
+    limit_param = _role_name(_style(contract, operation_id), _LIMIT_ROLE)
+    filled = dict(query)
+
+    if not paging or limit_param is None:
+        return filled
+
+    limit = _effective_limit(paging, query.get(limit_param))
+
+    if limit is not None:
+        filled[limit_param] = limit
+
+    return filled
+
+
+def cursor_issues(contract: ApiContract, operation_id: str, query: Mapping[str, object]) -> list[Issue]:
+    """A style whose cursors travel in an `after` and a `before` parameter takes one of them: both sent is one
+    `exclusiveCursors` issue at the `before` parameter, reported with the other input issues."""
+    style = _style(contract, operation_id)
+    after_param = _role_name(style, _AFTER_ROLE)
+    before_param = _role_name(style, _BEFORE_ROLE)
+
+    if after_param is None or before_param is None:
+        return []
+
+    if after_param not in query or before_param not in query:
+        return []
+
+    return [Issue(QUERY_PART, f"/{before_param}", _EXCLUSIVE_CURSORS_RULE)]
+
+
+def page_parts(
+    contract: ApiContract,
+    operation_id: str,
+    query: Mapping[str, object],
+    raw_query: str,
+    items: Sequence[object],
+    facts: Mapping[str, object],
+    status: int,
+    request_path: str,
+    *,
+    public_origin: str | None = None,
+) -> PageParts:
+    """The page body and headers from the handler's page facts by name (`items` already encoded and projected), the
+    decoded `query` and the raw one the links keep. `request_path` is the path as the client sent it, still
+    percent-encoded; `public_origin` is `configured_origin`'s answer, None under relative URLs.
+
+    Raises `BoundaryFailureError` for absolute URLs without a public origin, an origin under relative URLs, or a
+    numbered style without a limit."""
+    style = _style(contract, operation_id)
+    write_nulls = ir_string(style, "absent") == _NULL_ABSENT
+    slots: dict[str, object] = {
+        name: facts[name] for name in ir_strings(style, "handlerResult") if facts.get(name) is not None
+    }
+    limit = _limit_of(contract, operation_id, style, query)
+
+    if limit is not None:
+        slots[_LIMIT_ROLE] = limit
+        total = facts.get(_TOTAL)
+
+        if _is_int(total) and limit > 0:
+            slots["totalPages"] = -(-total // limit)
+
+    links = _PageLinks(raw_query, _url_base(contract, public_origin, request_path))
+    slots["self"] = links.without_members([])
+    position = ir_string(style, "position")
+
+    if position in (_PAGE, _OFFSET):
+        _add_numbered_slots(operation_id, style, query, links, facts, len(items), limit, slots)
+    else:
+        _add_token_slots(style, links, facts, position, slots)
+
+    slots["items"] = list(items)
+    slots["status"] = status
+    slots["path"] = request_path
+    meta = _rendered_meta(style, slots, write_nulls)
+
+    if meta is not None:
+        slots["meta"] = meta
+
+    body = render(_page_body(contract, operation_id, style), slots, write_nulls)
+
+    return PageParts(body.value if body.present else {}, _headers(operation_id, style, slots))
+
+
+def _style(contract: ApiContract, operation_id: str) -> IrMap:
+    style_id = ir_string(ir_map(contract.operation(operation_id), "paging"), "style") or ""
+
+    return contract.declaration("pagings", style_id)
+
+
+def _page_body(contract: ApiContract, operation_id: str, style: IrMap) -> object:
+    """The style's own body, or the format's page body, whose `$meta` the style's meta joins."""
+    body = ir_map(style, "response").get("body")
+
+    if body is not None:
+        return body
+
+    return ir_map(ir_map(contract.format(operation_id), "success"), _PAGE).get("body")
+
+
+def _rendered_meta(style: IrMap, slots: Mapping[str, object], write_nulls: bool) -> dict[str, object] | None:
+    """The style's meta members, joined into the format's `$meta`; none leaves `$meta` without a value."""
+    meta: dict[str, object] = {}
+
+    for member in ir_maps(ir_map(style, "response"), "meta"):
+        value = render(member.get("value"), slots, write_nulls)
+        name = ir_string(member, "name") or ""
+
+        if value.present:
+            meta[name] = value.value
+        elif write_nulls:
+            meta[name] = None
+
+    return meta or None
+
+
+def _headers(operation_id: str, style: IrMap, slots: Mapping[str, object]) -> tuple[tuple[str, str], ...]:
+    """The style's headers, each its value's text; an absent or null value writes none. Raises
+    `BoundaryFailureError` for a value with no text (an object, an array), which the generator refuses in a
+    template."""
+    response = ir_map(style, "response")
+    headers: list[tuple[str, str]] = []
+
+    for header in ir_maps(response, "headers"):
+        value = render(header.get("value"), slots, write_nulls=False)
+        name = ir_string(header, "name") or ""
+
+        if not value.present or value.value is None:
+            continue
+
+        text = scalar_text(value.value)
+
+        if text is None:
+            raise BoundaryFailureError(
+                f"seampact: the page header '{name}' of '{operation_id}' renders a {type(value.value).__qualname__}, "
+                "not a text value; write it from a scalar slot."
+            )
+
+        headers.append((name.lower(), text))
+
+    relations = [
+        f'<{url}>; rel="{ir_string(link, "rel") or ""}"'
+        for link in ir_maps(response, "links")
+        if isinstance(url := slots.get(ir_string(link, "role") or ""), str)
+    ]
+
+    if relations:
+        headers.append((LINK, ", ".join(relations)))
+
+    return tuple(headers)
+
+
+def _add_numbered_slots(
+    operation_id: str,
+    style: IrMap,
+    query: Mapping[str, object],
+    links: _PageLinks,
+    facts: Mapping[str, object],
+    item_count: int,
+    limit: int | None,
+    slots: dict[str, object],
+) -> None:
+    """A page or offset position: the boundary counts the page, its records and the URLs from the request."""
+    if limit is None or limit <= 0:
+        raise BoundaryFailureError(f"seampact: the list '{operation_id}' has no limit; regenerate the api.")
+
+    position = ir_string(style, "position")
+    is_page = position == _PAGE
+    position_role = _position_role(style)
+    position_param = ir_string(position_role, "name") or ""
+    base = ir_int(position_role, "base")
+    base = _DEFAULT_PAGE_BASE if base is None else base
+    sent = query.get(position_param)
+
+    if is_page:
+        page_number = sent if _is_int(sent) else base
+        slots[_PAGE] = page_number
+        page_index = page_number - base
+        offset = min(page_index * limit, _INT64_MAX)
+    else:
+        offset = sent if _is_int(sent) else _FIRST_OFFSET
+        page_index = offset // limit
+
+    slots[_OFFSET] = offset
+    total = facts.get(_TOTAL)
+    # A position past the last int64 offset has no next page and no record numbers, as on every target.
+    next_fits = offset <= _INT64_MAX - limit
+    has_next = next_fits and (
+        facts.get(_MORE) is True
+        if _MORE in ir_strings(style, "handlerResult")
+        else _is_int(total) and offset + limit < total
+    )
+
+    if item_count > 0 and offset <= _INT64_MAX - item_count:
+        slots["from"] = offset + 1
+        slots["to"] = offset + item_count
+
+    slots["first"] = links.with_member(position_param, _position_at(position, base, 0, limit))
+
+    if offset > _FIRST_OFFSET:
+        previous = str(base + page_index - 1) if is_page else str(max(offset - limit, _FIRST_OFFSET))
+        slots["previous"] = links.with_member(position_param, previous)
+
+    if has_next:
+        # An offset the client chose need not fall on a page start: the next page starts one limit further.
+        following = _position_at(_PAGE, base, page_index + 1, limit) if is_page else str(offset + limit)
+        slots["next"] = links.with_member(position_param, following)
+
+    total_pages = slots.get("totalPages")
+
+    if _is_int(total_pages):
+        last_index = max(total_pages - 1, 0)
+        last = _position_at(position, base, last_index, limit)
+        slots["last"] = links.with_member(position_param, last)
+
+
+def _add_token_slots(
+    style: IrMap, links: _PageLinks, facts: Mapping[str, object], position: str | None, slots: dict[str, object]
+) -> None:
+    """A cursor or since position: the URLs carry the tokens the handler returned."""
+    position_param = ir_string(_position_role(style), "name") or ""
+    before_param = _role_name(style, _BEFORE_ROLE)
+    removed = [position_param] if before_param is None else [position_param, before_param]
+    without_position = _PageLinks(_without_query_members(links.raw_query, removed), links.url_base)
+    slots["first"] = without_position.without_members([])
+    tokens = (
+        [("next", position_param, facts.get("nextSince"))]
+        if position == _SINCE
+        else [
+            ("next", position_param, facts.get("nextCursor")),
+            ("previous", before_param or position_param, facts.get("previousCursor")),
+        ]
+    )
+
+    for role, param, token in tokens:
+        if isinstance(token, str):
+            slots[role] = without_position.with_member(param, token)
+
+
+def _position_at(position: str | None, base: int, index: int, limit: int) -> str:
+    """The page number, or the offset, of the page at `index`."""
+    return str(base + index if position == _PAGE else index * limit)
+
+
+def _position_role(style: IrMap) -> IrMap:
+    """A cursor style may carry its position in `after` and `before` instead of `cursor`."""
+    position = ir_string(style, "position") or ""
+    role = _role_of(style, position)
+
+    if role is None and position == _CURSOR:
+        role = _role_of(style, _AFTER_ROLE)
+
+    if role is None:
+        raise BoundaryFailureError(
+            f"seampact: the paging style '{ir_string(style, 'id') or ''}' has no position role; regenerate the api."
+        )
+
+    return role
+
+
+def _role_name(style: IrMap, role: str) -> str | None:
+    return ir_string(_role_of(style, role), "name")
+
+
+def _role_of(style: IrMap, role: str) -> IrMap | None:
+    return next((declared for declared in ir_maps(style, "request") if ir_string(declared, "role") == role), None)
+
+
+def _limit_of(contract: ApiContract, operation_id: str, style: IrMap, query: Mapping[str, object]) -> int | None:
+    limit_param = _role_name(style, _LIMIT_ROLE)
+    paging = ir_map(contract.operation(operation_id), "paging")
+
+    if limit_param is None:
+        return ir_int(paging, "defaultLimit")
+
+    return _effective_limit(paging, query.get(limit_param))
+
+
+def _effective_limit(paging: IrMap, sent: object) -> int | None:
+    """The default for none sent, `maxLimit` for a larger one under `clamp`."""
+    if not _is_int(sent):
+        return ir_int(paging, "defaultLimit")
+
+    max_limit = ir_int(paging, "maxLimit")
+
+    if ir_string(paging, "overLimit") == _CLAMP and max_limit is not None and sent > max_limit:
+        return max_limit
+
+    return sent
+
+
+def _without_query_members(raw_query: str, names: Sequence[str]) -> str:
+    return "&".join(kept_query_pairs(raw_query, names))
+
+
+def _with_query_member(raw_query: str, name: str, value: str) -> str:
+    kept = _without_query_members(raw_query, [name])
+    member = f"{component_encoded(name)}={component_encoded(value)}"
+
+    return member if kept == "" else f"{kept}&{member}"
+
+
+def _url_base(contract: ApiContract, public_origin: str | None, request_path: str) -> str:
+    if not writes_absolute_urls(contract):
+        if public_origin is not None:
+            raise BoundaryFailureError(
+                f"seampact: the api '{contract.api}' writes relative URLs and its page links were given a public "
+                "origin; remove public_origin, or set 'api.wire.urls: absolute'."
+            )
+
+        return ""
+
+    if public_origin is None:
+        raise BoundaryFailureError(
+            f"seampact: the api '{contract.api}' writes absolute URLs ('api.wire.urls: absolute') and its page links "
+            "have no valid public origin; set public_origin to the origin clients call, such as "
+            "https://api.example.com."
+        )
+
+    return f"{public_origin}{path_link_safe(request_path)}"
+
+
+def _page_url(url_base: str, query: str) -> str:
+    """Under relative URLs a query-only reference (RFC 3986): it resolves against the URL the client called, so it
+    keeps a path prefix a reverse proxy stripped. An empty query is `?`, since an empty reference would keep the
+    called query. Under absolute URLs the base is the public origin and the request path."""
+    return f"{url_base}?{query}"
+
+
+def _is_int(value: object) -> TypeGuard[int]:
+    return isinstance(value, int) and not isinstance(value, bool)

seampact/codegen/runtime/pattern.py

@@ -0,0 +1,69 @@
+"""The framework-free pattern check: a contract pattern's normalised form (ADR 0003 section 9) translated for
+Python's `re` and searched anywhere in the text, as JSON Schema reads `pattern`. The normalised form already spells
+`.` and the shorthands as explicit classes, so the translation only maps `^` and `$` to the start and the end of the
+string (`\\A`, `\\Z`, never before a final newline) and an astral escape `\\u{...}` to `\\U........`."""
+
+import re
+from dataclasses import dataclass, field
+from functools import cache
+from typing import Final
+
+_ASTRAL_ESCAPE: Final = re.compile(r"u\{([0-9A-F]+)\}")
+_ANCHORS: Final = {"^": r"\A", "$": r"\Z"}
+
+
+@dataclass(frozen=True, slots=True)
+class ContractPattern:
+    normalized: str
+    _compiled: re.Pattern[str] = field(init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "_compiled", re.compile(python_regex(self.normalized)))
+
+    def matches(self, text: str) -> bool:
+        return self._compiled.search(text) is not None
+
+
+@cache
+def contract_pattern(normalized: str) -> ContractPattern:
+    """The compiled check of a normalised pattern, compiled once per process.
+
+    Raises `re.error` for a text that is not a normalised pattern."""
+    return ContractPattern(normalized)
+
+
+def python_regex(normalized: str) -> str:
+    """The `re` source of a normalised pattern."""
+    translated: list[str] = []
+    in_class = False
+    index = 0
+
+    while index < len(normalized):
+        char = normalized[index]
+
+        if char == "\\":
+            escape, index = _escape(normalized, index + 1)
+            translated.append(escape)
+            continue
+
+        if in_class:
+            in_class = char != "]"
+        elif char == "[":
+            in_class = True
+        else:
+            char = _ANCHORS.get(char, char)
+
+        translated.append(char)
+        index += 1
+
+    return "".join(translated)
+
+
+def _escape(normalized: str, index: int) -> tuple[str, int]:
+    """The escape starting after the backslash at `index - 1`, and the index after it."""
+    astral = _ASTRAL_ESCAPE.match(normalized, index)
+
+    if astral is not None:
+        return f"\\U{int(astral.group(1), 16):08X}", astral.end()
+
+    return "\\" + normalized[index : index + 1], index + 1

seampact/codegen/runtime/principal_members.py

@@ -0,0 +1,41 @@
+"""The members of an authenticated principal the boundary reads (ADR 0023 "Keys"): only those the principal schema
+declares, by wire name, as the wire writes them. The idempotency partition and a principal bucket key come from them,
+so two callers never share a key because their principal has no readable state."""
+
+from collections.abc import Mapping
+
+from seampact.codegen.runtime.contract import ApiContract
+from seampact.codegen.runtime.failures import BoundaryFailureError
+from seampact.codegen.runtime.ir_view import ir_map, ir_string
+from seampact.codegen.runtime.wire_codec import WireCodec
+
+
+def principal_members(
+    contract: ApiContract, operation_id: str, principal: object | None
+) -> Mapping[str, object] | None:
+    """Each declared member of the operation's principal by wire name, None for an anonymous caller.
+
+    Raises `BoundaryFailureError` for a principal that is not the generated principal type, or one whose schema
+    declares no member, since its callers could not be told apart."""
+    if principal is None:
+        return None
+
+    access = ir_map(contract.operation(operation_id), "access")
+    identity = ir_string(access, "identity") or ""
+    schema_id = ir_string(ir_map(contract.declaration("identities", identity), "principal"), "schema") or ""
+
+    if not contract.members.get(schema_id):
+        raise BoundaryFailureError(
+            f"seampact: the principal of identity '{identity}' declares no member, so its callers cannot be told "
+            "apart; declare one in its schema and regenerate the api."
+        )
+
+    members = WireCodec(contract).to_wire({"kind": "ref", "schema": schema_id}, principal)
+
+    if not isinstance(members, Mapping):
+        raise BoundaryFailureError(
+            f"seampact: the authenticate hook of identity '{identity}' returned a {type(principal).__qualname__}; "
+            f"return the generated principal type of '{schema_id}'."
+        )
+
+    return members

seampact/codegen/runtime/public_origin.py

@@ -0,0 +1,102 @@
+"""The origin absolute URLs start with (`api.wire.urls: absolute`): a scheme, a host and an optional port, from the
+app's configuration (FastAPI's `public_origin` argument, Django's `public_origin` setting). The request's `Host` and
+forwarded headers are never read. The boot check's item names the setting and the fix."""
+
+import re
+from typing import Final
+
+from seampact.codegen.runtime.contract import ApiContract
+from seampact.codegen.runtime.ir_view import ir_map, ir_string
+
+_ABSOLUTE_URLS: Final = "absolute"
+_SCHEMES: Final = ("http", "https")
+_SCHEME_SEPARATOR: Final = "://"
+_USER_INFO_SEPARATOR: Final = "@"
+_AUTHORITY_END: Final = re.compile(r"[/?#]")
+# What Java's `URI` reads as a server authority: a DNS name or IPv4 address, or a bracketed IPv6 address, then an
+# optional port of digits.
+_HOST_AND_PORT: Final = re.compile(
+    r"(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)*"
+    r"|\[[0-9A-Fa-f:.]+\])"
+    r"(?::(?P<port>[0-9]{1,5}))?"
+)
+_LOWEST_PORT: Final = 1
+_HIGHEST_PORT: Final = 65535
+_EXAMPLE: Final = "https://api.example.com"
+
+
+def writes_absolute_urls(contract: ApiContract) -> bool:
+    return ir_string(ir_map(ir_map(contract.ir_view, "api"), "wire"), "urls") == _ABSOLUTE_URLS
+
+
+def configured_origin(contract: ApiContract, configured: object) -> str | None:
+    """The configured origin under absolute URLs; None under relative ones, or when the boot check refuses it."""
+    if not writes_absolute_urls(contract) or not isinstance(configured, str) or _problem_of(configured) is not None:
+        return None
+
+    return configured
+
+
+def public_origin_problem(contract: ApiContract, setting: str, configured: object) -> str | None:
+    """The boot check's problem with the origin set in `setting`: one set under relative URLs, or a missing or invalid
+    one under absolute URLs."""
+    is_set = configured is not None and configured != ""
+
+    if not writes_absolute_urls(contract):
+        if not is_set:
+            return None
+
+        return (
+            f"the api '{contract.api}' writes relative URLs ('api.wire.urls: relative') and {setting} is set: remove "
+            "it, or set 'api.wire.urls: absolute' to write absolute URLs"
+        )
+
+    if not is_set:
+        return (
+            f"the api '{contract.api}' writes absolute URLs ('api.wire.urls: absolute') and {setting} is not set: set "
+            f"it to the origin clients call, such as {_EXAMPLE}"
+        )
+
+    problem = _problem_of(configured) if isinstance(configured, str) else "is not a string"
+
+    if problem is None:
+        return None
+
+    # The value is shown by its repr, so a line break or a control character never reaches the log line raw.
+    shown = repr(configured) if isinstance(configured, str) else type(configured).__qualname__
+
+    return (
+        f"{setting} is {shown}, which {problem}: set a scheme (http or https), a host and an optional port, such as "
+        f"{_EXAMPLE}"
+    )
+
+
+def _problem_of(configured: str) -> str | None:
+    scheme, separator, rest = configured.partition(_SCHEME_SEPARATOR)
+
+    if separator == "" or scheme not in _SCHEMES:
+        return "has no http or https scheme"
+
+    end = _AUTHORITY_END.search(rest)
+    authority = rest if end is None else rest[: end.start()]
+
+    if _USER_INFO_SEPARATOR in authority:
+        return "carries user info"
+
+    if authority != rest:
+        return "has a path, a query or a fragment (a trailing slash included)"
+
+    if authority == "":
+        return "has no host"
+
+    host_and_port = _HOST_AND_PORT.fullmatch(authority)
+
+    if host_and_port is None:
+        return "has a host that is not a DNS name, an IPv4 address or a bracketed IPv6 address, or an empty port"
+
+    port = host_and_port.group("port")
+
+    if port is not None and not _LOWEST_PORT <= int(port) <= _HIGHEST_PORT:
+        return f"has a port outside {_LOWEST_PORT}-{_HIGHEST_PORT}"
+
+    return None