feat(storage): add raw binary-blob primitive to every storage adapter
Introduce a first-class binary-blob storage primitive on the StorageAdapter contract and implement it across all storage backends. This stores opaque byte payloads verbatim instead of base64-in-JSON, eliminating the ~33% inflation and full-materialization cost of the JSON envelope. It unblocks zero-copy, mmap-able column-store segments and batch vector I/O at billion scale. New methods (declared abstract on BaseStorageAdapter, the class that implements StorageAdapter, and added to the StorageAdapter interface): saveBinaryBlob(key, data) raw write, atomic on real filesystems loadBinaryBlob(key) exact bytes, or null if absent deleteBinaryBlob(key) idempotent (missing is ignored) getBinaryBlobPath(key) real local fs path where one exists, else null Shared key -> location convention across every adapter: the key's "/"-separated segments nest under a `_blobs/` prefix and are suffixed with `.bin`, e.g. "graph-lsm/source/sstable-123" -> "<root>/_blobs/graph-lsm/source/sstable-123.bin". Blobs are not branch-scoped (COW): they are immutable producer-managed segments. Per-adapter behavior: - FileSystemStorage: writes under <rootDir>/_blobs via tmp+rename; returns the real on-disk path so native code can mmap it directly. Path convention matches the existing MmapFileSystemStorage subclass byte-for-byte. - S3CompatibleStorage / R2Storage / GcsStorage / AzureBlobStorage: put/get/delete raw octet-stream objects; getBinaryBlobPath returns null (remote stores have no local path). - MemoryStorage: defensive-copied Map<string, Buffer>; null path; cleared on clear(). - OPFSStorage: stores raw bytes in the OPFS tree; null path. - HistoricalStorageAdapter: read-only — save/delete throw; load resolves the blob from the historical commit tree; null path. Tests: tests/unit/storage/binaryBlob.test.ts exercises save/load round-trip (byte-identical, incl. non-UTF8 bytes), overwrite, delete-then-load, load-missing, and getBinaryBlobPath behavior for all eight adapters. Cloud adapters run against in-memory client fakes that drive the real adapter code; OPFS runs against an in-memory FileSystem Access API mock; the historical adapter commits a blob into a real COW tree. 59 new tests; full unit suite (1398 tests) green.
This commit is contained in:
parent
547721ae14
commit
298b572671
12 changed files with 1552 additions and 0 deletions
|
|
@ -30,6 +30,11 @@ export class MemoryStorage extends BaseStorage {
|
|||
// Unified object store for primitive operations (replaces metadata, nounMetadata, verbMetadata)
|
||||
private objectStore: Map<string, any> = new Map()
|
||||
|
||||
// Raw binary-blob store, keyed by blob key. Holds opaque byte payloads
|
||||
// (column-store segments, batch vectors) verbatim — no JSON envelope. In-memory
|
||||
// storage has no local file, so getBinaryBlobPath() returns null.
|
||||
private blobStore: Map<string, Buffer> = new Map()
|
||||
|
||||
// Backward compatibility aliases
|
||||
private get metadata(): Map<string, any> {
|
||||
return this.objectStore
|
||||
|
|
@ -136,6 +141,54 @@ export class MemoryStorage extends BaseStorage {
|
|||
return paths.sort()
|
||||
}
|
||||
|
||||
// ===========================================================================
|
||||
// Raw binary-blob primitive
|
||||
// ===========================================================================
|
||||
|
||||
/**
|
||||
* Persist a raw binary blob in memory under `key`. A defensive copy of the
|
||||
* bytes is stored so later mutations to the caller's buffer don't corrupt the
|
||||
* stored blob. Overwrites any existing blob at the same key.
|
||||
*
|
||||
* @param key - The blob key.
|
||||
* @param data - The exact bytes to store.
|
||||
*/
|
||||
public async saveBinaryBlob(key: string, data: Buffer): Promise<void> {
|
||||
this.blobStore.set(key, Buffer.from(data))
|
||||
}
|
||||
|
||||
/**
|
||||
* Load a copy of the bytes stored under `key`, or `null` if absent. A copy is
|
||||
* returned so callers cannot mutate the stored blob in place.
|
||||
*
|
||||
* @param key - The blob key.
|
||||
* @returns The blob bytes, or `null` if absent.
|
||||
*/
|
||||
public async loadBinaryBlob(key: string): Promise<Buffer | null> {
|
||||
const data = this.blobStore.get(key)
|
||||
return data ? Buffer.from(data) : null
|
||||
}
|
||||
|
||||
/**
|
||||
* Delete the blob stored under `key`. Missing blobs are ignored.
|
||||
*
|
||||
* @param key - The blob key.
|
||||
*/
|
||||
public async deleteBinaryBlob(key: string): Promise<void> {
|
||||
this.blobStore.delete(key)
|
||||
}
|
||||
|
||||
/**
|
||||
* In-memory storage has no local filesystem path to mmap, so this always
|
||||
* returns `null`. Callers must use {@link loadBinaryBlob} instead.
|
||||
*
|
||||
* @param _key - The blob key (unused).
|
||||
* @returns Always `null`.
|
||||
*/
|
||||
public getBinaryBlobPath(_key: string): string | null {
|
||||
return null
|
||||
}
|
||||
|
||||
/**
|
||||
* Get multiple metadata objects in batches (CRITICAL: Prevents socket exhaustion)
|
||||
* Memory storage implementation is simple since all data is already in memory
|
||||
|
|
@ -163,6 +216,7 @@ export class MemoryStorage extends BaseStorage {
|
|||
*/
|
||||
public async clear(): Promise<void> {
|
||||
this.objectStore.clear()
|
||||
this.blobStore.clear()
|
||||
this.statistics = null
|
||||
this.totalNounCount = 0
|
||||
this.totalVerbCount = 0
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue