Zum Inhalt springen
Deutsch

Utilities

Das Framework löst für sich selbst eine Handvoll Probleme, die in dem Code wieder auftauchen, den du darauf aufbaust: „es gibt vielleicht keinen Wert” ausdrücken, ohne null zu benutzen; einen Fehlschlag tragen, ohne zu werfen; etwas einmalig bei der ersten Nutzung berechnen; eine Queue abarbeiten, die immer weiter wächst; ein Paar von beiden Enden her nachschlagen; etwas so benennen, dass der Name nicht erraten werden kann; einen Wert auf einem Pfad ausgeben, auf dem ein Wurf den gerade gemeldeten Fehler ersetzen würde; und von einem Paket abhängen, das du nicht verpflichtend machen willst.

Das sind die Antworten, die es ohnehin schon benutzt. Die, denen du beim Benutzen des Frameworks selbst begegnest, werden über den Haupteinstiegspunkt exportiert — deshalb importiert alles Folgende aus 'actor-ts'; das ganze Verzeichnis, samt der Teile, die der Haupteinstiegspunkt nicht mitführt, liegt auf dem Subpath actor-ts/util (Der ganze Werkzeugkasten, unten). Keine davon ist Pflicht, um actor-ts zu benutzen: greif zu einer, wenn du das Problem hast, das sie löst.

import {
BidirectionalMap,
BidirectionalMultiMap,
Lazy,
RingBuffer,
none,
safeStringify,
some,
tryOf,
} from 'actor-ts';

Option<T> ist Some<T> | None. Zieh es T | null vor, wenn eine Domänen-API etwas zurückgibt oder ein Feld lange lebt: der Typ erzwingt, dass der leere Fall an der Nutzungsstelle behandelt wird, statt dass man an ihn denken muss.

import { fromNullable, none, some, type Option } from 'actor-ts';
const leader: Option<string> = some('node-a');
leader.map((address) => address.toUpperCase()).getOrElse('<none>'); // 'NODE-A'
none.getOrElse('<none>'); // '<none>'
fromNullable(process.env.SEED_NODE); // Some | None, aus einem Nullable
ExportZweck
some(value) / noneErzeugt eine. none ist eine geteilte Instanz, keine Factory.
fromNullable(value)null / undefined → None, alles andere → Some.
fromPredicate(value, pred)Some, wenn das Prädikat hält, sonst None.
firstSome(...options)Das erste Some, sonst None.

Die API spiegelt Scalas, wo es praktikabel ist: map, flatMap, filter, filterNot, fold, getOrElse, orElse, exists, forall, contains, forEach, toArray, toNullable, isSome, isNone. isSome() und isNone() sind Type Guards, und beide Klassen funktionieren mit P.instanceOf(Some) aus ts-pattern.

An drei Stellen ist ein Nullable weiterhin die richtige Wahl, und das Framework nutzt es dort bewusst: in Feldern auf heißen Pfaden, wo der Wrapper im Profil auftauchen würde; an Serialisierungsgrenzen, die über null round-trippen müssen; und bei optionalen Parametern mit bequemen Defaults.

Try — eine Berechnung, die geworfen haben könnte

Abschnitt betitelt „Try — eine Berechnung, die geworfen haben könnte“

Try<T> ist Success<T> | Failure. Es macht aus einem throw einen Wert, den du weiterreichen kannst — genau das brauchst du, wenn der Fehlschlag reisen soll: in eine Nachricht, über ein ask, in eine Zustandsmaschine.

import { tryOf } from 'actor-ts';
const parsed = tryOf(() => JSON.parse(payload));
parsed
.map((body) => body.userId)
.recover(() => 'anonymous')
.getOrElse('anonymous');

tryOf(compute) führt die Funktion aus und fängt, was sie wirft; success(value) und failure(error) erzeugen direkt eines. Über die gemeinsamen map / flatMap / fold / getOrElse / orElse / filter / forEach hinaus bietet Try recover (Fehler auf einen Wert abbilden), recoverWith (auf ein weiteres Try), get (erneut werfen), toNullable und toError. trySequence(tries) macht aus einem Array von Try<T> ein Try<T[]>, das beim ersten Fehlschlag scheitert.

Either — zwei Ausgänge, von denen keiner ein Fehler ist

Abschnitt betitelt „Either — zwei Ausgänge, von denen keiner ein Fehler ist“

Either<L, R> ist Left<L> | Right<R>, rechtsbetont: map und flatMap arbeiten auf der rechten Seite. Nimm es statt Try, wenn die Fehlerseite ein Domänenwert ist, den du typisiert haben willst — ein Validierungsbefund, ein Ablehnungsgrund — und kein geworfener Fehler.

import { left, right, type Either } from 'actor-ts';
function parseAge(raw: string): Either<string, number> {
const value = Number(raw);
return Number.isInteger(value) && value >= 0 ? right(value) : left(`not an age: ${raw}`);
}
parseAge('42').fold((reason) => `rejected: ${reason}`, (age) => `age ${age}`);

