routedef 0.1.0__py3-none-any.whl

routedef/__init__.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT
+
+from routedef.contracts import RouteDef, RouteHandler, RouteRequest, RouteResponse
+from routedef.errors import BadRequestBody, RouteConfigError
+from routedef.headers import get_header, normalize_headers
+from routedef.matching import CompiledPath, compile_path_template, expand_path_template, match_path
+from routedef.request import decode_json_body, decode_text_body, parse_query
+from routedef.response import response_body_kind, response_content_type, serialize_response_body
+from routedef.table import CompiledRoute, RouteMatch, RouteTable
+from routedef.types import JSONValue
+from routedef.version import __version__
+
+__all__ = (
+    "BadRequestBody",
+    "CompiledPath",
+    "CompiledRoute",
+    "JSONValue",
+    "RouteConfigError",
+    "RouteDef",
+    "RouteHandler",
+    "RouteMatch",
+    "RouteRequest",
+    "RouteResponse",
+    "RouteTable",
+    "__version__",
+    "compile_path_template",
+    "decode_json_body",
+    "decode_text_body",
+    "expand_path_template",
+    "get_header",
+    "match_path",
+    "normalize_headers",
+    "parse_query",
+    "response_body_kind",
+    "response_content_type",
+    "serialize_response_body",
+)

routedef/adapters/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT

routedef/adapters/cloudflare.py

