Documentation
Everything Navree does, from installing the CLI to queues, real time and testing. New here? Start with the introduction, then build your first app.
Prologue
- IntroductionWhat Navree is, who it's for, what comes in the box, and how it compares with Laravel, NestJS, Loco and Axum.
- Release notesNavree 0.1.0, the first release: what each module ships, the CLI, the reference CRM and the benchmark, and the known limitations you may run into.
- RoadmapWhat was deliberately left out of Navree 0.1, and the performance work the benchmark identified. No dates, no promises.
- ContributingHow the Navree repository is laid out, the crate-layer rule and the test that enforces it, running the tests, code style, and contributing to these docs.
Getting started
- InstallationInstall Rust and the
navreeCLI, create an app withnavree new, and run it withnavree dev. - Your first appBuild a small task-list API with an entity, a migration, validation, JWT authentication, access rules and feature tests, from
navree newto green tests. - ConfigurationTyped configuration from
.env,config/app.tomlandAPP_*environment variables: precedence, nesting, the application key and your own sections. - Directory structureWhat every file of a new Navree app is for, where generated code goes, and how the framework's own repository is laid out.
- DeploymentBuild a release binary, configure it through the environment, run the server, queue workers and the scheduler under a process manager, and put it behind a reverse proxy.
Architecture concepts
- Request lifecycleWhat happens from
cargo run -- serveto a response: the boot, every global layer in order, the route pipeline, the handler and the way back out. - ModulesHow an app is composed from modules that declare imports, providers, controllers and exports, and how the module graph is checked at boot.
- Providers and dependency injectionThe type-keyed container:
#[injectable]services, singleton, request and transient scopes, lazy handles, multi-bindings and overrides for tests. - Lifecycle hooksRun code when the app boots and when it shuts down:
on_init,on_bootstrap,on_shutdown, background tasks and graceful shutdown. - The crate hierarchyThe layers of Navree crates, the rule that a crate depends only on the layers below it, the shared contracts that make that possible, and the test that enforces it.
- The facade and featuresThe
navreecrate: one dependency that re-exports every module, a prelude, one Cargo feature per module (fullby default), and using a single crate on its own.
The basics
- Routing and controllersControllers and route attributes, the API prefix and versions, absolute
!paths, path and query parameters, route names and the route table. - Access control on routesDeny by default: every route declares who may call it with
#[public],#[authenticated],#[roles],#[permissions]or#[can], and refusals map to 401, 403 or 404. - The request pipeline and middlewareThe global Tower layers Navree installs and their order, adding your own layers in the pipeline's slots, guards, per-route settings and layers on a single route.
- Requests and extractorsReading paths, query strings, JSON and other bodies, headers, the request id, the client IP behind trusted proxies, the current user, and body limits; writing your own extractor.
- ValidationValidate request bodies and query strings with
Valid<Json<T>>on garde, with class-validator style messages andunique/existsdatabase rules. - Responses and API resourcesReturn JSON, status codes and headers from handlers, shape entities into API resources, and send pages, downloads and streams.
- ErrorsThe NestJS error format,
AppError, mapping your own and database errors to statuses, and how 5xx errors and panics are logged. - LoggingStructured logging on tracing: levels per target, pretty or JSON output, redaction of secrets, rotating files and the per-request log line.
- Rate limitingThe per-IP limit every app gets, throttles on single routes, the login throttle, and how client addresses work behind proxies.
- CORS and security headersAllow browser front ends on other origins with exact-origin CORS, and the security headers Navree sends on every response.
- Sessions and CSRFThe optional session module: encrypted session cookies, memory and database stores, CSRF protection for cookie clients, and when to use it instead of bearer tokens.
Security
- AuthenticationJWT access tokens, rotating refresh tokens with reuse detection, Passport-style strategies and the
CurrentUserextractor. - Account flowsRegistration, password reset, email verification, profile and password changes, and TOTP two-factor authentication with recovery codes.
- AuthorizationRoles, permissions and CASL-compatible abilities, checked on routes, on loaded records and in SQL list filters, and shared with the front end.
- Encryption and hashingThe application key, AES-256-GCM encryption with key rotation, Argon2id password hashing and secure token helpers.
- The audit logAn audit trail of data changes, sign-ins, permission changes and access denials: recorded by default, queryable over HTTP and in code, and pruned on a schedule.
Database
- Getting startedConnect to SQLite or PostgreSQL, configure the pool and run your first queries with SeaORM.
- Entities and repositoriesSeaORM entities in a Navree app, relations and eager loading, UUID v7 keys, soft deletes, and
Repofor writes that record change events. - The unit of work and transactionsOne lazy transaction per request, committed when the response succeeds; units of work in jobs and commands, after-commit hooks, row locks and change observers.
- MigrationsModule-owned SeaORM migrations: writing them, ordering them across modules, and the
migrate,migrate:status,migrate:rollbackandmigrate:freshcommands. - Seeding and factoriesSeeders for the data an app needs and demo data, the
db:seedcommand, and model factories for tests. - PaginationOffset pages in Laravel's
{data, meta}shape withPageQuery,paginateandPage, your own page parameters, and cursor pagination over UUID v7 keys.
Digging deeper
- Cache
CacheandLocksfromCacheModule: the in-memory store on moka,remember, stale-while-revalidate, counters, tags and atomic locks. - EventsA typed, in-process event bus: events, sync and queued listeners, emitting, ordering, transactions and errors.
- QueuesBackground jobs on the database or memory driver: dispatching, delays, unique jobs, retries with backoff, failed jobs,
queue:workand testing withQueueFake. - Task schedulingCron-style schedules declared in modules: commands, jobs and functions, overlap prevention, single-node runs,
schedule:workandschedule:run, all in UTC. - MailMailables rendered from MiniJinja templates; the SMTP, log, array and failover transports; queued sending; configuration, previewing and testing.
- NotificationsOne notification over the mail, database and broadcast channels: notifiable users, read state, the
/api/notificationsroutes, queueing and testing. - File storageNamed disks on object_store: putting, reading and streaming files, upload checks and signed temporary URLs.
- HTTP clientOutgoing HTTP requests with retries, per-attempt timeouts, an SSRF guard and a fake for tests.
- Real-time broadcastingA Pusher-protocol WebSocket server inside your app: public, private and presence channels, channel authorisation, a signed relay for workers, and Laravel Echo on the front end.
- Views and templatesMiniJinja templates for mail and other text: where they live, how modules embed them, escaping, filters and reloading.
- OpenAPIAn OpenAPI 3.1 document generated from your routes at boot, a docs UI, exports for typed clients, and API resources.
- Health and metricsLiveness and readiness endpoints, custom health checks, and Prometheus metrics with an optional bearer token.
- Console commands and the CLIThe
navreeCLI (new, everymake:*generator,dev), your app's own commands (serve,migrate,queue:work, ...), and writing your own. - Maintenance modeAnswer every request with a 503 while you deploy or migrate, with
downandup, a retry hint, a message and paths that stay up.
Testing
- Getting startedTest a Navree app the way it runs:
TestAppboots your modules in-process, with a fresh SQLite database per test, andcargo testruns it all. - HTTP testsCall your API in-process with
TestClient, act as a signed-in user, and assert on statuses, headers, JSON and errors; plus the CRM's test kit pattern. - Database testsA fresh SQLite database per test, preparing data with factories, seeders and the API, and asserting on rows, change events and audit entries.
- FakesReplace the edges of your app in tests: the queue, mail, the clock, outgoing HTTP, authentication and file storage, and how to observe events and broadcasts.