mapLeft, bimap und swap arbeiten auf der anderen Seite; isLeft() und isRight() sind Type Guards. eitherOf(compute) fängt einen Wurf in ein Left<Error>, und eitherSequence sammelt ein Array so ein wie trySequence.

Lazy<T> ist Scalas lazy val: die Berechnung läuft beim ersten get() und das Ergebnis wird gemerkt — ein geworfener Fehlschlag ebenso. Ein teures oder seiteneffektbehaftetes Setup passiert also genau einmal, egal wie viele Aufrufer fragen.

import { Lazy, lazyImportModule } from 'actor-ts';
const redisLazy = Lazy.of(() => lazyImportModule<typeof import('ioredis')>('ioredis'));
// Der erste Aufruf importiert; jeder weitere liefert dasselbe Promise.
const redis = await redisLazy.get();

Lazy.of(compute) (als lazy aliasiert) und Lazy.evaluated(value) erzeugen eines. get() erzwingt die Berechnung, peek() liefert den Wert nur, wenn er schon berechnet wurde, getSync() packt eine aufgelöste asynchrone Zelle aus, und map / flatMap / forEach komponieren, ohne zu erzwingen. reset() und setOverride(value) sind für Tests da — sie sind der Grund, warum ein lazy importiertes Backend gegen ein Fake getauscht werden kann, ohne den Produktionspfad anzufassen.

RingBuffer — eine Queue, die schnell bleibt, wenn sie tief wird

Abschnitt betitelt „RingBuffer — eine Queue, die schnell bleibt, wenn sie tief wird“

RingBuffer<T> ist eine First-in-first-out-Queue, deren Entnahme vorne O(1) ist. Sie existiert, weil Array.prototype.shift() das nicht ist: es indiziert jedes noch eingereihte Element neu, die Kosten einer Entnahme wachsen also mit der Zahl der Elemente dahinter. Auf einer Queue von zehn ist das unsichtbar, auf einer von hunderttausend teuer — und genau das wird die Mailbox eines Actors, der hinter seine Producer zurückfällt, denn die Default-Mailbox hat keine Decke.

import { RingBuffer } from 'actor-ts';
const pending = new RingBuffer<string>();
pending.push('a');
pending.push('b');
pending.shift(); // 'a'
pending.unshiftAll(['x', 'y']); // beide vor 'b', in dieser Reihenfolge
pending.length; // 3
pending.drain(); // ['x', 'y', 'b'] — und der Ring ist leer

Vier Operationen und sonst nichts. push hängt hinten an (amortisiert O(1) — das Backing-Array verdoppelt sich, und es wird bis zum ersten push gar nicht erst allokiert, ein ungenutzter Ring kostet also so viel wie ein leeres []). shift entnimmt vorne. drain leert ihn in ein frisches Array und gibt den Backing-Store frei, eine Queue, die auf eine Million gewachsen ist, gibt den Speicher also zurück. unshiftAll(items) setzt einen ganzen Stapel in einem Zug nach vorne, ohne Spread — das Framework spielt damit einen Stash von bis zu tausend Nachrichten wieder ein, wo unshift(...items) die Queue einmal pro Nachricht neu indizieren und den Stapel als Argumente auf den Call-Stack legen würde.

Bewusst kein allgemeiner Deque: jede weitere Operation ist ein weiterer Index-Umlauf-Sonderfall in einem Typ, der auf dem Nachrichtenpfad jedes Actors im System sitzt. Beide Queues in einer Mailbox sind einer, und die Work-Queue des ThroughputDispatcher ebenfalls.

BidirectionalMap — eine Map mit gepflegter Umkehrung

Abschnitt betitelt „BidirectionalMap — eine Map mit gepflegter Umkehrung“

BidirectionalMap<K, V> ist eine Map<K, V>, die zusätzlich value → key beantwortet. Sie existiert, weil ein handgeschriebener Reverse-Index zwei Maps sind, die im Gleichschritt gepflegt werden müssen — und wenn sie auseinanderlaufen, ist der Fehler still: ein veralteter Eintrag beantwortet weiter ein Paar, das es längst nicht mehr gibt.

import { BidirectionalMap } from 'actor-ts';
const seats = new BidirectionalMap<string, number>();
seats.set('ada', 1);
seats.set('grace', 2);
seats.get('ada'); // 1
seats.getKey(2); // 'grace' ← die Richtung, die eine Map nicht kann
seats.deleteValue(1); // entfernt das Paar auf beiden Seiten

Sie implementiert Map<K, V> vollständig und passt damit überall dort hinein, wo eine Map erwartet wird — new Map(bidirectionalMap), Spread, for…of, forEach.