@@ -0,0 +1,316 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable, Iterable, Mapping
+from importlib import import_module
+from typing import Generic, Protocol, SupportsBytes, TypeAlias, TypeVar, cast, runtime_checkable
+from urllib.parse import urlsplit
+
+from routedef.adapters.errors import AdapterError
+from routedef.contracts import RouteDef, RouteRequest, RouteResponse
+from routedef.errors import BadRequestBody
+from routedef.headers import get_header, normalize_headers
+from routedef.request import decode_json_body, decode_text_body, parse_query
+from routedef.response import serialize_response_body
+from routedef.table import RouteTable
+
+AuthT = TypeVar("AuthT")
+ContextT = TypeVar("ContextT")
+ValueT = TypeVar("ValueT")
+
+MaybeAwaitable: TypeAlias = Awaitable[ValueT] | ValueT
+ContextProvider = Callable[["CloudflareRequest"], MaybeAwaitable[ContextT]]
+AuthProvider = Callable[[RouteDef[AuthT, ContextT], "CloudflareRequest", ContextT], MaybeAwaitable[AuthT]]
+EnforcerResult = None | bool | RouteResponse
+Enforcer = Callable[[RouteDef[AuthT, ContextT], "CloudflareRequest", ContextT, AuthT], MaybeAwaitable[EnforcerResult]]
+ErrorHandler = Callable[[AdapterError, "CloudflareRequest"], MaybeAwaitable[RouteResponse]]
+ArrayBufferBody: TypeAlias = bytes | bytearray | memoryview
+ArrayBufferProxyBody: TypeAlias = ArrayBufferBody | Iterable[int] | SupportsBytes
+HeaderPair: TypeAlias = tuple[str, str]
+HeaderPairs: TypeAlias = Iterable[HeaderPair]
+ResponseFactory: TypeAlias = Callable[..., object]
+
+JSON_CONTENT_TYPE = "application/json"
+JSON_SUFFIX = "+json"
+TEXT_PREFIX = "text/"
+LOOKUP_HEADER_NAMES: tuple[str, ...] = (
+    "accept",
+    "accept-encoding",
+    "authorization",
+    "cache-control",
+    "content-length",
+    "content-type",
+    "cookie",
+    "host",
+    "if-match",
+    "if-modified-since",
+    "if-none-match",
+    "if-unmodified-since",
+    "referer",
+    "user-agent",
+    "x-forwarded-for",
+    "x-forwarded-host",
+    "x-forwarded-proto",
+    "x-real-ip",
+)
+__all__ = ("AdapterError", "CloudflareDispatcher", "CloudflareRequest")
+
+
+@runtime_checkable
+class HeaderItems(Protocol):
+    def items(self) -> HeaderPairs: ...
+
+
+@runtime_checkable
+class HeaderGetter(Protocol):
+    def get(self, name: str) -> str | None: ...
+
+
+@runtime_checkable
+class HeaderIndexer(Protocol):
+    def __getitem__(self, name: str) -> str: ...
+
+
+@runtime_checkable
+class ArrayBufferProxy(Protocol):
+    def to_py(self) -> ArrayBufferProxyBody: ...
+
+
+CloudflareHeaders: TypeAlias = Mapping[str, str] | HeaderPairs | HeaderItems | HeaderGetter | HeaderIndexer
+ArrayBufferResult: TypeAlias = ArrayBufferBody | ArrayBufferProxy
+
+
+class CloudflareRequest(Protocol):
+    method: str
+    url: str
+    headers: CloudflareHeaders
+
+
+@runtime_checkable
+class ArrayBufferRequest(CloudflareRequest, Protocol):
+    def arrayBuffer(self) -> Awaitable[ArrayBufferResult]: ...
+
+
+@runtime_checkable
+class TextRequest(CloudflareRequest, Protocol):
+    def text(self) -> Awaitable[str]: ...
+
+
+class CloudflareDispatcher(Generic[AuthT, ContextT]):
+    def __init__(
+        self,
+        route_table: RouteTable[AuthT, ContextT],
+        *,
+        context_provider: ContextProvider[ContextT] | None = None,
+        auth_provider: AuthProvider[AuthT, ContextT] | None = None,
+        enforcer: Enforcer[AuthT, ContextT] | None = None,
+        error_handler: ErrorHandler | None = None,
+        max_body_bytes: int | None = None,
+    ) -> None:
+        self._route_table = route_table
+        self._context_provider = context_provider
+        self._auth_provider = auth_provider
+        self._enforcer = enforcer
+        self._error_handler = error_handler
+        self._max_body_bytes = max_body_bytes
+
+    async def dispatch(self, request: CloudflareRequest) -> object:
+        url = urlsplit(request.url)
+        match = self._route_table.match(request.method, url.path)
+        if match is None:
+            return await self._error_response(AdapterError("not_found", 404, "not found"), request)
+
+        context: ContextT = await self._resolve_context(request)
+        auth: AuthT = await self._resolve_auth(match.route, request, context)
+        enforcement: EnforcerResult = await self._resolve_enforcement(match.route, request, context, auth)
+        if isinstance(enforcement, RouteResponse):
+            return _to_cloudflare_response(enforcement)
+        if enforcement is False:
+            return await self._error_response(AdapterError("forbidden", 403, "forbidden"), request)
+
+        try:
+            route_request = await _to_route_request(
+                request, match.route, match.path_params, context, auth, max_body_bytes=self._max_body_bytes
+            )
+        except _InvalidBody as exc:
+            return await self._error_response(AdapterError("bad_request", 400, str(exc)), request)
+        except _BodyTooLarge as exc:
+            return await self._error_response(AdapterError("body_too_large", 413, str(exc)), request)
+        try:
+            route_response = await match.route.handler(route_request)
+        except Exception as exc:
+            return await self._error_response(AdapterError("exception", 500, str(exc), exc), request)
+        return _to_cloudflare_response(route_response)
+
+    async def _resolve_context(self, request: CloudflareRequest) -> ContextT:
+        if self._context_provider is None:
+            return cast(ContextT, None)  # pragma: no mutate - cast is runtime-neutral.
+        return await _resolve(self._context_provider(request))
+
+    async def _resolve_auth(
+        self,
+        route: RouteDef[AuthT, ContextT],
+        request: CloudflareRequest,
+        context: ContextT,
+    ) -> AuthT:
+        if self._auth_provider is None:
+            return cast(AuthT, None)  # pragma: no mutate - cast is runtime-neutral.
+        return await _resolve(self._auth_provider(route, request, context))
+
+    async def _resolve_enforcement(
+        self,
+        route: RouteDef[AuthT, ContextT],
+        request: CloudflareRequest,
+        context: ContextT,
+        auth: AuthT,
+    ) -> EnforcerResult:
+        if self._enforcer is None:
+            return None
+        return await _resolve(self._enforcer(route, request, context, auth))
+
+    async def _error_response(self, error: AdapterError, request: CloudflareRequest) -> object:
+        if self._error_handler is None:
+            return _to_cloudflare_response(RouteResponse.json({"detail": error.message}, status=error.status))
+        return _to_cloudflare_response(await _resolve(self._error_handler(error, request)))
+
+
+async def _resolve(value: MaybeAwaitable[ValueT]) -> ValueT:
+    if inspect.isawaitable(value):
+        return await cast(Awaitable[ValueT], value)  # pragma: no mutate - cast is runtime-neutral.
+    return value
+
+
+async def _to_route_request(
+    request: CloudflareRequest,
+    route: RouteDef[AuthT, ContextT],
+    path_params: Mapping[str, str],
+    context: ContextT,
+    auth: AuthT,
+    *,
+    max_body_bytes: int | None,
+) -> RouteRequest[AuthT, ContextT]:
+    url = urlsplit(request.url)
+    headers = _normalize_cloudflare_headers(request.headers)
+    raw_body = await _read_raw_body(request)
+    if max_body_bytes is not None and len(raw_body) > max_body_bytes:
+        raise _BodyTooLarge("request body is too large")
+    try:
+        body = _decode_body(raw_body, headers)
+    except BadRequestBody as exc:
+        raise _InvalidBody(str(exc)) from exc
+
+    return RouteRequest(
+        method=request.method,
+        path=url.path,
+        route_path=route.path,
+        path_params=path_params,
+        query=parse_query(url.query),
+        headers=headers,
+        body=body,
+        raw_body=raw_body,
+        auth=auth,
+        context=context,
+    )
+
+
+def _normalize_cloudflare_headers(headers: CloudflareHeaders) -> Mapping[str, str]:
+    if isinstance(headers, Mapping):
+        return _normalize_mapping_headers(headers)  # pragma: no mutate - mapping behavior is covered via dispatch.
+    if isinstance(headers, HeaderItems):
+        return _normalize_header_pairs(headers.items())
+    if isinstance(headers, Iterable):
+        return _normalize_iterable_headers(headers)
+    return _normalize_lookup_headers(headers)
+
+
+def _normalize_mapping_headers(headers: CloudflareHeaders) -> Mapping[str, str]:
+    return normalize_headers(cast(Mapping[str, str], headers))  # pragma: no mutate - cast is runtime-neutral.
+
+
+def _normalize_iterable_headers(headers: CloudflareHeaders) -> Mapping[str, str]:
+    return _normalize_header_pairs(cast(HeaderPairs, headers))  # pragma: no mutate - cast is runtime-neutral.
+
+
+def _normalize_header_pairs(headers: HeaderPairs) -> Mapping[str, str]:
+    return {name.lower(): value for name, value in headers}
+
+
+def _normalize_lookup_headers(headers: HeaderGetter | HeaderIndexer) -> Mapping[str, str]:
+    normalized: dict[str, str] = {}
+    for name in LOOKUP_HEADER_NAMES:
+        value = _lookup_header(headers, name)
+        if value is not None:
+            normalized[name] = value
+    return normalized
+
+
+def _lookup_header(headers: HeaderGetter | HeaderIndexer, name: str) -> str | None:
+    if isinstance(headers, HeaderGetter):
+        value = headers.get(name)
+        if value is not None:
+            return value
+    if isinstance(headers, HeaderIndexer):
+        try:
+            return headers[name]
+        except (IndexError, KeyError, TypeError):
+            return None
+    return None
+
+
+async def _read_raw_body(request: CloudflareRequest) -> bytes:
+    if isinstance(request, ArrayBufferRequest):
+        return _array_buffer_to_bytes(await request.arrayBuffer())
+    if isinstance(request, TextRequest):
+        return (await request.text()).encode()
+    return b""
+
+
+def _array_buffer_to_bytes(body: ArrayBufferResult) -> bytes:
+    if isinstance(body, ArrayBufferProxy):
+        return bytes(body.to_py())
+    return bytes(body)
+
+
+def _decode_body(raw_body: bytes, headers: Mapping[str, str]) -> object | None:
+    if not raw_body:
+        return None
+    if _is_json_request(headers):
+        return decode_json_body(raw_body)
+    if _is_text_request(headers):
+        return decode_text_body(raw_body)
+    return None
+
+
+def _is_json_request(headers: Mapping[str, str]) -> bool:
+    media_type = _media_type(headers)
+    return media_type == JSON_CONTENT_TYPE or media_type.endswith(JSON_SUFFIX)
+
+
+def _is_text_request(headers: Mapping[str, str]) -> bool:
+    return _media_type(headers).startswith(TEXT_PREFIX)
+
+
+def _media_type(headers: Mapping[str, str]) -> str:
+    content_type = get_header(headers, "content-type") or ""  # pragma: no mutate
+    return content_type.partition(";")[0].strip().lower()
+
+
+def _to_cloudflare_response(response: RouteResponse) -> object:
+    workers = import_module("workers")
+    response_factory = cast(ResponseFactory, workers.Response)  # pragma: no mutate - cast is runtime-neutral.
+    return response_factory(
+        serialize_response_body(response),
+        status=response.status,
+        headers=dict(response.headers),
+    )
+
+
+class _InvalidBody(Exception):
+    pass
+
+
+class _BodyTooLarge(Exception):
+    pass

