// --------------------------------------------------------------------------- // BlobStore — the seam for large, opaque, write-once data. Separate from // the relational adapter on purpose: blobs want different lifecycle, // durability, and placement (think S3/R2 in cloud, flat files locally) // than the metadata that indexes them. // // Plugins see a `PluginBlobStore` that's already namespaced to the // plugin id and bound to the executor's scope stack. Reads fall through // the stack in order (innermost first, first hit wins); writes and // deletes require an explicit scope id naming where the operation // should land. That mirrors the secrets API — shadowing by key on // read, explicit target on write. // // Error channel is `StorageError` — blobs only do read/write/delete, so // they never produce `UniqueViolationError`. The HTTP edge translates // `StorageError` to the opaque public `InternalError({ traceId })`. // --------------------------------------------------------------------------- import { Effect } from "effect"; import { StorageError } from "@executor-js/storage-core"; export interface BlobStore { readonly get: (namespace: string, key: string) => Effect.Effect; /** Multi-namespace lookup for a single key. Backends issue one query * (`WHERE namespace IN (...) AND key = ?`) and return the hits keyed * by namespace — the caller applies its own precedence. Lets * `pluginBlobStore` walk the scope stack in O(1) round-trips instead * of one per scope. */ readonly getMany: ( namespaces: readonly string[], key: string, ) => Effect.Effect, StorageError>; readonly put: ( namespace: string, key: string, value: string, ) => Effect.Effect; readonly delete: (namespace: string, key: string) => Effect.Effect; readonly has: (namespace: string, key: string) => Effect.Effect; } export interface PluginBlobStore { /** Walk the scope stack (innermost first) and return the first * non-null value for `key`. */ readonly get: (key: string) => Effect.Effect; /** Write `value` under `key` at the named scope. Scope must be one * of the executor's configured scopes. */ readonly put: ( key: string, value: string, options: { readonly scope: string }, ) => Effect.Effect; /** Delete `key` at the named scope. */ readonly delete: ( key: string, options: { readonly scope: string }, ) => Effect.Effect; /** Walk the scope stack and return true if any scope has a value for `key`. */ readonly has: (key: string) => Effect.Effect; } const assertScope = (scope: string, scopes: readonly string[]): Effect.Effect => scopes.includes(scope) ? Effect.void : Effect.fail( new StorageError({ message: `Blob write targets scope "${scope}" which is not in the ` + `executor's scope stack [${scopes.join(", ")}].`, cause: undefined, }), ); const nsFor = (scope: string, pluginId: string) => `${scope}/${pluginId}`; /** * Bind a `BlobStore` to a specific scope stack and plugin id. Reads * fall through the stack; writes require an explicit scope. Used by * the executor to build the `blobs` field handed to each plugin's * `storage` factory. */ export const pluginBlobStore = ( store: BlobStore, scopes: readonly string[], pluginId: string, ): PluginBlobStore => ({ get: (key) => Effect.gen(function* () { const namespaces = scopes.map((s) => nsFor(s, pluginId)); const hits = yield* store.getMany(namespaces, key); if (hits.size === 0) return null; for (const ns of namespaces) { const v = hits.get(ns); if (v !== undefined) return v; } return null; }), put: (key, value, options) => Effect.flatMap(assertScope(options.scope, scopes), () => store.put(nsFor(options.scope, pluginId), key, value), ), delete: (key, options) => Effect.flatMap(assertScope(options.scope, scopes), () => store.delete(nsFor(options.scope, pluginId), key), ), has: (key) => store .getMany( scopes.map((s) => nsFor(s, pluginId)), key, ) .pipe(Effect.map((hits) => hits.size > 0)), }); /** * Minimal in-memory BlobStore — good for tests and trivial hosts. Real * backends (filesystem, S3/R2, SQLite-table-backed) implement the same * interface. * * Every method is `Effect<_, never>` — a pure in-memory Map can't fail. * `never` is assignable to `StorageError`, so the result still fits the * `BlobStore` interface. */ export const makeInMemoryBlobStore = (): BlobStore => { const store = new Map(); const k = (ns: string, key: string) => `${ns}::${key}`; return { get: (ns, key) => Effect.sync(() => store.get(k(ns, key)) ?? null), getMany: (namespaces, key) => Effect.sync(() => { const hits = new Map(); for (const ns of namespaces) { const v = store.get(k(ns, key)); if (v !== undefined) hits.set(ns, v); } return hits; }), put: (ns, key, value) => Effect.sync(() => { store.set(k(ns, key), value); }), delete: (ns, key) => Effect.sync(() => { store.delete(k(ns, key)); }), has: (ns, key) => Effect.sync(() => store.has(k(ns, key))), }; };