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 — ein Wert, den es vielleicht nicht gibt
Abschnitt betitelt „Option — ein Wert, den es vielleicht nicht gibt“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| Export | Zweck |
|---|---|
some(value) / none | Erzeugt 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 — einmal berechnen, bei der ersten Nutzung
Abschnitt betitelt „Lazy — einmal berechnen, bei der ersten Nutzung“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 Reihenfolgepending.length; // 3pending.drain(); // ['x', 'y', 'b'] — und der Ring ist leerVier 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'); // 1seats.getKey(2); // 'grace' ← die Richtung, die eine Map nicht kannseats.deleteValue(1); // entfernt das Paar auf beiden SeitenSie 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 hinaus | Zweck |
|---|---|
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 / valueSize | Verschiedene 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.
Sie darf im persistenten State liegen
Abschnitt betitelt „Sie darf im persistenten State liegen“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ückrichtungsubscriptions.size; // 3 — Paare, nicht Teilnehmersubscriptions.leftSize; // 2 — verschiedene Topicssubscriptions.rightSize; // 2 — verschiedene Subscriber
subscriptions.deleteRight('ada'); // ada verlässt alle Topics auf einmalsubscriptions.hasLeft('sport'); // false — sport hielt nur ada und ist mit wegDie 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 hinaus | Zweck |
|---|---|
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 / rightSize | Paare, 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.
Sie darf ebenfalls im persistenten State liegen
Abschnitt betitelt „Sie darf ebenfalls im persistenten State liegen“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.
Zufallszeichenketten und Bezeichner
Abschnitt betitelt „Zufallszeichenketten und Bezeichner“| Export | Zweck |
|---|---|
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.
Ziehen, bis eine frei ist
Abschnitt betitelt „Ziehen, bis eine frei ist“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.
Werte ausgeben, bei denen schon etwas schiefging
Abschnitt betitelt „Werte ausgeben, bei denen schon etwas schiefging“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 URL loggen, ohne das Passwort zu loggen
Abschnitt betitelt „Eine URL loggen, ohne das Passwort zu loggen“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.comist eine URL fürhooks.examplemit einem@in der Query und Byte für Byte zugleich ein Passwort, das aufopsendet, für den Hostexample.com. Kein Host passt zu beiden Lesarten, also benennt das Label keinen und kommt alshttps://***zurück. Dasselbe gilt ganz ohne Credential —wss://chat.example.com/rooms/@generalundhttps://host/a@bkommen alswss://***undhttps://***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@bkommt alswss://***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/vhostkommt alsamqp://host:5672/vhostzurück. - Ein Komma in einem Passwort wird mitmaskiert, wo immer ein
@steht:amqp://user:a,b@hostkommt alsamqp://hostzurück undamqp://user:a@b,c@hostalsamqp://***@host. Eine Liste mit Credentials, deren Einträge nicht jeder mit einem eigenenscheme://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:4222kommt alsnats://***@h2:4222zurück. Gib jedem Eintrag sein eigenesscheme://, und jeder Host bleibt:nats://u:p@a:4222,nats://u:p@b:4222kommt alsnats://***@a:4222,nats://***@b:4222zurück. - Ein schemaloses
user:a,b@hosthat nichts, was den Beginn seiner Userinfo anzeigt, und kommt weiterhin alsuser:a,***@hostzurü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 maskiertDie 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.
Optionale Peer-Dependencies
Abschnitt betitelt „Optionale Peer-Dependencies“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'| Export | Zweck |
|---|---|
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.
Options-Builder und -Validatoren
Abschnitt betitelt „Options-Builder und -Validatoren“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.
Der ganze Werkzeugkasten — actor-ts/util
Abschnitt betitelt „Der ganze Werkzeugkasten — actor-ts/util“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.
| Export | Was 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. |
TokenBucket | Rate-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, SafeHtml | Escaping 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, isCidrEntry | CIDR 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, addressPinRejection | Die 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_CAPACITY | Die 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_ATTEMPTS | Die Traversal-Denylist, gegen die Aktorpfade und PersistenceIds beide geprüft werden, und die Grenze, bei der ein Eindeutigkeits-Neuziehen aufgibt. |
Wie weiter
Abschnitt betitelt „Wie weiter“- Logging — wo
safeStringifymeistens landet. - Aktoren erzeugen — Benennung, und was ein Aktorpfad preisgibt.
- Persistente Aktoren — was State enthalten darf und wie er round-trippt.
- Konfiguration — wie Options, HOCON und Defaults sich schichten.
- Installation — welche Abhängigkeiten des Frameworks optional sind.