routedef/adapters/errors.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+AdapterErrorKind = Literal["not_found", "forbidden", "bad_request", "body_too_large", "exception"]
+
+
+@dataclass(frozen=True, slots=True)
+class AdapterError:
+    kind: AdapterErrorKind
+    status: int
+    message: str
+    exception: Exception | None = None

routedef/adapters/fastapi.py

@@ -0,0 +1,184 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable, Iterable, Mapping
+from typing import TypeAlias, TypeVar, cast
+
+from fastapi import APIRouter, Request, Response
+
+from routedef.adapters.errors import AdapterError
+from routedef.contracts import RouteDef, RouteRequest, RouteResponse
+from routedef.errors import BadRequestBody
+from routedef.headers import get_header
+from routedef.request import decode_json_body, parse_query
+from routedef.response import serialize_response_body
+from routedef.table import RouteTable
+
+AuthT = TypeVar("AuthT")
+ContextT = TypeVar("ContextT")
+ValueT = TypeVar("ValueT")
+
+MaybeAwaitable: TypeAlias = Awaitable[ValueT] | ValueT
+ContextProvider = Callable[[Request], MaybeAwaitable[ContextT]]
+AuthProvider = Callable[[RouteDef[AuthT, ContextT], Request, ContextT], MaybeAwaitable[AuthT]]
+EnforcerResult = None | bool | RouteResponse
+Enforcer = Callable[[RouteDef[AuthT, ContextT], Request, ContextT, AuthT], MaybeAwaitable[EnforcerResult]]
+ErrorHandler = Callable[[AdapterError, Request], MaybeAwaitable[RouteResponse]]
+
+JSON_CONTENT_TYPE = "application/json"
+JSON_SUFFIX = "+json"
+COMMON_METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD")
+__all__ = ("AdapterError", "build_fastapi_router")
+
+
+def build_fastapi_router(
+    routes: Iterable[RouteDef[AuthT, ContextT]],
+    *,
+    context_provider: ContextProvider[ContextT] | None = None,
+    auth_provider: AuthProvider[AuthT, ContextT] | None = None,
+    enforcer: Enforcer[AuthT, ContextT] | None = None,
+    error_handler: ErrorHandler | None = None,
+    max_body_bytes: int | None = None,
+) -> APIRouter:
+    route_table = RouteTable(routes)
+    router = APIRouter()
+
+    async def handle(request: Request) -> Response:
+        match = route_table.match(request.method, request.url.path)
+        if match is None:
+            return await _error_response(error_handler, AdapterError("not_found", 404, "not found"), request)
+
+        context: ContextT = await _resolve_context(context_provider, request)
+        auth: AuthT = await _resolve_auth(auth_provider, match.route, request, context)
+        enforcement: EnforcerResult = await _resolve_enforcement(enforcer, match.route, request, context, auth)
+        if isinstance(enforcement, RouteResponse):
+            return _to_fastapi_response(enforcement)
+        if enforcement is False:
+            return await _error_response(error_handler, AdapterError("forbidden", 403, "forbidden"), request)
+
+        try:
+            route_request = await _to_route_request(
+                request, match.route, match.path_params, context, auth, max_body_bytes=max_body_bytes
+            )
+        except _InvalidJSON as exc:
+            return await _error_response(error_handler, AdapterError("bad_request", 400, str(exc)), request)
+        except _BodyTooLarge as exc:
+            return await _error_response(error_handler, AdapterError("body_too_large", 413, str(exc)), request)
+        try:
+            route_response = await match.route.handler(route_request)
+        except Exception as exc:
+            return await _error_response(error_handler, AdapterError("exception", 500, str(exc), exc), request)
+        return _to_fastapi_response(route_response)
+
+    for route in route_table.routes:
+        router.add_api_route(route.route.path, handle, methods=[route.route.method])
+    if error_handler is not None:
+        router.add_api_route(
+            "/{routedef_path:path}",
+            handle,
+            methods=list(COMMON_METHODS),
+            include_in_schema=False,
+        )
+
+    return router
+
+
+async def _resolve_context(
+    context_provider: ContextProvider[ContextT] | None,
+    request: Request,
+) -> ContextT:
+    if context_provider is None:
+        return cast(ContextT, None)  # pragma: no mutate - cast is runtime-neutral.
+    return await _resolve(context_provider(request))
+
+
+async def _resolve_auth(
+    auth_provider: AuthProvider[AuthT, ContextT] | None,
+    route: RouteDef[AuthT, ContextT],
+    request: Request,
+    context: ContextT,
+) -> AuthT:
+    if auth_provider is None:
+        return cast(AuthT, None)  # pragma: no mutate - cast is runtime-neutral.
+    return await _resolve(auth_provider(route, request, context))
+
+
+async def _resolve_enforcement(
+    enforcer: Enforcer[AuthT, ContextT] | None,
+    route: RouteDef[AuthT, ContextT],
+    request: Request,
+    context: ContextT,
+    auth: AuthT,
+) -> EnforcerResult:
+    if enforcer is None:
+        return None
+    return await _resolve(enforcer(route, request, context, auth))
+
+
+async def _resolve(value: MaybeAwaitable[ValueT]) -> ValueT:
+    if inspect.isawaitable(value):
+        return await cast(Awaitable[ValueT], value)  # pragma: no mutate - cast is runtime-neutral.
+    return value
+
+
+async def _to_route_request(
+    request: Request,
+    route: RouteDef[AuthT, ContextT],
+    path_params: Mapping[str, str],
+    context: ContextT,
+    auth: AuthT,
+    *,
+    max_body_bytes: int | None,
+) -> RouteRequest[AuthT, ContextT]:
+    raw_body = await request.body()
+    if max_body_bytes is not None and len(raw_body) > max_body_bytes:
+        raise _BodyTooLarge("request body is too large")
+    try:
+        body = decode_json_body(raw_body) if raw_body and _is_json_request(request) else None
+    except BadRequestBody as exc:
+        raise _InvalidJSON(str(exc)) from exc
+
+    return RouteRequest(
+        method=request.method,
+        path=request.url.path,
+        route_path=route.path,
+        path_params=path_params,
+        query=parse_query(request.url.query),
+        headers=dict(request.headers),
+        body=body,
+        raw_body=raw_body,
+        auth=auth,
+        context=context,
+    )
+
+
+def _is_json_request(request: Request) -> bool:
+    content_type = get_header(dict(request.headers), "content-type") or ""  # pragma: no mutate
+    media_type = content_type.partition(";")[0].strip().lower()
+    return media_type == JSON_CONTENT_TYPE or media_type.endswith(JSON_SUFFIX)
+
+
+def _to_fastapi_response(response: RouteResponse) -> Response:
+    body = serialize_response_body(response)
+    return Response(
+        content=body,
+        status_code=response.status,
+        headers=dict(response.headers),
+    )
+
+
+async def _error_response(error_handler: ErrorHandler | None, error: AdapterError, request: Request) -> Response:
+    if error_handler is None:
+        return _to_fastapi_response(RouteResponse.json({"detail": error.message}, status=error.status))
+    return _to_fastapi_response(await _resolve(error_handler(error, request)))
+
+
+class _InvalidJSON(Exception):
+    pass
+
+
+class _BodyTooLarge(Exception):
+    pass