Über Map hinausZweck
getKey(value) / hasValue(value) / deleteValue(value)Die Rückrichtung.
trySet(key, value)Bindet nur, wenn dabei nichts entfernt wird; sonst false.
inverse()Dieselbe Map andersherum gelesen — eine Sicht, keine Kopie.
reverseEntries()[value, key]-Paare.
getOrInsertKey(value, defaultKey)Wie getOrInsert, von der Wertseite aus; liefert einen Key.
getOrInsertComputedKey(value, callback)Dasselbe, der Key wird bei Bedarf erzeugt. callback läuft höchstens einmal.
keySize / valueSizeVerschiedene Keys und verschiedene Werte. Beide sind immer gleich size, weil die Relation 1:1 ist — sie existieren, damit dieser Typ und die BidirectionalMultiMap, wo sich die Zahlen wirklich unterscheiden, sich gleich lesen.

Beide Richtungen liegen auf einer Map, also vergleichen beide per SameValueZero: NaN funktioniert als Key und als Wert, 0 und -0 sind dasselbe, und zwei strukturell gleiche Objekte sind zwei verschiedene Werte. Wenn du strukturelle Identität brauchst, indiziere eine abgeleitete Zeichenkette — genau das tut der Shard des Frameworks selbst, der auf ref.path.toString() schlüsselt statt auf den Ref.

Anders als eine gewöhnliche Klasse überlebt eine BidirectionalMap den Round-Trip durch Journal, Snapshot oder Durable State als echte Instanz — ohne Event-Adapter, ohne Serializer-Registrierung, ohne irgendetwas an der Grenze. Der getaggte JSON-Baum kennt sie so, wie er Map und Set kennt.

type State = { seats: BidirectionalMap<string, number> };
class SeatingPlan extends PersistentActor<Command, Event, State> {
initialState(): State {
return { seats: new BidirectionalMap() };
}
// Nach einem Neustart ist state.seats wieder eine BidirectionalMap — und
// state.seats.getKey(2) funktioniert, obwohl nur die Vorwärtspaare je
// geschrieben wurden.
}

Auf die Platte gehen nur die Vorwärtspaare; die Umkehrung wird beim Dekodieren rekonstruiert. Die vollständige Round-Trip-Tabelle steht unter was Events und State enthalten dürfen.

Ein Store, der mit withSerializer(new CborSerializer()) konfiguriert ist, trägt sie ebenfalls, unter CBOR-Tag 27. Das war nicht immer so — bis #1036 hat der CBOR-Codec sie fallen lassen, zusammen mit Map und Set, ohne etwas zu melden.

BidirectionalMultiMap — dasselbe für eine Viele-zu-viele-Relation

Abschnitt betitelt „BidirectionalMultiMap — dasselbe für eine Viele-zu-viele-Relation“

BidirectionalMultiMap<L, R> setzt viele Linke zu vielen Rechten in Beziehung und beantwortet beide Richtungen. Sie existiert für die Form, die eine Subscription-Registry hat: ein Subscriber hält viele Topics, ein Topic hat viele Subscriber — und die Nachricht, die dir sagt, dass ein Subscriber weg ist, trägt nur den Subscriber.

import { BidirectionalMultiMap } from 'actor-ts';
const subscriptions = new BidirectionalMultiMap<string, string>();
subscriptions.add('news', 'ada');
subscriptions.add('news', 'grace');
subscriptions.add('sport', 'ada');
subscriptions.get('news'); // Set { 'ada', 'grace' }
subscriptions.getKeys('ada'); // Set { 'news', 'sport' } ← die Rückrichtung
subscriptions.size; // 3 — Paare, nicht Teilnehmer
subscriptions.leftSize; // 2 — verschiedene Topics
subscriptions.rightSize; // 2 — verschiedene Subscriber
subscriptions.deleteRight('ada'); // ada verlässt alle Topics auf einmal
subscriptions.hasLeft('sport'); // false — sport hielt nur ada und ist mit weg

Die letzte Zeile ist die Invariante, die man kennen sollte: einen leeren Teilnehmer gibt es nicht. Wer seinen letzten Partner verliert, verschwindet aus beiden Richtungen. Ein Topic, das mit einem leeren Subscriber-Set zurückbleibt, ist für eine Paarzählung unsichtbar, belegt weiter das Cap, das deine Topics begrenzt — und inverse() würde etwas herausgeben, das mit nichts in Beziehung steht.

Über ein Paar Maps hinausZweck
add(left, right) / delete(left, right)Ein Paar, beide Richtungen. add ist idempotent.
get(left) / getKeys(right)Alles, womit eine Seite in Beziehung steht. Leeres Set, wenn es sie nicht gibt — nie undefined, du kannst also ohne Guard iterieren.
deleteLeft(left) / deleteRight(right)Einen Teilnehmer vollständig entfernen — der Terminated-Fall.
hasLeft(left) / hasRight(right)Ob dieser Teilnehmer mindestens einen Partner hat.
lefts() / rights()Die Teilnehmer, jeder genau einmal.
size / leftSize / rightSizePaare, verschiedene Linke, verschiedene Rechte. Alle drei O(1) — nimm eine der Teilnehmerzahlen, statt [...lefts()] auszumessen.
inverse()Die Relation andersherum gelesen — eine Sicht, keine Kopie. size stimmt auf beiden Seiten.

