@statewalker/webrun-storage 0.2.1 → 0.3.0

package/README.md

@@ -1,58 +1,108 @@
 # @statewalker/webrun-storage
 
-Domain-neutral byte-persistence seam: an immutable content-addressed `BlobStore` and a mutable `KvStore` with atomic compare-and-set.
+## What it is
 
-## Overview
+A small byte-persistence layer with two primitives: an immutable `BlobStore` keyed by a
+caller-supplied id, and a mutable `KvStore` with atomic compare-and-set. A `RefStore` facade
+stores string ids on top of a `KvStore`. Adapters are included for memory and for any
+`FilesApi` from `@statewalker/webrun-files`.
 
-`storage` is the persistence seam both axes of the two-axis VCS architecture plug into. It defines two small low-level primitives — a `BlobStore` (immutable, keyed by a caller-supplied id, with ranged reads and byte `size`) and a `KvStore` (mutable, keyed, with an atomic `cas`) — plus a thin typed `RefStore` facade over the KV primitive. It stores bytes and nothing more: it knows nothing of git objects, chunks, or hashing algorithms (**the caller owns every id**).
+## Why it exists
 
-Adapters implement the two primitives over different backends; `content-store` and `vcs-core` ride on top. This package ships an in-memory adapter and a `FilesApi`-backed adapter; SQL / KV backends are separate adapters over the same interfaces.
+Higher layers (a chunked content store, a git object store, ref tables) all need the same two
+things from a backend: write an immutable blob under a known id, and update a pointer atomically.
+This package defines exactly that contract and nothing more. A new backend (SQL, KV, cloud
+object storage) implements two interfaces, and every layer above works on it unchanged.
 
-## Installation
+## How to use
 
 ```bash
 pnpm add @statewalker/webrun-storage
 ```
 
-## Quick Start
+| Import | Contents |
+| --- | --- |
+| `@statewalker/webrun-storage` | `memBlobStore`, `memKvStore`, `filesBlobStore`, `refStore`, and the types `BlobStore`, `KvStore`, `RefStore`, `ObjectStore`, `ByteStream`, `FilesBlobStoreOptions`. ESM, runs in browsers, Node and workers. |
+
+`BlobStore`:
+
+- `put(id, bytes, opts?)`: stores a byte stream. Re-putting the same id is idempotent.
+  `opts.verify(bytes)` re-derives the id; on mismatch `put` rejects and stores nothing.
+- `get(id, range?)`: byte stream; `range` is `{ start?, end? }` with `end` exclusive. An absent id
+  yields an empty stream.
+- `has(id)`, `remove(id)` (resolves `false` if absent), `size(id)` (`-1` if absent),
+  `list(prefix?)`.
+
+`KvStore`: `get`, `put`, `remove`, `list(prefix?)`, and `cas(key, expected, next)`, which writes
+and returns `true` only when the current value equals `expected` byte for byte. `expected ===
+undefined` means "must not exist"; `next === undefined` deletes.
+
+`RefStore`: `read(name)`, `compareAndSet(name, expected, next)`, `list(prefix?)`, all with string
+ids. `ObjectStore` is an alias of `BlobStore`.
+
+## Examples
+
+Blobs in memory and over a `FilesApi`:
 
 ```typescript
 import { MemFilesApi } from "@statewalker/webrun-files-mem";
-import { filesBlobStore, memBlobStore, memKvStore, refStore } from "@statewalker/webrun-storage";
-
-// Immutable, content-addressed blobs (in-memory, or over any FilesApi):
-const blobs = memBlobStore();
-const overFiles = filesBlobStore(new MemFilesApi());
+import { filesBlobStore, memBlobStore } from "@statewalker/webrun-storage";
 
 async function* streamOf(...parts: string[]) {
   for (const p of parts) yield new TextEncoder().encode(p);
 }
 
-await blobs.put("a1", streamOf("hello ", "world")); // caller owns the id
-await blobs.has("a1"); // true
-await blobs.size("a1"); // 11, or -1 if absent
-const tail = blobs.get("a1", { start: 6 }); // ranged read -> "world"
+const blobs = memBlobStore();
+await blobs.put("a1b2c3", streamOf("hello ", "world")); // the caller owns the id
+await blobs.size("a1b2c3"); // 11
+const tail = blobs.get("a1b2c3", { start: 6 }); // "world"
+
+const onDisk = filesBlobStore(new MemFilesApi(), { root: "/objects" });
+await onDisk.put("a1b2c3", streamOf("hello")); // stored at /objects/a1/b2c3
+```
 