routedef/contracts.py

@@ -0,0 +1,165 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import builtins
+from collections.abc import Awaitable, Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Generic, Protocol, TypeVar, cast
+
+from routedef.errors import RouteConfigError
+from routedef.matching import expand_path_template
+from routedef.types import JSONValue
+
+AuthT = TypeVar("AuthT")
+ContextT = TypeVar("ContextT")
+ValueT = TypeVar("ValueT")
+
+
+def _normalize_method(method: str) -> str:
+    normalized = method.strip().upper()
+    if not normalized:
+        raise RouteConfigError("route method must not be empty")
+    return normalized
+
+
+def _validate_path(path: str) -> str:
+    if not path.strip():
+        raise RouteConfigError("route path must not be empty")
+    if not path.startswith("/"):
+        raise RouteConfigError("route path must start with '/'")
+    return path
+
+
+def _validate_name(name: str | None) -> str | None:
+    if name is not None and not name.strip():
+        raise RouteConfigError("route name must not be empty")
+    return name
+
+
+def _readonly_mapping(mapping: Mapping[str, ValueT]) -> Mapping[str, ValueT]:
+    snapshot: dict[str, ValueT] = {key: _typed_snapshot(value) for key, value in mapping.items()}
+    return MappingProxyType(snapshot)
+
+
+def _typed_snapshot(value: ValueT) -> ValueT:
+    return cast(ValueT, _deep_snapshot(value))  # pragma: no mutate - cast is runtime-neutral.
+
+
+def _deep_snapshot(value: object) -> object:
+    if isinstance(value, Mapping):
+        return MappingProxyType({key: _deep_snapshot(item) for key, item in value.items()})
+    if isinstance(value, list | tuple):
+        return tuple(_deep_snapshot(item) for item in value)
+    if isinstance(value, set | frozenset):
+        return frozenset(_deep_snapshot(item) for item in value)
+    return value
+
+
+def _body_snapshot(value: object) -> object:
+    if isinstance(value, Mapping):
+        return {key: _body_snapshot(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_body_snapshot(item) for item in value]
+    if isinstance(value, tuple):
+        return tuple(_body_snapshot(item) for item in value)
+    if isinstance(value, set | frozenset):
+        return frozenset(_body_snapshot(item) for item in value)
+    return value
+
+
+def _normalized_headers(headers: Mapping[str, str]) -> dict[str, str]:
+    return {name.lower(): value for name, value in headers.items()}
+
+
+def _headers_with_content_type(headers: Mapping[str, str], content_type: str | None) -> Mapping[str, str]:
+    normalized_headers = _normalized_headers(headers)
+    if content_type is not None and "content-type" not in normalized_headers:
+        header_name = "content-type"  # pragma: no mutate - response construction normalizes header keys.
+        normalized_headers[header_name] = content_type
+    return _readonly_mapping(normalized_headers)
+
+
+class RouteHandler(Protocol[AuthT, ContextT]):
+    def __call__(self, request: RouteRequest[AuthT, ContextT], /) -> Awaitable[RouteResponse]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class RouteDef(Generic[AuthT, ContextT]):
+    method: str
+    path: str
+    handler: RouteHandler[AuthT, ContextT]
+    metadata: Mapping[str, object] = field(default_factory=dict)
+    name: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "method", _normalize_method(self.method))
+        object.__setattr__(self, "path", _validate_path(self.path))
+        object.__setattr__(self, "metadata", _readonly_mapping(self.metadata))
+        object.__setattr__(self, "name", _validate_name(self.name))
+
+    def path_for(self, *, encode: bool = True, **path_params: object) -> str:
+        return expand_path_template(self.path, path_params, encode=encode)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RouteRequest(Generic[AuthT, ContextT]):
+    method: str
+    path: str
+    route_path: str
+    auth: AuthT
+    context: ContextT
+    path_params: Mapping[str, str] = field(default_factory=dict)
+    query: Mapping[str, str] = field(default_factory=dict)
+    headers: Mapping[str, str] = field(default_factory=dict)
+    body: object | None = None
+    raw_body: builtins.bytes = b""
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "method", _normalize_method(self.method))
+        object.__setattr__(self, "path", _validate_path(self.path))
+        object.__setattr__(self, "route_path", _validate_path(self.route_path))
+        object.__setattr__(self, "path_params", _readonly_mapping(self.path_params))
+        object.__setattr__(self, "query", _readonly_mapping(self.query))
+        object.__setattr__(self, "headers", _readonly_mapping(self.headers))
+        object.__setattr__(self, "body", _body_snapshot(self.body))
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RouteResponse:
+    status: int = 200
+    body: object | None = None
+    headers: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "body", _body_snapshot(self.body))
+        object.__setattr__(self, "headers", _readonly_mapping(_normalized_headers(self.headers)))
+
+    @classmethod
+    def json(cls, body: JSONValue, *, status: int = 200, headers: Mapping[str, str] | None = None) -> RouteResponse:
+        return cls(status=status, body=body, headers=_headers_with_content_type(headers or {}, "application/json"))
+
+    @classmethod
+    def text(cls, body: str, *, status: int = 200, headers: Mapping[str, str] | None = None) -> RouteResponse:
+        return cls(
+            status=status,
+            body=body,
+            headers=_headers_with_content_type(headers or {}, "text/plain; charset=utf-8"),
+        )
+
+    @classmethod
+    def bytes(
+        cls,
+        body: builtins.bytes,
+        *,
+        status: int = 200,
+        headers: Mapping[str, str] | None = None,
+        content_type: str = "application/octet-stream",
+    ) -> RouteResponse:
+        return cls(status=status, body=body, headers=_headers_with_content_type(headers or {}, content_type))
+
+    @classmethod
+    def empty(cls, status: int = 204, *, headers: Mapping[str, str] | None = None) -> RouteResponse:
+        return cls(status=status, body=None, headers=_headers_with_content_type(headers or {}, None))

routedef/errors.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT
+
+
+class RouteConfigError(ValueError):
+    """Raised when a route definition is invalid."""
+
+
+class BadRequestBody(ValueError):
+    """Raised when a request body cannot be decoded."""

routedef/headers.py

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT
+
+from collections.abc import Mapping
+
+
+def normalize_headers(headers: Mapping[str, str]) -> Mapping[str, str]:
+    return {name.lower(): value for name, value in headers.items()}
+
+
+def get_header(headers: Mapping[str, str], name: str) -> str | None:
+    normalized_name = name.lower()
+    for header_name, value in headers.items():
+        if header_name.lower() == normalized_name:
+            return value
+    return None

routedef/matching.py

@@ -0,0 +1,97 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from re import Pattern
+from urllib.parse import quote, unquote
+
+from routedef.errors import RouteConfigError
+
+_BRACE_PATTERN = re.compile(r"[{}]")
+_PLACEHOLDER_NAME_PATTERN = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
+
+
+@dataclass(frozen=True, slots=True)
+class CompiledPath:
+    path_template: str
+    pattern: Pattern[str]
+    param_names: tuple[str, ...]
+
+
+def compile_path_template(path_template: str) -> CompiledPath:
+    _validate_path_template(path_template)
+    pattern_parts = ["^"]
+    param_names: list[str] = []
+    position = 0
+
+    for brace_match in _BRACE_PATTERN.finditer(path_template):
+        brace_position = brace_match.start()
+        if brace_position < position:
+            continue
+        if brace_match.group() == "}":  # pragma: no mutate - alternate path raises the same config error.
+            raise RouteConfigError("route path placeholder name is invalid")
+
+        pattern_parts.append(re.escape(path_template[position:brace_position]))
+        placeholder_end = path_template.find("}", brace_position + 1)  # pragma: no mutate - equivalent search start.
+        if placeholder_end == -1:
+            raise RouteConfigError("route path placeholder name is invalid")
+
+        placeholder_name = path_template[brace_position + 1 : placeholder_end]
+        _validate_placeholder_name(placeholder_name)
+        if placeholder_name in param_names:
+            raise RouteConfigError(f"route path placeholder {placeholder_name!r} is duplicated")
+
+        param_names.append(placeholder_name)
+        pattern_parts.append(f"(?P<{placeholder_name}>[^/]+)")
+        position = placeholder_end + 1
+
+    pattern_parts.append(re.escape(path_template[position:]))
+    pattern_parts.append("$")
+    return CompiledPath(
+        path_template=path_template, pattern=re.compile("".join(pattern_parts)), param_names=tuple(param_names)
+    )
+
+
+def match_path(compiled_path: CompiledPath, path: str) -> dict[str, str] | None:
+    match = compiled_path.pattern.fullmatch(path)
+    if match is None:
+        return None
+    return {name: unquote(match.group(name)) for name in compiled_path.param_names}
+
+
+def expand_path_template(path_template: str, path_params: Mapping[str, object], *, encode: bool = True) -> str:
+    compiled_path = compile_path_template(path_template)
+    expected = set(compiled_path.param_names)
+    provided = set(path_params)
+    missing = expected - provided
+    if missing:
+        raise RouteConfigError(f"missing path params: {', '.join(sorted(missing))}")
+    unknown = provided - expected
+    if unknown:
+        raise RouteConfigError(f"unknown path params: {', '.join(sorted(unknown))}")
+
+    expanded = path_template
+    for name in compiled_path.param_names:
+        value = str(path_params[name])
+        if encode:
+            value = quote(value, safe="")  # pragma: no mutate - alphanumeric safe mutations are equivalent.
+        elif "/" in value:
+            raise RouteConfigError(f"path param {name!r} must not contain '/'")
+        expanded = expanded.replace(f"{{{name}}}", value)
+    return expanded
+
+
+def _validate_path_template(path_template: str) -> None:
+    if not path_template.strip():
+        raise RouteConfigError("route path must not be empty")
+    if not path_template.startswith("/"):
+        raise RouteConfigError("route path must start with '/'")
+
+
+def _validate_placeholder_name(placeholder_name: str) -> None:
+    if _PLACEHOLDER_NAME_PATTERN.fullmatch(placeholder_name) is None:
+        raise RouteConfigError("route path placeholder name is invalid")

routedef/py.typed

@@ -0,0 +1 @@
+

routedef/request.py

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT
+
+import json
+from collections.abc import Mapping
+from typing import Final, cast
+from urllib.parse import parse_qsl
+
+from routedef.errors import BadRequestBody
+from routedef.types import JSONValue
+
+DEFAULT_TEXT_ENCODING: Final = "utf-8"  # pragma: no mutate - UTF-8 aliases are equivalent.
+
+
+def parse_query(query_string: str | bytes) -> Mapping[str, str]:
+    query_text = query_string.decode() if isinstance(query_string, bytes) else query_string
+    return dict(parse_qsl(query_text, keep_blank_values=True))
+
+
+def decode_json_body(raw_body: bytes) -> JSONValue:
+    try:
+        return cast(JSONValue, json.loads(raw_body))  # pragma: no mutate - cast is runtime-neutral.
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise BadRequestBody("request body is not valid JSON") from exc
+
+
+def decode_text_body(raw_body: bytes, encoding: str = DEFAULT_TEXT_ENCODING) -> str:
+    try:
+        return raw_body.decode(encoding)
+    except UnicodeDecodeError as exc:
+        raise BadRequestBody("request body is not valid text") from exc

routedef/response.py

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT
+
+import json
+from typing import Final, Literal, cast
+
+from routedef.contracts import RouteResponse
+from routedef.headers import get_header
+
+ResponseBodyKind = Literal["empty", "bytes", "text", "json"]
+CONTENT_TYPE_HEADER: Final = "content-type"  # pragma: no mutate - header lookup is case-insensitive.
+
+
+def response_body_kind(response: RouteResponse) -> ResponseBodyKind:
+    if response.status == 204 or response.body is None:
+        return "empty"
+    if isinstance(response.body, bytes):
+        return "bytes"
+    if isinstance(response.body, str):
+        return "text"
+    return "json"
+
+
+def serialize_response_body(response: RouteResponse) -> bytes:
+    body_kind = response_body_kind(response)
+    if body_kind == "empty":
+        return b""
+    if body_kind == "bytes":
+        return cast(bytes, response.body)  # pragma: no mutate - cast is runtime-neutral.
+    if body_kind == "text":
+        return cast(str, response.body).encode()  # pragma: no mutate - cast is runtime-neutral.
+    return json.dumps(response.body, separators=(",", ":")).encode()
+
+
+def response_content_type(response: RouteResponse) -> str | None:
+    return get_header(response.headers, CONTENT_TYPE_HEADER)

