actor-ts 0.9.0

package/dist/persistence/object-storage/FilesystemObjectStorageBackend.js

@@ -0,0 +1,325 @@
+import { Lazy } from '../../util/Lazy.js';
+import { none, some } from '../../util/Option.js';
+import { wrapError } from '../../util/WrapError.js';
+import { makeKeyValidator } from '../storage/KeyValidator.js';
+import { ObjectStorageBackendError, ObjectStorageConcurrencyError, } from './ObjectStorageBackend.js';
+const DEFAULT_LOCK_TIMEOUT_MS = 5_000;
+const DEFAULT_STALE_LOCK_MS = 30_000;
+/**
+ * Reject keys that would escape the root directory via path-traversal
+ * (`../`, `\..\`, etc.), absolute-path injection, or NUL-byte tricks.
+ *
+ * **Exploit walkthrough (pre-fix):** the previous code did
+ * `path.join(root, key)` directly.  An attacker controlling `key`
+ * (e.g., a poorly-sanitised `persistenceId` flowing through the
+ * snapshot-store layer) could pass `'../../etc/passwd'` and read
+ * arbitrary files on the host, or `'/etc/passwd'` (absolute-path,
+ * Node's `path.join` interprets it as a full path and effectively
+ * ignores the root prefix on POSIX).
+ *
+ * This helper is the front-line syntactic check; {@link assertWithin
+ * Root} below is the defense-in-depth post-resolve check.
+ */
+/**
+ * Filesystem key-validation rules.  Same checks the pre-refactor
+ * `assertSafeKey` enforced — exported so other FS-style backends
+ * (S3, GCS) can reuse or extend.
+ *
+ * See `src/persistence/storage/KeyValidator.ts` for the factory.
+ */
+const FilesystemKeyRules = {
+    errorClass: ObjectStorageBackendError,
+    errorPrefix: 'invalid key',
+    rejectNul: true,
+    rejectAbsolutePaths: true,
+    rejectRelativeTraversal: true,
+};
+const assertSafeKey = makeKeyValidator(FilesystemKeyRules);
+/**
+ * Defense-in-depth post-`path.resolve` check that the computed
+ * absolute path stays under the configured root.  Catches edge cases
+ * the syntactic {@link assertSafeKey} might miss (e.g., URL-encoded
+ * traversal, symlinks resolved at OS level).
+ */
+function assertWithinRoot(pathMod, root, fullPath) {
+    const normRoot = pathMod.resolve(root);
+    const normFull = pathMod.resolve(fullPath);
+    if (normFull !== normRoot && !normFull.startsWith(normRoot + pathMod.sep)) {
+        throw new ObjectStorageBackendError(`path-traversal blocked: resolved path "${normFull}" escapes root "${normRoot}"`);
+    }
+}
+export class FilesystemObjectStorageBackend {
+    options;
+    lockTimeoutMs;
+    staleLockMs;
+    constructor(options) {
+        this.options = options;
+        this.lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+        this.staleLockMs = options.staleLockMs ?? DEFAULT_STALE_LOCK_MS;
+    }
+    async put(key, body, opts = {}) {
+        assertSafeKey(key);
+        const { fs, path } = await fsLazy.get();
+        const fullPath = path.join(this.options.dir, key);
+        assertWithinRoot(path, this.options.dir, fullPath);
+        const lockPath = fullPath + '.lock';
+        // Parent directory must exist before lock acquisition (the lock file
+        // lives there).  `mkdir(recursive)` is idempotent across processes,
+        // so concurrent puts to a fresh dir don't race here.
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        const release = await acquireLock(fs, lockPath, this.lockTimeoutMs, this.staleLockMs);
+        try {
+            // Read current state from disk — disk is canonical, no in-memory
+            // shadow that could disagree with another process's writes.
+            let currentEtag;
+            try {
+                const existing = new Uint8Array(await fs.readFile(fullPath));
+                currentEtag = computeEtag(existing);
+            }
+            catch (e) {
+                if (e?.code !== 'ENOENT') {
+                    throw new ObjectStorageBackendError(`filesystem put-read-current failed for ${key}`, e);
+                }
+                // ENOENT → object doesn't exist yet; currentEtag stays undefined.
+            }
+            // Validate CAS preconditions.
+            if (opts.ifNoneMatch === '*' && currentEtag !== undefined) {
+                throw new ObjectStorageConcurrencyError(key, `key ${key} already exists; ifNoneMatch=* rejected`);
+            }
+            if (opts.ifMatch !== undefined && currentEtag !== opts.ifMatch) {
+                throw new ObjectStorageConcurrencyError(key, `etag mismatch on ${key}: expected ${opts.ifMatch}, actual ${currentEtag ?? '<absent>'}`);
+            }
+            // Atomic write: write to a per-process temp file, then rename.
+            const tmpPath = `${fullPath}.tmp.${process.pid}.${Date.now()}.${Math.floor(Math.random() * 1e9)}`;
+            try {
+                await fs.writeFile(tmpPath, body);
+                await fs.rename(tmpPath, fullPath);
+            }
+            catch (e) {
+                try {
+                    await fs.unlink(tmpPath);
+                }
+                catch { /* may not exist */ }
+                throw wrapError(e, ObjectStorageBackendError, `filesystem put-write failed for ${key}`);
+            }
+            // Metadata sidecar.  Best-effort — a crash between rename(body) and
+            // writeFile(meta) leaves the body without metadata, which `get`
+            // tolerates by treating the sidecar as optional.
+            if (opts.contentEncoding || opts.contentType) {
+                const meta = JSON.stringify({
+                    contentEncoding: opts.contentEncoding,
+                    contentType: opts.contentType,
+                });
+                try {
+                    await fs.writeFile(fullPath + '.meta.json', meta);
+                }
+                catch (e) {
+                    throw wrapError(e, ObjectStorageBackendError, `filesystem put-meta failed for ${key}`);
+                }
+            }
+            return { etag: computeEtag(body) };
+        }
+        finally {
+            await release();
+        }
+    }
+    async get(key) {
+        assertSafeKey(key);
+        const { fs, path } = await fsLazy.get();
+        const fullPath = path.join(this.options.dir, key);
+        assertWithinRoot(path, this.options.dir, fullPath);
+        let body;
+        let stat;
+        try {
+            body = new Uint8Array(await fs.readFile(fullPath));
+            stat = await fs.stat(fullPath);
+        }
+        catch (e) {
+            if (e?.code === 'ENOENT')
+                return none;
+            throw wrapError(e, ObjectStorageBackendError, `filesystem get failed for ${key}`);
+        }
+        let contentEncoding;
+        let contentType;
+        try {
+            const metaRaw = await fs.readFile(fullPath + '.meta.json', 'utf8');
+            const meta = JSON.parse(metaRaw);
+            contentEncoding = meta.contentEncoding;
+            contentType = meta.contentType;
+        }
+        catch { /* no metadata sidecar → leave undefined */ }
+        return some({
+            body,
+            etag: computeEtag(body),
+            lastModified: stat.mtime,
+            contentEncoding,
+            contentType,
+        });
+    }
+    async delete(key) {
+        assertSafeKey(key);
+        const { fs, path } = await fsLazy.get();
+        const fullPath = path.join(this.options.dir, key);
+        assertWithinRoot(path, this.options.dir, fullPath);
+        const lockPath = fullPath + '.lock';
+        // Lock so a concurrent put doesn't see a half-deleted state mid-CAS.
+        // We may be deleting a never-written key (idempotent), but the
+        // serialization vs. concurrent puts still matters.
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        const release = await acquireLock(fs, lockPath, this.lockTimeoutMs, this.staleLockMs);
+        try {
+            try {
+                await fs.unlink(fullPath);
+            }
+            catch (e) {
+                if (e?.code === 'ENOENT') { /* idempotent */ }
+                else
+                    throw wrapError(e, ObjectStorageBackendError, `filesystem delete failed for ${key}`);
+            }
+            try {
+                await fs.unlink(fullPath + '.meta.json');
+            }
+            catch { /* sidecar may not exist */ }
+        }
+        finally {
+            await release();
+        }
+    }
+    async list(opts) {
+        // Empty prefix means "everything" — that's the standard list-all
+        // semantic and is safe.  Non-empty prefix has to obey the same
+        // key-shape rules as put/get/delete (no `..`, no absolute paths,
+        // no NUL bytes) — list otherwise could enumerate outside the root.
+        if (opts.prefix !== '')
+            assertSafeKey(opts.prefix);
+        const { fs, path } = await fsLazy.get();
+        const root = this.options.dir;
+        // Prefix may include a directory portion.  We walk from root and filter.
+        const out = [];
+        const walk = async (rel) => {
+            const full = path.join(root, rel);
+            let entries;
+            try {
+                entries = await fs.readdir(full, { withFileTypes: true });
+            }
+            catch (e) {
+                if (e?.code === 'ENOENT')
+                    return;
+                throw e;
+            }
+            for (const ent of entries) {
+                const childRel = rel ? `${rel}/${ent.name}` : ent.name;
+                if (ent.isDirectory()) {
+                    await walk(childRel);
+                }
+                else if (ent.isFile() && childRel.startsWith(opts.prefix)) {
+                    if (childRel.endsWith('.meta.json'))
+                        continue; // metadata sidecar
+                    if (childRel.endsWith('.lock'))
+                        continue; // per-key write lock
+                    if (TMP_FILE_RE.test(childRel))
+                        continue; // crash-leftover temp file
+                    const stat = await fs.stat(path.join(root, childRel));
+                    out.push({ key: childRel, size: stat.size, lastModified: stat.mtime });
+                }
+            }
+        };
+        await walk('');
+        out.sort((a, b) => a.key.localeCompare(b.key));
+        return opts.limit ? out.slice(0, opts.limit) : out;
+    }
+    async close() {
+        /* No in-memory state to clear — disk is canonical. */
+    }
+}
+const fsLazy = Lazy.of(async () => {
+    const fsName = 'node:fs/promises';
+    const pathName = 'node:path';
+    const fs = (await import(fsName));
+    const path = (await import(pathName));
+    return { fs, path };
+});
+/** Pattern emitted by `put`'s temp-file scheme — recognised by `list` to skip. */
+const TMP_FILE_RE = /\.tmp\.\d+\.\d+\.\d+$/;
+/**
+ * Acquire a per-key advisory lock by atomically creating `lockPath` with
+ * `O_EXCL`.  Retries with exponential backoff while the lock is held; on
+ * total timeout, falls through to a stale-lock check (lock files older
+ * than `staleLockMs` are forcibly removed, then one final retry is made).
+ *
+ * Returns an async release function that unlinks the lock file.  Callers
+ * must invoke it in a `finally` block; the OS won't auto-release on
+ * process exit (stale-lock detection covers that pathology).
+ */
+async function acquireLock(fs, lockPath, totalTimeoutMs, staleLockMs) {
+    const start = Date.now();
+    let backoffMs = 5;
+    // Bounded loop — termination is via either successful acquisition,
+    // throw on non-EEXIST error, or throw on total-timeout-exhausted.
+    for (;;) {
+        try {
+            await fs.writeFile(lockPath, `${process.pid} ${new Date().toISOString()}\n`, { flag: 'wx' });
+            return async () => {
+                try {
+                    await fs.unlink(lockPath);
+                }
+                catch { /* swallow — release is best-effort */ }
+            };
+        }
+        catch (e) {
+            const code = e?.code;
+            // POSIX returns `EEXIST` for `O_EXCL` collisions; Windows can also
+            // return `EPERM` when the lock file is in a transitional state
+            // (e.g. another writer just unlinked it but NTFS hasn't fully freed
+            // the directory entry yet — FILE_DISPOSITION_INFO pending), and
+            // `EBUSY` if the file is held open by another handle.  Both are
+            // benign retry signals; only genuinely unexpected codes (EROFS,
+            // ENOSPC, …) should bubble out as a backend error.
+            if (code !== 'EEXIST' && code !== 'EPERM' && code !== 'EBUSY') {
+                throw new ObjectStorageBackendError(`failed to acquire lock ${lockPath} (code=${code ?? '<none>'})`, e);
+            }
+            const elapsed = Date.now() - start;
+            if (elapsed >= totalTimeoutMs) {
+                // Total timeout exhausted — last-ditch stale-lock check.  If the
+                // lock file is older than `staleLockMs`, the holder almost
+                // certainly crashed; remove it and retry one more time.  If the
+                // lock disappears between EEXIST and stat (winner finished mid-
+                // check), `continue` lets us retake it normally.
+                let stale = false;
+                try {
+                    const stat = await fs.stat(lockPath);
+                    stale = Date.now() - stat.mtime.getTime() > staleLockMs;
+                }
+                catch {
+                    continue; // lock vanished — try to acquire it on the next loop
+                }
+                if (stale) {
+                    try {
+                        await fs.unlink(lockPath);
+                    }
+                    catch { /* race with another reclaimer is fine */ }
+                    continue;
+                }
+                throw new ObjectStorageBackendError(`timed out acquiring lock ${lockPath} after ${totalTimeoutMs}ms`);
+            }
+            await new Promise((r) => setTimeout(r, backoffMs));
+            backoffMs = Math.min(100, backoffMs * 2);
+        }
+    }
+}
+/** Cheap content-derived ETag — FNV-1a hex + length suffix. */
+function computeEtag(body) {
+    // Sync, deterministic approximation good enough for FS:
+    // 32-bit FNV-1a over the bytes, hex-prefixed.  Real S3 uses MD5/sha256;
+    // for our CAS purposes the only invariant required is "same bytes →
+    // same etag, different bytes → different etag with very high probability".
+    let h = 0x811c9dc5;
+    for (let i = 0; i < body.length; i++) {
+        h ^= body[i];
+        h = (h * 0x01000193) >>> 0;
+    }
+    // Mix in length so empty vs single-zero-byte differ trivially.
+    h ^= body.length;
+    return `"fs-${(h >>> 0).toString(16).padStart(8, '0')}-${body.length}"`;
+}
+//# sourceMappingURL=FilesystemObjectStorageBackend.js.map