Verglichen wird per SameValueZero, wie bei BidirectionalMap und aus demselben Grund: beide Richtungen liegen auf Map und Set. Zwei strukturell gleiche Objekte sind zwei verschiedene Teilnehmer — indiziere also eine abgeleitete Zeichenkette, wenn du strukturelle Identität brauchst. Genau das tun die Aufrufstellen des Frameworks selbst: sie schlüsseln Subscriber auf ref.path.toString() statt auf den Ref. Ein Terminated trägt den self-Ref der Zelle, der nicht das Objekt sein muss, das subscribed hat; der Pfad ist die Identität, auf die sich beide Seiten einigen.

Wie ihre 1:1-Schwester überlebt sie den Round-Trip durch Journal, Snapshot oder Durable State als echte Instanz — ohne Adapter, ohne Registrierung. Geschrieben wird nur die Vorwärtsrichtung, als Adjazenzliste; die Umkehrung wird beim Dekodieren rekonstruiert, sodass die beiden Hälften nicht widersprüchlich zurückkommen können. Der CBOR-Vorbehalt von oben gilt genauso.

ExportZweck
randomString(length, options?, exists?)length Zeichen aus den aktivierten Klassen. Voreinstellung: alphanumerisch. exists darf auf Position zwei stehen, wenn du keine Optionen übergibst.
randomHex(length, exists?)length Kleinbuchstaben-Hex-Zeichen — für Wire-Formate, die [0-9a-f] vorschreiben.
randomId(length, exists?)length Zeichen für etwas, das du selbst benennen musst.
randomUuid(exists?)Eine v4-UUID — für einen Bezeichner, der mit keinem anderswo erzeugten kollidieren darf.
RandomStringOptions{ lowerCase?, upperCase?, digits? } — jedes standardmäßig true.
ExistsPredicate(candidate: string) => boolean — die optionale Kollisionsprüfung, die alle vier annehmen. true heißt „vergeben, zieh noch einmal“.

Die ersten drei ziehen aus globalThis.crypto, korrigieren den Modulo-Bias, den ein schlichtes byte % alphabet.length einführt, und liefern exakt die angefragte Länge — nie weniger. randomUuid delegiert an globalThis.crypto.randomUUID().

import { randomId, randomString, randomUuid } from 'actor-ts';
const sessionId = randomId(12); // '9f3c1ab0e7d2'
const coupon = randomString(8, { lowerCase: false, digits: true }); // 'K7Q2XP4M'
const persistenceId = randomUuid(); // 'f81d4fae-7dec-41d0-a765-00a0c91e6bf6'

randomId ist die richtige Wahl, wenn du einen Aktor benennst. Ein Aktorname landet in einem Aktorpfad, und ein Pfad ist eine Adresse: auf dem Cluster-Wire kann alles, was einen Pfad erzeugen kann, auch dorthin senden. Ein Zähler macht diese Adresse erratbar — wer eine kennt, kennt die nächste. Genau deshalb benennt das Framework anonyme Aktoren und die Antwort-Refs von ask von hier aus statt aus $1, $2, $3.

randomHex existiert getrennt, weil manche Alphabete keine Stilfrage sind. W3C Trace-Context schreibt [0-9a-f]{32} und [0-9a-f]{16} für einen traceparent-Header vor, und eine Gegenstelle lehnt alles andere ab.

randomUuid steht am anderen Ende der Entropie-Skala als randomId, und die Trennung zwischen beiden lohnt sich. randomId(12) sind ~48 Bit: unerratbar unter den Namen, die ein Prozess gleichzeitig hält — mehr Eindeutigkeit muss ein Aktorname nicht tragen. randomUuid() sind 122 Zufallsbits, und so viel braucht es, damit ein Bezeichner von einem unterscheidbar bleibt, der in einem anderen Prozess, auf einer anderen Maschine, Jahre später und ohne jede Abstimmung erzeugt wurde — eine PersistenceId für ein neues Aggregat, eine Correlation-Id, die über einen Broker läuft, ein Schlüssel, den ein anderes System liest.

Alle vier nehmen als letztes Argument ein optionales Prädikat und ziehen erneut, solange es true antwortet:

import { randomUuid } from 'actor-ts';
const userId = randomUuid((id) => state.users.has(id));

also genau die Schleife, die bisher an der Aufrufstelle stand:

let userId: UserId;
do {
userId = randomUuid();
} while (state.users.has(userId));

Der Callback ist diese while-Bedingung. Deshalb heißt er exists, und deshalb bedeutet true „zieh noch einmal“ — ein Akzeptanz-Prädikat wäre die Negation der Schleife, die es ersetzt, und würde jeder Map- oder Set-gestützten Aufrufstelle ein ! verpassen. randomString nimmt ihn auf Position zwei, wenn du keine Optionen übergibst, und auf Position drei, wenn du es tust: randomString(8, exists), randomString(8, { digits: false }, exists).

Es liest nur, es schreibt nicht. Der akzeptierte Wert wird nirgends für dich vermerkt — was exists befragt, bleibt deine Sache.

