Configuration
Esta página aún no está disponible en tu idioma.
actor-ts uses HOCON for configuration — a superset of JSON
common in JVM config files, with substitutions, durations and
sizes. (include directives are refused
— compose the sources in code.) Six layers, resolved highest-first:
- Constructor arguments to
ActorSystem.create(name, settings)— explicit fields such asloggerorlogLevel, which beat any key. - The inline
configobject in the settings — the code overrides, above every file. - The secrets file —
secrets.conf, optional, with its active profile (Secrets file). - The application file —
application.confat the project root, or an explicit path viaconfigFile, with its active profile (Profiles). - The project’s defaults — its own
reference.conf, optional, with its active profile (The project reference.conf). - Reference defaults — bundled in the framework as
REFERENCE_CONF(seesrc/config/Reference.ts).
Anything not specified in layers 1 to 5 falls through to the
bundled default, and a ${VAR} in any of the files may read a
.env file as well as the environment.
Loading order spells out the whole chain.
This page explains what each key does. For the exhaustive list — every setting the framework ships, verbatim from the bundled file — see The full reference.conf.
A typical application.conf
Section titled “A typical application.conf”This sample shows a representative selection of blocks, not every key; for the full list, see The full reference.conf.
actor-ts { system { name = "my-app" } logger { level = "info" }
dispatcher { default = "hybrid" # hybrid | immediate | microtask | throughput throughput = 16 }
cluster { gossip-interval = 1s seed-retry-interval = 3s weakly-up-after = 0s # 0 = opt-in only max-members = 1000 max-tombstones = 10000 tombstone { time-to-live = 24h prune-interval = 5m min-retention = 0s # 0 = derive from down-after } failure-detector { implementation = simple # simple | phi heartbeat-interval = 500ms # shared by both implementations auto-down = on # on = remove at down-after, off = park at unreachable unreachable-after = 2s down-after = 5s phi { unreachable-threshold = 8 down-threshold = 12 max-sample-size = 200 min-std-deviation = 100ms acceptable-heartbeat-pause = 3s expected-response-after = "auto" # auto = heartbeat-interval } } split-brain-resolver { active-strategy = off # off | keep-majority | keep-oldest | keep-referee | static-quorum | lease-majority stable-after = 20s down-all-when-unstable = off } pub-sub { gossip-interval = 1s max-subscribers-per-topic = 10000 max-topics = 10000 max-remote-nodes-per-topic = 1000 send-to-dead-letters-when-no-subscribers = on } receptionist { gossip-interval = 1s max-subscribers-per-key = 1000 max-subscriptions-total = 10000 } }
distributed-data { gossip-interval = 1s max-pending-quorum-requests = 1000 # 0 = no cap max-quorum-timeout = 30s # 0 = no ceiling max-gossip-bytes = 1M # per gossip frame; 0 = no budget }
remote { tcp { host = "0.0.0.0" port = ${?ACTOR_TS_PORT} # unset: CLUSTER_PORT (bootstrap), then 2552 } max-frame-bytes = 16M }
persistence { journal { plugin = "actor-ts.persistence.journal.in-memory" } snapshot-store { plugin = "actor-ts.persistence.snapshot-store.in-memory" } }
sharding { number-of-shards = 64 role = "" # "" = unrestricted; names a role, never grants one rebalance-interval = 2s hand-off-timeout = 10s acquire-retry-interval = 5s # retry a failed coordinator lease acquire remember-entities = false passivation-idle = 5m # 0 disables auto-passivation # shard-passivation-idle # unset: follows passivation-idle max-entities = 0 # 0 = no per-node cap buffer-size = 100000 # region-wide; 0 = never buffer register-retry-interval = 500ms shard-region-query-timeout = 5s entity-recovery { # how remembered entities come back strategy = all # all | constant-rate constant-rate.frequency = 100ms constant-rate.number-of-entities = 5 # region-wide, not per shard } }}Place this at the project root. The framework auto-loads it on
ActorSystem.create.
The keys, grouped by module
Section titled “The keys, grouped by module”actor-ts.system
Section titled “actor-ts.system”| Key | Default | Purpose |
|---|---|---|
system.name | "default" | System name — used in actor paths and cluster identification. Applies when ActorSystem.create() is called without a name; an explicit create('billing') wins. |
system.shutdown-drain-timeout | 2s | How long terminate() lets the actors under /user finish queued work before the stop cascade starts. Returns as soon as the tree is quiet, so an idle system pays a tick. Keep it under coordinated-shutdown.default-phase-timeout; 0 disables draining. |
actor-ts.logger
Section titled “actor-ts.logger”| Key | Default | Purpose |
|---|---|---|
logger.level | "info" | One of debug / info / warn / error / off. |
actor-ts.actor
Section titled “actor-ts.actor”| Key | Default | Purpose |
|---|---|---|
actor.throughput | 16 | User messages one actor handles per dispatcher turn before yielding. Override it per path with an actor-ts.deployment entry, and per actor with ActorOptions.withThroughput(), which wins over both. |
actor.ask-timeout | 5s | Deadline ActorRef.ask arms when the caller names no timeoutMs. A per-call ask(message, ms) always wins. Not honoured by every ref — see below. |
ask-timeout reaches most refs, not all of them, and that is worth knowing
before you tune it. A ref applies the configured value only if it can reach
the ActorSystem that read it. Seven can: the ordinary local ref, TestProbe,
RemoteActorRef, ClusterSingletonProxy, the two shard refs, and EntityRef
through its region. The rest carry a system name and no system, and keep the
built-in 5 s — the dead-letter ref, Nobody, an unresolved-path ref and the
one-shot reply ref an ask synthesises for itself, plus two framework-internal
handles (a WebSocket connection and the graceful-stop watcher) that nothing can
reply to at all. Every one of them is a ref you hold where no live actor is
behind it, so an ask on one is waiting for a reply that is not coming — the
timeout decides how fast you find that out, not whether you find it out.
A bad value is refused, not clamped — unlike actor.throughput above.
ask-timeout = 0 would arm no deadline, and an ask with no deadline can never
settle, so there is no nearest-sensible value to fall back to; the system
throws at ActorSystem.create, naming the key, rather than at every ask site
later.
Below 4.6s it collides with scatter-gather routing. A router from
Router.scatterGatherFirstCompleted(…) defaults to a 4.5 s deadline precisely
so that it can collect its routees’ failures and answer before the caller’s own
ask gives up. Configure an ask timeout under that and the caller sees
AskTimeoutError instead of the AggregateError naming the failing routees.
The system logs one warn at startup when it happens; give the router its own
ScatterGatherOptions.withTimeoutMs() if the shorter ask deadline is what you
want.
actor-ts.diagnostics
Section titled “actor-ts.diagnostics”| Key | Default | Purpose |
|---|---|---|
diagnostics.log-dead-letters | 10 | Dead letters logged in full before logging suspends. 0 turns dead-letter logging off entirely. Every letter is captured and published on the event stream either way — this gates the log line and nothing else. |
diagnostics.log-dead-letters-during-shutdown | off | Log the burst terminate() produces while it drains mailboxes to dead letters. Off because an orderly shutdown drains every queued and stashed message that way; an individual ref.stop() still logs, because the system is not terminating. |
diagnostics.log-dead-letters-suspend-duration | 5m | How long logging stays suspended once the count above is reached. 0 never suspends, which is how “log every dead letter” is spelled. |
diagnostics.log-config-on-start | off | Write the merged configuration to the log once at startup — one info record, every key with the layer that set it, sorted by path. The answer to “why is this setting not what I wrote”. Read the redaction note below before turning it on. |
diagnostics.debug.unhandled | off | One debug record per message an actor was handed and declined: recipient path, message class, sender. The count (actor_unhandled_total) and the dead letter happen either way. |
diagnostics.debug.lifecycle | off | One debug record per actor start, stop and restart. ActorStarted / ActorStopped / ActorRestarted on the event stream carry the same facts to a subscriber that can be selective, which a log level cannot. |
diagnostics.debug.event-stream | off | One debug record per event-stream subscribe and unsubscribe — never per publish, which runs on every actor start, every stop and every dead letter. A whole-actor unsubscribe that removed nothing is not recorded; every actor stop makes one. |
The record names the recipient path, the sender when there is one, and the
message’s class — never the payload, for the same data-protection reason
dead-letters.store defaults to off. Every key here is also settable in
code, field by field, through ActorSystemOptions.withDiagnostics(…). See
Dead letters for the whole picture.
The debug.* keys need two switches, not one. The key decides whether a
record is produced; logger.level = debug decides whether it is written.
Setting only one of them looks exactly like a switch that does not work.
log-config-on-start is deliberately not in that family — it is an info
record, because an operator who asked for a config dump asked for output.
What the config dump redacts, and what it does not. A value is withheld
when any whole word of its key is password, passphrase, passwd,
pass, secret, token, key, credential, auth or authorization,
singular or plural — so cache.redis.password and an api-key print as
<redacted>, and so does every key beneath a branch named credentials.
Any word, wherever it stands in the name: an auth-header carries a bearer
token although it ends on header. And whole words only — a name is cut
into words at every character that is not a letter or a digit, at each
camelCase hump and in front of a digit after a letter, so passivation-idle
holds no pass and keyspace no key, while password2 holds the word it
numbers. Glued onto another word those words count as well
(pgpassword, clientsecret, ghtoken), all but key, pass and auth,
which end too many ordinary words; of the …key names apikey,
accesskey, secretkey and privatekey count, and pwd counts beside
another word of the key’s path, as in mysql-pwd or db.pwd — only a
variable called just PWD, a shell’s working directory, does not.
An sshkey is not read. A value whose name holds such a word is withheld
even when it is tuning: a
token-bucket-size of your own prints as <redacted>, and only the keys
reference.conf ships, such as cluster.receptionist.max-subscribers-per-key
and cache.redis.key-prefix, are exempted by name. A value that is a
boolean is never withheld whatever its key is called, since both of its
states are public.
A URL’s credentials are masked whatever its key is called. The userinfo
of every scheme://user:password@host in a printed value — and in each
element of a list — is replaced with ***. A cache.redis.url that
${?REDIS_URL} set to redis://default:s3cret@redis.example:6379/0 prints
as "redis://***@redis.example:6379/0", and so does a dsn, a
connection-string or a uri of your own that holds one. The userinfo
runs to the last @ before the next ://, so a password with an unescaped
/, ? or # in it is masked whole. The scheme and everything after that
@ — host, port, path and query — print exactly as written, which is what
tells you which Redis is configured, and the header counts these values
beside the keys it withheld. The price is paid by a value with no
credential and an @ further on, in a path or a query: https://host/a@b
prints as https://***@b.
A value the secrets file set is withheld whatever its
key is called, and the header counts those keys apart from the ones
withheld by name. The key rule also reads the fields of an object inside
a list, which is one key: in upstreams = [ { host = "db-1", password = "…" } ] the password prints as "<redacted>" and the host as written.
A value an environment variable supplied is withheld when the variable’s
name names a credential, by the same rule a key is read by, whatever the
key is called: my-app.dsn = ${DB_PASSWORD} prints as <redacted>, and
so does a key that refers to it and a string built from it. That holds for
a variable from the real environment and from the .env
file alike, in whichever layer read it — a code
override that replaced the key included — and in a WorkerMesh worker’s
dump. Every line names the variables behind its value, withheld or not —
my-app.db.host = "db-1" [application, from $DB_HOST] — and the header
counts these keys apart from the other two reasons.
The key rule is a heuristic over names, and it is the weakest of the four.
What none of them can see is printed in full: a bare password written out
under a key that does not name one, outside the secrets file and not taken
from a credential-named variable; a credential in a query string
(?password=…, ?authToken=…); SQL Server’s Server=…;Password=…
connection string; and memcached’s scheme-less user:password@host:11211
server list.
Nor is the list widened further: seed would redact cluster.seed-nodes, and
a dump whose ordinary keys read <redacted> is a dump nobody reads. So treat
the output as sensitive, keep the key off outside an investigation, and
check what your own keys are called before pasting a dump into a ticket. The
same rules, the same lists and the same limits apply to the DevTools config
panel.
actor-ts.mailbox
Section titled “actor-ts.mailbox”| Key | Default | Purpose |
|---|---|---|
mailbox.default.capacity | 0 | Bound every actor the application wrote at this many queued user messages, without touching a spawn site. 0 means no global bound, which is the shipped behaviour — so this is not a retune, it is the switch that introduces message loss for every application actor at once. |
mailbox.default.overflow | "drop-head" | System-wide policy for any bounded mailbox: the global bound above, and every actor that sets withMailboxCapacity() without naming a policy of its own. drop-head / drop-new / reject. |
The bound reaches the actors the application wrote, which is not the same
set as the actors under /user: a sharded entity is spawned by its shard and
a cluster singleton by its manager, both under /system, and both are the
application’s classes. Exempt are the framework’s own actors — shard regions
and shards, singleton managers, the pub-sub mediator, the reliable-delivery
producer, the DevTools hub — because shedding their traffic would break
invariants the application never asked about and cannot see. (A framework
class run as an entity is an entity: the host ShardedDaemonProcess runs
each daemon in is bounded.) A spawn site wins over both keys:
ActorOptions.withMailboxCapacity() overrides the capacity, withMailbox()
replaces the queue outright. Between the two sits the
actor-ts.deployment entry matching an actor’s path:
its capacity and policy win over these keys for the paths it names, and its
mailbox-capacity = 0 exempts them from the global bound.
Read Mailbox sizing before turning it
on. This key and a deployment entry’s mailbox-capacity are the two in this
file that can lose a message in an actor whose code says nothing about a
mailbox — this one in every application actor at once — and the page names
the framework-written actors a blanket bound still reaches because
application code spawns them — the WebSocket hub and its connections, the
broker adapters, the gRPC client and server.
actor-ts.deployment
Section titled “actor-ts.deployment”Per-path settings: a throughput and a mailbox for the actors whose path a key matches, without touching their spawn sites (#868). The block ships empty — its keys are your actor paths — so nothing changes until you write an entry.
actor-ts.deployment { "/user/ingest" { throughput = 64 mailbox-capacity = 10000 mailbox-overflow = "drop-new" } "/user/chat/ws-*" { mailbox-capacity = 256 } "/system/cluster/sharding/region-orders/**" { mailbox-capacity = 5000 }}| Key | Default | Purpose |
|---|---|---|
deployment."<path>".throughput | unset | User messages a matched actor handles per dispatcher turn. An integer; 0 or below reads as 1, as actor.throughput does. |
deployment."<path>".mailbox-capacity | unset | Queued user messages before the overflow policy acts. An integer, 0 or above; 0 leaves the matched actors unbounded however mailbox.default.capacity is set. |
deployment."<path>".mailbox-overflow | unset | drop-head / drop-new / reject, for any bounded mailbox of a matched actor: this entry’s capacity, a spawn-site one that names no policy, or the global one. |
Keys are absolute path patterns, in quotes. /user/ingest names one
actor; * is any run of characters inside one segment
(/user/pool/routee-*), and a segment that is exactly ** is one or more
whole segments (/user/hub/**) — the grammar parallelism.offload uses.
Quote every key: an unquoted one does not parse, and a . in an actor name
would split it. The keys carry no scheme and no system name, so they keep
matching when the system is renamed, and an actor parallelism.offload moves
onto a worker matches inside the worker too, whose system has a name of its
own.
Each leaf resolves on its own: the spawn site (ActorOptions) first,
then the matching entry, then actor.throughput / mailbox.default, then
the built-in value. withMailbox() still replaces the queue outright,
whatever the entry says.
One entry per actor, chosen whole. When several keys match, the most
specific wins: an exact path, then keys with a * but no ** segment, then
keys with a ** segment; within each, the longer literal prefix (the text
before the first *), then more literal characters, then plain string
order. A leaf the chosen entry leaves out falls through to the system layer,
never to a less specific entry — so with "/user/**" { throughput = 8 }
beside it, an empty "/user/special" { } runs /user/special at
actor.throughput.
Who wrote the class decides what an entry reaches, as for
mailbox.default: the actors your application wrote, including the sharded
entities and singleton instances the framework spawns for you under
/system, and never one of the framework’s own actors, whatever the key
says. So /system is not refused here as it is in parallelism.offload:
/system/cluster/sharding/region-orders/** bounds that region’s entities and
leaves its shards alone.
A key that matches nothing does nothing. The system refuses to start,
with a ConfigError naming actor-ts.deployment."<key>" and the leaf, on a
key that is not absolute, has an empty, . or .. segment, or can name
only the root or a guardian (/user, /*); on an entry that is not a
block; on a leaf other than the three; and on a value outside its range.
actor-ts.dispatcher
Section titled “actor-ts.dispatcher”| Key | Default | Purpose |
|---|---|---|
dispatcher.default | "hybrid" | hybrid (default) — wakes actors on the microtask queue and spends every 64th unit on a macrotask, so timers and I/O still run; immediate — the previous default, one setImmediate per turn: fair, at ~2.4 µs a hop; microtask — unbounded, starves the event loop under sustained load, for measurement only; throughput — drains up to dispatcher.throughput queued turns per tick, across actors. An unset or unrecognised value falls back to hybrid. |
dispatcher.throughput | 16 | Queued actor turns a ThroughputDispatcher drains per tick, across actors — not messages, and not per actor. See actor.throughput above for the per-actor batch. An integer from 1 up; unlike actor.throughput it is not raised to 1 — with default = throughput, a 0 or below fails ActorSystem.create with an OptionsError from ThroughputDispatcher. |
actor-ts.dead-letters
Section titled “actor-ts.dead-letters”| Key | Default | Purpose |
|---|---|---|
dead-letters.store | "off" | Ordered by how much is kept: off = publish only, keep nothing / metrics = count them, keep no payload / memory = a bounded ring / persistent = also write to the journal, so the queue survives a restart. |
dead-letters.max-entries | 1000 | Letters held before the oldest is evicted. Ignored by off and metrics, which hold none. |
dead-letters.retention | 1h | Age letters out after this long. 0 disables ageing and leaves max-entries as the only bound. |
dead-letters.max-replays | 3 | How often one letter may be replayed before it is quarantined. |
dead-letters.persistence-id | "" | Journal stream the persistent store writes to. Empty derives it from the system name, so two systems sharing a journal keep separate queues. |
Every key here is also settable in code, field by field, through
ActorSystemOptions.withDeadLetters(…) — which wins over this block, as
explicit options always do. See Dead
letters for what the queue holds and how to
replay from it.
actor-ts.cluster
Section titled “actor-ts.cluster”| Key | Default | Purpose |
|---|---|---|
cluster.gossip-interval | 1s | How often gossip is exchanged with a random peer. |
cluster.seed-nodes | [] | Peers this node announces itself to at start-up, "system@host:port" (or "host:port"). Empty = “I am the first node” — see below. |
cluster.roles | [] | Role tags this node carries. Shard regions, singletons, the per-role thresholds and the role-filtered downing strategies all place by role. |
cluster.app-version | (unset) | The application version this node states to its peers — a label for operators, shown on /cluster/members and wherever a member is printed; nothing places, routes or downs on it. Comment-only in reference.conf: unset states none and puts nothing on the wire — see below. |
cluster.seed-retry-interval | 3s | How often to retry seed connections during join. |
cluster.weakly-up-after | 0s | Auto-promote a joining member to weakly-up after this long. 0 disables it — see Weakly-up. |
cluster.publish-stats-interval | 0s | How often this node publishes a ClusterStatsPublished sample of its membership view on system.eventStream. 0 arms no timer — see below. |
cluster.shutdown-after-unsuccessful-join | 0s | How long a node may stay joining or weakly-up before it gives up the join. At the deadline, if nothing can promote it any more, it logs a warning, leaves and runs the coordinated-shutdown pipeline with ClusterJoinUnsuccessfulReason; otherwise it asks again every seed-retry-interval. 0 sets no deadline — see Joining and seeds. |
cluster.max-members | 1000 | Cap on live member entries gossip may introduce. 0 disables the cap. |
cluster.max-tombstones | 10000 | Cap on removed tombstones gossip may introduce. 0 disables the cap. |
cluster.minimum-members-before-up | 1 | Members that must be present before anything is promoted to up. 1 is the historical behaviour — see below. |
cluster.role.<role>.minimum-members-before-up | (unset) | Per-role threshold, composed with the one above as an AND. Comment-only in reference.conf, since role names are per-deployment. |
cluster.run-coordinated-shutdown-when-down | on | What a node does once its own downing decision removes it. on leaves, then runs the coordinated-shutdown pipeline with ClusterDowningReason, which ends the actor system; off leaves the membership and keeps its actors running. See below. |
cluster.down-smaller-island | off | When two same-name clusters that formed during a startup partition meet, the smaller one downs itself (on a tie, the one whose lowest address sorts higher). Off: the meeting is logged at error and the other island’s frames are refused; an operator restarts one side (#1176). |
cluster.tombstone.time-to-live | 24h | How long a removed tombstone is kept before it is pruned. |
cluster.tombstone.prune-interval | 5m | How often the prune pass runs. |
cluster.tombstone.min-retention | 0s | Floor on tombstone age before pruning is allowed. 0 derives it from failure-detector.down-after (6×). |
cluster.failure-detector.implementation | simple | Which detection algorithm this node runs — simple (elapsed-time thresholds) or phi (variance-aware φ-accrual). |
cluster.failure-detector.heartbeat-interval | 500ms | How often heartbeats are sent. Shared by both implementations — see below. |
cluster.failure-detector.unreachable-after | 2s | Suspicion threshold for unreachable status. simple only. |
cluster.failure-detector.down-after | 5s | Silence after which the verdict is down. With no split-brain strategy that removes the peer, under the default auto-down = on; with a strategy, or under auto-down = off, the peer is parked at unreachable. Measured from the last heartbeat, so it must exceed unreachable-after. simple only. |
cluster.failure-detector.auto-down | on | What a down verdict does when no split-brain strategy is configured. on lets the detector remove the peer, so the surviving nodes take over its shards and singletons — and every side of a partition then does it to the other, unless a strategy such as lease-majority is configured. off is the opt-out: it parks the peer at unreachable until a strategy, Cluster.down or POST /cluster/down removes it. Both implementations. A configured strategy decides every removal, whatever this says — see below. |
cluster.failure-detector.phi.unreachable-threshold | 8 | φ value above which the peer is flagged unreachable. A continuous score, so fractions are fine. |
cluster.failure-detector.phi.down-threshold | 12 | φ value above which the peer is flagged down. Must exceed phi.unreachable-threshold. |
cluster.failure-detector.phi.max-sample-size | 200 | How many recent inter-arrival times are kept per peer. |
cluster.failure-detector.phi.min-std-deviation | 100ms | Floor on the sampled standard deviation, so a very steady peer is not flagged on noise. |
cluster.failure-detector.phi.acceptable-heartbeat-pause | 3s | Grace added to the last heartbeat before φ starts rising — a pure offset, so a stall up to ~3.5 s past the expected beat passes at the default cadence. Chosen by measurement; see the φ-accrual detector. |
cluster.failure-detector.phi.expected-response-after | "auto" | The inter-arrival time φ assumes until a peer’s first heartbeat interval is measured, with a deviation of a quarter of it. "auto" is heartbeat-interval; a duration decouples the two. |
cluster.split-brain-resolver.active-strategy | off | Which downing strategy arbitrates a partition — off, keep-majority, keep-oldest, keep-referee, static-quorum or lease-majority. |
cluster.split-brain-resolver.stable-after | 20s | How long the membership and reachability view must hold still before the strategy is consulted — or, if it never does, half of how long one peer must have been continuously unreachable. See below. |
cluster.split-brain-resolver.down-all-when-unstable | off | Down every member, this node included, when the view never once holds still for stable-after across 3 × stable-after of churn. Off — see below. |
cluster.split-brain-resolver.keep-majority.role | "" | Only members carrying this role count toward the majority. "" counts every member. |
cluster.split-brain-resolver.keep-oldest.role | "" | Only members with this role are eligible “oldest”. "" considers every member. |
cluster.split-brain-resolver.keep-oldest.down-if-alone | on | Whether the oldest loses when it is the only member on its side, against two or more on the other. On, a crash of the oldest leaves the rest running; off, every survivor downs itself (#932). |
cluster.split-brain-resolver.static-quorum.role | "" | Only members carrying this role count toward quorum. "" counts every member. |
cluster.split-brain-resolver.static-quorum.quorum-size | (unset) | Reachable members required to keep running. Required by static-quorum; comment-only in reference.conf — see below. |
cluster.split-brain-resolver.keep-referee.referee-address | (unset) | The referee node’s address; the side containing it wins. Required by keep-referee; comment-only. |
cluster.split-brain-resolver.keep-referee.down-all-if-below-quorum | (unset) | Down everyone if the referee’s own side is smaller than this. Optional; comment-only. |
cluster.configuration-compatibility-check.enforce | off | What a divergence does beyond being reported. on also bars the diverging peer from this node’s placement candidates — see below. |
cluster.configuration-compatibility-check.checked-paths | ["actor-ts.remote.max-frame-bytes"] | Settings whose effective values this node publishes to its peers and compares theirs against. |
These are layered under whatever Cluster.join(system, options) passes, so
an explicit withGossipIntervalMs(…) still wins. The failure detector
merges per threshold: setting only down-after in code keeps the other
two from the file. The phi block merges the same way, per field, against
withPhiAccrual(…).
heartbeat-interval is deliberately outside phi and has no copy inside
it. The cadence belongs to the cluster’s heartbeat loop rather than to
either algorithm, so switching implementation cannot change how often this
node talks to its peers. phi.expected-response-after follows it under
auto: the detector resolves the word against the cadence it is given, so a
heartbeat-interval tuned in this file or in code carries the estimate
along. auto-down sits outside phi for the same reason: both detectors
reach a down verdict, so what that verdict does is not a property of
either. Everything else under failure-detector belongs to exactly one
implementation and is ignored by the other.
The HOCON tree and the ClusterOptions fields are deliberately not
isomorphic: the three tombstone knobs are grouped under tombstone because
that is how you tune them, while the fields stay flat
(withTombstoneTtlMs(…), …). remote.tcp.host → host already makes the
same translation.
min-retention = 0s means derive the floor from the failure detector,
not no floor — the same thing leaving the field unset means, so a file
that spells the default out behaves like one that omits it.
The two max-* caps bound the local member map. remote.max-frame-bytes
bounds one gossip frame; these bound what a sequence of well-formed frames
can accumulate, which is a different quantity — see
Cluster security.
publish-stats-interval arms a fifth periodic task on this node, and only
when it is positive: every interval it publishes one
ClusterStatsPublished — member count, up count, unreachable count,
leader and this node’s address — on system.eventStream and to every
cluster.subscribe listener. Every figure is already reachable through the
Cluster API; what the key buys is the cadence. It is node-local and
deliberately not on the cluster-wide cluster.eventStream, where a per-node
periodic sample would cost N frames per node per interval. It is also
actor-ts.devtools.stats-interval’s sibling rather than its replacement:
same figures, different channel, and neither forwards into the other. See
Cluster overview.
split-brain-resolver.active-strategy names a strategy rather than
describing one, which is why the object it builds needs no HOCON shape of
its own. The provider it constructs lands in the same slot
withDowning(…) fills, and the same precedence applies: an explicit
withDowning(…) wins, an absent one falls through to the file. See
Downing strategies for what each strategy
decides.
Three of its keys ship comment-only in reference.conf, so they are
absent until you write them. Each is required or bounded and has no legal
default: quorum-size = 0 and referee-address = "" are both refused by
the strategies’ own validators, so a shipped leaf could only be a value
that stops the node from starting. Naming static-quorum without
quorum-size, or keep-referee without referee-address, is refused at
startup with the missing key in the message.
lease-majority arbitrates through a lease the framework builds from
actor-ts.coordination.lease, so it needs a
backend there: with the shipped backend = none the strategy is refused at
startup rather than run with nothing to arbitrate through. The lease is
named <system>-split-brain-resolver, owned by this node, and built at the
strategy’s first decision — the node’s address does not exist yet when the
strategy does. There is no lease-majority block: its role and acquire
timeout stay in code, withDowning(new LeaseMajority(…)), and a key written
under split-brain-resolver.lease-majority is refused.
stable-after and down-all-when-unstable are the block’s policy half:
they decide when the strategy is asked, not which one. Both are ignored
while active-strategy = off. With no resolver there is no decision for a
window to delay: by default the failure detector removes a peer it declares
down itself, at failure-detector.down-after, and under
failure-detector.auto-down = off it parks the peer at unreachable until
someone removes it — a second window in front of that would be two
thresholds for one decision.
failure-detector.auto-down is the switch for that no-resolver case; beside
a configured strategy it changes nothing, because the strategy decides every
removal whatever it says. on is the default because an n-node cluster has
to stay operational with only one node left: a crashed peer is removed at
down-after, and the last available node takes over its shards and
singletons. The price is paid under a partition: the detector cannot tell a
crash from one, every side’s detector reaches down-after for the other side
at about the same moment, and removing on that verdict forks the cluster into
two that do not merge again when the network heals — configure
lease-majority or another strategy for production. off is the opt-out,
and its price is paid on a crash: the crashed node stays a member, its shards
are not reallocated and its remote watchers get no Terminated, until a
strategy, Cluster.down or POST /cluster/down (with
actor-ts.management.enable-down-endpoint = on) removes it, or it restarts
on the same address. The node logs one warning per parked peer naming those
three. See the failure detector.
stable-after is what makes a decision be about a settled fact. Every
bundled strategy is a pure function of one view, so a view read mid-churn —
half the peers already unreachable, the rest about to be — yields a verdict
about a cluster that existed at no instant. The clock is the
failure-detection tick, so the effective resolution is
failure-detector.heartbeat-interval: invisible at twenty seconds, worth
knowing at two hundred milliseconds. There is deliberately no upper
bound tying it to failure-detector.down-after: with a strategy configured
the detector parks an unreachable peer and evicts nothing, so the window has
no deadline to out-run.
It is a preference rather than a precondition. The view it watches is every
member’s address and status, so any join, leave or transition anywhere
restarts it — and a deployment whose membership moves more often than
stable-after would otherwise never arbitrate a partition at all, with the
detector no longer evicting to fall back on. A peer that has been
continuously unreachable for 2 × stable-after is therefore put to the
strategy whatever else is moving. That multiple sits above one window, so a
view that does settle is always arbitrated the ordinary way first, and below
the 3 × stable-after escalation deadline, so a strategy is asked before
down-all-when-unstable can stop the cluster.
down-all-when-unstable is the escalation for the cluster that never
settles: when the view has not once held still for a whole stable-after
across 3 × stable-after of continuous change — and something is still
unreachable — every member is downed, this node included, and the log says
so at warn. The margin is derived rather than configured, because it only
ever means “several times however long this deployment thinks a view needs to
settle”, and a margin below the window could never observe one quiet window
before firing.
It ships off, and turning it on is a durability-over-availability
posture rather than a detail. It is the only setting in this subsystem that
stops the whole cluster, and it is reached by a timer rather than by a
strategy’s verdict — a rolling restart whose replacements arrive less than
stable-after apart looks exactly like a cluster that will not settle. A
view that moves only because members join and leave cleanly never escalates:
churn is not a partition, which is why an empty unreachable set is a hard
precondition.
run-coordinated-shutdown-when-down is what a node does once its own
downing decision removes it — a strategy’s verdict that includes this node,
or down-all-when-unstable. Under off it only leaves: its peers stop
counting it, but the node keeps running its actors — the entities and
singletons it hosted, an HTTP binding — beside the side that won, which is the
second writer a downing decision exists to prevent. Under on, the default,
it leaves and then runs the
coordinated-shutdown pipeline
with ClusterDowningReason, even when the leave fails;
coordinated-shutdown.terminate-actor-system and exit-process decide what
that run ends in, as they do for a signal. The price of on is that a wrong
self-down terminates a node; the two known ones — static-quorum downing a
cluster still smaller than quorum-size
(issue #933), and
keep-oldest downing every survivor once the lowest-addressed node crashed
(issue #932) — are fixed,
which is when the default moved to on. A downing a peer decides about
this node reaches the switch only through this node’s own strategy: a peer
that removed it refuses its heartbeats, and a node every peer refuses has its
strategy asked at once
(issue #940).
configuration-compatibility-check compares effective values, not config
values. Each node publishes what it actually resolved for every setting in
checked-paths and compares what its peers publish back, so two nodes that
differ only because one called .withMaxFrameBytes(…) are still caught —
which comparing the config tree could not do, since an explicit option sits
above it. checked-paths is an allow-list of what leaves the node, so a
setting absent from it is never gossiped; only names something publishes can
be compared, and the framework publishes three of them (see
Joining and seeds). Absence on either side is
silence, so a mixed-version cluster reports nothing rather than everything.
enforce = on bars the diverging peer from this node’s placement candidates
and does nothing else. It never downs or quarantines anyone: a misconfigured
majority would then evict the correctly-configured minority, which turns a
warning into an outage — and the candidate set is a per-node view, so nothing
that elects a role from it (a singleton’s host, a shard’s home) reads it,
or two nodes would elect two winners.
minimum-members-before-up holds the joining / weakly-up → up
transition until the local member map holds at least that many members —
the leader’s promotions and a founder’s own self-election alike. It counts
members in joining, weakly-up and up, so a leaving member does not
hold the threshold open for its replacement, and it is never evaluated in
reverse: there is no up → joining transition, so a cluster that later
shrinks keeps the members it promoted and holds only new ones.
Per-role thresholds compose with it as an AND — the global count and
every configured role’s count must be met. They are written
cluster.role.<role>.minimum-members-before-up and ship comment-only, since
no leaf here could name a role your deployment invented. What they buy is
“do not place work on a cluster that has no backend yet”: shard regions and
singletons are hosted by role, so an all-frontend cluster satisfies a global
count while being useless to place on.
It is not cluster.bootstrap.minimum-members, which is a wait
predicate for awaitReady / isReady and never changes a member’s status.
Setting this one largely subsumes that one — a node that is up at all
already implies the threshold was met — so there is rarely a reason to set
both. And it is not a quorum or a security control: any node may
announce itself up, so it bounds accidents rather than adversaries.
Arbitration is split-brain-resolver above; note that static-quorum has no
“nothing is unreachable” early return yet, so pair a threshold above 1 with
a downing strategy you have checked at that cluster size.
While the threshold is unmet the node stays joining, and it says so once —
naming the key and the current count — rather than reporting the cold-start
stall diagnosis, which would be a false verdict here. See
Joining and seeds.
seed-nodes is one list that is correct on every node of a deployment,
which is why it is a key at all. A node removes its own address from the
list before dialling, so naming the designated first node and shipping the
same file everywhere leaves that node with an empty list — and self-electing
— while every other node dials it. The shape that does not work is the
symmetric one, every node listed: self-exclusion then leaves nobody with the
empty list selfElection: 'immediate' requires, so nobody is ever promoted.
Config does not create that trap, and the node
diagnoses it, but it does make it a one-line
mistake — cluster bootstrap with stable
observation, which stays a code option, is the way out when the members are
not known in advance.
Both leaves are read as lists and only as lists, so a single
seed-nodes = ${?SEED_NODES} is refused at start-up rather than split on
commas. Write one optional substitution per entry — unset ones drop out of
the array:
actor-ts.cluster { seed-nodes = [ ${?SEED_1}, ${?SEED_2}, ${?SEED_3} ] roles = [ ${?NODE_ROLE} ]}For the single comma-separated variable, seedsFromEnv(...) in code is the
first-class form — see seed providers.
A malformed entry is refused by Cluster.join before the transport binds,
with the offending string in the message.
cluster.seed-nodes and discovery.config.seeds are not two answers to one
question, and the order between them is fixed: Cluster.bootstrap runs
discovery first and forwards what it found, so a discovered seed wins; this
key applies when discovery named nobody or only this node — a discovered list
that is this node alone is filtered to nothing, which is silence.
CLUSTER_SEEDS is a rung of the same discovery ladder, so a seed it names
wins over this key too. An explicit seeds: [] passed to Cluster.bootstrap
still wins over both — it says “there is nobody else”, which is an answer
rather than a silence, and it is refused while
cluster.bootstrap.new-cluster-enabled is off. See
actor-ts.discovery.
app-version is the application version this node states to its peers, so
the window of a rolling update in which old and new code share one cluster
can be read off the cluster itself: it is shown on
GET /cluster/members
and in every log line that prints a member. It is a label and nothing more —
nothing places, routes or downs on it. It ships comment-only, the
remote.tcp.advertised-host shape: unset states no version and puts nothing
on the wire. It changes per release rather than per node, so the
substitution is the usual form, and an unset variable drops the key:
actor-ts.cluster.app-version = ${?APP_VERSION}A literal version goes in quotes: app-version = 1.0 is a number to HOCON
and reaches the peers as "1".
A value from the environment is read as JSON first wherever it parses as
JSON. A version that reads as a number comes back in that number’s own
spelling — 1.10 as 1.1, 2.0 as 2, 1e3 as 1000 — so releases 1.1
and 1.10 print the same label, a whole number past Number.MAX_SAFE_INTEGER
can come back with other last digits (20261104123456789 as
20261104123456788), and one that reads as null, a list or an object stops
the start with a ConfigError; a version with a second dot (1.2.3) or a
letter (v1.10) is unchanged. Quote such a value inside the variable
(APP_VERSION='"1.10"'), or set it in code with withAppVersion(...).
A label is 1 to 64 visible ASCII characters — no whitespace and no control
character, because every peer prints it — and Cluster.join refuses one that
is not, an empty one included, before the transport binds. A peer’s label
that breaks the rule is dropped, never the member. withAppVersion(...) in
code wins over the file, as explicit options always do.
selfElection and the transport have no HOCON form. The transport is an
object a config file cannot express. selfElection is the one setting whose
shared value is not merely useless but unsafe: all-'never' never starts a
cluster and all-<delay> has every node self-elect at the same moment, which
is the split brain the option exists to close — cluster bootstrap is what
hands out a per-node value.
The standalone ClusterClient
Section titled “The standalone ClusterClient”| Key | Default | Purpose |
|---|---|---|
cluster.client.contact-points | (unset) | Cluster nodes a client with no explicit list dials — each host:port or <system>@host:port, tried in order. Comment-only in reference.conf; see below. |
cluster.client.system-name | "cluster-client" | Synthetic system name the client puts in its hello. It names the client’s side of the handshake and is not an identity. |
cluster.client.ask-timeout | 5s | Deadline for ask(path, message) when the call itself names none. A per-call timeoutMs still wins. |
cluster.client.connect-timeout | 5s | How long one contact point gets to answer the hello handshake before the client gives up on it and dials the next. |
cluster.client.receptionist.ask-timeout | 5s | Deadline for the ask a cluster node makes on a client’s behalf when an arriving envelope carries an askId. |
This block is read differently from every other one on this page, and
ClusterClient is why: a client is by definition
outside the cluster, so it holds no ActorSystem and there is no
system.config above it. Its constructor therefore loads the configuration
itself — the same chain ActorSystem.create uses, ACTOR_TS_CONFIG then
./application.conf then the built-in defaults — which is what makes a client
built with no options at all a configurable thing rather than a broken one.
Pass a Config as the constructor’s second argument to pin it instead, and
the filesystem is never consulted.
The receptionist half is the asymmetric one. ClusterClientReceptionist
runs inside a system, so it reads that system’s config and loads nothing.
It nests under cluster.client rather than joining
actor-ts.cluster.receptionist above, which belongs to the discovery
Receptionist — a different actor with a different protocol that happens to
share the word.
contact-points ships comment-only, the same shape as
remote.tcp.advertised-host: the list is per-deployment identity that no
default could state, and [] is not the absence of one — an empty list is
refused by the validator, so a shipped leaf could only be a value that stops
every client that merely copied the file.
client-identity, tls and logger have no HOCON form at all. The last two
are certificate material and a Logger instance. The first is the one that
is a security decision rather than a packaging one: a client’s synthetic
port is drawn from the CSPRNG so that no peer can predict, address or
pre-claim its slot, and a fleet sharing one configured value is exactly what
that draw exists to prevent. Set it with withClientIdentity(host, port) if
you need a stable one.
The transport has no HOCON form — it is an object a config file cannot
express. seeds and roles do have one, cluster.seed-nodes and
cluster.roles above: they are per-deployment identity, which is why each
entry takes its own optional substitution rather than a shared default. A
per-role threshold names a role rather than assigning one, so it reads from
the file even though the assignment still happens at the join site.
actor-ts.cluster.singleton
Section titled “actor-ts.cluster.singleton”| Key | Default | Purpose |
|---|---|---|
cluster.singleton.role | "" | Restrict hosting to nodes carrying this role tag. "" = any node may host; the empty string is dropped, never passed on. |
cluster.singleton.buffer-size | 1000 | Messages a proxy holds while the cluster has no host, before it drops the newest to dead letters. |
cluster.singleton.hand-over-timeout | 10s | How long an incoming host waits for every eligible peer to confirm it is not running the singleton, before hosting anyway. |
cluster.singleton.use-lease | off | Give every singleton this node starts a lease built from actor-ts.coordination.lease, so only the holder hosts. Refused at start() while coordination.lease.backend = none; a withLease(…) in code wins, and withUseLease(false) opts one singleton out. |
cluster.singleton.acquire-retry-interval | 5s | How long the manager waits before re-acquire()ing a lease it failed to take. Only reached when the singleton has a lease — passed in code, or built by use-lease. |
cluster.singleton.max-hand-over-state-bytes | 1M | Cap on a warm-hand-over snapshot. A snapshot above it is not sent and the successor starts cold. |
cluster.singleton.restart-on-termination | on | Re-spawn the singleton after its instance dies unexpectedly — as against the planned teardown of a hand-over. |
The block is read by both doors, and the second one is why it exists.
cluster.singleton.start(...) layers it under the caller’s
StartSingletonOptions, so an explicit withBufferSize(…) still wins per
field. cluster.singleton.ref(...) takes no options object at all, so
before this block a proxy-only node had no way whatsoever to set its buffer
cap — or to learn that the singleton is role-restricted, which is worse: a
configured role reaching only start() leaves such a node routing at the
plain leader while the managers host on the role member.
Precedence has one turn that reads backwards: a role declared on the actor
class’s SingletonKey — or passed to withRole(…) — beats the config
file, because both are code and code is the higher layer. That holds on the
proxy too, and in either call order: a node that calls ref before start
builds its proxy from the file, and the explicit role the start carries then
replaces it rather than losing to it. A configured role arriving after an
explicit one is discarded in silence for the same reason — it is precedence
resolving, not a problem to report.
What the proxy does warn about is two roles from the same layer — two
withRole calls, or a key and an options object that disagree. One singleton
cannot be restricted two ways and nothing outranks anything, so it keeps the
first and names the second in the log.
role = "" is the shape of the key, not a value anyone runs with. It is
dropped rather than passed on, and here that is load-bearing twice over: ''
would shadow an explicit withRole(…) on the layer above, and
StartSingletonOptionsValidator refuses an empty role outright, so a node
that copied the shipped file unedited would fail every start().
use-lease builds the singleton’s lease from
the coordination block: named
<system>-singleton-<type>, owned by this node — its cluster address and
incarnation — and renewed on the system’s scheduler. The file picks the
backend and nothing about identity, so there is no lease-name: one value for
the block would put every singleton on one record, and one written there is
refused by start() and ref() alike.
Two more keys are deliberately not here.
singleton-identification-interval configures a poll this proxy does not do
(it subscribes to cluster events instead), and
min-number-of-hand-over-retries counts attempts nothing counts — the wait
is bounded by hand-over-timeout. The hand-over re-send cadence is a
correctness property of the exchange rather than a tuning knob, and stays a
constant.
actor-ts.cluster.pub-sub
Section titled “actor-ts.cluster.pub-sub”| Key | Default | Purpose |
|---|---|---|
cluster.pub-sub.gossip-interval | 1s | How often a mediator pushes its topic set to a random peer. |
cluster.pub-sub.max-subscribers-per-topic | 10000 | Cap on local subscribers for one topic. A Subscribe past it is answered with SubscribeRejected. |
cluster.pub-sub.max-topics | 10000 | Cap on distinct topics one mediator tracks — enforced against gossiped topic claims as well as local subscribes. |
cluster.pub-sub.max-remote-nodes-per-topic | 1000 | Cap on peers that may claim subscribers for one topic. |
cluster.pub-sub.send-to-dead-letters-when-no-subscribers | on | Route a publish that reached nobody to system.deadLetters instead of discarding it. |
The three caps bound what one mediator can be made to hold, and publish
fan-out walks all of them — so they are a latency bound as much as a
memory one. The gossip half is the one worth knowing about: a peer
announcing topics it claims subscribers for used to allocate an entry per
name on every receiver, with no local Subscribe involved. See
DistributedPubSub.
actor-ts.cluster.receptionist
Section titled “actor-ts.cluster.receptionist”| Key | Default | Purpose |
|---|---|---|
cluster.receptionist.gossip-interval | 1s | How often the receptionist gossips its local registrations. |
cluster.receptionist.max-subscribers-per-key | 1000 | Cap on subscribers for one service key. A Subscribe past it is answered with ReceptionistSubscribeRejected. |
cluster.receptionist.max-subscriptions-total | 10000 | Cap on key/subscriber pairs across every key on this node — one subscriber on three keys counts as three. |
Both blocks layer under whatever the extension’s start(...) was passed,
so an explicit withMaxTopics(…) still wins. Stopped subscribers are
released by death watch and do not count against either cap.
actor-ts.distributed-data
Section titled “actor-ts.distributed-data”| Key | Default | Purpose |
|---|---|---|
distributed-data.gossip-interval | 1s | How often a replica pushes its key set to a random peer. |
distributed-data.quorum-timeout | 5s | Deadline for an updateAsync / getAsync that names no timeoutMs; a per-call timeoutMs still wins. Clamped by max-quorum-timeout like a caller’s value. Must be positive. |
distributed-data.max-pending-quorum-requests | 1000 | Cap on unsettled quorum requests — updateAsync and getAsync share one budget. A request past it is rejected outright. 0 disables the cap. |
distributed-data.max-quorum-timeout | 30s | Ceiling on a quorum deadline — a call’s own timeoutMs, or quorum-timeout when it names none; a larger value is clamped down to this one. 0 disables the ceiling. |
distributed-data.max-gossip-bytes | 1M | Byte budget for one gossip frame’s payload. A larger store is pushed a slice per tick, resuming where the last one stopped. 0 removes the budget. |
distributed-data.log-data-size-exceeding | 100K | Warn (rate-limited) about a key whose own encoding passes this many bytes. Reports only — the key is gossiped exactly as it would have been. 0 never warns. |
distributed-data.durable-keys | [] | Which keys a configured durableStore persists. Empty means every key. An entry is an exact key name or a prefix with one trailing *. |
max-gossip-bytes is always clamped down to remote.max-frame-bytes, so
lowering the wire cap lowers the gossip budget with it and no setting can put
gossip back over the edge. It matters because the two failures are not
comparable: a frame past the wire cap is rejected on its 4-byte length prefix
and the receiving transport drops the whole peer association — heartbeats,
membership gossip and every cross-node tell along with it — while a budget
merely spreads the same state over more ticks. A single key whose own encoding
exceeds the budget cannot be sliced; it is skipped with a rate-limited warning
naming the key and both sizes, counted in
distributed_data_gossip_skipped_keys_total, and it does not converge.
The block is top-level rather than under cluster.* (where pub-sub and
receptionist live) because the module is: DistributedData ships from
src/crdt/, and the cluster is a positional argument to start(cluster)
rather than one of its tunables. durableStore has no key here — it is a
DurableStateStore instance, which a config file cannot express.
Both caps bound the unsettled set itself. Every pending quorum request holds
a promise, a timer and a target set alive until its deadline passes, so an
uncapped replicator under load accumulates all three with nothing to stop it.
Refusing past max-pending-quorum-requests turns what would arrive later as a
timeout storm into immediate rejections that name the knob. See
Quorum reads and writes.
log-data-size-exceeding reports on the same measurement max-gossip-bytes
takes, one order of magnitude earlier, and changes nothing about what travels.
A key past the whole budget is already loud; a key at a large fraction of it
gossips perfectly while consuming that fraction of every tick it appears in, so
the rest of the store sweeps proportionally slower with nothing to say why.
100K is roughly a tenth of the shipped budget — ten such keys fill a whole
frame — and deliberately not Akka’s 10KiB, which is a tenth of that again and
would fire on the first legitimate ORSet a deployment stores. The line has
its own quiet period rather than sharing the oversize warning’s: raising
max-gossip-bytes is the fix for that one and makes this one more relevant,
so neither may silence the other.
durable-keys narrows what a configured durableStore writes; without a store
it is inert, and a non-empty list with no store is warned about at startup.
An empty list means every key — the behaviour of every release before the
option existed — never “persist nothing”; persisting nothing is what
configuring no store does. An entry is an exact key name or a prefix with one
trailing * (session-*), and that is the entire syntax: a richer pattern
would mean compiling a matcher out of a config file, and new RegExp(…) over
operator-supplied text is a ReDoS surface on the path that decides what
survives a restart. A replica’s record is rewritten whole on every save, so
removing an entry drops the keys it named from the persisted record on the
next mutation. See
Durable storage.
max-quorum-timeout bounds the other axis. A pending request holds one of
those slots for its whole deadline, so a single caller passing an hour-long
timeoutMs parks the budget for an hour and locks out later callers who
never came near the cap themselves.
quorum-timeout is the deadline a quorum call gets when it names none, and
max-quorum-timeout clamps it exactly as it clamps a caller’s timeoutMs.
It is a key of its own rather than actor.ask-timeout: that one moves the
default of ActorRef.ask, and how long a replica holds a pending slot for its
peers to answer is a different wait. Unlike the two caps it has no off
switch, and 0 cannot be one: the replicator arms a 0 deadline like any
other, so it expires at the next timer tick — a write fails there and a read
settles for what this replica alone holds — unless every replica it waits on
has already answered, and the validator refuses it.
actor-ts.coordination
Section titled “actor-ts.coordination”| Key | Default | Purpose |
|---|---|---|
coordination.lease.backend | none | What the framework builds its leases with — none or kubernetes — when a consumer’s switch asks for one. in-memory is refused by name. See leases the framework builds. |
coordination.lease.ttl | (unset) | Lease TTL for the whole deployment. Ships no leaf — a value here would supply ttlMs for every lease in the process and make the “ttlMs is required” guard unreachable. |
coordination.lease.renewal-interval | (unset) | How often a held lease is renewed. Ships no leaf — unset selects a third of the TTL with a floor (100 ms in-memory, 500 ms Kubernetes), capped at half the TTL so a renewal always comes round before the record lapses, and 0 cannot mean “derive it” because the validator rejects it. |
coordination.lease.kubernetes.namespace | (unset) | Namespace holding the Lease object. Ships no leaf — unset means “read namespace-path from the Pod’s ServiceAccount mount”, and "" is rejected. |
coordination.lease.kubernetes.namespace-path | "/var/run/secrets/kubernetes.io/serviceaccount/namespace" | File the Pod’s namespace is read from. |
coordination.lease.kubernetes.token-path | "/var/run/secrets/kubernetes.io/serviceaccount/token" | File the bearer token is read from. A path, never the token. |
coordination.lease.kubernetes.ca-path | "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt" | File the CA cert pinning the API server’s TLS is read from. |
coordination.lease.kubernetes.token-reload-interval | 1m | How long a credential read from that mount is reused before the token file’s mtime is checked again. No effect on an explicit authToken. |
coordination.lease.kubernetes.operation-timeout | 10s | Ceiling on one API-server request. |
coordination.lease.kubernetes.lease-name-max-length | 253 | Lease object names longer than this are truncated to a stable head plus a hash of the full name. 253 is the DNS-1123 subdomain bound the API server enforces. |
The block serves two kinds of lease. One the framework builds for a consumer
that asks reads it from the node’s own configuration — see
below. One you build in code reads it
under the options you pass to new InMemoryLease(…) /
new KubernetesLease(…), in the usual order: explicit options win, then this
block, then the built-in defaults. Such a lease may have no ActorSystem in
scope, so its constructor loads the config chain itself, honouring
ACTOR_TS_CONFIG and ./application.conf — unless you hand it one:
new KubernetesLease(options, system.config) reads that config and nothing
else, overrides included.
Three keys ship no leaf at all and are listed above only so the names are
discoverable. Each is a field the code requires or derives, and a shipped value
would make hasPath true forever — which is precisely how the thing it stands
in for becomes unreachable. Set one in your own application.conf and it is
read normally:
actor-ts.coordination.lease { ttl = 30s kubernetes.namespace = "actors"}acquire-retries and acquire-retry-delay are not settable here. The two
backends ship different built-in defaults — 3 attempts / 100 ms for Kubernetes,
1 / 50 ms in memory — and one leaf could not express both without silently
unifying them. Set them per lease in code.
Leases the framework builds
Section titled “Leases the framework builds”Three consumers ask for a lease by configuration, and all three get it from this block:
| Switch | Lease name | Refused, if misconfigured, when |
|---|---|---|
sharding.use-lease = on | <system>-sharding-<type>, one per sharded type | the type starts |
cluster.singleton.use-lease = on | <system>-singleton-<type>, one per singleton | the singleton starts |
split-brain-resolver.active-strategy = lease-majority | <system>-split-brain-resolver, one per cluster | the node joins its cluster |
actor-ts.coordination.lease { backend = kubernetes ttl = 15s}actor-ts.cluster.singleton.use-lease = onThe file chooses the backend and its tuning, and nothing about identity. The
name is derived per consumer — lower-cased into a valid Kubernetes object
name, with a hash of the original appended when that changed it, so
OrderService and orderservice stay two records — and fitted into
kubernetes.lease-name-max-length. The owner is the node that builds the
lease: its cluster address and its incarnation, so a restarted pod waits out
its predecessor’s TTL instead of inheriting a record the predecessor may still
be acting on. Neither has a key; name, owner, plugin, acquire-retries
and acquire-retry-delay written into this block are refused rather than
ignored, and so are a lease-name in the sharding or singleton block and any
key under split-brain-resolver.lease-majority.
What else is refused, each naming the key: a switch that asks for a lease
while backend = none, an unknown backend, in-memory — its store lives in
one process or worker thread, so a lease built from it would gate nothing —
and a missing ttl, which no default can stand in for. The block itself is
checked whenever a node joins its cluster, so a misspelt backend does not wait
for the first consumer that asks. An explicit withLease(…) still wins over
a switch, and withUseLease(false) opts one sharded type or singleton out of
a deployment-wide on.
A backend that is named but cannot be reached — no API server, no
ServiceAccount mount, credentials the server rejects — is not refused at
startup, because nothing in a file can tell. The consumer starts with its
lease and fails closed: every acquire that fails is retried — the singleton
manager and the coordinator log it at warn and wait out their
acquire-retry-interval, lease-majority asks again at its next decision —
and until one succeeds no node hosts the singleton, the coordinator allocates
no shards and lease-majority reaches no verdict. Nothing runs as though it
held a lease it could not acquire.
Persistence’s per-entity lease() hooks on PersistentActor and
ReplicatedEventSourcedActor stay code: they need a lease per persistence id,
which a switch cannot express.
actor-ts.cluster.bootstrap
Section titled “actor-ts.cluster.bootstrap”| Key | Default | Purpose |
|---|---|---|
cluster.bootstrap.stable-margin | 5s | How long the contact-point set must be unchanged before the observation calls it stable. |
cluster.bootstrap.poll-interval | 1s | How often discovery is polled during the observation. |
cluster.bootstrap.max-wait | 60s | Total budget for the observation before it gives up and fails the bootstrap. |
cluster.bootstrap.required-contact-points | 1 | How many contact points a stable set must contain. 1 keeps single-node development working; a value matching the expected replica count is what catches discovery that is stably wrong rather than merely slow. |
cluster.bootstrap.self-election-grace | 10s | How long the lowest-addressed node waits for a peer to promote it before forming a cluster itself. |
cluster.bootstrap.new-cluster-enabled | on | Whether a node that finds nobody to join may found a cluster. on is right for a deployment’s first start only, and every start logs a warning while it is; set it off once the cluster exists. Off, no bootstrapped node self-elects, on either path, and an explicit seeds: [] is refused — a node that finds nobody fails its readiness wait instead of starting alone. |
cluster.bootstrap.minimum-members | 1 | Fewest up members — self included — before awaitReady / Cluster.isReady counts the cluster as ready. |
cluster.bootstrap.await-ready | (unset) | Readiness budget. Comment-only in reference.conf: unset is what selects the computed default (self-election-grace + 5s behind stable observation with new-cluster-enabled on, 5s otherwise), and a key that is always present could not express it. |
cluster.bootstrap.discovery.method | "auto" | Which seed provider the bootstrap builds — auto, config, dns or kubernetes. auto is the ladder; the other three pin one rung so a misconfigured deployment fails loudly instead of falling through. |
cluster.bootstrap.discovery.service-name | "" | The DNS name the dns provider resolves and the Kubernetes Service whose Endpoints the kubernetes provider reads. "" means “not stated here”, and CLUSTER_SERVICE_NAME then answers. |
The five observation timings are read only when stableObservation is on;
new-cluster-enabled, the readiness pair and the discovery sub-block are
read by every Cluster.bootstrap call. All of them layer under the explicit
options, so a withRequiredContactPoints(…), a discovery: 'dns' or a
withNewClusterEnabled(false) in code still wins.
A method outside those four names is refused, not ignored. Falling back
to auto on a typo would leave one node discovering differently from its
peers, which is the cold-start split brain the observation exists to close.
selfElection has no key here and will not get one: it differs per node by
construction, so one shared value would either stop every node from starting
or have all of them form a cluster at once. new-cluster-enabled is the
shared value that is safe: it picks no policy per node, it only takes
“found a cluster” off the table, so off on every node of a running cluster
is correct on all of them. See Cluster
bootstrap.
actor-ts.discovery
Section titled “actor-ts.discovery”| Key | Default | Purpose |
|---|---|---|
discovery.dns.cache-ttl | 60s | How long the DNS provider reuses one resolved answer. In-process and per provider; failures are never cached. 0 disables caching. |
discovery.dns.use-srv | false | Read SRV records instead of A records. SRV carries a port per target, so each address is paired with the record’s port rather than this node’s remoting port. |
discovery.dns.pinned-addresses | (unset) | CIDRs (A-record mode) and/or host suffixes (SRV mode) a resolved address must match; anything else is discarded rather than offered as a seed. Comment-only in reference.conf, because an always-present empty list could not say “no pinning” — see below. |
discovery.kubernetes.request-timeout | 10s | Ceiling on the one HTTPS request the Kubernetes provider makes to the API server — a deadline on the whole exchange, TLS handshake included, so a server that accepts the connection and never answers fails the lookup instead of hanging the bootstrap. |
discovery.kubernetes.namespace | (unset) | Namespace whose Endpoints object the Kubernetes provider reads. Comment-only in reference.conf, for a different reason than the pin lists: CLUSTER_NAMESPACE sits underneath it, so a published value would be the config layer on every node and the variable would be unreachable. Unset, the chain is this key, then the variable, then the built-in "default". |
discovery.kubernetes.pinned-addresses | (unset) | CIDRs the discovered pod IPs must fall inside. CIDRs only — Endpoints resolve to IPs, so a host suffix could never match. Comment-only, same reason. |
discovery.config.seeds | (unset) | Static [system@]host:port list — the first rung of the auto ladder and the whole of method = "config". A deployment topology: one list is correct on every node when it names the designated first node by the address it advertises; a list naming every node never cold-starts without stableObservation. Comment-only for precedence: CLUSTER_SEEDS sits beneath it, and even a published [] would silence it — [] drops this rung rather than meaning “unset”, and method = "config" refuses it. |
Top-level rather than under cluster.* for the reason distributed-data is:
the module is. A SeedProvider is built and then handed to the cluster, and
the same providers serve a hand-wired Cluster.join that never bootstraps.
Which provider runs is not here either — that is
cluster.bootstrap.discovery.method above, a property of the join rather than
of a provider, so a deployment can pin the DNS answer without also deciding
the ladder.
A static seed list has two homes, and the order between them is fixed. Under
Cluster.bootstrap discovery runs first and what it returns is forwarded —
discovery.config.seeds, or CLUSTER_SEEDS when the file names none, both
rungs of this ladder — so a discovered seed wins, and
cluster.seed-nodes applies only when discovery named
nobody or only this node. An explicit seeds: [] passed to
Cluster.bootstrap outranks both, while new-cluster-enabled allows it at
all. Either list is written the same way: name
the designated first node and ship one file everywhere. A list naming every
node is
the symmetric trap
in both homes.
Where the environment sits
Section titled “Where the environment sits”Discovery has always been steerable by CLUSTER_SEEDS,
CLUSTER_SERVICE_NAME and CLUSTER_NAMESPACE. Those variables kept their
meaning and moved below this block rather than above it:
explicit options > actor-ts.discovery.* > CLUSTER_* > built-in defaultswhich is the framework’s ordinary precedence with the environment appended at
the bottom, not a fourth layer bolted on top of it. An env-only deployment
therefore behaves exactly as it did before these keys existed, and an
application.conf can now override a variable it could not previously reach.
That last claim is about reference.conf as much as about the ordering, and it
is what decides which of these keys may ship a value at all. Presence is the
read — a published leaf is a configured value on a node that configured nothing
— so a key with a CLUSTER_* variable beneath it ships comment-only:
discovery.kubernetes.namespace and discovery.config.seeds, with
cluster.bootstrap.discovery.service-name solving the same problem the other
way, published as "" and dropped by its reader. cache-ttl, use-srv and
kubernetes.request-timeout carry published values because nothing sits
under them to shadow.
A deployment that wants a variable to outrank its own application.conf
lifts it there itself:
actor-ts.cluster.bootstrap.discovery.service-name = ${?CLUSTER_SERVICE_NAME}actor-ts.discovery.kubernetes.namespace = ${?CLUSTER_NAMESPACE}That is a read during parsing (see Environment substitution), not a precedence layer — the value lands in whichever config layer the file belongs to, and the usual order applies from there.
actor-ts.remote
Section titled “actor-ts.remote”| Key | Default | Purpose |
|---|---|---|
remote.tcp.host | (unset) | The interface to bind. Read when the options leave host unset. Comment-only in reference.conf: on the Cluster.bootstrap path CLUSTER_HOST / POD_IP / HOSTNAME sit beneath it, and a published value would make them unreachable. Unset, the chain goes on through those variables (bootstrap only) to the built-in "0.0.0.0" — a wildcard belongs here and is the default. |
remote.tcp.advertised-host | (unset) | The address peers dial — this node’s identity. Unset, it follows remote.tcp.host when that is routable, then CLUSTER_HOST / POD_IP / HOSTNAME, then loopback. A wildcard is refused. Deliberately absent from reference.conf, because a shipped value is what “unset” would have to be distinguishable from. |
remote.tcp.port | (unset) | The port to bind. Read when the options leave port unset. Comment-only for the same reason, with CLUSTER_PORT beneath it on the bootstrap path; the built-in default is 2552. |
remote.tcp.advertised-port | (unset) | The port peers dial. Unset means the same as remote.tcp.port — set it only where the deployment publishes the process on a different one. Absent from reference.conf for the same reason as advertised-host. |
remote.max-frame-bytes | 16M | Per-frame wire cap. A frame whose length-prefix exceeds it is rejected before any payload is buffered. |
remote.tls.enabled | false | Not honoured — true buys a startup warning, not encryption. See below. |
remote.untrusted-mode | false | Admit an inbound envelope only when trusted-selection-paths lists its target. Off, any /user actor is addressable by name — which is what makes an ActorRef work across nodes. /system is refused either way. See below. |
remote.trusted-selection-paths | [] | Paths a peer may address by name while untrusted-mode is on. Empty means: nothing beyond the framework endpoints this node registered. |
remote.handshake-timeout | 5s | How long a connection may sit without its half of the handshake before it is torn down. One value for both directions — see below. |
remote.connect-timeout | (unset) | How long a dial may take to open — the TCP connect and, over TLS, the TLS handshake — before it is aborted and logged as one that could not connect. Unset, it is remote.handshake-timeout, which it may not exceed. Comment-only in reference.conf, so “unset” stays expressible — see below. |
remote.outbound-queue-size | 1000 | How many frames are held for a peer that cannot take them right now, oldest dropped first. |
remote.max-inbound-connections | 1024 | How many inbound connections this node accepts before it refuses sockets outright, newest refused rather than oldest evicted. |
remote.incomplete-frame-idle | 30s | How long a connection may hold a half-received frame with no further byte arriving. A stall bound, re-armed on every chunk. |
host/port are the bind pair and advertised-host/advertised-port
the identity pair: the first says where the listener opens, the second
says what goes into every gossip frame for peers to dial back. They are the
same values until a deployment remaps one, which is why naming one routable
host and one port still does both jobs and nothing configured today moves.
Both entry points read the bind pair from config — Cluster.join and
Cluster.bootstrap alike — so a deployment can move it out of code
entirely:
actor-ts.remote.tcp { host = "0.0.0.0" port = ${?ACTOR_TS_PORT} # env-var substitution}On the Cluster.bootstrap path the environment sits beneath this block — the
order actor-ts.discovery already uses:
explicit options > actor-ts.remote.tcp.* > CLUSTER_HOST / POD_IP / HOSTNAME, CLUSTER_PORT > 0.0.0.0, 2552A port in the file therefore wins over CLUSTER_PORT, and the variable still
answers on a node whose file names none — with ACTOR_TS_PORT unset above,
port drops out and CLUSTER_PORT decides. That is why neither leaf ships in
reference.conf: a published value would be the config layer on every node.
Cluster.join consults no variable for the bind pair; it takes its options,
then this block, then the built-in pair.
A published container port is the case that needs all four. The process
listens on 2552 inside the container, docker run -p 3000:2552 puts it on
3000 outside, and 3000 is the number that belongs in every other node’s
seed list:
actor-ts.remote.tcp { host = "0.0.0.0" # bind every interface — the container port = 2552 # does not know its published address advertised-host = ${?HOST_IP} # what peers dial … advertised-port = 3000 # … and on which port}Under Kubernetes only the host half moves: pod-to-pod gossip dials the
container port directly, so advertised-host = ${?POD_IP} on its own is the
whole configuration.
remote.max-frame-bytes applies to the transport the cluster builds for
itself. If you construct a TcpTransport yourself and pass it via
withTransport(…), set its cap there — the framework will not re-cap a
transport it did not create.
Who a peer may address by name
Section titled “Who a peer may address by name”An inbound envelope frame carries the target path the sender chose, and
the node resolves it against its own actor tree. That is the one thing on the
cluster wire a remote party picks freely, and the two keys above are the scope
around it.
/system is not part of that scope. The framework’s own actors — shard
coordinators and regions, singleton managers, the pub-sub mediator, the
DistributedData replica, both DevTools lanes — are reachable only through the
per-path handler each of them registers, in both modes. That door attaches the
connection’s identity to the frame; resolving a path by name never did, which is
why a body arriving that way had no sender at all. This is a change in
behaviour: before it, anyone who completed a hello could address them
(issue #964).
untrusted-mode narrows the other half. Off — the default — a peer may name
any /user actor, which is what a RemoteActorRef rebuilt from a wire ref
does and what makes an ActorRef usable across nodes at all. On, only the
paths you list:
actor-ts.remote { untrusted-mode = true trusted-selection-paths = ["/user/orders/*", "/user/reporting/intake"]}An entry is one exact path unless it ends in /*, in which case it is that
path and everything below it. The suffix is segment-anchored, so
/user/orders/* admits /user/orders/7 and refuses /user/orders-archive;
nothing else here is a pattern, and a * anywhere but as the whole final
segment is rejected at startup rather than matched literally. Paths are written
guardian-rooted, the way the tree renders them; the leading / is optional.
Turn the mode on where the cluster network crosses a boundary you do not
control — the same networks remote.max-frame-bytes is worth lowering on. What
it costs is that any actor a peer addresses by name has to be listed, including
the ones reached through a ref that travelled over the wire, so start by
watching cluster_envelope_refusals_total{reason="not-allow-listed"} on a node
with the mode on and an allow-list you expect to be complete.
Refusals are counted rather than logged one by one: an envelope is its own
frame, so a line per refusal would let a peer write this node’s log at message
rate. The first refusal of each reason is logged at WARN and further ones are
folded into at most one line every 30 seconds, naming the connection’s peer
and never the requested path.
The same rule applies to ClusterClientReceptionist, and it is the more exposed
of the two seams: a ClusterClient never joined the
membership ring. A refused path is answered with the identical path not found
the client gets for a path that does not exist, so the endpoint cannot be used
to map the actor tree.
The association lifecycle
Section titled “The association lifecycle”Four of the last five keys bound what a party that can open a TCP connection to
the cluster port is able to make this node hold. All four have been enforced
since the transport was hardened; what changed is that they are settable
(issue #846). The fifth,
connect-timeout, bounds this node’s own dials instead and is described below:
actor-ts.remote { handshake-timeout = 5s outbound-queue-size = 1000 max-inbound-connections = 1024 incomplete-frame-idle = 30s}handshake-timeout covers a connection that never speaks its half of the
handshake — a dial that never gets its hello-ack, and an accepted socket that
never sends a hello. It is one key for both directions on purpose. The
dialling side’s clock starts before the TCP connect and the TLS handshake, the
accepting side’s after the accept, so with one number the peer that is still
trying has always given up first and the acceptor can never be the deadline
that punishes a slow-but-legitimate dial. A split dial/accept pair would let an
accept deadline set below the dial deadline make a healthy peer permanently
unjoinable, with nothing in either node’s log saying why.
connect-timeout is not that split: it bounds only how long this node’s own
dial may take to open — the TCP connect and, on a TLS dial, the TLS handshake —
under the handshake deadline that still bounds the whole dial
(issue #1475). A dial that
has not opened by then is aborted and logged as
could not connect to … within N ms; one that opened is handshake-timeout’s
to end, and its line says connected to …, but no hello-ack came. Set it lower
than handshake-timeout to learn sooner that a peer is not there, while a slow
one still gets the whole handshake deadline to answer:
actor-ts.remote { handshake-timeout = 5s connect-timeout = 2s}It ships comment-only, the tcp.advertised-host shape: unset means “the same
as handshake-timeout”, the one deadline a dial had before the key. It may not
exceed handshake-timeout — both validators refuse that, a lone
connect-timeout = 10s against the 5 s default — and a shipped value of its own
would have refused every handshake-timeout set below it, so lowering the one
key an operator already knows can never trip a rule about one they never wrote.
incomplete-frame-idle covers the other half: a connection that spoke and then
went silent mid-frame. It is a stall bound rather than a budget for the
frame — it is re-armed on every chunk, so a peer pushing a large frame over a
congested link is never punished for being slow, only for stopping. Keep it
above handshake-timeout; both validators refuse a value at or below it,
because a socket that sends nothing at all never reaches this deadline and the
handshake timer is what covers that one. What they compare is the resolved
pair, not the pair you wrote: writing one of the two keys on its own is checked
against the other’s built-in default, so a lone incomplete-frame-idle = 1s is
refused for sitting under the 5 s handshake-timeout it would run against.
max-inbound-connections is what stops either cost from being multiplied by
opening sockets in a loop, and it is the half of the inbound-memory bound worth
tightening: that bound is this count times what one connection may buffer. Set
it from the real peer count where you know it — one inbound connection per peer
in a full mesh, plus whatever ClusterClients dial
in — and leave headroom, because refusing a legitimate peer is a partition. The
newest connection is refused rather than the oldest evicted; eviction would let
an attacker push established peers off the node.
outbound-queue-size is the one key here that bounds what this node holds
rather than what a peer holds against it: frames written for a peer that cannot
take them right now, with the oldest dropped first, because the newest
membership and heartbeat state is the state worth keeping. Today that is the
buffer in front of the handshake, so a tell racing the handshake is held
rather than lost. The key is named for the category and not for that one
buffer: the post-handshake backpressure queue
(issue #931) is the same
quantity with the same policy and the same warning, and will land under this
key rather than a second one.
None of the five has an “off” spelling. 0 is refused for each, because it is
a distinct way of breaking the node rather than a way of removing a cap: no
handshake window, no time for a dial to open, no room to buffer, no inbound
connection admitted, no connection allowed to end off a frame boundary.
These reach the transport the cluster builds for itself. A TcpTransport you
construct and pass via withTransport(…) carries its own — set them in its
TcpTransportOptions.
actor-ts.http
Section titled “actor-ts.http”| Key | Default | Purpose |
|---|---|---|
http.backend | "fastify" | One of fastify / express / hono. |
http.shutdown-grace-period | 0ms | How long unbind() lets in-flight requests drain before connections are forced. 0 forces immediately. |
http.server | (see below) | Connection-level bounds for the listening socket itself. |
http.cors | (see below) | Per-route defaults for the cors() directive. |
http.hsts | (see below) | The policy the hsts() middleware sends. |
http.request-timeout | (see below) | The handler deadline of the requestTimeout() middleware — not http.server.request-timeout. |
http.client | (see below) | Outbound HttpClient defaults. |
http.websocket | (see below) | Server-side WebSocket defaults for websocket() routes. |
http.backend only decides what newServerAt(...).bind() uses when the
builder was given no backend of its own — useBackend(new HonoBackend())
always wins, and is still the only way to pass a backend you configured or
wrote yourself. An unrecognised name fails the bind() with a
ConfigError rather than silently falling back to Fastify. Express and
Hono are optional peer dependencies, imported only if you name them.
The grace period defaults to 0 — force as soon as the server closes —
because that is what unbind() has always done in practice. Raise it if
you want in-flight requests to finish.
It is usually an upper bound rather than a delay: unbind() returns as soon
as the server has actually closed. Where a backend’s close() cannot
settle — Express holding a live WebSocket, for one — the window becomes a
deadline that is always reached, so a large value there is time you always
pay. A caller that passes its own value — binding.unbind(1_000) —
overrides the config.
The bounds on a connection — as against a route on it — come from
actor-ts.http.server:
| Key | Default | Purpose |
|---|---|---|
http.server.idle-timeout | (backend’s own) | How long an idle connection is held before it is closed — a keep-alive HTTP/1.1 connection between requests, and an HTTP/2 session with nothing moving on it. Ships no leaf — see below. 0 disables it — on the Hono backend under Bun, where it is the only bound on a request whose body stops arriving, that leaves such a connection open until the client closes it (§ below). At most 2147482647 ms — on the Hono backend under Bun, where it is a wider bound, at most 255s (§ below). |
http.server.header-timeout | 60s | How long a connection may take to deliver its complete header block before it is answered 408 and destroyed. The slow-loris guard, held by actor-ts itself — see below. A shorter request-timeout is the header deadline too: the guard runs on the smaller of the two. 0 disables it. At most 2147483647 ms. |
http.server.request-timeout | 300s | How long a connection may take to deliver a request in full, headers and body. Bounds receiving, never answering — a handler’s deadline is http.request-timeout. Shorter than header-timeout, it bounds the header phase as well, since the headers are part of the request. At most 4294967295 ms. |
http.server.max-connections | (unlimited) | Concurrent connections the listening socket accepts before it starts closing new ones. Ships no leaf — see below. |
http.server.max-content-length | (the backend’s own) | The largest request body accepted, in bytes; a larger one is answered 413 before the handler runs. Read as a size (8MiB). Ships no leaf — see below. |
http.server.max-header-bytes | (the runtime’s own) | The largest request header block accepted, in bytes; a larger one never reaches a handler. Read as a size (16KiB). Ships no leaf — see below. |
The usual order applies per field: newServerAt(...).withServerOptions(...)
wins, then this block, then the built-in default. They are resolved once at
bind(), before the backend is built. The timeouts and max-connections are
installed on the server at listen(), so they reach a backend you constructed
and passed to useBackend(...) exactly as they reach the one the framework
builds. The two size caps — like tls and http2 — are fixed when the server
is built, so the framework builds its backend with them, and a backend you
built yourself has to carry them: a hand-built FastifyBackend adopts them
only through new FastifyBackend(fastifyFactoryOptions(serverOptions)), and
bind() refuses a backend whose own cap differs from a set key — Fastify’s
bodyLimit or its server’s header cap, withMaxBodyBytes on Express or Hono —
rather than serve under either number. An equal cap binds, and an unset key
refuses nothing.
The three durations are refused at bind() above what the runtime can hold
where each one ends up, because past that a deadline meant as “effectively
never” comes out short. header-timeout and idle-timeout end up in a timer,
which arms anything over 2147483647 ms as 1 ms; idle-timeout stops a second
under that, at 2147482647 ms, because both runtimes add a second to it.
request-timeout ends up in Node’s connection sweep, which reads it as a 32-bit
number, so its ceiling is 4294967295 ms. HOCON reaches both in one line:
30d is 2 592 000 000 ms, past the timer’s ceiling, and 60d is past the
sweep’s.
actor-ts.http.server { idle-timeout = 5s request-timeout = 30s max-connections = 10000 max-content-length = 8MiB}Four leaves ship no value and are listed above only so the names are discoverable, for the same reason four of the CORS leaves do: a published literal would be a number nobody chose.
idle-timeout unset keeps whatever the backend picked, and the backends
disagree on purpose — 72 s on Fastify against node:http’s 5 s on Express
and on Hono-over-Node. Fastify’s is high so the server outlives a load
balancer’s idle window and the balancer never posts a request onto a socket
that is already closing; five seconds is the platform’s. Neither is wrong, so
the block picks no winner. Set it to make them agree. Hono under Bun is the
one backend that does not keep its runtime’s own: Bun’s 10 s cut slow handlers
with no response, so there an unset idle-timeout is derived from the request
deadline instead — 36 s by default (§ above).
It bounds an idle HTTP/2 session too, and request-timeout an HTTP/2
stream’s receive. keepAliveTimeout and requestTimeout, which carry them to
an HTTP/1.1 connection, are properties no HTTP/2 session or stream reads, so on
a listener with http2 on actor-ts runs timers of its own: a session that has
had no stream open for idle-timeout is closed with a GOAWAY — the same value
on both runtimes, and a PING frame resets nothing — and a stream whose request
is still arriving at request-timeout is answered 408 and reset. A stream
in flight holds its session, so a slow handler, a long poll and an SSE stream
outlive the idle bound as they do on HTTP/1.1, and a request received in full
is never cut by the receive deadline. Unset, an idle HTTP/2 session is left to
Fastify’s own session timer — 72 s on Node, 144 s on Bun, which fires it at
twice the value and lets a PING reset it — and on Hono over Node to nothing at
all. On Bun the HTTP/2 listener bounds a connection that negotiates HTTP/1.1
on the same port by neither key, so there both are reported held for HTTP/2
only and bind() warns. None
of this is the Hono backend under Bun, whose sessions Bun.serve’s own
whole-connection bound holds (§ above), set or derived: an idle session there
was closed within one sweep of a 4s value (bun 1.4.2), and a silent stream
does not outlive it.
max-connections unset is unlimited, which is what every release before this
key did. It is server-wide, unlike the http.websocket.max-connections
below, which is per route: it counts every connection the process accepts on
this binding — WebSocket upgrades included, and an attached
DevTools server too, since DevTools binds
through the same system.http(...) path.
max-content-length unset keeps each backend’s own body cap — the 1 MiB every
shipped backend applies, or what withMaxBodyBytes (Express, Hono) or
bodyLimit (a Fastify you built) set. Set, it is the cap on every backend and
every runtime: each backend counts a body’s bytes in code of its own, so a
declared Content-Length over it is refused before a byte is read, and a
chunked body is abandoned once it crosses it — 413 either way, before the
handler runs. A backend built with a different cap of its own is refused at
bind(), naming both; there is no rule for which of two numbers wins, because
either answer leaves one of them silently not held.
max-header-bytes unset keeps the runtime’s own: 16 KiB on node:http, and on
Bun the process-wide --max-http-header-size, 16 KiB too unless the process
was started with another. Set, a request whose header block is larger never
reaches a handler — node:http answers 431, though a client still writing
when the server gives up may see a reset instead. It is an option a server
takes when it is built, so it reaches one only where actor-ts builds it:
Fastify’s factory options, the node:http server Express is served from, and
@hono/node-server’s serverOptions — the table above says where that leaves
a gap.
request-timeout is enforced by a periodic sweep whose interval is
http.createServer’s connectionsCheckingInterval — 30 s by default, and a
factory option actor-ts does not set — so a connection is closed no earlier
than the value set here and no later than one sweep after it: measured
on bun 1.4.0, a 2s request-timeout closed a stalled body at 30.0 s. What
the peer is told depends on the backend. A bare node:http server answers
408 before closing; the default Fastify backend under Bun closes with no
status line at all, because Fastify’s clientError handler writes its 408
and then destroys the socket, and on bun 1.4.2 a handler of that shape
delivers nothing. header-timeout is not swept, because it is not the
runtime that enforces it: it fires at the value set here.
Both ship the number http.createServer already uses, so publishing them
changed no bound that was already being held — but Fastify sets
requestTimeout to 0, no bound at all, so on the default backend the
published 300s is a deadline where there previously was none. At the 1 MiB
body cap that is a client sending under 3.5 KB/s; raise it if you accept
legitimately slower uploads, or set 0 to opt out.
Setting header-timeout = 0 opts out of the slow-loris guard entirely: no
deadline is armed and the property is cleared. A runtime may still hang up on
its own — bun 1.4.0 drops a connection carrying no complete request after about
12 s whatever this says — so 0 buys an unbounded header phase only where the
runtime grants one. The TLS handshake was inside the guard’s window too, so a
handshake that never completes is then the runtime’s to end as well: Bun’s
HTTPS listener closes one after about 12 s, but an HTTP/2 listener waits for the
TLS handshake timeout, 120 s on bun 1.4.2 and node v26.10.0 alike.
request-timeout bounds receiving only — the clock stops once the request has
arrived — so a slow handler, a long poll and an SSE stream are unaffected. The
route-level requestTimeout() middleware is the
other half and is deliberately a different surface, with a key of its own,
http.request-timeout below: it bounds how long a handler takes to answer,
this bounds how long a peer takes to ask.
The cors() route directive reads its per-field
defaults from actor-ts.http.cors:
| Key | Default | Purpose |
|---|---|---|
http.cors.origins | (unset) | Exact-match origin allowlist, e.g. ["https://app.example"]. Ships no leaf — see below. A "*" entry is refused. |
http.cors.methods | (unset) | Access-Control-Allow-Methods. Ships no leaf — unset follows the methods registered at each pattern. |
http.cors.allowed-headers | (unset) | Access-Control-Allow-Headers. Ships no leaf — unset echoes the sanitised request headers. |
http.cors.exposed-headers | [] | Access-Control-Expose-Headers. [] sends none. |
http.cors.credentials | false | Access-Control-Allow-Credentials: true. Forbidden with "*" origins. |
http.cors.max-age | (unset) | Preflight cache lifetime in seconds, a bare integer. Ships no leaf — unset sends no Access-Control-Max-Age at all. |
The usual order applies per field: what cors(options, routes) names in code
wins, then this block, then the built-in default. So a deployment can move the
allowlist out of code entirely and keep withCredentials() where it is.
Two of the option arms are code-only and have no key here. The "*"
wildcard is one: withAnyOrigin() is documented as the explicit opt-in, and a
config file that could write origins = ["*"] would widen every cors() route
in the process to any origin with one line — so a "*" in this list is refused
with a ConfigError naming the key. The other is withOriginPredicate(...),
which is a function and has no HOCON spelling at all.
Four leaves ship no value and are listed above only so the names are
discoverable — a published literal would be worse than no key. methods and
allowed-headers have defaults computed per pattern and per request, which a
fleet-wide list would override; max-age unset means the header is not sent;
and a shipped origins would satisfy the required-origins check for every
route in the process, turning a cors() that names no allowlist anywhere from
a loud error into a silent deny-all. Set any of them in your own
application.conf and it is read normally:
actor-ts.http.cors { origins = ["https://app.example", "https://admin.example"] max-age = 600 # seconds — not a duration string exposed-headers = ["x-request-id"]}Values are validated on the merged result, so a bad one throws OptionsError
naming the field rather than reaching a browser as a header it will reject.
This block is resolved when the route tree is compiled — inside bind(),
the first moment the tree and the ActorSystem are both in scope. That is also
where a cors() with no origins in code and none in config now fails, rather
than at the cors(...) call itself.
The hsts() middleware —
strictTransportSecurity() by its long name — reads its policy from
actor-ts.http.hsts:
| Key | Default | Purpose |
|---|---|---|
http.hsts.max-age | 15552000 | How long a browser keeps the pin, in seconds (180 days) — a bare integer, not a duration string. 0 and anything below 86400 (a day) are refused here; code may set any value. |
http.hsts.include-sub-domains | true | Emit includeSubDomains. |
http.hsts.preload | false | Emit preload. Needs a max-age of at least a year and include-sub-domains. |
The usual order applies per field: what hsts(options) names in code wins,
then this block, then the built-in default. The merged policy is validated
once, when the route tree is compiled inside bind() — so withPreload() in
code over a year of max-age from this block is a valid policy, and one that
cannot back its preload fails bind() with an OptionsError rather than
sending a header the preload list will refuse.
actor-ts.http.hsts { max-age = 63072000 # seconds — two years, not a duration string preload = on}A max-age below 86400 — one day — is refused with a ConfigError naming
the key and the floor. 0 tells every browser to forget the pin, and a shorter
pin than a day has lapsed before a visitor comes back the next day, so one line
in a configuration file would un-pin every client of every hsts() route in
the process. Code may still set any value with withMaxAge(...) — the
five-minute first stage of hstspreload.org’s ramp-up, withMaxAge(300), and
withMaxAge(0), which switches HSTS off, included.
The block governs the hsts() middleware only. The hsts field of the
securityHeaders() bundle and of withSecurityHeaders(...) is code-only, and
where both paths emit the header, the route-level hsts() wins — see
Security headers.
A middleware is built before any ActorSystem exists, so hsts() carries a
hook that compile() resolves against this block. Wrapped in a function of
your own — (request, next) => hsts()(request, next) — it is out of
compile()’s sight and sends the code options over the built-in defaults.
Hand it to withMiddleware(...) as it is.
A wrapper hides the middleware, not the result: when this block differs from
what reference.conf ships and no hsts() in the route tree read it —
wrapped, absent, or HSTS sent through the bundle only — bind() logs a warning
naming the block and the address it bound. What it cannot see is a wrapped
hsts() beside another one that did read the block.
The requestTimeout() middleware reads its
deadline from actor-ts.http.request-timeout:
| Key | Default | Purpose |
|---|---|---|
http.request-timeout.deadline | 30s | How long a handler may take to answer before the middleware answers 503 for it. On the Hono backend under Bun it also sets the default http.server.idle-timeout, so the 503 is written before the connection is cut (see the http.server section). |
This is the handler’s deadline, and deliberately not
http.server.request-timeout above: that one bounds how long a peer takes to
send a request and never a response, this one starts once the request has
arrived. What requestTimeout(...) names in code wins, then this block, then
the built-in default, so requestTimeout() with no argument takes its deadline
from here:
actor-ts.http.request-timeout { deadline = 10s}The leaf is the kebab-case of the deadlineMs field with the unit suffix
dropped, read as a duration. The response sent on timeout, withOnTimeout(...),
is a function and code-only. The merged deadline is validated once, when
the route tree is compiled inside bind(): one that is not positive, or longer
than a timer can hold (2147483647 ms, about 24.9 days), fails bind() with an
OptionsError — a runtime would arm such a timer as 1 ms and answer every
request 503 at once.
It reaches requestTimeout() the way the HSTS block reaches hsts(), through
the hook compile() resolves, and the same warning names it at bind() when it
is configured and nothing in the tree read it.
The system’s shared HttpClient — and any newClient(...) that leaves a
field unset — reads its bounds from actor-ts.http.client:
| Key | Default | Purpose |
|---|---|---|
http.client.max-response-bytes | 8M | Largest response body buffered before the request is aborted. |
http.client.default-timeout | 30s | Deadline for a call that names no timeoutMs of its own. |
http.client.redirect | "follow" | What to do with a 3xx carrying a Location — follow / error / manual. |
http.client.max-redirects | 5 | Hops a followed chain may take before the call is refused. 0 refuses the first. |
These are a floor, not a policy: an integration passes its own bounds to
newClient(...), and a single call overrides them with maxResponseBytes /
timeoutMs / redirect / maxRedirects. What the block buys is the ability
to move the fleet-wide numbers without a code change — an endpoint that turns
out to need 60 s, or a deployment on a link where 8 MiB is the wrong ceiling,
used to force every caller off the shared client.
Every leaf is the kebab-case of its HttpClientOptions field with any unit
suffix dropped — the value carries the unit, so default-timeout = 30s. The
camelCase spellings this block used before are rejected at the first
HttpExtension access, not at ActorSystem.create, with a ConfigError
naming both, rather than ignored: max-response-bytes is a
ceiling a deployment lowers deliberately, and quietly restoring the built-in
default would be the one failure mode a rename must not have.
Values are validated on read, on the merged settings, so a bad one throws
OptionsError naming the field rather than failing later inside a request.
max-response-bytes and default-timeout must both be positive here — unlike
a request’s timeoutMs, where 0 is the documented way to opt one call out
of any deadline. A 0 in this block would disarm every call that named no
deadline of its own, which is the state the defaults exist to prevent.
Server-side WebSocket routes (websocket(path, actorRef)) read their
defaults from actor-ts.http.websocket:
| Key | Default | Purpose |
|---|---|---|
http.websocket.max-frame-bytes | 1M | Largest inbound frame accepted (bytes). |
http.websocket.on-oversize-frame | "close" | What to do when a frame exceeds the limit — close / drop. |
http.websocket.on-invalid-message | "close" | What to do when a message fails to decode — close / drop / hook. |
http.websocket.max-buffered-bytes | 4M | Outbound backpressure threshold (bytes). |
http.websocket.on-backpressure | "drop" | What to do when the buffer is exceeded — drop / close. |
http.websocket.max-connections | (unlimited) | Max concurrent connections per route; a new upgrade beyond it is closed with 1013. |
http.websocket.max-pre-attach-frames | 256 | Inbound frames held while the connection actor starts. |
http.websocket.max-pre-attach-bytes | 4M | Bytes held while the connection actor starts; past either cap the socket is closed with 1013. |
http.websocket.accept-timeout | 10s | How long an admitted upgrade waits for its connection actor before the socket is closed and its max-connections slot released. Infinity switches the watchdog off and is code-only, because HOCON has no Infinity literal — withAcceptTimeoutMs(Infinity) and a withConfig overrides object both reach it. |
http.websocket.connection-mailbox-capacity | (unset) | Queued outbound messages each connection actor may hold — the queue connection.tell, sendRaw and close go into — before the overflow policy sheds frames; close() is never shed. Unset, a connection falls through like any other application actor: to the deployment entry matching its path, then to mailbox.default.capacity. A positive integer; 0 is refused rather than read as “off”. |
http.websocket.connection-mailbox-overflow | (unset) | drop-head / drop-new / reject for a full connection mailbox. Needs a capacity from the route or the leaf above — a configured one, global or per path, does not count — and is refused at bind() without one. Unset, it falls through to the matching deployment entry’s mailbox-overflow, then to mailbox.default.overflow. |
The same leaf rule applies here: kebab-case, unit suffix dropped, and a retired
camelCase spelling is a ConfigError rather than a cap that silently reverted
to the default. This block is read, and so checked, at the bind() of a
server with a WebSocket route — not when the HttpExtension is first fetched.
actor-ts.reliable-delivery
Section titled “actor-ts.reliable-delivery”| Key | Default | Purpose |
|---|---|---|
reliable-delivery.producer.resend-timeout | 500ms | How long the producer waits for an acknowledgment before retransmitting the same seq. One fixed interval, re-armed unchanged on every miss — there is no backoff. |
reliable-delivery.producer.window-size | 16 | Flow-control window: at most this many un-acked messages in flight. Further sends queue in memory until an acknowledgment opens a slot. |
reliable-delivery.consumer.max-producers | 1024 | Most producers the consumer keeps deduplication state for at once. At the cap the least-recently-used entry is evicted. 0 = unbounded. |
reliable-delivery.consumer.producer-idle-time-to-live | 5m | How long a producer’s deduplication entry survives with no delivery from it; the sweep runs on this same interval. 0 turns the sweep off. |
reliable-delivery.consumer.max-out-of-order | 1024 | Most sequences the consumer retains for one producer above an open gap. At the cap a delivery is refused — no handler call, no acknowledgment — and that producer stalls until the gap closes. Keep it above every producer’s window-size. 0 = unbounded. |
Both blocks layer under whatever ReliableDelivery.producer(...) /
ReliableDelivery.consumer(...) was passed, so an explicit withWindowSize(…)
still wins. They are read there and nowhere else. Neither controller can
read configuration in its constructor — Actor.system is a getter over a
context the cell injects afterwards — so a controller you construct yourself
and hand to system.spawn keeps its built-in defaults and never sees this
block.
0 is how all three consumer bounds spell the Infinity their option fields
document, because Infinity cannot be written in HOCON at all: the number
reader takes a numeric literal and the duration parser refuses a non-finite
value. It is the same spelling cluster.max-members and
sharding.max-entities already use. What it costs is worth stating plainly.
The deduplication map is keyed by a producerId the sender chooses, so 0
on max-producers hands a peer the decision about how much this consumer
retains — one entry per distinct id, never released. 0 on
max-out-of-order does the same inside one entry: a sender that withholds one
sequence and keeps sending the ones after it grows that producer’s set for as
long as it keeps going.
max-out-of-order is a floor as well as a bound. A producer has
window-size sends in flight when a gap opens, so a cap below the largest
window of any producer talking to this consumer stalls that producer on its
very first gap, with nothing queued behind it. The shipped 1024 leaves room
for any window a caller would plausibly configure.
actor-ts.serialization
Section titled “actor-ts.serialization”| Key | Default | Purpose |
|---|---|---|
serialization.read-constraints.max-nesting-depth | 256 | Container levels a decoder will descend before refusing the payload. Never raised past the encoder’s own ceiling. |
serialization.read-constraints.max-document-bytes | 0 | Ceiling on one document before it is parsed — checked in JsonSerializer / CborSerializer, and on the cluster wire against the frame’s length prefix. 0 = no ceiling of our own. |
serialization.read-constraints.max-string-length | 20M | Ceiling on one CBOR byte string, text string or map key, checked against the length prefix before the bytes are allocated. 0 removes it. |
These bound what this node reads, never what it writes. A peer that completes the handshake, or any client whose body reaches a serializer, chooses the bytes; these decide how much work this process will do on them before giving up. Lowering one therefore makes this node stricter than its own encoder — it does not change the wire format.
max-nesting-depth is the one that matters, because until it existed there was
nothing at all on the JSON side: JSON.parse is iterative in every runtime
actor-ts supports and accepts a million levels without complaint, so the
recursion that overflows is the framework’s own tagged-tree walker, reached
straight off the cluster wire. It may be lowered freely and cannot be
raised past 256: that number is also the encoder’s hard cap, and a node that
read deeper than it writes would accept a payload it is unable to produce.
Raising it is an OptionsError at startup.
max-document-bytes ships as 0 because every path the framework owns is
already bounded in bytes — remote.max-frame-bytes on the cluster wire, the
server’s body cap over HTTP. Set it where a serializer is reached some other
way (a broker payload, a queue message) and nothing upstream has an opinion, or
where the byte bound upstream is looser than the document you are willing to
parse. On the cluster wire it is enforced against the frame’s 4-byte length
prefix, so the frame is refused before its payload is buffered, let alone
parsed; that is the earliest point in the framework at which it can act, and it
is earlier than the serializers manage, because they are handed bytes that
already exist.
Being bounded in bytes is not the same as being bounded in work, and the gap
is worth stating: at the shipped defaults a frame nested past
max-nesting-depth is refused only after JSON.parse has materialised it.
Measured on Bun 1.4, one 16 MiB frame of balanced [ costs about 1.0 s of CPU
and 260 MiB of heap before the depth ceiling reports it — roughly four times
what a legitimate frame of the same size costs, and repeatable by any peer that
completed the handshake. remote.max-frame-bytes and max-document-bytes are
the two knobs that bound it. A pre-parse scan of the raw buffer would close it
with neither set, and was measured and not shipped: it costs 18–28 % of every
frame decode to remove a fourfold amplification.
max-string-length binds on CBOR only, and its default sits deliberately
above remote.max-frame-bytes, so on the cluster wire the frame cap is the
effective ceiling and this one never fires. The asymmetry is the point: a CBOR
item announces its length, so refusing it costs nothing and prevents the
allocation, while by the time the JSON walker sees a string JSON.parse has
already materialised it.
Two edges are deliberately outside this block. The persistence PayloadCodec
decodes bytes the framework itself wrote, so a tightened ceiling there would
turn recoverable history into unreadable history. And the HTTP body edge
builds its serializers with no ActorSystem handle to read config through —
that seam is issue #967.
actor-ts.management
Section titled “actor-ts.management”| Key | Default | Purpose |
|---|---|---|
management.enable-leave-endpoint | false | Serve POST /cluster/leave (HTTP endpoints). |
management.enable-down-endpoint | false | Serve POST /cluster/down — operator-initiated force-down of a peer. |
management.enable-metrics-endpoint | false | Serve GET /metrics in Prometheus text format. |
management.auth-protect-health | false | Extend the auth middleware over /health and /ready as well as /cluster/*. |
management.liveness-path | "health" | Single path segment the liveness probe answers on. |
management.readiness-path | "ready" | Single path segment the readiness probe answers on. |
management.health-checks.check-timeout | 1s | Deadline for one health check; past it that check reports status: false and its siblings still report normally. |
These are the settings managementRoutes(system, cluster, options) layers
under its explicit options — the usual three layers, so a value set in code
wins, a file fills what the code left unset, and the built-in defaults are the
floor. The port and host are not here: they belong to
system.http(port, { host }), not to the route tree.
auth and ipAllowlist have no key, and cannot get one. Both are
Middleware functions, which HOCON has no way to express, so this block
decides which endpoints exist and where the probes answer — never who
may reach them. A config file therefore cannot loosen the management server’s
access control, which is why the two mutating endpoints are safe to expose as
config at all.
The two probe paths are single segments, and a value containing / is
refused with an OptionsError when the routes are built. That rule is not
cosmetic: path(segment, …) strips surrounding slashes only, so
readiness-path = "k8s/ready" would be stored as one segment holding a slash,
match no URL, and take the endpoint out of existence with nothing logged. A
startup error is the visible version of the same outcome.
check-timeout bounds a single check rather than the whole probe. A probe
aggregates every registered check into one response, so without it the slowest
check is the response time and a check that never settles is a probe that
never answers — which Kubernetes reads as a failure carrying no clue as to
which dependency hung. Past the deadline the registry answers for that check
with { name: 'unknown', status: false, detail: … }; the name is unknown
because the name lives inside the result the check never returned.
actor-ts.metrics
Section titled “actor-ts.metrics”| Key | Default | Purpose |
|---|---|---|
metrics.max-series-per-family | 10000 | Distinct label tuples one metric family may mint; every tuple past it is folded into a single __overflow__ series (the cardinality cap). Covers the in-process registry and the prom-client bridge alike. 0 disables the cap. |
metrics.name-prefix | "" | Prefix the prom-client bridge puts in front of every metric name it registers, e.g. "actor_ts_". The bridge only. |
These are read when MetricsExtension builds a registry, under the options of
the call that builds it — the usual three layers, so a value set in code wins,
a file fills what the code left unset, and the built-in defaults are the
floor. enable(options) takes the cap for the in-process registry;
enablePromClient(options) takes both leaves for the bridge. The free
promClientRegistry(options) reads neither: it takes no ActorSystem, so the
bridge it returns, installed with useRegistry, behaves exactly as its options
say.
The cap reaches registries nobody enables in code. DevTools switches the
registry on with no options while it is attached, and the relay of a
worker mesh does
the same inside every worker — whose system is built from the main thread’s
effective config. So a cap set here holds on every thread, while one passed to
the main thread’s own enable(options) stays on the main thread.
name-prefix reaches the bridge and nothing else. The in-process registry
has no prefix: the management GET /metrics route renders the
stock metrics under the names that
page lists.
Two metrics switches stay in the blocks of the code that serves them:
management.enable-metrics-endpoint turns the scrape
route on, and
worker-mesh.metrics-relay-interval
paces the relay that brings the workers’ registries into it.
actor-ts.tracing
Section titled “actor-ts.tracing”| Key | Default | Purpose |
|---|---|---|
tracing.tracer-name | "actor-ts" | Name the OpenTelemetry adapter asks getTracer for — the instrumentation scope your tracing backend files every framework span under. |
tracing.tracer-version | (unset) | Version passed to getTracer beside the name. Comment-only in reference.conf: unset passes no version. Quote it — an unquoted 1.0 is a number to HOCON and arrives as "1". |
tracing.logger-name | "actor-ts" | Name the OpenTelemetry logger of the otelLogs slot asks getLogger for — the instrumentation scope your backend files every framework log record under. Not logger.sinks.otlp.scope-name; see below. |
tracing.logger-version | (unset) | Version passed to getLogger beside the name. Comment-only in reference.conf: unset passes no version. Quote it, as tracer-version above. |
The two tracer-* leaves are read when TracingExtension.enableOtel(options)
builds the tracer, under the options of that call — the usual three layers, so
a value set in code wins, a file fills what the code left unset, and the
built-in default is the floor. Per field: a name set in code keeps a
configured version. The free
otelTracer(options) reads neither: it takes no ActorSystem, so the tracer it
returns, installed with enable(...), behaves exactly as its options say.
Neither leaf reaches a tracer you built yourself. A pre-built tracer in
the options is used as it is. The @opentelemetry/api namespace and a
pre-built tracer have no key at all: both are objects a config file cannot
hold.
The two logger-* leaves are read when the system builds its logger from the
otelLogs slot — ActorSystemOptions.withOtelLogs(options), at
ActorSystem.create — under the slot’s options: the same three layers, field
by field. The logger’s level is not here: it is the slot’s own level, else
logLevel, else logger.level. The free
otelLogger(options) reads neither leaf, so a logger built with it and handed
over with withLogger behaves exactly as its options say, and a pre-built
logger in the slot’s options is used as it is.
logger.sinks.otlp.scope-name is a different knob. It names the records
the OTLP HTTP sink
sends on its own — a separate route to a collector, one that needs no
OpenTelemetry SDK — while tracing.logger-name names the logger of the slot.
The two never meet: the slot wins over every sink, so a system that sets it
builds no OTLP sink at all.
actor-ts.persistence
Section titled “actor-ts.persistence”| Key | Default | Purpose |
|---|---|---|
persistence.max-concurrent-recoveries | 50 | Journal replays allowed to run at once, system-wide. 0 is uncapped. sharding.entity-recovery paces entity starts one layer up; this bounds how many of their replays are in flight. |
persistence.recovery-timeout | 30s | Ceiling on one actor’s whole recovery — snapshot load, journal read, fold, and the highestSeq probe a fully compacted stream needs; for a ReplicatedEventSourcedActor, its snapshot load and journal read. Past it the replay fails with a RecoveryTimeoutError — through onRecoveryFailure on a PersistentActor, as a failed preStart on a ReplicatedEventSourcedActor, which has no such hook. 0 is no deadline. |
persistence.snapshot-is-optional | false | Fall back to a full journal replay when the snapshot store cannot answer. Never applies to an actor that set integrity() or encryption() — see below. |
persistence.journal-breaker | "persistence-journal" | Circuit-breaker id the journal is called through; "" disables it. Its numbers live under actor-ts.circuit-breaker.persistence-journal. |
persistence.snapshot-breaker | "persistence-snapshot" | As above, for the snapshot store. |
persistence.auto-start | on | Open the selected journal, snapshot store and durable-state store in the startup’s persistence-start phase, so a plug-in nothing registered or a store that cannot open fails the startup instead of the first persisted message. off opens them on their first operation. withPersistence({ behavior }) wins over it, and a WorkerMesh worker always runs with it off — see opening the stores at startup. |
persistence.journal.plugin | "...in-memory" | Fully-qualified key to the journal’s config. |
persistence.snapshot-store.plugin | "...in-memory" | Fully-qualified key to the snapshot store’s config. |
persistence.durable-state.plugin | "...in-memory" | Fully-qualified key to the durable-state store’s config. |
persistence.snapshot-store.in-memory.keep-n | 0 | Snapshots the built-in in-memory store keeps per persistenceId. 0 keeps every one — the opposite polarity from the persistent stores’ 3, because this is the store an unconfigured application gets and a bound here would silently discard snapshots. |
persistence.journal.sqlite.path | "" | Database file, or ":memory:" for an in-memory database. Empty is not set, with no default behind it: a selected journal with no path, here or in code, is refused at registration. |
persistence.journal.sqlite.events-table | "events" | Event table. The tags (_tags) and metadata (_meta) tables follow this name. |
persistence.journal.sqlite.wal | off | Open the database with journal_mode = WAL — concurrent readers during a write. |
persistence.journal.sqlite.busy-timeout | 1s | How long a blocked writer waits for the lock before SQLITE_BUSY; 0 fails fast. |
persistence.snapshot-store.sqlite.path | "" | As above: empty is not set, a selected store with no path is refused at registration, and ":memory:" is the explicit in-memory database. |
persistence.snapshot-store.sqlite.snapshots-table | "snapshots" | Snapshot table. |
persistence.snapshot-store.sqlite.keep-n | 3 | Snapshots kept per persistenceId; 0 disables pruning. |
persistence.snapshot-store.sqlite.busy-timeout | 1s | As above. |
persistence.durable-state.sqlite.path | "" | As above, except that a database handed over in code stands in for the path: a selected store with neither is refused at registration. |
persistence.durable-state.sqlite.table | "durable_state" | Durable-state table. |
persistence.durable-state.sqlite.auto-create-tables | on | Run CREATE TABLE IF NOT EXISTS when the store opens — at startup, unless persistence.auto-start is off. Off when a schema tool owns the DDL. |
persistence.durable-state.sqlite.busy-timeout | 1s | As above. |
persistence.snapshot-store.object-storage.backend | "" | Which backend the object-storage plugin builds — filesystem, s3, or empty to leave it to code. |
persistence.snapshot-store.object-storage.prefix | "" | Prepended to every object key — e.g. env-prod/. |
persistence.snapshot-store.object-storage.keep-n | 3 | Snapshots kept per persistenceId; 0 disables pruning. |
persistence.snapshot-store.object-storage.max-decompressed-bytes | 512M | Decompression-bomb guard on read. Infinity opts out and is code-only, because HOCON has no Infinity literal — withMaxDecompressedBytes(Infinity) and a withConfig overrides object both reach it. |
persistence.snapshot-store.object-storage.compression.algorithm | "gzip" | At-rest compression — none / gzip / zstd. |
persistence.snapshot-store.object-storage.encryption.mode | "none" | Server-side encryption — none / sse-s3 / sse-kms. client-aes256-gcm is refused here. |
persistence.snapshot-store.object-storage.encryption.kms-key-id | "" | KMS key ARN, required when the mode is sse-kms. A key name, never key material. |
persistence.snapshot-store.object-storage.s3.bucket | "" | Bucket name. Required when backend = s3. |
persistence.snapshot-store.object-storage.s3.region | "" | AWS region; auto for Cloudflare R2. Required when backend = s3. |
persistence.snapshot-store.object-storage.s3.endpoint | "" | MinIO / R2 / B2 / Spaces / Wasabi endpoint; empty means AWS S3. |
persistence.snapshot-store.object-storage.s3.force-path-style | off | Path-style URLs instead of virtual-host style — required for MinIO. |
persistence.snapshot-store.object-storage.filesystem.dir | "" | Root directory, created recursively. Required when backend = filesystem. |
persistence.snapshot-store.object-storage.filesystem.lock-timeout | 5s | Wait for a per-key write lock before failing. |
persistence.snapshot-store.object-storage.filesystem.stale-lock | 30s | Lock files older than this are force-removed. |
The two breaker leaves are ids, not blocks of numbers. A breaker’s
settings live under actor-ts.circuit-breaker.<id>, layered over
actor-ts.circuit-breaker.default — that is the one home for them, and
publishing max-failures a second time under actor-ts.persistence would be
two places to change one thing. What ships by default is the failure count
(10 in a row, then 15 s of fast-fail) and no call-timeout, because
omitting it is what means “no deadline”. To put a ceiling on a single append
— the fix for a backend that accepts the connection and then stalls — name it:
actor-ts.circuit-breaker.persistence-journal.call-timeout = 10sA JournalConcurrencyError never counts as a breaker failure: it is the
ownership verdict of a conditional append, not an outage, and ten unlucky
entities losing a race must not fast-fail every healthy one on the node. The
same holds for JournalIntegrityError and SnapshotIntegrityError — a
durable fact about the stored bytes that waiting cannot change.
snapshot-is-optional deliberately does not cover a snapshot that failed to
verify. Stores that check integrity reject a tampered body the same way
they report being unreachable, so an actor whose persistenceOptions carry
integrity or encryption gets no fallback at all — tolerating the outage
would tolerate the tampering, and turn an integrity control into a retry.
The five behaviour leaves cover every PersistentActor, and a
ReplicatedEventSourcedActor’s own persist, its recovery and its snapshot
saves; its append of an event a peer sent is not behind the journal breaker
until #958. DurableStateActor is outside all of this: none of these leaves
reaches a durable-state store, whether its DurableStateOptions name one or it
uses the system-wide store persistence.durable-state.plugin selects.
The object-storage block configures both stores
registerObjectStoragePlugins(persistence) returns: the snapshot store and the
durable-state store share one backend, so it is declared once rather than
twice. With the block filled in, the plug-in needs no options at all —
(persistence) => registerObjectStoragePlugins(persistence) in the plugins
slot of ActorSystemOptions.withPersistence. Explicit
ObjectStoragePluginOptions still win, field by field, and a field left unset
in code falls through to the block instead of shadowing it. Values are
validated once, on the merged settings, so backend = s3 without a bucket is
refused with an OptionsError naming backend.bucket when the plug-in runs,
and the startup fails rather than the first snapshot.
No key material has a path in that block, and that is structural rather than
a convention. There is no leaf for S3 credentials, for a client-side master
key or for an integrity key, so a config file cannot express one. Omitting S3
credentials falls through to the SDK’s default chain — AWS_ACCESS_KEY_ID /
AWS_SECRET_ACCESS_KEY, an EC2 instance profile, or IAM Roles for Service
Accounts. encryption.mode = client-aes256-gcm is refused with an
OptionsError rather than quietly ignored, because a deployment that asked for
client-side encryption and silently got plaintext is the worse outcome;
configure that mode in code with ObjectStoragePluginOptions.withEncryption(…).
kms-key-id is fine — an ARN is a name, and the key itself never leaves KMS.
durable-state.plugin is the third axis, and it is new. Durable state used
to be the one persistence contract with no registry: every registerXxxPlugins
helper built its store eagerly and handed it back, so a DurableStateActor had
to be given that instance in code. It is now selected exactly like the journal
and the snapshot store, and DurableStateOptions.store is optional — an actor
that names no store uses whichever this key selects.
SQLite is registered through the plugins slot with registerSqlitePlugins,
and needs no options at all when the three blocks above are filled in:
const systemOptions = ActorSystemOptions.create().withPersistence({ plugins: [(persistence) => registerSqlitePlugins(persistence)], // path, tables, retention … from HOCON});Precedence is the usual three layers — explicit RegisterSqlitePluginsOptions
outrank the block, the block outranks the built-in defaults, per field, and a
field left unset in code falls through instead of shadowing. A path given in
code is shared by all three stores as a default, so a leaf that names its own
keeps it; a pre-opened database overrides the durable-state leaf’s own and
reaches that store only, because the journal and the snapshot store open their
own file. There is no leaf for a driver, a database or a serializer —
those are live objects, and a config file cannot express one.
A store the configuration selects has to name its database. One whose block and
code options leave path unset, or set it empty or to a remote URL, is refused
when registerSqlitePlugins runs, so ActorSystem.create throws with an error
that names the key; path = ":memory:" is the explicit in-memory database. A
store that is registered but not selected is never built, so it needs nothing.
The five relational backends read their own blocks too (#872). Postgres,
MariaDB, SQL Server, libSQL and Cloudflare D1 share one journal, one snapshot
store and one durable-state store between them, so the table half of every block
is the same three or four leaves and only the connection half differs.
registerPostgresPlugins(persistence) — and each of its four siblings — therefore
needs no options at all when the blocks below are filled in:
const systemOptions = ActorSystemOptions.create().withPersistence({ plugins: [(persistence) => registerPostgresPlugins(persistence)], // url, tables, retention ... from HOCON});The connection is repeated under each of the three plugin roots rather than
hoisted to a per-backend one, because a plugin id is its config section and the
three axes are selected independently — they may legitimately name different
databases. A deployment that shares one connection writes it once and
substitutes: url = ${actor-ts.persistence.journal.postgres.url}.
Three things deliberately have no leaf. A pre-built pool or client and a
serializer are live objects, so a config file cannot express one. poolConfig
is the driver’s whole option surface, free-form and unvalidated, so it stays
code-only — the long tail. For SQL Server that means a purely config-driven
store is reached through url, in the Server=...;Database=... form. An
mssql:// url passes the read like any other string and is refused with an
OptionsError when the store is built: node-mssql has parsed none since its
8.0, and reads one as a single unknown key with no server behind it.
What an operator does tune on the three SQL drivers has typed leaves instead
(#1490): max-pool-size, idle-timeout, connect-timeout and ca-file under
every Postgres, MariaDB and SQL Server block, plus MariaDB’s acquire-timeout
and SQL Server’s request-timeout. Every one is comment-only — unset
leaves the driver’s own default, the only value that keeps tracking it — and
reaches the driver under the driver’s own name only when set. Each is read
when the store is built. A value of the wrong kind — a word where a number
goes, a fraction where a count goes, a duration that does not parse — fails
that read, with a ConfigError naming the leaf, or for the duration an error
naming only the value. One of the right kind is then checked by the store: a
size below 1, a timeout that is not a positive whole number of milliseconds,
a timeout the driver could not arm as a timer (above about 24.8 days), and a
MariaDB idle-timeout that is not a whole number of seconds — the connector
counts it in seconds — are refused with an OptionsError. So is a setting
made twice: a leaf beside the same key in poolConfig or in the url
(connectionLimit in a MariaDB url, Max Pool Size in a SQL Server connection
string) is refused naming both, rather than one quietly winning. ca-file is
a path the framework reads when the pool opens, never the certificate itself;
it is how a server behind a private CA is reached from configuration, and the
only way for MariaDB and SQL Server, whose urls cannot carry a CA. It is
refused beside anything that says otherwise about TLS: a url ssl parameter for
Postgres, which node-postgres would put in its place; an ssl the MariaDB
connector reads as false; an Encrypt or TrustServerCertificate that leaves
the CA unused on SQL Server; or a poolConfig that names another CA.
And tags-table is a comment in the reference configuration rather than a
key, because its default is derived from events-table (<events-table>_tags):
absence is what keeps the two in step. It is read all the same, so an
application.conf can still pin it.
The two credentials that do have a leaf — libSQL’s auth-token and D1’s
api-token — are strings the operator supplies from somewhere, and the
documented route is a substitution (api-token = ${?CLOUDFLARE_API_TOKEN}).
Both ship empty, and empty reads as not set, so the placeholder never becomes a
bearer token.
A url that switches TLS verification off is refused for Postgres, SQL
Server and MongoDB (#1490). Their drivers read a verification switch out of the
connection string itself — sslmode=no-verify or ssl=no-verify, and under
uselibpqcompat=true also sslmode=prefer, require or verify-ca;
TrustServerCertificate set to anything but false, no, 0 or empty; and
tlsInsecure, tlsAllowInvalidCertificates or tlsAllowInvalidHostnames set
to anything but false — so their readers inspect the leaf and throw a
ConfigError naming it and the switch, in any letter case of the key and for a
${?…} substitution alike. Only HOCON is inspected: the same string passed to
withUrl(...) is the code’s decision. About the file the refusal is strict,
refusing a block’s url even when code supplies its own connection. Plaintext
is a different decision and stays allowed (sslmode=disable, Encrypt=false,
tls=false), and MariaDB is not inspected at all: its connector reads the url’s
ssl as a boolean, and ssl=true verifies.
TLS everywhere has
the reasoning and the config-only routes to a private CA.
PostgreSQL
Section titled “PostgreSQL”| Key | Default | Purpose |
|---|---|---|
persistence.journal.postgres.url | "" | Connection string. Empty is not set — the store falls through to the connection the register helper was given. |
persistence.journal.postgres.events-table | "events" | Event table. The tags join table is derived as <events-table>_tags. |
persistence.journal.postgres.auto-create-tables | on | Run CREATE TABLE IF NOT EXISTS when the store opens — at startup, unless persistence.auto-start is off. Off when a schema tool owns the DDL. |
persistence.journal.postgres.max-pool-size | (unset) | Connections the pool holds — pg-pool’s max, which defaults to 10. Comment-only, as are the three below. |
persistence.journal.postgres.idle-timeout | (unset) | How long an idle connection stays open — pg-pool’s idleTimeoutMillis, default 10s. |
persistence.journal.postgres.connect-timeout | (unset) | How long opening a connection may take — pg’s connectionTimeoutMillis; unset, it waits indefinitely. |
persistence.journal.postgres.ca-file | (unset) | PEM file of the CA that signed the server certificate, read when the pool opens and handed to pg as ssl.ca. Refused beside a url ssl parameter. |
persistence.snapshot-store.postgres.url | "" | As above. |
persistence.snapshot-store.postgres.snapshots-table | "snapshots" | Snapshot table. |
persistence.snapshot-store.postgres.keep-n | 3 | Snapshots kept per persistenceId; 0 disables pruning. |
persistence.snapshot-store.postgres.auto-create-tables | on | As above. |
persistence.snapshot-store.postgres.max-pool-size, idle-timeout, connect-timeout, ca-file | (unset) | As above. |
persistence.durable-state.postgres.url | "" | As above. |
persistence.durable-state.postgres.table | "durable_state" | Durable-state table. |
persistence.durable-state.postgres.auto-create-tables | on | As above. |
persistence.durable-state.postgres.max-pool-size, idle-timeout, connect-timeout, ca-file | (unset) | As above. |
MariaDB / MySQL
Section titled “MariaDB / MySQL”| Key | Default | Purpose |
|---|---|---|
persistence.journal.mariadb.url | "" | Connection string. Empty is not set — the store falls through to the connection the register helper was given. |
persistence.journal.mariadb.events-table | "events" | Event table. The tags join table is derived as <events-table>_tags. |
persistence.journal.mariadb.auto-create-tables | on | Run CREATE TABLE IF NOT EXISTS when the store opens — at startup, unless persistence.auto-start is off. Off when a schema tool owns the DDL. |
persistence.journal.mariadb.max-pool-size | (unset) | Connections the pool holds — the connector’s connectionLimit, which defaults to 10. Comment-only, as are the four below. |
persistence.journal.mariadb.acquire-timeout | (unset) | How long a caller waits for a free connection — acquireTimeout, default 10s. |
persistence.journal.mariadb.idle-timeout | (unset) | How long an idle connection stays open — idleTimeout, default 1800s. Whole seconds only: the connector counts in seconds. |
persistence.journal.mariadb.connect-timeout | (unset) | How long opening a connection may take — connectTimeout, default 1s, capped at the acquire timeout. |
persistence.journal.mariadb.ca-file | (unset) | PEM file of the CA that signed the server certificate, read when the pool opens and handed to the connector as ssl.ca. Refused beside a url ssl that switches TLS off. |
persistence.snapshot-store.mariadb.url | "" | As above. |
persistence.snapshot-store.mariadb.snapshots-table | "snapshots" | Snapshot table. |
persistence.snapshot-store.mariadb.keep-n | 3 | Snapshots kept per persistenceId; 0 disables pruning. |
persistence.snapshot-store.mariadb.auto-create-tables | on | As above. |
persistence.snapshot-store.mariadb.max-pool-size, acquire-timeout, idle-timeout, connect-timeout, ca-file | (unset) | As above. |
persistence.durable-state.mariadb.url | "" | As above. |
persistence.durable-state.mariadb.table | "durable_state" | Durable-state table. |
persistence.durable-state.mariadb.auto-create-tables | on | As above. |
persistence.durable-state.mariadb.max-pool-size, acquire-timeout, idle-timeout, connect-timeout, ca-file | (unset) | As above. |
SQL Server
Section titled “SQL Server”| Key | Default | Purpose |
|---|---|---|
persistence.journal.mssql.url | "" | Connection string. Empty is not set — the store falls through to the connection the register helper was given. |
persistence.journal.mssql.events-table | "events" | Event table. The tags join table is derived as <events-table>_tags. |
persistence.journal.mssql.auto-create-tables | on | Run CREATE TABLE IF NOT EXISTS when the store opens — at startup, unless persistence.auto-start is off. Off when a schema tool owns the DDL. |
persistence.journal.mssql.max-pool-size | (unset) | Connections the pool holds — node-mssql’s pool.max, which defaults to 10. Comment-only, as are the four below. |
persistence.journal.mssql.idle-timeout | (unset) | How long an idle connection stays open — pool.idleTimeoutMillis, default 30s. |
persistence.journal.mssql.connect-timeout | (unset) | How long opening a connection may take — connectionTimeout, default 15s. |
persistence.journal.mssql.request-timeout | (unset) | How long one request may run — requestTimeout, default 15s. |
persistence.journal.mssql.ca-file | (unset) | PEM file of the CA that signed the server certificate, read when the pool opens and handed to tedious to verify against — a connection string has no key for one. Refused beside an Encrypt or TrustServerCertificate in the url that leaves it unused. |
persistence.snapshot-store.mssql.url | "" | As above. |
persistence.snapshot-store.mssql.snapshots-table | "snapshots" | Snapshot table. |
persistence.snapshot-store.mssql.keep-n | 3 | Snapshots kept per persistenceId; 0 disables pruning. |
persistence.snapshot-store.mssql.auto-create-tables | on | As above. |
persistence.snapshot-store.mssql.max-pool-size, idle-timeout, connect-timeout, request-timeout, ca-file | (unset) | As above. |
persistence.durable-state.mssql.url | "" | As above. |
persistence.durable-state.mssql.table | "durable_state" | Durable-state table. |
persistence.durable-state.mssql.auto-create-tables | on | As above. |
persistence.durable-state.mssql.max-pool-size, idle-timeout, connect-timeout, request-timeout, ca-file | (unset) | As above. |
libSQL / Turso
Section titled “libSQL / Turso”| Key | Default | Purpose |
|---|---|---|
persistence.journal.libsql.url | "" | Connection string. Empty is not set — the store falls through to the connection the register helper was given. |
persistence.journal.libsql.auth-token | "" | Turso auth token. Empty is not set; prefer ${?TURSO_AUTH_TOKEN}. |
persistence.journal.libsql.events-table | "events" | Event table. The tags join table is derived as <events-table>_tags. |
persistence.journal.libsql.auto-create-tables | on | Run CREATE TABLE IF NOT EXISTS when the store opens — at startup, unless persistence.auto-start is off. Off when a schema tool owns the DDL. |
persistence.snapshot-store.libsql.url | "" | As above. |
persistence.snapshot-store.libsql.auth-token | "" | As above. |
persistence.snapshot-store.libsql.snapshots-table | "snapshots" | Snapshot table. |
persistence.snapshot-store.libsql.keep-n | 3 | Snapshots kept per persistenceId; 0 disables pruning. |
persistence.snapshot-store.libsql.auto-create-tables | on | As above. |
persistence.durable-state.libsql.url | "" | As above. |
persistence.durable-state.libsql.auth-token | "" | As above. |
persistence.durable-state.libsql.table | "durable_state" | Durable-state table. |
persistence.durable-state.libsql.auto-create-tables | on | As above. |
Cloudflare D1
Section titled “Cloudflare D1”| Key | Default | Purpose |
|---|---|---|
persistence.journal.cloudflare-d1.account-id | "" | Cloudflare account id. Empty is not set. |
persistence.journal.cloudflare-d1.database-id | "" | D1 database id — the UUID, not the database name. |
persistence.journal.cloudflare-d1.api-token | "" | API token with D1:Edit. Empty is not set; prefer ${?CLOUDFLARE_API_TOKEN}. |
persistence.journal.cloudflare-d1.base-url | "https://api.cloudflare.com/client/v4" | D1 REST endpoint. Override only for a proxy or a test double. |
persistence.journal.cloudflare-d1.timeout | 30s | Deadline on one D1 request. A replay reads an actor’s whole history in one statement, which is one request, so this bounds a whole recovery. |
persistence.journal.cloudflare-d1.max-response-bytes | 64M | Ceiling on one D1 response body. The whole replay arrives as one response; raise it when a long history stops recovering. |
persistence.journal.cloudflare-d1.events-table | "events" | Event table. The tags join table is derived as <events-table>_tags. |
persistence.journal.cloudflare-d1.auto-create-tables | on | Run CREATE TABLE IF NOT EXISTS when the store opens — at startup, unless persistence.auto-start is off. Off when a schema tool owns the DDL. |
persistence.snapshot-store.cloudflare-d1.account-id | "" | As above. |
persistence.snapshot-store.cloudflare-d1.database-id | "" | As above. |
persistence.snapshot-store.cloudflare-d1.api-token | "" | As above. |
persistence.snapshot-store.cloudflare-d1.base-url | "https://api.cloudflare.com/client/v4" | As above. |
persistence.snapshot-store.cloudflare-d1.timeout | 30s | As above. |
persistence.snapshot-store.cloudflare-d1.max-response-bytes | 64M | As above. |
persistence.snapshot-store.cloudflare-d1.snapshots-table | "snapshots" | Snapshot table. |
persistence.snapshot-store.cloudflare-d1.keep-n | 3 | Snapshots kept per persistenceId; 0 disables pruning. |
persistence.snapshot-store.cloudflare-d1.auto-create-tables | on | As above. |
persistence.durable-state.cloudflare-d1.account-id | "" | As above. |
persistence.durable-state.cloudflare-d1.database-id | "" | As above. |
persistence.durable-state.cloudflare-d1.api-token | "" | As above. |
persistence.durable-state.cloudflare-d1.base-url | "https://api.cloudflare.com/client/v4" | As above. |
persistence.durable-state.cloudflare-d1.timeout | 30s | As above. |
persistence.durable-state.cloudflare-d1.max-response-bytes | 64M | As above. |
persistence.durable-state.cloudflare-d1.table | "durable_state" | Durable-state table. |
persistence.durable-state.cloudflare-d1.auto-create-tables | on | As above. |
The three non-relational backends read their own blocks too (#872). They do
not share an implementation with each other or with the SQL family, so each
block speaks its own backend’s vocabulary — Mongo has collections and creates
indexes, DynamoDB has account-global table names and a region rather than a
URL, and Cassandra is reached by a seed list and lays out four tables.
registerMongoPlugins(persistence), registerDynamoDbPlugins(persistence) and
registerCassandraPlugins(persistence) therefore need no options at all once
the blocks below are filled in.
Cassandra has no durable-state block, and that is not an omission: the
framework ships no Cassandra durable-state store, so that backend has two plugin
axes where the other two have three.
MongoDB
Section titled “MongoDB”| Key | Default | Purpose |
|---|---|---|
persistence.journal.mongodb.url | "" | Connection string — mongodb://… or mongodb+srv://…. Empty is not set. |
persistence.journal.mongodb.database-name | "actor_ts" | Database the collections live in. |
persistence.journal.mongodb.events-collection | "events" | Events collection. Its meta collection is <it>_meta. |
persistence.journal.mongodb.auto-create-indexes | on | Create the indexes when the store opens — at startup, unless persistence.auto-start is off. The unique index is what refuses a duplicate append, so off means I created them myself. |
persistence.journal.mongodb.max-pool-size | (unset) | Connections the client holds open to one server — the driver’s maxPoolSize, which defaults to 100. Comment-only, as are the four below. |
persistence.journal.mongodb.min-pool-size | (unset) | Connections kept open ahead of use — minPoolSize, default 0. At most max-pool-size. |
persistence.journal.mongodb.server-selection-timeout | (unset) | How long an operation waits for a server it can use — serverSelectionTimeoutMS, default 30s. |
persistence.journal.mongodb.connect-timeout | (unset) | How long opening a connection may take — connectTimeoutMS, default 30s. |
persistence.journal.mongodb.ca-file | (unset) | PEM file of the CA that signed the server certificate, read when the client opens and handed to the driver as ca, with TLS on. Refused beside a url tlsCAFile, and beside a tls or ssl set to false. |
persistence.snapshot-store.mongodb.url | "" | As above. |
persistence.snapshot-store.mongodb.database-name | "actor_ts" | As above. |
persistence.snapshot-store.mongodb.snapshots-collection | "snapshots" | Snapshots collection. |
persistence.snapshot-store.mongodb.keep-n | 3 | Snapshots kept per persistenceId; 0 disables pruning. |
persistence.snapshot-store.mongodb.auto-create-indexes | on | As above. |
persistence.snapshot-store.mongodb.max-pool-size, min-pool-size, server-selection-timeout, connect-timeout, ca-file | (unset) | As above. |
persistence.durable-state.mongodb.url | "" | As above. |
persistence.durable-state.mongodb.database-name | "actor_ts" | As above. |
persistence.durable-state.mongodb.collection | "durable_state" | Durable-state collection. |
persistence.durable-state.mongodb.max-pool-size, min-pool-size, server-selection-timeout, connect-timeout, ca-file | (unset) | As above. |
clientOptions has no leaf — the driver’s whole option surface, which stays
code-only — and neither does a pre-built client or a serializer. What an
operator tunes on the client has the typed leaves above instead (#1490), each
comment-only so that unset keeps the driver’s own default, mongodb 6 and 7
alike. The store checks them when it is built, as it checks the SQL ones, and a
leaf beside the same option in clientOptions or in the url’s query is refused
naming both: the driver reads all three case-insensitively, keeps the object’s
value and drops the url’s without a word.
The url is inspected like the relational ones above: tlsInsecure,
tlsAllowInvalidCertificates or tlsAllowInvalidHostnames set to anything but
false is refused. A private CA goes into the url as tlsCAFile or beside it
as ca-file — one or the other, since the driver reads tlsCAFile only when it
was handed no CA.
DynamoDB
Section titled “DynamoDB”| Key | Default | Purpose |
|---|---|---|
persistence.journal.dynamodb.region | "" | AWS region, e.g. eu-central-1. Empty is not set. |
persistence.journal.dynamodb.endpoint | "" | Endpoint override for dynamodb-local or LocalStack; empty means the real service. |
persistence.journal.dynamodb.events-table | "actor_ts_events" | Events table. Prefixed because a DynamoDB table name is account- and region-global. |
persistence.journal.dynamodb.billing-mode | "pay-per-request" | How a table the store creates is billed: pay-per-request (on-demand) or provisioned. AWS’s own spelling is refused. |
persistence.journal.dynamodb.provisioned-throughput.read-capacity-units | (unset) | Deliberately a comment, as is the write half below. The read capacity a provisioned table is created with; refused under pay-per-request. |
persistence.journal.dynamodb.provisioned-throughput.write-capacity-units | (unset) | The write half. Set both or neither: with neither, a provisioned table gets 5 read and 5 write units. |
persistence.journal.dynamodb.table-ready-timeout | 30s | How long a table the store just created may take to become ACTIVE. |
persistence.journal.dynamodb.auto-create-tables | on | CreateTable when the store opens — at startup, unless persistence.auto-start is off; an existing table is the expected case. Off when the tables are provisioned elsewhere. |
persistence.journal.dynamodb.max-attempts | (unset) | Attempts per request, the first included — the SDK’s maxAttempts. Comment-only, as are the three below: unset leaves the SDK’s own resolution (AWS_MAX_ATTEMPTS, the shared config file, then 3). |
persistence.journal.dynamodb.retry-mode | (unset) | standard or adaptive — the SDK’s retryMode; any other word is refused. Unset: AWS_RETRY_MODE, the shared config file, then standard. |
persistence.journal.dynamodb.request-timeout | (unset) | How long one attempt may take before it fails — the request handler’s requestTimeout, with throwOnRequestTimeout on. Unset: no limit. |
persistence.journal.dynamodb.connection-timeout | (unset) | How long opening the connection may take — the request handler’s connectionTimeout. Unset: no limit. |
persistence.snapshot-store.dynamodb.region | "" | As above. |
persistence.snapshot-store.dynamodb.endpoint | "" | As above. |
persistence.snapshot-store.dynamodb.snapshots-table | "actor_ts_snapshots" | Snapshots table. |
persistence.snapshot-store.dynamodb.keep-n | 3 | Snapshots kept per persistenceId; 0 disables pruning. |
persistence.snapshot-store.dynamodb.billing-mode | "pay-per-request" | As above. |
persistence.snapshot-store.dynamodb.provisioned-throughput.read-capacity-units | (unset) | As above. |
persistence.snapshot-store.dynamodb.provisioned-throughput.write-capacity-units | (unset) | As above. |
persistence.snapshot-store.dynamodb.table-ready-timeout | 30s | As above. |
persistence.snapshot-store.dynamodb.auto-create-tables | on | As above. |
persistence.snapshot-store.dynamodb.max-attempts, retry-mode, request-timeout, connection-timeout | (unset) | As above. |
persistence.durable-state.dynamodb.region | "" | As above. |
persistence.durable-state.dynamodb.endpoint | "" | As above. |
persistence.durable-state.dynamodb.table | "actor_ts_durable_state" | Durable-state table. |
persistence.durable-state.dynamodb.billing-mode | "pay-per-request" | As above. |
persistence.durable-state.dynamodb.provisioned-throughput.read-capacity-units | (unset) | As above. |
persistence.durable-state.dynamodb.provisioned-throughput.write-capacity-units | (unset) | As above. |
persistence.durable-state.dynamodb.table-ready-timeout | 30s | As above. |
persistence.durable-state.dynamodb.auto-create-tables | on | As above. |
persistence.durable-state.dynamodb.max-attempts, retry-mode, request-timeout, connection-timeout | (unset) | As above. |
Credentials have no leaf: omitted, the SDK’s own default chain supplies them.
clientConfig has none either — the SDK’s whole option surface, which stays
code-only — but what an operator tunes on the client does: the four typed
leaves above (#1490), comment-only so that unset keeps the SDK’s own
resolution, which a shipped value would overrule. The store checks them when it
is built, and a leaf beside what it replaces in clientConfig — maxAttempts,
retryMode, a retryStrategy that makes both moot, or a requestHandler — is
refused naming both. request-timeout sets throwOnRequestTimeout beside the
handler’s requestTimeout, without which the handler only logs that a request
ran long. Table provisioning has leaves too (#1490): the billing
mode’s values are kebab-case like every HOCON value, and the reader maps them to
AWS’s PAY_PER_REQUEST and PROVISIONED. The capacity pair ships as a comment
because, published, it would be refused under the default pay-per-request,
where AWS ignores capacity; a provisioned table with no pair is created at 5
read and 5 write capacity units, so name the pair when you provision on purpose.
Cassandra / ScyllaDB
Section titled “Cassandra / ScyllaDB”| Key | Default | Purpose |
|---|---|---|
persistence.journal.cassandra.contact-points | [] | Seed nodes the cluster topology is discovered from. [] is not set — the list shape of the "" idiom. |
persistence.journal.cassandra.keyspace | "" | Keyspace every statement names (keyspace.table); the client is never bound to it with USE. Empty is not set; required at the point of use. |
persistence.journal.cassandra.local-data-center | "datacenter1" | Local DC for DCAwareRoundRobinPolicy. |
persistence.journal.cassandra.port | 9042 | CQL native-transport port. |
persistence.journal.cassandra.auto-create-keyspace | off | CREATE KEYSPACE on start, with the replication below — a development convenience. |
persistence.journal.cassandra.replication.class | "simple-strategy" | The keyspace’s replication strategy: simple-strategy or network-topology-strategy. CQL’s own class names are refused. Read only by auto-create-keyspace. |
persistence.journal.cassandra.replication.replication-factor | 1 | Copies of every row under simple-strategy. |
persistence.journal.cassandra.replication.data-centers | (unset) | Deliberately a comment. Copies per data center under network-topology-strategy, as a list of { name, replication-factor } entries; refused under simple-strategy. |
persistence.journal.cassandra.consistency | (unset) | Deliberately a comment in reference.conf. Unset, the driver picks the CQL level; set the numeric value from types.consistencies (6 = LOCAL_QUORUM) to pin it. |
persistence.journal.cassandra.events-table | "events" | Events table. |
persistence.journal.cassandra.metadata-table | "metadata" | Highest sequence number per persistenceId. |
persistence.journal.cassandra.all-ids-table | "all_persistence_ids" | The lookup behind persistenceIds(). |
persistence.journal.cassandra.tag-index-table | "events_by_tag" | Side table, written only when use-tag-index is on. |
persistence.journal.cassandra.partition-size | 500000 | Rows per partition before rolling over to a new one. |
persistence.journal.cassandra.auto-create-tables | on | Create the four tables when the store connects — at startup, unless persistence.auto-start is off. |
persistence.journal.cassandra.use-tag-index | off | Dual-write an events_by_tag side table so tag queries walk one partition. |
persistence.journal.cassandra.lightweight-transactions | on | Claim the sequence range with Paxos before writing. Off risks a silently lost append, because a Cassandra INSERT is an upsert. |
persistence.journal.cassandra.serial-consistency | (unset) | Deliberately a comment. Ignored unless the LWT above is on; unset the driver picks cluster-wide SERIAL. 9 is localSerial. |
persistence.snapshot-store.cassandra.contact-points | [] | As above. |
persistence.snapshot-store.cassandra.keyspace | "" | As above. |
persistence.snapshot-store.cassandra.local-data-center | "datacenter1" | As above. |
persistence.snapshot-store.cassandra.port | 9042 | As above. |
persistence.snapshot-store.cassandra.auto-create-keyspace | off | As above. |
persistence.snapshot-store.cassandra.replication.class | "simple-strategy" | As above. |
persistence.snapshot-store.cassandra.replication.replication-factor | 1 | As above. |
persistence.snapshot-store.cassandra.replication.data-centers | (unset) | As above. |
persistence.snapshot-store.cassandra.consistency | (unset) | As above. |
persistence.snapshot-store.cassandra.snapshots-table | "snapshots" | Snapshots table. |
persistence.snapshot-store.cassandra.keep-n | 3 | Snapshots kept per persistenceId; 0 disables pruning. |
persistence.snapshot-store.cassandra.auto-create-tables | on | As above. |
credentials has no leaf at all — it is key material, and key material is
never expressible in a config file. replication is not free-form (#1490): it
is the typed shape the keyspace DDL is built from, so its leaves are read one by
one, and a verbatim object never reaches the DDL. Its data centers are a list
rather than a map because a data center’s name is data, not a key — as a key,
an unquoted eu.west would nest instead of naming one.
The plugin keys point to another config section that holds
that plugin’s settings. actor-ts.persistence.journal.sqlite above is the
worked example: it is both the id the journal is registered under and the block
that journal reads. See each journal page in
Persistence for the per-plugin keys.
actor-ts.circuit-breaker
Section titled “actor-ts.circuit-breaker”| Key | Default | Purpose |
|---|---|---|
circuit-breaker.default.max-failures | 10 | Consecutive failures before a breaker opens (circuit breaker). |
circuit-breaker.default.reset-timeout | 15s | How long it stays open before letting a probe through. |
circuit-breaker.default.max-reset-timeout | 60s | Ceiling the grown window is clamped to. Must be at least reset-timeout — a breaker whose merged settings say otherwise refuses to start. |
circuit-breaker.default.backoff-factor | 1.0 | Multiplier per consecutive open. 1.0 = the flat window every earlier release had. |
circuit-breaker.default.random-factor | 0.0 | Jitter fraction in [0, 1] spread over that window. 0.0 = no jitter. |
circuit-breaker.default.ignored-error-names | [] | Error.name values that never count as a failure. |
circuit-breaker.default.call-timeout | (unset) | Deliberately a comment in reference.conf — see below. Unset, there is no per-call deadline. |
circuit-breaker.<id>.* | (the block above) | The same leaves, for the single breaker breaker('<id>') resolves — overrides the default block leaf by leaf. |
These are read by the CircuitBreakerExtension, the door that resolves a
breaker by id:
import { CircuitBreakerExtensionId } from 'actor-ts';
const payments = system.extension(CircuitBreakerExtensionId).breaker('payment-api');await payments.call(() => fetch('https://payments.example/charge'));new CircuitBreaker({ … }) reads none of this and is unchanged — it is the
door for a breaker whose settings live in code. Explicit options passed as
breaker(id, options) still outrank both blocks, which is what carries the two
things HOCON cannot express: the isFailure predicate and the random seam.
default is reserved, and the two readings of it coincide: it is the block
every breaker inherits from and the id breaker() resolves with no argument,
so a breaker named default reads exactly the block that configures it. That
is the reason the defaults sit in a named sub-block rather than at
actor-ts.circuit-breaker.* directly — there, ids and leaves would share one
namespace, and breaker('random-factor') would go looking for its settings
inside a number.
call-timeout is a comment rather than a leaf because omitting
callTimeoutMs is what disables the per-call timeout, and 0 is refused by
the validator — so “no deadline” is a state only a missing key can express.
Writing it works normally; the block simply does not publish a default that
would hand every config-resolved breaker a deadline a hand-built one lacks.
backoff-factor and random-factor ship neutral on purpose. 1.0 and
0.0 reproduce the flat, unjittered reopen window exactly, so the block is
additive and turning either on is a change a deployment makes deliberately.
With both set, the window is
reset-timeout × backoff-factor^(consecutive opens − 1), clamped to
max-reset-timeout and then spread by ± random-factor; it returns to
reset-timeout as soon as a probe succeeds and the breaker closes.
ignored-error-names is checked before isFailure, not after. The list
is the operator’s half of the classifier and arrives from a config file, while
the predicate is compiled in — if the predicate could overrule the list, the
leaf would go inert for exactly the deployments that set it.
These <id> paths take the id your code asks breaker(id) for, so they cannot
be enumerated in reference.conf.
actor-ts.projection
Section titled “actor-ts.projection”| Key | Default | Purpose |
|---|---|---|
projection.recovery-strategy | "retry-and-fail" | What a projection does when its handler throws — fail, skip, retry-and-fail or retry-and-skip (when the handler throws). |
projection.max-retries | 3 | Retry budget for the two retry-* strategies — attempts after the first. |
projection.retry-backoff | 1s | Delay before the first retry; doubles on each further attempt. |
projection.max-retry-backoff | 60s | Ceiling on that doubling delay. Must be at least retry-backoff — a projection whose merged settings say otherwise refuses to start. |
projection.poll-interval | 1s | How often a projection asks the journal for new events. |
projection.group-after-envelopes | 20 | Most events per handleGroup call (grouped handlers). Grouped projections only — a handle projection is delivered one event per call and ignores it. |
These are the process-wide defaults for every projection.
ProjectionOptions on a single projection outranks them, and they
outrank the built-in defaults — the usual three layers. A projection
that passes an empty liveOptions still gets poll-interval from
here; only a value actually set in code overrides it.
group-after-envelopes is checked only where it applies: a size the
validator refuses, such as 0, stops the grouped projections and
leaves a handle projection alone, which refuses only a
groupAfterEnvelopes set in its own code.
Top-level rather than under actor-ts.persistence, because that block
holds plugin ids and nothing else, so a tuning leaf inside it would
read as the name of a plugin.
actor-ts.backoff-supervisor
Section titled “actor-ts.backoff-supervisor”| Key | Default | Purpose |
|---|---|---|
backoff-supervisor.min-backoff | 200ms | Floor of the respawn delay, and the window after-min-stable measures a child’s stability against (backoff supervisor). |
backoff-supervisor.max-backoff | 10s | Ceiling the doubling delay clamps to. Must be at least min-backoff — a supervisor whose merged settings say otherwise refuses to start. |
backoff-supervisor.random-factor | 0.2 | Jitter fraction in [0, 1], so a herd of supervisors does not respawn in lockstep. Inert for a supervisor that supplies its own policy — that policy computes the whole delay. |
backoff-supervisor.max-stash-size | 1000 | Messages held per supervisor while its child is dead; the oldest becomes a dead letter when the buffer is full. |
backoff-supervisor.reset-counter | "after-min-stable" | When the consecutive-restart counter resets — never, after-min-stable, or a duration naming the stable window explicitly. |
backoff-supervisor.forward | "stash" | What happens to messages arriving during a backoff window — stash buffers them for the next child, drop discards them. |
backoff-supervisor.trigger-on | "any" | Which terminations respawn the child — any, failure (crashes only) or stop (clean stops only). |
backoff-supervisor.drain-grace | "auto" | How long a respawned child has to survive before the stash drains into it, so a child that crashes in preStart does not take the stash with it. auto is one fixed wait of min(50ms, min-backoff), resolved per supervisor against its merged min-backoff; a duration fixes it, and 0 drains at once. |
backoff-supervisor.forward-during-grace | true | Whether messages arriving inside that grace go straight to the respawned child (true) or wait in the stash until it has survived the grace (false) — up to one grace of latency after each respawn, in exchange for nothing dead-lettered while a child keeps crashing in preStart. |
These are the fleet-wide defaults for every BackoffSupervisor in the
process. The options passed to one supervisor outrank them, and they
outrank the built-in defaults — the usual three layers, per field. A
supervisor built as BackoffSupervisor.factory({ child: Flaky }) takes the
whole block; one that names minBackoff in code takes the rest of it.
The merge happens in the supervisor’s preStart, which is the first point
where system.config is reachable — so a value a config file puts out of
range fails the supervisor’s start rather than the call that built it. The
rule is the same one that rejects the value written in code.
child-name is deliberately absent: a child’s name is per-call-site
identity, where one fleet-wide value would be actively wrong. It is still
settable in code.
actor-ts.cache
Section titled “actor-ts.cache”| Key | Default | Purpose |
|---|---|---|
cache.in-memory.max-entries | 10000 | Max entries before LRU eviction (in-memory cache). |
cache.in-memory.cleanup-interval | 60s | Interval of the background sweep for expired entries; 0 disables it. |
cache.in-memory.prefix-quotas | (unset) | Per-prefix caps that split one instance between its consumers; must sum to at most max-entries. |
cache.in-memory.time-to-live | 0 | Lifetime stamped on a set / mset that names no ttlMs. 0 = no expiry, which is the historical behaviour. |
cache.in-memory.time-to-idle | 0 | A read pushes such an entry’s expiry out again, never past its time-to-live. 0 = a read extends nothing. |
cache.<name>.in-memory.* | (the block above) | The same leaves, for the single instance cache('<name>') resolves — overrides the global block leaf by leaf, and rejects a retired spelling the same way. |
cache.<name>.plugin | "...in-memory" | Which backend cache('<name>') resolves to. |
cache.redis.url | "" | redis://host:port (or rediss://). Mutually exclusive with host / port. "" = unset. |
cache.redis.host / .port | (unset) | Deliberately comments in reference.conf — see below. Unset, ioredis uses its own 127.0.0.1:6379. |
cache.redis.db | 0 | Logical database. Ignored when url is set; put it in the URL path instead. |
cache.redis.key-prefix | "" | Prepended to every key — isolates systems or environments sharing one server. |
cache.redis.password | "" | AUTH password. Prefer a substitution: password = ${?REDIS_PASSWORD}. |
cache.memcached.servers | "localhost:11211" | Comma-separated host:port list — a string, not a list, because that is what memjs takes. |
cache.memcached.username / .password | "" | SASL credentials. Prefer ${?MEMCACHED_PASSWORD}. |
cache.memcached.key-prefix | "" | Applied server-side to every operation. |
cache.<name>.redis.* / cache.<name>.memcached.* | (the blocks above) | The same leaves for one instance, so cache('rate-limit') and cache('idempotency') can hold different databases on one server. |
Redis and Memcached caches read their connection settings from
actor-ts.cache.redis / actor-ts.cache.memcached, and the framework
registers both factories itself — so
actor-ts.cache.sessions.plugin = "actor-ts.cache.redis" is all a cache
needs to come up on Redis, with no registerCache call in your code.
Both drivers are lazy optional peers, so a block nobody resolves costs
nothing: ioredis and memjs are imported on the first cache
operation, not at startup.
An empty string means unset everywhere in those two blocks. The ""
values above are the shape of the key, published so you can see the name
and the nesting; the reader drops them rather than handing them on. That
is also why host and port are comments rather than leaves: url is
mutually exclusive with them, and a shipped host = "localhost" would be
set for every deployment and would make every url an OptionsError.
Write both on purpose and you still get that error, which is the point.
These <name> paths take the name your code asks cache(name) for,
so they cannot be enumerated in reference.conf. Sizing one consumer
for its own key space is what the one cache per
consumer advice needs.
actor-ts.sharding
Section titled “actor-ts.sharding”| Key | Default | Purpose |
|---|---|---|
sharding.number-of-shards | 64 | How many shards the entity space is divided into. Every node that starts or proxies a type must agree on it — the coordinator refuses a region that does not, see numShards is a cluster-wide agreement. |
sharding.role | "" | Only members carrying this role host shards. "" = unrestricted. It names a role, it does not grant one — see a role names, it does not grant below. |
sharding.rebalance-interval | 2s | Gap between coordinator-driven rebalance passes. |
sharding.hand-off-timeout | 10s | How long to wait for HandOffComplete before force-reallocating. |
sharding.persist-coordinator-state | off | Keep each coordinator’s allocation map in the persistence journal, so a new leader starts from the map the previous one last wrote. The journal must be shared by the cluster; a node-local one on a node expecting remote peers is refused (#1188). |
sharding.coordinator-state-load-timeout | 10s | How long a new leader waits for that map to load before it places shards without it. |
sharding.rebalance-absolute-limit | 0 | Flat ceiling on shards a rebalance may have in flight. 0 = no absolute ceiling. See bounding rebalance churn below. |
sharding.rebalance-relative-limit | 0.1 | The same ceiling as a fraction of number-of-shards, so it scales with the entity space — 0.1 of the shipped 64 is 6. 0 = no relative ceiling; 0 for both leaves the rebalance uncapped. Where both are set the lower wins, and a ceiling never floors below one shard. |
sharding.acquire-retry-interval | 5s | How long the coordinator waits before re-acquiring a lease it failed to take. Observable only where the coordinator has a lease — passed in code, or built by use-lease. |
sharding.use-lease | off | Give every sharded type’s coordinator a lease built from actor-ts.coordination.lease, so only the holder allocates shards under a partition. Refused when the type starts while coordination.lease.backend = none; a withLease(…) in code wins, and withUseLease(false) opts one type out. |
sharding.remember-entities | false | Persist the set of active entity IDs. |
sharding.passivation-idle | 5m | Auto-passivate an entity after this idle window. 0 = disabled. An entity that keeps state in memory and does not rebuild it in preStart loses that state — see passivation. |
sharding.shard-passivation-idle | (unset) | Auto-passivate a shard after it has stood empty this long. Unset it follows passivation-idle; 0 keeps empty shards resident. Deliberately absent from reference.conf, because a shipped value is what “unset” would have to be distinguishable from. |
sharding.max-entities | 0 | Entity cap per sharded type on this node; the entity the replacement policy names is passivated on overflow. 0 = no cap. Two started types each get the whole cap — see choosing what a full node gives up below. |
sharding.passivation.replacement | least-recently-used | Which resident entity the cap gives up. Also segmented-least-recently-used and least-frequently-used. Inert while max-entities = 0. |
sharding.passivation.segmented-protected-proportion | 0.8 | Share of the cap held by the protected segment under segmented-least-recently-used; the rest is probation. Ignored under every other policy. |
sharding.passivation.admission-window-proportion | 0.0 | Share of the cap held as a probationary window in front of the policy. 0 = no window. Required by admission-filter. |
sharding.passivation.admission-filter | off | frequency-sketch makes a candidate leaving the window out-rank the entity it would displace. Rejected at sharding.start(...) unless admission-window-proportion > 0. |
sharding.passivation.stop-timeout | 0ms | How long an entity may take to act on the stop-message a Passivate handed it before the shard stops it outright. 0 waits forever, which is the shipped behaviour. |
sharding.buffer-size | 100000 | How many messages one region may hold across all its shards while their homes are unknown or handing off, or while their shard backs off after a failure (shard-failure-backoff below). The same cap bounds, per shard, what a shard holds for its entities backing off after a stop nobody asked for (entity-restart-backoff below). Past the cap the newest message is dropped to dead letters with its sender, so what is already queued keeps the order the caller sent it in. Mind the polarity against max-entities above: here 0 means never buffer — dead-letter immediately, not “no cap”. |
sharding.register-retry-interval | 500ms | How often a region re-sends an unacknowledged registration to the coordinator. Everything routed for the type buffers until the coordinator answers, so this is also how long a lost Register stalls it. |
sharding.shard-region-query-timeout | 5s | Default wait for sharding.shards() and sharding.shardRefFor(). An explicit timeoutMs argument still wins over it. Not how long the region remembers a caller it has not answered yet — a query like these, or a cross-node ask — which is a minute, or actor.ask-timeout or this key where either is longer. Raising this key never cuts a query’s answer off; lowering it never cuts off an ask’s. |
sharding.entity-recovery.strategy | all | How remembered entities come back after a region is handed a shard. all starts every one at once — today’s behaviour, and the reason the default did not move. constant-rate paces them, see pacing a remembered-entity restore below. |
sharding.entity-recovery.constant-rate.frequency | 100ms | Gap between two paced recovery batches. Ignored under strategy = all. |
sharding.entity-recovery.constant-rate.number-of-entities | 5 | Entities one paced batch starts. A region-wide budget, not a per-shard one — the queue is fed by every shard the region owns, so this is entity starts per window per sharded type on this node; two paced types each get the whole budget. Ignored under strategy = all. |
sharding.stale-region-detection.enabled | off | Make each region beat to the coordinator and let the coordinator evict one that goes silent. Off by default — eviction is destructive. See detecting a region that went silent below. |
sharding.stale-region-detection.heartbeat-interval | 5s | Gap between two region → coordinator beats. Per sharded type, not per node. Inert while enabled = off. |
sharding.stale-region-detection.stale-after | 20s | Silence after which a region is declared gone and its shards re-homed. Must be greater than heartbeat-interval, and by more than one beat. Inert while enabled = off. |
sharding.shard-failure-backoff.min | 200ms | First wait before a shard that stopped unexpectedly — outside a hand-off, a passivation or a release — is re-created; each death in a row doubles it, up to max. The region keeps the shard meanwhile and buffers its messages. Must be greater than 0. See when shards and entities keep failing. |
sharding.shard-failure-backoff.max | 10s | The ceiling the doubling wait stops at. Must not be below min. |
sharding.shard-failure-backoff.random-factor | 0.2 | Each wait is spread by up to this fraction either way, so shards that died together do not come back in step. In 0..1; 0 makes every wait exact. |
sharding.shard-failure-backoff.reset-after | 60s | A shard that went this long without failing, counted from when it came back, starts again at min when it next dies. A passivation in between is not a failure. |
sharding.entity-restart-backoff.min | 200ms | First wait before a shard re-creates an entity that stopped without being passivated — past its restart budget, after a recovery failure it swallowed, a lost lease or a plain stopSelf; each such stop in a row doubles it, up to max. The shard holds the entity’s messages meanwhile, against buffer-size per shard, and the restarts inside the budget are not delayed. Must be greater than 0. See an entity that keeps stopping. |
sharding.entity-restart-backoff.max | 10s | The ceiling the doubling wait stops at. Must not be below min. |
sharding.entity-restart-backoff.random-factor | 0.2 | Each wait is spread by up to this fraction either way, so entities that stopped together do not come back in step. In 0..1; 0 makes every wait exact. |
sharding.entity-restart-backoff.reset-after | 60s | An entity that went this long without stopping unasked, counted from when it came back, starts again at min when it next stops. A passivation in between is not a failure. |
sharding.healthcheck.names | [] | Sharded types this node is not ready without. Cluster.join installs one readiness check per name, shard-region:<name>, which fails until this node’s region for the type is registered with the coordinator — never started or stopped, refused over number-of-shards, or not acknowledged yet. Read once per join, not per sharding.start(...); [] gates on nothing. See the built-in checks. |
These apply to every sharded type started on the node, healthcheck.names
aside. They are read once per sharding.start(...) and layered under whatever
that call passes explicitly, so the usual order holds per field:
// actor-ts.sharding.passivation-idle = 2 minutes
const shardingOptions = StartShardingOptions.create<CartCommand>() .withTypeName('cart') .withEntityActor(CartEntity) .withExtractEntityId((command) => command.entityId) .withNumShards(256);
cluster.sharding.start(shardingOptions);// numShards 256 (explicit), passivationIdleMs 120_000 (config file)A role names, it does not grant
Section titled “A role names, it does not grant”sharding.role says which role hosts a type. It does not give the
node that role. A node’s own roles are a separate setting, assigned in code
or through actor-ts.cluster.roles:
// On every node that should host the shards:const clusterOptions = ClusterOptions.create() .withHost('10.0.0.7') .withPort(2551) .withRoles(['backend']);# In the config file every node shares:actor-ts.sharding.role = "backend"Set only the first half and nothing changes; set only the second and no
shard is ever allocated — the coordinator finds no candidate member, every
message for the type accumulates in the region’s routing buffer, and the only
sign of it is one warning naming the role and the number of regions it
excluded. A role that no member carries is the same silent failure a typo
in withRole produces, except that from a shared config file it applies to
every sharded type on every node at once.
That asymmetry is also why the key exists: which role hosts a type is uniform across a deployment, and which roles a node carries is not.
A configured role reaches sharded daemon
processes too, because they are
started through the same sharding.start(...). That is intended — a
deployment that places its entities on backend nodes usually means its
daemons as well — and ShardedDaemonProcessOptions.withRole(...) still wins
over it per process.
proxy deliberately has no leaf. It is per-node topology, not a
deployment-wide fact: a second start disagreeing about it throws, and a
proxy = on everyone shared would leave nothing hosting anything.
Pacing a remembered-entity restore
Section titled “Pacing a remembered-entity restore”Under remember-entities a region that
is handed a shard is shipped that shard’s whole registry and, by default,
spawns every entity in it at once — for every shard it is given. A node
restart or a rebalance therefore opens one journal replay per remembered
entity, all in the same tick. constant-rate spreads those starts:
actor-ts.sharding.entity-recovery { strategy = constant-rate constant-rate.frequency = 100ms constant-rate.number-of-entities = 5}Two things about that budget are worth stating plainly, because both are easy to read the other way:
- It is region-wide, per sharded type. Five entities per 100 ms is five
for this sharded type on this node, no matter how many shards the node
holds — the scope
max-entitieshas. Each started type runs its own region and its own queue, so a node recovering two paced types starts up to ten per window. Read per shard the same numbers would mean 5 × the shard count, which on a 64-shard cluster is not a bound at all — the same conflationmax-entitiesis kept region-wide to avoid. - It paces starts, not replays. A replay is asynchronous, so one that
outlasts the window still overlaps the next batch. What this key smooths is
the arrival rate; how many recoveries may be in flight is
persistence.max-concurrent-recoveries, one layer down — the two compose.
Nothing is shed: the backlog drains until every remembered entity is back, and
a message routed to an entity still in the queue creates it immediately — only
the recovery burst waits. The default stays all because pacing changes when
an entity comes back, and how fast a journal can take the replays is a fact
about that journal rather than about sharding.
Bounding rebalance churn
Section titled “Bounding rebalance churn”The default allocation
strategy places a shard by
shardId % candidates.length, so a node joining changes the answer for most
shards at once. At the shipped number-of-shards = 64 that is 32 shards on a
1 → 2 node join, 42 on a 2 → 3 join and 46 on a 3 → 4 — each one a shard
stopped, every entity under it stopped, then re-allocated, re-created and, if
it persists, replayed. Nothing announces it either: the coordinator does not
react to a MemberUp, and it rebalances only once the set of up members has
held still for its settle window — failure-detector.down-after, or the larger
of that and split-brain-resolver.stable-after with a split-brain strategy —
so the whole burst arrives on the first periodic tick after that window (see
members that are not up).
The two limits bound how many of those may be in flight at once:
actor-ts.sharding { rebalance-absolute-limit = 0 # 0 = no absolute ceiling rebalance-relative-limit = 0.1 # fraction of number-of-shards}Three things about that bound are worth stating plainly:
- It counts shards in flight, not shards per tick. A tick fires every
rebalance-intervalwhile a hand-off may stand for a wholehand-off-timeout, so a per-tick six would admit roughly thirty at once. What the coordinator budgets each tick is the ceiling minus what is already moving. - Only voluntary moves are capped. A region that dies leaves its shards with no owner at all; those are re-homed immediately, ceiling or not. Throttling that path would leave shards unreachable rather than merely slow to settle.
- Nothing is dropped, and no node is drained first. What the budget leaves behind is proposed again on the next tick until the map is balanced, and the shards that go first are picked round-robin across their current owners — a ceiling that empties one node before touching the next is worse than no ceiling.
Set rebalance-relative-limit = 0 (with the absolute limit already 0) to
restore the unbounded behaviour.
Detecting a region that went silent
Section titled “Detecting a region that went silent”Read the scope before reaching for this: it is a backstop for one narrow case, and the case most people mean is already covered without it.
A node that stops gossiping is not this backstop’s case. By default — no
split-brain strategy, actor-ts.cluster.failure-detector.auto-down = on —
the failure detector removes it after
actor-ts.cluster.failure-detector.down-after (5 s); with a split-brain
strategy, at that strategy’s verdict, no sooner than
split-brain-resolver.stable-after (20 s by default). With
failure-detector.auto-down = off it is parked at unreachable, and its
shards stay homed there until an operator downs it (Cluster.down) or a
strategy decides. Either way the
coordinator re-homes the node’s shards from the resulting MemberRemoved, and
the backstop below never does: it leaves a parked node’s regions to that
decision, because the node may still be running their shards. No new shard
is placed on a parked node in the meantime (see members that are not
up). A region stopped
cleanly tells the coordinator on its way down. What none of these covers is a
region that is gone or wedged on a node that is still up and gossiping,
where that notification never arrived: it is single-shot, unacknowledged, and
a transport failure on the way down is logged and swallowed. Then the shards
stay allocated to an actor that does not exist, and nothing self-heals — the
candidate set is derived from the registry and checks only that a region’s
node is up, never that the region itself is alive.
actor-ts.sharding.stale-region-detection { enabled = on heartbeat-interval = 5s stale-after = 20s}Five things worth knowing before turning it on:
- The switch drives both halves. Off, no region beats and no coordinator
sweeps, so the mechanism costs nothing at all. On, every region of every
sharded type sends one small frame per
heartbeat-interval. - An evicted region that is still alive is told, and comes back. The
coordinator cannot tell a region that is gone from one whose beats were lost,
so an eviction is a decision it can get wrong — and a region that is still
alive would otherwise learn nothing, keep its shards and keep serving their
entities, leaving one shard with two live homes for as long as the node
stayed up. It is therefore sent a notice: one that is really gone or wedged
never processes it, and one that was merely silent gives up every shard it
holds — the entities stop, so a persistent one flushes — and registers again
at once. That region has then beaten to the coordinator zero times, so it is
not a sweep candidate again until a beat of its own arrives, which is what
stops a permanently muted region cycling every
stale-after. - The beat is per sharded type, not per node. Ten types on a node is ten frames per interval, on top of the cluster’s own heartbeats.
- A region that never beats is never swept. That is what makes turning the key on safe mid-deployment: for as long as the leader runs with it on and some regions do not, those regions are simply not armed yet, rather than evicted on a timer and re-registering in a loop.
stale-aftermust exceedheartbeat-interval, and the shipped four intervals is deliberate: at one, a single dropped frame evicts a healthy region and stops every entity under every shard it held. A pair that crosses is rejected atsharding.start(...), against the resolved values, so overriding one cannot silently cross the other’s default.
There is deliberately no check-interval. The sweep rides the
rebalance-interval tick, which is already the dial for how often the
coordinator looks at the shard map, so the detection latency is stale-after
plus at most one tick.
Choosing what a full node gives up
Section titled “Choosing what a full node gives up”max-entities says how many entities a node keeps; the passivation block
says which one leaves when a new one arrives. Every key in it is inert
while max-entities = 0, which is the shipped default, so a deployment that
sets no cap is unaffected by all of it.
Read the cap’s scope before tuning any of this: it is per sharded type on
this node, not node-wide and not per shard. A node running a cart type and
a session type with max-entities = 50000 holds up to a hundred thousand
entities, fifty thousand of each. Per shard the bound would divide across a
set that changes on every rebalance; node-wide it would need a budget shared
between regions that know nothing about each other.
The default, least-recently-used, has one blind spot, and it is the reason
the block exists. Recency cannot tell touched once, ever from touched
constantly until a moment ago, so a pass over a large cold key space — a
nightly export, a crawler, a backfill — evicts the working set one entity at a
time and leaves the cache full of ids nothing will ask for again:
actor-ts.sharding { max-entities = 50000 passivation { replacement = segmented-least-recently-used segmented-protected-proportion = 0.8 admission-window-proportion = 0.01 admission-filter = frequency-sketch }}segmented-least-recently-usedsplits the cap in two. An entity that has been used once sits on probation; using it again moves it to the protected segment, and eviction takes from probation first. A scan entity is never touched twice, so it can only ever displace another scan entity.admission-window-proportionreserves a small slice of the cap for brand-new arrivals. It is what makes a filter possible at all: a region cannot refuse the entity a message has just arrived for — it is being created to receive that message — so the candidate judged against the incumbent is whatever falls out of the window’s far end instead.admission-filter = frequency-sketchis that judgement. A compact count-min sketch of how often each id has been seen decides which of the two stays, and it remembers ids the node no longer holds — which is exactly the history needed to recognise an entity that used to be hot. It is rejected without a window rather than silently doing nothing.
least-frequently-used is the third policy: fewest accesses loses, with every
count halved periodically so the ranking follows recent traffic rather than a
lifetime total. It suits a working set that is stable but not recent — a fleet
of devices reporting on a slow cycle — where recency says almost nothing.
stop-timeout is unrelated to the choice above, and unrelated to max-entities
too: a positive value arms it with or without a cap. When an entity passivates
itself with Passivate, the
stop-message is a request: the entity decides when to act on it. If it never
does, the entity never terminates and its slot is held against max-entities
for the lifetime of the node. After stop-timeout the shard stops it outright.
It ships off (0, the unbounded wait), so nothing changes for a deployment
that does not name it. That is deliberate rather than cautious: an entity
mid-drain — a long flush, a slow final write — is entitled to take as long as
the drain takes, and a forced stop there abandons the flush. The operator who
knows how long the drain can legitimately run is the one who can pick the bound,
so it is opt-in.
A per-type setting therefore belongs in the builder; the config file is for the node-wide baseline you want to move between staging and production without a rebuild. The polymorphic options — the entity actor, the extractors, the allocation strategy, a lease, the stores — have no HOCON form and stay in code.
actor-ts.coordinated-startup
Section titled “actor-ts.coordinated-startup”| Key | Default | Purpose |
|---|---|---|
coordinated-startup.default-phase-timeout | 30s | Budget of every startup phase that names none of its own. A task that outlives it fails the startup, so it is what bounds an open that never answers. |
coordinated-startup.phases.<name>.timeout | — | Per-phase budget, overriding default-phase-timeout for that phase alone. |
coordinated-startup.phases.<name>.recover | — | true makes a failing task in that phase a WARN the startup steps over, instead of a failed startup. |
coordinated-startup.phases.<name>.depends-on | — | Phases that must run first. Added to a seeded phase’s existing edge; required when the name declares a new phase. |
The block tunes the startup graph
the system runs as the last step of create: how long each phase may take,
and whether it recovers. The tasks are code, passed through
withCoordinatedStartup. Like the shutdown block below, phases ships no
values of its own:
actor-ts.coordinated-startup { default-phase-timeout = 45s phases { persistence-start { timeout = 2m } # a database that is slow to accept a pool warm-caches { # …and a phase a task passed in code runs in timeout = 10s recover = true depends-on = ["persistence-start"] } }}A child naming persistence-start or before-system-ready merges into it:
fields it leaves out keep what the phase was seeded with. Any other name
declares a phase, which a task passed in code may then name, and there
depends-on is required — a phase with no edges would run before
persistence-start. depends-on names a seeded phase or another child of the
block, and on a seeded phase it is added to the edge it already has, so a
config file cannot run before-system-ready ahead of persistence-start. A
declared phase does not recover unless it says so, like the two seeded ones.
An unknown setting under a phase, a declared phase without depends-on, a name
that resolves to no phase, a cycle or a zero budget is a ConfigError at
ActorSystem.create.
Code wins, setting by setting: withDefaultPhaseTimeoutMs over
default-phase-timeout, and a phase withPhases names is that entry’s as a
whole — the block’s child for it is not applied, while the children for the
other phases still are.
actor-ts.coordinated-shutdown
Section titled “actor-ts.coordinated-shutdown”| Key | Default | Purpose |
|---|---|---|
coordinated-shutdown.default-phase-timeout | 5s | Default per-phase timeout. A phase that overruns it is abandoned so the next one still runs. |
coordinated-shutdown.terminate-actor-system | true | Whether the built-in terminator task tears the actor system down in the final phase. |
coordinated-shutdown.exit-process | false | Whether to call process.exit(exit-code) once a run ends. A run that a phase with recover = false halts exits at the halt, in place of the teardown it would otherwise get, and with 1 where exit-code is 0. |
coordinated-shutdown.exit-code | 0 | Status that exit carries. 0–255; anything else is a ConfigError at startup. A run for a failed startup, a run for a node that could not join (ClusterJoinUnsuccessfulReason: the join give-up, a failed Cluster.bootstrap readiness wait or refusal), and a run that a phase with recover = false halts, exit 1 where this is 0, so none of them reads as a clean stop. |
coordinated-shutdown.auto-register-tasks | true | Whether framework components register their own teardown — the HTTP unbind, broker closes, the cluster leave, the DevTools detach. |
coordinated-shutdown.run-by-process-signals | true | Whether runUntilTerminated() and the cluster bootstrap arm SIGTERM/SIGINT when the caller named no signals. |
coordinated-shutdown.run-by-actor-system-terminate | false | Whether a system.terminate() that names no runCoordinatedShutdown runs the pipeline first, with ActorSystemTerminateReason. false keeps it the bare teardown; a call that chooses gets what it chose, either way. |
coordinated-shutdown.phases.<name>.timeout | — | Per-phase budget, overriding default-phase-timeout for that phase alone. |
coordinated-shutdown.phases.<name>.recover | — | false makes a failing task in that phase halt the pipeline instead of being logged and stepped over. |
coordinated-shutdown.phases.<name>.depends-on | — | Phases that must run first. Added to a canonical phase’s existing edge; required when the name declares a new phase. |
Setting terminate-actor-system = false removes only the built-in
terminator — user tasks registered in ActorSystemTerminate still run. Use
it when a host process owns the system’s lifetime and a signal handler must
not kill it.
The phases block is the config front-end to the phase DAG, and it ships no
values of its own — its children are named after your phases, so there is
nothing to publish a default for:
actor-ts.coordinated-shutdown.phases { service-requests-done { timeout = 30s } # retime one canonical phase flush-metrics { # …and add one of your own timeout = 3s recover = false depends-on = ["before-actor-system-terminate"] } actor-system-terminate { depends-on = ["flush-metrics"] }}A child naming one of the twelve canonical phases merges into it: fields
it leaves out keep what the phase was seeded with. Any other name declares
a phase, and there depends-on is required — a phase with no edges sorts into
the first ready batch and would run before before-service-unbind, which is
never what adding a phase meant. depends-on on a canonical phase is added
to the edge it already has rather than replacing it, so a config file cannot
re-parent cluster-leave ahead of service-unbind; the topological sort
catches cycles, not a pipeline quietly running in the wrong order. Declaration
order in the file does not matter — two phases may name each other and are
registered dependency-first. An unresolvable name, a cycle, or an unknown
setting under a phase is a ConfigError at startup, not at shutdown.
run-by-process-signals switches the default, not the capability. Naming
signals explicitly — runUntilTerminated(['SIGTERM']), or shutdownOnSignals
in the bootstrap options — still installs them, because explicit options
outrank config. Turning it off is for a host process that owns SIGTERM
itself: runUntilTerminated() still waits and still holds the event loop open,
it simply arms nothing.
exit-process is for the opposite case: a lingering handle (an open socket,
a pooled connection a driver never released) keeps the process alive after
the pipeline is done, and from the outside that is indistinguishable from a
hang. Off by default, because forcing an exit hides exactly the leaks you
would rather find. exit-code is the status it hands over — 0, because a
pipeline that ran to the end is the success case; set it where a supervisor
should tell a planned drain apart from a crash. A run that halts — a phase
with recover = false whose task failed — exits too, and never with 0:
with exit-code where that is not 0 and with 1 where it is, as a run for
a failed startup does. It exits at the halt, so the teardown the halt would
otherwise get — the one a signal’s run or an opted-in terminate() performs —
never starts; the halt is logged at error, naming the phase, just before.
What that teardown would have flushed is flushed before the exit instead —
the dead-letter queue’s writes, then the log sinks, each within
logger.close-timeout — so that line reaches a buffering sink too; the same
goes for a completed run with terminate-actor-system = false.
actor-ts.sharded-daemon-process
Section titled “actor-ts.sharded-daemon-process”| Key | Default | Purpose |
|---|---|---|
sharded-daemon-process.liveness-interval | 30s | Period of the safety-net ping that re-wakes every daemon index whether or not a cluster event fired. 0 disables it; the event-driven re-wake on LeaderChanged / MemberRemoved runs either way. See the liveness heartbeat. |
sharded-daemon-process.role | "" | Only members carrying this role host daemons. "" is not “unrestricted” here — see an unset daemon role inherits the sharding one below. Like sharding.role it names a role and does not grant one. |
A daemon set is a module built on sharding rather than a sharding
tunable, which is why these live in their own block: actor-ts.sharding.*
configures every sharded type on the node, these two only the daemons. They
are read once per ShardedDaemonProcess.init(...) and layered under whatever
that call passes explicitly, the usual order per field:
// actor-ts.sharded-daemon-process.liveness-interval = 10s
const daemonOptions = ShardedDaemonProcessOptions.create<Tick>() .withName('reconciler') .withNumDaemons(8) .withActorFor((index) => () => new Reconciler(index));
ShardedDaemonProcess.init(system, cluster, daemonOptions);// livenessIntervalMs 10_000 (config file) — nothing explicit overrides itname, numDaemons and the per-index actor have no leaf. They describe one
daemon set rather than a deployment, and a factory has no HOCON form at all.
An unset daemon role inherits the sharding one
Section titled “An unset daemon role inherits the sharding one”sharded-daemon-process.role left at "" means no daemon-specific
opinion, not unrestricted. The daemon set is started as an ordinary
sharded type, so with nothing set here it picks up
actor-ts.sharding.role exactly like every other type:
actor-ts.sharding.role = "backend" # every sharded type# sharded-daemon-process.role left at "" # daemons follow alongNaming a role here narrows only the daemons, and leaves the rest of the sharded types to the global key:
actor-ts.sharding.role = "backend" # entities on the backend nodesactor-ts.sharded-daemon-process.role = "batch" # daemons on the batch nodesThe same caveat as sharding.role applies, and it bites harder here because
nothing sends a daemon a first message: a role that no up member carries
allocates nothing, so the daemons simply never start. The coordinator logs
one line naming the role when a region did register and the role filtered it
out.
actor-ts.devtools
Section titled “actor-ts.devtools”| Key | Default | Purpose |
|---|---|---|
devtools.host | "127.0.0.1" | Interface attach binds. Anything routable is refused unless something gates it — see below. |
devtools.port | 9333 | Port to bind; 0 lets the operating system pick one, and the returned binding reports which. |
devtools.allow-remote | false | Acknowledge an ungated bind on a routable interface. |
devtools.serve-ui | true | false leaves the tap without the bundled UI. |
devtools.allowed-origins | [] | Extra origins allowed to open the tap’s WebSocket. Same-origin is always accepted; this only widens it. |
devtools.panels.actors | true | Actor tree, mailbox depths and cell states. |
devtools.panels.cluster | true | Cluster topology, shard maps, membership timeline. |
devtools.panels.tracing | true | Span flame graph and waterfall — its Payload column carries every actor message that passed while DevTools was attached, serialised. |
devtools.panels.explain | true | Per-actor explain plan. |
devtools.panels.time-travel | true | Journal browsing and state reconstruction — the panel that shows raw persisted events. |
devtools.panels.profiler | true | Actor profiler. |
devtools.panels.dead-letters | true | Undelivered messages, payloads included. |
devtools.panels.event-stream | true | Live tail of the event bus and the cluster PubSub topics, payloads included. |
devtools.panels.config | true | Resolved configuration with the source of each key (values whose key names a secret are redacted). |
devtools.panels.send | true | The send-message view. The capability behind it is a separate, code-only switch. |
devtools.mailbox-sample-interval | 1s | How often the actor tree, mailbox depths and cell states are resampled. |
devtools.mailbox-sample-limit | 50 | How many mailboxes one sample carries. |
devtools.stats-interval | 1s | How often the dashboard figures are sampled. |
devtools.span-buffer-capacity | 10000 | Ceiling on retained spans, in messages. |
devtools.span-flush-interval | 250ms | How often buffered spans are flushed to the panel. |
devtools.capture-payloads | true | false leaves the tracing panel running — spans, timings, flame graph — and empties only its Payload column, where panels.tracing = false takes the whole panel. A capture the application set for itself is untouched either way. |
devtools.event-buffer-capacity | 500 | Events the bus tail buffers between flushes; past it the oldest are dropped and the panel is told how many. |
devtools.event-flush-interval | 250ms | How often buffered events are flushed to the panel. |
devtools.replay-auto-capture | true | Borrow a fold from a running PersistentActor to reconstruct state. |
This block does not start DevTools. Nothing in ActorSystem constructs
the extension — DevTools.attach(system) is always a code call — so these
keys change how an attachment behaves, never whether one happens. There
is deliberately no enabled key: reading one would mean importing the
DevTools subsystem, embedded UI bundle and all, into every system that never
opens it.
A configured host faces the same rule a code-set one does. Options are
validated once, on the merged settings, so devtools.host = "0.0.0.0" throws
an OptionsError naming host exactly as .withHost('0.0.0.0') in code
does. auth and ipAllowlist are middleware and have no HOCON form, which
is what makes allow-remote the only answer a file can give to that rule.
Seven fields have no key. auth, ipAllowlist, backend, cluster and
replayFolds are functions and live objects HOCON cannot express, and
uiDevelopmentRoot is a panel-development escape hatch whose own
documentation says never to set it in an application. The last two are a
decision rather than an impossibility: allow-ungated-mount states a fact
about the code that binds mount()’s routes rather than about a deployment,
and allow-message-sending is the one DevTools capability that writes into
the running system from a browser. Both stay beside the call they qualify.
A panels object passed in code overrides the configured switches one
switch at a time, not wholesale: .withPanels({ timeTravel: false }) on top
of a file that says panels { send = false } leaves send off. That is the
usual precedence applied one level deeper — otherwise naming one panel in code
would switch every panel an operator disabled back on.
actor-ts.offload-pool (pure functions on worker threads)
Section titled “actor-ts.offload-pool (pure functions on worker threads)”| Key | Default | Purpose |
|---|---|---|
offload-pool.size | "auto" | Workers at most — "auto" is the available parallelism minus the main thread. Spawned as tasks need them. |
offload-pool.min-size | 0 | Workers kept alive through idleness. |
offload-pool.max-queue | 10000 | Tasks waiting for a worker before overflow decides what happens to the next one. |
offload-pool.overflow | "reject" | reject fails the run with OffloadQueueFullError; wait keeps it pending until a slot frees. |
offload-pool.idle-timeout | 60s | A worker beyond min-size with nothing to do is retired after this. |
offload-pool.task-timeout | 0s | 0 = no deadline unless run() names one. A deadline terminates the worker. |
offload-pool.max-restarts | 10 | Worker terminations — crash or deadline — the pool replaces inside restart-window; -1 = forever. Past the budget every run fails. |
offload-pool.restart-window | 60s | The window the restart budget counts over. |
offload-pool.warm-up | off | Spawn every worker at start instead of on the first task that needs it. |
The task — a named export of a module — and the worker bootstrap are code,
never keys, for the reason worker-cluster.bootstrap has none. See
Blocking and CPU-bound work.
actor-ts.parallelism (actors on worker threads from config alone)
Section titled “actor-ts.parallelism (actors on worker threads from config alone)”| Key | Default | Purpose |
|---|---|---|
parallelism.workers | 0 | 0 is off — the single-threaded system, bit for bit. A number or "auto" (available parallelism minus the main thread) starts a worker mesh in the background and turns system.spawn into a placement decision. |
parallelism.offload | ["/user/*"] | Path patterns of the top-level actors that move to a worker. * is one segment, ** one or more. A pattern that could reach /system is refused. |
parallelism.placement | "consistent-hash" | Which worker an actor lands on: a hash of its name, or "round-robin". |
parallelism.leader | "main" | "worker" moves the cluster leader — and the shard coordinator — onto a worker by giving the workers a hostname that sorts before main. |
parallelism.spawn-timeout | 10s | How long a spawn waits for its worker’s acknowledgment before the ref fails. |
parallelism.buffer-size | 100000 | Messages held across every spawn still awaiting its worker; past it, dead letters. |
The actor module — the file exporting the classes a worker may spawn — is
code, never a key: by convention actors.js next to the entry module,
otherwise ParallelismOptions.withModule(...). The threads’ hostnames,
ports, roles and restart pacing are the worker-mesh.* and
worker-cluster.* keys below. See Parallelism.
actor-ts.worker-cluster (multi-runtime workers)
Section titled “actor-ts.worker-cluster (multi-runtime workers)”| Key | Default | Purpose |
|---|---|---|
worker-cluster.workers | "auto" | Number of workers — "auto" is the machine’s available parallelism (os.availableParallelism(), which respects a container’s CPU quota; navigator.hardwareConcurrency as the fallback). |
worker-cluster.system-name | "worker-cluster" | ActorSystem name each worker hosts. |
worker-cluster.hostname | "worker" | Host component of each worker’s NodeAddress. |
worker-cluster.base-port | 1 | Port of the first worker; each subsequent slot increments. |
worker-cluster.ready-timeout | 10s | Per-worker hello/init/ready handshake deadline. |
worker-cluster.restart-policy | "on-failure" | always / on-failure / never. |
worker-cluster.restart-min-backoff | 200ms | Delay before the first respawn of a crashed slot. |
worker-cluster.restart-max-backoff | 10s | Ceiling for the respawn delay, which doubles per attempt. |
worker-cluster.restart-random-factor | 0.2 | ± jitter fraction on each respawn delay, in [0, 1]. |
worker-cluster.max-restarts | 10 | Restarts granted per slot inside the window before it is retired; -1 restarts forever. |
worker-cluster.restart-window | 60s | Sliding window the restart budget counts over; 0 never resets the tally. |
The four duration keys drop the Ms suffix their options-object fields carry
(ready-timeout sets readyTimeoutMs) and take a HOCON duration literal, the
same way logger.close-timeout feeds closeTimeoutMs. restart-random-factor
is a plain fraction, not a duration.
Four fields have no key on purpose: initData is per-call identity, backend
and onWorkerPermanentlyDown are live objects a config file cannot express,
and bootstrap names a module the runtime will execute — ACTOR_TS_CONFIG
and a dropped-in application.conf are a wider surface than the call site, so
it stays a code-only field.
actor-ts.worker-mesh (the main thread as a mesh member)
Section titled “actor-ts.worker-mesh (the main thread as a mesh member)”| Key | Default | Purpose |
|---|---|---|
worker-mesh.workers | "auto" | Worker count — "auto" is the available parallelism minus one, because the main thread is a working member; at least 1. |
worker-mesh.main-hostname | "main" | Host component of the main thread’s address. Sorts before the workers’ by default, so main leads and hosts the shard coordinator. |
worker-mesh.main-port | 1 | Port component of the main thread’s address — synthetic, nothing binds it. |
worker-mesh.worker-hostname | "worker" | Host component of every worker’s address. One that sorts before main-hostname moves the leader onto a worker. |
worker-mesh.base-port | 2 | Port of the first worker; each slot increments. |
worker-mesh.main-roles | [] | Cluster roles the main thread joins with. |
worker-mesh.worker-roles | [] | Cluster roles every worker joins with — what role-restricted singletons, shards and routers select on. |
worker-mesh.metrics-relay-interval | 10s | How often the main thread pulls every worker’s metrics registry into its own /metrics. While the relay runs, every series carries thread="main" or thread="worker-<slot>"; a worker’s figures are at most one interval old. 0 switches the relay off and exports the main thread alone — see the scope of a scrape. |
The mesh’s workers are a worker cluster, so the ready timeout and the restart
pacing are the worker-cluster.* keys above. The actor module (withModule)
and the bootstrap have no key, for the reason bootstrap has none.
Validation runs on the merged settings, so every one of these is rejected with
an OptionsError when it comes from a file exactly as it would from code: an
empty system-name or hostname, a base-port outside [1, 65535], a
restart-random-factor outside [0, 1], a negative backoff or window, a
max-restarts below -1, and a restart-max-backoff under
restart-min-backoff.
These fill in WorkerCluster.spawn(options) for fields it leaves unset.
spawn is a static with no ActorSystem in scope, so it loads the config
chain itself — the same one ActorSystem.create uses, honouring
ACTOR_TS_CONFIG and ./application.conf. An unknown restart-policy is
rejected with an OptionsError instead of silently meaning “never”.
Broker plugins — actor-ts.io.broker.*
Section titled “Broker plugins — actor-ts.io.broker.*”Each broker actor reads from its own subtree. See the per-protocol pages for each protocol’s own keys:
| Subtree | Page |
|---|---|
io.broker.kafka | Kafka |
io.broker.mqtt | MQTT |
io.broker.amqp | AMQP |
io.broker.nats | NATS |
io.broker.jetstream | NATS JetStream |
io.broker.jetstream-key-value | JetStream KV + Object Store |
io.broker.jetstream-object-store | JetStream KV + Object Store |
io.broker.redis-streams | Redis Streams |
io.broker.grpc.{client,server} | gRPC |
io.broker.websocket | WebSocket client |
io.broker.sse | SSE |
io.broker.tcp | TCP |
io.broker.tcp-server | TCP |
io.broker.udp | UDP |
io.broker.email-bridge | Email bridge |
Every one of these subtrees but grpc.server also takes the leaves
BrokerActor reads for all of them: reconnect (initial-delay,
max-delay, factor, max-attempts, random-factor), circuit-breaker
(a breaker id, whose numbers live under actor-ts.circuit-breaker.<id> — see
Circuit breaker) and
outbound-buffer. The gRPC server is a
plain actor, not a BrokerActor, and reads none of them, so a reconnect
block under it configures nothing. So
actor-ts.io.broker.kafka.outbound-buffer = 0 makes the
Kafka actor drop what it is sent while disconnected rather than buffer it.
They are described once, on
the BrokerActor base page, and
their old camelCase spellings are refused when the broker actor starts.
Not every field of those types has a key. An ActorRef (target,
bindings, subscriptions) names a live actor in this process, a codec or a
handler is a function, and TLS material is a private key — none of the three
has a config-file spelling, and each says so in its own JSDoc rather than
being silently absent.
HOCON-specific syntax
Section titled “HOCON-specific syntax”Durations
Section titled “Durations”gossip-interval = 1s # 1000 msunreachable-after = 2.5s # 2500 msdown-after = 5000ms # explicit msgc-cadence = 10m # minutesttl = 24h # hoursRecognized units, case-insensitive, with or without a space before them:
| Amount | Spellings |
|---|---|
| nanoseconds | ns nano nanos nanosecond nanoseconds |
| microseconds | us μs micro micros microsecond microseconds |
| milliseconds | ms milli millis millisecond milliseconds |
| seconds | s sec secs second seconds |
| minutes | m min mins minute minutes |
| hours | h hr hrs hour hours |
| days | d day days |
A bare number is milliseconds. A leading sign and a fraction are both
accepted — -500ms and 1.5s are valid. All three spellings of the micro
sign reach the same unit, so text copied from elsewhere parses: μs
(U+03BC, what the table is keyed on), µs (U+00B5, what a keyboard
produces) and Μs (U+039C).
Two things are refused at parse time rather than quietly becoming a number nobody can use:
- An unrecognized unit —
Unknown duration unit "..." in .... The lookup reads the unit table’s own keys only, the same way reads see own keys only guards the key path, soconstructoris refused like any other unknown unit instead of resolving through the prototype chain. - Anything that is not a finite number of milliseconds —
Invalid duration: .... That covers a literal long enough to overflow a double, and any spelling the pattern does not match, exponent notation (1e3) included.
max-frame-bytes = 16M # 16 777 216 bytes — binaryupload-limit = 16MB # 16 000 000 bytes — decimalbuffer = 64Kheap = 2GRecognized units, case-insensitive, with or without a space before them:
| Amount | Binary (1024) | Decimal (1000) |
|---|---|---|
| bytes | B byte bytes | — |
| kilo | K KiB kibibyte kibibytes | KB kilobyte kilobytes |
| mega | M MiB mebibyte mebibytes | MB megabyte megabytes |
| giga | G GiB gibibyte gibibytes | GB gigabyte gigabytes |
| tera | T TiB tebibyte tebibytes | TB terabyte terabytes |
| peta | P PiB pebibyte pebibytes | PB petabyte petabytes |
The single letter is binary, as HOCON specifies, and so is the iB form;
only the bare B suffix is decimal. The two diverge as they scale — 16MB
is 4.63 % smaller than 16M, and at T the decimal value is 9.05 % smaller
— so a cap written in the unintended one is a cap in the wrong place.
Unlike a duration, a size takes no sign — -1K is Invalid size — and
it has to come to a whole number of bytes. A fraction with a unit is fine
when it does, so 1.5K is 1536, and refused when it does not: 1.1K is
1126.4 bytes, and fails as
Invalid size: 1.1K is not a whole number of bytes. A bare number has to
be whole itself, whether it is written as a string or as a number: "1.5"
is Invalid size, and 1.5 is refused naming the key it is set at, as
Config at "..." is not a whole number of bytes (got 1.5).
The same two refusals apply, with the messages spelled for sizes:
Unknown size unit "..." in ... for a unit that is not in the table —
constructor included, for the reason above — and Invalid size: ... for
anything that does not come out a finite, whole byte count.
Environment substitution
Section titled “Environment substitution”port = ${?ACTOR_TS_PORT} # use env if set, else fall throughlog-level = ${?LOG_LEVEL} # sameapi-key = ${API_KEY} # required — error if env is unsetfallback-port = 2552 # the default …fallback-port = ${?ENV_PORT} # … replaced only when ENV_PORT is setUse ${?ENV} for optional, ${ENV} for required.
A variable that is set but empty counts as not set — PORT= in a shell,
environment: [PORT] in a compose file and an empty line of an env file all
mean “unset”. ${?PORT} then resolves to nothing and the default shows
through, and ${PORT} fails with an error saying the variable is set but
empty. To set a key to an empty string, write "" in the file.
There is no default-if-unset form. Everything between the braces is the
path, so ${ENV_PORT:-2552} is looked up as a key named ENV_PORT:-2552
and fails as an unresolved substitution, and ${?ENV_PORT:-2552} is
optional and silently resolves to nothing. Declare the default first and
the optional override after it, as the last two lines do: an optional
substitution that resolves to nothing leaves the earlier value in place,
and a later plain assignment replaces it as usual.
The same holds across layers. With the default in reference.conf or in a
file merged underneath, an unset ${?ENV} in application.conf removes the
key from that layer and the one below shows through, which is what the first
line above relies on. A key reference.conf carries only as a comment —
remote.tcp.host and port, the advertised-* pair,
discovery.config.seeds and others — has no layer below it, so an unset
${?ENV} leaves it unset and the reader’s own fallback applies.
A substitution may name a key whose value is itself a substitution. The
chain resolves whatever order its lines come in, and a key the file defines
wins over the environment at every link, so api.url = ${db.url} with
db.url = ${db.host} reads the file’s host even when a DB_URL variable is
set. A chain that leads back to where it started is refused as a
Substitution cycle: a -> b -> a, the optional form included. A key that
names itself — pod.ip = ${?pod.ip} — is no cycle: it reads the environment
and then the value it replaced.
Empty values
Section titled “Empty values”host = # nothing after it — no assignment, host keeps its valuehost = ${?DB_HOST} # DB_HOST unset or empty — host keeps its valuehost = ${DB_HOST} # DB_HOST unset or empty — the start failshost = "" # an explicitly empty stringroles = [] # an explicitly empty listAn assignment with nothing after its = or : is no assignment: the key
keeps what an earlier line of the same file gave it, and across files the
layer below shows through. That holds before a comma, before the closing
}, before a comment and at the end of the file. To set a key to empty,
write "" or [].
A value may still go on the line after its key, as JSON lays it out
("timeout": then 10s), as long as that line does not itself start a
field: a line that reads name = …, name: …, name { … or
include "…" is the next field, and the assignment above it has no value.
So an unquoted value that looks like a field — localhost:2552 — belongs
on the same line as its key.
Value concatenation
Section titled “Value concatenation”url = "redis://:"${REDIS_PASSWORD}"@cache:6379" # one stringaddress = ${HOST}":"${PORT} # "db:5432"name = app-${STAGE} # "app-prod"seeds = [ ${?SEED_HOST}":"${?SEED_PORT} ] # one elementQuoted strings, substitutions and unquoted text written next to each other
on one line make one string. The spaces between the pieces are kept, so
${A} ${B} is the two values with a space between them, and a field that
follows after a space still starts a new field (a = "x" b = 1). A single
piece keeps its type: port = ${PORT} is a number when PORT holds one.
Inside a string, a variable joins in as the text it holds. On its own,
${X} reads a variable as JSON first, so PORT=2552 gives a number and
FLAGS=[1,2] a list; inside a string that would turn a password of digits
into a number in exponent notation, so it does not. A key of the file joins
in as HOCON writes it — 30, true — and a key that holds an object or a
list cannot be joined into a string.
An unset ${?X} inside a string adds nothing. A string made of optional
substitutions only, none of them set, is no value at all, so the earlier
value or the layer below shows through — as for a single ${?X}.
${ inside quotes is text, not a substitution: "${X}" is the five
characters it shows. And because // starts a comment, a URL goes in
quotes — url = http://host is refused, where it used to read as http:.
Not supported, and refused with an error that says so: joining objects or
lists ({ a = 1 } { b = 2 }, [1] [2], ${base} { … }), +=, and
triple-quoted strings (#537).
Includes are not supported
Section titled “Includes are not supported”include "shared-cluster.conf" # error: `include` is not supportedA config source cannot name another file or URL to pull in. That is a decision, not a gap: resolving an include would let whoever writes the config choose which paths the process reads, relative to a root the parser has no way to know. Merging in code leaves that choice with the caller.
import { Config } from 'actor-ts';
const shared = Config.parseFile('shared-cluster.conf');const application = Config.parseFile('application.conf');const config = shared.merge(application);merge layers its argument on top, so the local file wins — the same
order the include above was reaching for. Pasting the shared content
into one file works too.
One caveat: substitutions are resolved when each file is parsed, not once
over the merged tree. A ${my.port} in shared-cluster.conf whose
my.port only application.conf defines fails at the first parseFile
with Unresolved substitution — where a real include would have
produced one document and resolved it. A value the base file refers to
has to live in the base file or in the environment. Shared defaults are
what the project reference.conf is for:
Config.load resolves it before application.conf, and
application.conf may refer to its keys.
The parser says all of this when it meets an include, quoting the line
and the target, so a config ported from Akka or Pekko fails with an
answer rather than a puzzle.
Reserved keys
Section titled “Reserved keys”Three keys are refused anywhere in a config source — as a key, as any segment of a path expression, and inside a substitution:
__proto__.anything = 1 # error: refusedconstructor.x = 1 # error: refusedprototype = 1 # error: refusedvalue = ${__proto__} # error: refusedA key path is expanded onto a plain object, and assigning __proto__ writes
through to the object prototype rather than creating a normal key — so allowing
it would let a config file change the behaviour of every object in the process.
The parser rejects these with the usual line and column instead.
The check is exact-match, so keys that merely resemble them are fine:
_proto_, constructorName and prototypes all work normally.
Reads see own keys only
Section titled “Reads see own keys only”Refusing three names guards the write side. The read side is guarded the
other way round — positively — because Object.prototype has a dozen more
members and a list could never keep up with them:
name = ${toString} # error: unresolved substitution — not a native functionport = ${?valueOf} # optional: falls through to the environment, then awayEvery lookup — a substitution, hasPath, and each typed getter — reads
own keys only, in the config tree and in the environment alike. A name
that happens to match an inherited member therefore misses instead of
resolving to whatever lives on the prototype, and hasPath('toString') is
false on any config that does not declare a toString key itself.
Declaring one is still allowed and still works: an own key shadows the
inherited member, so toString = "mine" reads back as "mine".
Reading config in code
Section titled “Reading config in code”const actorSystemOptions = ActorSystemOptions.create().withConfig({ 'actor-ts': { cluster: { 'gossip-interval': '500ms' } }, });const system = ActorSystem.create( 'my-app', actorSystemOptions,);
// Inside an actor / extension:const config = system.config;const interval = config.getDuration('actor-ts.cluster.gossip-interval');// → 500 (in ms)The object nests the way the HOCON blocks do. Its keys are taken
literally, so a dotted key such as 'actor-ts.cluster.gossip-interval'
is a single key with dots in its name, not a path to the setting.
The Config interface has typed getters: getString, getNumber,
getBoolean, getDuration, getBytes, getStringList, etc.
Missing keys throw unless you check first with hasPath.
Loading order
Section titled “Loading order”1. REFERENCE_CONF ← bundled defaults2. the project's reference.conf — the first of these that is set: `referenceConfigFile` setting › ACTOR_TS_REFERENCE_CONFIG env var › ./reference.conf (CWD)3. that file's profiles.<profile> block ← when a profile is active4. one application file — the first of these that is set: `configFile` setting › ACTOR_TS_CONFIG env var › ./application.conf (CWD)5. that file's profiles.<profile> block ← when a profile is active6. one secrets file — the first of these that is set: `secretsFile` setting › ACTOR_TS_SECRETS_CONF env var › ./secrets.conf (CWD)7. that file's profiles.<profile> block ← when a profile is active8. constructor `config: { ... }` ← code-level override9. constructor field overrides ← explicit fields beat config (logLevel, dispatcher, scheduler, …)
beside them, not a layer — a .env file: `environmentFile` setting › ACTOR_TS_ENV_FILE › ./.env (CWD)Each layer overlays on top of the previous, key by key. Layer 9
(constructor fields) always wins for the fields it covers; everything
else flows through the HOCON merge. The profile is withProfile(name),
then the ACTOR_TS_PROFILE environment variable, then none — see
Profiles. Layers 2, 4 and 6 are optional files: for each,
the first of its candidates that is set decides, a path with no file
behind it is an empty layer, and false for a path option reads no
such file at all. The settings, on ActorSystemOptions, are
withReferenceConfigFile, withConfigFile and withSecretsFile, and
withEnvironmentFile for the .env; Config.load callers pass
referenceConfPath, appConfPath, secretsConfPath and
environmentFilePath instead — see The project
reference.conf and Secrets
file.
A file’s substitutions read its own keys, then the layers already
resolved beneath it, then the real environment, then the variables of
the .env file. So application.conf may build on
a key the project reference.conf sets, while a lower file never sees a
higher one — there is no late binding.
Each of layers 2, 4 and 6 is a single file. The option, the variable and the CWD lookup are three ways of naming it, tried in that order, and the first one that is set decides — an option or a variable that points at a file which does not exist loads nothing, rather than moving on to the next candidate (issue #996 is about saying so at startup). A variable that is set but empty counts as not set. The variables hold a path, never inline HOCON; a value that is not the path of an existing file is treated the same way. To layer further files, compose them in code as Includes are not supported shows.
The project reference.conf
Section titled “The project reference.conf”# reference.conf — the project's defaults, committed with the codemy-app { pool-size = 4 db.host = "localhost" db.url = "postgres://"${my-app.db.host}"/app"}The bundled reference.conf holds the framework’s defaults; a project
keeps its own in a reference.conf of its own, next to the code, and
lets application.conf override single keys of it per deployment. It
may set framework keys too — a project-wide actor-ts.dispatcher, say —
and carries profiles like the other files. It is read from the working
directory unless referenceConfPath, withReferenceConfigFile or
ACTOR_TS_REFERENCE_CONFIG names another file.
Environment files
Section titled “Environment files”# .env — git-ignored, beside the applicationDB_PASSWORD=s3cretREDIS_URL="redis://:s3cret@cache:6379"A .env file supplies variables to the substitutions of every file the
loader reads — ${DB_PASSWORD} in application.conf or in the secrets
file. It is read from the working directory unless
environmentFilePath, withEnvironmentFile or the real
ACTOR_TS_ENV_FILE names another one, and false reads none. The real
environment always wins over it, an empty value in it counts as unset,
and it never writes process.env, so child processes do not inherit it.
It may itself name the other files and the profile (ACTOR_TS_CONFIG=…,
ACTOR_TS_PROFILE=…), as the real environment can.
The grammar is Node’s --env-file one: KEY=value, an optional
export, quoted values in ', " or ` that may span lines (a
PEM key fits), \n read as a line break inside double quotes only, and
# starting a comment — a value with a # in it goes in quotes.
$VAR is kept as written, never expanded. A directory called .env —
a Python virtual environment often is one — is no file.
Where the built-in default lives
Section titled “Where the built-in default lives”Layer 1 is reference.conf, but not every setting has a key there — and
even those that do need a value in code for the case where nothing is
configured. That value has a fixed home, so you can always find what a
setting falls back to:
- Options defaults sit next to the field they back, in the matching
XOptions.ts.DEFAULT_MAX_ENTRIESis inInMemoryCacheOptions.ts,DEFAULT_NUM_SHARDSinShardingOptions.ts. - Everything else — caps, bounds and timeouts with no option behind
them — is in a
Constants.ts:src/<subsystem>/Constants.tsfor one subsystem,src/util/Constants.tsfor values several share.
So a reference.conf leaf and its code-level fallback are always exactly
two files, and the second one is named after the first.
Profiles
Section titled “Profiles”One application.conf can carry several environments. A root
profiles block holds one block per environment, each written as a
delta to the root of the same file:
my-app { host = "localhost" primary-host = ${my-app.host} pool-size = 4}
profiles { production.my-app { host = "db.internal" pool-size = 32 } staging = ${profiles.production}}The active profile’s block is laid over the root of its file, and every
other profile is dropped. Select it in code with withProfile, or with
the ACTOR_TS_PROFILE environment variable:
import { ActorSystem, ActorSystemOptions } from 'actor-ts';
const actorSystemOptions = ActorSystemOptions.create().withProfile('production');const system = ActorSystem.create('my-app', actorSystemOptions);- Code beats the environment.
withProfile—profilewhen you callConfig.loadyourself — outranksACTOR_TS_PROFILE, and no profile is the default. An empty name selects none, which is how code opts out of one the environment selected. - An unknown profile fails closed. A name neither the application
file nor the secrets file defines is refused at
startup, naming the profiles they do define — read as “no overlay”, a
misspelled
ACTOR_TS_PROFILE=produtionwould start production on the root’s development values. Every profile is checked to be a block when the file is read, active or not. profilesis reserved at the root. The block is stripped before the tree is used, so an inactive profile never reachessystem.config, the config dump or the DevTools panel. A rootprofileskey in theconfigobject you pass in code is refused rather than ignored.my-app.profiles, below the root, is an ordinary key.- The profile is laid over first, then substitutions resolve. An
alias in the root follows the profile: above,
primary-hostreadsdb.internalunderproductionandlocalhostwithout a profile. An inactive profile is never resolved, so a variable only production needs may be unset on a laptop. - A profile reads the root of its own file, the layers beneath it and
the environment — never a layer above. A profile of
application.confcan read a key the bundled or the projectreference.confsets, but not one only the secrets file sets, and a substitution that reads theprofilesblock is refused by name. staging = ${profiles.production}copies a whole profile, verbatim. A later delta does not merge into the copy: aprofiles.staging.my-app.pool-size = 8after it replaces the copied block, andhostis gone. The${profiles.production} { … }form that would merge is not supported yet (#537) — write a profile out in full when it differs from the one it would copy.
withProfile reaches the configuration of the system it builds,
system.config. A few components read the configuration themselves when
no system or Config is handed to them: ClusterClient, InMemoryLease,
KubernetesLease and WorkerCluster.spawn, and the exported
read…OptionsFromConfig helpers called without a Config,
readMessageBoundaryOptionsFromConfig, readLeaseOptionsFromConfig,
readKubernetesLeaseOptionsFromConfig and readOffloadPoolOptionsFromConfig
among them. They call Config.load() and see a profile only through
ACTOR_TS_PROFILE — set the variable when you use them, or hand them
system.config. A WorkerMesh hands its worker pool the main system’s
system.config, and its workers select no profile of their own: they run
with the values the main system’s profile produced.
Secrets file
Section titled “Secrets file”Credentials do not belong in application.conf. An optional second
file holds them, read after the application file and merged above it:
my-app.db { user = "app" password = "s3cr3t"}
profiles.production.my-app.db.password = ${?PRODUCTION_DB_PASSWORD}It is the first of these that is set: withSecretsFile(path) on
ActorSystemOptions, the ACTOR_TS_SECRETS_CONF environment variable,
then secrets.conf in the working directory — secretsConfPath takes
the setting’s place when you call Config.load yourself, and false
reads no secrets file.
import { ActorSystem, ActorSystemOptions } from 'actor-ts';
const actorSystemOptions = ActorSystemOptions.create().withSecretsFile('/run/secrets/orders.conf');const system = ActorSystem.create('orders', actorSystemOptions);A file that is not there is an empty layer, not an error, so a
deployment without one needs nothing. A file that is there is read on every
start, so a secrets.conf in the working directory that belongs to another
tool stops startup: the ConfigError names the file and why it was read —
move such a file, or name the right one with withSecretsFile or
ACTOR_TS_SECRETS_CONF. It splits into a root and profiles exactly as
the application file does, and the same profile is laid over its root.
Every value it sets is withheld from the config dump and the
DevTools panel, whatever its key is called — my-app.db.user above
included — and that holds when a higher layer overrides the key and in a
WorkerMesh worker, which receives its whole tree as one overrides
object. The dump’s header names the file it looked for, and says when
it was not there.
Keep the file out of version control — secrets.conf in .gitignore —
and in production mount it from your platform’s secret store: see the
Kubernetes
and Docker Compose
recipes.
Validation
Section titled “Validation”Option values are validated once, at consume time, on the merged
settings — after the layers above are resolved. Because it runs
on the merged result, the same rules apply no matter how a value
arrived: the fluent builder, a plain settings object, or a HOCON key.
Cross-field rules (e.g. “downThreshold must exceed
unreachableThreshold”) see the final values.
An invalid value throws an OptionsError (exported from the package
root), naming the offending field and what it expected:
MqttOptions: protocolVersion must be one of 4, 5 (got 6)- For broker actors (MQTT, Kafka, WebSocket client, …) the error is
raised when the actor starts (
preStart), after the required-field check — so a missing required setting still surfaces asBrokerOptionsError, and only present-but-invalid values becomeOptionsError. - For non-broker consumers (caches, leases, sharding, …) the error is raised from the constructor.
OptionsError is distinct from ConfigError (malformed HOCON — wrong
type, missing path) and BrokerOptionsError (a required broker setting
absent from every layer). Unset optional fields never trigger it; they
fall through to their defaults.
import { CircuitBreaker, CircuitBreakerOptions, OptionsError } from 'actor-ts';
// Non-broker consumers validate in their constructor, so the error is// thrown synchronously and a plain try/catch works:try { const options = CircuitBreakerOptions.create() .withMaxFailures(0); // invalid — must be a positive integer new CircuitBreaker(options); // validates in the constructor} catch (e) { if (e instanceof OptionsError) { console.error(`bad option ${e.field}: ${e.message}`); }}// For a broker actor the OptionsError is thrown later in preStart and// re-wrapped as ActorInitializationError, so it surfaces via supervision// (not the spawning call's try/catch).Where to next
Section titled “Where to next”- Actor system — how settings reach the framework.
- Cluster overview — the keys most relevant to multi-node setups.
- Persistence overview — journal + snapshot-store plugin selection.
- Version policy — what’s stable vs experimental.
