Sharded daemon process
Esta página aún no está disponible en tu idioma.
Sometimes you need N background workers, distributed across the cluster, each with a stable identity:
- A worker per partition of work (think Kafka consumer-group pattern, but inside the cluster).
- N scheduled coordinators, one per timezone, one per region.
- N background reconcilers each owning a slice of work-IDs.
A singleton gives you
one of these. Sharding gives you one per entity ID.
ShardedDaemonProcess gives you exactly N, indexed
0..N-1, spread evenly across the cluster, automatically
respawned on failover.
A minimal example
Section titled “A minimal example”import { ActorSystem, Actor } from 'actor-ts';import { Cluster, ClusterOptions } from 'actor-ts/cluster';import { ShardedDaemonProcess, ShardedDaemonProcessOptions } from 'actor-ts/cluster';
class Reconciler extends Actor<{ kind: 'check' }> { constructor(public readonly index: number) { super(); }
override preStart(): void { this.log.info(`reconciler #${this.index} starting`); // schedule periodic check, e.g.: this.context.timers.startTimerWithFixedDelay( 'check', { kind: 'check' }, 60_000, ); }
override onReceive(message: { kind: 'check' }): void { this.log.info(`reconciler #${this.index} ticking`); // ... per-index work }}
const system = ActorSystem.create('my-app');const clusterOptions = ClusterOptions.create() .withHost(host) .withPort(port) .withSeeds(seeds);const cluster = await Cluster.join(system, clusterOptions);
const shardedDaemonProcessOptions = ShardedDaemonProcessOptions.create() .withName('reconciler') .withNumDaemons(8) .withActorFor((i) => () => new Reconciler(i));const handle = ShardedDaemonProcess.init(system, cluster, shardedDaemonProcessOptions);
// Each of the 8 daemons starts automatically. No further setup needed.
// Optionally: send a message to a specific indexhandle.tell(3, { kind: 'check' });Three things happen on init:
- The framework registers a sharded entity type
(
daemon-reconciler). - Each entity ID is just the daemon’s index as a string (
'0','1', …,'7'). - Internal “wake-up” messages are sent to every index, forcing the sharding machinery to materialize the entity actors on the nodes the coordinator chose.
After this, all 8 daemons are running, distributed across cluster nodes, each with its stable index visible via the constructor argument.
What the handle gives you
Section titled “What the handle gives you”interface ShardedDaemonProcessHandle<T> { readonly region: ActorRef<DaemonEnvelope<T>>; tell(index: number, message: T): void; stop(): void;}region— the underlying sharding region ref. Messages sent here must be wrapped in{ index, body }envelopes; usehandle.tellinstead.tell(index, message)— convenience for sending to daemoni.stop()— stops the liveness heartbeat and cluster subscription. Does not stop the daemons themselves — they keep running until the cluster shuts down.
How it builds on sharding
Section titled “How it builds on sharding”ShardedDaemonProcess is a thin wrapper around ClusterSharding:
typeName: 'daemon-<name>'.extractEntityId: env => env.index.toString().rememberEntities: true— so a node failure re-spawns the daemon elsewhere.allocationStrategy: LeastShardAllocationStrategyby default — spreads daemons evenly.
You could write all this manually with ClusterSharding.start
yourself. The wrapper exists to:
- Save you the boilerplate.
- Auto-send wake-up messages on init so daemons materialize eagerly.
- Subscribe to
LeaderChanged/MemberRemovedand re-send wake-ups, ensuring daemons that should be running actually are. - Provide the
livenessIntervalMssafety net.
Liveness heartbeat
Section titled “Liveness heartbeat”const shardedDaemonProcessOptions = ShardedDaemonProcessOptions.create() .withName('reconciler') .withNumDaemons(8) .withActorFor((i) => () => new Reconciler(i)) .withLivenessIntervalMs(30_000);ShardedDaemonProcess.init(system, cluster, shardedDaemonProcessOptions); // default — pings each index every 30sPeriodically (default every 30 s), the wrapper sends a synthetic “wake-up” to every index. If a daemon for some index was unexpectedly stopped (a node leaving + a brief partition just at the wrong moment), the wake-up causes the sharding machinery to re-spawn it on a current up-member.
This is belt-and-braces — most failover is handled by sharding’s own cluster-event subscriptions. The liveness ping covers the edge case where an event was missed.
Set to 0 to disable. Useful in tests where you control the
cluster events deterministically.
Or set it in application.conf and leave the call site alone:
actor-ts.sharded-daemon-process.liveness-interval = 10sConfiguration
Section titled “Configuration”type ShardedDaemonProcessOptionsType<T> = { name: string; // unique daemon-set identifier numDaemons: number; // total daemons across the cluster actorFor: (i: number) => ActorClassOrFactory<T>; role?: string; // restrict to specific nodes livenessIntervalMs?: number; // safety-net ping cadence; default 30s};| Field | HOCON | What |
|---|---|---|
name | — | A unique daemon-set name. Two init calls with the same name conflict. |
numDaemons | — | How many daemons to run. Fixed at init; can’t change without restart, and must be identical on every node — it becomes the sharded type’s numShards, and the coordinator refuses a node that disagrees (see numShards is a cluster-wide agreement). A rolling deploy that changes it leaves the not-yet-updated nodes registered and the updated ones refused, until the last one is over. |
actorFor(i) | — | Returns the actor class or factory for daemon i. Use i to differentiate per-index logic. |
role | actor-ts.sharded-daemon-process.role | Only nodes carrying this role host daemons (passed through to sharding). |
livenessIntervalMs | actor-ts.sharded-daemon-process.liveness-interval | Safety-net ping cadence; default 30s. |
The two keys are read once per init and layered under whatever the call
passes, so an explicit withRole / withLivenessIntervalMs still wins. The
other three have no leaf: they describe one daemon set rather than a
deployment, and a factory has no HOCON form at all.
name and numDaemons staying code-only is not an oversight. numDaemons
becomes the sharded type’s numShards, which every node must agree on — a
value each node reads from its own file is the one shape of that agreement
nothing can check until a node is already being refused.
An unset role inherits the sharding one
Section titled “An unset role inherits the sharding one”The daemon set starts as an ordinary sharded type, so leaving role unset —
in code and in actor-ts.sharded-daemon-process.role, whose shipped ""
counts as unset — lets the daemons follow
actor-ts.sharding.role like
every other type:
actor-ts.sharding.role = "backend" # every sharded type, daemons includedNaming one here narrows the daemons alone:
actor-ts.sharding.role = "backend" # entities on the backend nodesactor-ts.sharded-daemon-process.role = "batch" # daemons on the batch nodesLike sharding.role, this names a role and does not grant one — a node’s
own roles are a separate setting, ClusterOptions.withRoles([...]) or
actor-ts.cluster.roles. A role no
up-member carries allocates nothing, and for daemons that is silent: nobody
sends a daemon a first message, so there is no reply to wait for and no
buffer to fill. The coordinator logs one line naming the role once a region
has registered and been filtered out.
When to reach for it
Section titled “When to reach for it”Three good fits:
- Partitioned background work —
Nreconciliation jobs each owning a slice of IDs. Modulo or hash to assign work to daemon index. - Distributed schedulers — a per-timezone scheduler, a per-region quota-replenisher. Each daemon’s index maps to its scope.
- Stream-processing groups — when integrating with Kafka / broker actors, each daemon can be one consumer-group member.
When NOT to use it
Section titled “When NOT to use it”Comparison
Section titled “Comparison”| Tool | What |
|---|---|
| ClusterSingleton | Exactly 1 actor cluster-wide. |
| ShardedDaemonProcess | Exactly N indexed actors, distributed. |
| ClusterSharding | One actor per key (potentially infinite). |
| ClusterRouter | Route messages across pre-existing actors on every node. |
The “right tool by cardinality”: 1 → singleton, fixed N → daemon-process, many (one per business entity) → sharding, “every node” → cluster router.
Where to next
Section titled “Where to next”- Sharding overview — the foundation it builds on.
- Singleton overview — for N=1.
- Allocation strategy — what places the daemons.
- Remember entities — what makes them survive coordinator failover.
The ShardedDaemonProcess
API reference covers the full surface.
