rivet-core

rivet-core is the runtime kernel for rivet composition and dispatch.

Build Lifecycle Order

ApplicationBuilder::build() executes stages in a deterministic order:

1. Configure modules (RivetModule::configure).
2. Collect providers from modules.
3. Register all providers.
4. Boot all providers.
5. Collect routes from modules.
6. Collect middleware from modules.

If any stage fails, build stops immediately and later stages do not run.

Middleware Order Semantics

Middleware runs in registration order on the way in and reverse order on the way out.

Given middleware [A, B], execution order is:

1. A.before
2. B.before
3. terminal dispatch
4. B.after
5. A.after

A middleware can short-circuit by returning a response without calling next.

Build Failure Behavior

Build-time failures return RivetError with deterministic messages.

Primary categories are:

• configure/module failures
• provider register/boot failures
• route collection failures (including duplicates)

The builder is fail-fast and does not attempt partial recovery.

Dispatch Contract For Adapters

Adapters should treat Dispatcher::dispatch(Request) -> Response as the only dispatch boundary.

Current dispatch behavior:

• matched route: 200
• no route path match: 404
• path match + method mismatch: 405 with allow header
• HEAD falls back to GET and clears body when no explicit HEAD route exists

Adapter responsibilities remain transport-specific concerns such as timeout, panic boundaries, IO buffering, and protocol translation.

Observability

Core emits structured tracing events for build stages, route outcomes, middleware execution, and dispatch completion. Request body contents are intentionally not logged.

Examples

Run the minimal example:

cargo run -p rivet-core --example minimal_app

Run the modular provider example:

cargo run -p rivet-core --example modular_provider_app

modular_provider_app shows a module exposing a service provider that initializes a service in the container during build.

Run the Laravel-style builder example:

cargo run -p rivet-core --example laravel_style_app

laravel_style_app demonstrates the fluent bootstrap API: ApplicationBuilder::configure(..., config)->with_routing(...)->with_middleware(...)->with_exceptions(...)->with_schedule(...)->build().

The simplified API surface used by examples:

• Builder::with_defaults() for in-memory container/config bootstrapping.
• Application::make::<T>() for typed service resolution from the app container.
• ProviderFactory + with_providers(&[...]) for compile-time static provider registries.