Middlewares & Interceptors
Relevant source files
The following files were used as context for generating this wiki page:
Middlewares and interceptors provide extensibility points within the Crucible framework's phased request pipeline. They allow developers to inject custom logic into the request-response lifecycle for tasks such as logging, authentication, and telemetry without modifying the core framework code.
The framework orchestrates these extensions through specific interfaces. Middlewares typically handle request transformations or side effects like logging, while interceptors can observe or modify the execution of operations.
Sources: AGENTS.md:73-77, crates/crucible-server-runtime-rust/src/middleware.rs
System Architecture
The Crucible framework utilizes a phased pipeline to process requests. Extensions hook into this pipeline via traits defined in the Rust server runtime.
The diagram shows the logical flow of a request through the middleware and interceptor layers before reaching the core operation logic.
Sources: AGENTS.md:73-77, crates/crucible-server-runtime-rust/src/middleware.rs
Extension Types
Crucible distinguishes between general-purpose extensions and those aware of specific operation metadata.
Middlewares
Middlewares process every request and response passing through the server. They are defined by the Middleware and OperationAwareMiddleware traits. Typical implementations include ServiceLog, which handles request/response logging and error reporting.
Interceptors
Interceptors focus on the execution boundary of operations. The framework supports both generic Interceptor and TypedInterceptor variants. These allow for more granular control or observation of the data passed into and out of service operations.
| Extension Interface | Description |
|---|---|
Middleware | Basic request/response transformation layer. |
OperationAwareMiddleware | Middleware with access to operation-specific IR metadata. |
Interceptor | Logic that wraps the execution of an operation. |
TypedInterceptor | Interceptors acting on typed input/output models. |
Sources: AGENTS.md:73-77, crates/crucible-server-runtime-rust/src/middlewares/service_log.rs
Implementation Examples
Service Logging Middleware
The ServiceLog middleware records telemetry and operational data. It interacts with the LogSink and Recorder interfaces to persist or transmit logs.
// Example structure of a service log middleware
pub struct ServiceLog<S, R> {
sink: S,
recorder: R,
}
Sources: crates/crucible-server-runtime-rust/src/middlewares/service_log.rs:1-10
Client-Side Hooks
In generated clients, such as the Go and R clients, similar concepts are implemented as configuration options to allow callers to inject behavior.
- Go Client: Uses
TelemetryHookto process events likeOperationStartedEventandAttemptFinishedEvent. - R Client: Supports
middlewareinclient_configfor request transformations applied on every attempt.
Sources: crates/crucible-codegen-go/src/lib.rs:248-261, crates/crucible-codegen-r/src/lib.rs:431-440
Execution Flow
When a client initiates a call, the framework executes middlewares and interceptors in a specific sequence.
The sequence diagram illustrates how middlewares wrap interceptors, which in turn wrap the operation execution.
Sources: AGENTS.md:38-42, crates/crucible-codegen-go/src/lib.rs:248-261
Conclusion
Middlewares and Interceptors are the primary mechanisms for extending the Crucible framework. By utilizing interfaces like Middleware, OperationAwareMiddleware, and Interceptor, developers can implement cross-cutting concerns such as security, observability, and custom protocol handling while maintaining a clean separation from the core service logic.