Nidus

Nidus is a modular Rust backend framework for building explicit, production-ready services with typed dependency injection, module graphs, Axum routes, Tower middleware, validation, OpenAPI, observability, testing, and separately installable adapters. It composes Axum, Tower, Tokio, serde, tracing, garde, utoipa, SQLx adapters, cache adapters, and normal Cargo workflows instead of replacing them.

Install

Install the Nidus CLI from crates.io:

cargo install cargo-nidus
cargo nidus new hello-nidus
cd hello-nidus
cargo run

During local framework development, install the CLI from this checkout:

cargo install --path crates/cargo-nidus
cargo nidus new hello-nidus

Application dependencies stay explicit:

[dependencies]
nidus = { package = "nidus-rs", version = "1.0.16", features = ["http", "config", "openapi", "validation"] }

For production observability through the facade:

nidus = { package = "nidus-rs", version = "1.0.16", features = ["observability", "events", "jobs", "otel"] }

For embedded dashboard introspection:

nidus = { package = "nidus-rs", version = "1.0.16", features = ["dashboard"] }

Official integrations are separate crates:

nidus-sqlx = { version = "1.0.16", features = ["sqlite"] }
nidus-cache = { version = "1.0.16", features = ["moka"] }
nidus-redis = { version = "1.0.16", features = ["health"] }
nidus-kafka = { version = "1.0.16", features = ["health"] }
nidus-jobs-sqlx = { version = "1.0.16", features = ["postgres"] }
nidus-opentelemetry = "1.0.16"
nidus-sentry = "1.0.16"

Which Crate Do I Install?

• Use cargo-nidus for cargo nidus new, route inspection, graph inspection, and OpenAPI generation.
• Use nidus-rs as the application facade. Import it as nidus in Cargo.toml.
• Enable facade features such as http, config, openapi, validation, auth, events, jobs, observability, and otel only when the app needs them.
• Add only the data, messaging, durable-job, and telemetry adapter crates the application uses; the facade does not pull them transitively.
• Depend on lower-level crates such as nidus-core or nidus-http only when building framework extensions.

Common Imports And Extension Traits

Use the prelude at application entrypoints:

use nidus::prelude::*;

The prelude is the recommended import because it keeps common app composition types and extension traits in scope:

• NidusApplicationExt enables Nidus::create::<AppModule>().
• The facade builder supports .with_router(router) and .build_with_router(router) for composing manual Axum routes with module routes.
• ApplicationHttpExt remains available for lower-level Nidus::bootstrap::<AppModule>()?.with_router(router) composition.
• ApiDefaultsObservabilityExt enables .observability(&observability) and observability-aware API defaults when the observability feature is enabled.

Common Compile Errors

• no method named with_router after Nidus::bootstrap: import ApplicationHttpExt or nidus::prelude::*; after Nidus::create, call the builder's .with_router(router) before .build().await.
• no method named listen or no method named into_router: import NidusApplicationExt or nidus::prelude::*.
• no method named observability: import ApiDefaultsObservabilityExt or nidus::prelude::*.

Learning Path

1. Run cargo nidus new hello-nidus and start the generated server.
2. Inspect the generated module, controller, and service with cargo nidus routes and cargo nidus graph.
3. Add one feature controller or service with cargo nidus generate.
4. Add config, validation, or openapi when the first real route needs it.
5. Add nidus-sqlx or nidus-cache only after the application has a real persistence or cache boundary.

Quickstart

use nidus::prelude::*;

#[controller("/users")]
struct UsersController;

#[routes]
impl UsersController {
    #[get("/:id")]
    async fn find_one(&self, Path(id): Path<i64>) -> String {
        format!("user {id}")
    }
}

#[module]
struct AppModule {
    controllers: (UsersController,),
}

#[nidus::main]
async fn main() -> nidus::Result<()> {
    let app = Nidus::create::<AppModule>()
        .build_with_router(UsersController.into_router())
        .await?;

    app.listen("127.0.0.1:3000").await?;
    Ok(())
}

Core Concepts

• Modules: explicit imports, providers, controllers, and exports.
• Providers: Rust types registered by type, with singleton, transient, request-scoped, lazy, optional, and factory patterns.
• Controllers: Axum-backed route composition with Nidus route metadata.
• Guards and pipes: explicit authorization and validation boundaries.
• Config: typed configuration from JSON, files, pairs, and environment variables.
• OpenAPI: route metadata, schemas, and generated documents.
• Observability: additive production setup for HTTP metrics, traces, events, jobs, lifecycle validation, and official adapter operations.
• Dashboard: optional protected /nidus/dashboard runtime cockpit with Home, Atlas, Routes, Timeline, Adapters, Settings, JSON APIs, route snapshots, timeline storage, and SSE stream.
• Events and jobs: in-process event buses, sync/async queues, and observed runners.
• Testing: nidus_testing::TestApp for in-memory request tests and provider overrides.

