@pdsjs/spaces 1.0.0

package/src/writer.js

@@ -0,0 +1,195 @@
+// @pdsjs/spaces/writer - the single write path for permissioned repos.
+//
+// createRecord, putRecord, deleteRecord and applyWrites all funnel through
+// applyWrites here: one commit, one rev, one LtHash advance, one atomic
+// commitSpaceWrite. Nothing else mutates a permissioned repo.
+
+import {
+  cborEncodeDagCbor,
+  cidToString,
+  createCid,
+  createTid,
+} from '@pdsjs/core/repo';
+import { RepoCommit } from './commit.js';
+import { formatRecordPath } from './path.js';
+import { makeSpaceRow } from './space-row.js';
+
+export const MAX_WRITES_PER_COMMIT = 200;
+
+export class SpaceWriteError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} code - machine-readable error name for the XRPC response
+   */
+  constructor(message, code) {
+    super(message);
+    this.name = 'SpaceWriteError';
+    this.code = code;
+  }
+}
+
+export class SpaceRecordNotFoundError extends SpaceWriteError {
+  /** @param {string} collection @param {string} rkey */
+  constructor(collection, rkey) {
+    super(`Record not found: ${collection}/${rkey}`, 'RecordNotFound');
+  }
+}
+
+export class SpaceRecordAlreadyExistsError extends SpaceWriteError {
+  /** @param {string} collection @param {string} rkey */
+  constructor(collection, rkey) {
+    super(
+      `Record already exists: ${collection}/${rkey}`,
+      'RecordAlreadyExists',
+    );
+  }
+}
+
+// Commits for one space must not interleave: applyWrites reads the current set
+// hash and the touched records' CIDs, then commits a state derived from them.
+// Two concurrent commits would each fold their ops into the same starting hash
+// and the last write would drop the other's contribution. The port's commit is
+// atomic but cannot serialise across calls, so serialise here — sound because a
+// permissioned repo lives in exactly one process (a Node PDS, or one Durable
+// Object).
+/** @type {WeakMap<object, Map<string, Promise<any>>>} */
+const spaceQueues = new WeakMap();
+
+/**
+ * @template T
+ * @param {object} storage
+ * @param {string} space
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+function serialize(storage, space, fn) {
+  let queues = spaceQueues.get(storage);
+  if (!queues) {
+    queues = new Map();
+    spaceQueues.set(storage, queues);
+  }
+  const prior = queues.get(space) ?? Promise.resolve();
+  // Chain off the prior commit's settlement, not its value, so one failed
+  // commit does not poison every later write to the same space.
+  const next = prior.then(fn, fn);
+  queues.set(
+    space,
+    next.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return next;
+}
+
+/**
+ * @typedef {Object} SpaceWriteInput
+ * @property {'create'|'update'|'put'|'delete'} action
+ * @property {string} collection
+ * @property {string} rkey
+ * @property {Object} [record] - required for everything but delete
+ */
+
+/**
+ * @typedef {Object} SpaceWriteResult
+ * @property {'create'|'update'|'delete'} action
+ * @property {string} collection
+ * @property {string} rkey
+ * @property {string|null} cid - null for deletes
+ * @property {string|null} prev - null for creates
+ */
+
+/**
+ * Apply a batch of writes to a permissioned repo as one commit.
+ *
+ * Writes resolve in order against the state the batch has built up, not just
+ * what was stored on entry, so a batch can create then update a record and a
+ * repeated create is still caught rather than double-counted in the set hash.
+ *
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} storage
+ * @param {Object} opts
+ * @param {string} opts.space - space AT-URI
+ * @param {SpaceWriteInput[]} opts.writes
+ * @param {string} [opts.now] - ISO timestamp, for deterministic tests
+ * @returns {Promise<{rev: string, setHash: Uint8Array, results: SpaceWriteResult[]}>}
+ */
+export async function applyWrites(storage, { space, writes, now }) {
+  if (writes.length > MAX_WRITES_PER_COMMIT) {
+    throw new SpaceWriteError(
+      `Too many writes. Max: ${MAX_WRITES_PER_COMMIT}`,
+      'InvalidRequest',
+    );
+  }
+
+  return serialize(storage, space, async () => {
+    const timestamp = now ?? new Date().toISOString();
+
+    // A writer's PDS is never told about membership — the member list is the
+    // authority's concern — so it materialises its own repo on first write.
+    if ((await storage.getSpace(space)) === null) {
+      await storage.putSpace(
+        makeSpaceRow(space, { isOwner: false, createdAt: timestamp }),
+      );
+    }
+
+    const state = await storage.getSpaceRepo(space);
+    const repo = RepoCommit.fromState(state?.setHash ?? null);
+    const rev = createTid();
+
+    /** @type {Map<string, string|null>} live cid per touched path; null = deleted */
+    const staged = new Map();
+    /** @type {SpaceWriteResult[]} */
+    const results = [];
+    /** @type {import('@pdsjs/core/ports').SpaceWrite[]} */
+    const portWrites = [];
+
+    for (const write of writes) {
+      const { collection, rkey } = write;
+      const key = formatRecordPath(collection, rkey);
+      const prev = staged.has(key)
+        ? /** @type {string|null} */ (staged.get(key))
+        : await storage.getSpaceRecordCid(space, collection, rkey);
+
+      if (write.action === 'create' && prev) {
+        throw new SpaceRecordAlreadyExistsError(collection, rkey);
+      }
+      if ((write.action === 'update' || write.action === 'delete') && !prev) {
+        throw new SpaceRecordNotFoundError(collection, rkey);
+      }
+
+      if (write.action === 'delete') {
+        repo.applyOp({ collection, rkey, cid: null, prev });
+        staged.set(key, null);
+        results.push({ action: 'delete', collection, rkey, cid: null, prev });
+        portWrites.push({
+          action: 'delete',
+          collection,
+          rkey,
+          cid: null,
+          value: null,
+          prev,
+        });
+        continue;
+      }
+
+      const value = cborEncodeDagCbor(write.record);
+      const cid = cidToString(await createCid(value));
+      repo.applyOp({ collection, rkey, cid, prev });
+      staged.set(key, cid);
+
+      const action = prev ? 'update' : 'create';
+      results.push({ action, collection, rkey, cid, prev });
+      portWrites.push({ action, collection, rkey, cid, value, prev });
+    }
+
+    const setHash = repo.state();
+    await storage.commitSpaceWrite(space, {
+      writes: portWrites,
+      setHash,
+      rev,
+      indexedAt: timestamp,
+    });
+
+    return { rev, setHash, results };
+  });
+}