ClusterSingletonManager

ClusterSingletonManager is the per-node actor that owns the singleton election logic. Every node runs one; only the leader’s manager has an active singleton child. When leadership changes, the old manager stops its child; the new manager spawns one.

The proxy on every node tracks “where is the leader’s manager?” and routes messages there. When n1 leaves, the manager on n2 or n3 becomes the leader, spawns the singleton, and proxies shift their target.

Configuration

The manager is not spawned by hand — cluster.singleton.start(...) does it, at the well-known path proxies address, and the start options below are what it configures:

import { SingletonKey, StartSingletonOptions } from 'actor-ts';

const singletonOptions = StartSingletonOptions.create<JobCommand>()
  .withRole('control-plane')            // optional
  .withLease(leaseImpl)                 // optional split-brain protection
  .withAcquireRetryIntervalMs(5_000);   // retry cadence when lease acquire fails
cluster.singleton.start(JobScheduler, singletonOptions);

The manager’s own ClusterSingletonManagerOptions — cluster, typeName, singletonActor and the three above — are assembled from these by the extension. The fields are documented here because they are what the manager acts on, not because you construct them:

Field	Required	What
cluster	Yes	The cluster the manager watches.
typeName	Yes	Logical name for this singleton; the child actor’s name.
singletonActor	Yes	How to construct the singleton. Only invoked on the host.
role	No	Restrict hosting to nodes carrying this role. Other nodes’ managers stay passive.
lease	No	If set, the host must acquire this lease before spawning the singleton.
acquireRetryIntervalMs	No (default 5s)	Retry cadence after a failed lease acquisition.

Which node hosts

Without a role, the host is the cluster leader. With one, it is the first up-member carrying that role — not “the leader, if it happens to carry the role”, which would leave the singleton hosted nowhere whenever the elected leader lacked it. Both forms read the same address-ordered member list, so every node independently picks the same node, and the proxy resolves the host exactly the way the managers do.

The naming convention

The manager must be spawned at a path matching:

actor-ts://<system>/system/cluster/singleton/manager-<typeName>

Hence the actor name 'singleton-manager-job-scheduler' above when typeName = 'job-scheduler'. The ClusterSingletonProxy uses this path convention to find the manager on whichever node is currently leader.

If you misname, the proxy can’t route — silent breakage. Always:

import { singletonManagerPath } from 'actor-ts';

const path = singletonManagerPath(system.name, 'job-scheduler');
// "actor-ts://<sysName>/system/cluster/singleton/manager-job-scheduler"

You can use this helper if you want to assert the path matches.

The two operational paths

No-lease (default)

LeaderChanged → I'm leader now? → yes → spawn singleton
                                → no → stop my singleton (if any)

Synchronous reconcile. As soon as gossip says this node is the leader, the manager spawns its singleton child. Simple, fast.

Drawback: during a partition, both halves can have their own leader. Both managers spawn their singleton. Two singletons exist — that’s exactly the case singleton is meant to prevent.

With lease

const singletonOptions = StartSingletonOptions.create<JobCommand>()
  .withLease(someLeaseImpl);
cluster.singleton.start(JobScheduler, singletonOptions);

Adds an async gate on the lease. The flow:

The lease provider — typically a Kubernetes Lease resource — guarantees at most one holder cluster-wide. Even if two managers think they’re leader, only one can acquire the lease, and only that one spawns the singleton.

The framework uses internal events (no inline awaits) for state transitions, so concurrent cluster events can’t interleave with an in-flight acquire.

See Singleton with lease for the configuration and lease-impl choices.

Lease lost

lease lost (revoked, renew failed) → stop singleton immediately

If the lease is revoked (someone else acquired it, or the provider’s renew failed), the manager stops the singleton and waits. When LeaderChanged fires again (e.g., the manager notices it’s still seen as leader by gossip), it retries lease.acquire().

Watching the child

The manager death-watches the singleton child. If the child crashes (uncaught error reaches its supervisor’s escalate directive), the framework’s normal supervision applies — by default, the child is restarted. Manager doesn’t intervene unless leadership also changed.

If the child explicitly stops itself (context.stopSelf()), the manager sees the Terminated but does nothing with it: it doesn’t re-spawn, and it doesn’t release the lease — a held lease stays held, and the manager’s child reference is left pointing at the now-dead singleton. The singleton is gone until the next leader change.

If you want a self-stopping singleton to be re-spawned, the manager isn’t the place — write a watchdog actor at a level above, or have the singleton supervise its own state and never self-stop.

Restart semantics

When the manager itself fails (which is rare), its supervisor (typically the user-guardian) restarts it. On restart:

• Cluster subscriptions are re-established.
• The current leader is queried again.
• If this node is still leader, lease-acquire (if applicable) is retried, and the singleton is spawned afresh.

The old singleton’s state is lost unless it persists itself. For stateful singletons, use PersistentActor.

When you’d interact with the manager directly

You usually don’t. The proxy is the contract — tell to the proxy, receive replies, never touch the manager.

Direct manager contact is useful only for:

• Tests verifying the election protocol works as expected.
• Diagnostics in production — “is the manager on this node active?” via the management endpoints.
• Custom singleton patterns that don’t fit the proxy abstraction (rare; usually a sign the singleton model isn’t right for the use case).

Diagnostics

import { MemberUp, LeaderChanged } from 'actor-ts';

cluster.subscribe((evt) => {
  if (evt instanceof LeaderChanged) {
    console.log(`leader is now ${evt.leader.map((m) => m.address).getOrElse('<none>')}`);
  }
});

The manager’s behavior is driven entirely by these events. If you suspect the manager is misbehaving, log LeaderChanged + MemberUp / MemberRemoved to see what the manager sees.

For the lease path, also log lease.acquire() returns — the manager logs these by default at debug level.

Call start() on every node that may become leader

cluster.singleton.ref(JobScheduler);    // addresses it, never hosts it
cluster.singleton.start(JobScheduler);  // puts this node into rotation

A proxy routes to whichever node is currently leader and expects a manager there. A node that only ever called ref runs no manager, so if it becomes leader nothing anywhere is hosting the singleton and messages dead-letter with a warning naming the type. Either call start everywhere, or role-restrict so only starting nodes can host.

Declare a role on the key, not only in the options

class Ingress extends Actor<IngressCommand> {
  static readonly singleton = SingletonKey.of<IngressCommand>('ingress', 'edge');
}

A node that only calls ref has no options object — it has the key, and nothing else. A role declared only through StartSingletonOptions.withRole is therefore invisible to it, and its proxy resolves a different host than the managers do. Put the role on the key and every node agrees by construction; withRole still overrides it where you need a per-deployment answer.

acquireRetryIntervalMs must be positive

acquireRetryIntervalMs: 0,   // ✗ does not disable retries

0 does not disable retries — there is no disable switch. The value is validated as a positive number when you start the singleton, so a non-positive value is rejected up front with an OptionsError. And 0 never means “stop retrying” internally: the 5s default applies only to an unset value, so 0 would just retry immediately. Use a positive interval; the 5s default suits most lease providers.

Where to next

• Singleton overview — the bigger picture: proxy + manager + singleton.
• Singleton with lease — split-brain protection details.
• Coordination — the lease abstraction.
• Cluster overview — how leader election works at the cluster level.

The ClusterSingletonManager API reference covers all message types and settings.