safeStringify(value, maxLength?) stellt einen beliebigen Wert als Zeichenkette dar und wirft dabei nie.

import { Actor, safeStringify } from 'actor-ts';
class Worker extends Actor<unknown> {
onReceive(message: unknown) {
this.log.warn(`unhandled message: ${safeStringify(message)}`);
}
}

JSON.stringify wirft bei einer zyklischen Struktur und bei einem BigInt. Damit riskierst du, wenn du damit eine Logzeile oder eine Fehlermeldung baust, das gerade gemeldete Problem durch ein anderes zu ersetzen — geworfen aus dem meldenden Code heraus, wo ein Aufrufer am wenigsten damit rechnet. Ein onReceive, das eine unerwartete Nachricht loggt, ist genau diese Lage: die Nachricht ist unbekannt, also weiß man nichts über ihre Form.

Zyklen kollabieren zu [Circular], BigInt wird mit n-Suffix dargestellt, Funktionen und Symbole werden benannt, und das Ergebnis ist gedeckelt (standardmäßig 8 KiB), statt zu einer mehrere Megabyte großen Zeichenkette anzuwachsen, die beim Bauen die Event-Loop blockiert.

Eine Verbindungs-URL ist die eine Zeichenkette in einer Konfiguration, die regelmäßig ein Geheimnis inline mitführt — amqp://user:pass@host/vhost, mongodb+srv://user:pass@cluster — und die Stellen, die eine solche ausgeben, werden am seltensten auf Preisgabe geprüft: eine Ablehnungsmeldung, eine Reconnect-Warnung, ein Frame, den ein entferntes Gegenüber geschickt hat. Zwei Darstellungen für zwei verschiedene Aufgaben.

import { redactUrlCredentials, redactedUrlLabel } from 'actor-ts';
redactUrlCredentials('amqp://user:pass@rabbit:5672/vhost');
// → 'amqp://***@rabbit:5672/vhost'
redactedUrlLabel('wss://user:pass@example.com/ws/orders?token=abc');
// → 'wss://example.com/ws/orders'

redactUrlCredentials(value) maskiert die Userinfo und ändert sonst nichts — keine Normalisierung, kein angehängter Schrägstrich, kein kleingeschriebener Host —, damit ein Betreiber den getippten Wert weiterhin wiedererkennt. Auf allem ohne scheme://…@-Authority ist die Funktion ein striktes No-op, und genau das macht sie sicher anwendbar auf einen Wert, der nur vielleicht eine URL ist (':memory:', 'file:local.db', 'not a url' kommen unverändert zurück). Das ist es, was die framework-eigene Options-Validierung in jeden OptionsError schreibt, der eine URL ablehnt. Ein Passwort mit einem rohen /, ? oder # darin wird ebenfalls maskiert, von dieser Funktion und von beiden weiter unten — RFC 3986 verlangt alle drei prozentkodiert, aber ein eingefügtes Passwort enthält sie so, wie es getippt wurde, also reicht die Userinfo bis zum letzten @ vor dem nächsten ://. Den Preis zahlt ein @ weiter hinten in einem Pfad oder einer Query, das genauso gelesen wird: https://host/a@b kommt als https://***@b zurück — das *** sagt, dass das Folgende auf das letzte @ folgte, nicht unbedingt der Host ist. Die Userinfo bleibt auf ihrer eigenen Zeile: Sobald ein @ gesehen wurde, beendet ein Zeilenumbruch sie, und vor dem ersten @ liest der Scan über einen Zeilenumbruch hinaus nur bis zum ersten Leerzeichen oder Tab. So wird der nächste Frame eines Stack-Traces — jeder Frame eines Scoped Package trägt ein @ — oder die nächste Logzeile nie für ein Passwort gehalten, während ein aus einer Datei gelesenes Secret weiterhin vollständig maskiert wird: Ein Zeilenumbruch, auf den ein @ folgt, etwa ein abschließender Zeilenumbruch vor dem @, gehört zur Userinfo, und ebenso ein Secret, das über mehrere Zeilen umbrochen ist. Die Regel gibt zwei Formen von Secrets auf, und keine davon wird vollständig maskiert. Ein Leerzeichen oder Tab nach einem Zeilenumbruch beendet den Scan, bevor er das @ erreicht, also kommt 'amqp://user:pa\n ss@rabbit' unverändert zurück, und ein @ vor einem Zeilenumbruch beendet die Userinfo dort, also kommt 'amqp://user:p@ss\nword@rabbit' als 'amqp://***@ss\nword@rabbit' zurück und behält ss und word. redactedUrlLabel verbirgt beide in einem Wert, den es aus seinem Parse neu aufbaut — einer URL ohne , und ohne zweites :// vor einem ? oder # —, aber nicht in jedem Wert, den es stattdessen maskiert: So kommt 'nats://a:b@h1,nats://u:pa\n ss@h2' als 'nats://***@h1,nats://u:pa\n ss@h2' zurück.

