Object Storage im Überblick
Das Object-Storage-Backend des Frameworks ist eine S3-kompatible Persistenz-Schicht. Zwei Implementierungen werden mitgeliefert:
| Backend | Verwendung |
|---|---|
FilesystemObjectStorageBackend | Lokale Dateien; Dev + Tests. |
S3ObjectStorageBackend | Alles S3-kompatible (AWS S3, MinIO, R2, B2). |
Verwendet von:
ObjectStorageDurableStateStore— Durable State im Cloud-Storage.ObjectStorageSnapshotStore— Snapshots im Cloud-Storage.
Gebaut auf einem kleinen Interface (PUT / GET / DELETE / LIST + CAS-Unterstützung); beide Backends sprechen dieselbe Oberfläche.
Wann verwenden
Abschnitt betitelt „Wann verwenden“| Du solltest Object Storage verwenden, wenn… |
|---|
| Du Cloud-native bist und S3 (oder ähnlich) deine Storage-Plattform ist. |
| Du geteilte Persistenz über Cluster-Nodes willst, ohne Cassandra zu betreiben. |
| Du Server-Side-Encryption über Cloud-KMS willst. |
| Du unendliches Scaling willst, ohne Storage-Kapazität zu verwalten. |
Für Single-Node-Deployments ist SQLite einfacher. Für High-Throughput-Multi-Node-Persistenz ist Cassandra schneller. Object Storage sitzt dazwischen — cloud-freundlich, anständige Performance, viele Features.
Ein minimales Beispiel
Abschnitt betitelt „Ein minimales Beispiel“import { DurableStateOptions, ObjectStorageDurableStateStore, ObjectStorageDurableStateStoreOptions, S3ObjectStorageBackend, S3ObjectStorageOptions,} from 'actor-ts/persistence';
const s3ObjectStorageOptions = S3ObjectStorageOptions.create() .withRegion('eu-west-1') .withBucket('my-app-state');const backend = new S3ObjectStorageBackend(s3ObjectStorageOptions);
const objectStorageDurableStateStoreOptions = ObjectStorageDurableStateStoreOptions.create().withBackend(backend);const stateStore = new ObjectStorageDurableStateStore( objectStorageDurableStateStoreOptions,);
const durableStateOptions = DurableStateOptions.create<State>() .withPersistenceId(`cart-${userId}`) .withStore(stateStore) .withEmptyState(() => ({ items: [] }));const cart = system.spawnAnonymous(() => new Cart(durableStateOptions));Der State von Cart lebt in S3 unter cart-<userId> als
Object-Key. Reads und Writes gehen durch die S3-API.
Was gespeichert wird
Abschnitt betitelt „Was gespeichert wird“Object-Keys folgen einem vorhersagbaren Layout:
state/ cart-user-42 # ein Object pro persistenceId cart-user-43
snapshots/ account-42/ seq-100 # Snapshots indexiert nach seqNr seq-200 seq-300Das Framework verwaltet dieses Layout; du baust keine Keys manuell.
Das Interface
Abschnitt betitelt „Das Interface“interface ObjectStorageBackend { put(key: string, body: Uint8Array, options?: PutOptions): Promise<{ etag: string }>; get(key: string): Promise<Option<ObjectFetched>>; delete(key: string): Promise<void>; list(options: { prefix: string; limit?: number }): Promise<ObjectInfo[]>;}Kleine Oberfläche — passt zu AWS S3, MinIO, Cloudflare R2, Backblaze B2, Wasabi, etc. Die meisten S3-kompatiblen APIs passen exakt.
CAS für optimistische Concurrency
Abschnitt betitelt „CAS für optimistische Concurrency“await backend.put('state/cart-42', body, { ifMatch: 'previous-etag',});ifMatch lässt Aufrufer Compare-and-Set-Writes machen — wenn
das aktuelle ETag abweicht, schlägt das Put mit
ObjectStorageConcurrencyError fehl. Verwendet von
ObjectStorageDurableStateStore, um nebenläufige Writer ohne
separate Koordination zu erkennen.
ifNoneMatch: '*' ist Create-only — gelingt nur, wenn der
Key noch nicht existiert.
Einige ältere S3-kompatible Stores beachten diese Header nicht richtig. Die Backend-Implementierungen des Frameworks werfen klar in diesem Fall, anstatt still zu ignorieren; prüfe die CAS-Unterstützung deines Providers, bevor du dich darauf verlässt.
Backends
Abschnitt betitelt „Backends“Filesystem
Abschnitt betitelt „Filesystem“import { FilesystemObjectStorageBackend, FilesystemObjectStorageOptions } from 'actor-ts/persistence';
const filesystemObjectStorageOptions = FilesystemObjectStorageOptions.create().withDir('/var/lib/actor-ts');const backend = new FilesystemObjectStorageBackend( filesystemObjectStorageOptions,);Speichert Objects als Dateien unter rootDir. Kein Netzwerk,
keine S3-Kosten. Richtig für:
- Tests — gleicher Code-Pfad wie Produktion, mit lokalen Dateien.
- Lokales Dev — kein MinIO-Container erforderlich.
- Kleine Single-Node-Deployments — wenn du speziell das Object-Storage-Interface ohne S3 willst.
Das Root-Verzeichnis ist die gesamte Welt dieses Backends. Ein
Key mit .., absolutem Präfix oder NUL-Byte wird direkt
abgelehnt, und jede Operation kanonisiert zusätzlich den Pfad, den
sie gleich anfasst — ein Symlink, der im Root liegt und aus ihm
herauszeigt, wird also abgelehnt statt verfolgt. Das Root selbst
darf ein Symlink sein: jede Operation löst es auf und misst das
Containment am Ergebnis, /var/lib/app -> /mnt/data funktioniert
also normal.
„Der Pfad, den sie gleich anfasst“ meint die Objektnamen: den Key
selbst, die Verzeichnisse darüber und seinen .meta.json-Sidecar.
Der Key und seine Eltern werden aus unterschiedlichen Gründen
geprüft, und keine der beiden Prüfungen deckt die andere ab —
rename folgt nie einem Link an der letzten Komponente, ein
verlinktes Elternverzeichnis verschiebt also, wo ein Body
landet, während get und das Compare-and-Swap von put den Key
beide mit readFile öffnen, und das folgt sehr wohl einem Link.
Drei Grenzen sollte man kennen, denn sonst nimmt man mehr an, als
die Prüfung leistet. Sie liest das Dateisystem und handelt
danach, lehnt also einen bereits vorhandenen Link ab, kann aber
das Rennen gegen einen nicht gewinnen, der genau dazwischen
gelegt wird — portables O_NOFOLLOW ist über node:fs nicht
erreichbar. Sie schließt die eigenen Operationen des Backends
ein; sie ist keine Sandbox um ein Verzeichnis, in das andere
lokale Prozesse schreiben dürfen. Wenn nicht vertrauenswürdige
Nutzer Einträge im Storage-Root anlegen können, ist das bereits
das größere Problem.
Die Lock-Datei pro Key ist anders abgedeckt, denn dort geht es
nicht um Containment. Das Nehmen des Locks ist ein exklusives
Create, das einen Link ablehnt statt ihm zu folgen. Die
Stale-Lock-Wiederherstellung, die nach Ablauf des
Acquisition-Timeouts läuft, stellt dann zwei Fragen zu diesem
Namen, und sie stellt sie mit lstat: wie alt der Eintrag ist und
ob er überhaupt eine reguläre Datei ist. Beides zählt. stat
würde das Alter des Ziels melden, ein auf eine uralte Datei
gerichteter Link könnte das Lock also für verwaist erklären; und
was keine reguläre Datei ist, hat dieses Backend nie geschrieben,
die Wiederherstellung lehnt es also ab, statt es zu entfernen.
Außerdem läuft die Wiederherstellung höchstens einmal pro
Acquisition — sie wird erst erreicht, wenn das Timeout schon
verbraucht ist, ein Eintrag mit stets gleicher Antwort würde sonst
endlos wiederholt.
import { S3ObjectStorageBackend, S3ObjectStorageOptions } from 'actor-ts/persistence';
const s3ObjectStorageOptions = S3ObjectStorageOptions.create() .withRegion('eu-west-1') .withBucket('my-app-state') .withEndpoint('https://s3.eu-west-1.amazonaws.com') // optionaler Override .withCredentials({ accessKeyId: process.env.AWS_ACCESS_KEY_ID!, secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!, });const backend = new S3ObjectStorageBackend(s3ObjectStorageOptions);Funktioniert mit jedem S3-kompatiblen Service. Für Nicht-AWS:
// MinIO:const s3ObjectStorageOptions = S3ObjectStorageOptions.create() .withRegion('us-east-1') .withBucket('my-bucket') .withEndpoint('http://minio:9000') .withForcePathStyle(true);new S3ObjectStorageBackend(s3ObjectStorageOptions);
// Cloudflare R2:const s3ObjectStorage2Options = S3ObjectStorageOptions.create() .withRegion('auto') .withBucket('my-bucket') .withEndpoint('https://<account-id>.r2.cloudflarestorage.com');new S3ObjectStorageBackend(s3ObjectStorage2Options);
// Backblaze B2:const s3ObjectStorage3Options = S3ObjectStorageOptions.create() .withRegion('us-west-002') .withBucket('my-bucket') .withEndpoint('https://s3.us-west-002.backblazeb2.com');new S3ObjectStorageBackend(s3ObjectStorage3Options);Aus der Konfiguration
Abschnitt betitelt „Aus der Konfiguration“Alles oben ist die Builder-Form, und sie bleibt der primäre Stil. Dieselbe Verdrahtung ist auch aus HOCON erreichbar — genau das, was eine Flotte braucht, wenn Bucket, Region und Prefix sich pro Umgebung unterscheiden:
actor-ts.persistence.snapshot-store { plugin = "actor-ts.persistence.snapshot-store.object-storage"
object-storage { backend = "s3" prefix = "env-prod/" keep-n = 5
compression { algorithm = "zstd" } encryption { mode = "sse-kms", kms-key-id = "arn:aws:kms:eu-central-1:…" }
s3 { bucket = "my-app-state" region = "eu-central-1" } }}import { ActorSystem, ActorSystemOptions } from 'actor-ts';import { registerObjectStoragePlugins, type ObjectStoragePluginHandles } from 'actor-ts/persistence';
let objectStorage: ObjectStoragePluginHandles | undefined;const systemOptions = ActorSystemOptions.create().withPersistence({ plugins: [async (persistence) => { objectStorage = await registerObjectStoragePlugins(persistence); }],});const system = ActorSystem.create('my-app', systemOptions);await system.whenReady();Gar kein Options-Argument: Das Plugin liest seinen Block über die Extension.
Ein Block konfiguriert beide Stores, die der Aufruf zurückgibt, denn
Snapshot Store und Durable-State-Store teilen sich ein einziges Backend. Das
Plug-in läuft innerhalb von ActorSystem.create, und der Start wartet auf das
Promise, das es zurückgibt, also lässt eine scheiternde Codec-Prüfung — etwa
ein nicht installierter Kompressions-Peer — den Start scheitern statt erst den
ersten persistierten Snapshot; siehe Stores beim Start
öffnen. Sobald
whenReady() erfüllt ist, hält objectStorage die Handles: den
Durable-State-Store und close(), das das geteilte Backend freigibt, sobald
das System beendet ist.
Options trotzdem zu übergeben funktioniert weiterhin und gewinnt Feld für Feld
— eine Option, die du nicht setzt, fällt auf HOCON durch, statt es zu
überdecken. Alle Blätter stehen in der
Konfigurationsreferenz.
Für Credentials und Schlüssel gibt es in diesem Block keinen Pfad. 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 nicht
tragen: 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, IAM
Roles for Service Accounts), und encryption.mode = client-aes256-gcm wird mit
einem OptionsError abgelehnt, der auf
ObjectStoragePluginOptions.withEncryption(…) zeigt, statt still Klartext zu
schreiben. kms-key-id ist eine ARN — ein Name — und damit unbedenklich.
Optionale Features
Abschnitt betitelt „Optionale Features“| Feature | Seite |
|---|---|
| Kompression (gzip / zstd) | Kompression |
| Verschlüsselung at rest (AES-GCM) | Verschlüsselung |
| Body-Integrität (HMAC-SHA256) | Body-Integrität |
| Storage-Key-Bindung + Rollback-Schutz | Einen Body an seinen Key binden |
| Master-Key-Rotation | Schlüsselrotation |
| Per-Actor-Kompressions- / Verschlüsselungs-Policies | Per-Actor-Policies |
| Snapshot-Store-Backend | Snapshot-Store-Backend |
Alle optional — starte ohne; schichte nach Bedarf darauf.
Performance
Abschnitt betitelt „Performance“Grobe Zahlen für S3:
- Put (kleines Objekt): 20-50 ms.
- Get: 10-30 ms.
- Delete: 30-50 ms.
Filesystem-Backend: Sub-Millisekunde.
Ein LIST im Filesystem-Backend liest nur das Verzeichnis, das
sein Prefix benennt — alles bis zum letzten / des Prefix —,
kostet also den getroffenen Teilbaum und nicht das gesamte
Storage-Root. Genau das hält ein Prefix pro persistenceId wie
snapshots/<pid>/ im Sub-Millisekunden-Bereich, egal wie viele
andere Entities sich das Root teilen. Ein Prefix ohne /
(snapshots) hat kein Verzeichnis, auf das es einschränken
könnte, und läuft weiterhin über alles — bevorzuge daher Keys mit
einem Verzeichnis-Segment pro Entity.
Object Storage ist langsamer als SQLite / Cassandra für einzelne Operationen. Kompensiere mit:
- Snapshot-Policies, die die Recovery begrenzen.
- CachedSnapshotStore-Decorator für Read-Through-Caching. Sind die Snapshots verschlüsselt, hält dieser Cache ihren Klartext — siehe Sicherheit — der Cache hält Klartext; deshalb verweigert der Decorator das Cachen eines verschlüsselten Loads, bis du es bestätigst.
- Batching, wo immer das Framework es erlaubt.
Wie geht’s weiter
Abschnitt betitelt „Wie geht’s weiter“- Kompression — gzip / zstd At-Rest-Kompression.
- Verschlüsselung — AES-GCM-Verschlüsselung at rest.
- Snapshot-Store-Backend — Snapshots in Object Storage.
- Durable State — der Haupt-Konsument.
- Persistenz im Überblick — das größere Bild.
