{"id":51354419,"url":"https://github.com/vicotrbb/nidus","last_synced_at":"2026-07-02T18:34:13.578Z","repository":{"id":368066784,"uuid":"1278329267","full_name":"vicotrbb/nidus","owner":"vicotrbb","description":"Nidus is a modular Rust application framework inspired by NestJS ergonomics and built on Rust-native explicitness, compile-time checks, Axum, Tower, and Tokio.","archived":false,"fork":false,"pushed_at":"2026-06-29T00:03:58.000Z","size":7250,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-29T00:05:14.868Z","etag":null,"topics":["axum","backend","dependency-injection","framework","rust","tokio","tower","web-framework"],"latest_commit_sha":null,"homepage":"https://vicotrbb.github.io/nidus/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vicotrbb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"vicotrbb"}},"created_at":"2026-06-23T17:29:10.000Z","updated_at":"2026-06-29T00:04:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vicotrbb/nidus","commit_stats":null,"previous_names":["vicotrbb/nidus"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/vicotrbb/nidus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicotrbb%2Fnidus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicotrbb%2Fnidus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicotrbb%2Fnidus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicotrbb%2Fnidus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vicotrbb","download_url":"https://codeload.github.com/vicotrbb/nidus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicotrbb%2Fnidus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35057511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["axum","backend","dependency-injection","framework","rust","tokio","tower","web-framework"],"created_at":"2026-07-02T18:34:13.087Z","updated_at":"2026-07-02T18:34:13.560Z","avatar_url":"https://github.com/vicotrbb.png","language":"Rust","funding_links":["https://github.com/sponsors/vicotrbb"],"categories":[],"sub_categories":[],"readme":"# Nidus\n\nNidus 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.\n\n## Install\n\nInstall the Nidus CLI from crates.io:\n\n```bash\ncargo install cargo-nidus\ncargo nidus new hello-nidus\ncd hello-nidus\ncargo run\n```\n\nDuring local framework development, install the CLI from this checkout:\n\n```bash\ncargo install --path crates/cargo-nidus\ncargo nidus new hello-nidus\n```\n\nApplication dependencies stay explicit:\n\n```toml\n[dependencies]\nnidus = { package = \"nidus-rs\", version = \"1.0.5\", features = [\"http\", \"config\", \"openapi\", \"validation\"] }\n```\n\nFor production observability through the facade:\n\n```toml\nnidus = { package = \"nidus-rs\", version = \"1.0.5\", features = [\"observability\", \"events\", \"jobs\", \"otel\"] }\n```\n\nFor embedded dashboard introspection:\n\n```toml\nnidus = { package = \"nidus-rs\", version = \"1.0.5\", features = [\"dashboard\"] }\n```\n\nOfficial integrations are separate crates:\n\n```toml\nnidus-sqlx = { version = \"1.0.5\", features = [\"sqlite\"] }\nnidus-cache = { version = \"1.0.5\", features = [\"moka\"] }\n```\n\n## Which Crate Do I Install?\n\n- Use `cargo-nidus` for `cargo nidus new`, route inspection, graph inspection, and OpenAPI generation.\n- Use `nidus-rs` as the application facade. Import it as `nidus` in `Cargo.toml`.\n- Enable facade features such as `http`, `config`, `openapi`, `validation`, `auth`, `events`, `jobs`, `observability`, and `otel` only when the app needs them.\n- Add `nidus-sqlx` or `nidus-cache` when choosing those official adapters.\n- Depend on lower-level crates such as `nidus-core` or `nidus-http` only when building framework extensions.\n\n## Common Imports And Extension Traits\n\nUse the prelude at application entrypoints:\n\n```rust\nuse nidus::prelude::*;\n```\n\nThe prelude is the recommended import because it keeps common app composition\ntypes and extension traits in scope:\n\n- `NidusApplicationExt` enables `Nidus::create::\u003cAppModule\u003e()`.\n- The facade builder supports `.with_router(router)` and\n  `.build_with_router(router)` for composing manual Axum routes with module\n  routes.\n- `ApplicationHttpExt` remains available for lower-level\n  `Nidus::bootstrap::\u003cAppModule\u003e()?.with_router(router)` composition.\n- `ApiDefaultsObservabilityExt` enables `.observability(\u0026observability)` and\n  observability-aware API defaults when the `observability` feature is enabled.\n\n## Common Compile Errors\n\n- `no method named with_router` after `Nidus::bootstrap`: import\n  `ApplicationHttpExt` or `nidus::prelude::*`; after `Nidus::create`, call the\n  builder's `.with_router(router)` before `.build().await`.\n- `no method named listen` or `no method named into_router`: import\n  `NidusApplicationExt` or `nidus::prelude::*`.\n- `no method named observability`: import `ApiDefaultsObservabilityExt` or\n  `nidus::prelude::*`.\n\n## Learning Path\n\n1. Run `cargo nidus new hello-nidus` and start the generated server.\n2. Inspect the generated module, controller, and service with `cargo nidus routes` and `cargo nidus graph`.\n3. Add one feature controller or service with `cargo nidus generate`.\n4. Add `config`, `validation`, or `openapi` when the first real route needs it.\n5. Add `nidus-sqlx` or `nidus-cache` only after the application has a real persistence or cache boundary.\n\n## Quickstart\n\n```rust\nuse nidus::prelude::*;\n\n#[controller(\"/users\")]\nstruct UsersController;\n\n#[routes]\nimpl UsersController {\n    #[get(\"/:id\")]\n    async fn find_one(\u0026self, Path(id): Path\u003ci64\u003e) -\u003e String {\n        format!(\"user {id}\")\n    }\n}\n\n#[module]\nstruct AppModule {\n    controllers: (UsersController,),\n}\n\n#[nidus::main]\nasync fn main() -\u003e nidus::Result\u003c()\u003e {\n    let app = Nidus::create::\u003cAppModule\u003e()\n        .build_with_router(UsersController.into_router())\n        .await?;\n\n    app.listen(\"127.0.0.1:3000\").await?;\n    Ok(())\n}\n```\n\n## Core Concepts\n\n- **Modules:** explicit imports, providers, controllers, and exports.\n- **Providers:** Rust types registered by type, with singleton, transient, request-scoped, lazy, optional, and factory patterns.\n- **Controllers:** Axum-backed route composition with Nidus route metadata.\n- **Guards and pipes:** explicit authorization and validation boundaries.\n- **Config:** typed configuration from JSON, files, pairs, and environment variables.\n- **OpenAPI:** route metadata, schemas, and generated documents.\n- **Observability:** additive production setup for HTTP metrics, traces, events, jobs, lifecycle validation, and official adapter operations.\n- **Dashboard:** optional protected `/nidus/dashboard` runtime cockpit with Home, Atlas, Routes, Timeline, Adapters, Settings, JSON APIs, route snapshots, timeline storage, and SSE stream.\n- **Events and jobs:** in-process event buses, sync/async queues, and observed runners.\n- **Testing:** `nidus_testing::TestApp` for in-memory request tests and provider overrides.\n\n## Production Defaults\n\n`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.\n\nRecommended production observability is additive:\n\n```rust\nuse nidus::prelude::*;\n\nlet observability = Observability::production(\"users-api\")\n    .version(env!(\"CARGO_PKG_VERSION\"))\n    .environment(\"prod\")\n    .prometheus()\n    .tracing()\n    .otel_from_env();\n\nlet app = Nidus::create::\u003cAppModule\u003e()\n    .with_observability(observability.clone())\n    .build()\n    .await?;\n```\n\nAutomatic instrumentation applies where Nidus owns the integration point:\nHTTP middleware, `ObservedEventBus`, `ObservedJobRunner`, module validation, and\nofficial adapter builders. Raw SQLx queries, raw cache clients, ORMs, queues,\nand HTTP clients remain explicit application instrumentation.\n\n## Adapter Story\n\nThe `nidus` facade stays lean. SQLx and cache integration live in `nidus-sqlx` and `nidus-cache`, with direct access to the underlying ecosystem clients. This keeps vendor dependencies out of core applications until they are explicitly installed.\n\n## Examples\n\n- `examples/hello-world`: minimal server.\n- `examples/openapi`: OpenAPI JSON and docs routes.\n- `examples/production-api`: production middleware defaults.\n- `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.\n- `examples/realworld-api`: team tasks API with modules, SQLite, validation, OpenAPI, health, observability, request IDs, guards, CORS, limits, timeouts, events, and jobs.\n- `examples/sqlx-app` and `examples/cache-app`: official adapter wiring.\n- `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`.\n- `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`.\n\nRun an example:\n\n```bash\ncargo run -p nidus-example-realworld-api\n```\n\nThe `external-*` examples are standalone Cargo packages with their own\n`[workspace]` tables. Verify them from their folders or with\n`bash scripts/verify-external-examples.sh`; they intentionally do not use local\nworkspace path dependencies. Before `1.0.5` is published to crates.io, verify\nthe same examples against temporary local patches:\n\n```bash\nNIDUS_EXTERNAL_EXAMPLES_LOCAL_PATCH=1 bash scripts/verify-external-examples.sh\n```\n\nThat mode copies the external examples to a temp directory and appends\ntemporary `[patch.crates-io]` entries there only. The checked-in examples stay\ncopyable crates.io-style manifests.\n\n## Documentation\n\n- Local Markdown docs: [docs/](docs/README.md)\n- Generated website source: [website/](website/)\n- GitHub Pages build: `.github/workflows/pages.yml`\n\nBuild and check the static website locally:\n\n```bash\ncd website\nnpm run verify\n```\n\n## Release Status\n\nNidus 1.0.0 established the public crate set. The current release track is 1.0.5, focused on the opt-in dashboard runtime cockpit, documentation alignment, example proof, and package verification across every publishable crate. Publishing still requires crates.io credentials and should be reported with exact evidence when it is not performed.\n\n## Fuzzing\n\nThe `fuzz/` package uses cargo-fuzz to compile deterministic fuzz targets for\nconfig parsing, route path normalization, and OpenAPI path normalization:\n\n```bash\ncargo +nightly fuzz build\ncargo +nightly fuzz run route_paths\n```\n\nUse short local runs for development and CI compile checks for release hygiene.\n\n## Contributing\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md). Changes should be small, tested, documented, and aligned with Rust ecosystem expectations.\n\n## License\n\nLicensed under either [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicotrbb%2Fnidus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvicotrbb%2Fnidus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicotrbb%2Fnidus/lists"}