orxtra v0.13.0 /services.src.orxtra.services._dispatcher
Updated
On this page

The single dispatch choke point: DispatchContext carries injectable infrastructure, and dispatch() authorizes, validates params, resolves injected dependencies, and calls the service function.

#services.src.orxtra.services._dispatcher

#services.src.orxtra.services._dispatcher

Generic capability dispatcher.

Routes raw dicts to the appropriate service function, validating parameters via the capability's params model and injecting infrastructure dependencies from the DispatchContext.

#DispatchContext

Infrastructure dependencies injected into dispatched calls.

#_resolve_caller_principal_arg

python
async def _resolve_caller_principal_arg(context: DispatchContext, cap: Capability) -> Principal

Resolve the caller_principal inject token to a persisted principal.

Requires BOTH context.auth_context and context.principal_storage; either missing is a hard error naming the capability and the missing dependency, matching the standard inject-resolution error shape. Resolution delegates to orxtra.identity.resolve_caller_principal.

#_resolve_injections

python
async def _resolve_injections(context: DispatchContext, cap: Capability) -> list[Any]

Resolve a capability's declared inject tokens to positional arguments.

Walks the canonical inject order, and for each token the capability declares, reads the matching field off the context. A declared token whose context field is None is a hard error naming the capability and the missing dependency -- never a silent None pass-through. The derived caller_principal token is resolved from the auth context and principal storage instead of a single context field. A declared token the dispatcher does not know how to route is also a hard error.

#dispatch

python
async def dispatch(context: DispatchContext, capability_name: str, raw_args: dict[str, Any]) -> Any

Dispatch a capability call.

  1. Looks up the capability by name
  2. Enforces authorization: the context must carry an auth_context whose

scopes include the capability's required_scope

  1. Validates raw_args via the capability's params_model
  2. Resolves the infrastructure dependencies the capability declares

(cap.injects) from the DispatchContext

  1. Calls the service function (declared infra first, positionally, then

the validated kwargs) and returns the result

Raises ValueError if the capability is unknown, the context lacks an auth_context, or a declared dependency is missing from the context. Raises orxtra.auth.AuthorizationError if the auth context lacks the capability's required scope. Raises pydantic.ValidationError if raw_args fail validation.

#_prepare_kwargs

python
def _prepare_kwargs(validated: Any) -> dict[str, Any]

Convert a validated params model instance to kwargs for the service function.

Handles type coercions that the service functions expect:

  • UUID string fields are converted to UUID objects
  • Path string fields are converted to Path objects
  • datetime string fields are converted to datetime objects
  • FilterPredicate dicts are converted to FilterPredicate objects
Search