package/dist/persistence/object-storage/FilesystemObjectStorageBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilesystemObjectStorageBackend.js","sourceRoot":"","sources":["../../../src/persistence/object-storage/FilesystemObjectStorageBackend.ts"],"names":[],"mappings":"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"}

package/dist/persistence/object-storage/ObjectStorageBackend.d.ts

@@ -0,0 +1,86 @@
+import type { Option } from '../../util/Option.js';
+/**
+ * Generic object-storage abstraction — the same surface that an S3-style
+ * service exposes (PUT / GET / DELETE / LIST), reduced to the minimum
+ * actor-ts needs.  Two implementations ship: `FilesystemObjectStorage
+ * Backend` for tests and local dev, `S3ObjectStorageBackend` for any
+ * S3-compatible service (AWS S3, MinIO, Cloudflare R2, Backblaze B2, …).
+ *
+ * The `ifMatch` / `ifNoneMatch` options exist to support optimistic
+ * concurrency control — required by `ObjectStorageDurableStateStore` to
+ * detect concurrent writers.  Backends that can't honour them (e.g. some
+ * older S3-compatible stores) must throw `ObjectStorageBackendError` with
+ * a clear message rather than silently ignoring them, so callers know
+ * their CAS expectation was lost.
+ */
+export interface PutOptions {
+    readonly contentType?: string;
+    /** Set when the body is compressed; matches the HTTP `Content-Encoding` header. */
+    readonly contentEncoding?: string;
+    /**
+     * Strict CAS: the operation succeeds only if the object's current ETag
+     * matches.  Mismatch → `ObjectStorageConcurrencyError`.  S3 maps this
+     * to the `If-Match` request header.
+     */
+    readonly ifMatch?: string;
+    /**
+     * Create-only — succeed only if the object does NOT yet exist.  The
+     * sentinel `'*'` matches S3's `If-None-Match: *` semantics.
+     */
+    readonly ifNoneMatch?: '*';
+    /**
+     * Server-side encryption hint.  Only honoured by S3-style backends;
+     * filesystem backends ignore it.
+     */
+    readonly sse?: 'AES256' | {
+        readonly kmsKeyId: string;
+    };
+}
+export interface ObjectInfo {
+    readonly key: string;
+    readonly size: number;
+    readonly lastModified: Date;
+}
+export interface ObjectFetched {
+    readonly body: Uint8Array;
+    readonly etag: string;
+    readonly lastModified: Date;
+    readonly contentEncoding?: string;
+    readonly contentType?: string;
+}
+export interface ObjectStorageBackend {
+    /** PUT — returns the new ETag.  Throws on CAS failure. */
+    put(key: string, body: Uint8Array, opts?: PutOptions): Promise<{
+        etag: string;
+    }>;
+    /** GET — None if the object doesn't exist. */
+    get(key: string): Promise<Option<ObjectFetched>>;
+    /** DELETE — idempotent; deleting a non-existent key is a no-op. */
+    delete(key: string): Promise<void>;
+    /**
+     * LIST — returns object keys under `prefix`, sorted ascending by key.
+     * `limit` is a soft cap, the backend may return fewer entries.
+     */
+    list(opts: {
+        readonly prefix: string;
+        readonly limit?: number;
+    }): Promise<ObjectInfo[]>;
+    /** Optional: shut down any underlying client / file handle. */
+    close?(): Promise<void>;
+}
+/**
+ * CAS conflict — thrown by `put` when `ifMatch` / `ifNoneMatch` rejects.
+ * Backends should map their native conflict (412 Precondition Failed for
+ * S3, OS-level rename-failure for filesystem) to this error type so
+ * higher layers can detect it portably.
+ */
+export declare class ObjectStorageConcurrencyError extends Error {
+    readonly key: string;
+    constructor(key: string, message?: string);
+}
+/** Generic fault from a backend operation that isn't a CAS conflict. */
+export declare class ObjectStorageBackendError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+//# sourceMappingURL=ObjectStorageBackend.d.ts.map

