Skip to content

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.

ModuleRoleImported by
RedisModuleOpens 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.
RedisQueueModuleBinds 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.
QueueModuleFrom 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 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.

apps/worker/src/module.rs (from the demo, abridged)
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:

  1. RedisModule, which RedisQueueModule imports, reads RedisConfig from <PREFIX>_REDIS__* and registers the factory that opens the RedisConnection; the first config the boot loads registers the active environment.
  2. RedisModule::<Cache>, in an app opening a second Valkey, does the same under <PREFIX>_REDIS__CACHE__*.
  3. RedisQueueModule registers factories — declared to run after the connection’s — that bind the port’s Jobs over RedisQueueProducer and the Redis consumer as the port’s BoundConsumer, with its lease read from <PREFIX>_REDIS__QUEUE__*.
  4. AudioQueueModule brings AudioProcessor (the #[processor] host) and its #[process] methods into the reachable set, and the host brings QueueModule, which contributes the QueueWorker transport — once, however many hosts bring it — with its drain window read from <PREFIX>_QUEUE__*.
  5. QueueWorker::configure discovers inventory::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. serve runs each method with permits of its own until the drain.

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.

apps/api/src/module.rs (from the demo, abridged)
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.

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.

Terminal window
$ 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=4

One 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.

  • crates/nest-rs-redis/src/module.rs — RedisModule and its collect (config resolution + the instance’s connection).
  • crates/nest-rs-redis/src/queue/module.rs — RedisQueueModule binding Jobs over RedisQueueProducer and the Redis consumer as BoundConsumer over the same connection.
  • crates/nest-rs-queue/src/module.rs — QueueModule contributing the QueueWorker transport.
  • crates/nest-rs-queue/src/worker.rs — QueueWorker::configure filtering ProcessMethod by ReachableProviders and 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.