@vantran-se/openchamber-web 1.24.4 → 2.0.1

package/server/lib/openchamber-sessions/session-metadata-store.js

@@ -0,0 +1,285 @@
+/**
+ * OpenChamber per-session metadata, held by OpenCode.
+ *
+ * Goal mode, session assist, obligatory context re-injection and pinned
+ * notes/plans keep their per-session state in the session's `metadata`, under
+ * the `openchamber` namespace. OpenCode 2.0.15 added `PATCH /api/session/{id}`
+ * with `metadata`, so the OpenCode record is the single authority and every
+ * client reading `session.metadata` sees the same thing.
+ *
+ * OpenCode replaces the whole object on PATCH. Writers here send a JSON Merge
+ * Patch (RFC 7386): nested objects merge key by key and a `null` deletes. The
+ * store reads the record, merges, and writes the result back, one write per
+ * session at a time, so goal mode saving progress cannot drop an assist recap
+ * that was written a moment earlier.
+ *
+ * Before 2.0.15 the state lived in `sessions-metadata.json` under the data dir.
+ * Entries still in that file are the newest metadata their sessions have: they
+ * are served from the file and pushed to OpenCode, lazily on the session's
+ * first write and in one sweep once OpenCode is up. A pushed entry leaves the
+ * file; an empty file is renamed to `sessions-metadata.json.migrated` and kept
+ * so nothing is lost if a migration turns out wrong.
+ */
+
+import fsDefault from 'node:fs';
+import pathDefault from 'node:path';
+
+import { createOpenCodeClient as createOpenCodeClientDefault } from './opencode-client.js';
+
+const LEGACY_FILE_NAME = 'sessions-metadata.json';
+
+const asNonEmptyString = (value) => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * RFC 7386 merge. Returns a new object; `null` in the patch removes the key,
+ * and a non-object patch value replaces whatever was there.
+ */
+export const mergeMetadataPatch = (current, patch) => {
+  const base = isPlainObject(current) ? { ...current } : {};
+  if (!isPlainObject(patch)) return base;
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) {
+      delete base[key];
+      continue;
+    }
+    base[key] = isPlainObject(value) ? mergeMetadataPatch(base[key], value) : value;
+  }
+  return base;
+};
+
+const isSessionNotFound = (error) => error?._tag === 'SessionNotFoundError';
+
+/**
+ * Reads and writes one session's metadata on OpenCode. `read` resolves `null`
+ * when OpenCode does not know the session; any other failure throws, because
+ * "could not ask" must not become "empty".
+ */
+export const createOpenCodeSessionMetadata = ({
+  buildOpenCodeUrl,
+  getOpenCodeAuthHeaders,
+  createOpenCodeClient = createOpenCodeClientDefault,
+}) => {
+  const clientFor = (directory) => createOpenCodeClient({
+    baseUrl: buildOpenCodeUrl('/', '').replace(/\/$/, ''),
+    headers: getOpenCodeAuthHeaders(),
+    directory,
+  });
+  return {
+    read: async (sessionID, { directory = '' } = {}) => {
+      let session;
+      try {
+        // The 2.x client unwraps the `{ data }` envelope: this is the record itself.
+        session = await clientFor(directory).session.get({ sessionID });
+      } catch (error) {
+        if (isSessionNotFound(error)) return null;
+        throw error;
+      }
+      return isPlainObject(session?.metadata) ? session.metadata : {};
+    },
+    write: (sessionID, metadata, { directory = '' } = {}) =>
+      clientFor(directory).session.update({ sessionID, metadata }),
+  };
+};
+
+/**
+ * @param {object} options
+ * @param {string} options.dataDir OpenChamber data directory; holds the legacy file.
+ * @param {{ read: Function, write: Function }} options.openCode See {@link createOpenCodeSessionMetadata}.
+ * @param {typeof fsDefault.promises} [options.fsPromises]
+ * @param {typeof pathDefault} [options.path]
+ * @param {() => number} [options.now]
+ */
+export const createSessionMetadataStore = ({
+  dataDir,
+  openCode,
+  fsPromises = fsDefault.promises,
+  path = pathDefault,
+  now = Date.now,
+}) => {
+  const legacyPath = path.join(dataDir, LEGACY_FILE_NAME);
+
+  /** sessionID → metadata from the legacy file that OpenCode does not hold yet. */
+  const unmigrated = new Map();
+  let legacyLoad = null;
+
+  /**
+   * One chain per session: read, merge and write cannot interleave with another
+   * write to the same session. Different sessions proceed in parallel.
+   */
+  const sessionChains = new Map();
+  const runForSession = (id, work) => {
+    const previous = sessionChains.get(id) ?? Promise.resolve();
+    const next = previous.then(work, work);
+    const settled = next.then(() => undefined, () => undefined);
+    sessionChains.set(id, settled);
+    void settled.then(() => {
+      if (sessionChains.get(id) === settled) sessionChains.delete(id);
+    });
+    return next;
+  };
+
+  /** Legacy file rewrites, one at a time so an older snapshot never lands last. */
+  let fileChain = Promise.resolve();
+  const runFileWrite = (work) => {
+    const next = fileChain.then(work, work);
+    fileChain = next.then(() => undefined, () => undefined);
+    return next;
+  };
+
+  const parseLegacy = (raw) => {
+    const parsed = JSON.parse(raw);
+    if (!isPlainObject(parsed)) throw new Error('session metadata file is not a JSON object');
+    const result = new Map();
+    for (const [sessionID, value] of Object.entries(parsed)) {
+      const id = asNonEmptyString(sessionID);
+      if (id && isPlainObject(value)) result.set(id, value);
+    }
+    return result;
+  };
+
+  /**
+   * Resolves once the legacy file has been read. A read failure rejects and
+   * lets the next call retry: writing while the file is unknown could push an
+   * older record over one the file still holds, or the file's older record over
+   * a newer write later on.
+   */
+  const loadLegacy = () => {
+    if (!legacyLoad) {
+      legacyLoad = (async () => {
+        let raw;
+        try {
+          raw = await fsPromises.readFile(legacyPath, 'utf8');
+        } catch (error) {
+          if (error?.code === 'ENOENT') return;
+          throw new Error(`session metadata is unavailable: ${error?.message ?? error}`);
+        }
+        try {
+          for (const [id, metadata] of parseLegacy(raw)) unmigrated.set(id, metadata);
+        } catch (error) {
+          // Unreadable bytes are kept for the user; there is nothing to migrate.
+          const backup = `${legacyPath}.corrupt-${now()}`;
+          await fsPromises.rename(legacyPath, backup).catch(() => undefined);
+          console.warn(`[openchamber-sessions] legacy session metadata was unreadable and was moved to ${backup}: ${error?.message ?? error}`);
+        }
+      })().catch((error) => {
+        legacyLoad = null;
+        throw error;
+      });
+    }
+    return legacyLoad;
+  };
+
+  /** Writes what is left to migrate, or retires the file once nothing is. */
+  const persistLegacy = () => runFileWrite(async () => {
+    if (unmigrated.size === 0) {
+      await fsPromises.rename(legacyPath, `${legacyPath}.migrated`).catch((error) => {
+        if (error?.code !== 'ENOENT') throw error;
+      });
+      return;
+    }
+    const tmpPath = `${legacyPath}.${process.pid}.tmp`;
+    await fsPromises.writeFile(tmpPath, JSON.stringify(Object.fromEntries(unmigrated)), 'utf8');
+    await fsPromises.rename(tmpPath, legacyPath);
+  });
+
+  /**
+   * Drops a pushed entry from the legacy file. OpenCode already holds the
+   * record, so a failed rewrite does not fail the write that caused it. The
+   * entry then stays on disk and the next start pushes that older copy again;
+   * the next rewrite of the file (any other migrated session) clears it first.
+   */
+  const forgetLegacy = async (id) => {
+    unmigrated.delete(id);
+    await persistLegacy().catch((error) => {
+      console.warn('[openchamber-sessions] could not update the legacy session metadata file:', error?.message ?? error);
+    });
+  };
+
+  /**
+   * The session's full metadata: the legacy entry while it is still waiting to
+   * be migrated, OpenCode's record otherwise. `{}` for a session OpenCode does
+   * not know. Throws when OpenCode could not be asked.
+   */
+  const get = async (sessionID, { directory = '' } = {}) => {
+    const id = asNonEmptyString(sessionID);
+    if (!id) return {};
+    await loadLegacy();
+    if (unmigrated.has(id)) return unmigrated.get(id);
+    return (await openCode.read(id, { directory })) ?? {};
+  };
+
+  /**
+   * Applies a merge patch on OpenCode and returns the full metadata afterwards.
+   * Nothing is written when the current record cannot be read, so a patch never
+   * replaces fields it could not see.
+   */
+  const setSessionMetadata = async (sessionID, patch, { directory = '' } = {}) => {
+    const id = asNonEmptyString(sessionID);
+    if (!id) throw new Error('a session id is required to store session metadata');
+    if (!isPlainObject(patch)) throw new Error('a session metadata patch must be an object');
+    await loadLegacy();
+
+    return runForSession(id, async () => {
+      const fromLegacy = unmigrated.has(id);
+      const current = fromLegacy ? unmigrated.get(id) : await openCode.read(id, { directory });
+      if (current === null) throw new Error(`session ${id} was not found`);
+      const merged = mergeMetadataPatch(current, patch);
+      await openCode.write(id, merged, { directory });
+      if (fromLegacy) await forgetLegacy(id);
+      return merged;
+    });
+  };
+
+  /**
+   * Pushes every legacy entry to OpenCode. A session OpenCode no longer knows
+   * has nothing to receive its metadata, so its entry is dropped. Any other
+   * failure keeps the entry for the next sweep. Resolves the number of entries
+   * still waiting.
+   */
+  const migrateLegacy = async () => {
+    await loadLegacy();
+    const pending = [...unmigrated.keys()];
+    if (pending.length === 0) return 0;
+    let changed = false;
+    await Promise.all(pending.map((id) => runForSession(id, async () => {
+      // A write that ran first already migrated it.
+      if (!unmigrated.has(id)) return;
+      try {
+        await openCode.write(id, unmigrated.get(id));
+      } catch (error) {
+        if (!isSessionNotFound(error)) {
+          console.warn(`[openchamber-sessions] could not migrate metadata for ${id}:`, error?.message ?? error);
+          return;
+        }
+      }
+      unmigrated.delete(id);
+      changed = true;
+    })));
+    if (changed) await persistLegacy();
+    return unmigrated.size;
+  };
+
+  /**
+   * `{ [sessionID]: metadata }` for sessions whose metadata still lives in the
+   * legacy file. The proxy lays these over OpenCode's records until they are
+   * migrated; empty once migration is done.
+   */
+  const listUnmigrated = async () => {
+    await loadLegacy();
+    return Object.fromEntries(unmigrated);
+  };
+
+  return {
+    get,
+    setSessionMetadata,
+    migrateLegacy,
+    listUnmigrated,
+    legacyPath,
+  };
+};

