Rust Server Framework
Relevant source files
The following files were used as context for generating this wiki page:
- crates/crucible-server-runtime-rust/src/service.rs
- crates/crucible-server-runtime-rust/src/host.rs
- crates/crucible-server-runtime-rust/src/operations.rs
- AGENTS.md
- crates/crucible-codegen-rust/src/names.rs
- crates/crucible-codegen-rust/tests/doc_links.rs
- crates/crucible-codegen-common/src/guide.rs
- crates/crucible-codegen-docs/src/markdown.rs
The Rust Server Framework provides the core runtime infrastructure for services defined in the .cru modeling language. It manages the request lifecycle through an orchestrator and a phased pipeline. The framework handles critical service concerns including protocol negotiation, input validation, error handling, and hosting for environments like HTTP or AWS Lambda.
Sources: AGENTS.md:1-5, AGENTS.md:52-54
Core Architecture and Phased Pipeline
The framework uses a phased pipeline to process incoming requests. The orchestrator coordinates these phases to ensure that security, validation, and protocol requirements are met before dispatching to specific operation handlers.
Orchestration and Dispatch
The framework isolates service logic from the underlying transport layer. A hosting layer (e.g., HTTP) receives raw requests and passes them to the orchestrator. The orchestrator identifies the target operation based on the Crucible IR description and manages the execution of middleware and interceptors.
The diagram shows the flow of a request from the hosting environment through the framework's internal components.
Sources: AGENTS.md:52-56, AGENTS.md:104-106
Framework Extension Interfaces
Developers extend the framework through predefined interfaces rather than modifying the core runtime. These interfaces allow for custom logic during the request/response lifecycle.
| Interface | Description |
|---|---|
Middleware | Transforms requests and responses for all operations. |
OperationAwareMiddleware | Provides context about the specific operation being invoked. |
Protocol | Defines how the model maps to wire formats (e.g., JSON). |
Interceptor | Hooks into specific points in the execution pipeline. |
TypedInterceptor | Intercepts requests and responses using generated types. |
LogSink | Receives and processes framework logs. |
Recorder | Captures metrics and execution traces. |
Sources: AGENTS.md:104-108
Modeling and Code Generation
The server runtime utilizes the full Crucible Intermediate Representation (IR). Code generation creates thin Rust bindings that link modeled shapes to the framework's traits.
Rust Naming Conventions
The framework enforces specific naming rules to ensure generated code is valid and idiomatic Rust.
- Fields and Functions: Converted to
snake_case. Reserved keywords (e.g.,type,match) are escaped asr#keyword. - Variants: Converted to
UpperCamelCase. - Intra-doc Links: The generator creates Rustdoc links that resolve to modeled types within the server module.
- Server Module: Unlike SDKs, the server module includes internal APIs and types to facilitate full service implementation.
Sources: crates/crucible-codegen-rust/src/names.rs:7-35, crates/crucible-codegen-rust/tests/doc_links.rs:43-45
Data Handling and Validation
The framework provides one-pass body readers and writers shared with client runtimes. It enforces constraints defined in the model, such as length, range, and patterns, before the request reaches the developer's handler.
Sources: AGENTS.md:57-59, crates/crucible-codegen-docs/src/markdown.rs:710-725
Versioning and Compatibility
The framework supports multiple API releases simultaneously. It uses a versioning header (e.g., Crucible-Version) to decide which model logic to apply to a request.
- Phased Pipeline: The runtime uses the header to select the appropriate versioned shapes.
- Sunset Documentation: The framework can be configured with sunset dates for older releases, allowing it to signal upcoming retirements.
- Internal API: The server audience maintains pending reasons and internal permissions that are stripped from external documentation.
Sources: crates/crucible-codegen-docs/src/markdown.rs:18-40, crates/crucible-codegen-docs/src/markdown.rs:1034-1050
Conclusion
The Rust Server Framework ensures consistency across Crucible-based services by centralizing orchestration and validation logic. By using trait-based extensions and automated codegen, it allows developers to focus on operation implementation while the runtime handles protocol adherence and security. Significance lies in its deterministic code generation and performance-oriented design, which minimizes per-request overhead through static descriptions.
Sources: AGENTS.md:95-108, AGENTS.md:120-125