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:
- Konstruktor-Argumente an
ActorSystem.create(name, settings)— explizite Felder wieloggeroderlogLevel, die jeden Key schlagen. - Das inline
config-Objekt in den Settings — die Code-Overrides, über jeder Datei. - Die Secrets-Datei —
secrets.conf, optional, mit ihrem aktiven Profil (Secrets-Datei). - Die Anwendungsdatei —
application.confim Projekt-Root, oder ein expliziter Pfad viaconfigFile, mit ihrem aktiven Profil (Profile). - Die Defaults des Projekts — seine eigene
reference.conf, optional, mit ihrem aktiven Profil (Die reference.conf des Projekts). - Reference-Defaults — im Framework gebündelt als
REFERENCE_CONF(siehesrc/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.
Eine typische application.conf
Abschnitt betitelt „Eine typische application.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.
Die Keys, gruppiert nach Modul
Abschnitt betitelt „Die Keys, gruppiert nach Modul“actor-ts.system
Abschnitt betitelt „actor-ts.system“| Key | Default | Zweck |
|---|---|---|
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-timeout | 2s | Wie 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. |
actor-ts.logger
Abschnitt betitelt „actor-ts.logger“| Key | Default | Zweck |
|---|---|---|
logger.level | "info" | Einer von debug / info / warn / error / off. |
actor-ts.actor
Abschnitt betitelt „actor-ts.actor“| Key | Default | Zweck |
|---|---|---|
actor.throughput | 16 | User-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-timeout | 5s | Frist, 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.
actor-ts.diagnostics
Abschnitt betitelt „actor-ts.diagnostics“| Key | Default | Zweck |
|---|---|---|
diagnostics.log-dead-letters | 10 | Dead 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-shutdown | off | Den 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-duration | 5m | Wie 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-start | off | Schreibt 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.unhandled | off | Ein 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.lifecycle | off | Ein 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-stream | off | Ein 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.
actor-ts.mailbox
Abschnitt betitelt „actor-ts.mailbox“| Key | Default | Zweck |
|---|---|---|
mailbox.default.capacity | 0 | Begrenzt 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.
actor-ts.deployment
Abschnitt betitelt „actor-ts.deployment“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 }}| Key | Default | Zweck |
|---|---|---|
deployment."<path>".throughput | ungesetzt | User-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-capacity | ungesetzt | Eingereihte 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-overflow | ungesetzt | drop-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.
actor-ts.dispatcher
Abschnitt betitelt „actor-ts.dispatcher“| Key | Default | Zweck |
|---|---|---|
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.throughput | 16 | Eingereihte 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. |
actor-ts.dead-letters
Abschnitt betitelt „actor-ts.dead-letters“| Key | Default | Zweck |
|---|---|---|
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-entries | 1000 | Aufbewahrte Letters, bevor das älteste verdrängt wird. Von off und metrics ignoriert, die keine aufbewahren. |
dead-letters.retention | 1h | Letters nach dieser Zeit altern lassen. 0 schaltet das Altern ab und lässt max-entries als einzige Schranke. |
dead-letters.max-replays | 3 | Wie 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.
actor-ts.cluster
Abschnitt betitelt „actor-ts.cluster“| Key | Default | Zweck |
|---|---|---|
cluster.gossip-interval | 1s | Wie 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-interval | 3s | Wie oft Seed-Verbindungen während des Joins wiederholt werden. |
cluster.weakly-up-after | 0s | Befördert ein joining-Mitglied nach dieser Zeit automatisch zu weakly-up. 0 schaltet das ab — siehe Weakly-up. |
cluster.publish-stats-interval | 0s | Wie oft dieser Node eine ClusterStatsPublished-Momentaufnahme seines Mitgliederbilds auf system.eventStream veröffentlicht. 0 startet keinen Timer — siehe unten. |
cluster.shutdown-after-unsuccessful-join | 0s | Wie 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-members | 1000 | Obergrenze für lebende Mitgliedseinträge, die Gossip anlegen darf. 0 schaltet die Grenze ab. |
cluster.max-tombstones | 10000 | Obergrenze für removed-Tombstones, die Gossip anlegen darf. 0 schaltet die Grenze ab. |
cluster.minimum-members-before-up | 1 | Mitglieder, 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-down | on | Was 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-island | off | Treffen 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-live | 24h | Wie lange ein removed-Tombstone gehalten wird, bevor er gepruned wird. |
cluster.tombstone.prune-interval | 5m | Wie oft der Prune-Durchlauf läuft. |
cluster.tombstone.min-retention | 0s | Mindestalter, bevor ein Tombstone gepruned werden darf. 0 leitet es aus failure-detector.down-after ab (6×). |
cluster.failure-detector.implementation | simple | Welchen Erkennungsalgorithmus dieser Node fährt — simple (Zeitschwellen) oder phi (varianzbewusstes φ-Accrual). |
cluster.failure-detector.heartbeat-interval | 500ms | Wie oft Heartbeats gesendet werden. Gilt für beide Implementierungen — siehe unten. |
cluster.failure-detector.unreachable-after | 2s | Verdachtsschwelle für unreachable-Status. Nur simple. |
cluster.failure-detector.down-after | 5s | Stille, 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-down | on | Was 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-threshold | 8 | φ-Wert, ab dem der Peer als unreachable gilt. Ein kontinuierlicher Score, Nachkommastellen sind also erlaubt. |
cluster.failure-detector.phi.down-threshold | 12 | φ-Wert, ab dem der Peer als down gilt. Muss größer als phi.unreachable-threshold sein. |
cluster.failure-detector.phi.max-sample-size | 200 | Wie viele jüngste Zwischenankunftszeiten pro Peer behalten werden. |
cluster.failure-detector.phi.min-std-deviation | 100ms | Untergrenze für die gemessene Standardabweichung, damit ein sehr gleichmäßiger Peer nicht wegen Rauschen auffällt. |
cluster.failure-detector.phi.acceptable-heartbeat-pause | 3s | Kulanz 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-strategy | off | Welche Downing-Strategie eine Partition entscheidet — off, keep-majority, keep-oldest, keep-referee, static-quorum oder lease-majority. |
cluster.split-brain-resolver.stable-after | 20s | Wie 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-unstable | off | Alle 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-alone | on | Ob 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.enforce | off | Was 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.
Der eigenständige ClusterClient
Abschnitt betitelt „Der eigenständige ClusterClient“| Key | Default | Zweck |
|---|---|---|
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-timeout | 5s | Frist für ask(path, message), wenn der Aufruf selbst keine nennt. Ein timeoutMs pro Aufruf gewinnt weiterhin. |
cluster.client.connect-timeout | 5s | Wie 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-timeout | 5s | Frist 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.
actor-ts.cluster.singleton
Abschnitt betitelt „actor-ts.cluster.singleton“| Key | Default | Zweck |
|---|---|---|
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-size | 1000 | Nachrichten, die ein Proxy hält, solange der Cluster keinen Host hat, bevor er die neuesten in die Dead Letters gibt. |
cluster.singleton.hand-over-timeout | 10s | Wie 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-lease | off | Gibt 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-interval | 5s | Wie 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-bytes | 1M | Obergrenze für einen Warm-Hand-over-Snapshot. Ein größerer wird nicht gesendet, und der Nachfolger startet kalt. |
cluster.singleton.restart-on-termination | on | Startet 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.
actor-ts.cluster.pub-sub
Abschnitt betitelt „actor-ts.cluster.pub-sub“| Key | Default | Zweck |
|---|---|---|
cluster.pub-sub.gossip-interval | 1s | Wie oft ein Mediator seine Topic-Menge an einen zufälligen Peer schickt. |
cluster.pub-sub.max-subscribers-per-topic | 10000 | Obergrenze für lokale Subscriber eines Topics. Ein Subscribe darüber wird mit SubscribeRejected beantwortet. |
cluster.pub-sub.max-topics | 10000 | Obergrenze 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-topic | 1000 | Obergrenze für Peers, die Subscriber für ein Topic beanspruchen dürfen. |
cluster.pub-sub.send-to-dead-letters-when-no-subscribers | on | Ein 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.
actor-ts.cluster.receptionist
Abschnitt betitelt „actor-ts.cluster.receptionist“| Key | Default | Zweck |
|---|---|---|
cluster.receptionist.gossip-interval | 1s | Wie oft der Receptionist seine lokalen Registrierungen gossipt. |
cluster.receptionist.max-subscribers-per-key | 1000 | Obergrenze für Subscriber eines Service Keys. Ein Subscribe darüber wird mit ReceptionistSubscribeRejected beantwortet. |
cluster.receptionist.max-subscriptions-total | 10000 | Obergrenze 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.
actor-ts.distributed-data
Abschnitt betitelt „actor-ts.distributed-data“| Key | Default | Zweck |
|---|---|---|
distributed-data.gossip-interval | 1s | Wie oft eine Replika ihren Key-Satz an einen zufälligen Peer schickt. |
distributed-data.quorum-timeout | 5s | Frist 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-requests | 1000 | Obergrenze 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-timeout | 30s | Obergrenze 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-bytes | 1M | Byte-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-exceeding | 100K | Warnt (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.
actor-ts.coordination
Abschnitt betitelt „actor-ts.coordination“| Key | Default | Zweck |
|---|---|---|
coordination.lease.backend | none | Womit 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-interval | 1m | Wie 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-timeout | 10s | Obergrenze für einen einzelnen Request an den API-Server. |
coordination.lease.kubernetes.lease-name-max-length | 253 | Lease-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.
Leases, die das Framework baut
Abschnitt betitelt „Leases, die das Framework baut“Drei Konsumenten verlangen einen Lease per Konfiguration, und alle drei bekommen ihn aus diesem Block:
| Schalter | Lease-Name | Abgelehnt, falls falsch konfiguriert, wenn |
|---|---|---|
sharding.use-lease = on | <system>-sharding-<type>, einer pro geshardetem Typ | der Typ startet |
cluster.singleton.use-lease = on | <system>-singleton-<type>, einer pro Singleton | das Singleton startet |
split-brain-resolver.active-strategy = lease-majority | <system>-split-brain-resolver, einer pro Cluster | der Node seinem Cluster beitritt |
actor-ts.coordination.lease { backend = kubernetes ttl = 15s}actor-ts.cluster.singleton.use-lease = onDie 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.
actor-ts.cluster.bootstrap
Abschnitt betitelt „actor-ts.cluster.bootstrap“| Key | Default | Zweck |
|---|---|---|
cluster.bootstrap.stable-margin | 5s | Wie lange die Contact-Point-Menge unverändert bleiben muss, bevor die Observation sie stabil nennt. |
cluster.bootstrap.poll-interval | 1s | Wie oft Discovery während der Observation abgefragt wird. |
cluster.bootstrap.max-wait | 60s | Gesamtbudget der Observation, bevor sie aufgibt und den Bootstrap scheitern lässt. |
cluster.bootstrap.required-contact-points | 1 | Wie 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-grace | 10s | Wie lange der niedrigst-adressierte Knoten auf eine Promotion durch einen Peer wartet, bevor er selbst einen Cluster bildet. |
cluster.bootstrap.new-cluster-enabled | on | Ob 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-members | 1 | Wie 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.
actor-ts.discovery
Abschnitt betitelt „actor-ts.discovery“| Key | Default | Zweck |
|---|---|---|
discovery.dns.cache-ttl | 60s | Wie 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-srv | false | SRV-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-timeout | 10s | Obergrenze 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.
Wo die Umgebungsvariablen sitzen
Abschnitt betitelt „Wo die Umgebungsvariablen sitzen“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 DefaultsDas 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.
actor-ts.remote
Abschnitt betitelt „actor-ts.remote“| Key | Default | Zweck |
|---|---|---|
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-bytes | 16M | Wire-Cap pro Frame. Ein Frame, dessen Längen-Präfix darüber liegt, wird verworfen, bevor irgendeine Payload gepuffert wird. |
remote.tls.enabled | false | Nicht umgesetzt — true bringt eine Startup-Warnung, keine Verschlüsselung. Siehe unten. |
remote.untrusted-mode | false | Ein 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-timeout | 5s | Wie 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-size | 1000 | Wie viele Frames für einen Peer gehalten werden, der sie gerade nicht annehmen kann; die ältesten fallen zuerst weg. |
remote.max-inbound-connections | 1024 | Wie viele eingehende Verbindungen dieser Knoten annimmt, bevor er Sockets rundheraus ablehnt — abgelehnt wird die neueste, nicht die älteste verdrängt. |
remote.incomplete-frame-idle | 30s | Wie 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, 2552Ein 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.
Wen ein Peer namentlich adressieren darf
Abschnitt betitelt „Wen ein Peer namentlich adressieren darf“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.
Der Assoziations-Lebenszyklus
Abschnitt betitelt „Der Assoziations-Lebenszyklus“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.
actor-ts.http
Abschnitt betitelt „actor-ts.http“| Key | Default | Zweck |
|---|---|---|
http.backend | "fastify" | Einer von fastify / express / hono. |
http.shutdown-grace-period | 0ms | Wie 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:
| Key | Default | Zweck |
|---|---|---|
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-timeout | 60s | Wie 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-timeout | 300s | Wie 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:
| Key | Default | Zweck |
|---|---|---|
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.credentials | false | Access-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:
| Key | Default | Zweck |
|---|---|---|
http.hsts.max-age | 15552000 | Wie 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-domains | true | includeSubDomains senden. |
http.hsts.preload | false | preload 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:
| Key | Default | Zweck |
|---|---|---|
http.request-timeout.deadline | 30s | Wie 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:
| Key | Default | Zweck |
|---|---|---|
http.client.max-response-bytes | 8M | Größter Response-Body, der gepuffert wird, bevor der Request abgebrochen wird. |
http.client.default-timeout | 30s | Deadline 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-redirects | 5 | Hops, 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:
| Key | Default | Zweck |
|---|---|---|
http.websocket.max-frame-bytes | 1M | Größ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-bytes | 4M | Outbound-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-frames | 256 | Eingehende Frames, die gehalten werden, während der Connection-Actor startet. |
http.websocket.max-pre-attach-bytes | 4M | Bytes, die gehalten werden, während der Connection-Actor startet; jenseits einer der beiden Grenzen wird der Socket mit 1013 geschlossen. |
http.websocket.accept-timeout | 10s | Wie 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.
actor-ts.reliable-delivery
Abschnitt betitelt „actor-ts.reliable-delivery“| Key | Default | Zweck |
|---|---|---|
reliable-delivery.producer.resend-timeout | 500ms | Wie 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-size | 16 | Flow-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-producers | 1024 | Fü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-live | 5m | Wie 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-order | 1024 | Wie 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.
actor-ts.serialization
Abschnitt betitelt „actor-ts.serialization“| Key | Default | Zweck |
|---|---|---|
serialization.read-constraints.max-nesting-depth | 256 | Container-Ebenen, in die ein Decoder absteigt, bevor er das Payload ablehnt. Nie über die eigene Obergrenze des Encoders hinaus. |
serialization.read-constraints.max-document-bytes | 0 | Obergrenze 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-length | 20M | Obergrenze 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.
actor-ts.management
Abschnitt betitelt „actor-ts.management“| Key | Default | Zweck |
|---|---|---|
management.enable-leave-endpoint | false | POST /cluster/leave ausliefern (HTTP-Endpunkte). |
management.enable-down-endpoint | false | POST /cluster/down ausliefern — operator-initiiertes Force-Down eines Peers. |
management.enable-metrics-endpoint | false | GET /metrics im Prometheus-Textformat ausliefern. |
management.auth-protect-health | false | Die 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-timeout | 1s | Deadline 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.
actor-ts.metrics
Abschnitt betitelt „actor-ts.metrics“| Key | Default | Zweck |
|---|---|---|
metrics.max-series-per-family | 10000 | Wie 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.
actor-ts.tracing
Abschnitt betitelt „actor-ts.tracing“| Key | Default | Zweck |
|---|---|---|
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.
actor-ts.persistence
Abschnitt betitelt „actor-ts.persistence“| Key | Default | Zweck |
|---|---|---|
persistence.max-concurrent-recoveries | 50 | Journal-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-timeout | 30s | Obergrenze 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-optional | false | Auf 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-start | on | Journal, 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-n | 0 | Snapshots, 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.wal | off | Datenbank mit journal_mode = WAL öffnen — parallele Leser während eines Schreibvorgangs. |
persistence.journal.sqlite.busy-timeout | 1s | Wie 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-n | 3 | Aufbewahrte Snapshots pro persistenceId; 0 schaltet das Pruning ab. |
persistence.snapshot-store.sqlite.busy-timeout | 1s | Wie 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-tables | on | CREATE 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-timeout | 1s | Wie 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-n | 3 | Aufbewahrte Snapshots pro persistenceId; 0 schaltet das Pruning ab. |
persistence.snapshot-store.object-storage.max-decompressed-bytes | 512M | Schutz 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-style | off | Path-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-timeout | 5s | Wartezeit auf ein Write-Lock pro Key, bevor abgebrochen wird. |
persistence.snapshot-store.object-storage.filesystem.stale-lock | 30s | Lock-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 = 10sEin 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.
PostgreSQL
Abschnitt betitelt „PostgreSQL“| Key | Default | Zweck |
|---|---|---|
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-tables | on | CREATE 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-n | 3 | Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab. |
persistence.snapshot-store.postgres.auto-create-tables | on | Wie 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-tables | on | Wie oben. |
persistence.durable-state.postgres.max-pool-size, idle-timeout, connect-timeout, ca-file | (ungesetzt) | Wie oben. |
MariaDB / MySQL
Abschnitt betitelt „MariaDB / MySQL“| Key | Default | Zweck |
|---|---|---|
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-tables | on | CREATE 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-n | 3 | Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab. |
persistence.snapshot-store.mariadb.auto-create-tables | on | Wie 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-tables | on | Wie oben. |
persistence.durable-state.mariadb.max-pool-size, acquire-timeout, idle-timeout, connect-timeout, ca-file | (ungesetzt) | Wie oben. |
SQL Server
Abschnitt betitelt „SQL Server“| Key | Default | Zweck |
|---|---|---|
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-tables | on | CREATE 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-n | 3 | Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab. |
persistence.snapshot-store.mssql.auto-create-tables | on | Wie 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-tables | on | Wie oben. |
persistence.durable-state.mssql.max-pool-size, idle-timeout, connect-timeout, request-timeout, ca-file | (ungesetzt) | Wie oben. |
libSQL / Turso
Abschnitt betitelt „libSQL / Turso“| Key | Default | Zweck |
|---|---|---|
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-tables | on | CREATE 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-n | 3 | Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab. |
persistence.snapshot-store.libsql.auto-create-tables | on | Wie 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-tables | on | Wie oben. |
Cloudflare D1
Abschnitt betitelt „Cloudflare D1“| Key | Default | Zweck |
|---|---|---|
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.timeout | 30s | Frist 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-bytes | 64M | Obergrenze 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-tables | on | CREATE 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.timeout | 30s | Wie oben. |
persistence.snapshot-store.cloudflare-d1.max-response-bytes | 64M | Wie oben. |
persistence.snapshot-store.cloudflare-d1.snapshots-table | "snapshots" | Snapshot-Tabelle. |
persistence.snapshot-store.cloudflare-d1.keep-n | 3 | Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab. |
persistence.snapshot-store.cloudflare-d1.auto-create-tables | on | Wie 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.timeout | 30s | Wie oben. |
persistence.durable-state.cloudflare-d1.max-response-bytes | 64M | Wie oben. |
persistence.durable-state.cloudflare-d1.table | "durable_state" | Durable-State-Tabelle. |
persistence.durable-state.cloudflare-d1.auto-create-tables | on | Wie 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.
MongoDB
Abschnitt betitelt „MongoDB“| Key | Default | Zweck |
|---|---|---|
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-indexes | on | Indizes 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-n | 3 | Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab. |
persistence.snapshot-store.mongodb.auto-create-indexes | on | Wie 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.
DynamoDB
Abschnitt betitelt „DynamoDB“| Key | Default | Zweck |
|---|---|---|
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-timeout | 30s | Wie lange eine Tabelle, die der Store gerade angelegt hat, brauchen darf, bis sie ACTIVE ist. |
persistence.journal.dynamodb.auto-create-tables | on | CreateTable, 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-n | 3 | Pro 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-timeout | 30s | Wie oben. |
persistence.snapshot-store.dynamodb.auto-create-tables | on | Wie 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-timeout | 30s | Wie oben. |
persistence.durable-state.dynamodb.auto-create-tables | on | Wie 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.
Cassandra / ScyllaDB
Abschnitt betitelt „Cassandra / ScyllaDB“| Key | Default | Zweck |
|---|---|---|
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.port | 9042 | CQL-Native-Transport-Port. |
persistence.journal.cassandra.auto-create-keyspace | off | CREATE 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-factor | 1 | Kopien 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-size | 500000 | Zeilen pro Partition, bevor auf eine neue umgebrochen wird. |
persistence.journal.cassandra.auto-create-tables | on | Die vier Tabellen anlegen, wenn der Store sich verbindet — beim Start, sofern persistence.auto-start nicht abgeschaltet ist. |
persistence.journal.cassandra.use-tag-index | off | Eine events_by_tag-Side-Table mitschreiben, damit Tag-Queries eine Partition lesen. |
persistence.journal.cassandra.lightweight-transactions | on | Den 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.port | 9042 | Wie oben. |
persistence.snapshot-store.cassandra.auto-create-keyspace | off | Wie oben. |
persistence.snapshot-store.cassandra.replication.class | "simple-strategy" | Wie oben. |
persistence.snapshot-store.cassandra.replication.replication-factor | 1 | Wie 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-n | 3 | Pro persistenceId aufbewahrte Snapshots; 0 schaltet das Pruning ab. |
persistence.snapshot-store.cassandra.auto-create-tables | on | Wie 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.
actor-ts.circuit-breaker
Abschnitt betitelt „actor-ts.circuit-breaker“| Key | Default | Zweck |
|---|---|---|
circuit-breaker.default.max-failures | 10 | Aufeinanderfolgende Fehler, bis ein Breaker öffnet (Circuit Breaker). |
circuit-breaker.default.reset-timeout | 15s | Wie lange er offen bleibt, bevor er eine Probe durchlässt. |
circuit-breaker.default.max-reset-timeout | 60s | Obergrenze des gewachsenen Fensters. Muss mindestens reset-timeout sein — ein Breaker, dessen gemergte Settings das verletzen, startet nicht. |
circuit-breaker.default.backoff-factor | 1.0 | Multiplikator je aufeinanderfolgendem Öffnen. 1.0 = das flache Fenster jedes früheren Releases. |
circuit-breaker.default.random-factor | 0.0 | Jitter-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.
actor-ts.projection
Abschnitt betitelt „actor-ts.projection“| Key | Default | Zweck |
|---|---|---|
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-retries | 3 | Retry-Budget der beiden retry-*-Strategien — Versuche nach dem ersten. |
projection.retry-backoff | 1s | Verzögerung vor dem ersten Retry; verdoppelt sich mit jedem weiteren Versuch. |
projection.max-retry-backoff | 60s | Obergrenze dieser Verdopplung. Muss mindestens retry-backoff sein — eine Projektion, deren gemergte Settings das verletzen, startet nicht. |
projection.poll-interval | 1s | Wie oft eine Projektion das Journal nach neuen Events fragt. |
projection.group-after-envelopes | 20 | Hö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.
actor-ts.backoff-supervisor
Abschnitt betitelt „actor-ts.backoff-supervisor“| Key | Default | Zweck |
|---|---|---|
backoff-supervisor.min-backoff | 200ms | Untergrenze der Respawn-Verzögerung — und das Fenster, an dem after-min-stable die Stabilität eines Kindes misst (Backoff-Supervisor). |
backoff-supervisor.max-backoff | 10s | Obergrenze, auf die die Verdopplung geklemmt wird. Muss mindestens min-backoff sein — ein Supervisor, dessen gemergte Settings das verletzen, startet nicht. |
backoff-supervisor.random-factor | 0.2 | Jitter-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-size | 1000 | Nachrichten, 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-grace | true | Ob 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.
actor-ts.cache
Abschnitt betitelt „actor-ts.cache“| Key | Default | Zweck |
|---|---|---|
cache.in-memory.max-entries | 10000 | Max. Einträge vor LRU-Eviction (In-Memory-Cache). |
cache.in-memory.cleanup-interval | 60s | Intervall 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-live | 0 | Lebensdauer, die ein set / mset ohne eigenes ttlMs bekommt. 0 = kein Ablauf, also das bisherige Verhalten. |
cache.in-memory.time-to-idle | 0 | Ein 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.db | 0 | Logische 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.
actor-ts.sharding
Abschnitt betitelt „actor-ts.sharding“| Key | Default | Zweck |
|---|---|---|
sharding.number-of-shards | 64 | In 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-interval | 2s | Abstand zwischen koordinator-getriebenen Rebalance-Passes. |
sharding.hand-off-timeout | 10s | Wie lange auf HandOffComplete gewartet wird, bevor zwangsumverteilt wird. |
sharding.persist-coordinator-state | off | Hä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-timeout | 10s | Wie lange ein neuer Leader auf das Laden dieser Karte wartet, bevor er ohne sie platziert. |
sharding.rebalance-absolute-limit | 0 | Feste 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-limit | 0.1 | Dieselbe 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-interval | 5s | Wie 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-lease | off | Gibt 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-entities | false | Persistiere die Menge aktiver Entity-IDs. |
sharding.passivation-idle | 5m | Auto-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-entities | 0 | Entity-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.replacement | least-recently-used | Welche 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-proportion | 0.8 | Anteil 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-proportion | 0.0 | Anteil des Caps, der als Bewährungsfenster vor der Strategie reserviert wird. 0 = kein Fenster. Vom admission-filter vorausgesetzt. |
sharding.passivation.admission-filter | off | frequency-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-timeout | 0ms | Wie 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-size | 100000 | Wie 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-interval | 500ms | Wie 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-timeout | 5s | Default-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.strategy | all | Wie 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.frequency | 100ms | Abstand zwischen zwei gedrosselten Recovery-Batches. Unter strategy = all wirkungslos. |
sharding.entity-recovery.constant-rate.number-of-entities | 5 | Wie 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.enabled | off | Lä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-interval | 5s | Abstand zwischen zwei Schlägen Region → Koordinator. Pro Sharded Type, nicht pro Node. Bei enabled = off wirkungslos. |
sharding.stale-region-detection.stale-after | 20s | Stille, 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.min | 200ms | Erste 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.max | 10s | Die Obergrenze, bei der die verdoppelte Wartezeit stehen bleibt. Darf nicht unter min liegen. |
sharding.shard-failure-backoff.random-factor | 0.2 | Jede 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-after | 60s | Ein 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.min | 200ms | Erste 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.max | 10s | Die Obergrenze, bei der die verdoppelte Wartezeit stehen bleibt. Darf nicht unter min liegen. |
sharding.entity-restart-backoff.random-factor | 0.2 | Jede 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-after | 60s | Eine 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)Eine Rolle wird benannt, nicht vergeben
Abschnitt betitelt „Eine Rolle wird benannt, nicht vergeben“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.
Einen Remember-Entities-Restore drosseln
Abschnitt betitelt „Einen Remember-Entities-Restore drosseln“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, derentwegenmax-entitiesregionsweit 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-recoverieseine 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.
Rebalance-Churn begrenzen
Abschnitt betitelt „Rebalance-Churn begrenzen“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 ganzeshand-off-timeoutstehen 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.
Eine verstummte Region erkennen
Abschnitt betitelt „Eine verstummte Region erkennen“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-aftererneut 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-aftermuss größer alsheartbeat-intervalsein, 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 beisharding.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.
Wählen, was ein voller Node hergibt
Abschnitt betitelt „Wählen, was ein voller Node hergibt“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-usedteilt 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-proportionreserviert 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-sketchist 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.
actor-ts.coordinated-startup
Abschnitt betitelt „actor-ts.coordinated-startup“| Key | Default | Zweck |
|---|---|---|
coordinated-startup.default-phase-timeout | 30s | Budget 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.
actor-ts.coordinated-shutdown
Abschnitt betitelt „actor-ts.coordinated-shutdown“| Key | Default | Zweck |
|---|---|---|
coordinated-shutdown.default-phase-timeout | 5s | Default-Timeout pro Phase. Eine Phase, die es überschreitet, wird abgebrochen, damit die nächste noch läuft. |
coordinated-shutdown.terminate-actor-system | true | Ob der eingebaute Terminator-Task das Actor-System in der finalen Phase herunterfährt. |
coordinated-shutdown.exit-process | false | Ob 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-code | 0 | Status, 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-tasks | true | Ob 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-signals | true | Ob runUntilTerminated() und der Cluster-Bootstrap SIGTERM/SIGINT scharfschalten, wenn der Aufrufer keine Signale genannt hat. |
coordinated-shutdown.run-by-actor-system-terminate | false | Ob 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.
actor-ts.sharded-daemon-process
Abschnitt betitelt „actor-ts.sharded-daemon-process“| Key | Default | Zweck |
|---|---|---|
sharded-daemon-process.liveness-interval | 30s | Takt 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 itname, 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 alongEine 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 nodesactor-ts.sharded-daemon-process.role = "batch" # daemons on the batch nodesDerselbe 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.
actor-ts.devtools
Abschnitt betitelt „actor-ts.devtools“| Key | Default | Zweck |
|---|---|---|
devtools.host | "127.0.0.1" | Interface, an das attach bindet. Alles Routbare wird abgelehnt, solange nichts davor sitzt — siehe unten. |
devtools.port | 9333 | Port, an den gebunden wird; 0 lässt das Betriebssystem einen freien wählen, das zurückgegebene Binding meldet welchen. |
devtools.allow-remote | false | Bestätigt einen ungeschützten Bind auf einem routbaren Interface. |
devtools.serve-ui | true | false 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.actors | true | Aktor-Baum, Mailbox-Tiefen und Cell-Zustände. |
devtools.panels.cluster | true | Cluster-Topologie, Shard-Maps, Membership-Timeline. |
devtools.panels.tracing | true | Span-Flamegraph und -Wasserfall — seine Payload-Spalte trägt jede Actor-Nachricht, die während des DevTools-Attach vorbeikam, serialisiert. |
devtools.panels.explain | true | Explain-Plan pro Aktor. |
devtools.panels.time-travel | true | Journal-Browsing und State-Rekonstruktion — das Panel, das rohe persistierte Events zeigt. |
devtools.panels.profiler | true | Aktor-Profiler. |
devtools.panels.dead-letters | true | Unzustellbare Nachrichten, inklusive Payload. |
devtools.panels.event-stream | true | Live-Tail von Event-Bus und Cluster-PubSub-Topics, inklusive Payload. |
devtools.panels.config | true | Aufgelöste Konfiguration mit der Quelle jedes Keys (Werte, deren Key ein Geheimnis benennt, werden redigiert). |
devtools.panels.send | true | Die Ansicht zum Nachrichtenversand. Die Fähigkeit dahinter ist ein eigener, nur im Code setzbarer Schalter. |
devtools.mailbox-sample-interval | 1s | Wie oft Aktor-Baum, Mailbox-Tiefen und Cell-Zustände neu abgetastet werden. |
devtools.mailbox-sample-limit | 50 | Wie viele Mailboxen ein Sample trägt. |
devtools.stats-interval | 1s | Wie oft die Dashboard-Kennzahlen abgetastet werden. |
devtools.span-buffer-capacity | 10000 | Obergrenze der gehaltenen Spans, in Nachrichten. |
devtools.span-flush-interval | 250ms | Wie oft gepufferte Spans ans Panel geflusht werden. |
devtools.capture-payloads | true | false 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-capacity | 500 | Events, die der Bus-Tail zwischen zwei Flushes puffert; darüber fallen die ältesten weg und das Panel erfährt, wie viele. |
devtools.event-flush-interval | 250ms | Wie oft gepufferte Events ans Panel geflusht werden. |
devtools.replay-auto-capture | true | Leiht 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üssel | Default | Zweck |
|---|---|---|
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-size | 0 | Worker, die über Leerlauf hinweg am Leben bleiben. |
offload-pool.max-queue | 10000 | Tasks, 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-timeout | 60s | Ein Worker jenseits von min-size ohne Arbeit wird danach abgebaut. |
offload-pool.task-timeout | 0s | 0 = keine Deadline, außer run() nennt eine. Eine Deadline terminiert den Worker. |
offload-pool.max-restarts | 10 | Worker-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-window | 60s | Das Fenster, über das das Restart-Budget zählt. |
offload-pool.warm-up | off | Jeden 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üssel | Default | Zweck |
|---|---|---|
parallelism.workers | 0 | 0 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-timeout | 10s | Wie lange ein Spawn auf die Bestätigung seines Workers wartet, bevor die Ref fehlschlägt. |
parallelism.buffer-size | 100000 | Nachrichten, 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.
actor-ts.worker-cluster (Multi-Runtime-Worker)
Abschnitt betitelt „actor-ts.worker-cluster (Multi-Runtime-Worker)“| Key | Default | Zweck |
|---|---|---|
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-port | 1 | Port des ersten Workers; jeder weitere Slot inkrementiert. |
worker-cluster.ready-timeout | 10s | Frist für den Hello/Init/Ready-Handshake pro Worker. |
worker-cluster.restart-policy | "on-failure" | always / on-failure / never. |
worker-cluster.restart-min-backoff | 200ms | Wartezeit vor dem ersten Respawn eines abgestürzten Slots. |
worker-cluster.restart-max-backoff | 10s | Obergrenze für die Respawn-Wartezeit, die pro Versuch verdoppelt wird. |
worker-cluster.restart-random-factor | 0.2 | ±-Jitter-Anteil auf jede Respawn-Wartezeit, in [0, 1]. |
worker-cluster.max-restarts | 10 | Restarts pro Slot innerhalb des Fensters, bevor er stillgelegt wird; -1 startet unbegrenzt neu. |
worker-cluster.restart-window | 60s | Gleitendes 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)“| Key | Default | Zweck |
|---|---|---|
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-port | 1 | Port-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-port | 2 | Port 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-interval | 10s | Wie 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.
Broker-Plugins — actor-ts.io.broker.*
Abschnitt betitelt „Broker-Plugins — actor-ts.io.broker.*“Jeder Broker-Actor liest aus seinem eigenen Subtree. Siehe die per-Protokoll-Seiten für die Keys des jeweiligen Protokolls:
| Subtree | Seite |
|---|---|
io.broker.kafka | Kafka |
io.broker.mqtt | MQTT |
io.broker.amqp | AMQP |
io.broker.nats | NATS |
io.broker.jetstream | NATS JetStream |
io.broker.jetstream-key-value | JetStream KV + Object Store |
io.broker.jetstream-object-store | JetStream KV + Object Store |
io.broker.redis-streams | Redis Streams |
io.broker.grpc.{client,server} | gRPC |
io.broker.websocket | WebSocket Client |
io.broker.sse | SSE |
io.broker.tcp | TCP |
io.broker.tcp-server | TCP |
io.broker.udp | UDP |
io.broker.email-bridge | E-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.
HOCON-spezifische Syntax
Abschnitt betitelt „HOCON-spezifische Syntax“Durations
Abschnitt betitelt „Durations“gossip-interval = 1s # 1000 msunreachable-after = 2.5s # 2500 msdown-after = 5000ms # explizite msgc-cadence = 10m # Minutenttl = 24h # StundenErkannte Einheiten, unabhängig von Groß- und Kleinschreibung, mit oder ohne Leerzeichen davor:
| Größenordnung | Schreibweisen |
|---|---|
| Nanosekunden | ns nano nanos nanosecond nanoseconds |
| Mikrosekunden | us μs micro micros microsecond microseconds |
| Millisekunden | ms milli millis millisecond milliseconds |
| Sekunden | s sec secs second seconds |
| Minuten | m min mins minute minutes |
| Stunden | h hr hrs hour hours |
| Tage | d 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;constructorwird 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ärupload-limit = 16MB # 16 000 000 Bytes — dezimalbuffer = 64Kheap = 2GErkannte Einheiten, unabhängig von Groß- und Kleinschreibung, mit oder ohne Leerzeichen davor:
| Größenordnung | Binär (1024) | Dezimal (1000) |
|---|---|---|
| Bytes | B byte bytes | — |
| Kilo | K KiB kibibyte kibibytes | KB kilobyte kilobytes |
| Mega | M MiB mebibyte mebibytes | MB megabyte megabytes |
| Giga | G GiB gibibyte gibibytes | GB gigabyte gigabytes |
| Tera | T TiB tebibyte tebibytes | TB terabyte terabytes |
| Peta | P PiB pebibyte pebibytes | PB petabyte petabytes |
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.
Environment-Substitution
Abschnitt betitelt „Environment-Substitution“port = ${?ACTOR_TS_PORT} # nutze env, falls gesetzt, sonst fallbacklog-level = ${?LOG_LEVEL} # gleichapi-key = ${API_KEY} # required — Fehler, wenn env nicht gesetztfallback-port = 2552 # der Default …fallback-port = ${?ENV_PORT} # … nur ersetzt, wenn ENV_PORT gesetzt istVerwende ${?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.
Leere Werte
Abschnitt betitelt „Leere Werte“host = # nichts dahinter — keine Zuweisung, host behält seinen Werthost = ${?DB_HOST} # DB_HOST nicht gesetzt oder leer — host behält seinen Werthost = ${DB_HOST} # DB_HOST nicht gesetzt oder leer — der Start scheiterthost = "" # ein ausdrücklich leerer Stringroles = [] # eine ausdrücklich leere ListeEine 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.
Wert-Konkatenation
Abschnitt betitelt „Wert-Konkatenation“url = "redis://:"${REDIS_PASSWORD}"@cache:6379" # ein Stringaddress = ${HOST}":"${PORT} # "db:5432"name = app-${STAGE} # "app-prod"seeds = [ ${?SEED_HOST}":"${?SEED_PORT} ] # ein ElementQuoted 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).
Includes werden nicht unterstützt
Abschnitt betitelt „Includes werden nicht unterstützt“include "shared-cluster.conf" # Fehler: `include` wird nicht unterstütztEine 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.
Reservierte Schlüssel
Abschnitt betitelt „Reservierte Schlüssel“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: abgelehntconstructor.x = 1 # Fehler: abgelehntprototype = 1 # Fehler: abgelehntvalue = ${__proto__} # Fehler: abgelehntEin 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.
Lesend sind nur eigene Schlüssel sichtbar
Abschnitt betitelt „Lesend sind nur eigene Schlüssel sichtbar“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 Funktionport = ${?valueOf} # optional: fällt auf die Umgebung durch, dann wegJeder 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.
Config im Code lesen
Abschnitt betitelt „Config im Code lesen“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.
Ladereihenfolge
Abschnitt betitelt „Ladereihenfolge“1. REFERENCE_CONF ← gebündelte Defaults2. 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 ist4. 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 ist6. 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 ist8. Konstruktor `config: { ... }` ← Code-Level-Override9. 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.
Die reference.conf des Projekts
Abschnitt betitelt „Die reference.conf des Projekts“# reference.conf — die Defaults des Projekts, mit dem Code eingechecktmy-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-Dateien
Abschnitt betitelt „Env-Dateien“# .env — von git ignoriert, neben der AnwendungDB_PASSWORD=s3cretREDIS_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.
Wo der eingebaute Default steht
Abschnitt betitelt „Wo der eingebaute Default steht“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_ENTRIESliegt inInMemoryCacheOptions.ts,DEFAULT_NUM_SHARDSinShardingOptions.ts. - Alles andere — Obergrenzen, Schranken und Timeouts ohne Option
dahinter — steht in einer
Constants.ts:src/<subsystem>/Constants.tsfür ein einzelnes Subsystem,src/util/Constants.tsfü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.
Profile
Abschnitt betitelt „Profile“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 duConfig.loadselbst aufrufst — hat Vorrang vorACTOR_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=produtiondie 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. profilesist auf oberster Ebene reserviert. Der Block wird entfernt, bevor der Baum benutzt wird, sodass ein inaktives Profil niesystem.config, den Konfigurations-Dump oder das DevTools-Panel erreicht. Ein Keyprofilesauf oberster Ebene imconfig-Objekt, das du im Code übergibst, wird abgelehnt statt ignoriert.my-app.profilesunterhalb 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-hostunterproductionden Wertdb.internalund ohne Profillocalhost. 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.confkann einen Key lesen, den die gebündelte oder diereference.confdes Projekts setzt, aber keinen, den nur die Secrets-Datei setzt, und eine Substitution, die den Blockprofilesliest, wird mit Namen abgelehnt. staging = ${profiles.production}kopiert ein ganzes Profil, wörtlich. Ein späteres Delta verschmilzt nicht mit der Kopie: einprofiles.staging.my-app.pool-size = 8danach ersetzt den kopierten Block, undhostist 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.
Secrets-Datei
Abschnitt betitelt „Secrets-Datei“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.
Validierung
Abschnitt betitelt „Validierung“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 alsBrokerOptionsError, und nur vorhandene, aber ungültige Werte werden zuOptionsError. - 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).Wie es weitergeht
Abschnitt betitelt „Wie es weitergeht“- Actor System — wie Settings das Framework erreichen.
- Cluster Overview — die Keys, die für Multi-Node-Setups am relevantesten sind.
- Persistence Overview — Journal- + Snapshot-Store-Plugin-Auswahl.
- Versionspolitik — was stabil vs. experimentell ist.