package/server/lib/openchamber-sessions/session-metadata-store.test.js

@@ -0,0 +1,259 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createSessionMetadataStore, mergeMetadataPatch } from './session-metadata-store.js';
+
+const tempDirs = [];
+
+const makeDataDir = () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-metadata-'));
+  tempDirs.push(dir);
+  return dir;
+};
+
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+  }
+  vi.restoreAllMocks();
+});
+
+describe('mergeMetadataPatch', () => {
+  it('merges nested objects key by key instead of replacing them', () => {
+    const current = { openchamber: { goal: { id: 'g1', status: 'active' }, assist: { recap: 'r' } } };
+    const merged = mergeMetadataPatch(current, { openchamber: { goal: { status: 'complete' } } });
+
+    expect(merged).toEqual({
+      openchamber: { goal: { id: 'g1', status: 'complete' }, assist: { recap: 'r' } },
+    });
+    // The input is untouched: callers keep whatever they already held.
+    expect(current.openchamber.goal.status).toBe('active');
+  });
+
+  it('deletes a key when its patch value is null', () => {
+    expect(mergeMetadataPatch({ a: 1, b: 2 }, { b: null })).toEqual({ a: 1 });
+    expect(mergeMetadataPatch({ openchamber: { goal: {}, assist: {} } }, { openchamber: { assist: null } }))
+      .toEqual({ openchamber: { goal: {} } });
+  });
+
+  it('replaces arrays and scalars rather than merging into them', () => {
+    expect(mergeMetadataPatch({ pins: ['a', 'b'] }, { pins: ['c'] })).toEqual({ pins: ['c'] });
+    expect(mergeMetadataPatch({ a: { nested: true } }, { a: 'flat' })).toEqual({ a: 'flat' });
+  });
+
+  it('treats a missing or non-object base as empty', () => {
+    expect(mergeMetadataPatch(undefined, { a: 1 })).toEqual({ a: 1 });
+    expect(mergeMetadataPatch('nope', { a: 1 })).toEqual({ a: 1 });
+    expect(mergeMetadataPatch({ a: 1 }, 'nope')).toEqual({ a: 1 });
+  });
+});
+
+const legacyFile = (dataDir) => path.join(dataDir, 'sessions-metadata.json');
+const writeLegacy = (dataDir, content) => {
+  fs.writeFileSync(legacyFile(dataDir), typeof content === 'string' ? content : JSON.stringify(content));
+};
+
+const notFound = () => Object.assign(new Error('Session not found'), { _tag: 'SessionNotFoundError' });
+
+/**
+ * OpenCode's side: records by session id. A `write` replaces the whole object,
+ * which is what `PATCH /api/session/{id}` does with `metadata`.
+ */
+const createFakeOpenCode = (records = {}) => {
+  const sessions = new Map(Object.entries(records));
+  const fake = {
+    sessions,
+    writes: [],
+    failRead: null,
+    failWrite: null,
+    read: vi.fn(async (id) => {
+      if (fake.failRead) throw fake.failRead;
+      return sessions.has(id) ? structuredClone(sessions.get(id)) : null;
+    }),
+    write: vi.fn(async (id, metadata) => {
+      // Yield first so concurrent writers really overlap.
+      await Promise.resolve();
+      if (fake.failWrite) throw fake.failWrite;
+      if (!sessions.has(id)) throw notFound();
+      fake.writes.push([id, metadata]);
+      sessions.set(id, structuredClone(metadata));
+    }),
+  };
+  return fake;
+};
+
+const makeStore = (openCode, dataDir = makeDataDir()) => ({
+  dataDir,
+  store: createSessionMetadataStore({ dataDir, openCode }),
+});
+
+describe('createSessionMetadataStore', () => {
+  it('reads metadata from OpenCode, and a session OpenCode does not know as empty', async () => {
+    const openCode = createFakeOpenCode({ ses_1: { openchamber: { goal: { id: 'g1' } } } });
+    const { store } = makeStore(openCode);
+
+    await expect(store.get('ses_1')).resolves.toEqual({ openchamber: { goal: { id: 'g1' } } });
+    await expect(store.get('ses_missing')).resolves.toEqual({});
+  });
+
+  it('surfaces a failed read instead of answering empty', async () => {
+    const openCode = createFakeOpenCode({ ses_1: { a: 1 } });
+    openCode.failRead = new Error('connection refused');
+    const { store } = makeStore(openCode);
+
+    await expect(store.get('ses_1')).rejects.toThrow('connection refused');
+  });
+
+  it('merges a patch onto the OpenCode record and writes the whole result back', async () => {
+    const openCode = createFakeOpenCode({
+      ses_1: { openchamber: { kind: 'review', assist: { recap: 'r' } } },
+    });
+    const { store } = makeStore(openCode);
+
+    const merged = await store.setSessionMetadata('ses_1', { openchamber: { goal: { status: 'active' } } });
+
+    expect(merged).toEqual({ openchamber: { kind: 'review', assist: { recap: 'r' }, goal: { status: 'active' } } });
+    expect(openCode.sessions.get('ses_1')).toEqual(merged);
+    await store.setSessionMetadata('ses_1', { openchamber: { assist: null } });
+    expect(openCode.sessions.get('ses_1')).toEqual({ openchamber: { kind: 'review', goal: { status: 'active' } } });
+  });
+
+  it('keeps both of two concurrent patches to the same session', async () => {
+    const openCode = createFakeOpenCode({ ses_1: {} });
+    const { store } = makeStore(openCode);
+
+    await Promise.all([
+      store.setSessionMetadata('ses_1', { openchamber: { goal: { status: 'active' } } }),
+      store.setSessionMetadata('ses_1', { openchamber: { assist: { recap: 'r' } } }),
+    ]);
+
+    expect(openCode.sessions.get('ses_1')).toEqual({
+      openchamber: { goal: { status: 'active' }, assist: { recap: 'r' } },
+    });
+  });
+
+  it('writes nothing when the current record cannot be read or the session is gone', async () => {
+    const openCode = createFakeOpenCode({ ses_1: { keep: true } });
+    const { store } = makeStore(openCode);
+
+    openCode.failRead = new Error('timeout');
+    await expect(store.setSessionMetadata('ses_1', { a: 1 })).rejects.toThrow('timeout');
+    openCode.failRead = null;
+    await expect(store.setSessionMetadata('ses_missing', { a: 1 })).rejects.toThrow('not found');
+
+    expect(openCode.write).not.toHaveBeenCalled();
+    expect(openCode.sessions.get('ses_1')).toEqual({ keep: true });
+  });
+
+  it('rejects a missing id or a non-object patch', async () => {
+    const { store } = makeStore(createFakeOpenCode());
+    await expect(store.setSessionMetadata('', { a: 1 })).rejects.toThrow();
+    await expect(store.setSessionMetadata('ses_1', ['a'])).rejects.toThrow();
+  });
+
+  describe('legacy sessions-metadata.json', () => {
+    it('serves a legacy entry over the OpenCode record until it is migrated', async () => {
+      const openCode = createFakeOpenCode({ ses_1: { openchamber: { kind: 'review' } } });
+      const dataDir = makeDataDir();
+      writeLegacy(dataDir, { ses_1: { openchamber: { kind: 'review', goal: { id: 'g1' } } } });
+      const { store } = makeStore(openCode, dataDir);
+
+      await expect(store.get('ses_1')).resolves.toEqual({ openchamber: { kind: 'review', goal: { id: 'g1' } } });
+      await expect(store.listUnmigrated()).resolves.toEqual({
+        ses_1: { openchamber: { kind: 'review', goal: { id: 'g1' } } },
+      });
+      expect(openCode.read).not.toHaveBeenCalled();
+    });
+
+    it('migrates a legacy entry on its first write, merged with the patch', async () => {
+      const openCode = createFakeOpenCode({ ses_1: { stale: true }, ses_2: {} });
+      const dataDir = makeDataDir();
+      writeLegacy(dataDir, { ses_1: { openchamber: { goal: { id: 'g1' } } }, ses_2: { notes: ['n'] } });
+      const { store } = makeStore(openCode, dataDir);
+
+      await store.setSessionMetadata('ses_1', { openchamber: { assist: { recap: 'r' } } });
+
+      // The legacy record is the newer one: it wins over what OpenCode held.
+      expect(openCode.sessions.get('ses_1')).toEqual({ openchamber: { goal: { id: 'g1' }, assist: { recap: 'r' } } });
+      expect(JSON.parse(fs.readFileSync(legacyFile(dataDir), 'utf8'))).toEqual({ ses_2: { notes: ['n'] } });
+      await expect(store.listUnmigrated()).resolves.toEqual({ ses_2: { notes: ['n'] } });
+    });
+
+    it('pushes every entry, drops sessions OpenCode no longer has, and retires the file', async () => {
+      const openCode = createFakeOpenCode({ ses_1: { stale: true }, ses_2: { stale: true } });
+      const dataDir = makeDataDir();
+      // `{}` is a cleared record: it must clear OpenCode's copy too.
+      writeLegacy(dataDir, { ses_1: { openchamber: { goal: { id: 'g1' } } }, ses_2: {}, ses_gone: { a: 1 } });
+      const { store } = makeStore(openCode, dataDir);
+
+      await expect(store.migrateLegacy()).resolves.toBe(0);
+
+      expect(openCode.sessions.get('ses_1')).toEqual({ openchamber: { goal: { id: 'g1' } } });
+      expect(openCode.sessions.get('ses_2')).toEqual({});
+      expect(fs.existsSync(legacyFile(dataDir))).toBe(false);
+      expect(JSON.parse(fs.readFileSync(`${legacyFile(dataDir)}.migrated`, 'utf8'))).toMatchObject({ ses_gone: { a: 1 } });
+      await expect(store.get('ses_1')).resolves.toEqual({ openchamber: { goal: { id: 'g1' } } });
+    });
+
+    it('keeps an entry OpenCode could not take for the next sweep', async () => {
+      const openCode = createFakeOpenCode({ ses_1: {} });
+      const dataDir = makeDataDir();
+      writeLegacy(dataDir, { ses_1: { a: 1 } });
+      const { store } = makeStore(openCode, dataDir);
+
+      openCode.failWrite = new Error('connection refused');
+      await expect(store.migrateLegacy()).resolves.toBe(1);
+      expect(JSON.parse(fs.readFileSync(legacyFile(dataDir), 'utf8'))).toEqual({ ses_1: { a: 1 } });
+      await expect(store.get('ses_1')).resolves.toEqual({ a: 1 });
+
+      openCode.failWrite = null;
+      await expect(store.migrateLegacy()).resolves.toBe(0);
+      expect(openCode.sessions.get('ses_1')).toEqual({ a: 1 });
+    });
+
+    it('does not push a legacy entry over a write that migrated it first', async () => {
+      const openCode = createFakeOpenCode({ ses_1: {} });
+      const dataDir = makeDataDir();
+      writeLegacy(dataDir, { ses_1: { a: 1 } });
+      const { store } = makeStore(openCode, dataDir);
+
+      await Promise.all([store.setSessionMetadata('ses_1', { b: 2 }), store.migrateLegacy()]);
+
+      expect(openCode.sessions.get('ses_1')).toEqual({ a: 1, b: 2 });
+    });
+
+    it('moves a malformed file aside and has nothing to migrate', async () => {
+      const openCode = createFakeOpenCode({ ses_1: { a: 1 } });
+      const dataDir = makeDataDir();
+      writeLegacy(dataDir, '{ not json');
+      const { store } = makeStore(openCode, dataDir);
+
+      await expect(store.get('ses_1')).resolves.toEqual({ a: 1 });
+      expect(fs.readdirSync(dataDir).some((name) => name.startsWith('sessions-metadata.json.corrupt-'))).toBe(true);
+    });
+
+    it('refuses to write while the file cannot be read, then recovers', async () => {
+      const openCode = createFakeOpenCode({ ses_1: {} });
+      const dataDir = makeDataDir();
+      const readFile = vi.fn(async () => {
+        throw Object.assign(new Error('permission denied'), { code: 'EACCES' });
+      });
+      const store = createSessionMetadataStore({
+        dataDir,
+        openCode,
+        fsPromises: { ...fs.promises, readFile },
+      });
+
+      await expect(store.setSessionMetadata('ses_1', { a: 1 })).rejects.toThrow('permission denied');
+      expect(openCode.write).not.toHaveBeenCalled();
+
+      readFile.mockImplementation(async () => {
+        throw Object.assign(new Error('missing'), { code: 'ENOENT' });
+      });
+      await expect(store.setSessionMetadata('ses_1', { a: 1 })).resolves.toEqual({ a: 1 });
+    });
+  });
+});