Zum Inhalt springen
Deutsch

Konfiguration

actor-ts verwendet HOCON zur Konfiguration — eine Obermenge von JSON, die in JVM-Config-Dateien üblich ist, mit Substitutionen, Durations und Sizes. (include-Direktiven werden abgelehnt — setze die Quellen im Code zusammen.) Sechs Schichten, von oben nach unten aufgelöst:

  1. Konstruktor-Argumente an ActorSystem.create(name, settings) — explizite Felder wie logger oder logLevel, die jeden Key schlagen.
  2. Das inline config-Objekt in den Settings — die Code-Overrides, über jeder Datei.
  3. Die Secrets-Datei — secrets.conf, optional, mit ihrem aktiven Profil (Secrets-Datei).
  4. Die Anwendungsdatei — application.conf im Projekt-Root, oder ein expliziter Pfad via configFile, mit ihrem aktiven Profil (Profile).
  5. Die Defaults des Projekts — seine eigene reference.conf, optional, mit ihrem aktiven Profil (Die reference.conf des Projekts).
  6. Reference-Defaults — im Framework gebündelt als REFERENCE_CONF (siehe src/config/Reference.ts).

Alles, was nicht in Schicht 1 bis 5 spezifiziert ist, fällt auf den gebündelten Default zurück, und ein ${VAR} in jeder der Dateien darf neben der Umgebung auch eine .env-Datei lesen. Ladereihenfolge schreibt die ganze Kette aus.

Diese Seite erklärt, was die einzelnen Keys tun. Die vollständige Liste — jede Einstellung, die das Framework mitbringt, wörtlich aus der gebündelten Datei — steht unter Die vollständige reference.conf.

Dieses Beispiel zeigt eine repräsentative Auswahl der Blöcke, nicht jeden Key; die vollständige Liste steht unter Die vollständige 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 = kein Cap
max-quorum-timeout = 30s # 0 = keine Obergrenze
max-gossip-bytes = 1M # pro Gossip-Frame; 0 = kein Budget
}
remote {
tcp {
host = "0.0.0.0"
port = ${?ACTOR_TS_PORT} # ungesetzt: CLUSTER_PORT (Bootstrap), dann 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 deaktiviert die Auto-Passivierung
# shard-passivation-idle # ungesetzt: folgt passivation-idle
max-entities = 0 # 0 = kein Cap pro Node
buffer-size = 100000 # regionsweit; 0 = niemals puffern
register-retry-interval = 500ms
shard-region-query-timeout = 5s
entity-recovery { # wie erinnerte Entities zurückkommen
strategy = all # all | constant-rate
constant-rate.frequency = 100ms
constant-rate.number-of-entities = 5 # regionsweit, nicht pro Shard
}
}
}

Platziere das im Projekt-Root. Das Framework lädt es bei ActorSystem.create automatisch.

KeyDefaultZweck
system.name"default"Systemname — verwendet in Actor-Pfaden und zur Cluster-Identifikation. Greift, wenn ActorSystem.create() ohne Namen aufgerufen wird; ein explizites create('billing') gewinnt.
system.shutdown-drain-timeout2sWie lange terminate() den Actors unter /user gibt, die eingereihte Arbeit zu beenden, bevor die Stop-Kaskade startet. Kehrt zurück, sobald der Baum ruhig ist — ein untätiges System zahlt einen Tick. Halte den Wert unter coordinated-shutdown.default-phase-timeout; 0 schaltet den Drain ab.
KeyDefaultZweck
logger.level"info"Einer von debug / info / warn / error / off.
KeyDefaultZweck
actor.throughput16User-Nachrichten, die ein Actor pro Dispatcher-Turn vor dem Yield abarbeitet. Pro Pfad überschreibbar mit einem actor-ts.deployment-Eintrag, pro Actor mit ActorOptions.withThroughput(), das beide sticht.
actor.ask-timeout5sFrist, die ActorRef.ask setzt, wenn der Aufrufer kein timeoutMs nennt. Ein ask(message, ms) pro Aufruf gewinnt immer. Nicht jede Ref beachtet den Wert — siehe unten.

ask-timeout erreicht die meisten Refs, aber nicht alle — und das sollte man vor dem Tuning wissen. Eine Ref wendet den konfigurierten Wert nur an, wenn sie das ActorSystem erreichen kann, das ihn gelesen hat. Sieben können das: die gewöhnliche lokale Ref, TestProbe, RemoteActorRef, ClusterSingletonProxy, die beiden Shard-Refs und EntityRef über ihre Region. Die übrigen tragen einen Systemnamen und kein System und behalten die eingebauten 5 s: die Dead-Letter-Ref, Nobody, eine Ref auf einen nicht aufgelösten Pfad und die einmalige Antwort-Ref, die ein Ask sich selbst erzeugt, dazu zwei Framework-interne Handles (eine WebSocket-Verbindung und der Graceful-Stop-Watcher), auf die überhaupt nichts antworten kann. Sie alle hält man dort, wo kein lebender Actor dahintersteht — ein Ask darauf wartet also auf eine Antwort, die nicht kommt; der Timeout entscheidet nur, wie schnell man das erfährt, nicht ob.

Ein ungültiger Wert wird abgelehnt, nicht geklemmt — anders als actor.throughput oben. ask-timeout = 0 würde gar keine Frist setzen, und ein Ask ohne Frist kann nie beendet werden; es gibt also keinen sinnvollen Nachbarwert, auf den man klemmen könnte. Das System wirft in ActorSystem.create und nennt dabei den Key, statt später an jeder Ask-Stelle.

Unter 4.6s kollidiert der Wert mit dem Scatter-Gather-Routing. Ein Router aus Router.scatterGatherFirstCompleted(…) hat genau deshalb eine Frist von 4,5 s als Default, damit er die Fehler seiner Routees einsammeln und antworten kann, bevor das Ask des Aufrufers aufgibt. Ein kürzerer Ask-Timeout führt dazu, dass der Aufrufer AskTimeoutError sieht statt des AggregateError, der die fehlgeschlagenen Routees benennt. Das System schreibt in diesem Fall beim Start eine warn-Zeile; wenn die kürzere Ask-Frist gewollt ist, gib dem Router mit ScatterGatherOptions.withTimeoutMs() seine eigene.

KeyDefaultZweck
diagnostics.log-dead-letters10Dead Letters, die vollständig geloggt werden, bevor das Logging aussetzt. 0 schaltet das Dead-Letter-Logging ganz ab. Erfasst und auf dem Event-Stream publiziert wird jedes Letter ohnehin — das hier steuert nur die Log-Zeile.
diagnostics.log-dead-letters-during-shutdownoffDen Schwall loggen, den terminate() beim Leeren der Mailboxen in die Dead Letters erzeugt. Aus, weil ein geordnetes Herunterfahren jede eingereihte und gestashte Nachricht so entsorgt; ein einzelnes ref.stop() loggt weiterhin, denn das System terminiert nicht.
diagnostics.log-dead-letters-suspend-duration5mWie lange das Logging aussetzt, sobald die Anzahl oben erreicht ist. 0 setzt nie aus — so schreibt man „jedes Dead Letter loggen“.
diagnostics.log-config-on-startoffSchreibt die zusammengeführte Konfiguration einmal beim Start ins Log — ein info-Eintrag, jeder Key mit der Schicht, die ihn gesetzt hat, nach Pfad sortiert. Die Antwort auf „warum steht die Einstellung nicht so, wie ich sie geschrieben habe“. Vor dem Einschalten den Hinweis zur Schwärzung unten lesen.
diagnostics.debug.unhandledoffEin debug-Eintrag pro Nachricht, die ein Actor entgegengenommen und abgelehnt hat: Empfängerpfad, Nachrichtenklasse, Sender. Der Zähler (actor_unhandled_total) und das Dead Letter entstehen ohnehin.
diagnostics.debug.lifecycleoffEin debug-Eintrag pro Start, Stopp und Neustart eines Actors. ActorStarted / ActorStopped / ActorRestarted tragen dieselben Fakten zu einem Subscriber auf dem Event-Stream, der selektiv sein kann — was ein Log-Level nicht kann.
diagnostics.debug.event-streamoffEin debug-Eintrag pro Subscribe und Unsubscribe auf dem Event-Stream — nie pro Publish, das bei jedem Actor-Start, jedem Stopp und jedem Dead Letter läuft. Ein Unsubscribe über alle Kanäle, das nichts entfernt hat, wird nicht protokolliert; jeder Actor-Stopp erzeugt eines.

Der Eintrag nennt den Empfängerpfad, den Sender sofern bekannt und die Klasse der Nachricht — nie die Payload, aus demselben Datenschutzgrund, aus dem dead-letters.store auf off steht. Jeder Key hier ist auch im Code setzbar, feldweise, über ActorSystemOptions.withDiagnostics(…). Siehe Dead Letters für das ganze Bild.

Die debug.*-Keys brauchen zwei Schalter, nicht einen. Der Key entscheidet, ob ein Eintrag entsteht; logger.level = debug entscheidet, ob er geschrieben wird. Nur einen von beiden zu setzen sieht exakt so aus wie ein Schalter, der nicht funktioniert. log-config-on-start gehört absichtlich nicht zu dieser Familie — es ist ein info-Eintrag, denn wer einen Konfigurations-Dump anfordert, hat um Ausgabe gebeten.

Was der Dump schwärzt und was nicht. Ein Wert wird zurückgehalten, wenn irgendein ganzes Wort seines Keys password, passphrase, passwd, pass, secret, token, key, credential, auth oder authorization lautet, im Singular wie im Plural — cache.redis.password und ein api-key erscheinen also als <redacted>, und ebenso jeder Key unterhalb eines Zweigs namens credentials. Irgendein Wort, egal an welcher Stelle im Namen: ein auth-header trägt ein Bearer-Token, obwohl er auf header endet. Und nur ganze Wörter — ein Name wird an jedem Zeichen, das weder Buchstabe noch Ziffer ist, an jedem camelCase-Höcker und vor einer Ziffer nach einem Buchstaben in Wörter zerlegt, also enthält passivation-idle kein pass und keyspace kein key, password2 dagegen das Wort, das es nummeriert. An ein anderes Wort geklebt zählen diese Wörter ebenso (pgpassword, clientsecret, ghtoken), bis auf key, pass und auth, auf die zu viele gewöhnliche Wörter enden; von den Namen auf …key zählen apikey, accesskey, secretkey und privatekey, und pwd zählt neben einem anderen Wort des Key-Pfads, wie in mysql-pwd oder db.pwd — nur eine Variable, die bloß PWD heißt, das Arbeitsverzeichnis einer Shell, nicht. Ein sshkey wird nicht erkannt. Ein Wert, dessen Name ein solches Wort enthält, wird auch dann zurückgehalten, wenn er Tuning ist: eine eigene token-bucket-size erscheint als <redacted>, und nur die Keys, die reference.conf mitbringt, etwa cluster.receptionist.max-subscribers-per-key und cache.redis.key-prefix, sind namentlich ausgenommen. Ein Wert, der ein Boolean ist, wird nie zurückgehalten — egal wie sein Key heißt, denn beide Zustände sind öffentlich.

Die Zugangsdaten einer URL werden maskiert, egal wie ihr Key heißt. Die Userinfo jedes scheme://user:password@host in einem gedruckten Wert — und in jedem Element einer Liste — wird durch *** ersetzt. Hat ${?REDIS_URL} den Key cache.redis.url auf redis://default:s3cret@redis.example:6379/0 gesetzt, erscheint er als "redis://***@redis.example:6379/0" — und ebenso jeder eigene Key, dsn, connection-string oder uri, in dem eine solche URL steht. Die Userinfo reicht bis zum letzten @ vor dem nächsten ://, also wird ein Passwort mit einem rohen /, ? oder # darin ganz maskiert. Das Schema und alles hinter diesem @, also Host, Port, Pfad und Query, werden exakt so gedruckt, wie sie geschrieben wurden — daran erkennst du, welches Redis konfiguriert ist —, und die Kopfzeile zählt diese Werte neben den zurückgehaltenen Keys. Den Preis zahlt ein Wert ohne Zugangsdaten mit einem @ weiter hinten, in einem Pfad oder einer Query: https://host/a@b erscheint als https://***@b.

Ein Wert, den die Secrets-Datei gesetzt hat, wird zurückgehalten, egal wie sein Key heißt, und die Kopfzeile zählt diese Keys getrennt von denen, die ihr Name verrät. Die Key-Regel liest auch die Felder eines Objekts in einer Liste, die ein einziger Key ist: in upstreams = [ { host = "db-1", password = "…" } ] erscheint password als "<redacted>" und host so, wie er geschrieben wurde.

Ein Wert, den eine Umgebungsvariable geliefert hat, wird zurückgehalten, wenn der Name der Variable Zugangsdaten benennt, nach derselben Regel, nach der ein Key gelesen wird, egal wie der Key heißt: my-app.dsn = ${DB_PASSWORD} erscheint als <redacted>, und ebenso ein Key, der auf ihn verweist, und eine Zeichenkette, die aus ihm gebaut ist. Das gilt für eine Variable aus der echten Umgebung wie aus der .env-Datei, in welcher Schicht sie auch gelesen wurde — auch wenn ein Code-Override den Key ersetzt hat — und im Dump eines WorkerMesh-Workers. Jede Zeile nennt die Variablen hinter ihrem Wert, ob zurückgehalten oder nicht — my-app.db.host = "db-1" [application, from $DB_HOST] —, und die Kopfzeile zählt diese Keys getrennt von den beiden anderen Gründen.

Die Key-Regel ist eine Heuristik über Namen und die schwächste der vier. Was keine von ihnen sieht, wird vollständig gedruckt: ein ausgeschriebenes nacktes Passwort unter einem Key, der keines benennt, außerhalb der Secrets-Datei und nicht aus einer Variable, deren Name Zugangsdaten nennt; Zugangsdaten in einem Query-String (?password=…, ?authToken=…); der Connection-String von SQL Server in der Form Server=…;Password=…; und die schemalose Server-Liste user:password@host:11211 von Memcached. Und die Liste wird nicht weiter gefasst: seed würde cluster.seed-nodes schwärzen, und ein Dump, dessen gewöhnliche Keys <redacted> lauten, wird nicht mehr gelesen. Behandle die Ausgabe also als vertraulich, lass den Key außerhalb einer Untersuchung auf off, und sieh nach, wie deine eigenen Keys heißen, bevor du einen Dump in ein Ticket kopierst. Dieselben Regeln, dieselben Listen und dieselben Grenzen gelten für das Konfigurations-Panel der DevTools.

KeyDefaultZweck
mailbox.default.capacity0Begrenzt jeden Actor, den die Anwendung geschrieben hat, auf so viele eingereihte User-Nachrichten, ohne eine Spawn-Stelle anzufassen. 0 heißt: keine globale Schranke — das ist das ausgelieferte Verhalten. Das hier ist also kein Nachjustieren, sondern der Schalter, der für alle Anwendungs-Actors auf einmal Nachrichtenverlust einführt.
mailbox.default.overflow"drop-head"Systemweite Policy für jede begrenzte Mailbox: die globale Schranke oben und jeden Actor, der withMailboxCapacity() setzt, ohne eine eigene Policy zu nennen. drop-head / drop-new / reject.

Die Schranke erreicht die Actors, die die Anwendung geschrieben hat — und das ist nicht dieselbe Menge wie die Actors unter /user: eine Sharded Entity wird von ihrem Shard gespawnt, ein Cluster Singleton von seinem Manager, beide unter /system, und beide sind Klassen der Anwendung. Ausgenommen sind die eigenen Actors des Frameworks — Shard-Regions und Shards, Singleton-Manager, der Pub-Sub-Mediator, der Reliable-Delivery-Producer, der DevTools-Hub — denn ihren Verkehr abzuwerfen würde Invarianten brechen, nach denen die Anwendung nie gefragt hat und die sie nicht sieht. (Eine Framework-Klasse, die als Entity läuft, ist eine Entity: der Host, in dem ShardedDaemonProcess jeden Daemon laufen lässt, ist begrenzt.) Eine Spawn-Stelle sticht beide Keys: ActorOptions.withMailboxCapacity() überschreibt die Kapazität, withMailbox() ersetzt die Queue vollständig. Dazwischen liegt der actor-ts.deployment-Eintrag, der zum Pfad eines Actors passt: seine Kapazität und seine Policy stechen diese Keys für die Pfade, die er nennt, und sein mailbox-capacity = 0 nimmt sie von der globalen Schranke aus.

Lies Mailbox-Dimensionierung, bevor du das einschaltest. Dieser Key und das mailbox-capacity eines Deployment-Eintrags sind die beiden in dieser Datei, die eine Nachricht in einem Actor verlieren können, dessen Code nichts über eine Mailbox sagt — dieser hier in allen Anwendungs-Actors auf einmal — und die Seite nennt die vom Framework geschriebenen Actors, die eine pauschale Schranke weiterhin erreicht, weil Anwendungscode sie spawnt: den WebSocket-Hub und seine Connections, die Broker-Adapter, den gRPC-Client und -Server.

Einstellungen pro Pfad: ein Throughput und eine Mailbox für die Actors, deren Pfad ein Key trifft, ohne ihre Spawn-Stellen anzufassen (#868). Der Block wird leer ausgeliefert — seine Keys sind deine Actor-Pfade —, also ändert sich nichts, bis du einen Eintrag schreibst.

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 }
}
KeyDefaultZweck
deployment."<path>".throughputungesetztUser-Nachrichten, die ein getroffener Actor pro Dispatcher-Turn abarbeitet. Eine ganze Zahl; 0 oder weniger liest sich als 1, wie bei actor.throughput.
deployment."<path>".mailbox-capacityungesetztEingereihte User-Nachrichten, bevor die Overflow-Policy greift. Eine ganze Zahl ab 0; 0 lässt die getroffenen Actors unbegrenzt, egal wie mailbox.default.capacity gesetzt ist.
deployment."<path>".mailbox-overflowungesetztdrop-head / drop-new / reject, für jede begrenzte Mailbox eines getroffenen Actors: die Kapazität dieses Eintrags, eine der Spawn-Stelle ohne eigene Policy oder die globale.

Keys sind absolute Pfadmuster, in Anführungszeichen. /user/ingest nennt einen Actor; * ist eine beliebige Zeichenfolge innerhalb eines Segments (/user/pool/routee-*), und ein Segment, das genau ** ist, steht für ein oder mehrere ganze Segmente (/user/hub/**) — die Grammatik, die parallelism.offload verwendet. Setz jeden Key in Anführungszeichen: ohne parst er nicht, und ein . im Namen eines Actors würde ihn zerteilen. Die Keys tragen weder Schema noch Systemnamen, also treffen sie weiter, wenn das System umbenannt wird, und ein Actor, den parallelism.offload auf einen Worker verlegt, wird auch in seinem Worker getroffen, dessen System einen eigenen Namen hat.

Jedes Blatt wird für sich aufgelöst: zuerst die Spawn-Stelle (ActorOptions), dann der passende Eintrag, dann actor.throughput / mailbox.default, dann der eingebaute Wert. withMailbox() ersetzt die Queue weiterhin vollständig, egal was der Eintrag sagt.

Ein Eintrag pro Actor, und zwar als Ganzes. Treffen mehrere Keys, gewinnt der spezifischste: ein exakter Pfad, dann Keys mit *, aber ohne **-Segment, dann Keys mit einem **-Segment; innerhalb jeder Stufe das längere literale Präfix (der Text vor dem ersten *), dann mehr literale Zeichen, dann schlichte String-Reihenfolge. Ein Blatt, das der gewählte Eintrag weglässt, fällt auf die Systemebene durch, nie auf einen weniger spezifischen Eintrag — mit "/user/**" { throughput = 8 } daneben lässt ein leerer "/user/special" { } also /user/special mit actor.throughput laufen.

Wer die Klasse geschrieben hat, entscheidet, was ein Eintrag erreicht, wie bei mailbox.default: die Actors, die deine Anwendung geschrieben hat, einschließlich der Sharded Entities und Singleton-Instanzen, die das Framework für dich unter /system spawnt, und nie einen der eigenen Actors des Frameworks, egal was der Key sagt. Deshalb wird /system hier nicht abgewiesen wie bei parallelism.offload: /system/cluster/sharding/region-orders/** begrenzt die Entities dieser Region und lässt ihre Shards in Ruhe.

Ein Key, der nichts trifft, bewirkt nichts. Das System verweigert den Start mit einem ConfigError, der actor-ts.deployment."<key>" und das Blatt nennt, bei einem Key, der nicht absolut ist, ein leeres, ein .- oder ein ..-Segment hat oder nur die Wurzel oder einen Guardian nennen kann (/user, /*); bei einem Eintrag, der kein Block ist; bei einem anderen Blatt als den dreien; und bei einem Wert außerhalb seines Bereichs.

KeyDefaultZweck
dispatcher.default"hybrid"hybrid (Default) — weckt Actors über die Microtask-Queue und gibt jede 64. Einheit an eine Macrotask ab, damit Timer und I/O weiter drankommen; immediate — der bisherige Default, ein setImmediate pro Turn: fair, zum Preis von rund 2,4 µs pro Sprung; microtask — unbegrenzt, hungert die Event-Loop unter Dauerlast aus, nur zum Messen; throughput — arbeitet pro Tick bis zu dispatcher.throughput eingereihte Turns ab, über Actors hinweg. Ein nicht gesetzter oder unbekannter Wert fällt auf hybrid zurück.
dispatcher.throughput16Eingereihte Actor-Turns, die ein ThroughputDispatcher pro Tick abarbeitet, über Actors hinweg — keine Nachrichten und nicht pro Actor. Siehe actor.throughput oben für den Per-Actor-Batch. Eine ganze Zahl ab 1; anders als actor.throughput wird sie nicht auf 1 angehoben — mit default = throughput lässt eine 0 oder weniger ActorSystem.create mit einem OptionsError aus ThroughputDispatcher scheitern.
KeyDefaultZweck
dead-letters.store"off"Geordnet danach, wie viel aufbewahrt wird: off = nur publishen, nichts aufbewahren / metrics = zählen, keine Payload aufbewahren / memory = ein begrenzter Ring / persistent = zusätzlich ins Journal schreiben, sodass die Queue einen Neustart übersteht.
dead-letters.max-entries1000Aufbewahrte Letters, bevor das älteste verdrängt wird. Von off und metrics ignoriert, die keine aufbewahren.
dead-letters.retention1hLetters nach dieser Zeit altern lassen. 0 schaltet das Altern ab und lässt max-entries als einzige Schranke.
dead-letters.max-replays3Wie oft ein Letter erneut zugestellt werden darf, bevor es in Quarantäne kommt.
dead-letters.persistence-id""Journal-Stream, in den der persistent-Store schreibt. Leer leitet ihn aus dem Systemnamen ab, sodass zwei Systeme mit gemeinsamem Journal getrennte Queues behalten.

Jeder Key hier ist auch im Code setzbar, feldweise, über ActorSystemOptions.withDeadLetters(…) — was diesen Block überstimmt, wie explizite Options es immer tun. Siehe Dead Letters dafür, was die Queue enthält und wie man daraus erneut zustellt.

KeyDefaultZweck
cluster.gossip-interval1sWie oft Gossip mit einem zufälligen Peer ausgetauscht wird.
cluster.seed-nodes[]Peers, bei denen sich dieser Node beim Start meldet, "system@host:port" (oder "host:port"). Leer = „Ich bin der erste Node“ — siehe unten.
cluster.roles[]Rollen-Tags dieses Nodes. Shard-Regionen, Singletons, die Schwellen pro Rolle und die rollengefilterten Downing-Strategien platzieren alle nach Rolle.
cluster.app-version(nicht gesetzt)Die Anwendungsversion, die dieser Node seinen Peers nennt — ein Label für Betreiber, angezeigt von /cluster/members und überall, wo ein Mitglied ausgegeben wird; nichts platziert, routet oder downt danach. In reference.conf nur als Kommentar: nicht gesetzt nennt der Node keine und schickt nichts über die Leitung — siehe unten.
cluster.seed-retry-interval3sWie oft Seed-Verbindungen während des Joins wiederholt werden.
cluster.weakly-up-after0sBefördert ein joining-Mitglied nach dieser Zeit automatisch zu weakly-up. 0 schaltet das ab — siehe Weakly-up.
cluster.publish-stats-interval0sWie oft dieser Node eine ClusterStatsPublished-Momentaufnahme seines Mitgliederbilds auf system.eventStream veröffentlicht. 0 startet keinen Timer — siehe unten.
cluster.shutdown-after-unsuccessful-join0sWie lange ein Node joining oder weakly-up bleiben darf, bevor er den Join aufgibt. Kann ihn zur Frist nichts mehr befördern, protokolliert er eine Warnung, verlässt den Cluster und führt die Coordinated-Shutdown-Pipeline mit ClusterJoinUnsuccessfulReason aus; andernfalls fragt er alle seed-retry-interval erneut. 0 setzt keine Frist — siehe Joining und Seeds.
cluster.max-members1000Obergrenze für lebende Mitgliedseinträge, die Gossip anlegen darf. 0 schaltet die Grenze ab.
cluster.max-tombstones10000Obergrenze für removed-Tombstones, die Gossip anlegen darf. 0 schaltet die Grenze ab.
cluster.minimum-members-before-up1Mitglieder, die vorhanden sein müssen, bevor irgendetwas zu up befördert wird. 1 ist das bisherige Verhalten — siehe unten.
cluster.role.<role>.minimum-members-before-up(nicht gesetzt)Schwelle pro Rolle, mit der obigen als UND verknüpft. In reference.conf nur als Kommentar, da Rollennamen zum Deployment gehören.
cluster.run-coordinated-shutdown-when-downonWas ein Node tut, sobald ihn seine eigene Downing-Entscheidung entfernt. on verlässt die Mitgliedschaft und führt danach die Coordinated-Shutdown-Pipeline mit ClusterDowningReason aus, die das Actor-System beendet; off verlässt sie und lässt seine Actors weiterlaufen. Siehe unten.
cluster.down-smaller-islandoffTreffen zwei gleichnamige Cluster aufeinander, die sich während einer Start-Partition gebildet haben, downt sich der kleinere selbst (bei Gleichstand der, dessen niedrigste Adresse höher sortiert). Aus: Das Treffen wird mit error geloggt und die Frames der anderen Insel abgewiesen; ein Operator startet eine Seite neu (#1176).
cluster.tombstone.time-to-live24hWie lange ein removed-Tombstone gehalten wird, bevor er gepruned wird.
cluster.tombstone.prune-interval5mWie oft der Prune-Durchlauf läuft.
cluster.tombstone.min-retention0sMindestalter, bevor ein Tombstone gepruned werden darf. 0 leitet es aus failure-detector.down-after ab (6×).
cluster.failure-detector.implementationsimpleWelchen Erkennungsalgorithmus dieser Node fährt — simple (Zeitschwellen) oder phi (varianzbewusstes φ-Accrual).
cluster.failure-detector.heartbeat-interval500msWie oft Heartbeats gesendet werden. Gilt für beide Implementierungen — siehe unten.
cluster.failure-detector.unreachable-after2sVerdachtsschwelle für unreachable-Status. Nur simple.
cluster.failure-detector.down-after5sStille, nach der das Urteil down lautet. Ohne Split-Brain-Strategie entfernt das den Peer, unter dem Default auto-down = on; mit einer Strategie oder unter auto-down = off wird er auf unreachable geparkt. Wird ab dem letzten Heartbeat gemessen, muss also größer als unreachable-after sein. Nur simple.
cluster.failure-detector.auto-downonWas ein down-Urteil bewirkt, wenn keine Split-Brain-Strategie konfiguriert ist. on lässt den Detector den Peer selbst entfernen, sodass die überlebenden Nodes seine Shards und Singletons übernehmen — und das tut dann jede Seite einer Partition mit der anderen, sofern keine Strategie wie lease-majority konfiguriert ist. off ist das Opt-out: Es parkt den Peer auf unreachable, bis eine Strategie, Cluster.down oder POST /cluster/down ihn entfernt. Beide Implementierungen. Eine konfigurierte Strategie entscheidet jedes Entfernen, was immer dieser Schalter sagt — siehe unten.
cluster.failure-detector.phi.unreachable-threshold8φ-Wert, ab dem der Peer als unreachable gilt. Ein kontinuierlicher Score, Nachkommastellen sind also erlaubt.
cluster.failure-detector.phi.down-threshold12φ-Wert, ab dem der Peer als down gilt. Muss größer als phi.unreachable-threshold sein.
cluster.failure-detector.phi.max-sample-size200Wie viele jüngste Zwischenankunftszeiten pro Peer behalten werden.
cluster.failure-detector.phi.min-std-deviation100msUntergrenze für die gemessene Standardabweichung, damit ein sehr gleichmäßiger Peer nicht wegen Rauschen auffällt.
cluster.failure-detector.phi.acceptable-heartbeat-pause3sKulanz auf den letzten Heartbeat, bevor φ zu steigen beginnt — ein reiner Versatz, also geht beim Standard-Takt ein Stillstand bis etwa 3,5 s nach dem erwarteten Heartbeat durch. Per Messung gewählt; siehe den φ-Accrual-Detector.
cluster.failure-detector.phi.expected-response-after"auto"Die Zwischenankunftszeit, die φ annimmt, bis das erste Heartbeat-Intervall eines Peers gemessen ist, mit einer Standardabweichung von einem Viertel davon. "auto" ist heartbeat-interval; eine Dauer entkoppelt die beiden.
cluster.split-brain-resolver.active-strategyoffWelche Downing-Strategie eine Partition entscheidet — off, keep-majority, keep-oldest, keep-referee, static-quorum oder lease-majority.
cluster.split-brain-resolver.stable-after20sWie lange das Mitglieder- und Erreichbarkeitsbild unverändert bleiben muss, bevor die Strategie gefragt wird — oder, falls es das nie tut, die Hälfte davon, wie lange ein Peer durchgehend unerreichbar gewesen sein muss. Siehe unten.
cluster.split-brain-resolver.down-all-when-unstableoffAlle Mitglieder downen, diesen Node eingeschlossen, wenn das Bild über 3 × stable-after Unruhe kein einziges Mal für stable-after stillsteht. Aus — siehe unten.
cluster.split-brain-resolver.keep-majority.role""Nur Mitglieder mit dieser Rolle zählen zur Mehrheit. "" zählt alle.
cluster.split-brain-resolver.keep-oldest.role""Nur Mitglieder mit dieser Rolle kommen als „ältestes“ infrage. "" betrachtet alle.
cluster.split-brain-resolver.keep-oldest.down-if-aloneonOb das älteste verliert, wenn es allein auf seiner Seite steht, gegen zwei oder mehr auf der anderen. An, lässt ein Absturz des ältesten den Rest weiterlaufen; aus, downt sich jeder Überlebende selbst (#932).
cluster.split-brain-resolver.static-quorum.role""Nur Mitglieder mit dieser Rolle zählen zum Quorum. "" zählt alle.
cluster.split-brain-resolver.static-quorum.quorum-size(ungesetzt)Wie viele erreichbare Mitglieder nötig sind, um weiterzulaufen. Von static-quorum verlangt; in reference.conf nur als Kommentar — siehe unten.
cluster.split-brain-resolver.keep-referee.referee-address(ungesetzt)Adresse des Referee-Nodes; die Seite mit ihm gewinnt. Von keep-referee verlangt; nur als Kommentar.
cluster.split-brain-resolver.keep-referee.down-all-if-below-quorum(ungesetzt)Alle downen, wenn die Referee-Seite kleiner als dieser Wert ist. Optional; nur als Kommentar.
cluster.configuration-compatibility-check.enforceoffWas eine Abweichung bewirkt, über das Melden hinaus. on schließt den abweichenden Peer zusätzlich aus den Platzierungskandidaten dieses Nodes aus — siehe unten.
cluster.configuration-compatibility-check.checked-paths["actor-ts.remote.max-frame-bytes"]Einstellungen, deren effektive Werte dieser Node an seine Peers veröffentlicht und mit deren Werten vergleicht.

Diese Keys liegen unter dem, was Cluster.join(system, options) übergibt — ein explizites withGossipIntervalMs(…) gewinnt also weiterhin. Der Failure Detector wird pro Schwelle gemergt: setzt du im Code nur down-after, bleiben die beiden anderen aus der Datei erhalten. Der phi-Block wird genauso feldweise gegen withPhiAccrual(…) gemergt.

heartbeat-interval steht bewusst außerhalb von phi und hat dort keine Kopie. Die Kadenz gehört zur Heartbeat-Schleife des Clusters und nicht zu einem der beiden Algorithmen; ein Wechsel von implementation darf also nicht ändern, wie oft dieser Node mit seinen Peers spricht. phi.expected-response-after folgt ihr unter auto: Der Detector löst das Wort gegen die Kadenz auf, die er bekommt, also nimmt ein in dieser Datei oder im Code eingestelltes heartbeat-interval die Schätzung mit. auto-down steht aus demselben Grund außerhalb von phi: Beide Detectors kommen zu einem down-Urteil, also ist, was dieses Urteil bewirkt, keine Eigenschaft eines der beiden. Alles Übrige unter failure-detector gehört genau einer Implementierung und wird von der anderen ignoriert.

HOCON-Baum und ClusterOptions-Felder sind bewusst nicht deckungsgleich: die drei Tombstone-Stellschrauben stehen unter tombstone, weil man sie so einstellt, während die Felder flach bleiben (withTombstoneTtlMs(…), …). remote.tcp.host → host macht dieselbe Übersetzung schon länger.

min-retention = 0s heißt leite die Untergrenze aus dem Failure Detector ab, nicht keine Untergrenze — also genau das, was ein ungesetztes Feld bedeutet. Eine Datei, die den Default ausschreibt, verhält sich damit wie eine, die ihn wegläßt.

Die beiden max-*-Grenzen begrenzen die lokale Mitgliederkarte. remote.max-frame-bytes begrenzt einen Gossip-Frame; diese begrenzen, was eine Folge wohlgeformter Frames ansammeln kann — eine andere Größe, siehe Cluster-Sicherheit.

publish-stats-interval startet auf diesem Node eine fünfte periodische Aufgabe, und nur bei positivem Wert: alle interval veröffentlicht sie ein ClusterStatsPublished — Mitgliederzahl, up-Zahl, unreachable-Zahl, Leader und die eigene Adresse dieses Nodes — auf system.eventStream und an jeden cluster.subscribe-Listener. Jede Zahl ist über die Cluster-API ohnehin erreichbar; was der Key bringt, ist die Taktung. Er ist node-lokal und bewusst nicht auf dem clusterweiten cluster.eventStream, wo eine periodische Momentaufnahme pro Node N Frames pro Node und Intervall kosten würde. Er ist außerdem das Geschwister von actor-ts.devtools.stats-interval, nicht dessen Ersatz: dieselben Zahlen, ein anderer Kanal, und keiner leitet in den anderen weiter. Siehe Cluster — Überblick.

split-brain-resolver.active-strategy benennt eine Strategie, statt sie zu beschreiben — deshalb braucht das gebaute Objekt keine eigene HOCON-Form. Der konstruierte Provider landet in demselben Slot, den withDowning(…) füllt, und es gilt dieselbe Präzedenz: ein explizites withDowning(…) gewinnt, ein fehlendes fällt auf die Datei durch. Was jede Strategie entscheidet, steht unter Downing-Strategien.

Drei ihrer Keys stehen in reference.conf nur als Kommentar und sind damit abwesend, bis du sie schreibst. Jeder ist erforderlich oder begrenzt und hat keinen legalen Default: quorum-size = 0 und referee-address = "" werden von den Validatoren der Strategien abgelehnt, ein ausgelieferter Leaf könnte also nur ein Wert sein, der den Node am Starten hindert. static-quorum ohne quorum-size oder keep-referee ohne referee-address wird beim Start abgelehnt — mit dem fehlenden Key in der Meldung.

lease-majority entscheidet über einen Lease, den das Framework aus actor-ts.coordination.lease baut, und braucht dort deshalb ein Backend: Mit dem ausgelieferten backend = none wird die Strategie beim Start abgelehnt, statt ohne etwas zu laufen, worüber sie entscheiden könnte. Der Lease heißt <system>-split-brain-resolver, gehört diesem Node und wird bei der ersten Entscheidung der Strategie gebaut — die Adresse des Nodes gibt es noch nicht, wenn die Strategie entsteht. Einen lease-majority-Block gibt es nicht: Rolle und Acquire-Timeout bleiben im Code, withDowning(new LeaseMajority(…)), und ein Key unter split-brain-resolver.lease-majority wird abgelehnt.

stable-after und down-all-when-unstable sind die Policy-Hälfte des Blocks: sie entscheiden, wann die Strategie gefragt wird, nicht welche. Beide sind wirkungslos, solange active-strategy = off. Ohne Resolver gibt es keine Entscheidung, die ein Fenster verzögern könnte: Per Default entfernt der Failure Detector einen Peer, den er für down erklärt, selbst nach failure-detector.down-after, und unter failure-detector.auto-down = off parkt er den Peer auf unreachable, bis ihn jemand entfernt — ein zweites Fenster davor wären zwei Schwellen für eine Entscheidung.

failure-detector.auto-down ist der Schalter für genau diesen Fall ohne Resolver; neben einer konfigurierten Strategie ändert er nichts, denn die Strategie entscheidet jedes Entfernen, was immer er sagt. on ist der Default, weil ein Cluster aus n Nodes auch mit nur einem verbliebenen Node lauffähig bleiben muss: Ein abgestürzter Peer wird bei down-after entfernt, und der letzte verfügbare Node übernimmt seine Shards und Singletons. Den Preis zahlt man unter einer Partition: Der Detector kann einen Absturz nicht von einer unterscheiden, der Detector jeder Seite erreicht down-after für die andere Seite ungefähr im selben Moment, und auf dieses Urteil hin zu entfernen spaltet den Cluster in zwei, die nicht wieder zusammenfinden, wenn das Netz heilt — konfiguriere für Produktion lease-majority oder eine andere Strategie. off ist das Opt-out, und dessen Preis zahlt man bei einem Absturz: Der abgestürzte Node bleibt Mitglied, seine Shards werden nicht neu vergeben und seine entfernten Watcher bekommen kein Terminated, bis eine Strategie, Cluster.down oder POST /cluster/down (mit actor-ts.management.enable-down-endpoint = on) ihn entfernt oder er auf derselben Adresse neu startet. Der Node loggt pro geparktem Peer eine Warnung, die diese drei nennt. Siehe den Failure Detector.

stable-after sorgt dafür, dass eine Entscheidung über einen ruhenden Stand fällt. Jede eingebaute Strategie ist eine reine Funktion eines Bildes; ein mitten in der Unruhe gelesenes Bild — die Hälfte der Peers schon unreachable, der Rest gleich — liefert also ein Urteil über einen Cluster, den es zu keinem Zeitpunkt gab. Die Uhr ist der Failure-Detection-Tick, die effektive Auflösung damit failure-detector.heartbeat-interval: bei zwanzig Sekunden unsichtbar, bei zweihundert Millisekunden wissenswert. Es gibt bewusst keine Obergrenze gegen failure-detector.down-after: mit konfigurierter Strategie parkt der Detector einen unerreichbaren Peer und entfernt nichts, das Fenster hat also keine Frist zu schlagen.

Es ist eine Präferenz, keine Vorbedingung. Das beobachtete Bild umfasst Adresse und Status jedes Mitglieds; jeder Beitritt, jedes Verlassen und jeder Wechsel irgendwo startet es also neu — und ein Deployment, dessen Mitgliederbild sich häufiger bewegt als stable-after, würde eine Partition sonst überhaupt nie entscheiden, ohne dass der nicht mehr entfernende Detector noch auffinge. Ein Peer, der durchgehend 2 × stable-after lang unerreichbar war, wird deshalb der Strategie vorgelegt, gleich was sich sonst bewegt. Dieses Vielfache liegt oberhalb eines Fensters, damit ein Bild, das doch stillsteht, immer zuerst auf dem gewöhnlichen Weg entschieden wird, und unterhalb der Eskalationsfrist 3 × stable-after, damit eine Strategie gefragt wird, bevor down-all-when-unstable den Cluster stoppen kann.

down-all-when-unstable ist die Eskalation für den Cluster, der nie zur Ruhe kommt: hat das Bild über 3 × stable-after durchgehender Änderung kein einziges Mal ein volles stable-after stillgestanden — und ist weiterhin etwas unerreichbar —, werden alle Mitglieder gedownt, dieser Node eingeschlossen, und das Log sagt es auf warn. Der Abstand ist abgeleitet statt konfiguriert, denn er bedeutet ohnehin nur „ein Vielfaches dessen, was dieses Deployment für die Beruhigungszeit hält“ — und ein Abstand unterhalb des Fensters könnte nie ein einziges ruhiges Fenster abwarten.

Ausgeliefert wird aus; das Einschalten ist eine Haltung zugunsten von Integrität statt Verfügbarkeit, keine Kleinigkeit. Es ist die einzige Einstellung in diesem Bereich, die den ganzen Cluster stoppt, und sie wird von einer Uhr ausgelöst, nicht vom Urteil einer Strategie — ein rollierender Neustart, dessen Ersatz-Nodes weniger als stable-after auseinander eintreffen, sieht genau wie ein Cluster aus, der sich nicht beruhigt. Ein Bild, das sich nur durch saubere Beitritte und Abgänge bewegt, eskaliert nie: Unruhe ist keine Partition, weshalb eine leere Unerreichbar-Menge eine harte Vorbedingung ist.

run-coordinated-shutdown-when-down legt fest, was ein Node tut, sobald ihn seine eigene Downing-Entscheidung entfernt — das Urteil einer Strategie, das diesen Node einschließt, oder down-all-when-unstable. Unter off verlässt er nur die Mitgliedschaft: seine Peers zählen ihn nicht mehr, aber seine Actors laufen weiter — die Entities und Singletons, die er hielt, eine HTTP-Bindung — neben der Seite, die gewonnen hat; das ist der zweite Schreiber, den eine Downing-Entscheidung verhindern soll. Unter on, dem Default, verlässt er sie und führt danach die Coordinated-Shutdown-Pipeline mit ClusterDowningReason aus, auch wenn das Verlassen fehlschlägt; coordinated-shutdown.terminate-actor-system und exit-process entscheiden, worin dieser Lauf endet, wie bei einem Signal. Der Preis von on: ein falsches Selbst-Downing beendet einen Node; die beiden bekannten — static-quorum downte einen Cluster, der noch kleiner als quorum-size war (Issue #933), und keep-oldest downte jeden Überlebenden, sobald der Node mit der niedrigsten Adresse abstürzte (Issue #932) — sind behoben, und erst damit wurde on zum Default. Ein Downing, das ein Peer über diesen Node entscheidet, erreicht den Schalter nur über die eigene Strategie dieses Nodes: ein Peer, der ihn entfernt hat, lehnt seine Heartbeats ab, und bei einem Node, den jeder Peer ablehnt, wird die Strategie sofort gefragt (Issue #940).

configuration-compatibility-check vergleicht effektive Werte, keine Config-Werte. Jeder Node veröffentlicht, was er für jede Einstellung aus checked-paths tatsächlich aufgelöst hat, und vergleicht das mit dem, was seine Peers veröffentlichen — so werden auch zwei Nodes erwischt, die sich nur unterscheiden, weil einer .withMaxFrameBytes(…) gerufen hat. Ein Vergleich des Config-Baums könnte das nicht: eine explizite Option liegt darüber. checked-paths ist eine Erlaubnisliste dessen, was den Node verlässt — eine Einstellung, die nicht darin steht, wird nie gegossipt; und nur Namen, die auch jemand veröffentlicht, lassen sich vergleichen. Das Framework veröffentlicht drei davon (siehe Joining und Seeds). Abwesenheit auf einer der beiden Seiten ist Schweigen, damit ein Cluster mit gemischten Versionen nichts meldet statt alles.

enforce = on schließt den abweichenden Peer aus den Platzierungskandidaten dieses Nodes aus — und sonst nichts. Es downed oder quarantäniert niemanden: eine falsch konfigurierte Mehrheit würde dann die korrekt konfigurierte Minderheit verdrängen, und aus einer Warnung würde ein Ausfall. Die Kandidatenmenge ist außerdem eine Sicht pro Node, deshalb liest nichts, das eine Rolle wählt (der Host eines Singletons, das Zuhause eines Shards), daraus — sonst wählten zwei Nodes zwei Gewinner.

minimum-members-before-up hält den Übergang joining / weakly-up → up zurück, bis die lokale Mitgliederkarte mindestens so viele Mitglieder enthält — sowohl die Beförderungen des Leaders als auch die Selbstwahl eines Gründungsknotens. Gezählt werden Mitglieder in joining, weakly-up und up; ein leaving-Mitglied hält die Schwelle für seinen Nachfolger also nicht offen. Rückwärts wird nie ausgewertet: einen Übergang up → joining gibt es nicht, ein später schrumpfender Cluster behält die bereits beförderten Mitglieder und hält nur neue zurück.

Schwellen pro Rolle sind damit UND-verknüpft — die globale Zahl und jede konfigurierte Rollenzahl müssen erfüllt sein. Sie werden als cluster.role.<role>.minimum-members-before-up geschrieben und sind nur als Kommentar enthalten, denn kein Leaf hier könnte eine Rolle benennen, die Ihr Deployment erfunden hat. Ihr Nutzen ist „auf einem Cluster ohne Backend keine Arbeit platzieren“: Shard-Regionen und Singletons werden nach Rolle gehostet, ein Cluster aus lauter Frontends erfüllt also eine globale Zahl und ist trotzdem nutzlos.

Es ist nicht cluster.bootstrap.minimum-members, ein reines Warte-Prädikat für awaitReady / isReady, das nie einen Status ändert. Diese Einstellung macht jene weitgehend überflüssig — ein Node, der überhaupt up ist, belegt bereits, dass die Schwelle erreicht war —, beide zu setzen lohnt sich also selten. Und es ist kein Quorum und keine Sicherheitsmaßnahme: jeder Node darf sich selbst als up ankündigen, die Schwelle begrenzt also Versehen, nicht Angreifer. Zuständig ist der split-brain-resolver oben; beachten Sie, dass static-quorum noch keinen „nichts ist unreachable“-Frühausstieg hat — prüfen Sie eine Downing-Strategie also für die Clustergröße, bevor Sie eine Schwelle über 1 setzen.

Solange die Schwelle nicht erreicht ist, bleibt der Node joining und sagt das einmalig — mit Schlüsselname und aktueller Zahl — statt die Cold-Start-Stall-Diagnose zu melden, die hier ein falsches Urteil wäre. Siehe Joining und Seeds.

seed-nodes ist eine Liste, die auf jedem Node eines Deployments richtig ist — genau deshalb gibt es den Schlüssel überhaupt. Ein Node entfernt seine eigene Adresse aus der Liste, bevor er wählt; wer also den designierten ersten Node einträgt und dieselbe Datei überall ausliefert, lässt genau diesen Node mit einer leeren Liste zurück — er wählt sich selbst —, während alle anderen ihn kontaktieren. Was nicht funktioniert, ist die symmetrische Form, in der jeder Node gelistet ist: durch das Selbst-Ausschließen bleibt niemand mit der leeren Liste übrig, die selfElection: 'immediate' verlangt, also wird niemand jemals befördert. Die Config erzeugt diese Falle nicht, und der Node diagnostiziert sie, aber sie wird damit zu einem Einzeiler — Cluster-Bootstrap mit Stable Observation, die eine Code-Option bleibt, ist der Ausweg, wenn die Mitglieder vorab nicht bekannt sind.

Beide Leaves werden als Liste gelesen und nur als Liste; ein einzelnes seed-nodes = ${?SEED_NODES} wird beim Start abgelehnt statt an Kommata zerlegt. Schreiben Sie eine optionale Substitution pro Eintrag — nicht gesetzte fallen aus dem Array heraus:

actor-ts.cluster {
seed-nodes = [ ${?SEED_1}, ${?SEED_2}, ${?SEED_3} ]
roles = [ ${?NODE_ROLE} ]
}

Für die einzelne kommaseparierte Variable ist seedsFromEnv(...) im Code die vorgesehene Form — siehe Seed-Provider. Ein fehlerhafter Eintrag wird von Cluster.join abgelehnt, bevor der Transport bindet, und die Meldung nennt die betroffene Zeichenkette.

cluster.seed-nodes und discovery.config.seeds sind nicht zwei Antworten auf dieselbe Frage, und die Reihenfolge steht fest: Cluster.bootstrap führt zuerst die Discovery aus und reicht deren Ergebnis weiter, ein gefundener Seed gewinnt also; dieser Schlüssel greift, wenn die Discovery niemanden oder nur diesen Knoten genannt hat — eine gefundene Liste, die nur aus diesem Knoten besteht, wird zu nichts gefiltert, und das ist Schweigen. CLUSTER_SEEDS ist eine Sprosse derselben Discovery-Leiter, ein Seed, den es nennt, gewinnt also ebenfalls über diesen Schlüssel. Ein explizites seeds: [] an Cluster.bootstrap gewinnt weiterhin über beide — es sagt „es gibt sonst niemanden“, und das ist eine Antwort, kein Schweigen —, und es wird abgelehnt, solange cluster.bootstrap.new-cluster-enabled aus ist. Siehe actor-ts.discovery.

app-version ist die Anwendungsversion, die dieser Node seinen Peers nennt, damit sich das Fenster eines Rolling Updates, in dem alter und neuer Code in einem Cluster laufen, am Cluster selbst ablesen lässt: sie erscheint in GET /cluster/members und in jeder Logzeile, die ein Mitglied ausgibt. Sie ist ein Label und nicht mehr — nichts platziert, routet oder downt danach. Ausgeliefert wird sie nur als Kommentar, in der Form von remote.tcp.advertised-host: nicht gesetzt nennt der Node keine Version und schickt nichts über die Leitung. Sie ändert sich pro Release statt pro Node, daher ist die Substitution die übliche Form, und eine nicht gesetzte Variable lässt den Schlüssel weg:

actor-ts.cluster.app-version = ${?APP_VERSION}

Eine wörtliche Version gehört in Anführungszeichen: app-version = 1.0 ist für HOCON eine Zahl und erreicht die Peers als "1".

Ein Wert aus der Umgebung wird zuerst als JSON gelesen, wo immer er sich als JSON parsen lässt. Eine Version, die sich wie eine Zahl liest, kommt in der Schreibweise dieser Zahl zurück — 1.10 als 1.1, 2.0 als 2, 1e3 als 1000 —, die Releases 1.1 und 1.10 tragen also dasselbe Label, eine ganze Zahl jenseits von Number.MAX_SAFE_INTEGER kann mit anderen letzten Ziffern zurückkommen (20261104123456789 als 20261104123456788), und eine, die sich wie null, eine Liste oder ein Objekt liest, lässt den Start mit einem ConfigError scheitern; eine Version mit einem zweiten Punkt (1.2.3) oder einem Buchstaben (v1.10) bleibt unverändert. Einen solchen Wert in der Variablen selbst quoten (APP_VERSION='"1.10"') oder im Code mit withAppVersion(...) setzen.

Ein Label besteht aus 1 bis 64 sichtbaren ASCII-Zeichen — ohne Leerzeichen und ohne Steuerzeichen, weil jeder Peer es ausgibt —, und Cluster.join lehnt eines ab, das dem nicht entspricht, ein leeres eingeschlossen, bevor der Transport bindet. Das Label eines Peers, das die Regel verletzt, wird verworfen, nie das Mitglied. withAppVersion(...) im Code gewinnt über die Datei, wie explizite Options es immer tun.

selfElection und der Transport haben keine HOCON-Form. Der Transport ist ein Objekt, das eine Config-Datei nicht ausdrücken kann. selfElection ist die eine Einstellung, deren gemeinsamer Wert nicht bloß nutzlos, sondern unsicher ist: durchgängig 'never' startet nie einen Cluster, und durchgängig <delay> lässt alle Nodes im selben Moment sich selbst wählen — genau das Split-Brain, das die Option verhindern soll. Einen Wert pro Node verteilt der Cluster-Bootstrap.

KeyDefaultZweck
cluster.client.contact-points(nicht gesetzt)Cluster-Nodes, die ein Client ohne eigene Liste anwählt — jeweils host:port oder <system>@host:port, der Reihe nach probiert. In reference.conf nur als Kommentar; siehe unten.
cluster.client.system-name"cluster-client"Synthetischer System-Name im hello des Clients. Er benennt die Client-Seite des Handshakes und ist keine Identität.
cluster.client.ask-timeout5sFrist für ask(path, message), wenn der Aufruf selbst keine nennt. Ein timeoutMs pro Aufruf gewinnt weiterhin.
cluster.client.connect-timeout5sWie lange ein Kontaktpunkt Zeit hat, den hello-Handshake zu beantworten, bevor der Client ihn aufgibt und den nächsten wählt.
cluster.client.receptionist.ask-timeout5sFrist für das ask, das ein Cluster-Node stellvertretend für einen Client stellt, wenn ein ankommendes Envelope eine askId trägt.

Dieser Block wird anders gelesen als jeder andere auf dieser Seite, und ClusterClient ist der Grund: ein Client ist per Definition außerhalb des Clusters, hält also kein ActorSystem und hat kein system.config über sich. Sein Konstruktor lädt die Konfiguration deshalb selbst — dieselbe Kette, die ActorSystem.create benutzt: ACTOR_TS_CONFIG, dann ./application.conf, dann die eingebauten Defaults. Genau das macht einen ganz ohne Optionen gebauten Client zu etwas Konfigurierbarem statt zu etwas Kaputtem. Übergeben Sie ein Config als zweites Konstruktor-Argument, um ihn stattdessen festzunageln; dann wird das Dateisystem nie befragt.

Die receptionist-Hälfte ist die asymmetrische. ClusterClientReceptionist läuft innerhalb eines Systems, liest also dessen Config und lädt nichts. Sie liegt unter cluster.client statt bei actor-ts.cluster.receptionist oben — jener Block gehört dem Discovery-Receptionist, einem anderen Actor mit einem anderen Protokoll, der zufällig dasselbe Wort trägt.

contact-points wird nur als Kommentar ausgeliefert, dieselbe Form wie remote.tcp.advertised-host: die Liste ist Deployment-Identität, die kein Default aussprechen könnte, und [] ist nicht deren Abwesenheit — eine leere Liste weist der Validator zurück, ein ausgelieferter Leaf-Wert könnte also nur ein Wert sein, der jeden Client stoppt, der die Datei bloß kopiert hat.

client-identity, tls und logger haben überhaupt keine HOCON-Form. Die letzten beiden sind Zertifikatsmaterial und eine Logger-Instanz. Das erste ist die Entscheidung, die eine Sicherheits- und keine Verpackungsfrage ist: der synthetische Port eines Clients wird aus dem CSPRNG gezogen, damit kein Peer seinen Slot vorhersagen, adressieren oder vorwegnehmen kann — und eine Flotte, die sich einen konfigurierten Wert teilt, ist genau das, was diese Ziehung verhindern soll. Setzen Sie ihn mit withClientIdentity(host, port), wenn Sie einen stabilen brauchen.

Der Transport hat keine HOCON-Form — er ist ein Objekt, das eine Config-Datei nicht ausdrücken kann. seeds und roles haben eine, cluster.seed-nodes und cluster.roles weiter oben: sie sind Deployment-Identität, und genau deshalb bekommt jeder Eintrag seine eigene optionale Substitution statt eines geteilten Defaults. Eine Schwelle pro Rolle benennt eine Rolle, statt eine zuzuweisen — sie liest also aus der Datei, obwohl die Zuweisung weiterhin an der Join-Stelle passiert.

KeyDefaultZweck
cluster.singleton.role""Beschränkt das Hosten auf Nodes mit diesem Rollen-Tag. "" = jeder Node darf hosten; der leere String wird verworfen und nie weitergereicht.
cluster.singleton.buffer-size1000Nachrichten, die ein Proxy hält, solange der Cluster keinen Host hat, bevor er die neuesten in die Dead Letters gibt.
cluster.singleton.hand-over-timeout10sWie lange ein eingehender Host darauf wartet, dass jeder infrage kommende Peer bestätigt, das Singleton nicht zu betreiben, bevor er es trotzdem hostet.
cluster.singleton.use-leaseoffGibt jedem Singleton, das dieser Node startet, eine aus actor-ts.coordination.lease gebaute Lease, sodass nur der Halter hostet. Abgelehnt bei start(), solange coordination.lease.backend = none; ein withLease(…) im Code gewinnt, und withUseLease(false) nimmt ein einzelnes Singleton aus.
cluster.singleton.acquire-retry-interval5sWie lange der Manager wartet, bevor er ein fehlgeschlagenes acquire() einer Lease wiederholt. Nur erreichbar, wenn das Singleton eine Lease hat — im Code übergeben oder von use-lease gebaut.
cluster.singleton.max-hand-over-state-bytes1MObergrenze für einen Warm-Hand-over-Snapshot. Ein größerer wird nicht gesendet, und der Nachfolger startet kalt.
cluster.singleton.restart-on-terminationonStartet das Singleton neu, nachdem seine Instanz unerwartet gestorben ist — im Gegensatz zum geplanten Abbau einer Übergabe.

Beide Türen lesen den Block, und die zweite ist der Grund, dass es ihn gibt. cluster.singleton.start(...) legt ihn unter die Optionen des Aufrufers, ein explizites withBufferSize(…) gewinnt also weiterhin pro Feld. cluster.singleton.ref(...) nimmt überhaupt kein Optionsobjekt: vor diesem Block hatte ein reiner Proxy-Node schlicht keine Möglichkeit, seine Puffergrenze zu setzen — oder zu erfahren, dass das Singleton rollenbeschränkt ist, was schwerer wiegt: eine konfigurierte Rolle, die nur start() erreicht, lässt einen solchen Node beim einfachen Leader routen, während die Manager auf dem Rollen-Member hosten.

Eine Stelle der Präzedenz liest sich verkehrt herum: eine Rolle, die am SingletonKey der Actor-Klasse deklariert ist — oder an withRole(…) übergeben wird —, schlägt die Config-Datei, denn beides ist Code, und Code ist die höhere Schicht. Das gilt auch auf dem Proxy, und zwar in beiden Aufrufreihenfolgen: ein Node, der ref vor start aufruft, baut seinen Proxy aus der Datei, und die explizite Rolle, die das start mitbringt, ersetzt sie dann, statt gegen sie zu verlieren. Eine konfigurierte Rolle, die nach einer expliziten eintrifft, wird aus demselben Grund stillschweigend verworfen — das ist die Präzedenz bei der Arbeit, kein zu meldendes Problem.

Wovor der Proxy sehr wohl warnt, sind zwei Rollen aus derselben Schicht — zwei withRole-Aufrufe, oder ein Key und ein Optionsobjekt, die sich widersprechen. Ein Singleton lässt sich nicht auf zwei Arten beschränken, und nichts schlägt hier etwas anderes: er behält die erste und nennt die zweite im Log.

role = "" ist die Gestalt des Keys, kein Wert, mit dem jemand betreibt. Er wird verworfen statt weitergereicht, und das trägt hier gleich doppelt: '' würde ein explizites withRole(…) der Schicht darüber verdecken, und StartSingletonOptionsValidator weist eine leere Rolle rundheraus zurück — ein Node, der die ausgelieferte Datei unverändert kopiert, würde also jedes start() scheitern lassen.

use-lease baut die Lease des Singletons aus dem Coordination-Block: benannt <system>-singleton-<type>, im Besitz dieses Nodes — seiner Cluster-Adresse und Inkarnation — und erneuert auf dem Scheduler des Systems. Die Datei wählt das Backend und nichts an der Identität, deshalb gibt es kein lease-name: Ein Wert für den Block würde jedes Singleton auf einen Record legen, und einer, der dort steht, wird von start() wie von ref() abgelehnt.

Zwei weitere Keys fehlen mit Absicht. singleton-identification-interval konfiguriert ein Polling, das dieser Proxy nicht betreibt (er abonniert stattdessen Cluster-Events), und min-number-of-hand-over-retries zählt Versuche, die nichts zählt — die Wartezeit begrenzt hand-over-timeout. Die Wiederholrate der Übergabe ist eine Korrektheitseigenschaft des Austauschs und kein Tuning-Knopf und bleibt eine Konstante.

KeyDefaultZweck
cluster.pub-sub.gossip-interval1sWie oft ein Mediator seine Topic-Menge an einen zufälligen Peer schickt.
cluster.pub-sub.max-subscribers-per-topic10000Obergrenze für lokale Subscriber eines Topics. Ein Subscribe darüber wird mit SubscribeRejected beantwortet.
cluster.pub-sub.max-topics10000Obergrenze für verschiedene Topics eines Mediators — gilt für gegossipte Topic-Ansprüche genauso wie für lokale Subscribes.
cluster.pub-sub.max-remote-nodes-per-topic1000Obergrenze für Peers, die Subscriber für ein Topic beanspruchen dürfen.
cluster.pub-sub.send-to-dead-letters-when-no-subscribersonEin Publish, das niemanden erreicht hat, geht an system.deadLetters, statt verworfen zu werden.

Die drei Obergrenzen begrenzen, was ein Mediator überhaupt halten kann, und der Publish-Fan-out läuft über alle — sie sind also ebenso sehr eine Latenz- wie eine Speichergrenze. Die Gossip-Hälfte ist die, die man kennen sollte: ein Peer, der Topics ankündigt, für die er Subscriber beansprucht, hat früher auf jedem Empfänger einen Eintrag pro Namen angelegt — ganz ohne lokales Subscribe. Siehe DistributedPubSub.

KeyDefaultZweck
cluster.receptionist.gossip-interval1sWie oft der Receptionist seine lokalen Registrierungen gossipt.
cluster.receptionist.max-subscribers-per-key1000Obergrenze für Subscriber eines Service Keys. Ein Subscribe darüber wird mit ReceptionistSubscribeRejected beantwortet.
cluster.receptionist.max-subscriptions-total10000Obergrenze für Key/Subscriber-Paare über alle Keys dieses Nodes — ein Subscriber mit drei Keys zählt dreifach.

Beide Blöcke liegen unter dem, was dem start(...) der Extension übergeben wurde — ein explizites withMaxTopics(…) gewinnt also weiterhin. Gestoppte Subscriber werden vom Death Watch freigegeben und zählen gegen keine der Grenzen.

KeyDefaultZweck
distributed-data.gossip-interval1sWie oft eine Replika ihren Key-Satz an einen zufälligen Peer schickt.
distributed-data.quorum-timeout5sFrist für ein updateAsync / getAsync, das kein timeoutMs nennt; ein timeoutMs pro Aufruf gewinnt weiterhin. Wird von max-quorum-timeout begrenzt wie ein Wert des Aufrufers. Muss positiv sein.
distributed-data.max-pending-quorum-requests1000Obergrenze für offene Quorum-Requests — updateAsync und getAsync teilen sich ein Budget. Ein Request darüber wird direkt abgelehnt. 0 deaktiviert das Cap.
distributed-data.max-quorum-timeout30sObergrenze für eine Quorum-Frist — das eigene timeoutMs eines Aufrufs oder, wenn er keines nennt, quorum-timeout; ein größerer Wert wird darauf heruntergeschnitten. 0 deaktiviert die Obergrenze.
distributed-data.max-gossip-bytes1MByte-Budget für die Payload eines Gossip-Frames. Ein größerer Store wird pro Tick in Scheiben geschickt und setzt dort fort, wo der letzte Tick aufgehört hat. 0 entfernt das Budget.
distributed-data.log-data-size-exceeding100KWarnt (ratenbegrenzt) über einen Key, dessen eigene Kodierung diese Byte-Zahl überschreitet. Reine Meldung — der Key wird gegossipt wie zuvor. 0 warnt nie.
distributed-data.durable-keys[]Welche Keys ein konfigurierter durableStore persistiert. Leer heißt jeder Key. Ein Eintrag ist ein exakter Key-Name oder ein Präfix mit einem abschließenden *.

max-gossip-bytes wird immer auf remote.max-frame-bytes heruntergeschnitten: Wer das Wire-Cap senkt, senkt damit auch das Gossip-Budget, und keine Einstellung kann Gossip wieder darüber schieben. Das ist wichtig, weil die beiden Fehlerbilder nicht vergleichbar sind: Ein Frame über dem Wire-Cap wird schon an seinem 4-Byte-Längenpräfix abgelehnt, und der empfangende Transport verwirft die komplette Peer-Verbindung — Heartbeats, Membership-Gossip und jedes tell über Knotengrenzen inklusive — während ein Budget denselben Zustand lediglich über mehr Ticks verteilt. Ein einzelner Key, dessen eigene Kodierung das Budget überschreitet, lässt sich nicht weiter aufteilen: Er wird übersprungen, mit einer ratenbegrenzten Warnung samt Key-Name und beiden Größen gemeldet, in distributed_data_gossip_skipped_keys_total gezählt — und er konvergiert nicht.

Der Block liegt auf oberster Ebene statt unter cluster.* (wo pub-sub und receptionist wohnen), weil das Modul dort liegt: DistributedData kommt aus src/crdt/, und der Cluster ist ein positionales Argument von start(cluster), kein Tunable davon. durableStore hat hier keinen Key — es ist eine DurableStateStore-Instanz, die eine Config-Datei nicht ausdrücken kann.

Beide Caps begrenzen die Menge der offenen Requests selbst. Jeder offene Quorum-Request hält ein Promise, einen Timer und ein Ziel-Set am Leben, bis seine Deadline abläuft — ein ungedeckelter Replikator unter Last sammelt also alle drei an, ohne dass irgendetwas ihn bremst. Wer über max-pending-quorum-requests hinaus ablehnt, macht aus dem, was später als Timeout-Sturm ankäme, sofortige Fehler, die den Knopf beim Namen nennen. Siehe Quorum-Reads und -Writes.

log-data-size-exceeding meldet dieselbe Messung, die auch max-gossip-bytes vornimmt — nur eine Größenordnung früher — und ändert nichts daran, was verschickt wird. Ein Key jenseits des gesamten Budgets ist ohnehin laut; ein Key bei einem großen Bruchteil davon gossipt einwandfrei und verbraucht dabei genau diesen Bruchteil jedes Ticks, in dem er auftaucht — der Rest des Stores wird also entsprechend langsamer verteilt, ohne dass irgendetwas sagt, warum. 100K ist ungefähr ein Zehntel des ausgelieferten Budgets — zehn solcher Keys füllen ein ganzes Frame — und bewusst nicht Akkas 10KiB, was noch einmal ein Zehntel davon wäre und beim ersten legitimen ORSet eines Deployments anschlagen würde. Die Zeile hat ihre eigene Ruhephase, statt sich die der Oversize-Warnung zu teilen: Ein höheres max-gossip-bytes behebt jene und macht diese relevanter, keine der beiden darf die andere unterdrücken.

durable-keys schränkt ein, was ein konfigurierter durableStore schreibt; ohne Store ist der Key wirkungslos, und eine nicht-leere Liste ohne Store wird beim Start als Warnung gemeldet. Eine leere Liste heißt jeder Key — das Verhalten jedes Releases vor dieser Option — und niemals „nichts persistieren”; nichts zu persistieren erreicht man, indem man keinen Store konfiguriert. Ein Eintrag ist ein exakter Key-Name oder ein Präfix mit einem abschließenden * (session-*), und das ist die gesamte Syntax: Ein reichhaltigeres Muster hieße, aus einer Config-Datei einen Matcher zu bauen, und new RegExp(…) über einen vom Betreiber gelieferten Text ist eine ReDoS-Angriffsfläche auf genau dem Pfad, der entscheidet, was einen Neustart überlebt. Der Datensatz einer Replika wird bei jedem Save vollständig neu geschrieben — einen Eintrag zu entfernen löscht die Keys, die er benannte, bei der nächsten Mutation aus dem persistierten Datensatz. Siehe Durable Storage.

max-quorum-timeout begrenzt die andere Achse. Ein offener Request hält seinen Slot über die gesamte Deadline, ein einzelner Aufrufer mit einem stundenlangen timeoutMs parkt also das Budget für Stunden und sperrt spätere Aufrufer aus, die dem Cap selbst nie nahe kamen.

quorum-timeout ist die Deadline, die ein Quorum-Aufruf bekommt, wenn er selbst keine nennt, und max-quorum-timeout begrenzt sie genau so wie das timeoutMs eines Aufrufers. Es ist ein eigener Key statt actor.ask-timeout: Jener verschiebt den Default von ActorRef.ask, und wie lange eine Replika einen offenen Slot für die Antworten ihrer Peers hält, ist eine andere Wartezeit. Anders als die beiden Caps hat er keinen Aus-Schalter, und 0 kann keiner sein: Der Replikator stellt eine Deadline von 0 wie jede andere, sie läuft also beim nächsten Timer-Tick ab — ein Write scheitert dort, und ein Read begnügt sich mit dem, was diese Replika allein hält —, sofern nicht jede Replika, auf die der Request wartet, schon geantwortet hat, und der Validator weist sie ab.

KeyDefaultZweck
coordination.lease.backendnoneWomit das Framework seine Leases baut — none oder kubernetes —, wenn der Schalter eines Konsumenten einen verlangt. in-memory wird namentlich abgelehnt. Siehe Leases, die das Framework baut.
coordination.lease.ttl(ungesetzt)Lease-TTL für das gesamte Deployment. Liefert kein Leaf aus — ein Wert hier würde ttlMs für jeden Lease im Prozess setzen und die Prüfung „ttlMs ist Pflicht” unerreichbar machen.
coordination.lease.renewal-interval(ungesetzt)Wie oft ein gehaltener Lease erneuert wird. Liefert kein Leaf aus — ungesetzt wählt ein Drittel der TTL mit Untergrenze (100 ms In-Memory, 500 ms Kubernetes), gedeckelt auf die halbe TTL, damit ein Renewal immer vor dem Ablauf des Records drankommt, und 0 kann nicht „leite es ab” heißen, weil der Validator es ablehnt.
coordination.lease.kubernetes.namespace(ungesetzt)Namespace, in dem das Lease-Objekt liegt. Liefert kein Leaf aus — ungesetzt heißt „lies namespace-path aus dem ServiceAccount-Mount des Pods”, und "" wird abgelehnt.
coordination.lease.kubernetes.namespace-path"/var/run/secrets/kubernetes.io/serviceaccount/namespace"Datei, aus der der Namespace des Pods gelesen wird.
coordination.lease.kubernetes.token-path"/var/run/secrets/kubernetes.io/serviceaccount/token"Datei, aus der das Bearer-Token gelesen wird. Ein Pfad, niemals das Token.
coordination.lease.kubernetes.ca-path"/var/run/secrets/kubernetes.io/serviceaccount/ca.crt"Datei, aus der das CA-Zertifikat für das TLS-Pinning des API-Servers gelesen wird.
coordination.lease.kubernetes.token-reload-interval1mWie lange ein aus diesem Mount gelesenes Credential wiederverwendet wird, bevor die mtime der Token-Datei erneut geprüft wird. Ohne Wirkung auf ein explizites authToken.
coordination.lease.kubernetes.operation-timeout10sObergrenze für einen einzelnen Request an den API-Server.
coordination.lease.kubernetes.lease-name-max-length253Lease-Objektnamen, die länger sind, werden auf einen stabilen Kopf plus einen Hash des vollständigen Namens gekürzt. 253 ist die DNS-1123-Subdomain-Grenze, die der API-Server durchsetzt.

Der Block bedient zwei Arten von Lease. Ein Lease, den das Framework für einen Konsumenten baut, der danach fragt, liest ihn aus der Konfiguration des eigenen Nodes — siehe unten. Ein Lease, den du im Code baust, liest ihn unter den Optionen, die du an new InMemoryLease(…) / new KubernetesLease(…) übergibst, in der üblichen Reihenfolge: explizite Optionen gewinnen, dann dieser Block, dann die eingebauten Defaults. Ein solcher Lease hat womöglich kein ActorSystem in Reichweite, deshalb lädt sein Konstruktor die Config-Kette selbst und berücksichtigt dabei ACTOR_TS_CONFIG und ./application.conf — es sei denn, du übergibst ihm eine: new KubernetesLease(options, system.config) liest diese Config und sonst nichts, Overrides eingeschlossen.

Drei Keys liefern überhaupt kein Leaf aus und stehen oben nur, damit die Namen auffindbar sind. Jeder davon ist ein Feld, das der Code verlangt oder ableitet, und ein ausgelieferter Wert würde hasPath für immer wahr machen — genau so wird das, wofür er einspringt, unerreichbar. Setz einen davon in deiner eigenen application.conf und er wird ganz normal gelesen:

actor-ts.coordination.lease {
ttl = 30s
kubernetes.namespace = "actors"
}

acquire-retries und acquire-retry-delay sind hier nicht setzbar. Die beiden Backends liefern unterschiedliche eingebaute Defaults — 3 Versuche / 100 ms für Kubernetes, 1 / 50 ms in-memory —, und ein Leaf könnte beide nicht ausdrücken, ohne sie stillschweigend zu vereinheitlichen. Setz sie pro Lease im Code.

Drei Konsumenten verlangen einen Lease per Konfiguration, und alle drei bekommen ihn aus diesem Block:

SchalterLease-NameAbgelehnt, falls falsch konfiguriert, wenn
sharding.use-lease = on<system>-sharding-<type>, einer pro geshardetem Typder Typ startet
cluster.singleton.use-lease = on<system>-singleton-<type>, einer pro Singletondas Singleton startet
split-brain-resolver.active-strategy = lease-majority<system>-split-brain-resolver, einer pro Clusterder Node seinem Cluster beitritt
actor-ts.coordination.lease {
backend = kubernetes
ttl = 15s
}
actor-ts.cluster.singleton.use-lease = on

Die Datei wählt das Backend und sein Tuning, und nichts an der Identität. Der Name wird pro Konsument abgeleitet — kleingeschrieben zu einem gültigen Kubernetes-Objektnamen, mit einem Hash des Originals dahinter, wenn das ihn verändert hat, sodass OrderService und orderservice zwei Records bleiben — und in kubernetes.lease-name-max-length eingepasst. Der Owner ist der Node, der den Lease baut: seine Cluster-Adresse und seine Inkarnation, sodass ein neu gestarteter Pod die TTL seines Vorgängers abwartet, statt einen Record zu erben, auf den der Vorgänger womöglich noch handelt. Für beides gibt es keinen Key; name, owner, plugin, acquire-retries und acquire-retry-delay in diesem Block werden abgelehnt statt ignoriert, ebenso ein lease-name im Sharding- oder Singleton-Block und jeder Key unter split-brain-resolver.lease-majority.

Was außerdem abgelehnt wird, jeweils mit dem Key in der Meldung: ein Schalter, der einen Lease verlangt, während backend = none gilt, ein unbekanntes Backend, in-memory — sein Store lebt in einem Prozess oder Worker-Thread, ein daraus gebauter Lease würde also nichts absichern — und eine fehlende ttl, für die kein Default einspringen kann. Der Block selbst wird geprüft, sobald ein Node seinem Cluster beitritt, sodass ein vertipptes Backend nicht auf den ersten Konsumenten wartet, der danach fragt. Ein explizites withLease(…) gewinnt weiterhin gegen einen Schalter, und withUseLease(false) nimmt einen einzelnen geshardeten Typ oder ein einzelnes Singleton von einem deploymentweiten on aus.

Ein Backend, das genannt, aber nicht erreichbar ist — kein API-Server, kein ServiceAccount-Mount, Credentials, die der Server ablehnt —, wird beim Start nicht abgelehnt, denn aus einer Datei lässt sich das nicht erkennen. Der Konsument startet mit seinem Lease und schlägt geschlossen fehl: Jedes fehlgeschlagene Acquire wird wiederholt — Singleton-Manager und Koordinator loggen es auf warn und warten ihr acquire-retry-interval ab, lease-majority fragt bei seiner nächsten Entscheidung erneut —, und bis eines gelingt, hostet kein Node das Singleton, teilt der Koordinator keine Shards zu und kommt lease-majority zu keinem Urteil. Nichts läuft, als hielte es einen Lease, den es nicht erwerben konnte.

Die Per-Entity-lease()-Hooks der Persistence an PersistentActor und ReplicatedEventSourcedActor bleiben Code: Sie brauchen einen Lease pro Persistence-ID, und das kann ein Schalter nicht ausdrücken.

KeyDefaultZweck
cluster.bootstrap.stable-margin5sWie lange die Contact-Point-Menge unverändert bleiben muss, bevor die Observation sie stabil nennt.
cluster.bootstrap.poll-interval1sWie oft Discovery während der Observation abgefragt wird.
cluster.bootstrap.max-wait60sGesamtbudget der Observation, bevor sie aufgibt und den Bootstrap scheitern lässt.
cluster.bootstrap.required-contact-points1Wie viele Contact Points eine stabile Menge enthalten muss. 1 hält Einzelknoten-Entwicklung am Laufen; erst ein Wert, der der erwarteten Replica-Zahl entspricht, erkennt Discovery, die stabil falsch statt bloß langsam ist.
cluster.bootstrap.self-election-grace10sWie lange der niedrigst-adressierte Knoten auf eine Promotion durch einen Peer wartet, bevor er selbst einen Cluster bildet.
cluster.bootstrap.new-cluster-enabledonOb ein Knoten, der niemanden zum Beitreten findet, einen Cluster gründen darf. on ist nur für den ersten Start eines Deployments richtig, und jeder Start loggt eine Warnung, solange es an ist; setz es off, sobald der Cluster existiert. Aus wählt sich kein gebootstrappter Knoten selbst, auf keinem der beiden Pfade, und ein explizites seeds: [] wird abgelehnt — ein Knoten, der niemanden findet, scheitert an seinem Readiness-Warten, statt allein zu starten.
cluster.bootstrap.minimum-members1Wie wenige up-Mitglieder — sich selbst eingeschlossen — genügen, damit awaitReady / Cluster.isReady den Cluster als bereit zählt.
cluster.bootstrap.await-ready(nicht gesetzt)Readiness-Budget. In reference.conf nur als Kommentar: „nicht gesetzt“ wählt den berechneten Default (self-election-grace + 5s hinter der Stable Observation mit new-cluster-enabled an, sonst 5s), und ein immer vorhandener Key könnte das nicht ausdrücken.
cluster.bootstrap.discovery.method"auto"Welchen Seed-Provider der Bootstrap baut — auto, config, dns oder kubernetes. auto ist die Leiter; die anderen drei fixieren eine Sprosse, damit ein fehlkonfiguriertes Deployment laut scheitert statt durchzufallen.
cluster.bootstrap.discovery.service-name""Der DNS-Name, den der dns-Provider auflöst, und der Kubernetes-Service, dessen Endpoints der kubernetes-Provider liest. "" heißt „hier nicht angegeben“, dann antwortet CLUSTER_SERVICE_NAME.

Die fünf Observation-Timings werden nur gelesen, wenn stableObservation an ist; new-cluster-enabled, das Readiness-Paar und der discovery-Unterblock werden von jedem Cluster.bootstrap-Aufruf gelesen. Alle liegen unter den expliziten Optionen, ein withRequiredContactPoints(…), ein discovery: 'dns' oder ein withNewClusterEnabled(false) im Code gewinnt also weiterhin.

Ein method außerhalb dieser vier Namen wird abgelehnt, nicht ignoriert. Bei einem Tippfehler auf auto zurückzufallen hieße, dass ein Knoten anders entdeckt als seine Peers — genau das Cold-Start-Split-Brain, das die Observation schließen soll.

selfElection hat hier keinen Key und bekommt keinen: Der Wert unterscheidet sich konstruktionsbedingt pro Knoten, ein gemeinsamer Wert würde also entweder jeden Knoten am Start hindern oder alle gleichzeitig einen Cluster bilden lassen. new-cluster-enabled ist der gemeinsame Wert, der sicher ist: Er wählt keine Policy pro Knoten, er nimmt nur „einen Cluster gründen“ vom Tisch, also ist off auf jedem Knoten eines laufenden Clusters auf allen richtig. Siehe Cluster-Bootstrap.

KeyDefaultZweck
discovery.dns.cache-ttl60sWie lange der DNS-Provider eine aufgelöste Antwort wiederverwendet. In-Process und pro Provider; Fehlschläge werden nie gecacht. 0 schaltet den Cache ab.
discovery.dns.use-srvfalseSRV-Records statt A-Records lesen. SRV trägt einen Port pro Ziel, jede Adresse wird also mit dem Port des Records gepaart statt mit dem Remoting-Port dieses Knotens.
discovery.dns.pinned-addresses(nicht gesetzt)CIDRs (A-Record-Modus) und/oder Host-Suffixe (SRV-Modus), auf die eine aufgelöste Adresse passen muss; alles andere wird verworfen statt als Seed angeboten. In reference.conf nur als Kommentar, weil eine immer vorhandene leere Liste „kein Pinning“ nicht ausdrücken könnte — siehe unten.
discovery.kubernetes.request-timeout10sObergrenze für die eine HTTPS-Anfrage, die der Kubernetes-Provider an den API-Server stellt — eine Frist auf den ganzen Austausch einschließlich TLS-Handshake, damit ein Server, der die Verbindung annimmt und nie antwortet, den Lookup scheitern lässt, statt den Bootstrap hängen zu lassen.
discovery.kubernetes.namespace(nicht gesetzt)Namespace, dessen Endpoints-Objekt der Kubernetes-Provider liest. In reference.conf nur als Kommentar, aber aus einem anderen Grund als die Pin-Listen: Unter diesem Key liegt CLUSTER_NAMESPACE, ein veröffentlichter Wert wäre also auf jedem Knoten die Config-Schicht und die Variable damit unerreichbar. Nicht gesetzt lautet die Kette: dieser Key, dann die Variable, dann das eingebaute "default".
discovery.kubernetes.pinned-addresses(nicht gesetzt)CIDRs, in die die gefundenen Pod-IPs fallen müssen. Nur CIDRs — Endpoints lösen zu IPs auf, ein Host-Suffix könnte nie passen. Nur als Kommentar, aus demselben Grund.
discovery.config.seeds(nicht gesetzt)Statische [system@]host:port-Liste — die erste Sprosse der auto-Leiter und das Ganze von method = "config". Eine Deployment-Topologie: Eine Liste ist auf jedem Knoten richtig, wenn sie den designierten ersten Knoten unter der Adresse nennt, die er ankündigt; eine Liste, die jeden Knoten nennt, startet ohne stableObservation nie kalt. Nur als Kommentar, aus einem Präzedenz-Grund: Unter dem Key liegt CLUSTER_SEEDS, und schon ein veröffentlichtes [] brächte die Variable zum Schweigen — [] lässt diese Sprosse weg, statt „nicht gesetzt“ zu bedeuten, und method = "config" lehnt es ab.

Top-level statt unter cluster.*, aus demselben Grund wie distributed-data: Das Modul ist es. Ein SeedProvider wird gebaut und dann an den Cluster übergeben, und dieselben Provider bedienen ein von Hand verdrahtetes Cluster.join, das nie bootstrappt. Welcher Provider läuft, steht ebenfalls nicht hier — das ist cluster.bootstrap.discovery.method oben, eine Eigenschaft des Joins statt des Providers, damit ein Deployment die DNS-Antwort fixieren kann, ohne zugleich die Leiter festzulegen.

Eine statische Seed-Liste hat zwei Orte, und die Reihenfolge zwischen ihnen steht fest. Unter Cluster.bootstrap läuft zuerst die Discovery, und was sie liefert, wird weitergereicht — discovery.config.seeds oder, wenn die Datei keine nennt, CLUSTER_SEEDS, beides Sprossen dieser Leiter —, ein gefundener Seed gewinnt also, und cluster.seed-nodes greift nur, wenn die Discovery niemanden oder nur diesen Knoten genannt hat. Ein explizites seeds: [] an Cluster.bootstrap gewinnt über beide, solange new-cluster-enabled es überhaupt zulässt. Beide Listen schreibt man gleich: den designierten ersten Knoten nennen und eine Datei überall ausliefern. Eine Liste, die jeden Knoten nennt, ist an beiden Orten die symmetrische Falle.

Discovery ließ sich immer schon über CLUSTER_SEEDS, CLUSTER_SERVICE_NAME und CLUSTER_NAMESPACE steuern. Diese Variablen behalten ihre Bedeutung und sind unter diesen Block gerückt, nicht darüber:

explizite Optionen > actor-ts.discovery.* > CLUSTER_* > eingebaute Defaults

Das ist die gewöhnliche Precedence des Frameworks mit den Umgebungsvariablen am unteren Ende, keine vierte Schicht obendrauf. Ein Deployment, das nur Umgebungsvariablen benutzt, verhält sich also exakt wie vor diesen Keys, und eine application.conf kann jetzt eine Variable überschreiben, die sie vorher gar nicht erreichte.

Diese letzte Aussage betrifft reference.conf genauso wie die Reihenfolge, und sie entscheidet, welcher dieser Keys überhaupt einen Wert ausliefern darf. Das Vorhandensein ist die Lesung — ein veröffentlichtes Leaf ist ein konfigurierter Wert auf einem Knoten, der nichts konfiguriert hat. Ein Key mit einer CLUSTER_*-Variablen darunter wird deshalb nur als Kommentar ausgeliefert: discovery.kubernetes.namespace und discovery.config.seeds; cluster.bootstrap.discovery.service-name löst dasselbe Problem andersherum, veröffentlicht als "" und von seinem Reader verworfen. cache-ttl, use-srv und kubernetes.request-timeout tragen veröffentlichte Werte, weil unter ihnen nichts liegt, das sie verdecken könnten.

Ein Deployment, das eine Variable über die eigene application.conf stellen will, hebt sie selbst dorthin:

actor-ts.cluster.bootstrap.discovery.service-name = ${?CLUSTER_SERVICE_NAME}
actor-ts.discovery.kubernetes.namespace = ${?CLUSTER_NAMESPACE}

Das ist ein Lesevorgang beim Parsen (siehe Environment-Substitution), keine Precedence-Schicht — der Wert landet in derjenigen Config-Schicht, zu der die Datei gehört, und ab da gilt die übliche Reihenfolge.

KeyDefaultZweck
remote.tcp.host(ungesetzt)Das Interface, auf dem gebunden wird. Wird gelesen, wenn die Optionen host nicht setzen. In der reference.conf nur als Kommentar: Auf dem Cluster.bootstrap-Pfad liegen CLUSTER_HOST / POD_IP / HOSTNAME darunter, und ein ausgelieferter Wert machte sie unerreichbar. Ungesetzt geht die Kette über diese Variablen (nur beim Bootstrap) weiter zum eingebauten "0.0.0.0" — ein Wildcard gehört hierher und ist der Default.
remote.tcp.advertised-host(ungesetzt)Die Adresse, die Peers wählen — die Identität dieses Nodes. Ungesetzt folgt sie remote.tcp.host, sofern der routebar ist, dann CLUSTER_HOST / POD_IP / HOSTNAME, dann Loopback. Ein Wildcard wird abgelehnt. Bewusst nicht in der reference.conf, denn genau von einem ausgelieferten Wert müsste sich „ungesetzt” unterscheiden lassen.
remote.tcp.port(ungesetzt)Der Port, auf dem gebunden wird. Wird gelesen, wenn die Optionen port nicht setzen. Aus demselben Grund nur als Kommentar, mit CLUSTER_PORT darunter auf dem Bootstrap-Pfad; der eingebaute Default ist 2552.
remote.tcp.advertised-port(ungesetzt)Der Port, den Peers wählen. Ungesetzt bedeutet dasselbe wie remote.tcp.port — setz ihn nur dort, wo das Deployment den Prozess auf einem anderen veröffentlicht. Aus demselben Grund wie advertised-host nicht in der reference.conf.
remote.max-frame-bytes16MWire-Cap pro Frame. Ein Frame, dessen Längen-Präfix darüber liegt, wird verworfen, bevor irgendeine Payload gepuffert wird.
remote.tls.enabledfalseNicht umgesetzt — true bringt eine Startup-Warnung, keine Verschlüsselung. Siehe unten.
remote.untrusted-modefalseEin eingehendes Envelope nur annehmen, wenn trusted-selection-paths sein Ziel nennt. Aus ist jeder /user-Aktor namentlich adressierbar — genau das lässt eine ActorRef über Knoten hinweg funktionieren. /system wird in beiden Fällen abgelehnt. Siehe unten.
remote.trusted-selection-paths[]Pfade, die ein Peer namentlich adressieren darf, solange untrusted-mode an ist. Leer heißt: nichts über die Framework-Endpunkte hinaus, die dieser Knoten registriert hat.
remote.handshake-timeout5sWie lange eine Verbindung ohne ihre Hälfte des Handshakes bestehen darf, bevor sie abgeräumt wird. Ein Wert für beide Richtungen — siehe unten.
remote.connect-timeout(ungesetzt)Wie lange ein Dial zum Aufgehen brauchen darf — der TCP-Connect und über TLS der TLS-Handshake —, bevor er abgebrochen und als einer geloggt wird, der nicht verbinden konnte. Ungesetzt ist er remote.handshake-timeout, das er nicht überschreiten darf. In reference.conf nur als Kommentar, damit „ungesetzt” ausdrückbar bleibt — siehe unten.
remote.outbound-queue-size1000Wie viele Frames für einen Peer gehalten werden, der sie gerade nicht annehmen kann; die ältesten fallen zuerst weg.
remote.max-inbound-connections1024Wie viele eingehende Verbindungen dieser Knoten annimmt, bevor er Sockets rundheraus ablehnt — abgelehnt wird die neueste, nicht die älteste verdrängt.
remote.incomplete-frame-idle30sWie lange eine Verbindung ein halb empfangenes Frame halten darf, ohne dass ein weiteres Byte eintrifft. Eine Stall-Schranke, bei jedem Chunk neu gestellt.

host/port sind das Bind-Paar, advertised-host/advertised-port das Identitäts-Paar: das erste sagt, wo der Listener aufmacht, das zweite, was in jedes Gossip-Frame wandert, damit Peers zurückwählen können. Sie sind dieselben Werte, bis ein Deployment einen davon umbiegt — deshalb erledigt ein routebarer Host plus ein Port weiterhin beide Jobs und nichts, was heute konfiguriert ist, bewegt sich.

Beide Einstiegspunkte lesen das Bind-Paar aus der Config — Cluster.join und Cluster.bootstrap gleichermaßen —, also kann ein Deployment es komplett aus dem Code herausziehen:

actor-ts.remote.tcp {
host = "0.0.0.0"
port = ${?ACTOR_TS_PORT} # Env-Var-Substitution
}

Auf dem Cluster.bootstrap-Pfad liegen die Umgebungsvariablen unter diesem Block — die Reihenfolge, die actor-ts.discovery schon verwendet:

explizite Optionen > actor-ts.remote.tcp.* > CLUSTER_HOST / POD_IP / HOSTNAME, CLUSTER_PORT > 0.0.0.0, 2552

Ein Port in der Datei gewinnt also gegen CLUSTER_PORT, und die Variable antwortet weiterhin auf einem Node, dessen Datei keinen nennt — ist oben ACTOR_TS_PORT ungesetzt, fällt port heraus und CLUSTER_PORT entscheidet. Deshalb liefert die reference.conf keines der beiden Leaves aus: Ein veröffentlichter Wert wäre auf jedem Node die Config-Schicht. Cluster.join fragt für das Bind-Paar keine Variable ab; es nimmt seine Optionen, dann diesen Block, dann das eingebaute Paar.

Ein veröffentlichter Container-Port ist der Fall, der alle vier braucht. Der Prozess lauscht im Container auf 2552, docker run -p 3000:2552 legt ihn draußen auf 3000, und 3000 ist die Zahl, die in die Seed-Liste jedes anderen Nodes gehört:

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
}

Unter Kubernetes bewegt sich nur die Host-Hälfte: Pod-zu-Pod-Gossip wählt den Container-Port direkt, also ist advertised-host = ${?POD_IP} allein schon die ganze Konfiguration.

remote.max-frame-bytes gilt für den Transport, den der Cluster sich selbst baut. Wenn du einen TcpTransport selbst konstruierst und per withTransport(…) übergibst, setz das Cap dort — das Framework re-capped keinen Transport, den es nicht erzeugt hat.

Ein eingehendes envelope-Frame trägt den Zielpfad, den der Absender gewählt hat, und der Knoten löst ihn gegen seinen eigenen Aktor-Baum auf. Das ist das eine, was eine Gegenstelle auf der Cluster-Verbindung frei wählt, und die beiden Keys oben sind der Rahmen darum.

/system gehört nicht zu diesem Rahmen. Die Aktoren des Frameworks — Shard- Coordinators und -Regions, Singleton-Manager, der PubSub-Mediator, das DistributedData-Replikat, beide DevTools-Lanes — sind ausschließlich über den Pro-Pfad-Handler erreichbar, den jeder von ihnen registriert, in beiden Modi. Diese Tür heftet die Identität der Verbindung an das Frame; die namentliche Pfadauflösung hat das nie getan, weshalb ein so zugestellter Body überhaupt keinen Absender hatte. Das ist eine Verhaltensänderung: davor konnte jeder, der ein hello abgeschlossen hatte, sie adressieren (Issue #964).

untrusted-mode engt die andere Hälfte ein. Aus — der Default — darf ein Peer jeden /user-Aktor benennen, was genau das ist, was eine aus einer Wire-Ref rekonstruierte RemoteActorRef tut und was eine ActorRef über Knoten hinweg überhaupt brauchbar macht. An gelten nur die Pfade, die du auflistest:

actor-ts.remote {
untrusted-mode = true
trusted-selection-paths = ["/user/orders/*", "/user/reporting/intake"]
}

Ein Eintrag ist ein exakter Pfad, außer er endet auf /* — dann ist er dieser Pfad und alles darunter. Das Suffix ist segmentverankert: /user/orders/* lässt /user/orders/7 zu und lehnt /user/orders-archive ab. Sonst ist hier nichts ein Muster, und ein * irgendwo anders als als ganzes letztes Segment wird beim Start abgelehnt statt literal gematcht. Pfade werden guardian-verwurzelt geschrieben, so wie der Baum sie rendert; der führende / ist optional.

Schalte den Modus dort an, wo das Cluster-Netz eine Grenze überschreitet, die du nicht kontrollierst — dieselben Netze, in denen sich auch remote.max-frame-bytes zu senken lohnt. Der Preis ist, dass jeder namentlich adressierte Aktor aufgelistet sein muss, auch die, die über eine gewanderte Ref erreicht werden; fang deshalb damit an, auf einem Knoten mit angeschaltetem Modus und einer für vollständig gehaltenen Allow-List cluster_envelope_refusals_total{reason="not-allow-listed"} zu beobachten.

Ablehnungen werden gezählt statt einzeln geloggt: ein Envelope ist sein eigenes Frame, eine Zeile pro Ablehnung ließe einen Peer also das Log dieses Knotens im Nachrichtentakt schreiben. Die erste Ablehnung je Grund wird als WARN geloggt, weitere werden zu höchstens einer Zeile pro 30 Sekunden gefaltet, die den Peer der Verbindung nennt und nie den angefragten Pfad.

Dieselbe Regel gilt für ClusterClientReceptionist, und das ist die stärker exponierte der beiden Nahtstellen: ein ClusterClient ist dem Membership-Ring nie beigetreten. Ein abgelehnter Pfad wird mit demselben path not found beantwortet, das der Client für einen nicht existierenden Pfad bekommt — der Endpunkt taugt also nicht dazu, den Aktor-Baum zu kartieren.

Vier der letzten fünf Keys begrenzen, was eine Gegenstelle, die eine TCP-Verbindung zum Cluster-Port aufbauen kann, diesen Knoten halten lassen darf. Alle vier werden durchgesetzt, seit der Transport gehärtet wurde; neu ist nur, dass sie einstellbar sind (Issue #846). Der fünfte, connect-timeout, begrenzt stattdessen die eigenen Dials dieses Knotens und wird weiter unten beschrieben:

actor-ts.remote {
handshake-timeout = 5s
outbound-queue-size = 1000
max-inbound-connections = 1024
incomplete-frame-idle = 30s
}

handshake-timeout deckt eine Verbindung ab, die ihre Hälfte des Handshakes nie spricht — einen Dial, der nie sein hello-ack bekommt, und einen angenommenen Socket, der nie ein hello schickt. Es ist bewusst ein Key für beide Richtungen. Die Uhr der wählenden Seite startet vor dem TCP-Connect und dem TLS-Handshake, die der annehmenden Seite erst nach dem Accept — mit einer Zahl hat der Peer, der es noch versucht, also immer zuerst aufgegeben, und die annehmende Seite kann nie die Frist sein, die einen langsamen, aber legitimen Dial bestraft. Ein getrenntes Dial-/Accept-Paar würde erlauben, die Accept-Frist unter die Dial-Frist zu setzen und damit einen gesunden Peer dauerhaft unerreichbar zu machen — ohne dass in irgendeinem Log stünde, warum.

connect-timeout ist nicht dieses getrennte Paar: Es begrenzt nur, wie lange ein eigener Dial dieses Knotens zum Aufgehen brauchen darf — der TCP-Connect und bei einem TLS-Dial der TLS-Handshake —, unter der Handshake-Frist, die weiterhin den ganzen Dial begrenzt (Issue #1475). Ein Dial, der bis dahin nicht aufgegangen ist, wird abgebrochen und als could not connect to … within N ms geloggt; einer, der aufgegangen ist, endet über handshake-timeout, und seine Zeile sagt connected to …, but no hello-ack came. Setze ihn unter handshake-timeout, um früher zu erfahren, dass ein Peer nicht da ist, während ein langsamer weiterhin die ganze Handshake-Frist zum Antworten bekommt:

actor-ts.remote {
handshake-timeout = 5s
connect-timeout = 2s
}

Er wird nur als Kommentar ausgeliefert, in der Form von tcp.advertised-host: ungesetzt heißt „dasselbe wie handshake-timeout”, die eine Frist, die ein Dial vor dem Key hatte. Er darf handshake-timeout nicht überschreiten — beide Validatoren lehnen das ab, ein einzelnes connect-timeout = 10s gegen den Default von 5 s —, und ein eigener ausgelieferter Wert hätte jedes handshake-timeout darunter abgelehnt: Den einen Key zu senken, den ein Betreiber schon kennt, kann so nie eine Regel über einen Key auslösen, den er nie geschrieben hat.

incomplete-frame-idle deckt die andere Hälfte ab: eine Verbindung, die gesprochen hat und dann mitten im Frame verstummt ist. Es ist eine Stall-Schranke, kein Budget für das Frame — sie wird bei jedem Chunk neu gestellt, ein Peer, der ein großes Frame über eine verstopfte Leitung schiebt, wird also nie für seine Langsamkeit bestraft, nur fürs Aufhören. Halte sie über handshake-timeout; beide Validatoren lehnen einen Wert darunter oder darauf ab, denn ein Socket, der überhaupt nichts sendet, erreicht diese Frist nie — dafür ist der Handshake-Timer da. Verglichen wird das aufgelöste Paar, nicht das geschriebene: Steht nur einer der beiden Keys in der Config, wird er gegen den eingebauten Default des anderen geprüft. Ein einzelnes incomplete-frame-idle = 1s wird also abgelehnt, weil es unter dem handshake-timeout von 5 s liegt, gegen das es liefe.

max-inbound-connections verhindert, dass sich beide Kosten durch Sockets im Loop vervielfachen lassen, und ist die Hälfte der Schranke für eingehenden Decode-Speicher, die sich zu senken lohnt: diese Schranke ist dieser Zähler mal dem, was eine Verbindung puffern darf. Setz ihn nach der echten Peer-Zahl, wo du sie kennst — eine eingehende Verbindung je Peer im Vollmesh, plus die ClusterClients, die sich einwählen — und lass Luft, denn einen legitimen Peer abzulehnen ist eine Partition. Abgelehnt wird die neueste Verbindung statt die älteste verdrängt; Verdrängung ließe einen Angreifer etablierte Peers vom Knoten schieben.

outbound-queue-size ist der einzige Key hier, der begrenzt, was dieser Knoten hält, statt was ein Peer gegen ihn hält: Frames, die für einen Peer geschrieben wurden, der sie gerade nicht annehmen kann; die ältesten fallen zuerst weg, denn der neueste Membership- und Heartbeat-Stand ist der, den zu behalten sich lohnt. Heute ist das der Puffer vor dem Handshake, damit ein tell, das mit dem Handshake um die Wette läuft, gehalten statt verloren wird. Der Key ist nach der Kategorie benannt, nicht nach diesem einen Puffer: die Backpressure-Queue nach dem Handshake (Issue #931) ist dieselbe Größe mit derselben Policy und derselben Warnung und landet unter diesem Key statt unter einem zweiten.

Keiner der fünf hat eine „Aus”-Schreibweise. 0 wird für jeden abgelehnt, weil es keine Art ist, eine Schranke zu entfernen, sondern jeweils eine eigene Art, den Knoten kaputtzumachen: kein Handshake-Fenster, keine Zeit, in der ein Dial aufgehen kann, kein Platz zum Puffern, keine eingehende Verbindung angenommen, keine Verbindung, die auf einer Frame-Grenze enden darf.

Diese Werte erreichen den Transport, den der Cluster sich selbst baut. Ein TcpTransport, den du selbst baust und per withTransport(…) übergibst, trägt seine eigenen — setz sie in dessen TcpTransportOptions.

KeyDefaultZweck
http.backend"fastify"Einer von fastify / express / hono.
http.shutdown-grace-period0msWie lange unbind() in-flight Requests leerlaufen lässt, bevor Verbindungen erzwungen geschlossen werden. 0 erzwingt sofort.
http.server(siehe unten)Verbindungsschranken für den lauschenden Socket selbst.
http.cors(siehe unten)Pro-Route-Defaults für die cors()-Direktive.
http.hsts(siehe unten)Die Policy, die die Middleware hsts() sendet.
http.request-timeout(siehe unten)Die Handler-Frist der Middleware requestTimeout() — nicht http.server.request-timeout.
http.client(siehe unten)Defaults des ausgehenden HttpClient.
http.websocket(siehe unten)Serverseitige WebSocket-Defaults für websocket()-Routen.

http.backend entscheidet nur darüber, was newServerAt(...).bind() verwendet, wenn der Builder kein eigenes Backend bekommen hat — useBackend(new HonoBackend()) gewinnt immer und bleibt der einzige Weg, ein selbst konfiguriertes oder selbst geschriebenes Backend zu übergeben. Ein unbekannter Name lässt bind() mit einem ConfigError scheitern, statt still auf Fastify zurückzufallen. Express und Hono sind optionale Peer-Dependencies und werden nur importiert, wenn du sie benennst.

Die Grace Period ist per Default 0 — sofort erzwingen —, weil unbind() genau das in der Praxis immer getan hat. Erhöhe sie, wenn in-flight Requests fertig werden sollen.

Meist ist sie eine Obergrenze und keine Wartezeit: unbind() kehrt zurück, sobald der Server tatsächlich geschlossen ist. Wo das close() eines Backends nicht settlen kann — etwa Express mit einem lebenden WebSocket — wird das Fenster zu einer Deadline, die immer erreicht wird; ein großer Wert ist dort also Zeit, die du immer bezahlst. Ein Aufrufer, der einen eigenen Wert übergibt — binding.unbind(1_000) — überschreibt die Config.

Die Schranken einer Verbindung — im Gegensatz zu einer Route darauf — kommen aus actor-ts.http.server:

KeyDefaultZweck
http.server.idle-timeout(das des Backends)Wie lange eine untätige Verbindung gehalten wird, bevor sie geschlossen wird — eine Keep-Alive-Verbindung unter HTTP/1.1 zwischen zwei Requests, und eine HTTP/2-Session, auf der sich nichts bewegt. Hat kein Blatt — siehe unten. 0 schaltet ihn ab — auf dem Hono-Backend unter Bun ist er aber die einzige Schranke für einen Request, dessen Body nicht mehr weiterkommt, und eine solche Verbindung bleibt dann offen, bis der Client sie schließt (§ unten). Höchstens 2147482647 ms — auf dem Hono-Backend unter Bun, wo er weiter greift, höchstens 255s (§ unten).
http.server.header-timeout60sWie lange eine Verbindung brauchen darf, um ihren vollständigen Header-Block zu liefern, bevor sie mit 408 beantwortet und zerstört wird. Der Slowloris-Schutz, den actor-ts selbst hält — siehe unten. Ein kürzerer request-timeout ist zugleich die Header-Deadline: die Absicherung läuft mit dem kleineren der beiden Werte. 0 schaltet ihn ab. Höchstens 2147483647 ms.
http.server.request-timeout300sWie lange eine Verbindung brauchen darf, um einen Request vollständig zu liefern — Header und Body. Begrenzt das Empfangen, nie das Antworten — die Frist eines Handlers ist http.request-timeout. Ist er kürzer als header-timeout, begrenzt er auch die Header-Phase, denn die Header gehören zum Request. Höchstens 4294967295 ms.
http.server.max-connections(unbegrenzt)Gleichzeitige Verbindungen, die der lauschende Socket annimmt, bevor er neue schließt. Hat kein Blatt — siehe unten.
http.server.max-content-length(die des Backends)Der größte angenommene Request-Body in Bytes; ein größerer wird mit 413 beantwortet, bevor der Handler läuft. Wird als Größe gelesen (8MiB). Hat kein Blatt — siehe unten.
http.server.max-header-bytes(die der Runtime)Der größte angenommene Header-Block eines Requests in Bytes; ein größerer erreicht keinen Handler. Wird als Größe gelesen (16KiB). Hat kein Blatt — siehe unten.

Die übliche Reihenfolge gilt pro Feld: newServerAt(...).withServerOptions(...) gewinnt, dann dieser Block, dann der eingebaute Default. Aufgelöst wird einmal bei bind(), bevor das Backend gebaut wird. Die Timeouts und max-connections werden bei listen() auf dem Server installiert; sie erreichen ein Backend, das du selbst gebaut und an useBackend(...) übergeben hast, deshalb genauso wie das, das das Framework baut. Die beiden Größengrenzen stehen — wie tls und http2 — fest, wenn der Server gebaut wird: das Framework baut sein Backend mit ihnen, und ein Backend, das du selbst gebaut hast, muss sie mitbringen. Ein von Hand gebautes FastifyBackend übernimmt sie nur über new FastifyBackend(fastifyFactoryOptions(serverOptions)), und bind() lehnt ein Backend ab, dessen eigene Grenze von einem gesetzten Key abweicht — Fastifys bodyLimit oder die Header-Grenze seines Servers, withMaxBodyBytes bei Express oder Hono —, statt unter einer der beiden Zahlen zu laufen. Eine gleiche Grenze bindet, und ein ungesetzter Key lehnt nichts ab.

Die drei Dauern werden bei bind() oberhalb dessen abgelehnt, was die Runtime dort halten kann, wo der jeweilige Wert landet, denn darüber käme eine Deadline, die als „praktisch nie“ gemeint ist, zu kurz heraus. header-timeout und idle-timeout landen in einem Timer, der alles über 2147483647 ms als 1 ms scharf stellt; idle-timeout endet eine Sekunde darunter, bei 2147482647 ms, weil beide Runtimes ihm eine Sekunde aufschlagen. request-timeout landet im Verbindungs-Sweep von Node, der ihn als 32-Bit-Zahl liest; seine Obergrenze ist deshalb 4294967295 ms. HOCON erreicht beide in einer Zeile: 30d sind 2 592 000 000 ms, jenseits der Grenze des Timers, und 60d liegt jenseits der des Sweeps.

actor-ts.http.server {
idle-timeout = 5s
request-timeout = 30s
max-connections = 10000
max-content-length = 8MiB
}

Vier Blätter liefern keinen Wert und stehen oben nur, damit die Namen auffindbar sind — aus demselben Grund wie bei vier der CORS-Blätter: ein veröffentlichtes Literal wäre eine Zahl, die niemand gewählt hat.

idle-timeout behält ungesetzt das, was das Backend gewählt hat, und die Backends sind sich absichtlich uneinig: 72 s bei Fastify gegen die 5 s von node:http bei Express und bei Hono-über-Node. Fastifys Wert ist hoch, damit der Server das Idle-Fenster eines Load Balancers überlebt und der Balancer nie einen Request auf einen Socket schickt, der gerade schließt; fünf Sekunden sind die der Plattform. Keiner von beiden ist falsch, also kürt der Block keinen Sieger. Setz ihn, wenn sie sich einig sein sollen. Hono unter Bun ist das eine Backend, das nicht das Eigene seiner Runtime behält: Buns 10 s schnitten langsame Handler ohne Antwort ab, dort wird ein ungesetztes idle-timeout deshalb aus der Request-Deadline abgeleitet — per Default 36 s (§ oben).

Er begrenzt auch eine untätige HTTP/2-Session, und request-timeout das Empfangen eines HTTP/2-Streams. keepAliveTimeout und requestTimeout, die sie zu einer HTTP/1.1-Verbindung tragen, sind Properties, die keine HTTP/2-Session und kein HTTP/2-Stream liest; auf einem Listener mit http2 betreibt actor-ts deshalb eigene Timer: eine Session, die idle-timeout lang keinen offenen Stream hatte, wird mit einem GOAWAY geschlossen — derselbe Wert auf beiden Runtimes, und ein PING-Frame setzt nichts zurück —, und ein Stream, dessen Request bei request-timeout noch eintrifft, wird mit 408 beantwortet und zurückgesetzt. Ein laufender Stream hält seine Session; ein langsamer Handler, ein Long Poll und ein SSE-Stream überdauern die Idle-Schranke also wie unter HTTP/1.1, und ein vollständig empfangener Request wird von der Empfangs-Deadline nie gekappt. Ungesetzt bleibt eine untätige HTTP/2-Session Fastifys eigenem Session-Timer überlassen — 72 s auf Node, 144 s auf Bun, das ihn beim doppelten Wert feuern lässt und von einem PING zurücksetzen lässt —, auf Hono über Node gar keiner Schranke. Auf Bun begrenzt der HTTP/2-Listener eine Verbindung, die auf demselben Port HTTP/1.1 aushandelt, mit keinem der beiden Keys; dort werden beide als nur für HTTP/2 wirksam gemeldet, und bind() warnt. Nichts davon betrifft das Hono-Backend unter Bun, dessen Sessions die eigene verbindungsweite Schranke von Bun.serve hält (§ oben), gesetzt oder abgeleitet: eine untätige Session wurde dort innerhalb eines Takts nach einem Wert von 4s geschlossen (bun 1.4.2), und ein schweigender Stream überdauert sie nicht.

max-connections ist ungesetzt unbegrenzt — das, was jedes Release vor diesem Key getan hat. Der Wert gilt serverweit, anders als das http.websocket.max-connections weiter unten, das pro Route gilt: er zählt jede Verbindung, die der Prozess auf diesem Binding annimmt — WebSocket-Upgrades eingeschlossen, und ein angehängter DevTools-Server ebenso, denn DevTools bindet über denselben system.http(...)-Pfad.

max-content-length behält ungesetzt die eigene Body-Grenze jedes Backends — das 1 MiB, das jedes mitgelieferte Backend anlegt, oder das, was withMaxBodyBytes (Express, Hono) oder bodyLimit (ein selbst gebautes Fastify) festgelegt hat. Gesetzt ist der Wert die Grenze auf jedem Backend und jeder Runtime: jedes Backend zählt die Bytes eines Bodys in eigenem Code, ein angekündigtes Content-Length darüber wird also abgelehnt, bevor ein Byte gelesen ist, und ein Chunked-Body wird abgebrochen, sobald er sie überschreitet — 413 in beiden Fällen, bevor der Handler läuft. Ein Backend, das mit einer anderen eigenen Grenze gebaut wurde, wird bei bind() abgelehnt, mit beiden Zahlen in der Meldung; eine Regel, welche von zwei Zahlen gewinnt, gibt es nicht, denn jede Antwort ließe eine davon still unbeachtet.

max-header-bytes behält ungesetzt die Grenze der Runtime: 16 KiB bei node:http, und auf Bun das prozessweite --max-http-header-size, ebenfalls 16 KiB, sofern der Prozess nicht mit einem anderen Wert gestartet wurde. Gesetzt erreicht ein Request mit größerem Header-Block keinen Handler — node:http antwortet mit 431, ein Client, der noch schreibt, während der Server aufgibt, sieht stattdessen vielleicht einen Reset. Es ist eine Option, die ein Server bekommt, wenn er gebaut wird; sie erreicht ihn also nur dort, wo actor-ts ihn baut: über Fastifys Factory-Optionen, den node:http-Server, von dem Express bedient wird, und die serverOptions von @hono/node-server — wo das eine Lücke lässt, sagt die Tabelle oben.

request-timeout wird von einem periodischen Sweep durchgesetzt, dessen Intervall connectionsCheckingInterval von http.createServer ist — 30 s per Default, und eine Factory-Option, die actor-ts nicht setzt. Eine Verbindung wird also nicht früher als beim hier gesetzten Wert geschlossen und nicht später als einen Sweep danach — gemessen auf bun 1.4.0: ein request-timeout von 2s schloss einen hängenden Body nach 30,0 s. Was der Peer erfährt, hängt vom Backend ab. Ein blanker node:http-Server antwortet vor dem Schließen mit 408; das Default-Backend Fastify schließt unter Bun ganz ohne Statuszeile, denn Fastifys clientError-Handler schreibt sein 408 und zerstört den Socket danach, und auf bun 1.4.2 liefert ein Handler dieser Form nichts aus. header-timeout wird nicht gesweept, denn nicht die Runtime setzt ihn durch: er feuert beim hier gesetzten Wert.

Beide liefern die Zahl, die http.createServer ohnehin verwendet — das Veröffentlichen hat also keine Schranke geändert, die ohnehin schon gehalten wurde. Fastify setzt requestTimeout aber auf 0, also gar keine Schranke; auf dem Default-Backend ist die veröffentlichte 300s damit eine Deadline, wo vorher keine war. Bei der 1-MiB-Body-Grenze ist das ein Client mit unter 3,5 KB/s; erhöhe sie, wenn du berechtigterweise langsamere Uploads annimmst, oder setz 0, um auszusteigen.

header-timeout = 0 steigt komplett aus dem Slowloris-Schutz aus: es wird keine Deadline scharf gestellt und die Property wird geleert. Eine Runtime kann trotzdem von sich aus auflegen — bun 1.4.0 verwirft eine Verbindung ohne vollständigen Request nach etwa 12 s, was hier auch stehen mag —, 0 kauft also nur dort eine unbegrenzte Header-Phase, wo die Runtime eine gewährt. Der TLS-Handshake lag ebenfalls im Fenster der Absicherung; ein Handshake, der nie fertig wird, ist dann also auch Sache der Runtime: Buns HTTPS-Listener schließt ihn nach etwa 12 s, ein HTTP/2-Listener wartet dagegen auf den TLS-Handshake-Timeout — 120 s, auf bun 1.4.2 wie auf node v26.10.0.

request-timeout begrenzt nur das Empfangen — die Uhr stoppt, sobald der Request angekommen ist —, ein langsamer Handler, ein Long Poll und ein SSE-Stream bleiben also unberührt. Die Route-Middleware requestTimeout() ist die andere Hälfte und absichtlich eine andere Fläche, mit einem eigenen Key, http.request-timeout weiter unten: sie begrenzt, wie lange ein Handler zum Antworten braucht, dieser Key, wie lange ein Peer zum Fragen braucht.

Die Route-Direktive cors() liest ihre Defaults pro Feld aus actor-ts.http.cors:

KeyDefaultZweck
http.cors.origins(nicht gesetzt)Exakte Origin-Allowlist, z. B. ["https://app.example"]. Hat kein Blatt — siehe unten. Ein "*"-Eintrag wird abgelehnt.
http.cors.methods(nicht gesetzt)Access-Control-Allow-Methods. Hat kein Blatt — ungesetzt folgt es den am jeweiligen Pattern registrierten Methoden.
http.cors.allowed-headers(nicht gesetzt)Access-Control-Allow-Headers. Hat kein Blatt — ungesetzt werden die sanitisierten Request-Header geechot.
http.cors.exposed-headers[]Access-Control-Expose-Headers. [] sendet keine.
http.cors.credentialsfalseAccess-Control-Allow-Credentials: true. Verboten mit "*"-Origins.
http.cors.max-age(nicht gesetzt)Preflight-Cache-Dauer in Sekunden, als blanke Ganzzahl. Hat kein Blatt — ungesetzt wird gar kein Access-Control-Max-Age gesendet.

Es gilt die übliche Reihenfolge pro Feld: Was cors(options, routes) im Code nennt, gewinnt, dann dieser Block, dann der eingebaute Default. Ein Deployment kann die Allowlist also komplett aus dem Code herausziehen und withCredentials() dort lassen, wo es steht.

Zwei der Options-Arme sind nur im Code erreichbar und haben hier keinen Key. Der eine ist die "*"-Wildcard: withAnyOrigin() ist als ausdrücklicher Opt-in dokumentiert, und eine Config-Datei, die origins = ["*"] schreiben könnte, würde mit einer Zeile jede cors()-Route im Prozess auf jeden Origin öffnen — ein "*" in dieser Liste wird deshalb mit einem ConfigError abgelehnt, der den Key nennt. Der andere ist withOriginPredicate(...): eine Funktion hat in HOCON überhaupt keine Schreibweise.

Vier Blätter liefern keinen Wert aus und stehen oben nur, damit die Namen auffindbar sind — ein publizierter Literalwert wäre schlechter als gar kein Key. methods und allowed-headers haben Defaults, die pro Pattern bzw. pro Request berechnet werden und die eine flottenweite Liste überschreiben würde; ein ungesetztes max-age heißt, dass der Header nicht gesendet wird; und ein ausgeliefertes origins würde die Pflichtprüfung für jede Route im Prozess erfüllen und damit ein cors() ohne jede Allowlist von einem lauten Fehler in ein stilles Deny-all verwandeln. Setz sie in deiner eigenen application.conf, und sie werden ganz normal gelesen:

actor-ts.http.cors {
origins = ["https://app.example", "https://admin.example"]
max-age = 600 # Sekunden — kein Duration-String
exposed-headers = ["x-request-id"]
}

Die Werte werden auf dem gemergten Ergebnis validiert; ein falscher Wert wirft also OptionsError mit dem Feldnamen, statt als Header beim Browser zu landen, der ihn ablehnt.

Dieser Block wird beim Kompilieren des Route-Baums aufgelöst — in bind(), dem ersten Moment, in dem Baum und ActorSystem beide im Scope sind. Genau dort scheitert jetzt auch ein cors(), das weder im Code noch in der Config origins nennt, statt schon beim cors(...)-Aufruf.

Die Middleware hsts() — mit langem Namen strictTransportSecurity() — liest ihre Policy aus actor-ts.http.hsts:

KeyDefaultZweck
http.hsts.max-age15552000Wie lange ein Browser den Pin hält, in Sekunden (180 Tage) — eine blanke Ganzzahl, kein Duration-String. 0 und alles unter 86400 (einem Tag) werden hier abgelehnt; Code darf jeden Wert setzen.
http.hsts.include-sub-domainstrueincludeSubDomains senden.
http.hsts.preloadfalsepreload senden. Braucht ein max-age von mindestens einem Jahr und include-sub-domains.

Es gilt die übliche Reihenfolge pro Feld: Was hsts(options) im Code nennt, gewinnt, dann dieser Block, dann der eingebaute Default. Die gemergte Policy wird einmal validiert, wenn der Route-Baum in bind() kompiliert wird — ein withPreload() im Code über einem Jahr max-age aus diesem Block ist damit eine gültige Policy, und eine, die ihr preload nicht tragen kann, lässt bind() mit einem OptionsError scheitern, statt einen Header zu senden, den die Preload-Liste ablehnt.

actor-ts.http.hsts {
max-age = 63072000 # seconds — two years, not a duration string
preload = on
}

Ein max-age unter 86400 — einem Tag — wird mit einem ConfigError abgelehnt, der den Key und die Untergrenze nennt. 0 sagt jedem Browser, den Pin zu vergessen, und ein kürzerer Pin als ein Tag ist abgelaufen, bevor ein Besucher am nächsten Tag wiederkommt; eine Zeile in einer Config-Datei würde also jeden Client jeder hsts()-Route im Prozess entpinnen. Code darf weiterhin jeden Wert setzen, mit withMaxAge(...) — die fünfminütige erste Stufe des Ramp-ups von hstspreload.org, withMaxAge(300), und withMaxAge(0), das HSTS abschaltet, eingeschlossen.

Der Block steuert nur die Middleware hsts(). Das hsts-Feld des Bündels securityHeaders() und von withSecurityHeaders(...) ist nur im Code erreichbar, und wo beide Pfade den Header senden, gewinnt das hsts() auf Routenebene — siehe Security-Header.

Eine Middleware entsteht, bevor es ein ActorSystem gibt; hsts() trägt deshalb einen Hook, den compile() gegen diesen Block auflöst. In eine eigene Funktion verpackt — (request, next) => hsts()(request, next) — ist sie für compile() unsichtbar und sendet die Code-Optionen über den eingebauten Defaults. Gib sie so, wie sie ist, an withMiddleware(...).

Ein Wrapper verbirgt die Middleware, nicht das Ergebnis: Weicht dieser Block von dem ab, was reference.conf ausliefert, und hat ihn kein hsts() im Route-Baum gelesen — verpackt, gar nicht vorhanden oder HSTS nur über das Bündel —, schreibt bind() eine Warnung mit dem Block und der gebundenen Adresse ins Log. Nicht sehen kann es ein verpacktes hsts() neben einem anderen, das den Block gelesen hat.

Die Middleware requestTimeout() liest ihre Frist aus actor-ts.http.request-timeout:

KeyDefaultZweck
http.request-timeout.deadline30sWie lange ein Handler zum Antworten brauchen darf, bevor die Middleware für ihn mit 503 antwortet. Auf dem Hono-Backend unter Bun bestimmt er auch den Default von http.server.idle-timeout, damit die 503 geschrieben ist, bevor die Verbindung abreißt (siehe den Abschnitt http.server).

Das ist die Frist des Handlers und absichtlich nicht http.server.request-timeout von oben: jener begrenzt, wie lange ein Peer zum Senden eines Requests braucht, und nie eine Response; diese Frist beginnt, sobald der Request angekommen ist. Was requestTimeout(...) im Code nennt, gewinnt, dann dieser Block, dann der eingebaute Default — requestTimeout() ohne Argument nimmt seine Frist also von hier:

actor-ts.http.request-timeout {
deadline = 10s
}

Das Blatt ist die Kebab-Schreibweise des Felds deadlineMs ohne Einheiten-Suffix und wird als Dauer gelesen. Die Response bei Ablauf, withOnTimeout(...), ist eine Funktion und nur im Code erreichbar. Die gemergte Frist wird einmal validiert, wenn der Route-Baum in bind() kompiliert wird: Eine, die nicht positiv ist oder länger, als ein Timer halten kann (2147483647 ms, etwa 24,9 Tage), lässt bind() mit einem OptionsError scheitern — eine Runtime würde so einen Timer mit 1 ms scharf stellen und jeden Request sofort mit 503 beantworten.

Er erreicht requestTimeout() so, wie der HSTS-Block hsts() erreicht, über den Hook, den compile() auflöst, und dieselbe Warnung nennt ihn bei bind(), wenn er konfiguriert ist und nichts im Baum ihn gelesen hat.

Der gemeinsame HttpClient des Systems — und jedes newClient(...), das ein Feld offen lässt — liest seine Schranken aus actor-ts.http.client:

KeyDefaultZweck
http.client.max-response-bytes8MGrößter Response-Body, der gepuffert wird, bevor der Request abgebrochen wird.
http.client.default-timeout30sDeadline für einen Aufruf, der kein eigenes timeoutMs nennt.
http.client.redirect"follow"Was mit einem 3xx samt Location passiert — follow / error / manual.
http.client.max-redirects5Hops, die eine verfolgte Kette gehen darf, bevor der Aufruf abgelehnt wird. 0 lehnt den ersten ab.

Das ist ein Boden und keine Policy: Eine Integration übergibt ihre eigenen Schranken an newClient(...), und ein einzelner Aufruf überschreibt sie mit maxResponseBytes / timeoutMs / redirect / maxRedirects. Was der Block bringt, ist die Möglichkeit, die flottenweiten Zahlen ohne Codeänderung zu bewegen — ein Endpunkt, der doch 60 s braucht, oder ein Deployment auf einer Strecke, auf der 8 MiB die falsche Obergrenze sind, zwang bisher jeden Aufrufer weg vom gemeinsamen Client.

Jedes Blatt ist das Feld aus HttpClientOptions in kebab-case, ohne Einheiten-Suffix — die Einheit steht im Wert, also default-timeout = 30s. Die camelCase-Schreibweisen, die dieser Block früher hatte, werden beim ersten Zugriff auf die HttpExtension abgelehnt, nicht schon in ActorSystem.create, mit einem ConfigError, der beide Namen nennt, statt ignoriert zu werden: max-response-bytes ist eine Obergrenze, die ein Deployment bewusst senkt, und sie still auf den eingebauten Default zurückzusetzen wäre genau der eine Fehlermodus, den eine Umbenennung nicht haben darf.

Die Werte werden beim Lesen auf den gemergten Settings validiert; ein falscher Wert wirft also OptionsError mit dem Feldnamen, statt später mitten im Request zu scheitern. max-response-bytes und default-timeout müssen hier beide positiv sein — anders als das timeoutMs eines Requests, wo 0 der dokumentierte Weg ist, einen einzelnen Aufruf von jeder Deadline auszunehmen. Eine 0 in diesem Block würde jeden Aufruf ohne eigene Deadline entschärfen — genau der Zustand, den die Defaults verhindern sollen.

Serverseitige WebSocket-Routen (websocket(path, actorRef)) lesen ihre Defaults aus actor-ts.http.websocket:

KeyDefaultZweck
http.websocket.max-frame-bytes1MGrößter akzeptierter eingehender Frame (Bytes).
http.websocket.on-oversize-frame"close"Was passiert, wenn ein Frame das Limit überschreitet — close / drop.
http.websocket.on-invalid-message"close"Was passiert, wenn eine Nachricht nicht dekodiert werden kann — close / drop / hook.
http.websocket.max-buffered-bytes4MOutbound-Backpressure-Schwelle (Bytes).
http.websocket.on-backpressure"drop"Was passiert, wenn der Buffer überschritten wird — drop / close.
http.websocket.max-connections(unbegrenzt)Max. gleichzeitige Verbindungen pro Route; ein Upgrade darüber hinaus wird mit 1013 geschlossen.
http.websocket.max-pre-attach-frames256Eingehende Frames, die gehalten werden, während der Connection-Actor startet.
http.websocket.max-pre-attach-bytes4MBytes, die gehalten werden, während der Connection-Actor startet; jenseits einer der beiden Grenzen wird der Socket mit 1013 geschlossen.
http.websocket.accept-timeout10sWie lange ein zugelassenes Upgrade auf seinen Connection-Actor wartet, bevor der Socket geschlossen und sein max-connections-Platz freigegeben wird. Infinity schaltet den Watchdog ab und geht nur im Code, weil HOCON kein Infinity-Literal kennt — withAcceptTimeoutMs(Infinity) und ein withConfig-Overrides-Objekt erreichen es beide.
http.websocket.connection-mailbox-capacity(ungesetzt)Wie viele ausgehende Nachrichten jeder Connection-Actor einreihen darf — die Queue, in die connection.tell, sendRaw und close laufen —, bevor die Overflow-Policy Frames verwirft; close() wird nie verworfen. Ungesetzt fällt eine Verbindung wie jeder andere Anwendungs-Actor durch: auf den deployment-Eintrag, der zu ihrem Pfad passt, dann auf mailbox.default.capacity. Eine positive Ganzzahl; 0 wird abgelehnt statt als „aus“ gelesen.
http.websocket.connection-mailbox-overflow(ungesetzt)drop-head / drop-new / reject für eine volle Connection-Mailbox. Braucht eine Kapazität aus der Route oder dem Blatt darüber — eine konfigurierte, global oder pro Pfad, zählt nicht — und wird ohne sie in bind() abgelehnt. Ungesetzt fällt sie auf das mailbox-overflow des passenden Deployment-Eintrags durch, dann auf mailbox.default.overflow.

Hier gilt dieselbe Blattregel: kebab-case, Einheiten-Suffix weggelassen, und eine ausgemusterte camelCase-Schreibweise ist ein ConfigError statt einer Obergrenze, die still auf den Default zurückfiel. Gelesen und damit geprüft wird dieser Block beim bind() eines Servers mit WebSocket-Route — nicht schon beim ersten Zugriff auf die HttpExtension.

KeyDefaultZweck
reliable-delivery.producer.resend-timeout500msWie lange der Producer auf eine Bestätigung wartet, bevor er dieselbe seq erneut sendet. Ein festes Intervall, bei jedem Ausbleiben unverändert neu gestellt — es gibt kein Backoff.
reliable-delivery.producer.window-size16Flow-Control-Fenster: höchstens so viele unbestätigte Nachrichten gleichzeitig unterwegs. Weitere Sends warten im Speicher, bis eine Bestätigung einen Platz freigibt.
reliable-delivery.consumer.max-producers1024Für wie viele Producer der Consumer gleichzeitig Deduplizierungs-Zustand hält. An der Grenze wird der am längsten unbenutzte Eintrag verdrängt. 0 = unbegrenzt.
reliable-delivery.consumer.producer-idle-time-to-live5mWie lange der Deduplizierungs-Eintrag eines Producers ohne Zustellung von ihm überlebt; der Sweep läuft in genau diesem Intervall. 0 schaltet den Sweep ab.
reliable-delivery.consumer.max-out-of-order1024Wie viele Sequenzen der Consumer für einen Producer oberhalb einer offenen Lücke höchstens behält. An der Grenze wird ein Delivery abgewiesen — kein Handler-Aufruf, keine Bestätigung —, und dieser Producer steht, bis sich die Lücke schließt. Halte den Wert über der window-size jedes Producers. 0 = unbegrenzt.

Beide Blöcke liegen unter dem, was ReliableDelivery.producer(...) / ReliableDelivery.consumer(...) übergeben bekommt — ein explizites withWindowSize(…) gewinnt also weiterhin. Gelesen werden sie dort und sonst nirgends. Kein Controller kann in seinem Konstruktor Konfiguration lesen — Actor.system ist ein Getter über einen Kontext, den die Zelle erst danach injiziert —, deshalb behält ein Controller, den du selbst konstruierst und an system.spawn übergibst, seine eingebauten Defaults und sieht diesen Block nie.

0 ist die Schreibweise, mit der alle drei Consumer-Grenzen das Infinity ihrer Optionsfelder ausdrücken, denn Infinity lässt sich in HOCON überhaupt nicht schreiben: der Zahlen-Reader nimmt ein numerisches Literal, und der Duration-Parser weist einen nicht-endlichen Wert ab. Es ist dieselbe Schreibweise, die cluster.max-members und sharding.max-entities bereits verwenden. Was sie kostet, gehört klar gesagt. Die Deduplizierungs-Map ist auf eine producerId geschlüsselt, die der Sender wählt — 0 bei max-producers überlässt damit einem Peer die Entscheidung, wie viel dieser Consumer behält: ein Eintrag je verschiedener Id, nie freigegeben. 0 bei max-out-of-order tut dasselbe innerhalb eines Eintrags: ein Sender, der eine Sequenz zurückhält und die folgenden weiter schickt, lässt die Menge dieses Producers wachsen, solange er weitermacht.

max-out-of-order ist eine Untergrenze ebenso wie eine Obergrenze. Ein Producer hat window-size Sends unterwegs, wenn sich eine Lücke öffnet — eine Grenze unter dem größten Fenster eines Producers, der mit diesem Consumer spricht, lässt diesen Producer also schon an seiner allerersten Lücke stehen, ohne dass irgendetwas dahinter wartet. Die ausgelieferten 1024 lassen Platz für jedes Fenster, das ein Aufrufer plausibel konfigurieren würde.

KeyDefaultZweck
serialization.read-constraints.max-nesting-depth256Container-Ebenen, in die ein Decoder absteigt, bevor er das Payload ablehnt. Nie über die eigene Obergrenze des Encoders hinaus.
serialization.read-constraints.max-document-bytes0Obergrenze für ein Dokument vor dem Parsen — geprüft in JsonSerializer / CborSerializer und auf dem Cluster-Wire gegen das Längen-Präfix des Frames. 0 = keine eigene Obergrenze.
serialization.read-constraints.max-string-length20MObergrenze für einen CBOR-Byte-String, Text-String oder Map-Key, geprüft am Längen-Präfix, bevor die Bytes alloziert werden. 0 hebt sie auf.

Diese Grenzen binden, was dieser Knoten liest, nie was er schreibt. Ein Peer, der den Handshake abschließt, oder jeder Client, dessen Body einen Serializer erreicht, wählt die Bytes; diese Werte entscheiden, wie viel Arbeit der Prozess darauf verwendet, bevor er aufgibt. Eine Grenze zu senken macht diesen Knoten also strenger als seinen eigenen Encoder — am Wire-Format ändert sich nichts.

max-nesting-depth ist die entscheidende, denn bis dahin gab es auf der JSON-Seite überhaupt nichts: JSON.parse arbeitet in jeder von actor-ts unterstützten Runtime iterativ und akzeptiert klaglos eine Million Ebenen — die Rekursion, die überläuft, ist der eigene Tagged-Tree-Walker des Frameworks, direkt vom Cluster-Wire aus erreichbar. Der Wert darf beliebig gesenkt werden und kann nicht über 256 angehoben werden: das ist zugleich die harte Obergrenze des Encoders, und ein Knoten, der tiefer liest als er schreibt, würde ein Payload akzeptieren, das er selbst nicht erzeugen kann. Ein höherer Wert ist ein OptionsError beim Start.

max-document-bytes wird als 0 ausgeliefert, weil jeder Pfad, den das Framework selbst besitzt, bereits in Bytes begrenzt ist — remote.max-frame-bytes auf dem Cluster-Wire, das Body-Limit des Servers über HTTP. Setze den Wert dort, wo ein Serializer auf anderem Weg erreicht wird (ein Broker-Payload, eine Queue-Nachricht) und stromaufwärts niemand eine Meinung dazu hat — oder dort, wo die Byte-Grenze stromaufwärts lockerer ist als das Dokument, das du zu parsen bereit bist. Auf dem Cluster-Wire wird der Wert gegen das 4-Byte-Längen-Präfix des Frames geprüft, der Frame wird also abgelehnt, bevor sein Payload gepuffert und erst recht bevor es geparst wird; das ist der früheste Punkt im Framework, an dem er greifen kann, und früher als es den Serializern möglich ist, denn die bekommen Bytes, die es bereits gibt.

In Bytes begrenzt zu sein ist nicht dasselbe wie in Arbeit begrenzt zu sein, und die Lücke gehört benannt: in der Auslieferungskonfiguration wird ein über max-nesting-depth hinaus verschachtelter Frame erst abgelehnt, nachdem JSON.parse ihn materialisiert hat. Auf Bun 1.4 gemessen kostet ein einzelner 16-MiB-Frame aus ausbalancierten [ rund 1,0 s CPU und 260 MiB Heap, bevor die Tiefengrenze ihn meldet — etwa das Vierfache eines legitimen Frames derselben Größe, und wiederholbar für jeden Peer, der den Handshake abgeschlossen hat. remote.max-frame-bytes und max-document-bytes sind die beiden Stellschrauben, die das begrenzen. Ein Vorab-Scan des Rohpuffers würde es ohne beide schließen; er wurde gemessen und nicht ausgeliefert, weil er 18–28 % jeder Frame-Dekodierung kostet, um eine vierfache Verstärkung zu beseitigen.

max-string-length bindet nur bei CBOR, und der Default liegt bewusst über remote.max-frame-bytes: auf dem Cluster-Wire ist damit das Frame-Limit die wirksame Obergrenze und diese hier greift nie. Die Asymmetrie ist gewollt — ein CBOR-Item kündigt seine Länge an, die Ablehnung kostet also nichts und verhindert die Allokation, während JSON.parse den String längst materialisiert hat, wenn der JSON-Walker ihn sieht.

Zwei Kanten liegen bewusst außerhalb dieses Blocks. Der Persistence-PayloadCodec dekodiert Bytes, die das Framework selbst geschrieben hat; eine verschärfte Grenze würde dort wiederherstellbare Historie in unlesbare verwandeln. Und die HTTP-Body-Kante baut ihre Serializer ohne ActorSystem-Handle, über das sich die Konfiguration lesen ließe — diese Naht ist Issue #967.

KeyDefaultZweck
management.enable-leave-endpointfalsePOST /cluster/leave ausliefern (HTTP-Endpunkte).
management.enable-down-endpointfalsePOST /cluster/down ausliefern — operator-initiiertes Force-Down eines Peers.
management.enable-metrics-endpointfalseGET /metrics im Prometheus-Textformat ausliefern.
management.auth-protect-healthfalseDie auth-Middleware zusätzlich über /health und /ready legen, nicht nur über /cluster/*.
management.liveness-path"health"Einzelnes Pfadsegment, unter dem die Liveness-Probe antwortet.
management.readiness-path"ready"Einzelnes Pfadsegment, unter dem die Readiness-Probe antwortet.
management.health-checks.check-timeout1sDeadline für einen Health-Check; danach meldet dieser Check status: false, seine Geschwister melden weiterhin normal.

Das sind die Einstellungen, die managementRoutes(system, cluster, options) unter seine expliziten Optionen legt — die üblichen drei Ebenen: ein im Code gesetzter Wert gewinnt, eine Datei füllt, was der Code offen gelassen hat, und die eingebauten Defaults sind der Boden. Port und Host stehen nicht hier: die gehören zu system.http(port, { host }), nicht zum Route-Baum.

auth und ipAllowlist haben keinen Key und können auch keinen bekommen. Beides sind Middleware-Funktionen, die HOCON nicht ausdrücken kann. Der Block entscheidet also, welche Endpunkte es gibt und wo die Probes antworten — nie, wer sie erreichen darf. Eine Config-Datei kann die Zugriffskontrolle des Management-Servers damit nicht aufweichen, und genau deshalb ist es unbedenklich, die beiden mutierenden Endpunkte überhaupt per Config schaltbar zu machen.

Die beiden Probe-Pfade sind einzelne Segmente; ein Wert mit / wird beim Bauen der Routen mit einem OptionsError abgelehnt. Diese Regel ist nicht kosmetisch: path(segment, …) entfernt nur umschließende Slashes. readiness-path = "k8s/ready" würde also als ein Segment mit einem Slash darin gespeichert, auf keine URL passen und den Endpunkt lautlos verschwinden lassen. Ein Fehler beim Start ist die sichtbare Variante desselben Ausgangs.

check-timeout begrenzt einen einzelnen Check, nicht die gesamte Probe. Eine Probe aggregiert alle registrierten Checks zu einer Antwort — ohne die Deadline ist der langsamste Check die Antwortzeit, und ein Check, der nie fertig wird, ist eine Probe, die nie antwortet. Kubernetes liest das als Fehlschlag, ohne jeden Hinweis darauf, welche Abhängigkeit hängt. Nach Ablauf antwortet die Registry für diesen Check mit { name: 'unknown', status: false, detail: … }; unknown deshalb, weil der Name in genau dem Ergebnis steckt, das der Check nie zurückgegeben hat.

KeyDefaultZweck
metrics.max-series-per-family10000Wie viele verschiedene Label-Tupel eine Metrik-Familie anlegen darf; jedes weitere Tupel wird in eine einzige __overflow__-Serie gefaltet (die Kardinalitätsgrenze). Gilt für die In-Process-Registry und die prom-client-Bridge gleichermaßen. 0 schaltet die Grenze ab.
metrics.name-prefix""Präfix, das die prom-client-Bridge jedem Metriknamen voranstellt, den sie registriert, z. B. "actor_ts_". Nur die Bridge.

Gelesen werden diese Keys, wenn MetricsExtension eine Registry baut, und zwar unter den Optionen des Aufrufs, der sie baut — die üblichen drei Ebenen: ein im Code gesetzter Wert gewinnt, eine Datei füllt, was der Code offen gelassen hat, und die eingebauten Defaults sind der Boden. enable(options) nimmt die Grenze für die In-Process-Registry, enablePromClient(options) nimmt beide Leaves für die Bridge. Das freie promClientRegistry(options) liest keinen von beiden: Es bekommt kein ActorSystem, die Bridge, die es zurückgibt, verhält sich mit useRegistry installiert also genau so, wie ihre Optionen sagen.

Die Grenze erreicht auch Registries, die niemand im Code einschaltet. DevTools schaltet die Registry ohne Optionen ein, solange es angehängt ist, und das Relay eines Worker-Mesh tut dasselbe in jedem Worker — dessen System aus der effektiven Config des Main-Threads gebaut wird. Eine hier gesetzte Grenze gilt also auf jedem Thread, während eine, die dem eigenen enable(options) des Main-Threads übergeben wird, auf dem Main-Thread bleibt.

name-prefix erreicht die Bridge und sonst nichts. Die In-Process-Registry hat kein Präfix: Die Management-Route GET /metrics gibt die Stock-Metriken unter den Namen aus, die diese Seite auflistet.

Zwei Metrik-Schalter bleiben in den Blöcken des Codes, der sie bedient: management.enable-metrics-endpoint schaltet die Scrape-Route ein, und worker-mesh.metrics-relay-interval taktet das Relay, das die Registries der Worker hineinholt.

KeyDefaultZweck
tracing.tracer-name"actor-ts"Name, den der OpenTelemetry-Adapter von getTracer anfordert — der Instrumentation Scope, unter dem dein Tracing-Backend jeden Span des Frameworks ablegt.
tracing.tracer-version(nicht gesetzt)Version, die neben dem Namen an getTracer geht. In reference.conf nur als Kommentar: nicht gesetzt geht keine Version mit. Setze sie in Anführungszeichen — ein 1.0 ohne Anführungszeichen ist für HOCON eine Zahl und kommt als "1" an.
tracing.logger-name"actor-ts"Name, den der OpenTelemetry-Logger des otelLogs-Slots von getLogger anfordert — der Instrumentation Scope, unter dem dein Backend jeden Log-Record des Frameworks ablegt. Nicht logger.sinks.otlp.scope-name; siehe unten.
tracing.logger-version(nicht gesetzt)Version, die neben dem Namen an getLogger geht. In reference.conf nur als Kommentar: nicht gesetzt geht keine Version mit. Setze sie in Anführungszeichen, wie tracer-version oben.

Die beiden tracer-*-Leaves werden gelesen, wenn TracingExtension.enableOtel(options) den Tracer baut, und zwar unter den Optionen dieses Aufrufs — die üblichen drei Ebenen: ein im Code gesetzter Wert gewinnt, eine Datei füllt, was der Code offen gelassen hat, und der eingebaute Default ist der Boden. Feld für Feld: Ein im Code gesetzter Name lässt eine konfigurierte Version stehen. Das freie otelTracer(options) liest keinen von beiden: Es bekommt kein ActorSystem, der Tracer, den es zurückgibt, verhält sich mit enable(...) installiert also genau so, wie seine Optionen sagen.

Keiner der beiden Leaves erreicht einen Tracer, den du selbst gebaut hast. Ein vorgefertigter tracer in den Optionen wird so verwendet, wie er ist. Die @opentelemetry/api-Namespace und ein vorgefertigter Tracer haben gar keinen Key: Beides sind Objekte, die eine Config-Datei nicht halten kann.

Die beiden logger-*-Leaves werden gelesen, wenn das System seinen Logger aus dem otelLogs-Slot baut — ActorSystemOptions.withOtelLogs(options), bei ActorSystem.create — und zwar unter den Optionen des Slots: dieselben drei Ebenen, Feld für Feld. Das Level des Loggers steht nicht hier: Es ist das eigene level des Slots, sonst logLevel, sonst logger.level. Das freie otelLogger(options) liest keinen der beiden Leaves; ein Logger, den du damit baust und mit withLogger übergibst, verhält sich also genau so, wie seine Optionen sagen, und ein vorgefertigter logger in den Optionen des Slots wird so verwendet, wie er ist.

logger.sinks.otlp.scope-name ist eine andere Stellschraube. Sie benennt die Records, die der OTLP-HTTP-Sink selbst verschickt — ein eigener Weg zu einem Collector, der ohne OpenTelemetry-SDK auskommt —, während tracing.logger-name den Logger des Slots benennt. Die beiden begegnen sich nie: Der Slot gewinnt gegen jeden Sink, ein System, das ihn setzt, baut also gar keinen OTLP-Sink.

KeyDefaultZweck
persistence.max-concurrent-recoveries50Journal-Replays, die systemweit gleichzeitig laufen dürfen. 0 ist unbegrenzt. sharding.entity-recovery taktet eine Ebene höher das Starten der Entities; dies begrenzt, wie viele ihrer Replays gleichzeitig unterwegs sind.
persistence.recovery-timeout30sObergrenze für die gesamte Recovery eines Actors — Snapshot laden, Journal lesen, falten und die highestSeq-Abfrage, die ein vollständig kompaktierter Stream braucht; bei einem ReplicatedEventSourcedActor das Laden seines Snapshots und das Lesen seines Journals. Danach scheitert der Replay mit einem RecoveryTimeoutError — über onRecoveryFailure bei einem PersistentActor, als gescheitertes preStart bei einem ReplicatedEventSourcedActor, der keinen solchen Hook hat. 0 heißt keine Frist.
persistence.snapshot-is-optionalfalseAuf einen vollständigen Journal-Replay zurückfallen, wenn der Snapshot Store nicht antworten kann. Gilt nie für einen Actor, der integrity() oder encryption() gesetzt hat — siehe unten.
persistence.journal-breaker"persistence-journal"Id des Circuit Breakers, durch den das Journal gerufen wird; "" schaltet ihn ab. Seine Zahlen stehen unter actor-ts.circuit-breaker.persistence-journal.
persistence.snapshot-breaker"persistence-snapshot"Wie oben, für den Snapshot Store.
persistence.auto-startonJournal, Snapshot Store und Durable-State-Store, die ausgewählt sind, in der Phase persistence-start des Starts öffnen, sodass ein Plug-in, das niemand registriert hat, oder ein Store, der nicht öffnet, den Start scheitern lässt statt der ersten persistierten Nachricht. off öffnet sie bei ihrer ersten Operation. withPersistence({ behavior }) gewinnt darüber, und ein WorkerMesh-Worker läuft immer mit abgeschaltetem Wert — siehe Stores beim Start öffnen.
persistence.journal.plugin"...in-memory"Voll qualifizierter Key zur Konfig des Journals.
persistence.snapshot-store.plugin"...in-memory"Voll qualifizierter Key zur Konfig des Snapshot Stores.
persistence.durable-state.plugin"...in-memory"Voll qualifizierter Key zur Konfig des Durable-State-Stores.
persistence.snapshot-store.in-memory.keep-n0Snapshots, die der eingebaute In-Memory-Store pro persistenceId behält. 0 behält alle — die umgekehrte Polarität zur 3 der persistenten Stores, weil das der Store ist, den eine unkonfigurierte Anwendung bekommt, und eine Schranke hier still Snapshots verwerfen würde.
persistence.journal.sqlite.path""Datenbankdatei, oder ":memory:" für eine In-Memory-Datenbank. Leer heißt nicht gesetzt, ohne Default dahinter: ein ausgewähltes Journal ohne Pfad, hier oder im Code, wird bei der Registrierung abgelehnt.
persistence.journal.sqlite.events-table"events"Event-Tabelle. Die Tags- (_tags) und Metadaten-Tabelle (_meta) folgen diesem Namen.
persistence.journal.sqlite.waloffDatenbank mit journal_mode = WAL öffnen — parallele Leser während eines Schreibvorgangs.
persistence.journal.sqlite.busy-timeout1sWie lange ein blockierter Schreiber auf das Lock wartet, bevor SQLITE_BUSY kommt; 0 bricht sofort ab.
persistence.snapshot-store.sqlite.path""Wie oben: leer heißt nicht gesetzt, ein ausgewählter Store ohne Pfad wird bei der Registrierung abgelehnt, und ":memory:" ist die ausdrückliche In-Memory-Datenbank.
persistence.snapshot-store.sqlite.snapshots-table"snapshots"Snapshot-Tabelle.
persistence.snapshot-store.sqlite.keep-n3Aufbewahrte Snapshots pro persistenceId; 0 schaltet das Pruning ab.
persistence.snapshot-store.sqlite.busy-timeout1sWie oben.
persistence.durable-state.sqlite.path""Wie oben, nur dass ein im Code übergebenes Datenbank-Handle den Pfad ersetzt: ein ausgewählter Store ohne beides wird bei der Registrierung abgelehnt.
persistence.durable-state.sqlite.table"durable_state"Durable-State-Tabelle.
persistence.durable-state.sqlite.auto-create-tablesonCREATE TABLE IF NOT EXISTS, wenn der Store öffnet — beim Start, sofern persistence.auto-start nicht abgeschaltet ist. Aus, wenn ein Schema-Tool das DDL besitzt.
persistence.durable-state.sqlite.busy-timeout1sWie oben.
persistence.snapshot-store.object-storage.backend""Welches Backend das Object-Storage-Plugin baut — filesystem, s3, oder leer, um es dem Code zu überlassen.
persistence.snapshot-store.object-storage.prefix""Wird jedem Object-Key vorangestellt — z. B. env-prod/.
persistence.snapshot-store.object-storage.keep-n3Aufbewahrte Snapshots pro persistenceId; 0 schaltet das Pruning ab.
persistence.snapshot-store.object-storage.max-decompressed-bytes512MSchutz gegen Dekompressionsbomben beim Lesen. Infinity schaltet ihn ab und geht nur im Code, weil HOCON kein Infinity-Literal kennt — withMaxDecompressedBytes(Infinity) und ein withConfig-Overrides-Objekt erreichen es beide.
persistence.snapshot-store.object-storage.compression.algorithm"gzip"Kompression at rest — none / gzip / zstd.
persistence.snapshot-store.object-storage.encryption.mode"none"Serverseitige Verschlüsselung — none / sse-s3 / sse-kms. client-aes256-gcm wird hier abgelehnt.
persistence.snapshot-store.object-storage.encryption.kms-key-id""KMS-Key-ARN, nötig bei Modus sse-kms. Ein Name des Schlüssels, niemals Schlüsselmaterial.
persistence.snapshot-store.object-storage.s3.bucket""Bucket-Name. Pflicht bei backend = s3.
persistence.snapshot-store.object-storage.s3.region""AWS-Region; auto für Cloudflare R2. Pflicht bei backend = s3.
persistence.snapshot-store.object-storage.s3.endpoint""Endpoint für MinIO / R2 / B2 / Spaces / Wasabi; leer bedeutet AWS S3.
persistence.snapshot-store.object-storage.s3.force-path-styleoffPath-Style-URLs statt Virtual-Host-Style — nötig für MinIO.
persistence.snapshot-store.object-storage.filesystem.dir""Wurzelverzeichnis, wird rekursiv angelegt. Pflicht bei backend = filesystem.
persistence.snapshot-store.object-storage.filesystem.lock-timeout5sWartezeit auf ein Write-Lock pro Key, bevor abgebrochen wird.
persistence.snapshot-store.object-storage.filesystem.stale-lock30sLock-Dateien, die älter sind, werden zwangsweise entfernt.

Die beiden Breaker-Blätter sind Ids, keine Zahlenblöcke. Die Einstellungen eines Breakers stehen unter actor-ts.circuit-breaker.<id>, überlagert über actor-ts.circuit-breaker.default — das ist ihr einziger Ort, und max-failures ein zweites Mal unter actor-ts.persistence zu veröffentlichen wären zwei Stellen für eine Sache. Ausgeliefert wird der Fehlerzähler (zehn Fehler in Folge, danach 15 s Fast-Fail) und kein call-timeout, denn das Weglassen ist genau das, was „keine Frist“ bedeutet. Um einen einzelnen Append zu deckeln — die Antwort auf ein Backend, das die Verbindung annimmt und dann hängt — benennt man ihn:

actor-ts.circuit-breaker.persistence-journal.call-timeout = 10s

Ein JournalConcurrencyError zählt nie als Breaker-Fehler: er ist das Eigentümer-Urteil eines bedingten Appends, kein Ausfall, und zehn Entities, die ein Rennen verlieren, dürfen nicht jede gesunde Entity auf dem Knoten fast-failen. Dasselbe gilt für JournalIntegrityError und SnapshotIntegrityError — dauerhafte Tatsachen über die gespeicherten Bytes, die kein Warten ändert.

snapshot-is-optional deckt bewusst keinen Snapshot ab, dessen Prüfung fehlgeschlagen ist. Stores mit Integritätsprüfung weisen einen manipulierten Body genauso zurück, wie sie Unerreichbarkeit melden; ein Actor, dessen persistenceOptions integrity oder encryption tragen, bekommt deshalb gar keinen Fallback — den Ausfall zu tolerieren hieße, die Manipulation zu tolerieren, und machte aus einer Integritätskontrolle einen Retry.

Die fünf Verhaltens-Blätter gelten für jeden PersistentActor und für das eigene persist, die Recovery und das Speichern der Snapshots eines ReplicatedEventSourcedActor; sein Anhängen eines Events, das ein Peer geschickt hat, liegt bis #958 nicht hinter dem Journal-Breaker. DurableStateActor steht außerhalb davon: Keines dieser Blätter erreicht einen Durable-State-Store, ob seine DurableStateOptions einen nennen oder er den systemweiten Store nutzt, den persistence.durable-state.plugin auswählt.

Der object-storage-Block konfiguriert beide Stores, die registerObjectStoragePlugins(persistence) zurückgibt: Snapshot Store und Durable-State-Store teilen sich ein Backend, also wird es einmal statt zweimal deklariert. Ist der Block gefüllt, braucht das Plug-in gar keine Options mehr — (persistence) => registerObjectStoragePlugins(persistence) im plugins-Slot von ActorSystemOptions.withPersistence. Explizite ObjectStoragePluginOptions gewinnen weiterhin, Feld für Feld, und ein im Code nicht gesetztes Feld fällt auf den Block durch, statt ihn zu überdecken. Werte werden einmal auf den gemergten Settings validiert, also wird backend = s3 ohne Bucket mit einem OptionsError abgelehnt, der backend.bucket benennt, sobald das Plug-in läuft, und der Start scheitert statt erst der erste Snapshot.

Für Schlüsselmaterial gibt es in diesem Block keinen Pfad, und das ist strukturell und nicht bloß Konvention. Es existiert kein Blatt für S3-Credentials, für einen clientseitigen Master Key oder für einen Integritätsschlüssel — eine Config-Datei kann sie also gar nicht ausdrücken. Lässt man die S3-Credentials weg, greift die Default-Chain des SDK: AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY, ein EC2-Instance-Profile oder IAM Roles for Service Accounts. encryption.mode = client-aes256-gcm wird mit einem OptionsError abgelehnt statt still ignoriert, denn ein Deployment, das clientseitige Verschlüsselung angefordert hat und stillschweigend Klartext bekommt, ist das schlechtere Ergebnis; konfiguriere diesen Modus im Code mit ObjectStoragePluginOptions.withEncryption(…). kms-key-id ist unbedenklich — eine ARN ist ein Name, und der Schlüssel selbst verlässt KMS nie.

durable-state.plugin ist die dritte Achse, und sie ist neu. Durable State war bislang der einzige Persistence-Vertrag ohne Registry: jeder registerXxxPlugins-Helper baute seinen Store eifrig und gab ihn zurück, ein DurableStateActor musste diese Instanz also im Code bekommen. Jetzt wird er genau wie Journal und Snapshot Store ausgewählt, und DurableStateOptions.store ist optional — ein Actor, der keinen Store benennt, nutzt den, den dieser Key auswählt.

SQLite wird über den plugins-Slot mit registerSqlitePlugins registriert und braucht gar keine Options mehr, wenn die drei Blöcke oben gefüllt sind:

const systemOptions = ActorSystemOptions.create().withPersistence({
plugins: [(persistence) => registerSqlitePlugins(persistence)], // path, tables, retention … from HOCON
});

Es gelten die üblichen drei Ebenen — explizite RegisterSqlitePluginsOptions stechen den Block, der Block sticht die eingebauten Defaults, Feld für Feld, und ein im Code nicht gesetztes Feld fällt durch, statt zu überdecken. Ein im Code angegebener path gilt für alle drei Stores als Default, ein Blatt mit eigenem path behält also seinen; eine vorab geöffnete database überschreibt dagegen die eigene des Durable-State-Blatts und erreicht nur diesen Store, denn Journal und Snapshot-Store öffnen ihre eigene Datei. Für driver, database und serializer gibt es kein Blatt — das sind lebende Objekte, die eine Config-Datei nicht ausdrücken kann.

Ein Store, den die Konfiguration auswählt, muss seine Datenbank benennen. Einer, dessen Block und Code-Options path offen lassen oder ihn leer oder auf eine entfernte URL setzen, wird abgelehnt, wenn registerSqlitePlugins läuft, sodass ActorSystem.create mit einem Fehler wirft, der den Key nennt; path = ":memory:" ist die ausdrückliche In-Memory-Datenbank. Ein registrierter, aber nicht ausgewählter Store wird nie gebaut und braucht daher nichts.

Auch die fünf relationalen Backends lesen ihre eigenen Blöcke (#872). Postgres, MariaDB, SQL Server, libSQL und Cloudflare D1 teilen sich ein Journal, einen Snapshot-Store und einen Durable-State-Store, deshalb ist die Tabellen-Hälfte jedes Blocks dieselben drei oder vier Blätter und nur die Verbindungs-Hälfte unterscheidet sich. registerPostgresPlugins(persistence) — und jedes seiner vier Geschwister — braucht damit gar keine Optionen mehr, sobald die Blöcke unten gefüllt sind:

const systemOptions = ActorSystemOptions.create().withPersistence({
plugins: [(persistence) => registerPostgresPlugins(persistence)], // url, tables, retention ... from HOCON
});

Die Verbindung wiederholt sich unter jedem der drei Plugin-Roots, statt auf einen Backend-Root gehoben zu werden, denn eine Plugin-Id ist ihr Config-Abschnitt, und die drei Achsen werden unabhängig ausgewählt — sie dürfen berechtigterweise verschiedene Datenbanken benennen. Wer eine Verbindung teilt, schreibt sie einmal und substituiert: url = ${actor-ts.persistence.journal.postgres.url}.

Drei Dinge haben bewusst kein Blatt. Ein vorab gebauter pool oder client und ein serializer sind lebende Objekte, eine Config-Datei kann sie nicht ausdrücken. poolConfig ist die gesamte Optionsfläche des Treibers, frei und unvalidiert, und bleibt deshalb code-only — der lange Schwanz. Für SQL Server heißt das: ein rein per Config verdrahteter Store wird über url erreicht, in der Form Server=...;Database=.... Eine mssql://-URL besteht das Lesen wie jeder andere String und wird beim Bau des Stores mit einem OptionsError abgelehnt: node-mssql parst seit seinem 8.0 keine mehr und liest sie als einen einzigen unbekannten Schlüssel ohne Server dahinter.

Was der Betrieb an den drei SQL-Treibern tatsächlich einstellt, hat stattdessen typisierte Blätter (#1490): max-pool-size, idle-timeout, connect-timeout und ca-file unter jedem Postgres-, MariaDB- und SQL-Server-Block, dazu MariaDBs acquire-timeout und SQL Servers request-timeout. Jedes ist nur Kommentar — ungesetzt bleibt der eigene Default des Treibers, der einzige Wert, der ihm folgt — und erreicht den Treiber unter dessen eigenem Namen nur, wenn es gesetzt ist. Gelesen wird jedes beim Bau des Stores. Ein Wert der falschen Art — ein Wort, wo eine Zahl hingehört, ein Bruch, wo eine Anzahl hingehört, eine Dauer, die sich nicht parsen lässt — scheitert schon beim Lesen, mit einem ConfigError, der das Blatt nennt, bei der Dauer mit einem Fehler, der nur den Wert nennt. Einen Wert der richtigen Art prüft danach der Store: eine Größe unter 1, ein Timeout, das keine positive ganze Zahl von Millisekunden ist, ein Timeout, das der Treiber nicht als Timer stellen könnte (über etwa 24,8 Tage), und ein MariaDB-idle-timeout, das keine ganze Zahl von Sekunden ist — der Connector zählt es in Sekunden —, werden mit einem OptionsError abgelehnt. Ebenso eine doppelt getroffene Einstellung: ein Blatt neben demselben Schlüssel in poolConfig oder in der URL (connectionLimit in einer MariaDB-URL, Max Pool Size in einem SQL-Server-Connection-String) wird abgelehnt und nennt beide, statt dass eine Seite still gewinnt. ca-file ist ein Pfad, den das Framework beim Öffnen des Pools liest, nie das Zertifikat selbst; so wird ein Server hinter einer privaten CA aus der Konfiguration erreicht, und für MariaDB und SQL Server ist es der einzige Weg, weil ihre URLs keine CA tragen können. Abgelehnt wird es neben allem, was über TLS etwas anderes sagt: einem ssl-Parameter in der URL bei Postgres, den node-postgres an seine Stelle setzen würde; einem ssl, das der MariaDB-Connector als false liest; einem Encrypt oder TrustServerCertificate, das die CA bei SQL Server ungenutzt ließe; oder einer poolConfig, die eine andere CA nennt.

Und tags-table ist in der Referenzkonfiguration ein Kommentar statt eines Schlüssels, weil sein Default aus events-table abgeleitet wird (<events-table>_tags): genau die Abwesenheit hält beide im Gleichlauf. Gelesen wird er trotzdem, eine application.conf kann ihn also weiterhin festnageln.

Die beiden Credentials, die doch ein Blatt haben — libSQLs auth-token und D1s api-token —, sind Strings, die der Betrieb von irgendwoher liefert; der dokumentierte Weg ist eine Substitution (api-token = ${?CLOUDFLARE_API_TOKEN}). Beide werden leer ausgeliefert, und leer heißt nicht gesetzt, damit der Platzhalter nie zu einem Bearer-Token wird.

Eine url, die die TLS-Verifizierung abschaltet, wird abgelehnt — für Postgres, SQL Server und MongoDB (#1490). Ihre Treiber lesen einen Verifizierungs-Schalter aus dem Connection-String selbst — sslmode=no-verify oder ssl=no-verify, unter uselibpqcompat=true auch sslmode=prefer, require oder verify-ca; TrustServerCertificate auf irgendetwas außer false, no, 0 oder leer; und tlsInsecure, tlsAllowInvalidCertificates oder tlsAllowInvalidHostnames auf irgendetwas außer false —, ihre Reader inspizieren das Blatt also und werfen einen ConfigError, der es und den Schalter nennt, in jeder Groß- und Kleinschreibung des Schlüssels und für eine ${?…}-Substitution genauso. Inspiziert wird nur HOCON: Derselbe String, an withUrl(...) übergeben, ist die Entscheidung des Codes. Für die Datei ist die Ablehnung strikt und lehnt die url eines Blocks auch dann ab, wenn der Code eine eigene Verbindung mitgibt. Klartext ist eine andere Entscheidung und bleibt erlaubt (sslmode=disable, Encrypt=false, tls=false), und MariaDB wird gar nicht inspiziert: Sein Connector liest das ssl der URL als Boolean, und ssl=true prüft. TLS everywhere hat die Begründung und die reinen Config-Wege zu einer privaten CA.

KeyDefaultZweck
persistence.journal.postgres.url""Connection-String. Leer heißt nicht gesetzt — der Store fällt auf die Verbindung zurück, die dem Register-Helper übergeben wurde.
persistence.journal.postgres.events-table"events"Event-Tabelle. Die Tag-Join-Tabelle wird als <events-table>_tags abgeleitet.
persistence.journal.postgres.auto-create-tablesonCREATE TABLE IF NOT EXISTS, wenn der Store öffnet — beim Start, sofern persistence.auto-start nicht abgeschaltet ist. Aus, wenn ein Schema-Tool das DDL besitzt.
persistence.journal.postgres.max-pool-size(ungesetzt)Verbindungen, die der Pool hält — pg-pools max, Default 10. Nur Kommentar, wie die drei darunter.
persistence.journal.postgres.idle-timeout(ungesetzt)Wie lange eine untätige Verbindung offen bleibt — pg-pools idleTimeoutMillis, Default 10s.
persistence.journal.postgres.connect-timeout(ungesetzt)Wie lange das Öffnen einer Verbindung dauern darf — pgs connectionTimeoutMillis; ungesetzt wartet es unbegrenzt.
persistence.journal.postgres.ca-file(ungesetzt)PEM-Datei der CA, die das Server-Zertifikat signiert hat, beim Öffnen des Pools gelesen und pg als ssl.ca übergeben. Abgelehnt neben einem ssl-Parameter in der URL.
persistence.snapshot-store.postgres.url""Wie oben.
persistence.snapshot-store.postgres.snapshots-table"snapshots"Snapshot-Tabelle.
persistence.snapshot-store.postgres.keep-n3Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab.
persistence.snapshot-store.postgres.auto-create-tablesonWie oben.
persistence.snapshot-store.postgres.max-pool-size, idle-timeout, connect-timeout, ca-file(ungesetzt)Wie oben.
persistence.durable-state.postgres.url""Wie oben.
persistence.durable-state.postgres.table"durable_state"Durable-State-Tabelle.
persistence.durable-state.postgres.auto-create-tablesonWie oben.
persistence.durable-state.postgres.max-pool-size, idle-timeout, connect-timeout, ca-file(ungesetzt)Wie oben.
KeyDefaultZweck
persistence.journal.mariadb.url""Connection-String. Leer heißt nicht gesetzt — der Store fällt auf die Verbindung zurück, die dem Register-Helper übergeben wurde.
persistence.journal.mariadb.events-table"events"Event-Tabelle. Die Tag-Join-Tabelle wird als <events-table>_tags abgeleitet.
persistence.journal.mariadb.auto-create-tablesonCREATE TABLE IF NOT EXISTS, wenn der Store öffnet — beim Start, sofern persistence.auto-start nicht abgeschaltet ist. Aus, wenn ein Schema-Tool das DDL besitzt.
persistence.journal.mariadb.max-pool-size(ungesetzt)Verbindungen, die der Pool hält — das connectionLimit des Connectors, Default 10. Nur Kommentar, wie die vier darunter.
persistence.journal.mariadb.acquire-timeout(ungesetzt)Wie lange ein Aufrufer auf eine freie Verbindung wartet — acquireTimeout, Default 10s.
persistence.journal.mariadb.idle-timeout(ungesetzt)Wie lange eine untätige Verbindung offen bleibt — idleTimeout, Default 1800s. Nur ganze Sekunden: der Connector zählt in Sekunden.
persistence.journal.mariadb.connect-timeout(ungesetzt)Wie lange das Öffnen einer Verbindung dauern darf — connectTimeout, Default 1s, gedeckelt durch den Acquire-Timeout.
persistence.journal.mariadb.ca-file(ungesetzt)PEM-Datei der CA, die das Server-Zertifikat signiert hat, beim Öffnen des Pools gelesen und dem Connector als ssl.ca übergeben. Abgelehnt neben einem ssl in der URL, das TLS abschaltet.
persistence.snapshot-store.mariadb.url""Wie oben.
persistence.snapshot-store.mariadb.snapshots-table"snapshots"Snapshot-Tabelle.
persistence.snapshot-store.mariadb.keep-n3Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab.
persistence.snapshot-store.mariadb.auto-create-tablesonWie oben.
persistence.snapshot-store.mariadb.max-pool-size, acquire-timeout, idle-timeout, connect-timeout, ca-file(ungesetzt)Wie oben.
persistence.durable-state.mariadb.url""Wie oben.
persistence.durable-state.mariadb.table"durable_state"Durable-State-Tabelle.
persistence.durable-state.mariadb.auto-create-tablesonWie oben.
persistence.durable-state.mariadb.max-pool-size, acquire-timeout, idle-timeout, connect-timeout, ca-file(ungesetzt)Wie oben.
KeyDefaultZweck
persistence.journal.mssql.url""Connection-String. Leer heißt nicht gesetzt — der Store fällt auf die Verbindung zurück, die dem Register-Helper übergeben wurde.
persistence.journal.mssql.events-table"events"Event-Tabelle. Die Tag-Join-Tabelle wird als <events-table>_tags abgeleitet.
persistence.journal.mssql.auto-create-tablesonCREATE TABLE IF NOT EXISTS, wenn der Store öffnet — beim Start, sofern persistence.auto-start nicht abgeschaltet ist. Aus, wenn ein Schema-Tool das DDL besitzt.
persistence.journal.mssql.max-pool-size(ungesetzt)Verbindungen, die der Pool hält — node-mssqls pool.max, Default 10. Nur Kommentar, wie die vier darunter.
persistence.journal.mssql.idle-timeout(ungesetzt)Wie lange eine untätige Verbindung offen bleibt — pool.idleTimeoutMillis, Default 30s.
persistence.journal.mssql.connect-timeout(ungesetzt)Wie lange das Öffnen einer Verbindung dauern darf — connectionTimeout, Default 15s.
persistence.journal.mssql.request-timeout(ungesetzt)Wie lange eine Anfrage laufen darf — requestTimeout, Default 15s.
persistence.journal.mssql.ca-file(ungesetzt)PEM-Datei der CA, die das Server-Zertifikat signiert hat, beim Öffnen des Pools gelesen und tedious zum Prüfen übergeben — ein Connection-String hat dafür keinen Schlüssel. Abgelehnt neben einem Encrypt oder TrustServerCertificate in der URL, das sie ungenutzt ließe.
persistence.snapshot-store.mssql.url""Wie oben.
persistence.snapshot-store.mssql.snapshots-table"snapshots"Snapshot-Tabelle.
persistence.snapshot-store.mssql.keep-n3Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab.
persistence.snapshot-store.mssql.auto-create-tablesonWie oben.
persistence.snapshot-store.mssql.max-pool-size, idle-timeout, connect-timeout, request-timeout, ca-file(ungesetzt)Wie oben.
persistence.durable-state.mssql.url""Wie oben.
persistence.durable-state.mssql.table"durable_state"Durable-State-Tabelle.
persistence.durable-state.mssql.auto-create-tablesonWie oben.
persistence.durable-state.mssql.max-pool-size, idle-timeout, connect-timeout, request-timeout, ca-file(ungesetzt)Wie oben.
KeyDefaultZweck
persistence.journal.libsql.url""Connection-String. Leer heißt nicht gesetzt — der Store fällt auf die Verbindung zurück, die dem Register-Helper übergeben wurde.
persistence.journal.libsql.auth-token""Turso-Auth-Token. Leer heißt nicht gesetzt; besser ${?TURSO_AUTH_TOKEN}.
persistence.journal.libsql.events-table"events"Event-Tabelle. Die Tag-Join-Tabelle wird als <events-table>_tags abgeleitet.
persistence.journal.libsql.auto-create-tablesonCREATE TABLE IF NOT EXISTS, wenn der Store öffnet — beim Start, sofern persistence.auto-start nicht abgeschaltet ist. Aus, wenn ein Schema-Tool das DDL besitzt.
persistence.snapshot-store.libsql.url""Wie oben.
persistence.snapshot-store.libsql.auth-token""Wie oben.
persistence.snapshot-store.libsql.snapshots-table"snapshots"Snapshot-Tabelle.
persistence.snapshot-store.libsql.keep-n3Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab.
persistence.snapshot-store.libsql.auto-create-tablesonWie oben.
persistence.durable-state.libsql.url""Wie oben.
persistence.durable-state.libsql.auth-token""Wie oben.
persistence.durable-state.libsql.table"durable_state"Durable-State-Tabelle.
persistence.durable-state.libsql.auto-create-tablesonWie oben.
KeyDefaultZweck
persistence.journal.cloudflare-d1.account-id""Cloudflare-Account-Id. Leer heißt nicht gesetzt.
persistence.journal.cloudflare-d1.database-id""D1-Datenbank-Id — die UUID, nicht der Datenbankname.
persistence.journal.cloudflare-d1.api-token""API-Token mit D1:Edit. Leer heißt nicht gesetzt; besser ${?CLOUDFLARE_API_TOKEN}.
persistence.journal.cloudflare-d1.base-url"https://api.cloudflare.com/client/v4"D1-REST-Endpunkt. Nur für einen Proxy oder ein Test-Double überschreiben.
persistence.journal.cloudflare-d1.timeout30sFrist für einen D1-Request. Ein Replay liest die ganze Historie eines Actors in einer Anweisung, also einem Request — das begrenzt eine ganze Recovery.
persistence.journal.cloudflare-d1.max-response-bytes64MObergrenze für einen D1-Response-Body. Das ganze Replay kommt als eine Response; heb sie an, wenn eine lange Historie nicht mehr recovert.
persistence.journal.cloudflare-d1.events-table"events"Event-Tabelle. Die Tag-Join-Tabelle wird als <events-table>_tags abgeleitet.
persistence.journal.cloudflare-d1.auto-create-tablesonCREATE TABLE IF NOT EXISTS, wenn der Store öffnet — beim Start, sofern persistence.auto-start nicht abgeschaltet ist. Aus, wenn ein Schema-Tool das DDL besitzt.
persistence.snapshot-store.cloudflare-d1.account-id""Wie oben.
persistence.snapshot-store.cloudflare-d1.database-id""Wie oben.
persistence.snapshot-store.cloudflare-d1.api-token""Wie oben.
persistence.snapshot-store.cloudflare-d1.base-url"https://api.cloudflare.com/client/v4"Wie oben.
persistence.snapshot-store.cloudflare-d1.timeout30sWie oben.
persistence.snapshot-store.cloudflare-d1.max-response-bytes64MWie oben.
persistence.snapshot-store.cloudflare-d1.snapshots-table"snapshots"Snapshot-Tabelle.
persistence.snapshot-store.cloudflare-d1.keep-n3Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab.
persistence.snapshot-store.cloudflare-d1.auto-create-tablesonWie oben.
persistence.durable-state.cloudflare-d1.account-id""Wie oben.
persistence.durable-state.cloudflare-d1.database-id""Wie oben.
persistence.durable-state.cloudflare-d1.api-token""Wie oben.
persistence.durable-state.cloudflare-d1.base-url"https://api.cloudflare.com/client/v4"Wie oben.
persistence.durable-state.cloudflare-d1.timeout30sWie oben.
persistence.durable-state.cloudflare-d1.max-response-bytes64MWie oben.
persistence.durable-state.cloudflare-d1.table"durable_state"Durable-State-Tabelle.
persistence.durable-state.cloudflare-d1.auto-create-tablesonWie oben.

Auch die drei nicht-relationalen Backends lesen ihre eigenen Blöcke (#872). Sie teilen sich weder untereinander noch mit der SQL-Familie eine Implementierung, jeder Block spricht also das Vokabular seines Backends — Mongo hat Collections und legt Indizes an, DynamoDB hat account-globale Tabellennamen und eine Region statt einer URL, und Cassandra wird über eine Seed-Liste erreicht und legt vier Tabellen an. registerMongoPlugins(persistence), registerDynamoDbPlugins(persistence) und registerCassandraPlugins(persistence) brauchen darum gar keine Optionen mehr, sobald die Blöcke unten gefüllt sind.

Cassandra hat keinen durable-state-Block, und das ist kein Versehen: Das Framework liefert keinen Cassandra-Durable-State-Store aus, dieses Backend hat also zwei Plugin-Achsen, wo die anderen beiden drei haben.

KeyDefaultZweck
persistence.journal.mongodb.url""Connection-String — mongodb://… oder mongodb+srv://…. Leer heißt nicht gesetzt.
persistence.journal.mongodb.database-name"actor_ts"Datenbank, in der die Collections liegen.
persistence.journal.mongodb.events-collection"events"Event-Collection. Ihre Meta-Collection heißt <it>_meta.
persistence.journal.mongodb.auto-create-indexesonIndizes anlegen, wenn der Store öffnet — beim Start, sofern persistence.auto-start nicht abgeschaltet ist. Der Unique-Index ist das, was einen doppelten Append ablehnt — aus heißt also ich habe sie selbst angelegt.
persistence.journal.mongodb.max-pool-size(nicht gesetzt)Verbindungen, die der Client zu einem Server offen hält — maxPoolSize des Treibers, Default 100. Nur als Kommentar, wie die vier darunter.
persistence.journal.mongodb.min-pool-size(nicht gesetzt)Verbindungen, die vorab offen gehalten werden — minPoolSize, Default 0. Höchstens max-pool-size.
persistence.journal.mongodb.server-selection-timeout(nicht gesetzt)Wie lange eine Operation auf einen Server wartet, den sie benutzen kann — serverSelectionTimeoutMS, Default 30s.
persistence.journal.mongodb.connect-timeout(nicht gesetzt)Wie lange das Öffnen einer Verbindung dauern darf — connectTimeoutMS, Default 30s.
persistence.journal.mongodb.ca-file(nicht gesetzt)PEM-Datei der CA, die das Server-Zertifikat signiert hat; wird beim Öffnen des Clients gelesen und dem Treiber als ca übergeben, mit eingeschaltetem TLS. Abgelehnt neben einem tlsCAFile in der URL und neben einem tls oder ssl mit false.
persistence.snapshot-store.mongodb.url""Wie oben.
persistence.snapshot-store.mongodb.database-name"actor_ts"Wie oben.
persistence.snapshot-store.mongodb.snapshots-collection"snapshots"Snapshot-Collection.
persistence.snapshot-store.mongodb.keep-n3Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab.
persistence.snapshot-store.mongodb.auto-create-indexesonWie oben.
persistence.snapshot-store.mongodb.max-pool-size, min-pool-size, server-selection-timeout, connect-timeout, ca-file(nicht gesetzt)Wie oben.
persistence.durable-state.mongodb.url""Wie oben.
persistence.durable-state.mongodb.database-name"actor_ts"Wie oben.
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(nicht gesetzt)Wie oben.

clientOptions hat kein Blatt — die ganze Optionsfläche des Treibers, die code-only bleibt — und ein vorab gebauter client oder ein serializer auch nicht. Was ein Operator am Client einstellt, hat stattdessen die typisierten Blätter oben (#1490), jedes nur als Kommentar, damit nicht gesetzt den eigenen Default des Treibers behält, bei mongodb 6 wie 7. Der Store prüft sie beim Bauen, wie er die SQL-Blätter prüft, und ein Blatt neben derselben Option in clientOptions oder in der Query der URL wird unter Nennung beider Seiten abgelehnt: Der Treiber liest alle drei ohne Rücksicht auf Groß- und Kleinschreibung, behält den Wert des Objekts und verwirft den der URL kommentarlos.

Die url wird inspiziert wie die relationalen oben: tlsInsecure, tlsAllowInvalidCertificates oder tlsAllowInvalidHostnames auf irgendetwas außer false wird abgelehnt. Eine private CA kommt als tlsCAFile in die URL oder als ca-file daneben — das eine oder das andere, weil der Treiber tlsCAFile nur liest, wenn er keine CA bekommen hat.

KeyDefaultZweck
persistence.journal.dynamodb.region""AWS-Region, z. B. eu-central-1. Leer heißt nicht gesetzt.
persistence.journal.dynamodb.endpoint""Endpoint-Override für dynamodb-local oder LocalStack; leer meint den echten Dienst.
persistence.journal.dynamodb.events-table"actor_ts_events"Event-Tabelle. Mit Präfix, weil ein DynamoDB-Tabellenname account- und regionsweit global ist.
persistence.journal.dynamodb.billing-mode"pay-per-request"Wie eine Tabelle, die der Store anlegt, abgerechnet wird: pay-per-request (On-Demand) oder provisioned. Die Schreibweise von AWS wird abgelehnt.
persistence.journal.dynamodb.provisioned-throughput.read-capacity-units(nicht gesetzt)Bewusst ein Kommentar, wie die Schreib-Hälfte darunter. Die Lese-Kapazität, mit der eine provisioned-Tabelle angelegt wird; unter pay-per-request abgelehnt.
persistence.journal.dynamodb.provisioned-throughput.write-capacity-units(nicht gesetzt)Die Schreib-Hälfte. Beide setzen oder keine: Ohne beide bekommt eine provisioned-Tabelle 5 Lese- und 5 Schreib-Einheiten.
persistence.journal.dynamodb.table-ready-timeout30sWie lange eine Tabelle, die der Store gerade angelegt hat, brauchen darf, bis sie ACTIVE ist.
persistence.journal.dynamodb.auto-create-tablesonCreateTable, wenn der Store öffnet — beim Start, sofern persistence.auto-start nicht abgeschaltet ist; eine schon vorhandene Tabelle ist der erwartete Fall. Aus, wenn die Tabellen anderswo provisioniert werden.
persistence.journal.dynamodb.max-attempts(nicht gesetzt)Versuche pro Request, der erste mitgezählt — maxAttempts des SDK. Nur als Kommentar, wie die drei darunter: Nicht gesetzt bleibt die eigene Auflösung des SDK (AWS_MAX_ATTEMPTS, die geteilte Config-Datei, dann 3).
persistence.journal.dynamodb.retry-mode(nicht gesetzt)standard oder adaptive — retryMode des SDK; jedes andere Wort wird abgelehnt. Nicht gesetzt: AWS_RETRY_MODE, die geteilte Config-Datei, dann standard.
persistence.journal.dynamodb.request-timeout(nicht gesetzt)Wie lange ein Versuch dauern darf, bevor er fehlschlägt — requestTimeout des Request-Handlers, mit eingeschaltetem throwOnRequestTimeout. Nicht gesetzt: keine Grenze.
persistence.journal.dynamodb.connection-timeout(nicht gesetzt)Wie lange das Öffnen der Verbindung dauern darf — connectionTimeout des Request-Handlers. Nicht gesetzt: keine Grenze.
persistence.snapshot-store.dynamodb.region""Wie oben.
persistence.snapshot-store.dynamodb.endpoint""Wie oben.
persistence.snapshot-store.dynamodb.snapshots-table"actor_ts_snapshots"Snapshot-Tabelle.
persistence.snapshot-store.dynamodb.keep-n3Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab.
persistence.snapshot-store.dynamodb.billing-mode"pay-per-request"Wie oben.
persistence.snapshot-store.dynamodb.provisioned-throughput.read-capacity-units(nicht gesetzt)Wie oben.
persistence.snapshot-store.dynamodb.provisioned-throughput.write-capacity-units(nicht gesetzt)Wie oben.
persistence.snapshot-store.dynamodb.table-ready-timeout30sWie oben.
persistence.snapshot-store.dynamodb.auto-create-tablesonWie oben.
persistence.snapshot-store.dynamodb.max-attempts, retry-mode, request-timeout, connection-timeout(nicht gesetzt)Wie oben.
persistence.durable-state.dynamodb.region""Wie oben.
persistence.durable-state.dynamodb.endpoint""Wie oben.
persistence.durable-state.dynamodb.table"actor_ts_durable_state"Durable-State-Tabelle.
persistence.durable-state.dynamodb.billing-mode"pay-per-request"Wie oben.
persistence.durable-state.dynamodb.provisioned-throughput.read-capacity-units(nicht gesetzt)Wie oben.
persistence.durable-state.dynamodb.provisioned-throughput.write-capacity-units(nicht gesetzt)Wie oben.
persistence.durable-state.dynamodb.table-ready-timeout30sWie oben.
persistence.durable-state.dynamodb.auto-create-tablesonWie oben.
persistence.durable-state.dynamodb.max-attempts, retry-mode, request-timeout, connection-timeout(nicht gesetzt)Wie oben.

Credentials haben kein Blatt: Weggelassen liefert sie die Default-Chain des SDK. clientConfig ebenso wenig — die ganze Optionsfläche des SDK, die code-only bleibt —, aber was ein Operator am Client einstellt, hat Blätter: die vier typisierten Blätter oben (#1490), nur als Kommentar, damit nicht gesetzt die eigene Auflösung des SDK behält, die ein ausgelieferter Wert überstimmen würde. Der Store prüft sie beim Bauen, und ein Blatt neben dem, was es in clientConfig ersetzt — maxAttempts, retryMode, eine retryStrategy, die beide gegenstandslos macht, oder ein requestHandler —, wird unter Nennung beider Seiten abgelehnt. request-timeout setzt throwOnRequestTimeout neben requestTimeout des Handlers, ohne das der Handler nur loggt, dass ein Request lange lief. Auch das Provisioning der Tabellen hat Blätter (#1490): Die Werte des Billing-Modus sind kebab-case wie jeder HOCON-Wert, und der Reader bildet sie auf PAY_PER_REQUEST und PROVISIONED von AWS ab. Das Kapazitätspaar wird als Kommentar ausgeliefert, weil es veröffentlicht unter dem Default pay-per-request abgelehnt würde, wo AWS Kapazität ignoriert; eine provisioned-Tabelle ohne Paar wird mit 5 Lese- und 5 Schreib-Kapazitätseinheiten angelegt — nenne das Paar also, wenn du bewusst provisionierst.

KeyDefaultZweck
persistence.journal.cassandra.contact-points[]Seed-Knoten, aus denen die Cluster-Topologie ermittelt wird. [] heißt nicht gesetzt — die Listenform des ""-Idioms.
persistence.journal.cassandra.keyspace""Keyspace, den jede Anweisung nennt (keyspace.table); der Client wird nie per USE daran gebunden. Leer heißt nicht gesetzt; an der Nutzungsstelle erforderlich.
persistence.journal.cassandra.local-data-center"datacenter1"Lokales DC für die DCAwareRoundRobinPolicy.
persistence.journal.cassandra.port9042CQL-Native-Transport-Port.
persistence.journal.cassandra.auto-create-keyspaceoffCREATE KEYSPACE beim Start, mit der Replikation darunter — eine Entwicklungshilfe.
persistence.journal.cassandra.replication.class"simple-strategy"Die Replikationsstrategie des Keyspace: simple-strategy oder network-topology-strategy. CQLs eigene Klassennamen werden abgelehnt. Nur von auto-create-keyspace gelesen.
persistence.journal.cassandra.replication.replication-factor1Kopien jeder Zeile unter simple-strategy.
persistence.journal.cassandra.replication.data-centers(nicht gesetzt)Bewusst ein Kommentar. Kopien pro Data Center unter network-topology-strategy, als Liste von { name, replication-factor }-Einträgen; unter simple-strategy abgelehnt.
persistence.journal.cassandra.consistency(nicht gesetzt)Bewusst ein Kommentar in der reference.conf. Nicht gesetzt wählt der Treiber das CQL-Level; setze den Zahlenwert aus types.consistencies (6 = LOCAL_QUORUM), um es festzuschreiben.
persistence.journal.cassandra.events-table"events"Event-Tabelle.
persistence.journal.cassandra.metadata-table"metadata"Höchste Sequenznummer pro persistenceId.
persistence.journal.cassandra.all-ids-table"all_persistence_ids"Die Lookup-Tabelle hinter persistenceIds().
persistence.journal.cassandra.tag-index-table"events_by_tag"Side-Table, nur geschrieben wenn use-tag-index an ist.
persistence.journal.cassandra.partition-size500000Zeilen pro Partition, bevor auf eine neue umgebrochen wird.
persistence.journal.cassandra.auto-create-tablesonDie vier Tabellen anlegen, wenn der Store sich verbindet — beim Start, sofern persistence.auto-start nicht abgeschaltet ist.
persistence.journal.cassandra.use-tag-indexoffEine events_by_tag-Side-Table mitschreiben, damit Tag-Queries eine Partition lesen.
persistence.journal.cassandra.lightweight-transactionsonDen Sequenzbereich vor dem Schreiben per Paxos beanspruchen. Aus riskiert einen still verlorenen Append, weil ein Cassandra-INSERT ein Upsert ist.
persistence.journal.cassandra.serial-consistency(nicht gesetzt)Bewusst ein Kommentar. Ohne die LWT oben ignoriert; nicht gesetzt wählt der Treiber clusterweites SERIAL. 9 ist localSerial.
persistence.snapshot-store.cassandra.contact-points[]Wie oben.
persistence.snapshot-store.cassandra.keyspace""Wie oben.
persistence.snapshot-store.cassandra.local-data-center"datacenter1"Wie oben.
persistence.snapshot-store.cassandra.port9042Wie oben.
persistence.snapshot-store.cassandra.auto-create-keyspaceoffWie oben.
persistence.snapshot-store.cassandra.replication.class"simple-strategy"Wie oben.
persistence.snapshot-store.cassandra.replication.replication-factor1Wie oben.
persistence.snapshot-store.cassandra.replication.data-centers(nicht gesetzt)Wie oben.
persistence.snapshot-store.cassandra.consistency(nicht gesetzt)Wie oben.
persistence.snapshot-store.cassandra.snapshots-table"snapshots"Snapshot-Tabelle.
persistence.snapshot-store.cassandra.keep-n3Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab.
persistence.snapshot-store.cassandra.auto-create-tablesonWie oben.

credentials hat gar kein Blatt — das ist Schlüsselmaterial, und Schlüsselmaterial ist in einer Config-Datei nie ausdrückbar. replication ist nicht frei (#1490): Es ist die typisierte Form, aus der das Keyspace-DDL gebaut wird, seine Blätter werden also einzeln gelesen, und ein unverändertes Objekt erreicht das DDL nie. Seine Data Center sind eine Liste statt einer Map, weil der Name eines Data Centers ein Datum ist und kein Key — als Key würde ein ungequotetes eu.west verschachteln, statt eines zu benennen.

Die Plugin-Keys zeigen auf einen anderen Config-Abschnitt, der die Settings dieses Plugins enthält. actor-ts.persistence.journal.sqlite oben ist das ausgearbeitete Beispiel: es ist zugleich die Id, unter der das Journal registriert ist, und der Block, den dieses Journal liest. Siehe jede Journal-Seite in Persistence für die per-Plugin-Keys.

KeyDefaultZweck
circuit-breaker.default.max-failures10Aufeinanderfolgende Fehler, bis ein Breaker öffnet (Circuit Breaker).
circuit-breaker.default.reset-timeout15sWie lange er offen bleibt, bevor er eine Probe durchlässt.
circuit-breaker.default.max-reset-timeout60sObergrenze des gewachsenen Fensters. Muss mindestens reset-timeout sein — ein Breaker, dessen gemergte Settings das verletzen, startet nicht.
circuit-breaker.default.backoff-factor1.0Multiplikator je aufeinanderfolgendem Öffnen. 1.0 = das flache Fenster jedes früheren Releases.
circuit-breaker.default.random-factor0.0Jitter-Anteil in [0, 1], über dieses Fenster gestreut. 0.0 = kein Jitter.
circuit-breaker.default.ignored-error-names[]Error.name-Werte, die nie als Fehler zählen.
circuit-breaker.default.call-timeout(nicht gesetzt)Bewusst ein Kommentar in reference.conf — siehe unten. Ungesetzt gibt es keine Deadline pro Aufruf.
circuit-breaker.<id>.*(der Block oben)Dieselben Blätter für den einen Breaker, den breaker('<id>') auflöst — sticht den Default-Block Blatt für Blatt.

Gelesen werden sie von der CircuitBreakerExtension, der Tür, die einen Breaker über seine Id auflöst:

import { CircuitBreakerExtensionId } from 'actor-ts';
const payments = system.extension(CircuitBreakerExtensionId).breaker('payment-api');
await payments.call(() => fetch('https://payments.example/charge'));

new CircuitBreaker({ … }) liest davon nichts und ist unverändert — das ist die Tür für einen Breaker, dessen Settings im Code stehen. Explizite Options aus breaker(id, options) stechen weiterhin beide Blöcke, und genau das trägt die zwei Dinge, die HOCON nicht ausdrücken kann: das isFailure-Prädikat und die random-Naht.

default ist reserviert, und die beiden Lesarten fallen zusammen: es ist der Block, von dem jeder Breaker erbt, und die Id, die breaker() ohne Argument auflöst — ein Breaker namens default liest also genau den Block, der ihn konfiguriert. Deshalb liegen die Defaults in einem benannten Unterblock und nicht direkt unter actor-ts.circuit-breaker.*: dort teilten sich Ids und Blätter einen Namensraum, und breaker('random-factor') suchte seine Settings in einer Zahl.

call-timeout ist ein Kommentar statt eines Blattes, weil das Weglassen von callTimeoutMs den Timeout pro Aufruf abschaltet und der Validator 0 ablehnt — „keine Deadline“ ist also ein Zustand, den nur ein fehlender Key ausdrücken kann. Geschrieben wirkt er ganz normal; der Block veröffentlicht bloß keinen Default, der jedem aus Config aufgelösten Breaker eine Deadline gäbe, die ein im Code gebauter nicht hat.

backoff-factor und random-factor sind mit Absicht neutral. 1.0 und 0.0 reproduzieren exakt das flache, ungejitterte Reopen-Fenster, der Block ist also additiv, und beides einzuschalten ist eine bewusste Entscheidung des Deployments. Sind sie gesetzt, ist das Fenster reset-timeout × backoff-factor^(aufeinanderfolgende Öffnungen − 1), begrenzt auf max-reset-timeout und dann um ± random-factor gestreut; es fällt auf reset-timeout zurück, sobald eine Probe gelingt und der Breaker schließt.

ignored-error-names wird vor isFailure geprüft, nicht danach. Die Liste ist die Hälfte des Klassifikators, die dem Betrieb gehört und aus einer Config-Datei kommt, während das Prädikat einkompiliert ist — könnte das Prädikat die Liste überstimmen, liefe der Key genau in den Deployments ins Leere, die ihn gesetzt haben.

Diese <id>-Pfade tragen die Id, nach der dein Code breaker(id) fragt, und lassen sich deshalb in reference.conf nicht aufzählen.

KeyDefaultZweck
projection.recovery-strategy"retry-and-fail"Was eine Projektion tut, wenn ihr Handler wirft — fail, skip, retry-and-fail oder retry-and-skip (wenn der Handler wirft).
projection.max-retries3Retry-Budget der beiden retry-*-Strategien — Versuche nach dem ersten.
projection.retry-backoff1sVerzögerung vor dem ersten Retry; verdoppelt sich mit jedem weiteren Versuch.
projection.max-retry-backoff60sObergrenze dieser Verdopplung. Muss mindestens retry-backoff sein — eine Projektion, deren gemergte Settings das verletzen, startet nicht.
projection.poll-interval1sWie oft eine Projektion das Journal nach neuen Events fragt.
projection.group-after-envelopes20Höchstzahl Events pro handleGroup-Aufruf (gruppierte Handler). Nur für gruppierte Projektionen — eine handle-Projektion bekommt ein Event pro Aufruf und ignoriert den Wert.

Das sind die prozessweiten Defaults für jede Projektion. ProjectionOptions einer einzelnen Projektion sticht sie, und sie stechen die eingebauten Defaults — die üblichen drei Ebenen. Eine Projektion, die ein leeres liveOptions übergibt, bekommt poll-interval weiterhin von hier; nur ein im Code tatsächlich gesetzter Wert überschreibt es. group-after-envelopes wird nur dort geprüft, wo es gilt: eine Größe, die der Validator ablehnt, etwa 0, stoppt die gruppierten Projektionen und lässt eine handle-Projektion in Ruhe — die lehnt nur ein groupAfterEnvelopes ab, das ihr eigener Code setzt.

Top-Level statt unter actor-ts.persistence, weil dieser Block ausschließlich Plugin-Ids enthält — ein Tuning-Blatt darin läse sich als Name eines Plugins.

KeyDefaultZweck
backoff-supervisor.min-backoff200msUntergrenze der Respawn-Verzögerung — und das Fenster, an dem after-min-stable die Stabilität eines Kindes misst (Backoff-Supervisor).
backoff-supervisor.max-backoff10sObergrenze, auf die die Verdopplung geklemmt wird. Muss mindestens min-backoff sein — ein Supervisor, dessen gemergte Settings das verletzen, startet nicht.
backoff-supervisor.random-factor0.2Jitter-Anteil in [0, 1], damit eine Herde Supervisor nicht im Gleichschritt respawnt. Wirkungslos für einen Supervisor mit eigener policy — diese berechnet die gesamte Verzögerung.
backoff-supervisor.max-stash-size1000Nachrichten, die ein Supervisor puffert, solange sein Kind tot ist; bei vollem Puffer wird die älteste zum Dead Letter.
backoff-supervisor.reset-counter"after-min-stable"Wann der Zähler aufeinanderfolgender Restarts zurückgesetzt wird — never, after-min-stable oder eine Dauer, die das Stabilitätsfenster explizit benennt.
backoff-supervisor.forward"stash"Was mit Nachrichten passiert, die während eines Backoff-Fensters ankommen — stash puffert sie für das nächste Kind, drop verwirft sie.
backoff-supervisor.trigger-on"any"Welche Terminierungen einen Respawn auslösen — any, failure (nur Abstürze) oder stop (nur saubere Stopps).
backoff-supervisor.drain-grace"auto"Wie lange ein respawntes Kind überleben muss, bevor der Stash in es drained — damit ein Kind, das in preStart crasht, den Stash nicht mitnimmt. auto ist eine feste Wartezeit von min(50ms, min-backoff), pro Supervisor gegen sein gemergtes min-backoff aufgelöst; eine Dauer legt sie fest, und 0 drained sofort.
backoff-supervisor.forward-during-gracetrueOb Nachrichten, die während dieser Grace ankommen, direkt an das respawnte Kind gehen (true) oder im Stash warten, bis es die Grace überlebt hat (false) — bis zu eine Grace Latenz nach jedem Respawn, dafür keine Dead Letters, solange ein Kind in preStart immer wieder crasht.

Das sind die prozessweiten Defaults für jeden BackoffSupervisor im Prozess. Die Optionen eines einzelnen Supervisors stechen sie, und sie stechen die eingebauten Defaults — die üblichen drei Ebenen, pro Feld. Ein Supervisor als BackoffSupervisor.factory({ child: Flaky }) übernimmt den ganzen Block; einer, der minBackoff im Code nennt, den Rest davon.

Der Merge passiert im preStart des Supervisors — dem ersten Punkt, an dem system.config erreichbar ist. Ein Wert, den eine Konfigurationsdatei außerhalb des zulässigen Bereichs setzt, lässt deshalb den Start des Supervisors scheitern und nicht den Aufruf, der ihn gebaut hat. Die Regel ist dieselbe, die den im Code geschriebenen Wert ablehnt.

child-name fehlt bewusst: der Name des Kindes ist Identität der Aufrufstelle, wo ein prozessweiter Wert schlicht falsch wäre. Im Code bleibt er setzbar.

KeyDefaultZweck
cache.in-memory.max-entries10000Max. Einträge vor LRU-Eviction (In-Memory-Cache).
cache.in-memory.cleanup-interval60sIntervall des Hintergrund-Sweeps für abgelaufene Einträge; 0 schaltet ihn ab.
cache.in-memory.prefix-quotas(nicht gesetzt)Kontingente pro Präfix, die eine Instanz unter ihren Consumern aufteilen; ihre Summe darf max-entries nicht überschreiten.
cache.in-memory.time-to-live0Lebensdauer, die ein set / mset ohne eigenes ttlMs bekommt. 0 = kein Ablauf, also das bisherige Verhalten.
cache.in-memory.time-to-idle0Ein Lesezugriff schiebt den Ablauf eines solchen Eintrags wieder nach hinten, nie über seine time-to-live hinaus. 0 = ein Lesezugriff verlängert nichts.
cache.<name>.in-memory.*(der Block oben)Dieselben Blätter, für die einzelne Instanz, die cache('<name>') auflöst — überschreibt den globalen Block Blatt für Blatt und lehnt eine ausgemusterte Schreibweise genauso ab.
cache.<name>.plugin"...in-memory"Welches Backend cache('<name>') auflöst.
cache.redis.url""redis://host:port (oder rediss://). Schließt host / port gegenseitig aus. "" = nicht gesetzt.
cache.redis.host / .port(nicht gesetzt)Bewusst Kommentare in der reference.conf — siehe unten. Ungesetzt nimmt ioredis sein eigenes 127.0.0.1:6379.
cache.redis.db0Logische Datenbank. Wird ignoriert, wenn url gesetzt ist; dann gehört sie in den URL-Pfad.
cache.redis.key-prefix""Wird jedem Key vorangestellt — trennt Systeme oder Umgebungen, die sich einen Server teilen.
cache.redis.password""AUTH-Passwort. Besser als Substitution: password = ${?REDIS_PASSWORD}.
cache.memcached.servers"localhost:11211"Komma-getrennte host:port-Liste — ein String, keine Liste, weil memjs genau das nimmt.
cache.memcached.username / .password""SASL-Credentials. Besser ${?MEMCACHED_PASSWORD}.
cache.memcached.key-prefix""Wird serverseitig auf jede Operation angewendet.
cache.<name>.redis.* / cache.<name>.memcached.*(die Blöcke oben)Dieselben Blätter für eine Instanz, damit cache('rate-limit') und cache('idempotency') verschiedene Datenbanken auf einem Server halten können.

Redis- und Memcached-Caches lesen ihre Verbindungs-Settings aus actor-ts.cache.redis / actor-ts.cache.memcached, und das Framework registriert beide Factories selbst — mehr als actor-ts.cache.sessions.plugin = "actor-ts.cache.redis" braucht ein Cache also nicht, um auf Redis hochzukommen, ganz ohne registerCache-Aufruf in deinem Code. Beide Treiber sind lazy geladene optionale Peers, ein Block, den niemand auflöst, kostet also nichts: ioredis und memjs werden bei der ersten Cache-Operation importiert, nicht beim Start.

Ein leerer String bedeutet in diesen beiden Blöcken „nicht gesetzt”. Die ""-Werte oben sind die Form des Keys, veröffentlicht damit du Name und Verschachtelung siehst; der Reader verwirft sie, statt sie weiterzureichen. Deshalb sind host und port auch Kommentare und keine Blätter: url schließt sie gegenseitig aus, und ein ausgeliefertes host = "localhost" wäre für jedes Deployment gesetzt und machte jede url zu einem OptionsError. Schreibst du beides absichtlich, bekommst du diesen Fehler weiterhin — genau darum geht es.

Diese <name>-Pfade nehmen den Namen, den dein Code an cache(name) übergibt, und lassen sich deshalb nicht in reference.conf aufzählen. Einen Consumer allein für seinen eigenen Key-Raum zu dimensionieren ist genau das, was die Empfehlung ein Cache pro Consumer braucht.

KeyDefaultZweck
sharding.number-of-shards64In wie viele Shards der Entity-Raum geteilt wird. Jeder Node, der einen Typ startet oder proxyt, muss denselben Wert haben — der Koordinator verweigert eine Region, die abweicht, siehe numShards ist eine clusterweite Vereinbarung.
sharding.role""Nur Mitglieder mit dieser Rolle hosten Shards. "" = keine Einschränkung. Der Key benennt eine Rolle, er vergibt keine — siehe Eine Rolle wird benannt, nicht vergeben weiter unten.
sharding.rebalance-interval2sAbstand zwischen koordinator-getriebenen Rebalance-Passes.
sharding.hand-off-timeout10sWie lange auf HandOffComplete gewartet wird, bevor zwangsumverteilt wird.
sharding.persist-coordinator-stateoffHält die Zuteilungskarte jedes Coordinators im Persistence-Journal, sodass ein neuer Leader mit der Karte beginnt, die der vorige zuletzt geschrieben hat. Das Journal muss vom Cluster geteilt werden; ein node-lokales auf einem Node, der entfernte Peers erwartet, wird abgelehnt (#1188).
sharding.coordinator-state-load-timeout10sWie lange ein neuer Leader auf das Laden dieser Karte wartet, bevor er ohne sie platziert.
sharding.rebalance-absolute-limit0Feste Obergrenze dafür, wie viele Shards ein Rebalance gleichzeitig in Bewegung haben darf. 0 = keine absolute Obergrenze. Siehe Rebalance-Churn begrenzen weiter unten.
sharding.rebalance-relative-limit0.1Dieselbe Obergrenze als Anteil von number-of-shards, sie skaliert also mit dem Entity-Raum — 0.1 der ausgelieferten 64 sind 6. 0 = keine relative Obergrenze; 0 für beide lässt den Rebalance ungedeckelt. Sind beide gesetzt, gewinnt die kleinere, und eine Obergrenze fällt nie unter einen Shard.
sharding.acquire-retry-interval5sWie lange der Koordinator wartet, bevor er ein Lease erneut zu erwerben versucht, das er nicht bekommen hat. Wirkt nur dort, wo der Koordinator ein Lease hat — im Code übergeben oder von use-lease gebaut.
sharding.use-leaseoffGibt dem Koordinator jedes geshardeten Typs ein aus actor-ts.coordination.lease gebautes Lease, sodass unter einer Partition nur der Halter Shards zuteilt. Abgelehnt beim Start des Typs, solange coordination.lease.backend = none; ein withLease(…) im Code gewinnt, und withUseLease(false) nimmt einen einzelnen Typ aus.
sharding.remember-entitiesfalsePersistiere die Menge aktiver Entity-IDs.
sharding.passivation-idle5mAuto-Passiviere eine Entität nach diesem Idle-Fenster. 0 = deaktiviert. Eine Entität, die Zustand im Speicher hält und ihn nicht in preStart wiederaufbaut, verliert ihn dabei — siehe Passivierung.
sharding.shard-passivation-idle(ungesetzt)Auto-Passiviere einen Shard, nachdem er so lange leer stand. Ungesetzt folgt er passivation-idle; 0 hält leere Shards resident. Bewusst nicht in der reference.conf, denn genau von einem ausgelieferten Wert müsste sich „ungesetzt” unterscheiden lassen.
sharding.max-entities0Entity-Obergrenze pro Sharded Type auf diesem Node; bei Überlauf wird die Entität passiviert, die die Ersetzungsstrategie benennt. 0 = kein Cap. Zwei gestartete Typen bekommen je das volle Cap — siehe Wählen, was ein voller Node hergibt weiter unten.
sharding.passivation.replacementleast-recently-usedWelche residente Entität das Cap hergibt. Außerdem segmented-least-recently-used und least-frequently-used. Bei max-entities = 0 wirkungslos.
sharding.passivation.segmented-protected-proportion0.8Anteil des Caps im geschützten Segment unter segmented-least-recently-used; der Rest ist Bewährung. Unter jeder anderen Strategie wirkungslos.
sharding.passivation.admission-window-proportion0.0Anteil des Caps, der als Bewährungsfenster vor der Strategie reserviert wird. 0 = kein Fenster. Vom admission-filter vorausgesetzt.
sharding.passivation.admission-filterofffrequency-sketch verlangt von einem Kandidaten, der das Fenster verlässt, dass er die Entität überbietet, die er verdrängen würde. Ohne admission-window-proportion > 0 bei sharding.start(...) abgelehnt.
sharding.passivation.stop-timeout0msWie lange eine Entität auf die Stop-Nachricht eines Passivate reagieren darf, bevor der Shard sie hart stoppt. 0 wartet unbegrenzt — das ist das ausgelieferte Verhalten.
sharding.buffer-size100000Wie viele Nachrichten eine Region über alle ihre Shards zusammen halten darf, solange deren Heimat unbekannt ist oder gerade übergeben wird oder ihr Shard nach einem Ausfall im Backoff ist (shard-failure-backoff unten). Dieselbe Obergrenze gilt pro Shard für das, was ein Shard für seine Entities zurückhält, die nach einem Stopp, um den niemand gebeten hat, im Backoff sind (entity-restart-backoff unten). Jenseits des Caps wird die neueste Nachricht mit ihrem Sender an die Dead Letters gegeben — was schon in der Queue steht, behält so die Reihenfolge des Senders. Achte auf die umgekehrte Polarität zu max-entities oben: hier bedeutet 0 niemals puffern — sofort Dead Letter, nicht „kein Cap”.
sharding.register-retry-interval500msWie oft eine Region eine unbestätigte Registrierung erneut an den Koordinator schickt. Alles, was für den Typ geroutet wird, puffert bis zur Antwort des Koordinators — das ist also zugleich die Dauer, die ein verlorenes Register den Typ blockiert.
sharding.shard-region-query-timeout5sDefault-Wartezeit für sharding.shards() und sharding.shardRefFor(). Ein explizites timeoutMs-Argument sticht sie weiterhin. Nicht die Zeit, die sich die Region einen noch unbeantworteten Aufrufer merkt — eine solche Abfrage oder ein knotenübergreifendes ask —, denn die beträgt eine Minute, oder actor.ask-timeout bzw. diesen Schlüssel, wo einer davon länger ist. Den Schlüssel zu erhöhen schneidet also keiner Abfrage die Antwort ab; ihn zu senken keinem ask.
sharding.entity-recovery.strategyallWie erinnerte Entities zurückkommen, nachdem eine Region einen Shard bekommen hat. all startet alle auf einmal — das heutige Verhalten, und der Grund, warum der Default nicht verschoben wurde. constant-rate verteilt sie, siehe Einen Remember-Entities-Restore drosseln weiter unten.
sharding.entity-recovery.constant-rate.frequency100msAbstand zwischen zwei gedrosselten Recovery-Batches. Unter strategy = all wirkungslos.
sharding.entity-recovery.constant-rate.number-of-entities5Wie viele Entities ein gedrosselter Batch startet. Ein regionsweites Budget, keines pro Shard — die Queue wird von jedem Shard der Region gespeist, das sind also Entity-Starts pro Fenster pro Sharded Type auf diesem Node; zwei gedrosselte Typen bekommen je das volle Budget. Unter strategy = all wirkungslos.
sharding.stale-region-detection.enabledoffLässt jede Region an den Koordinator schlagen und den Koordinator eine verstummte Region entfernen. Per Default aus — eine Entfernung ist destruktiv. Siehe Eine verstummte Region erkennen weiter unten.
sharding.stale-region-detection.heartbeat-interval5sAbstand zwischen zwei Schlägen Region → Koordinator. Pro Sharded Type, nicht pro Node. Bei enabled = off wirkungslos.
sharding.stale-region-detection.stale-after20sStille, nach der eine Region für verschwunden erklärt und ihre Shards neu vergeben werden. Muss größer als heartbeat-interval sein, und um mehr als einen Schlag. Bei enabled = off wirkungslos.
sharding.shard-failure-backoff.min200msErste Wartezeit, bevor ein unerwartet gestoppter Shard — außerhalb einer Übergabe, einer Passivierung oder einer Freigabe — neu erstellt wird; jeder Tod in Folge verdoppelt sie, bis max. Die Region behält den Shard so lange und puffert seine Nachrichten. Muss größer als 0 sein. Siehe wenn Shards und Entities immer wieder ausfallen.
sharding.shard-failure-backoff.max10sDie Obergrenze, bei der die verdoppelte Wartezeit stehen bleibt. Darf nicht unter min liegen.
sharding.shard-failure-backoff.random-factor0.2Jede Wartezeit wird um bis zu diesen Anteil in beide Richtungen gestreut, damit gemeinsam gestorbene Shards nicht im Gleichschritt zurückkommen. In 0..1; 0 macht jede Wartezeit exakt.
sharding.shard-failure-backoff.reset-after60sEin Shard, der seit seiner Rückkehr so lange nicht ausgefallen ist, beginnt beim nächsten Tod wieder bei min. Eine Passivierung dazwischen ist kein Ausfall.
sharding.entity-restart-backoff.min200msErste Wartezeit, bevor ein Shard eine Entity neu erstellt, die ohne Passivierung gestoppt ist — jenseits ihres Neustart-Budgets, nach einem verschluckten Recovery-Fehler, einem verlorenen Lease oder einem schlichten stopSelf; jeder solche Stopp in Folge verdoppelt sie, bis max. Der Shard hält die Nachrichten der Entity so lange zurück, gegen buffer-size pro Shard, und die Neustarts innerhalb des Budgets werden nicht verzögert. Muss größer als 0 sein. Siehe eine Entity, die immer wieder stoppt.
sharding.entity-restart-backoff.max10sDie Obergrenze, bei der die verdoppelte Wartezeit stehen bleibt. Darf nicht unter min liegen.
sharding.entity-restart-backoff.random-factor0.2Jede Wartezeit wird um bis zu diesen Anteil in beide Richtungen gestreut, damit gemeinsam gestoppte Entities nicht im Gleichschritt zurückkommen. In 0..1; 0 macht jede Wartezeit exakt.
sharding.entity-restart-backoff.reset-after60sEine Entity, die seit ihrer Rückkehr so lange nicht ungefragt gestoppt ist, beginnt beim nächsten solchen Stopp wieder bei min. Eine Passivierung dazwischen ist kein Ausfall.
sharding.healthcheck.names[]Sharded Types, ohne die dieser Node nicht bereit ist. Cluster.join installiert pro Name einen Readiness-Check, shard-region:<name>, der fehlschlägt, bis die Region dieses Nodes für den Typ beim Koordinator registriert ist — nie gestartet oder gestoppt, wegen number-of-shards abgelehnt oder noch nicht bestätigt. Einmal pro Join gelesen, nicht pro sharding.start(...); [] macht die Readiness von keinem Typ abhängig. Siehe die eingebauten Checks.

Diese Keys gelten für jeden auf dem Node gestarteten Sharded Type, healthcheck.names ausgenommen. Sie werden einmal pro sharding.start(...) gelesen und unter das gelegt, was dieser Aufruf explizit übergibt — die übliche Reihenfolge gilt also pro Feld:

// 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 (explizit), passivationIdleMs 120_000 (Config-Datei)

sharding.role sagt, welche Rolle einen Typ hostet. Der Key gibt dem Node diese Rolle nicht. Die eigenen Rollen eines Nodes sind eine eigene Einstellung — im Code vergeben oder über 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"

Setzt du nur die erste Hälfte, ändert sich nichts; setzt du nur die zweite, wird nie ein Shard zugeteilt — der Koordinator findet kein passendes Mitglied, jede Nachricht für den Typ sammelt sich im Routing-Puffer der Region, und das einzige Anzeichen ist eine Warnung, die die Rolle und die Zahl der ausgeschlossenen Regionen nennt. Eine role, die kein Mitglied trägt, ist dasselbe stille Versagen wie ein Tippfehler in withRole — nur dass sie aus einer geteilten Config-Datei auf einen Schlag für jeden Sharded Type auf jedem Node gilt.

Genau diese Asymmetrie ist auch der Grund für den Key: welche Rolle einen Typ hostet, ist über ein Deployment hinweg einheitlich — welche Rollen ein Node trägt, nicht.

Eine konfigurierte Rolle erreicht auch Sharded Daemon Processes, weil sie über dasselbe sharding.start(...) gestartet werden. Das ist so gewollt — wer seine Entities auf backend-Nodes legt, meint in der Regel auch seine Daemons — und ShardedDaemonProcessOptions.withRole(...) sticht sie pro Prozess weiterhin.

proxy hat bewusst keinen Key. Es ist Topologie pro Node und keine deployment-weite Tatsache: ein zweites start mit abweichendem Wert wirft, und ein von allen geteiltes proxy = on ließe niemanden mehr etwas hosten.

Unter remember-entities bekommt eine Region, der ein Shard zugeteilt wird, dessen komplettes Register zugeschickt und startet daraus per Default jede Entität auf einmal — und das für jeden Shard, den sie bekommt. Ein Node-Neustart oder ein Rebalance öffnet damit einen Journal-Replay pro erinnerter Entität, alle im selben Tick. constant-rate verteilt diese Starts:

actor-ts.sharding.entity-recovery {
strategy = constant-rate
constant-rate.frequency = 100ms
constant-rate.number-of-entities = 5
}

Zwei Dinge an diesem Budget muss man deutlich sagen, weil beide sich leicht andersherum lesen lassen:

  • Es gilt regionsweit, pro Sharded Type. Fünf Entities pro 100 ms sind fünf für diesen Sharded Type auf diesem Node, egal wie viele Shards der Node hält — derselbe Geltungsbereich wie bei max-entities. Jeder gestartete Typ hat seine eigene Region und Queue, ein Node, der zwei gedrosselte Typen wiederherstellt, startet also bis zu zehn pro Fenster. Pro Shard gelesen hießen dieselben Zahlen 5 × die Shard-Anzahl, was auf einem 64-Shard-Cluster überhaupt keine Schranke mehr ist — dieselbe Verwechslung, derentwegen max-entities regionsweit gehalten wird.
  • Es drosselt Starts, keine Replays. Ein Replay läuft asynchron; einer, der länger dauert als das Fenster, überlappt also weiterhin den nächsten Batch. Was dieser Key glättet, ist die Ankunftsrate; wie viele Recoveries gleichzeitig laufen dürfen, begrenzt persistence.max-concurrent-recoveries eine Ebene tiefer — beides greift ineinander.

Nichts geht verloren: der Rückstand wird abgearbeitet, bis jede erinnerte Entität wieder da ist, und eine Nachricht an eine Entität, die noch in der Queue steht, erzeugt sie sofort — nur der Recovery-Schwall wartet. Der Default bleibt all, weil Drosseln verändert, wann eine Entität zurückkommt, und wie schnell ein Journal die Replays verträgt eine Eigenschaft dieses Journals ist und keine des Shardings.

Die Default-Allocation Strategy platziert einen Shard über shardId % candidates.length; ein hinzukommender Node ändert die Antwort also für die meisten Shards gleichzeitig. Bei den ausgelieferten number-of-shards = 64 sind das 32 Shards bei einem Beitritt 1 → 2 Nodes, 42 bei 2 → 3 und 46 bei 3 → 4 — jeder davon ein gestoppter Shard, jede Entität darunter gestoppt, dann neu zugewiesen, neu erzeugt und, sofern sie persistiert, neu abgespielt. Angekündigt wird es auch nicht: der Koordinator reagiert nicht auf ein MemberUp, und er verteilt erst um, wenn die Menge der up-Mitglieder für sein Beruhigungsfenster stillgehalten hat — failure-detector.down-after, mit einer Split-Brain-Strategie das Größere davon und split-brain-resolver.stable-after. Der ganze Schwall kommt also mit dem ersten periodischen Tick nach diesem Fenster (siehe Mitglieder, die nicht up sind).

Die beiden Limits begrenzen, wie viele davon gleichzeitig in Bewegung sein dürfen:

actor-ts.sharding {
rebalance-absolute-limit = 0 # 0 = no absolute ceiling
rebalance-relative-limit = 0.1 # fraction of number-of-shards
}

Drei Punkte dazu, die man ausdrücklich sagen sollte:

  • Gezählt wird, was gleichzeitig läuft, nicht was pro Tick startet. Ein Tick feuert alle rebalance-interval, während eine Übergabe ein ganzes hand-off-timeout stehen darf — sechs pro Tick ließen also rund dreißig gleichzeitig zu. Der Koordinator budgetiert pro Tick die Obergrenze minus dem, was schon unterwegs ist.
  • Gedeckelt wird nur der freiwillige Pfad. Eine gestorbene Region hinterlässt Shards ganz ohne Besitzer; die werden sofort neu vergeben, mit oder ohne Obergrenze. Diesen Pfad zu drosseln hieße, Shards unerreichbar zu lassen statt sie nur langsamer einschwingen zu lassen.
  • Nichts geht verloren, und kein Node wird zuerst leergeräumt. Was das Budget übrig lässt, schlägt die Strategy im nächsten Tick erneut vor, bis die Map ausgeglichen ist; und welche Shards zuerst gehen, wird im Round-Robin über ihre aktuellen Besitzer entschieden — eine Obergrenze, die einen Node leert, bevor sie den nächsten anfasst, ist schlechter als gar keine.

Setze rebalance-relative-limit = 0 (das absolute Limit steht bereits auf 0), um das ungedeckelte Verhalten wiederherzustellen.

Lies erst den Geltungsbereich, bevor du danach greifst: das hier ist ein Auffangnetz für genau einen engen Fall, und der Fall, den die meisten meinen, ist schon ohne ihn abgedeckt.

Ein Node, der aufhört zu gossipen, ist nicht der Fall dieses Auffangnetzes. Per Default — keine Split-Brain-Strategie, actor-ts.cluster.failure-detector.auto-down = on — entfernt ihn der Failure Detector nach actor-ts.cluster.failure-detector.down-after (5 s); mit einer Split-Brain-Strategie bei deren Urteil, nicht vor split-brain-resolver.stable-after (per Default 20 s). Mit failure-detector.auto-down = off wird er auf unreachable geparkt, und seine Shards bleiben dort zugewiesen, bis ein Operator ihn auf down setzt (Cluster.down) oder eine Strategie entscheidet. In jedem Fall vergibt der Koordinator die Shards des Nodes aus dem daraus folgenden MemberRemoved neu, und das Auffangnetz unten tut es nie: Es überlässt die Regionen eines geparkten Nodes dieser Entscheidung, weil der Node ihre Shards noch ausführen kann. Einem geparkten Node wird in der Zwischenzeit kein neuer Shard zugewiesen (siehe Mitglieder, die nicht up sind). Eine sauber gestoppte Region sagt dem Koordinator auf ihrem Weg nach unten Bescheid. Was nichts davon abdeckt, ist eine Region, die auf einem noch laufenden, noch gossipenden Node verschwunden oder verklemmt ist und deren Meldung nie ankam: sie geht genau einmal raus, wird nicht quittiert, und ein Transportfehler auf dem Weg nach unten wird nur geloggt und geschluckt. Dann bleiben die Shards einem Actor zugewiesen, den es nicht mehr gibt, und nichts heilt das — die Kandidatenmenge wird aus der Registry abgeleitet und prüft nur, ob der Node einer Region up ist, nie, ob die Region selbst noch lebt.

actor-ts.sharding.stale-region-detection {
enabled = on
heartbeat-interval = 5s
stale-after = 20s
}

Fünf Dinge sind vor dem Einschalten wissenswert:

  • Der Schalter steuert beide Hälften. Aus schlägt keine Region und fegt kein Koordinator, der Mechanismus kostet also überhaupt nichts. An schickt jede Region jedes Sharded Type einen kleinen Frame pro heartbeat-interval.
  • Eine entfernte Region, die noch lebt, wird benachrichtigt und kommt zurück. Der Koordinator kann eine verschwundene Region nicht von einer unterscheiden, deren Schläge verloren gingen — eine Entfernung ist also eine Entscheidung, die er falsch treffen kann, und eine noch lebende Region erführe sonst nichts davon, behielte ihre Shards und bediente deren Entities weiter: ein Shard mit zwei lebenden Zuhause, so lange der Node oben bleibt. Sie bekommt deshalb eine Meldung: Eine wirklich verschwundene oder verklemmte verarbeitet sie nie, eine nur verstummte gibt jeden gehaltenen Shard auf — die Entities stoppen, eine persistente flusht also — und registriert sich sofort neu. Diese Region hat dann null Mal an den Koordinator geschlagen und ist erst wieder Sweep-Kandidat, wenn ein eigener Schlag ankommt; genau das verhindert, dass eine dauerhaft verstummte Region alle stale-after erneut entfernt wird.
  • Der Schlag geht pro Sharded Type, nicht pro Node. Zehn Typen auf einem Node sind zehn Frames pro Intervall, zusätzlich zu den Heartbeats des Clusters selbst.
  • Eine Region, die nie schlägt, wird nie entfernt. Genau das macht das Einschalten mitten in einem Rollout sicher: solange der Leader den Schalter an hat und einzelne Regionen noch nicht, sind diese Regionen schlicht noch nicht scharf — statt im Sekundentakt entfernt zu werden und sich in einer Schleife neu zu registrieren.
  • stale-after muss größer als heartbeat-interval sein, und die ausgelieferten vier Intervalle sind Absicht: bei einem einzigen entfernt ein verlorener Frame eine gesunde Region und stoppt jede Entität unter jedem Shard, den sie hielt. Ein Paar, das sich kreuzt, wird bei sharding.start(...) abgelehnt, und zwar gegen die aufgelösten Werte — das Überschreiben des einen kann den Default des anderen also nicht stillschweigend unterlaufen.

Ein check-interval gibt es bewusst nicht. Der Sweep läuft auf dem rebalance-interval-Tick mit, der ohnehin schon der Regler dafür ist, wie oft der Koordinator auf die Shard-Map schaut — die Erkennungslatenz ist also stale-after plus höchstens ein Tick.

max-entities sagt, wie viele Entities ein Node hält; der passivation-Block sagt, welche geht, wenn eine neue dazukommt. Jeder Key darin ist bei max-entities = 0 wirkungslos — und das ist der ausgelieferte Default, ein Deployment ohne Cap ist von allem hier also unberührt.

Lies die Reichweite des Caps, bevor du daran drehst: es gilt pro Sharded Type auf diesem Node, nicht node-weit und nicht pro Shard. Ein Node, der einen cart- und einen session-Typ mit max-entities = 50000 betreibt, hält bis zu hunderttausend Entities, fünfzigtausend je Typ. Pro Shard würde die Grenze über eine Menge geteilt, die sich bei jedem Rebalance ändert; node-weit bräuchte sie ein Budget, das sich Regionen teilen, die nichts voneinander wissen.

Der Default least-recently-used hat einen blinden Fleck, und der ist der Grund für den Block. Aktualität kann einmal überhaupt benutzt nicht von bis eben ständig benutzt unterscheiden — ein Durchlauf über einen großen kalten Schlüsselraum (ein nächtlicher Export, ein Crawler, ein Backfill) verdrängt das Arbeitsset Entität für Entität und füllt den Cache mit IDs, nach denen nie wieder jemand fragt:

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-used teilt das Cap in zwei Hälften. Eine einmal benutzte Entität sitzt auf Bewährung; wird sie erneut benutzt, wandert sie ins geschützte Segment, und verdrängt wird zuerst aus der Bewährung. Eine Scan-Entität wird nie ein zweites Mal berührt, kann also nur eine andere Scan-Entität verdrängen.
  • admission-window-proportion reserviert einen kleinen Teil des Caps für brandneue Ankömmlinge. Erst das macht einen Filter überhaupt möglich: eine Region kann die Entität, für die gerade eine Nachricht eingetroffen ist, nicht ablehnen — sie wird ja erzeugt, um diese Nachricht zu empfangen —, und so ist der Kandidat, der gegen den Amtsinhaber antritt, stattdessen das, was am anderen Ende des Fensters herausfällt.
  • admission-filter = frequency-sketch ist dieses Urteil. Ein kompakter Count-Min-Sketch darüber, wie oft jede ID gesehen wurde, entscheidet, wer bleibt — und er erinnert sich an IDs, die der Node längst nicht mehr hält, was genau die Historie ist, um eine früher heiße Entität wiederzuerkennen. Ohne Fenster wird er abgelehnt, statt still nichts zu tun.

least-frequently-used ist die dritte Strategie: die wenigsten Zugriffe verlieren, wobei alle Zähler periodisch halbiert werden, damit die Rangfolge dem jüngeren Verkehr folgt statt einer Lebenszeitsumme. Sie passt zu einem Arbeitsset, das stabil, aber nicht aktuell ist — eine Flotte von Geräten, die in langsamem Takt meldet —, wo Aktualität fast nichts aussagt.

stop-timeout hat mit dieser Wahl nichts zu tun — und mit max-entities ebenso wenig: ein positiver Wert schärft die Schranke mit oder ohne Cap. Wenn sich eine Entität mit Passivate selbst passiviert, ist die Stop-Nachricht eine Bitte: die Entität entscheidet, wann sie darauf reagiert. Tut sie es nie, terminiert sie nie, und ihr Platz bleibt für die Lebensdauer des Nodes gegen max-entities belegt. Nach stop-timeout stoppt der Shard sie hart.

Ausgeliefert wird sie aus (0, das unbegrenzte Warten), sodass sich für eine Deployment, die den Key nicht nennt, nichts ändert. Das ist Absicht und nicht Vorsicht: eine Entität mitten im Leeren — ein langer Flush, ein langsamer letzter Write — darf so lange brauchen, wie das Leeren dauert, und ein harter Stopp bricht diesen Flush ab. Wer weiß, wie lange das Leeren legitim laufen darf, ist die Betreiberin — also entscheidet sie, und der Key ist Opt-in.

Ein Setting für genau einen Typ gehört deshalb in den Builder; die Config-Datei ist für die node-weite Grundeinstellung, die du ohne Rebuild zwischen Staging und Produktion verschieben willst. Die polymorphen Optionen — der Entity-Actor, die Extraktoren, die Allocation Strategy, ein Lease, die Stores — haben keine HOCON-Form und bleiben im Code.

KeyDefaultZweck
coordinated-startup.default-phase-timeout30sBudget jeder Startphase, die kein eigenes nennt. Ein Task, der es überschreitet, lässt den Start scheitern; es ist also das, was ein Öffnen begrenzt, das nie antwortet.
coordinated-startup.phases.<name>.timeout—Budget für genau diese Phase; überschreibt default-phase-timeout nur für sie.
coordinated-startup.phases.<name>.recover—true macht einen fehlgeschlagenen Task in dieser Phase zu einem WARN, über den der Start hinweggeht, statt zu einem gescheiterten Start.
coordinated-startup.phases.<name>.depends-on—Phasen, die vorher laufen müssen. Bei einer vorgegebenen Phase wird die Kante ergänzt; bei einem neuen Namen ist die Angabe Pflicht.

Der Block stimmt den Startup-Graphen ab, den das System als letzten Schritt von create ausführt: wie lange jede Phase dauern darf und ob sie sich erholt. Die Tasks sind Code und kommen über withCoordinatedStartup. Wie der Shutdown-Block unten liefert phases selbst keine Werte aus:

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"]
}
}
}

Ein Kind, das persistence-start oder before-system-ready benennt, verschmilzt mit ihr: weggelassene Felder behalten das, womit die Phase initialisiert wurde. Jeder andere Name deklariert eine Phase, die ein im Code übergebener Task dann nennen darf, und dort ist depends-on Pflicht — eine Phase ohne Kanten liefe vor persistence-start. depends-on nennt eine vorgegebene Phase oder ein anderes Kind des Blocks, und an einer vorgegebenen Phase wird es der bestehenden Kante hinzugefügt; so kann eine Config-Datei before-system-ready nicht vor persistence-start laufen lassen. Eine deklarierte Phase erholt sich nur, wenn sie es sagt, wie die beiden vorgegebenen. Ein unbekanntes Setting unter einer Phase, eine deklarierte Phase ohne depends-on, ein Name, der auf keine Phase zeigt, ein Zyklus oder ein Budget von null ist ein ConfigError in ActorSystem.create.

Der Code gewinnt, Setting für Setting: withDefaultPhaseTimeoutMs über default-phase-timeout, und eine Phase, die withPhases nennt, gehört als Ganzes diesem Eintrag — das Kind des Blocks für sie wird nicht angewendet, die Kinder für die anderen Phasen schon.

KeyDefaultZweck
coordinated-shutdown.default-phase-timeout5sDefault-Timeout pro Phase. Eine Phase, die es überschreitet, wird abgebrochen, damit die nächste noch läuft.
coordinated-shutdown.terminate-actor-systemtrueOb der eingebaute Terminator-Task das Actor-System in der finalen Phase herunterfährt.
coordinated-shutdown.exit-processfalseOb process.exit(exit-code) aufgerufen wird, sobald ein Lauf endet. Ein Lauf, den eine Phase mit recover = false anhält, beendet den Prozess am Halt, anstelle des Teardowns, den er sonst bekäme, und mit 1, wo exit-code 0 ist.
coordinated-shutdown.exit-code0Status, den der Exit trägt. 0–255; alles andere ist ein ConfigError beim Start. Ein Lauf für einen fehlgeschlagenen Start, ein Lauf für einen Node, der nicht beitreten konnte (ClusterJoinUnsuccessfulReason: das Aufgeben des Joins, ein gescheitertes Readiness-Warten oder eine Ablehnung von Cluster.bootstrap), und ein Lauf, den eine Phase mit recover = false anhält, enden mit 1, wo hier 0 steht, und lesen sich so nie wie ein sauberer Stopp.
coordinated-shutdown.auto-register-taskstrueOb Framework-Komponenten ihr eigenes Teardown registrieren — das HTTP-Unbind, das Schließen der Broker, das Cluster-Leave, das DevTools-Detach.
coordinated-shutdown.run-by-process-signalstrueOb runUntilTerminated() und der Cluster-Bootstrap SIGTERM/SIGINT scharfschalten, wenn der Aufrufer keine Signale genannt hat.
coordinated-shutdown.run-by-actor-system-terminatefalseOb ein system.terminate(), das kein runCoordinatedShutdown nennt, zuerst die Pipeline ausführt, mit ActorSystemTerminateReason. false lässt es den bloßen Teardown bleiben; ein Aufruf, der wählt, bekommt in beiden Fällen, was er gewählt hat.
coordinated-shutdown.phases.<name>.timeout—Budget für genau diese Phase; überschreibt default-phase-timeout nur für sie.
coordinated-shutdown.phases.<name>.recover—false lässt einen fehlgeschlagenen Task in dieser Phase die Pipeline anhalten, statt ihn zu loggen und weiterzugehen.
coordinated-shutdown.phases.<name>.depends-on—Phasen, die vorher laufen müssen. Bei einer kanonischen Phase wird die Kante ergänzt; bei einem neuen Namen ist die Angabe Pflicht.

terminate-actor-system = false entfernt nur den eingebauten Terminator — in ActorSystemTerminate registrierte eigene Tasks laufen weiterhin. Nutze es, wenn ein Host-Prozess die Lebensdauer des Systems besitzt und ein Signal-Handler es nicht killen darf.

Der phases-Block ist das Config-Frontend zum Phasen-DAG und liefert selbst keine Werte aus — seine Kinder sind nach deinen Phasen benannt, es gibt also nichts, wofür sich ein Default veröffentlichen ließe:

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"] }
}

Ein Kind, das eine der zwölf kanonischen Phasen benennt, verschmilzt mit ihr: weggelassene Felder behalten das, womit die Phase initialisiert wurde. Jeder andere Name deklariert eine Phase, und dort ist depends-on Pflicht — eine Phase ohne Kanten landet im ersten fertigen Batch und liefe vor before-service-unbind, was nie gemeint war, wenn jemand eine Phase hinzufügt. depends-on an einer kanonischen Phase wird der bestehenden Kante hinzugefügt statt sie zu ersetzen; so kann eine Config-Datei cluster-leave nicht vor service-unbind umhängen — die topologische Sortierung fängt Zyklen ab, nicht eine Pipeline, die still in der falschen Reihenfolge läuft. Die Reihenfolge in der Datei spielt keine Rolle: zwei Phasen dürfen einander benennen und werden abhängigkeitsweise registriert. Ein nicht auflösbarer Name, ein Zyklus oder ein unbekanntes Setting unter einer Phase ist ein ConfigError beim Start, nicht beim Shutdown.

run-by-process-signals schaltet den Default um, nicht die Fähigkeit. Wer Signale explizit nennt — runUntilTerminated(['SIGTERM']) oder shutdownOnSignals in den Bootstrap-Optionen —, installiert sie trotzdem, denn explizite Optionen schlagen die Konfiguration. Ausschalten ist für einen Host-Prozess, der SIGTERM selbst besitzt: runUntilTerminated() wartet weiterhin und hält die Event-Loop offen, es schaltet nur nichts scharf.

exit-process ist für den umgekehrten Fall: ein hängengebliebenes Handle (ein offener Socket, eine gepoolte Verbindung, die ein Treiber nie freigegeben hat) hält den Prozess am Leben, nachdem die Pipeline fertig ist — von außen nicht von einem Hänger zu unterscheiden. Per Default aus, weil ein erzwungener Exit genau die Leaks verdeckt, die du eigentlich finden willst. exit-code ist der Status, den er übergibt — 0, weil eine bis zum Ende gelaufene Pipeline der Erfolgsfall ist; setze ihn dort, wo ein Supervisor einen geplanten Drain von einem Absturz unterscheiden soll. Auch ein Lauf, der anhält — eine Phase mit recover = false, deren Task fehlschlug —, beendet den Prozess, und nie mit 0: mit exit-code, wo dieser nicht 0 ist, und mit 1, wo er es ist, wie ein Lauf für einen fehlgeschlagenen Start. Der Exit kommt am Halt, sodass der Teardown, den der Halt sonst bekäme — den der Lauf eines Signals oder ein terminate() mit Pipeline ausführt —, nie beginnt; unmittelbar davor wird der Halt auf error geloggt, mit dem Namen der Phase. Was dieser Teardown geflusht hätte, wird stattdessen vor dem Exit geflusht — die Schreibvorgänge der Dead-Letter-Queue, danach die Log-Sinks, jeweils innerhalb von logger.close-timeout —, sodass diese Zeile auch einen bündelnden Sink erreicht; dasselbe gilt für einen abgeschlossenen Lauf mit terminate-actor-system = false.

KeyDefaultZweck
sharded-daemon-process.liveness-interval30sTakt des Sicherheitsnetz-Pings, der jeden Daemon-Index neu weckt — unabhängig davon, ob ein Cluster-Event gefeuert hat. 0 schaltet ihn ab; das ereignisgetriebene Neuwecken bei LeaderChanged / MemberRemoved läuft ohnehin weiter. Siehe den Liveness-Heartbeat.
sharded-daemon-process.role""Nur Mitglieder mit dieser Rolle hosten Daemons. "" heißt hier nicht „unbeschränkt“ — siehe eine nicht gesetzte Daemon-Rolle erbt die Sharding-Rolle weiter unten. Wie sharding.role benennt der Key eine Rolle, er vergibt sie nicht.

Ein Daemon-Set ist ein Modul auf Sharding und keine Sharding-Stellschraube — deshalb der eigene Block: actor-ts.sharding.* konfiguriert jeden gesharderten Typ auf dem Knoten, diese beiden nur die Daemons. Sie werden einmal pro ShardedDaemonProcess.init(...) gelesen und unter das gelegt, was der Aufruf explizit übergibt — die übliche Reihenfolge pro Feld:

// 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 it

name, numDaemons und der Aktor pro Index haben kein Leaf. Sie beschreiben ein einzelnes Daemon-Set und kein Deployment, und eine Factory hat ohnehin keine HOCON-Form.

Eine nicht gesetzte Daemon-Rolle erbt die Sharding-Rolle

Abschnitt betitelt „Eine nicht gesetzte Daemon-Rolle erbt die Sharding-Rolle“

sharded-daemon-process.role auf "" heißt keine daemon-spezifische Meinung, nicht unbeschränkt. Das Daemon-Set startet als ganz normaler gesharderter Typ, übernimmt also ohne Eintrag hier actor-ts.sharding.role genau wie jeder andere Typ:

actor-ts.sharding.role = "backend" # every sharded type
# sharded-daemon-process.role left at "" # daemons follow along

Eine Rolle hier zu benennen schränkt nur die Daemons ein und überlässt die übrigen gesharderten Typen dem globalen Key:

actor-ts.sharding.role = "backend" # entities on the backend nodes
actor-ts.sharded-daemon-process.role = "batch" # daemons on the batch nodes

Derselbe Vorbehalt wie bei sharding.role gilt, und er trifft hier härter, weil einem Daemon niemand eine erste Nachricht schickt: Eine Rolle, die kein Up-Mitglied trägt, allokiert nichts — die Daemons starten also schlicht nie. Der Coordinator loggt eine Zeile mit der Rolle, sobald sich eine Region registriert hat und die Rolle sie herausgefiltert hat.

KeyDefaultZweck
devtools.host"127.0.0.1"Interface, an das attach bindet. Alles Routbare wird abgelehnt, solange nichts davor sitzt — siehe unten.
devtools.port9333Port, an den gebunden wird; 0 lässt das Betriebssystem einen freien wählen, das zurückgegebene Binding meldet welchen.
devtools.allow-remotefalseBestätigt einen ungeschützten Bind auf einem routbaren Interface.
devtools.serve-uitruefalse lässt den Tap ohne die mitgelieferte UI.
devtools.allowed-origins[]Zusätzliche Origins, die den WebSocket des Taps öffnen dürfen. Same-Origin ist immer erlaubt; das hier erweitert nur.
devtools.panels.actorstrueAktor-Baum, Mailbox-Tiefen und Cell-Zustände.
devtools.panels.clustertrueCluster-Topologie, Shard-Maps, Membership-Timeline.
devtools.panels.tracingtrueSpan-Flamegraph und -Wasserfall — seine Payload-Spalte trägt jede Actor-Nachricht, die während des DevTools-Attach vorbeikam, serialisiert.
devtools.panels.explaintrueExplain-Plan pro Aktor.
devtools.panels.time-traveltrueJournal-Browsing und State-Rekonstruktion — das Panel, das rohe persistierte Events zeigt.
devtools.panels.profilertrueAktor-Profiler.
devtools.panels.dead-letterstrueUnzustellbare Nachrichten, inklusive Payload.
devtools.panels.event-streamtrueLive-Tail von Event-Bus und Cluster-PubSub-Topics, inklusive Payload.
devtools.panels.configtrueAufgelöste Konfiguration mit der Quelle jedes Keys (Werte, deren Key ein Geheimnis benennt, werden redigiert).
devtools.panels.sendtrueDie Ansicht zum Nachrichtenversand. Die Fähigkeit dahinter ist ein eigener, nur im Code setzbarer Schalter.
devtools.mailbox-sample-interval1sWie oft Aktor-Baum, Mailbox-Tiefen und Cell-Zustände neu abgetastet werden.
devtools.mailbox-sample-limit50Wie viele Mailboxen ein Sample trägt.
devtools.stats-interval1sWie oft die Dashboard-Kennzahlen abgetastet werden.
devtools.span-buffer-capacity10000Obergrenze der gehaltenen Spans, in Nachrichten.
devtools.span-flush-interval250msWie oft gepufferte Spans ans Panel geflusht werden.
devtools.capture-payloadstruefalse lässt das Tracing-Panel laufen — Spans, Zeiten, Flame-Graph — und leert nur dessen Payload-Spalte, während panels.tracing = false das ganze Panel mitnimmt. Eine Erfassung, die die Anwendung selbst gesetzt hat, bleibt so oder so unangetastet.
devtools.event-buffer-capacity500Events, die der Bus-Tail zwischen zwei Flushes puffert; darüber fallen die ältesten weg und das Panel erfährt, wie viele.
devtools.event-flush-interval250msWie oft gepufferte Events ans Panel geflusht werden.
devtools.replay-auto-capturetrueLeiht sich den Fold eines laufenden PersistentActor, um State zu rekonstruieren.

Dieser Block startet DevTools nicht. Nichts im ActorSystem erzeugt die Extension — DevTools.attach(system) ist immer ein Aufruf im Code — die Keys ändern also, wie eine Attachment sich verhält, nie ob es eine gibt. Einen enabled-Key gibt es bewusst nicht: ihn zu lesen hieße, das DevTools-Subsystem samt eingebettetem UI-Bundle in jedes System zu importieren, das DevTools nie öffnet.

Ein konfigurierter Host trifft dieselbe Regel wie ein im Code gesetzter. Optionen werden einmal validiert, auf den gemergten Settings — devtools.host = "0.0.0.0" wirft also einen OptionsError mit Feld host, genauso wie .withHost('0.0.0.0') im Code. auth und ipAllowlist sind Middleware und haben keine HOCON-Form; genau deshalb ist allow-remote die einzige Antwort, die eine Datei auf diese Regel geben kann.

Sieben Felder haben keinen Key. auth, ipAllowlist, backend, cluster und replayFolds sind Funktionen und lebende Objekte, die HOCON nicht ausdrücken kann, und uiDevelopmentRoot ist eine Notluke für die Panel-Entwicklung, deren eigene Doku sagt, sie in einer Anwendung nie zu setzen. Die letzten beiden sind eine Entscheidung, keine Unmöglichkeit: allow-ungated-mount sagt etwas über den Code aus, der die Routen von mount() bindet, nicht über ein Deployment, und allow-message-sending ist die eine DevTools-Fähigkeit, die aus dem Browser in das laufende System schreibt. Beide bleiben neben dem Aufruf, den sie qualifizieren.

Ein im Code übergebenes panels-Objekt überschreibt die konfigurierten Schalter einzeln, nicht als Ganzes: .withPanels({ timeTravel: false }) über einer Datei mit panels { send = false } lässt send aus. Das ist die übliche Präzedenz, eine Ebene tiefer angewandt — sonst würde ein einzelnes im Code genanntes Panel jedes vom Betrieb abgeschaltete Panel wieder einschalten.

actor-ts.offload-pool (reine Funktionen auf Worker-Threads)

Abschnitt betitelt „actor-ts.offload-pool (reine Funktionen auf Worker-Threads)“
SchlüsselDefaultZweck
offload-pool.size"auto"Worker höchstens — "auto" ist die verfügbare Parallelität minus Main-Thread. Gespawnt, wenn Tasks sie brauchen.
offload-pool.min-size0Worker, die über Leerlauf hinweg am Leben bleiben.
offload-pool.max-queue10000Tasks, die auf einen Worker warten, bevor overflow über den nächsten entscheidet.
offload-pool.overflow"reject"reject lässt den Lauf mit OffloadQueueFullError fehlschlagen; wait hält ihn offen, bis ein Platz frei wird.
offload-pool.idle-timeout60sEin Worker jenseits von min-size ohne Arbeit wird danach abgebaut.
offload-pool.task-timeout0s0 = keine Deadline, außer run() nennt eine. Eine Deadline terminiert den Worker.
offload-pool.max-restarts10Worker-Terminierungen — Crash oder Deadline —, die der Pool innerhalb von restart-window ersetzt; -1 = unbegrenzt. Jenseits des Budgets schlägt jeder Lauf fehl.
offload-pool.restart-window60sDas Fenster, über das das Restart-Budget zählt.
offload-pool.warm-upoffJeden Worker beim Start spawnen statt beim ersten Task, der ihn braucht.

Der Task — ein benannter Export eines Moduls — und das Worker-Bootstrap sind Code, nie Schlüssel, aus demselben Grund, aus dem worker-cluster.bootstrap keinen hat. Siehe Blockierende und CPU-lastige Arbeit.

actor-ts.parallelism (Actors auf Worker-Threads allein per Config)

Abschnitt betitelt „actor-ts.parallelism (Actors auf Worker-Threads allein per Config)“
SchlüsselDefaultZweck
parallelism.workers00 ist aus — das Single-Thread-System, Bit für Bit. Eine Zahl oder "auto" (verfügbare Parallelität minus Main-Thread) startet im Hintergrund ein Worker-Mesh und macht system.spawn zu einer Platzierungsentscheidung.
parallelism.offload["/user/*"]Pfadmuster der Top-Level-Actors, die auf einen Worker wandern. * ist ein Segment, ** eines oder mehrere. Ein Muster, das /system erreichen könnte, wird abgelehnt.
parallelism.placement"consistent-hash"Auf welchem Worker ein Actor landet: ein Hash seines Namens, oder "round-robin".
parallelism.leader"main""worker" verschiebt den Cluster-Leader — und den Shard-Coordinator — auf einen Worker, indem die Worker einen Hostnamen bekommen, der vor main sortiert.
parallelism.spawn-timeout10sWie lange ein Spawn auf die Bestätigung seines Workers wartet, bevor die Ref fehlschlägt.
parallelism.buffer-size100000Nachrichten, die über alle noch unbestätigten Spawns gehalten werden; darüber hinaus Dead Letters.

Das Actor-Modul — die Datei, die die Klassen exportiert, die ein Worker spawnen darf — ist Code, nie ein Schlüssel: per Konvention actors.js neben dem Entry-Modul, sonst ParallelismOptions.withModule(...). Hostnamen, Ports, Rollen und Restart-Pacing der Threads sind die worker-mesh.*- und worker-cluster.*-Schlüssel unten. Siehe Parallelität.

KeyDefaultZweck
worker-cluster.workers"auto"Anzahl Worker — "auto" ist die verfügbare Parallelität der Maschine (os.availableParallelism(), das die CPU-Quote eines Containers respektiert; navigator.hardwareConcurrency als Fallback).
worker-cluster.system-name"worker-cluster"ActorSystem-Name, den jeder Worker hostet.
worker-cluster.hostname"worker"Hostname-Komponente der NodeAddress jedes Workers.
worker-cluster.base-port1Port des ersten Workers; jeder weitere Slot inkrementiert.
worker-cluster.ready-timeout10sFrist für den Hello/Init/Ready-Handshake pro Worker.
worker-cluster.restart-policy"on-failure"always / on-failure / never.
worker-cluster.restart-min-backoff200msWartezeit vor dem ersten Respawn eines abgestürzten Slots.
worker-cluster.restart-max-backoff10sObergrenze für die Respawn-Wartezeit, die pro Versuch verdoppelt wird.
worker-cluster.restart-random-factor0.2±-Jitter-Anteil auf jede Respawn-Wartezeit, in [0, 1].
worker-cluster.max-restarts10Restarts pro Slot innerhalb des Fensters, bevor er stillgelegt wird; -1 startet unbegrenzt neu.
worker-cluster.restart-window60sGleitendes Fenster, über das das Restart-Budget zählt; 0 setzt es nie zurück.

Die vier Duration-Keys lassen das Ms-Suffix ihrer Felder im Options-Objekt weg (ready-timeout setzt readyTimeoutMs) und nehmen ein HOCON-Duration-Literal — genauso, wie logger.close-timeout das Feld closeTimeoutMs speist. restart-random-factor ist ein reiner Bruchteil, keine Duration.

Vier Felder haben bewusst keinen Key: initData ist Identität des einzelnen Aufrufs, backend und onWorkerPermanentlyDown sind lebende Objekte, die eine Config-Datei nicht ausdrücken kann, und bootstrap benennt ein Modul, das die Runtime ausführt — ACTOR_TS_CONFIG und eine abgelegte application.conf sind eine breitere Angriffsfläche als die Aufrufstelle, deshalb bleibt es ein reines Code-Feld.

actor-ts.worker-mesh (der Main-Thread als Mesh-Mitglied)

Abschnitt betitelt „actor-ts.worker-mesh (der Main-Thread als Mesh-Mitglied)“
KeyDefaultZweck
worker-mesh.workers"auto"Worker-Anzahl — "auto" ist die verfügbare Parallelität minus eins, weil der Main-Thread ein arbeitendes Mitglied ist; mindestens 1.
worker-mesh.main-hostname"main"Host-Komponente der Adresse des Main-Threads. Sortiert per Default vor den Workern, also führt main und hostet den Shard-Coordinator.
worker-mesh.main-port1Port-Komponente der Adresse des Main-Threads — synthetisch, nichts bindet ihn.
worker-mesh.worker-hostname"worker"Host-Komponente jeder Worker-Adresse. Eine, die vor main-hostname sortiert, verschiebt den Leader auf einen Worker.
worker-mesh.base-port2Port des ersten Workers; jeder Slot inkrementiert.
worker-mesh.main-roles[]Cluster-Rollen, mit denen der Main-Thread joint.
worker-mesh.worker-roles[]Cluster-Rollen, mit denen jeder Worker joint — worauf rollenbeschränkte Singletons, Shards und Router selektieren.
worker-mesh.metrics-relay-interval10sWie oft der Main-Thread die Metrik-Registry jedes Workers in sein eigenes /metrics zieht. Solange das Relay läuft, trägt jede Serie thread="main" oder thread="worker-<slot>"; die Werte eines Workers sind höchstens ein Intervall alt. 0 schaltet das Relay ab und exportiert nur den Main-Thread — siehe den Geltungsbereich eines Scrapes.

Die Worker des Mesh sind ein Worker-Cluster, deshalb sind Ready-Timeout und Restart-Taktung die worker-cluster.*-Keys oben. Das Actor-Modul (withModule) und das Bootstrap haben keinen Key — aus dem Grund, aus dem bootstrap keinen hat.

Die Validierung läuft auf den gemergten Settings, deshalb wird jeder dieser Werte aus einer Datei mit einem OptionsError genauso abgelehnt wie aus Code: ein leerer system-name oder hostname, ein base-port außerhalb von [1, 65535], ein restart-random-factor außerhalb von [0, 1], ein negativer Backoff oder ein negatives Fenster, ein max-restarts unter -1 und ein restart-max-backoff unterhalb von restart-min-backoff.

Diese Keys füllen WorkerCluster.spawn(options) für Felder auf, die der Aufruf nicht setzt. spawn ist ein Static ohne ActorSystem im Scope und lädt die Config-Kette daher selbst — dieselbe, die ActorSystem.create verwendet, inklusive ACTOR_TS_CONFIG und ./application.conf. Eine unbekannte restart-policy wird mit einem OptionsError abgelehnt, statt still „never” zu bedeuten.

Jeder Broker-Actor liest aus seinem eigenen Subtree. Siehe die per-Protokoll-Seiten für die Keys des jeweiligen Protokolls:

SubtreeSeite
io.broker.kafkaKafka
io.broker.mqttMQTT
io.broker.amqpAMQP
io.broker.natsNATS
io.broker.jetstreamNATS JetStream
io.broker.jetstream-key-valueJetStream KV + Object Store
io.broker.jetstream-object-storeJetStream KV + Object Store
io.broker.redis-streamsRedis Streams
io.broker.grpc.{client,server}gRPC
io.broker.websocketWebSocket Client
io.broker.sseSSE
io.broker.tcpTCP
io.broker.tcp-serverTCP
io.broker.udpUDP
io.broker.email-bridgeE-Mail-Bridge

Jeder dieser Subtrees außer grpc.server nimmt außerdem die Blätter, die BrokerActor für alle liest: reconnect (initial-delay, max-delay, factor, max-attempts, random-factor), circuit-breaker (eine Breaker-Id, deren Zahlen unter actor-ts.circuit-breaker.<id> liegen — siehe Circuit Breaker) und outbound-buffer. Der gRPC-Server ist ein gewöhnlicher Actor, kein BrokerActor, und liest keines davon; ein reconnect-Block unter ihm konfiguriert also nichts. actor-ts.io.broker.kafka.outbound-buffer = 0 lässt den Kafka-Actor also verwerfen, was ihm ohne Verbindung geschickt wird, statt es zu puffern. Beschrieben sind sie einmal, auf der BrokerActor-Basisseite, und ihre alten camelCase-Schreibweisen werden abgelehnt, sobald der Broker-Actor startet.

Nicht jedes Feld dieser Typen hat einen Key. Eine ActorRef (target, bindings, subscriptions) benennt einen lebenden Actor in diesem Prozess, ein Codec oder ein Handler ist eine Funktion, und TLS-Material ist ein Private Key — keines der drei hat eine Schreibweise in einer Config-Datei, und jedes sagt das in seinem eigenen JSDoc, statt einfach zu fehlen.

gossip-interval = 1s # 1000 ms
unreachable-after = 2.5s # 2500 ms
down-after = 5000ms # explizite ms
gc-cadence = 10m # Minuten
ttl = 24h # Stunden

Erkannte Einheiten, unabhängig von Groß- und Kleinschreibung, mit oder ohne Leerzeichen davor:

GrößenordnungSchreibweisen
Nanosekundenns nano nanos nanosecond nanoseconds
Mikrosekundenus μs micro micros microsecond microseconds
Millisekundenms milli millis millisecond milliseconds
Sekundens sec secs second seconds
Minutenm min mins minute minutes
Stundenh hr hrs hour hours
Taged day days

Eine bloße Zahl sind Millisekunden. Ein führendes Vorzeichen und ein Bruchteil sind beide erlaubt — -500ms und 1.5s sind gültig. Alle drei Schreibweisen des Mikro-Zeichens landen auf derselben Einheit, damit kopierter Text parst: μs (U+03BC, worauf die Tabelle indiziert ist), µs (U+00B5, was eine Tastatur erzeugt) und Μs (U+039C).

Zwei Dinge werden beim Parsen abgelehnt, statt still zu einer Zahl zu werden, mit der niemand etwas anfangen kann:

  • Eine unbekannte Einheit — Unknown duration unit "..." in .... Die Suche liest ausschließlich die eigenen Schlüssel der Einheitentabelle, so wie lesend nur eigene Schlüssel sichtbar sind den Key-Pfad absichert; constructor wird also wie jede andere unbekannte Einheit abgelehnt, statt über die Prototype-Kette aufgelöst zu werden.
  • Alles, was keine endliche Anzahl Millisekunden ergibt — Invalid duration: .... Das umfasst ein Literal, das lang genug ist, um ein Double zu überlaufen, und jede Schreibweise, auf die das Muster nicht passt, Exponentialschreibweise (1e3) eingeschlossen.
max-frame-bytes = 16M # 16 777 216 Bytes — binär
upload-limit = 16MB # 16 000 000 Bytes — dezimal
buffer = 64K
heap = 2G

Erkannte Einheiten, unabhängig von Groß- und Kleinschreibung, mit oder ohne Leerzeichen davor:

GrößenordnungBinär (1024)Dezimal (1000)
BytesB byte bytes—
KiloK KiB kibibyte kibibytesKB kilobyte kilobytes
MegaM MiB mebibyte mebibytesMB megabyte megabytes
GigaG GiB gibibyte gibibytesGB gigabyte gigabytes
TeraT TiB tebibyte tebibytesTB terabyte terabytes
PetaP PiB pebibyte pebibytesPB petabyte petabytes

Der einzelne Buchstabe ist binär, wie HOCON es festlegt, und die iB-Form ebenso; allein das blanke B-Suffix ist dezimal. Die beiden laufen mit der Größenordnung auseinander — 16MB ist 4,63 % kleiner als 16M, bei T ist der dezimale Wert 9,05 % kleiner — eine Obergrenze in der ungewollten Form ist also eine Obergrenze an der falschen Stelle.

Anders als eine Duration nimmt eine Size kein Vorzeichen — -1K ist Invalid size — und sie muss eine ganze Anzahl Bytes ergeben. Ein Bruchteil mit Einheit ist in Ordnung, wenn er das tut, 1.5K sind also 1536, und wird abgelehnt, wenn nicht: 1.1K sind 1126,4 Bytes und scheitern als Invalid size: 1.1K is not a whole number of bytes. Eine bloße Zahl muss selbst ganz sein, ob als String oder als Zahl geschrieben: "1.5" ist Invalid size, und 1.5 wird unter Nennung des Keys abgelehnt, an dem es steht, als Config at "..." is not a whole number of bytes (got 1.5).

Dieselben zwei Ablehnungen gelten, mit den für Sizes buchstabierten Meldungen: Unknown size unit "..." in ... für eine Einheit, die nicht in der Tabelle steht — constructor eingeschlossen, aus dem Grund oben — und Invalid size: ... für alles, was keine endliche, ganze Byte-Anzahl ergibt.

port = ${?ACTOR_TS_PORT} # nutze env, falls gesetzt, sonst fallback
log-level = ${?LOG_LEVEL} # gleich
api-key = ${API_KEY} # required — Fehler, wenn env nicht gesetzt
fallback-port = 2552 # der Default …
fallback-port = ${?ENV_PORT} # … nur ersetzt, wenn ENV_PORT gesetzt ist

Verwende ${?ENV} für optional, ${ENV} für required.

Eine Variable, die gesetzt, aber leer ist, zählt als nicht gesetzt — PORT= in einer Shell, environment: [PORT] in einer Compose-Datei und eine leere Zeile einer Env-Datei bedeuten alle „nicht gesetzt“. ${?PORT} löst sich dann zu nichts auf und der Default scheint durch, und ${PORT} scheitert mit einem Fehler, der sagt, dass die Variable gesetzt, aber leer ist. Um einen Key auf einen leeren String zu setzen, schreib "" in die Datei.

Eine Default-falls-nicht-gesetzt-Form gibt es nicht. Alles zwischen den Klammern ist der Pfad: ${ENV_PORT:-2552} wird als Key namens ENV_PORT:-2552 nachgeschlagen und scheitert als unaufgelöste Substitution, und ${?ENV_PORT:-2552} ist optional und löst sich still zu nichts auf. Deklariere erst den Default und danach den optionalen Override, wie es die letzten beiden Zeilen tun: eine optionale Substitution, die sich zu nichts auflöst, lässt den früheren Wert stehen, und eine spätere einfache Zuweisung ersetzt ihn wie gewohnt.

Über Schichten hinweg gilt dasselbe. Steht der Default in reference.conf oder in einer darunter gemergten Datei, entfernt ein nicht gesetztes ${?ENV} in application.conf den Key aus dieser Schicht, und die darunter scheint durch — genau darauf verlässt sich die erste Zeile oben. Ein Key, den reference.conf nur als Kommentar trägt — remote.tcp.host und port, das advertised-*-Paar, discovery.config.seeds und andere —, hat keine Schicht darunter: Ein nicht gesetztes ${?ENV} lässt ihn ungesetzt, und der eigene Fallback des Readers greift.

Eine Substitution darf einen Key nennen, dessen Wert selbst eine Substitution ist. Die Kette löst sich in jeder Reihenfolge ihrer Zeilen auf, und ein Key, den die Datei definiert, schlägt an jedem Glied die Umgebung: api.url = ${db.url} mit db.url = ${db.host} liest den Host aus der Datei, auch wenn eine Variable DB_URL gesetzt ist. Eine Kette, die zu ihrem Anfang zurückführt, wird als Substitution cycle: a -> b -> a abgelehnt, die optionale Form eingeschlossen. Ein Key, der sich selbst nennt — pod.ip = ${?pod.ip} —, ist kein Zyklus: Er liest die Umgebung und danach den Wert, den er ersetzt hat.

host = # nichts dahinter — keine Zuweisung, host behält seinen Wert
host = ${?DB_HOST} # DB_HOST nicht gesetzt oder leer — host behält seinen Wert
host = ${DB_HOST} # DB_HOST nicht gesetzt oder leer — der Start scheitert
host = "" # ein ausdrücklich leerer String
roles = [] # eine ausdrücklich leere Liste

Eine Zuweisung, nach deren = oder : nichts steht, ist keine Zuweisung: Der Key behält, was ihm eine frühere Zeile derselben Datei gegeben hat, und über Dateien hinweg scheint die Schicht darunter durch. Das gilt vor einem Komma, vor der schließenden }, vor einem Kommentar und am Dateiende. Um einen Key zu leeren, schreib "" oder [].

Ein Wert darf weiterhin in der Zeile nach seinem Key stehen, wie JSON es anordnet ("timeout": und darunter 10s), solange diese Zeile nicht selbst ein Feld beginnt: Eine Zeile der Form name = …, name: …, name { … oder include "…" ist das nächste Feld, und die Zuweisung darüber hat keinen Wert. Ein unquoted Wert, der wie ein Feld aussieht — localhost:2552 —, gehört deshalb in dieselbe Zeile wie sein Key.

url = "redis://:"${REDIS_PASSWORD}"@cache:6379" # ein String
address = ${HOST}":"${PORT} # "db:5432"
name = app-${STAGE} # "app-prod"
seeds = [ ${?SEED_HOST}":"${?SEED_PORT} ] # ein Element

Quoted Strings, Substitutionen und unquoted Text, die in einer Zeile nebeneinander stehen, ergeben einen String. Die Leerzeichen zwischen den Stücken bleiben erhalten, ${A} ${B} ist also beide Werte mit einem Leerzeichen dazwischen, und ein Feld nach einem Leerzeichen beginnt weiterhin ein neues Feld (a = "x" b = 1). Ein einzelnes Stück behält seinen Typ: port = ${PORT} ist eine Zahl, wenn PORT eine enthält.

In einem String trägt eine Variable den Text bei, den sie enthält. Allein liest ${X} eine Variable zuerst als JSON, PORT=2552 ergibt also eine Zahl und FLAGS=[1,2] eine Liste; in einem String würde das ein Passwort aus Ziffern in eine Zahl in Exponentenschreibweise verwandeln, deshalb geschieht es dort nicht. Ein Key der Datei fließt so ein, wie HOCON ihn schreibt — 30, true —, und ein Key, der ein Objekt oder eine Liste enthält, lässt sich nicht in einen String einfügen.

Ein nicht gesetztes ${?X} in einem String fügt nichts hinzu. Ein String, der nur aus optionalen Substitutionen besteht, von denen keine gesetzt ist, ist gar kein Wert, sodass der frühere Wert oder die Schicht darunter durchscheint — wie bei einem einzelnen ${?X}.

${ in Anführungszeichen ist Text, keine Substitution: "${X}" sind die fünf Zeichen, die dort stehen. Und weil // einen Kommentar beginnt, gehört eine URL in Anführungszeichen — url = http://host wird abgelehnt, wo es früher als http: gelesen wurde.

Nicht unterstützt und mit einem Fehler abgelehnt, der das sagt: Objekte oder Listen zusammenfügen ({ a = 1 } { b = 2 }, [1] [2], ${base} { … }), += und Strings in dreifachen Anführungszeichen (#537).

include "shared-cluster.conf" # Fehler: `include` wird nicht unterstützt

Eine Config-Quelle kann keine weitere Datei und keine URL benennen, die hinzugeladen wird. Das ist eine Entscheidung, keine Lücke: ein aufgelöstes include überließe demjenigen, der die Config schreibt, die Wahl, welche Pfade der Prozess liest — relativ zu einer Wurzel, die der Parser gar nicht kennen kann. Das Zusammenführen im Code belässt diese Wahl beim Aufrufer.

import { Config } from 'actor-ts';
const shared = Config.parseFile('shared-cluster.conf');
const application = Config.parseFile('application.conf');
const config = shared.merge(application);

merge legt sein Argument obenauf, die lokale Datei gewinnt also — genau die Reihenfolge, auf die das include oben hinauswollte. Den geteilten Inhalt in eine Datei zu kopieren funktioniert ebenfalls.

Ein Vorbehalt: Substitutionen werden beim Parsen jeder einzelnen Datei aufgelöst, nicht einmal über den gemergten Baum. Ein ${my.port} in shared-cluster.conf, dessen my.port nur application.conf definiert, scheitert schon beim ersten parseFile mit Unresolved substitution — wo ein echtes include ein einziges Dokument erzeugt und dieses aufgelöst hätte. Ein Wert, auf den die Basisdatei verweist, muss in der Basisdatei oder in der Umgebung stehen. Für gemeinsame Defaults ist die reference.conf des Projekts da: Config.load löst sie vor application.conf auf, und application.conf darf auf ihre Keys verweisen.

Der Parser sagt all das, wenn er auf ein include trifft, und zitiert dabei Zeile und Ziel — eine aus Akka oder Pekko portierte Config scheitert damit mit einer Antwort statt mit einem Rätsel.

Drei Schlüssel werden in einer Config-Quelle überall abgelehnt — als Schlüssel, als jedes Segment eines Pfadausdrucks und innerhalb einer Substitution:

__proto__.anything = 1 # Fehler: abgelehnt
constructor.x = 1 # Fehler: abgelehnt
prototype = 1 # Fehler: abgelehnt
value = ${__proto__} # Fehler: abgelehnt

Ein Schlüsselpfad wird auf ein einfaches Objekt expandiert, und eine Zuweisung an __proto__ schreibt in den Objekt-Prototypen statt einen normalen Schlüssel anzulegen — würde man das zulassen, könnte eine Config-Datei das Verhalten jedes Objekts im Prozess verändern. Der Parser lehnt sie stattdessen mit der gewohnten Zeilen- und Spaltenangabe ab.

Die Prüfung vergleicht exakt, ähnlich aussehende Schlüssel sind also unproblematisch: _proto_, constructorName und prototypes funktionieren normal.

Drei abgelehnte Namen sichern die Schreibseite. Die Leseseite ist andersherum abgesichert — positiv — denn Object.prototype hat ein Dutzend weitere Member, und eine Liste käme dabei nie hinterher:

name = ${toString} # Fehler: unaufgelöste Substitution — keine native Funktion
port = ${?valueOf} # optional: fällt auf die Umgebung durch, dann weg

Jeder Zugriff — eine Substitution, hasPath und jeder typisierte Getter — liest ausschließlich eigene Schlüssel, im Config-Baum wie in der Umgebung. Ein Name, der zufällig einem geerbten Member entspricht, geht damit ins Leere, statt zu dem aufzulösen, was auf dem Prototypen liegt, und hasPath('toString') ist false, solange die Config keinen eigenen toString-Schlüssel deklariert. Das bleibt erlaubt und funktioniert weiterhin: ein eigener Schlüssel überdeckt den geerbten Member, toString = "mine" liest sich also als "mine" zurück.

const actorSystemOptions = ActorSystemOptions.create().withConfig({
'actor-ts': { cluster: { 'gossip-interval': '500ms' } },
});
const system = ActorSystem.create(
'my-app',
actorSystemOptions,
);
// Innerhalb eines Actors / einer Extension:
const config = system.config;
const interval = config.getDuration('actor-ts.cluster.gossip-interval');
// → 500 (in ms)

Das Objekt ist so verschachtelt wie die HOCON-Blöcke. Seine Keys werden wörtlich genommen, ein Key mit Punkten wie 'actor-ts.cluster.gossip-interval' ist also ein einzelner Key mit Punkten im Namen, kein Pfad zur Einstellung.

Das Config-Interface hat typisierte Getter: getString, getNumber, getBoolean, getDuration, getBytes, getStringList, etc. Fehlende Keys werfen, es sei denn, Du prüfst zuerst mit hasPath.

1. REFERENCE_CONF ← gebündelte Defaults
2. die reference.conf des Projekts — die erste hiervon, die gesetzt ist:
`referenceConfigFile`-Setting › ENV-Var ACTOR_TS_REFERENCE_CONFIG › ./reference.conf (CWD)
3. deren Block profiles.<profil> ← wenn ein Profil aktiv ist
4. eine Anwendungsdatei — die erste hiervon, die gesetzt ist:
`configFile`-Setting › ENV-Var ACTOR_TS_CONFIG › ./application.conf (CWD)
5. deren Block profiles.<profil> ← wenn ein Profil aktiv ist
6. eine Secrets-Datei — die erste hiervon, die gesetzt ist:
`secretsFile`-Setting › ENV-Var ACTOR_TS_SECRETS_CONF › ./secrets.conf (CWD)
7. deren Block profiles.<profil> ← wenn ein Profil aktiv ist
8. Konstruktor `config: { ... }` ← Code-Level-Override
9. Konstruktor-Feld-Overrides ← explizite Felder schlagen Config
(logLevel, dispatcher, scheduler, …)
daneben, keine Schicht — eine .env-Datei: `environmentFile`-Setting › ACTOR_TS_ENV_FILE › ./.env (CWD)

Jede Schicht überlagert die vorherige, Key für Key. Schicht 9 (Konstruktor-Felder) gewinnt immer für die Felder, die sie abdeckt; alles andere fließt durch den HOCON-Merge. Das Profil ist withProfile(name), dann die Umgebungsvariable ACTOR_TS_PROFILE, dann keines — siehe Profile. Die Schichten 2, 4 und 6 sind optionale Dateien: Für jede entscheidet der erste gesetzte Kandidat, ein Pfad, hinter dem keine Datei liegt, ist eine leere Schicht, und false als Pfad-Option liest gar keine solche Datei. Die Settings sind, auf ActorSystemOptions, withReferenceConfigFile, withConfigFile und withSecretsFile, für die .env withEnvironmentFile; wer Config.load selbst aufruft, übergibt stattdessen referenceConfPath, appConfPath, secretsConfPath und environmentFilePath — siehe Die reference.conf des Projekts und Secrets-Datei.

Die Substitutionen einer Datei lesen ihre eigenen Keys, dann die Schichten, die unter ihr schon aufgelöst sind, dann die echte Umgebung, dann die Variablen der .env-Datei. application.conf darf also auf einem Key aufbauen, den die reference.conf des Projekts setzt, während eine untere Datei nie eine höhere sieht — es gibt kein Late Binding.

Jede der Schichten 2, 4 und 6 ist eine einzige Datei. Die Option, die Variable und die CWD-Suche sind drei Arten, sie zu benennen, in dieser Reihenfolge probiert — und die erste, die gesetzt ist, entscheidet: zeigt eine Option oder Variable auf eine Datei, die nicht existiert, wird nichts geladen, statt zum nächsten Kandidaten weiterzugehen (Issue #996 dreht sich darum, das beim Start zu melden). Eine Variable, die gesetzt, aber leer ist, zählt als nicht gesetzt. Die Variablen enthalten einen Pfad, nie inline HOCON; ein Wert, der nicht der Pfad einer existierenden Datei ist, wird genauso behandelt. Um weitere Dateien zu schichten, setze sie im Code zusammen, wie es Includes werden nicht unterstützt zeigt.

# reference.conf — die Defaults des Projekts, mit dem Code eingecheckt
my-app {
pool-size = 4
db.host = "localhost"
db.url = "postgres://"${my-app.db.host}"/app"
}

Die gebündelte reference.conf enthält die Defaults des Frameworks; ein Projekt hält seine eigenen in einer eigenen reference.conf neben dem Code und lässt application.conf je Deployment einzelne Keys davon überschreiben. Sie darf auch Framework-Keys setzen — etwa einen projektweiten actor-ts.dispatcher — und trägt Profile wie die anderen Dateien. Gelesen wird sie aus dem Arbeitsverzeichnis, sofern nicht referenceConfPath, withReferenceConfigFile oder ACTOR_TS_REFERENCE_CONFIG eine andere Datei nennt.

# .env — von git ignoriert, neben der Anwendung
DB_PASSWORD=s3cret
REDIS_URL="redis://:s3cret@cache:6379"

Eine .env-Datei liefert Variablen für die Substitutionen jeder Datei, die der Loader liest — ${DB_PASSWORD} in application.conf oder in der Secrets-Datei. Gelesen wird sie aus dem Arbeitsverzeichnis, sofern nicht environmentFilePath, withEnvironmentFile oder die echte Variable ACTOR_TS_ENV_FILE eine andere nennt, und false liest keine. Die echte Umgebung gewinnt immer gegen sie, ein leerer Wert darin zählt als nicht gesetzt, und sie schreibt nie in process.env, sodass Kindprozesse sie nicht erben. Sie darf selbst die anderen Dateien und das Profil benennen (ACTOR_TS_CONFIG=…, ACTOR_TS_PROFILE=…), wie es die echte Umgebung kann.

Die Grammatik ist die von Nodes --env-file: KEY=value, ein optionales export, Werte in ', " oder `, die über Zeilen gehen dürfen (ein PEM-Schlüssel passt), \n als Zeilenumbruch nur in doppelten Anführungszeichen, und # beginnt einen Kommentar — ein Wert mit # gehört in Anführungszeichen. $VAR bleibt, wie es dasteht, und wird nie expandiert. Ein Verzeichnis namens .env — oft eine virtuelle Python-Umgebung — ist keine Datei.

Schicht 1 ist reference.conf — aber nicht jede Einstellung hat dort einen Key, und selbst die, die einen haben, brauchen einen Wert im Code für den Fall, dass nichts konfiguriert ist. Dieser Wert hat einen festen Ort, damit immer auffindbar ist, worauf eine Einstellung zurückfällt:

  • Options-Defaults stehen neben dem Feld, das sie belegen, in der passenden XOptions.ts. DEFAULT_MAX_ENTRIES liegt in InMemoryCacheOptions.ts, DEFAULT_NUM_SHARDS in ShardingOptions.ts.
  • Alles andere — Obergrenzen, Schranken und Timeouts ohne Option dahinter — steht in einer Constants.ts: src/<subsystem>/Constants.ts für ein einzelnes Subsystem, src/util/Constants.ts für Werte, die mehrere teilen.

Ein reference.conf-Blatt und sein Code-Fallback sind damit immer genau zwei Dateien, und die zweite ist nach der ersten benannt.

Eine application.conf kann mehrere Umgebungen tragen. Ein Block profiles auf oberster Ebene enthält je Umgebung einen Block, jeweils als Delta zur Wurzel derselben Datei geschrieben:

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}
}

Der Block des aktiven Profils wird über die Wurzel seiner Datei gelegt, jedes andere Profil fällt weg. Gewählt wird es im Code mit withProfile oder über die Umgebungsvariable ACTOR_TS_PROFILE:

import { ActorSystem, ActorSystemOptions } from 'actor-ts';
const actorSystemOptions = ActorSystemOptions.create().withProfile('production');
const system = ActorSystem.create('my-app', actorSystemOptions);
  • Code schlägt die Umgebung. withProfile — profile, wenn du Config.load selbst aufrufst — hat Vorrang vor ACTOR_TS_PROFILE, und ohne beides ist kein Profil aktiv. Ein leerer Name wählt keines; so wählt Code ein Profil ab, das die Umgebung gesetzt hat.
  • Ein unbekanntes Profil wird abgelehnt. Einen Namen, den weder die Anwendungsdatei noch die Secrets-Datei definiert, lehnt der Start ab und nennt die Profile, die es gibt — als „kein Overlay“ gelesen, würde ein vertipptes ACTOR_TS_PROFILE=prodution die Produktion mit den Entwicklungswerten der Wurzel starten. Jedes Profil wird beim Lesen der Datei darauf geprüft, ein Block zu sein, ob aktiv oder nicht.
  • profiles ist auf oberster Ebene reserviert. Der Block wird entfernt, bevor der Baum benutzt wird, sodass ein inaktives Profil nie system.config, den Konfigurations-Dump oder das DevTools-Panel erreicht. Ein Key profiles auf oberster Ebene im config-Objekt, das du im Code übergibst, wird abgelehnt statt ignoriert. my-app.profiles unterhalb der Wurzel ist ein gewöhnlicher Key.
  • Erst wird das Profil darübergelegt, dann werden Substitutionen aufgelöst. Ein Alias in der Wurzel folgt dem Profil: oben liest primary-host unter production den Wert db.internal und ohne Profil localhost. Ein inaktives Profil wird nie aufgelöst, eine Variable, die nur die Produktion braucht, darf auf dem Laptop also fehlen.
  • Ein Profil liest die Wurzel seiner eigenen Datei, die Schichten unter ihr und die Umgebung — nie eine Schicht darüber. Ein Profil der application.conf kann einen Key lesen, den die gebündelte oder die reference.conf des Projekts setzt, aber keinen, den nur die Secrets-Datei setzt, und eine Substitution, die den Block profiles liest, wird mit Namen abgelehnt.
  • staging = ${profiles.production} kopiert ein ganzes Profil, wörtlich. Ein späteres Delta verschmilzt nicht mit der Kopie: ein profiles.staging.my-app.pool-size = 8 danach ersetzt den kopierten Block, und host ist weg. Die Form ${profiles.production} { … }, die verschmelzen würde, wird noch nicht unterstützt (#537) — schreib ein Profil vollständig aus, wenn es von dem abweicht, das es kopieren würde.

withProfile erreicht die Konfiguration des Systems, das damit gebaut wird, also system.config. Einige Komponenten lesen die Konfiguration selbst, wenn ihnen kein System und keine Config übergeben wird: ClusterClient, InMemoryLease, KubernetesLease und WorkerCluster.spawn sowie die exportierten Helfer read…OptionsFromConfig, wenn sie ohne Config aufgerufen werden, darunter readMessageBoundaryOptionsFromConfig, readLeaseOptionsFromConfig, readKubernetesLeaseOptionsFromConfig und readOffloadPoolOptionsFromConfig. Sie rufen Config.load() auf und sehen ein Profil nur über ACTOR_TS_PROFILE — setze die Variable, wenn du sie verwendest, oder übergib ihnen system.config. Ein WorkerMesh übergibt seinem Worker-Pool die system.config des Main-Systems, und seine Worker wählen kein eigenes Profil: Sie laufen mit den Werten, die das Profil des Main-Systems ergeben hat.

Credentials gehören nicht in application.conf. Eine optionale zweite Datei nimmt sie auf; sie wird nach der Anwendungsdatei gelesen und über ihr zusammengeführt:

my-app.db {
user = "app"
password = "s3cr3t"
}
profiles.production.my-app.db.password = ${?PRODUCTION_DB_PASSWORD}

Es ist die erste hiervon, die gesetzt ist: withSecretsFile(path) auf ActorSystemOptions, die Umgebungsvariable ACTOR_TS_SECRETS_CONF, dann secrets.conf im Arbeitsverzeichnis — wer Config.load selbst aufruft, übergibt statt des Settings secretsConfPath, und false liest keine Secrets-Datei.

import { ActorSystem, ActorSystemOptions } from 'actor-ts';
const actorSystemOptions = ActorSystemOptions.create().withSecretsFile('/run/secrets/orders.conf');
const system = ActorSystem.create('orders', actorSystemOptions);

Eine Datei, die nicht da ist, ist eine leere Schicht und kein Fehler; ein Deployment ohne sie braucht also nichts. Eine Datei, die da ist, wird bei jedem Start gelesen — eine secrets.conf im Arbeitsverzeichnis, die zu einem anderen Werkzeug gehört, hält den Start also an: Der ConfigError nennt die Datei und den Grund, aus dem sie gelesen wurde; verschiebe eine solche Datei oder nenne die richtige mit withSecretsFile oder ACTOR_TS_SECRETS_CONF. Sie teilt sich genau wie die Anwendungsdatei in eine Wurzel und profiles, und dasselbe Profil wird über ihre Wurzel gelegt.

Jeder Wert, den sie setzt, wird zurückgehalten — im Konfigurations-Dump wie im DevTools-Panel, egal wie sein Key heißt, oben also auch my-app.db.user —, und das gilt auch, wenn eine höhere Schicht den Key überschreibt, und in einem Worker eines WorkerMesh, der seinen ganzen Baum als ein einziges Overrides-Objekt erhält. Die Kopfzeile des Dumps nennt die Datei, nach der gesucht wurde, und sagt, wenn sie nicht da war.

Halte die Datei aus der Versionskontrolle heraus — secrets.conf in die .gitignore — und binde sie in Produktion aus dem Secret-Store deiner Plattform ein: siehe die Rezepte für Kubernetes und Docker Compose.

Optionswerte werden einmal validiert, zur Consume-Zeit, auf den gemergten Settings — nachdem die obigen Ebenen aufgelöst sind. Weil die Prüfung auf dem gemergten Ergebnis läuft, gelten dieselben Regeln, egal wie ein Wert ankam: über den fluenten Builder, ein einfaches Settings-Objekt oder einen HOCON-Key. Cross-Field-Regeln (z. B. „downThreshold muss unreachableThreshold übersteigen”) sehen die finalen Werte.

Ein ungültiger Wert wirft einen OptionsError (aus dem Paket-Root exportiert), der das betroffene Feld und die Erwartung nennt:

MqttOptions: protocolVersion must be one of 4, 5 (got 6)
  • Bei Broker-Aktoren (MQTT, Kafka, WebSocket-Client, …) wird der Fehler beim Start des Aktors (preStart) geworfen, nach der Pflichtfeld-Prüfung — ein fehlendes Pflichtfeld erscheint also weiterhin als BrokerOptionsError, und nur vorhandene, aber ungültige Werte werden zu OptionsError.
  • Bei Nicht-Broker-Konsumenten (Caches, Leases, Sharding, …) wird der Fehler aus dem Konstruktor geworfen.

OptionsError ist verschieden von ConfigError (fehlerhaftes HOCON — falscher Typ, fehlender Pfad) und BrokerOptionsError (ein Broker-Pflichtfeld fehlt in jeder Ebene). Ungesetzte optionale Felder lösen ihn nie aus; sie fallen auf ihre Defaults zurück.

import { CircuitBreaker, CircuitBreakerOptions, OptionsError } from 'actor-ts';
// Nicht-Broker-Consumer validieren in ihrem Konstruktor, daher wird der
// Fehler synchron geworfen und ein einfaches try/catch funktioniert:
try {
const options = CircuitBreakerOptions.create()
.withMaxFailures(0); // ungültig — muss eine positive Ganzzahl sein
new CircuitBreaker(options); // validiert im Konstruktor
} catch (e) {
if (e instanceof OptionsError) {
console.error(`bad option ${e.field}: ${e.message}`);
}
}
// Bei einem Broker-Actor wird der OptionsError erst in preStart geworfen
// und als ActorInitializationError verpackt — er taucht also über die
// Supervision auf (nicht im try/catch des Spawn-Aufrufs).