-// Mutable KV with atomic compare-and-set, and the ref facade over it:
-const kv = memKvStore();
-const created = await kv.cas("head", undefined, new TextEncoder().encode("v1")); // true (create)
+Atomic pointer updates:
 
-const refs = refStore(kv);
-await refs.compareAndSet("refs/heads/main", undefined, "commit-1");
-const id = await refs.read("refs/heads/main"); // "commit-1"
+```typescript
+import { memKvStore, refStore } from "@statewalker/webrun-storage";
+
+const refs = refStore(memKvStore());
+await refs.compareAndSet("refs/heads/main", undefined, "commit-1"); // true: created
+await refs.compareAndSet("refs/heads/main", "commit-0", "commit-2"); // false: lost the race
+await refs.read("refs/heads/main"); // "commit-1"
 ```
 
-## API
+## Internals
+
+### Ids belong to the caller
+
+`put` never hashes. A git store passes git object ids, a chunk store passes its own chunk hashes.
+The package therefore depends on no hash library and works with any id scheme. Integrity checking
+is opt-in through `verify`; a mismatch fails with
+`blob id mismatch: supplied "<id>", verify computed "<computed>"`.
+
+### Compare-and-set is part of the contract
+
+`cas` is a required method, not an optional capability, so `RefStore` can always offer atomic
+updates without checking what the backend supports. The in-memory adapter is atomic because
+JavaScript runs it in one turn.
+
+### One backend object per blob
+
+`filesBlobStore` writes each blob to its own file, sharded like git's loose objects:
+`<root>/<first two chars>/<rest>`. Ids shorter than three characters produce odd paths; use
+hash-like ids. Packing and chunk grouping are left to the layers above.
+
+### Ranged reads
+
+`get(id, { start, end })` matches the usual "inclusive start, exclusive end" slice convention, so
+random access into pack files and large blobs needs no full read.
 
-- **`BlobStore`** — `put(id, bytes, opts?)` (streaming, bounded-memory; `opts.verify` re-derives and checks the id), `get(id, range?)` with `{ start?, end? }` (end exclusive), `has(id)`, `remove(id)`, `size(id)` (`-1` when absent), `list(prefix?)`. Re-putting the same id is idempotent. `ObjectStore` is an alias.
-- **`KvStore`** — `get` / `put` / `remove` / `list`, plus `cas(key, expected, next)` (writes and returns `true` only if the current value deep-equals `expected`; `next === undefined` deletes).
-- **`RefStore`** — thin string-id facade over a `KvStore`: `read`, `compareAndSet`, `list`.
+### Dependencies
 
-**Adapters & facade:** `memBlobStore()`, `memKvStore()`, `filesBlobStore(files, opts?)`, `refStore(kv)`.
+Only `@statewalker/webrun-files`, for the `FilesApi` type used by `filesBlobStore`. No runtime
+dependencies.
 
-## Notes
+## License
 
-- **Hash-agnostic.** `put(id, …)` takes the id from the caller — `content-store` hashes chunks, `vcs-core` computes git object ids. Optional integrity verification is a caller-injected `verify` on `put`.
-- **CAS is a required primitive** so `RefStore` always gets atomic compare-and-set with no per-consumer branching.
-- **One backend object per blob;** packing/CDC-grouping lives in the layers above (`vcs-core` packfiles, `content-store` chunks).
-- The same behavioural suite runs against every adapter (mem and files), and the seam is bounded-memory by construction. Built red/green TDD.
+MIT