routedef/table.py

@@ -0,0 +1,73 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Generic, TypeVar
+
+from routedef.contracts import RouteDef
+from routedef.errors import RouteConfigError
+from routedef.matching import CompiledPath, compile_path_template, match_path
+
+AuthT = TypeVar("AuthT")
+ContextT = TypeVar("ContextT")
+
+
+@dataclass(frozen=True, slots=True)
+class CompiledRoute(Generic[AuthT, ContextT]):
+    route: RouteDef[AuthT, ContextT]
+    compiled_path: CompiledPath
+
+
+@dataclass(frozen=True, slots=True)
+class RouteMatch(Generic[AuthT, ContextT]):
+    route: RouteDef[AuthT, ContextT]
+    path_params: Mapping[str, str]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "path_params", MappingProxyType(dict(self.path_params)))
+
+
+@dataclass(frozen=True, slots=True)
+class RouteTable(Generic[AuthT, ContextT]):
+    routes: tuple[CompiledRoute[AuthT, ContextT], ...]
+
+    def __init__(self, routes: Iterable[RouteDef[AuthT, ContextT]]) -> None:
+        compiled_routes: list[CompiledRoute[AuthT, ContextT]] = []
+        seen_routes: set[tuple[str, str]] = set()
+        seen_names: set[str] = set()
+
+        for route in routes:
+            route_key = (route.method, route.path)
+            if route_key in seen_routes:
+                raise RouteConfigError(f"route table contains duplicate route {route.method} {route.path}")
+            seen_routes.add(route_key)
+            if route.name is not None:
+                if route.name in seen_names:
+                    raise RouteConfigError(f"route table contains duplicate route name {route.name!r}")
+                seen_names.add(route.name)
+            compiled_routes.append(CompiledRoute(route=route, compiled_path=compile_path_template(route.path)))
+
+        object.__setattr__(self, "routes", tuple(compiled_routes))
+
+    def match(self, method: str, path: str) -> RouteMatch[AuthT, ContextT] | None:
+        normalized_method = _normalize_method(method)
+        for compiled_route in self.routes:
+            if compiled_route.route.method != normalized_method:
+                continue
+
+            path_params = match_path(compiled_route.compiled_path, path)
+            if path_params is not None:
+                return RouteMatch(route=compiled_route.route, path_params=path_params)
+
+        return None
+
+
+def _normalize_method(method: str) -> str:
+    normalized = method.strip().upper()
+    if not normalized:
+        raise RouteConfigError("route method must not be empty")
+    return normalized

routedef/types.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT
+
+from collections.abc import Mapping
+from typing import TypeAlias
+
+JSONValue: TypeAlias = (
+    None | bool | int | float | str | list["JSONValue"] | tuple["JSONValue", ...] | Mapping[str, "JSONValue"]
+)

routedef/version.py

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 provide.io llc
+# SPDX-License-Identifier: MIT
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _metadata_version
+from pathlib import Path
+from typing import Final
+
+_PACKAGE_NAME: Final = "routedef"
+_FALLBACK_VERSION: Final = "0.1.0"
+_VERSION_FILE: Final = Path(__file__).resolve().parents[2] / "VERSION"
+
+
+def load_version() -> str:
+    try:
+        return _metadata_version(_PACKAGE_NAME)
+    except PackageNotFoundError:
+        if not _VERSION_FILE.exists():
+            return _FALLBACK_VERSION
+        return _VERSION_FILE.read_text(encoding="utf-8").strip()  # pragma: no mutate - UTF-8 aliases equivalent.
+
+
+__version__ = load_version()