package/dist/persistence/object-storage/ObjectStorageBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectStorageBackend.d.ts","sourceRoot":"","sources":["../../../src/persistence/object-storage/ObjectStorageBackend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,GAAG,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,GAAG;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CACzD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC;IAC5B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjF,8CAA8C;IAC9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;IACjD,mEAAmE;IACnE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACxF,+DAA+D;IAC/D,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;aAC1B,GAAG,EAAE,MAAM;gBAAX,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAI1D;AAED,wEAAwE;AACxE,qBAAa,yBAA0B,SAAQ,KAAK;aACL,KAAK,CAAC,EAAE,OAAO;gBAAhD,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,OAAO,YAAA;CAI7D"}

package/dist/persistence/object-storage/ObjectStorageBackend.js

@@ -0,0 +1,24 @@
+/**
+ * CAS conflict — thrown by `put` when `ifMatch` / `ifNoneMatch` rejects.
+ * Backends should map their native conflict (412 Precondition Failed for
+ * S3, OS-level rename-failure for filesystem) to this error type so
+ * higher layers can detect it portably.
+ */
+export class ObjectStorageConcurrencyError extends Error {
+    key;
+    constructor(key, message) {
+        super(message ?? `object-storage CAS conflict on key ${key}`);
+        this.key = key;
+        this.name = 'ObjectStorageConcurrencyError';
+    }
+}
+/** Generic fault from a backend operation that isn't a CAS conflict. */
+export class ObjectStorageBackendError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'ObjectStorageBackendError';
+    }
+}
+//# sourceMappingURL=ObjectStorageBackend.js.map