Eine URL, die die Laufzeit bereits geparst hat, braucht diese Vermutung nicht. Für die URL, an die eine Anfrage ging, oder ein dagegen aufgelöstes Redirect-Ziel maskiert redactParsedUrlCredentials(url) genau deren username und password und behält ein @, das Pfad oder Query mitführen:

import { redactParsedUrlCredentials } from 'actor-ts';
redactParsedUrlCredentials(new URL('https://registry.npmjs.org/@types%2fnode'));
// → 'https://registry.npmjs.org/@types%2fnode'
redactParsedUrlCredentials(new URL('https://user:pass@idp.example/authorize?login_hint=a@b'));
// → 'https://***@idp.example/authorize?login_hint=a@b'

Was auf den Host folgt, durchläuft weiterhin den Scan von oben, sodass eine in einen Pfad oder eine Query geschriebene URL (?target=http://user:pass@inner/) ihr eigenes Credential maskiert behält. Das Ergebnis ist das href der URL, so normalisiert, wie die Laufzeit sie sendet — deshalb ist das die Darstellung für eine URL, mit der eine Anfrage gestellt wird, und nicht für einen getippten Wert: Ein vertipptes Passwort mit einem / darin (user:12/PW1@host) wird als Host, Port und Pfad geparst, und einen konfigurierten String nur zum Anzeigen zu parsen, würde genau das Passwort ausgeben, das verborgen werden sollte. HttpClient benennt die URLs in seinen Redirect- und Größenfehlern auf diese Weise, SseActor das Ziel eines Redirects, den er ablehnt; ein Location-Header, der sich nicht parsen lässt, fällt auf den Scan zurück.

redactedUrlLabel(value) geht weiter und reduziert eine URL auf eine stabile Identität: Schema, Host, Port und Pfad, ohne Userinfo und ohne Query-String — ein WebSocket-Endpunkt wird üblicherweise mit einem ?token=… authentifiziert. Der Pfad bleibt bewusst erhalten, denn er unterscheidet zwei Verbindungen zum selben Host. Ein Wert, der nicht genau eine URL ist, wird maskiert statt geparst: Ein schemaloses user:password@host — die Server-Form, die memjs und nats.js annehmen — kommt als ***@host zurück, und eine kommagetrennte Liste behält jeden Eintrag, jeweils mit maskierter Userinfo.

Das Label maskiert jede Userinfo so wie der Scan — bis zum letzten @ vor dem nächsten :// — und zeigt, außer bei den beiden mehrzeiligen Formen oben, kein Credential, das das Label von v0.17.0 verborgen hat. Daraus folgen drei Fälle, jeder gegen eine Kopie des veröffentlichten Labels geprüft:

  • Ein @ hinter dem Host benennt keinen Host. https://user:pass@hooks.example/notify?to=ops@example.com ist eine URL für hooks.example mit einem @ in der Query und Byte für Byte zugleich ein Passwort, das auf ops endet, für den Host example.com. Kein Host passt zu beiden Lesarten, also benennt das Label keinen und kommt als https://*** zurück. Dasselbe gilt ganz ohne Credential — wss://chat.example.com/rooms/@general und https://host/a@b kommen als wss://*** und https://*** zurück —, und das Label zeigt nie, was auf ein ? oder # folgt, sodass ein Query-Token mit einem @ darin nichts von seinem Ende preisgibt: wss://feed.example.com/ws?token=a@b kommt als wss://*** zurück. Wo WHATWG vor dem / keinen gültigen Host liest, ist die Lesart des Scans die einzige, und ihr Host wird genannt: amqp://user:pa/PW1@host:5672/vhost kommt als amqp://host:5672/vhost zurück.
  • Ein Komma in einem Passwort wird mitmaskiert, wo immer ein @ steht: amqp://user:a,b@host kommt als amqp://host zurück und amqp://user:a@b,c@host als amqp://***@host. Eine Liste mit Credentials, deren Einträge nicht jeder mit einem eigenen scheme:// beginnen, ist derselbe String wie ein solches Passwort, also gehen die Hosts vor ihrem letzten @ in der Maske auf, und das ***@ bleibt stehen, um das zu sagen: nats://h1:4222,u:p@h2:4222 kommt als nats://***@h2:4222 zurück. Gib jedem Eintrag sein eigenes scheme://, und jeder Host bleibt: nats://u:p@a:4222,nats://u:p@b:4222 kommt als nats://***@a:4222,nats://***@b:4222 zurück.
  • Ein schemaloses user:a,b@host hat nichts, was den Beginn seiner Userinfo anzeigt, und kommt weiterhin als user:a,***@host zurück.

Nimm die Funktion überall dort, wo eine Gegenstelle beeinflusst, wie oft eine Zeile geschrieben wird — also überall dort, wo die URL sonst nach fremdem Gutdünken ins Log gespiegelt würde. Der WebsocketClientActor setzt sie für seine Warnung über zu große Frames ein. Diese Zeile entsteht nicht mehr pro Frame: Der Verstoß schließt die Verbindung, eine Gegenstelle bekommt also eine Zeile pro Verbindungsaufbau. Die Redaktion bleibt trotzdem nötig, denn wie viele Verbindungsaufbauten es gibt, entscheidet weiterhin die Gegenstelle.

Der zweite Konsument ist BrokerActor, und dort geht es gar nicht um ein Log: redactedEndpointLabel() ist das, was BrokerConnected, BrokerDisconnected, BrokerReconnectFailed und BrokerReconnectAttempt erreicht — Events auf dem systemweiten EventStream. Dieses Publikum ist größer als eine Log-Datei (subscribe kennt keinen Autorisierungsbegriff), und die Events entstehen auf dem Erfolgspfad: einmal pro Verbindungsaufbau und einmal pro Reconnect-Versuch. Der Fall zeigt außerdem, dass der Fallback echte Arbeit leistet: Eine zusammengesetzte Server-Liste geht nie an den URL-Parser, nimmt also den Scan-Pfad und kommt als nats://***@a:4222,nats://***@b:4222 zurück, statt auf einen einzigen Host eingedampft zu werden.

Eine dritte Darstellung gibt es für den Fall, dass die Zeichenkette gar nicht dir gehört. redactErrorCredentials(error) wendet die erste auf einen Error an, den irgendein Treiber geworfen hat — mehrere schreiben das Verbindungsziel samt Userinfo in die Meldung, die sie auslösen — und liefert eine Kopie, denn dieser Fehler gehört dem Treiber und kann dort noch gehalten oder bereits an eigene Listener gegeben worden sein.

import { redactErrorCredentials } from 'actor-ts';
const safe = redactErrorCredentials(driverError);
// Meldung, Stack, eigene String-Properties und die `cause`-Kette, alle maskiert

Die Kopie ist so gebaut, dass sie die Fragen beantwortet, die ein Subscriber tatsächlich stellt: Sie trägt den Prototyp des Originals, instanceof gilt also weiterhin, und dessen eigene enumerable Properties, code / errno / syscall überleben also. Bewusst nicht übernommen wird alles, was nur über einen Getter erreichbar ist — ein Getter kann das Geheimnis neu berechnen, und eine Redaktion, die ein Property-Zugriff rückgängig macht, ist keine. Das stellt BrokerDisconnected.cause und BrokerReconnectFailed.cause auf dieselbe Stufe wie das endpoint daneben; ohne das hätte ein Betreiber, der „Broker-Events tragen mein Passwort nicht mehr“ liest, bei einem Feld recht gehabt und beim Event unrecht.

lazyImportModule(name, options?) importiert ein Modul dynamisch und wirft, wenn es fehlt, einen Fehler, der das Paket und den Installationsbefehl nennt.

import { Lazy, lazyImportModule } from 'actor-ts';
const redisLazy = Lazy.of(() =>
lazyImportModule<typeof import('ioredis')>('ioredis', { context: 'MyCacheActor' }),
);
// MyCacheActor requires the 'ioredis' package. Install it with: npm install ioredis
// Original error: Cannot find module 'ioredis'
ExportZweck
lazyImportModule<T>(name, options?)import(name), oder ein „fehlende Peer-Dependency”-Fehler.
LazyImportOptions{ context?, installHint? } — wer es brauchte und wie man es installiert.

Auf diesem Muster sind die Broker, Caches und Persistence-Backends des Frameworks aufgebaut, und deshalb scheitern sie alle auf dieselbe Weise: das Modul darf keine harte Abhängigkeit sein, also muss der Import dynamisch sein, also ist der voreingestellte Fehlerfall ein nacktes Cannot find module, das nichts darüber sagt, welches Paket fehlt oder was dagegen zu tun ist. In Kombination mit Lazy — ebenfalls über den Haupteinstiegspunkt exportiert — passiert der Import genau einmal, bei der ersten Nutzung statt beim Erzeugen.

OptionsBuilder und OptionsValidator sind die beiden Basisklassen hinter jeder XOptions-Familie im Framework — MqttOptions, SqliteJournalOptions, ActorSystemOptions und die übrigen. Zum Benutzen dieser Options brauchst du sie nicht; du brauchst sie, um eigene in derselben Form zu schreiben.

import { OptionsBuilder, OptionsValidator } from 'actor-ts';
type MyOptionsType = { readonly port?: number; readonly host?: string };
class MyOptionsBuilder extends OptionsBuilder<MyOptionsType> {
withPort(port: number): this { return this.set('port', port); }
withHost(host: string): this { return this.set('host', host); }
}
class MyOptionsValidator extends OptionsValidator<MyOptionsType> {
constructor() { super('MyOptions'); }
protected rules(_settings: Partial<MyOptionsType>): void {
this.port('port'); // No-op, solange ungesetzt; sonst OptionsError
this.nonEmptyString('host');
}
}

Ein Builder ist seine Settings: das geschützte set schreibt jedes Feld als eigene aufzählbare Property, eine Instanz ist also strukturell ein Beutel der Felder, die du gesetzt hast — und ein Plain-Objekt ist damit austauschbar.

Die Check-Helfer (port, positiveNumber, positiveInt, nonNegativeInt, numberInRange, oneOf, nonEmptyString, nonEmptyArray, url, dazu fail für Sonderregeln) nehmen nur den Feldnamen — er wird gegen deinen Options-Typ auf Tippfehler geprüft, und ein Helfer auf einem Feld des falschen Typs ist ein Compile-Fehler. Jeder ist ein No-op, solange das Feld undefined ist: ein ungesetztes Optional besteht also immer, und wo Pflichtfelder erzwungen werden, bleibt dir überlassen. Ein abgelehnter Wert wirft OptionsError, das daneben exportiert wird, damit du es gezielt fangen kannst — und wenn der abgelehnte Wert eine URL ist, meldet url sie mit maskierten Zugangsdaten (Eine URL loggen, ohne das Passwort zu loggen, oben).

Die Validierung läuft einmal, zum Zeitpunkt des Verbrauchs, auf den zusammengeführten Settings — damit sind Builder, Plain-Objekt und HOCON gleichermaßen abgedeckt, und feldübergreifende Regeln sehen die endgültigen Werte. Wie die Schichten auflösen, steht unter Konfiguration.

Alles oben liegt auf dem Haupteinstiegspunkt, weil du ihm beim Benutzen des Frameworks begegnest. Der Rest von src/util/ löst Probleme, die einen Schritt weiter außen liegen, und ist über einen eigenen Subpath erreichbar:

import { TokenBucket, mergeOptions, wrapError } from 'actor-ts/util';

Der Subpath ist eine Obermenge: jeder Name, den der Haupteinstiegspunkt mitführt, liegt auch dort — eine Datei, die some und mergeOptions braucht, kann also beides aus actor-ts/util nehmen statt zweimal zu importieren.

ExportWas er tut
mergeOptions(defaults, fromConfig, explicit)Die eine Implementierung der Options-Präzedenz explizit > HOCON > Defaults. undefined auf einer höheren Schicht heißt „nicht gesetzt” und fällt durch, statt die Schicht darunter zu überschreiben — was du willst, und was ein einfacher Spread nicht tut.
stripUndefined(partial)Entfernt die Schlüssel, deren Wert undefined ist — so kommt mergeOptions zu dieser Eigenschaft.
TokenBucketRate-Limiting mit qps als Nachfüllrate und burst als Kapazität, träge aus der verstrichenen Zeit nachgefüllt — kein Hintergrund-Timer. Die Uhr ist injizierbar, ein Test schiebt die Zeit also vor statt auf sie zu warten.
wrapError(error, ErrorClass, message)Eine gefangene Exception als typisierten Framework-Fehler mit kontextbezogener Nachricht weiterwerfen, das Original als cause. Ein Fehler, der bereits die Zielklasse hat, wird unverändert zurückgegeben statt doppelt eingepackt.
escapeHtml, html, rawHtml, SafeHtmlEscaping für HTML-Elementinhalt und Attributwerte in Anführungszeichen. Das Tagged Template html escapt jede Interpolation standardmäßig; rawHtml ist die Ausnahme für eine Zeichenkette, die du schon sicher gemacht hast. Kein Sanitizer für nicht vertrauenswürdiges Markup.
stripTrailing(value, char), stripSurrounding(value, char)Ein wiederholtes Zeichen in linearer Zeit von den Enden abschneiden. Die Regex-Schreibweise backtrackt quadratisch, was zählt, wenn der Wert ein Request-Pfad oder ein Hostname ist, den ein entfernter Peer gewählt hat.
parseCidr, cidrMatches, isCidrEntryCIDR parsen und matchen, IPv4 und IPv6, mit IPv4-mapped IPv6 so behandelt, dass ein reiner IPv4-Bereich auch einen Dual-Stack-Peer trifft.
parseAddressPin, addressMatchesPins, addressPinRejectionDie darauf aufbauenden Adress-Pin-Regeln: ein Eintrag ist ein CIDR (gegen IPs gematcht) oder ein Host-Suffix (gegen Hostnamen auf Label-Grenze gematcht, damit evilsvc.cluster.local nicht an svc.cluster.local vorbeikommt). addressPinRejection gibt den Grund zurück, warum ein Eintrag unbrauchbar ist — für den eigenen Validator zum Melden.
DEFAULT_ASK_TIMEOUT_MS, DEFAULT_GOSSIP_INTERVAL_MS, DEFAULT_EXPLAIN_CAPACITYDie subsystemübergreifenden Defaults, damit ein eigenes Timeout, das unter dem Ask-Timeout bleiben muss, den Wert lesen kann statt die Zahl zu kopieren.
PATH_TRAVERSAL_SEGMENTS, MAXIMUM_DRAW_ATTEMPTSDie Traversal-Denylist, gegen die Aktorpfade und PersistenceIds beide geprüft werden, und die Grenze, bei der ein Eindeutigkeits-Neuziehen aufgibt.