routedef-0.1.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: routedef
+Version: 0.1.0
+Summary: Route definition primitives for Python services.
+Project-URL: Homepage, https://github.com/provide-io/routedef
+Project-URL: Repository, https://github.com/provide-io/routedef
+Project-URL: Documentation, https://github.com/provide-io/routedef/blob/main/docs/architecture.md
+Project-URL: Issues, https://github.com/provide-io/routedef/issues
+Author: provide.io llc
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.116.0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# RouteDef 🧭
+
+Runtime-neutral route definitions for Python services.
+
+`routedef` gives applications one route contract that can be mounted into multiple runtimes. The core package has
+no FastAPI, Cloudflare, ASGI, auth, database, or application dependency. Runtime-specific code lives in adapters.
+
+## What It Provides ✅
+
+- `RouteDef`: method, path template, handler, and metadata.
+- `RouteRequest`: canonical request object for handlers.
+- `RouteResponse`: canonical response object for handlers.
+- `RouteTable`: ordered method/path matching with `{path_param}` extraction.
+- `build_fastapi_router`: FastAPI router integration.
+- `CloudflareDispatcher`: direct Cloudflare Python Workers integration.
+
+## Why Use It 🎯
+
+Use `RouteDef` when you need the same route definitions to work across more than one Python runtime, especially
+when migrating between framework-hosted APIs and Cloudflare Python Workers.
+
+- One handler contract instead of per-runtime handler shapes.
+- App-owned auth and authorization through metadata, auth providers, and enforcers.
+- Dependency-free core package with optional runtime adapters.
+- Testable route behavior without starting a web server.
+- Migration-friendly wrappers for legacy split-argument handlers.
+
+## Why Not 🚧
+
+Do not use `RouteDef` as a full web framework, ORM, dependency injection container, auth library, or request
+validation system. It intentionally does not own app policy, storage, schemas, background jobs, or runtime
+lifecycle. If a service will only ever run in one framework and already has a stable route layer, the adapter
+boundary may not be worth adding.
+
+## Architecture 🏗️
+
+![routedef request flow](https://raw.githubusercontent.com/provide-io/routedef/main/docs/diagrams/routedef-flow.svg)
+
+![routedef package boundaries](https://raw.githubusercontent.com/provide-io/routedef/main/docs/diagrams/runtime-adapters.svg)
+
+See [docs/architecture.md](https://github.com/provide-io/routedef/blob/main/docs/architecture.md) for package
+boundaries and [docs/migration.md](https://github.com/provide-io/routedef/blob/main/docs/migration.md) for migration
+examples covering undef-style roles, admin authorization callbacks, Taybols JWT auth, and uwarp split-argument
+handlers.
+
+## Basic Usage 🚀
+
+```python
+from routedef import RouteDef, RouteRequest, RouteResponse, RouteTable
+
+
+async def get_item(request: RouteRequest[None, dict[str, object]]) -> RouteResponse:
+    return RouteResponse.json({"id": request.path_params["id"]})
+
+
+routes = RouteTable([RouteDef("GET", "/v1/items/{id}", get_item)])
+```
+
+## FastAPI
+
+```python
+from fastapi import FastAPI
+from routedef.adapters.fastapi import build_fastapi_router
+
+app = FastAPI()
+app.include_router(build_fastapi_router(routes))
+```
+
+## Cloudflare Python Workers
+
+```python
+from routedef.adapters.cloudflare import CloudflareDispatcher
+from workers import WorkerEntrypoint
+
+dispatcher = CloudflareDispatcher(routes)
+
+
+class Default(WorkerEntrypoint):
+    async def fetch(self, request):
+        return await dispatcher.dispatch(request)
+```
+
+A real local Cloudflare fixture lives in
+[examples/cloudflare-worker](https://github.com/provide-io/routedef/blob/main/examples/cloudflare-worker). Run it with:
+
+```bash
+uv run python scripts/check_cloudflare_worker.py
+```
+
+The integration script vendors the local `src/routedef` package into a temporary Python Worker project, runs
+`pywrangler sync`, starts `wrangler@latest dev`, and probes routes over HTTP.
+
+## Quality Gates 🧪
+
+```bash
+uv run pre-commit run --all-files
+uv run pytest -q --cov=src/routedef --cov-branch --cov-report=term-missing --cov-fail-under=100
+uv run pre-commit run mutation-sweep --hook-stage manual
+uv run pre-commit run cloudflare-worker-integration --hook-stage manual
+```
+
+The project requires 100% branch coverage, strict typing, security/dead-code/complexity checks, REUSE compliance,
+max-LOC checks, mutation testing, and a Cloudflare Worker runtime integration gate.

routedef-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+routedef/__init__.py,sha256=cw0wrUBBJm-wnc7Tga-2_aVGboGFRf7IVkff1Ye_RMQ,1234
+routedef/contracts.py,sha256=081x0i0aSnZKjc_IZOQ4B4pCymZ_oWyKs2NvIysUd40,6362
+routedef/errors.py,sha256=TJHDFSy5zTDN_mgUEFCEXh-078QrKl3BWJPpZBNuLrw,274
+routedef/headers.py,sha256=faj1VwlX5sZ9sNTn-plraYytv3qZ-xCtnVlsmvmQuvk,515
+routedef/matching.py,sha256=r5QndyzTn9OegK0W4FR-FlzBGjKrPun7IrnXF_C53Xs,3740
+routedef/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+routedef/request.py,sha256=trrM_ykUKFOlD4lPAkbB_PkFKELoEcFOp1FPyjpllOQ,1147
+routedef/response.py,sha256=k0Dyf0UJtDU5SeOZpC6UQp3WttUIuAHyWk23cKDVYYY,1287
+routedef/table.py,sha256=VoDBSu-_dl1JEDqKOWEFXH0Ww29A9sZdbORFqRYHfmg,2673
+routedef/types.py,sha256=F1BY4waHkpGZ4vvtFayyq9J1ZXM1EpG3HpaqB77P_d0,295
+routedef/version.py,sha256=SGrMNmVzFdfS5OueS96awHV92QpUwWAD6QFyfknzdgk,735
+routedef/adapters/__init__.py,sha256=AfTpA_a8cTuYHTE9chFero4BXkqswCVK4rlm8AbEdiA,91
+routedef/adapters/cloudflare.py,sha256=0JytHp_bvA75Bn355aj7codhrocIw-YwgJedix3AIfM,11191
+routedef/adapters/errors.py,sha256=VveydsrKsHdJWX4Wk78mkz2uf6r1_OWus5lHuRk4T00,446
+routedef/adapters/fastapi.py,sha256=ghK03xWhIMYpyIKvqG2m7TK2T4jTj0LMeVqOe97PZzc,6741
+routedef-0.1.0.dist-info/METADATA,sha256=t3J1GWFkhe_HCAAoawSto_Edh1AA7RLWiyRFDsDKRgc,4578
+routedef-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+routedef-0.1.0.dist-info/licenses/LICENSE,sha256=IBrM7Cb7nvl0Ll4FXN98teG1rrsSxLGucsADvbqf050,1071
+routedef-0.1.0.dist-info/RECORD,,

routedef-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

routedef-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 provide.io llc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.