package/dist/files-blob-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files-blob-store.d.ts","sourceRoot":"","sources":["../src/files-blob-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,YAAY,CAAC;AAExD,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAkDvF"}
+{"version":3,"file":"files-blob-store.d.ts","sourceRoot":"","sources":["../src/files-blob-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,YAAY,CAAC;AAExD,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAID;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,SAAS,CA4DvF"}

package/dist/index.js

@@ -42,13 +42,19 @@ async function assertVerified(id, chunks, verify) {
 }
 //#endregion
 //#region src/files-blob-store.ts
+const isDotSegment = (segment) => segment === "." || segment === "..";
 /**
 * {@link BlobStore} backed by a {@link FilesApi}. Ids map to git-style sharded
 * paths (`ab/cdef…`) so a large id space never lands in one flat directory.
 */
 function filesBlobStore(files, opts) {
 	const base = (opts?.root ?? "/").replace(/\/+$/, "");
-	const pathFor = (id) => `${base}/${id.slice(0, 2)}/${id.slice(2)}`;
+	const pathFor = (id) => {
+		const shard = id.slice(0, 2);
+		const rest = id.slice(2);
+		if (id === "" || /[/\\]/.test(id) || isDotSegment(shard) || isDotSegment(rest)) throw new Error(`Invalid blob id: ${JSON.stringify(id)}`);
+		return `${base}/${shard}/${rest}`;
+	};
 	const idFrom = (relative) => relative.replace("/", "");
 	return {
 		async put(id, bytes, opts) {

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@statewalker/webrun-storage",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Domain-neutral byte-persistence seam (BlobStore + KvStore with CAS) over the webrun-files FilesApi",
+  "bugs": {
+    "url": "https://github.com/statewalker/webrun-sync/issues"
+  },
+  "homepage": "https://github.com/statewalker/webrun-sync/tree/main/packages/webrun-storage#readme",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/statewalker/webrun-vcs.git",
+    "url": "git+https://github.com/statewalker/webrun-sync.git",
     "directory": "packages/webrun-storage"
   },
   "private": false,
@@ -27,10 +31,10 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-files": "^0.10.0"
+    "@statewalker/webrun-files": "^0.12.0"
   },
   "devDependencies": {
-    "@statewalker/webrun-files-mem": "^0.10.0",
+    "@statewalker/webrun-files-mem": "^0.12.0",
     "rolldown": "^1.2.12",
     "vitest": "^5.0.3",
     "typescript": "^7.0.2",
@@ -45,6 +49,7 @@
     "format": "biome format --write .",
     "format:check": "biome format .",
     "format:fix": "biome check --write --unsafe .",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.tests.json"
   }
 }

package/src/files-blob-store.ts

@@ -7,6 +7,8 @@ export interface FilesBlobStoreOptions {
   root?: string;
 }
 
+const isDotSegment = (segment: string): boolean => segment === "." || segment === "..";
+
 /**
  * {@link BlobStore} backed by a {@link FilesApi}. Ids map to git-style sharded
  * paths (`ab/cdef…`) so a large id space never lands in one flat directory.
@@ -14,7 +16,17 @@ export interface FilesBlobStoreOptions {
 export function filesBlobStore(files: FilesApi, opts?: FilesBlobStoreOptions): BlobStore {
   const base = (opts?.root ?? "/").replace(/\/+$/, "");
 
-  const pathFor = (id: string): string => `${base}/${id.slice(0, 2)}/${id.slice(2)}`;
+  const pathFor = (id: string): string => {
+    const shard = id.slice(0, 2);
+    const rest = id.slice(2);
+    // webrun-files resolves `..` before any mount or guard sees the path, so an
+    // id carrying a separator or a dot segment would land outside `root`. Ids
+    // come from remote peers (content-transfer's serve-store), so refuse them.
+    if (id === "" || /[/\\]/.test(id) || isDotSegment(shard) || isDotSegment(rest)) {
+      throw new Error(`Invalid blob id: ${JSON.stringify(id)}`);
+    }
+    return `${base}/${shard}/${rest}`;
+  };
   const idFrom = (relative: string): string => relative.replace("/", "");
 
   return {