Framework Internals
This page is for framework authors and application integrators who extend the gateway. Read the architecture overview for system context and the request lifecycle for execution behavior.
Application Assembly
The YAML launcher parses a manifest into ProxyConfig. Python can supply that
configuration or explicit ProviderIntegration declarations. Both paths call
create_proxy_application and use the same route assembly and lifespan owners.
Construction validates declarations and routes. Lifespan startup creates network resources and preloads the Rails catalog. Requests then use those ready owners. Keeping these phases separate prevents request-time configuration loading and ensures initialization failures prevent readiness.
The following artifacts define application behavior and review coverage:
Guard-contract derivation runs from typed declarations to exported YAML. Editing an export does not change execution. Stateful hooks, arbitrary Python validation, and transport behavior require review beyond the export. Refer to guard contracts for the exact boundary.
Execution Dependencies
This dependency view is scoped to one gateway process. Rectangles are components or declarations; hexagons are internal callable or protocol interfaces. Solid arrows show invocation; dotted arrows describe declaration, protocol, and implementation dependencies. Interfaces describe dependencies, not extra runtime services.
The execution kernels receive a checker and dispatch callable instead of importing a provider implementation or constructing the Rails engine. Route assembly supplies those dependencies. Provider declarations carry the API semantics; reusable kernels control check outcomes and byte release. This lets tests exercise execution with deterministic checkers and dispatch functions.
The HTTP proxy layer uses ProviderTransport to adapt outbound requests and apply
forwarding and representation rules. The HTTPX transport performs the final
exchange. A custom HTTP transport does not select a new provider binding or Rails
policy after inspection.
Composition Hooks and Internal Interfaces
Distinguish documented application composition from the private interfaces used to implement it:
Use the Python integration guide for supported composition examples and the transport reference for streaming and cleanup requirements.
Trusted Rails Selection
This view shows per-request selection for declarative ProxyConfig providers
against a catalog that is already ready. Rectangles represent selection steps or
inputs; the diamond branches on application configuration. Solid arrows describe
selection. The
dotted arrow supplies the preloaded checker catalog. Authentication is
application-owned; receiving a request header does not make that value an
authorized policy choice.
YAML requires fixed per-provider IDs. ProxyConfig providers without fixed IDs
require a resolver, including with a one-entry catalog. Direct Python composition
can infer static selection from one entry when no resolver is supplied; an
explicit resolver still runs in direct mode. These assembly rules differ, while
request-time lookup uses the same preloaded repository.
The resolver receives the original buffered request and canonical operation identity. Its cooperative deadline defaults to five seconds, independently of provider HTTP deadlines. Async callbacks and sync callbacks returning awaitables are supported; a blocking synchronous callback cannot be preempted by this deadline. Cancellation must propagate without selecting a fallback configuration.
The callback owns authorization for its selection. Use trusted identity or deliberately populated application state rather than raw caller headers. The catalog contains trusted Rails directories and is fixed for a lifespan. Model routing remains independent of Rails selection. Refer to configuration resolution for examples and failure behavior.
State and Resource Ownership
The following scopes own declarations and runtime resources:
Classifiers describe events; hooks enforce stateful protocol behavior. Factories must return independent hook instances for each request. The stream binding encodes that boundary, and the provider composition tests check request-local state. Refer to streaming errors and cleanup for response ownership and cooperative cleanup limits.
Where to Make a Change
Use these implementation and test entry points for each change:
Keep changes aligned with the current content profiles. Follow Development for validation commands and release compatibility requirements.