package/dist/persistence/object-storage/ObjectStorageBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectStorageBackend.js","sourceRoot":"","sources":["../../../src/persistence/object-storage/ObjectStorageBackend.ts"],"names":[],"mappings":"AAqEA;;;;;GAKG;AACH,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IAC1B;IAA5B,YAA4B,GAAW,EAAE,OAAgB;QACvD,KAAK,CAAC,OAAO,IAAI,sCAAsC,GAAG,EAAE,CAAC,CAAC;QADpC,QAAG,GAAH,GAAG,CAAQ;QAErC,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED,wEAAwE;AACxE,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IACL;IAA7C,YAAY,OAAe,EAAkB,KAAe;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,UAAK,GAAL,KAAK,CAAU;QAE1D,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF"}

package/dist/persistence/object-storage/ObjectStoragePlugin.d.ts

@@ -0,0 +1,93 @@
+import type { PersistenceExtension } from '../PersistenceExtension.js';
+import { ObjectStorageDurableStateStore } from '../durable-state-stores/ObjectStorageDurableStateStore.js';
+import { type S3Credentials } from './S3ObjectStorageBackend.js';
+import type { ObjectStorageBackend } from './ObjectStorageBackend.js';
+import { type CompressionConfig, type CompressionResolver, type EncryptionConfig, type EncryptionResolver } from './PluginConfig.js';
+/** Canonical plugin IDs registered by `registerObjectStoragePlugins`. */
+export declare const OBJECT_STORAGE_SNAPSHOT_PLUGIN_ID = "actor-ts.persistence.snapshot-store.object-storage";
+export declare const OBJECT_STORAGE_DURABLE_STATE_PLUGIN_ID = "actor-ts.persistence.durable-state.object-storage";
+/**
+ * Backend selection — discriminated union so the plugin can build either
+ * the filesystem-backed or the S3-backed object store from a single
+ * config blob.  An already-constructed `ObjectStorageBackend` is also
+ * accepted for advanced cases (mock backend in tests, custom subclass).
+ */
+export type ObjectStorageBackendSpec = {
+    readonly kind: 'filesystem';
+    readonly dir: string;
+} | {
+    readonly kind: 's3';
+    readonly bucket: string;
+    readonly region: string;
+    readonly endpoint?: string;
+    readonly forcePathStyle?: boolean;
+    readonly credentials?: S3Credentials;
+} | {
+    readonly kind: 'custom';
+    readonly backend: ObjectStorageBackend;
+};
+export interface ObjectStoragePluginOptions {
+    /** Plugin ID under which the snapshot store is registered. */
+    readonly snapshotPluginId?: string;
+    /** Plugin ID for the durable-state store. */
+    readonly durableStatePluginId?: string;
+    /** Backend definition — filesystem, S3, or custom. */
+    readonly backend: ObjectStorageBackendSpec;
+    /** Key prefix prepended to every object — e.g. `'env-prod/'`. */
+    readonly prefix?: string;
+    /** Snapshot history retention; `0` disables pruning.  Default: 3. */
+    readonly keepN?: number;
+    /** Compression config or per-pid resolver.  Default: gzip. */
+    readonly compression?: CompressionConfig | CompressionResolver;
+    /** Encryption config or per-pid resolver.  Default: none. */
+    readonly encryption?: EncryptionConfig | EncryptionResolver;
+}
+export interface ObjectStoragePluginHandles {
+    /** The shared backend — both stores write through this. */
+    readonly backend: ObjectStorageBackend;
+    /**
+     * The DurableState store instance.  `PersistenceExtension` doesn't
+     * carry a DurableState registry today, so callers that want
+     * DurableState pass this directly into `DurableStateActor`'s
+     * settings.
+     */
+    readonly durableStateStore: ObjectStorageDurableStateStore;
+}
+/**
+ * Register the object-storage SnapshotStore against `PersistenceExtension`
+ * and return a ready-to-use DurableStateStore instance.  Mirrors the
+ * Cassandra plugin's one-call wiring while accepting that DurableState
+ * isn't extension-managed today — callers who want DurableState read
+ * `handles.durableStateStore` from the return value and pass it into
+ * their `DurableStateActor` settings.
+ *
+ * **Eager peer-dep validation (#18, #59).**  Before returning, this
+ * function probes any optional peer-dependency the configured codecs
+ * need — `fzstd` for `compression: 'zstd'` (when neither Bun nor
+ * Node 22.15+ provides a native impl), `SubtleCrypto` when any
+ * encryption config is supplied.  A failing probe surfaces the
+ * "install X" message **here**, at registration time, instead of
+ * silently surviving until the first persist call.  For resolvers
+ * built via `compressionByPrefix` / `encryptionByPrefix` every config
+ * the resolver could return is probed; opaque user-written resolvers
+ * fall back to first-use checks.
+ *
+ * Example:
+ *
+ *   const ext = system.extension(PersistenceExtensionId);
+ *   const { durableStateStore } = await registerObjectStoragePlugins(ext, {
+ *     backend: { kind: 's3', bucket: 'my-app', region: 'eu-central-1' },
+ *     compression: { algorithm: 'zstd' },
+ *     encryption:  encryptionByPrefix({ default: { mode: 'sse-s3' } }),
+ *   });
+ *   // ... and to make the snapshot plugin active:
+ *   //   actor-ts.persistence.snapshot-store.plugin = "actor-ts.persistence.snapshot-store.object-storage"
+ */
+export declare function registerObjectStoragePlugins(ext: PersistenceExtension, options: ObjectStoragePluginOptions): Promise<ObjectStoragePluginHandles>;
+/**
+ * Probe every codec peer-dep the configured options may need.  Public
+ * so callers can pre-validate (e.g. at app bootstrap) independently of
+ * actually registering the plugin.
+ */
+export declare function validateObjectStoragePeerDeps(options: ObjectStoragePluginOptions): Promise<void>;
+//# sourceMappingURL=ObjectStoragePlugin.d.ts.map

package/dist/persistence/object-storage/ObjectStoragePlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectStoragePlugin.d.ts","sourceRoot":"","sources":["../../../src/persistence/object-storage/ObjectStoragePlugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,8BAA8B,EAAE,MAAM,2DAA2D,CAAC;AAK3G,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,yEAAyE;AACzE,eAAO,MAAM,iCAAiC,uDAAuD,CAAC;AACtG,eAAO,MAAM,sCAAsC,sDAAsD,CAAC;AAE1G;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACrD;IACE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC;CACtC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAExE,MAAM,WAAW,0BAA0B;IACzC,8DAA8D;IAC9D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAC3C,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,GAAG,mBAAmB,CAAC;IAC/D,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,GAAG,kBAAkB,CAAC;CAC7D;AAED,MAAM,WAAW,0BAA0B;IACzC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,EAAE,8BAA8B,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,4BAA4B,CAChD,GAAG,EAAE,oBAAoB,EACzB,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,0BAA0B,CAAC,CAwBrC;AAED;;;;GAIG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAiBf"}