Zum Inhalt springen
Deutsch

Object Storage im Überblick

Das Object-Storage-Backend des Frameworks ist eine S3-kompatible Persistenz-Schicht. Zwei Implementierungen werden mitgeliefert:

BackendVerwendung
FilesystemObjectStorageBackendLokale Dateien; Dev + Tests.
S3ObjectStorageBackendAlles 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.

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.

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.

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

Das Framework verwaltet dieses Layout; du baust keine Keys manuell.

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.

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.

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);

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.

FeatureSeite
Kompression (gzip / zstd)Kompression
Verschlüsselung at rest (AES-GCM)Verschlüsselung
Body-Integrität (HMAC-SHA256)Body-Integrität
Storage-Key-Bindung + Rollback-SchutzEinen Body an seinen Key binden
Master-Key-RotationSchlüsselrotation
Per-Actor-Kompressions- / Verschlüsselungs-PoliciesPer-Actor-Policies
Snapshot-Store-BackendSnapshot-Store-Backend

Alle optional — starte ohne; schichte nach Bedarf darauf.

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.