Production Defaults

nidus-http provides opt-in production API defaults for request IDs, request context, health, readiness checks, metrics, CORS, body limits, timeout responses, security headers, structured logging, error envelopes, unmatched-route not_found fallbacks, and OpenTelemetry trace-context helpers. The defaults return normal Axum routers and Tower layers, so applications can replace or reorder the boundary.

Recommended production observability is additive:

use nidus::prelude::*;

let observability = Observability::production("users-api")
    .version(env!("CARGO_PKG_VERSION"))
    .environment("prod")
    .prometheus()
    .tracing()
    .otel_from_env();

let app = Nidus::create::<AppModule>()
    .with_observability(observability.clone())
    .build()
    .await?;

Automatic instrumentation applies where Nidus owns the integration point: HTTP middleware, ObservedEventBus, ObservedJobRunner, module validation, and official adapter builders. Raw SQLx queries, raw cache clients, ORMs, queues, and HTTP clients remain explicit application instrumentation.

Adapter Story

The nidus facade stays lean. Redis and SQLx data access, Kafka, NATS/JetStream, RabbitMQ, SQS, SQLx-backed durable jobs, OpenTelemetry, and Sentry live in separately installable crates. Each adapter exposes the native ecosystem client and composes with typed DI, lifecycle, health, observability, and dashboard events. Shared envelopes and correlation live in nidus-integrations; broker-specific semantics are not hidden behind a generic queue API. Delivery is documented as at-most-once or at-least-once where appropriate, never as universal exactly-once processing.

Examples

• examples/hello-world: minimal server.
• examples/openapi: OpenAPI JSON and docs routes.
• examples/production-api: production middleware defaults.
• examples/dashboard-api: embedded dashboard runtime cockpit with bearer or local-disabled auth, SQLite storage, metadata-only capture, route snapshots, Atlas graph, Timeline event/job filters, APIs, SSE, and live curl checks.
• examples/realworld-api: team tasks API with modules, SQLite, validation, OpenAPI, health, observability, request IDs, guards, CORS, limits, timeouts, events, and jobs.
• examples/sqlx-app and examples/cache-app: official adapter wiring.
• examples/integrations-production: runnable Redis, MySQL, CockroachDB, Kafka, NATS/JetStream, RabbitMQ, SQS, durable jobs, OpenTelemetry, and Sentry entrypoints.
• examples/external-support-desk: copyable external-user support desk API using crates.io-style dependencies, DI, ticket lifecycle routes, API-key auth, request IDs, validation errors, not-found behavior, and nidus-testing.
• examples/external-commerce: copyable external-user commerce API using crates.io-style dependencies, nidus-sqlx SQLite wiring, nidus-cache, products, carts, inventory, idempotent checkout, health/readiness, metrics, and nidus-testing.

Run an example:

cargo run -p nidus-example-realworld-api

The external-* examples are standalone Cargo packages with their own [workspace] tables. Verify them from their folders or with bash scripts/verify-external-examples.sh; they intentionally do not use local workspace path dependencies. While preparing an unpublished release, verify the same examples against temporary local patches:

NIDUS_EXTERNAL_EXAMPLES_LOCAL_PATCH=1 bash scripts/verify-external-examples.sh

That mode copies the external examples to a temp directory and appends temporary [patch.crates-io] entries there only. The checked-in examples stay copyable crates.io-style manifests.

Documentation

• Local Markdown docs: docs/
• Generated website source: website/
• GitHub Pages build: .github/workflows/pages.yml

Build and check the static website locally:

cd website
npm run verify

Release Status

Nidus 1.0.0 established the public crate set. The current release track is 1.0.16, hardening event and module lifecycles, reducing focused observability and configuration-path work, and tightening feature and safe-code boundaries while preserving the established 1.x public APIs.

Fuzzing

The fuzz/ package uses cargo-fuzz to compile deterministic fuzz targets for config parsing, route path normalization, and OpenAPI path normalization:

cargo +nightly fuzz build
cargo +nightly fuzz run route_paths

Use short local runs for development and CI compile checks for release hygiene.

Contributing

Read CONTRIBUTING.md. Changes should be small, tested, documented, and aligned with Rust ecosystem expectations.

License

Licensed under either MIT or Apache-2.0.