Wiring
RedisModule, RedisQueueModule and QueueModule — how producer-only and worker apps share a features crate without spawning workers they don't run.
The same features::audio crate compiles into the API binary and the
worker binary. Only the worker drains the queue. That split is two
module imports, two mains, one shared features crate — the framework
decides which #[process] methods actually run by walking the access
graph from each app’s root.
Three modules, three roles
Section titled “Three modules, three roles”| Module | Role | Imported by |
|---|---|---|
RedisModule | Opens the Redis connection every Redis binding shares — the queue’s producer and consumer, the rate-limit store, the schedule’s lock; a second Valkey is a named instance. A bare import reads <PREFIX>_REDIS__*; for_root(cfg) pins the base. | Each Redis binding, bare, by the instance it runs on. A root names it to pin it, or for a connection it injects with no binding. |
RedisQueueModule | Binds the queue port over that connection: Jobs, the portable handle a feature injects to enqueue, and the consumer the worker runs jobs through. A bare import reads <PREFIX>_REDIS__QUEUE__*; for_root(RedisQueueConfig { lease }) pins the base — see Delivery on Redis. | Every app that enqueues or runs jobs. |
QueueModule | From nest_rs::queue: contributes the port’s QueueWorker transport, which discovers the reachable #[process] methods at boot and runs each over the bound consumer; its own setting is the drain window, <PREFIX>_QUEUE__SHUTDOWN_TIMEOUT_SECS, which for_root(cfg) pins at the app’s root. | Brought, bare, by each #[processor] host (AudioQueueModule’s) — so only an app importing a queue adapter runs a worker. |
The redis-queue feature compiles all three. Each Redis binding is a feature of
its own — redis-queue, redis-throttler, redis-schedule — and redis is the
connection alone, so an app that rate-limits on Redis compiles no queue; beside
health, RedisModule attaches each instance’s readiness check too. Import
RedisQueueModule without redis-queue and the build fails on the import, with
rustc’s note naming the queue feature of nest-rs-redis: redis-queue is the
umbrella feature that turns it on, where the umbrella’s own queue is the port
alone.
The server is Valkey, in its latest release: the connection speaks the
Redis protocol — hence redis://, rediss:// and nest_rs::redis — and Valkey
is the server it is supported and tested on, never Redis itself; see
Limits. The URL’s scheme declares the topology — one
server, Sentinel or a Cluster — and every binding runs on each: see
Valkey topologies.
RedisModule reads <PREFIX>_REDIS__URL from the environment,
and fails the boot naming it when it is unset, in every profile — no default
names a Redis, so development’s sits in .env.development, as nestrs new
writes it; RedisModule::for_root(RedisConfig { url, .. }) supplies that URL as the
base the environment overlays — so a deployment setting <PREFIX>_REDIS__URL
still wins, field by field (the dual-path rule).
One connection, one variable, named for the crate that parses it: a
throttler-only app sets the same <PREFIX>_REDIS__URL. See Module boot for the
four boot phases that resolve the connection before any transport attaches.
The worker app
Section titled “The worker app”The worker imports the queue’s Redis binding, which opens the connection, and
each feature’s queue adapter. That’s it — AudioQueueModule pulls in the
AudioModule port, and its processor the QueueModule that runs its jobs; the
backend binding is the one line the adapter leaves to the root, which chooses it.
use nest_rs::core::module;// …use nest_rs::redis::{RedisQueueModule, RedisScheduleModule};// …
use features::audio::AudioQueueModule;use features::notifications::{NotificationsQueueModule, NotificationsScheduleModule};
#[module( imports = [ // … RedisQueueModule, // … AudioQueueModule, NotificationsQueueModule, // … ],)]pub struct WorkerModule;The demo’s worker also opens the database — the notifications job writes a row — runs the notifications purge on a schedule, and serves its health probes over HTTP; the excerpt keeps the queue’s lines.
At boot:
RedisModule, whichRedisQueueModuleimports, readsRedisConfigfrom<PREFIX>_REDIS__*and registers the factory that opens theRedisConnection; the first config the boot loads registers the active environment.RedisModule::<Cache>, in an app opening a second Valkey, does the same under<PREFIX>_REDIS__CACHE__*.RedisQueueModuleregisters factories — declared to run after the connection’s — that bind the port’sJobsoverRedisQueueProducerand the Redis consumer as the port’sBoundConsumer, with its lease read from<PREFIX>_REDIS__QUEUE__*.AudioQueueModulebringsAudioProcessor(the#[processor]host) and its#[process]methods into the reachable set, and the host bringsQueueModule, which contributes theQueueWorkertransport — once, however many hosts bring it — with its drain window read from<PREFIX>_QUEUE__*.QueueWorker::configurediscoversinventory::iter::<ProcessMethod>(), keeps only the methods whose provider is reachable, refuses what the backend cannot honour, and logs each one. It then prepares the consumer, which creates each queue’s consumer group and loads the scripts.serveruns each method with permits of its own until the drain.
The producer-only app
Section titled “The producer-only app”A producer-only binary imports RedisQueueModule, and no
queue adapter — so no QueueModule. It gets
Arc<Jobs> to push with — and no worker, no discovered
inventory, no read of any queue.
use nest_rs::core::{GlobalInterceptors, module};// …use nest_rs::redis::{RedisQueueModule, RedisScheduleModule};use nest_rs::seaorm::SeaOrmDatabaseModule;// …use features::audio::{AudioHttpModule, AudioScheduleModule};// …
#[module( imports = [ // … SeaOrmDatabaseModule, RedisQueueModule, // … RedisScheduleModule, // … AudioHttpModule, AudioScheduleModule, ], // …)]pub struct ApiModule;That apps/api is exactly this shape: producer-only. Its HTTP
controller and scheduled timer both end in AudioService::enqueue_transcode,
which pushes through the bound Jobs onto Redis. Leave
RedisQueueModule out and the boot refuses AudioService, which injects
Jobs, naming the binding to import. No worker
runs in this process — that’s the worker binary’s job. RedisScheduleModule
is the schedule’s binding, not a worker’s: the occurrence lock the timer
claims through, because the API’s replicas fire that enqueue once per
occurrence between them rather than once each.
Binding SeaOrmDatabaseModule beside the queue also attaches the outbox relay,
with nothing listed: a push inside one of the app’s transactions waits in the
database for its commit, and the relay files it from this process — see A push
inside a transaction.
Module-gating across the shared crate
Section titled “Module-gating across the shared crate”The worker depends on the shared features crate, so AudioController
and AudioResolver are compiled in. They are not active: the
worker doesn’t import AudioHttpModule or AudioGraphqlModule, so
the access graph never marks those providers as reachable. Every
transport and mount — HttpTransport, QueueWorker, /graphql — filters
its inventory through the ReachableProviders set the access graph
computes from the running app’s root. Linked but unreachable ⇒ inert,
said once at boot — at debug for these, which live in a shared crate and
are another binary’s to serve, and at warn for a host in the app’s own
crate, whose module it forgot to import. There is no ungated mode: a
container no boot sealed — one a test builds by hand — carries no set, and
QueueWorker::configure refuses it with UngatedDiscoveryError naming
#[process] method.
The same property cuts the other way: the API binary’s
AudioQueueModule is not imported, so its #[process] methods
sit in the binary as dead code. No worker is spawned for audio in
the API. Even if you accidentally imported QueueModule in the
API, omitting AudioQueueModule would keep AudioProcessor::transcode
out of the reachable set — QueueWorker::serve would idle until
shutdown.
This is what makes splitting producer and consumer across deploys
cheap. The features crate is one library, the binaries are
compositions of it, and module-gating is the line that decides what
each binary actually does at runtime. See
fundamentals/modules for the access graph
that enforces this — boot fails with AccessGraphError if a provider
injects something its module doesn’t own or import transitively.
What the wire looks like at boot
Section titled “What the wire looks like at boot”$ nestrs run dev worker INFO nest_rs::app: transport attached transport="queue" INFO nest_rs::queue: mounted host="AudioProcessor" method="transcode" queue="audio" retries=3 concurrency=4One transport attached line per transport, and one mounted line per discovered
method that survived the reachability filter. The producer-only API’s boot
opens the same connection, but logs no transport attached transport="queue" and no
mounted line on nest_rs::queue — the worker side never wakes up.
Reference
Section titled “Reference”crates/nest-rs-redis/src/module.rs—RedisModuleand itscollect(config resolution + the instance’s connection).crates/nest-rs-redis/src/queue/module.rs—RedisQueueModulebindingJobsoverRedisQueueProducerand the Redis consumer asBoundConsumerover the same connection.crates/nest-rs-queue/src/module.rs—QueueModulecontributing theQueueWorkertransport.crates/nest-rs-queue/src/worker.rs—QueueWorker::configurefilteringProcessMethodbyReachableProvidersand preparing the consumer.apps/api/,apps/worker/— producer-only and worker shapes side by side.- fundamentals/modules — boot phases, imports, dynamic modules, the access graph.
Going further
Section titled “Going further”- Producing jobs — enqueue from a service.
- Retries and failure — the worker-side failure budget.
- Observability — the boot and per-job lines this wiring emits.