loom.rest.compiler

RestInterface compiler.

Validates and compiles RestInterface declarations into CompiledRoute records at startup. No reflection or validation occurs after compilation.

Compilation steps per interface:

  1. Validate structural constraints (prefix, routes non-empty if auto=False).

  2. For each RestRoute: - Verify use_case has a compiled ExecutionPlan. - Resolve effective pagination mode (route → interface → global). - Resolve effective profile policy (route → interface → global).

  3. Detect and resolve (method, path) conflicts: custom routes win over duplicates. Raise InterfaceCompilationError on ambiguous conflicts within the same routes tuple.

  4. Validate expose_profile requires a non-empty allowed_profiles.

Classes

CompiledRoute(interface_name, route, ...[, ...])

Fully resolved route ready for transport binding.

RestInterfaceCompiler(use_case_compiler[, ...])

Compiles RestInterface declarations into CompiledRoute records.

Exceptions

InterfaceCompilationError

Raised when a RestInterface fails structural validation at startup.
exception loom.rest.compiler.InterfaceCompilationError[source]

Bases: Exception

Raised when a RestInterface fails structural validation at startup.

Parameters:

message – Human-readable description of the compilation failure.

Example:

raise InterfaceCompilationError(
    "UserRestInterface: duplicate route (GET, /{user_id})"
)
class loom.rest.compiler.CompiledRoute(interface_name, route, full_path, effective_pagination_mode, effective_profile_default, effective_allowed_profiles, effective_expose_profile, effective_allow_pagination_override, read_only=False, interface_tags=(), execute_param_types=())[source]

Bases: object

Fully resolved route ready for transport binding.

Produced by RestInterfaceCompiler for each valid route declaration. All policy fields are resolved — no further lookup is needed at request time.

Parameters:

  • interface_name (str) – Qualified name of the originating RestInterface.

  • route (RestRoute) – Original RestRoute declaration.

  • full_path (str) – Absolute HTTP path (interface.prefix + route.path).

  • effective_pagination_mode (PaginationMode) – Resolved pagination strategy after applying route → interface → global precedence.

  • effective_profile_default (str) – Resolved default profile name.

  • effective_allowed_profiles (tuple[str, ...]) – Resolved set of allowed profiles.

  • effective_expose_profile (bool) – Whether ?profile=... is publicly accepted for this route.

  • effective_allow_pagination_override (bool) – Whether callers may override pagination mode via query parameters for this route.

  • read_only (bool) – True for GET routes — instructs the executor to skip the UnitOfWork transaction for this request.

  • interface_tags (tuple[str, ...]) – OpenAPI tags inherited from the parent RestInterface.

  • execute_param_types (tuple[tuple[str, Any], ...])

class loom.rest.compiler.RestInterfaceCompiler(use_case_compiler, defaults=None, metrics=None)[source]

Bases: object

Compiles RestInterface declarations into CompiledRoute records.

Validates structure, resolves policies, and caches the result. Designed to run once at startup, driven by bootstrap_app() or the FastAPI composition root.

Parameters:

  • use_case_compiler (UseCaseCompiler) – Compiler that holds the cached ExecutionPlan registry.

  • defaults (RestApiDefaults | None) – Global REST API defaults applied when interface/route level is unset. Defaults to RestApiDefaults with offset pagination.

  • metrics (MetricsAdapter | None) – Optional metrics adapter. Reserved for future use (HTTP metrics are emitted at request time by the router runtime).

Example:

compiler = RestInterfaceCompiler(use_case_compiler)
routes = compiler.compile(UserRestInterface)
compile(interface)[source]

Compile interface and return the list of CompiledRoute.

Compilation is idempotent: repeated calls with the same class return the cached result.

Parameters:

interface (type[RestInterface[Any]]) – RestInterface subclass to compile.

Returns:

Ordered list of compiled routes ready for transport binding.

Raises:

InterfaceCompilationError – If the interface fails validation.

Return type:

list[CompiledRoute]