@bevel-software/platform-core-backend 0.28.1 → 0.30.0

package/src/modules/workflow/file-lock.service.ts

@@ -23,6 +23,28 @@
  * never be keyed on a path no file verb would accept. See
  * `canonicalFileIdentity`.
  *
+ * Workspace identity works the same way. The lock routes pass the `:id`
+ * path param, which Express URL-decodes, so a slashed branch's workspace
+ * arrives as `alice/feature`; the deletion gate and the git status probe ask
+ * with the encoded `alice%2Ffeature`. Every method keys rows on
+ * `canonicalWorkspaceId`, so both spellings are one workspace and a held file
+ * is seen whichever spelling asks.
+ *
+ * Unlike raw path spellings (below), rows written under the decoded workspace id before this
+ * landed are still honoured until they go: every read, heartbeat and release
+ * also matches that spelling, and an acquire is refused while a live row
+ * under it holds the same file. Otherwise a lock held across the upgrade
+ * would be invisible for up to its TTL — to the deletion gate and to a second
+ * editor alike. Nothing new is ever written under it, so once the last such
+ * row has expired or been released the extra spelling matches nothing.
+ *
+ * This covers rows LEFT by the previous version, not rows it is still
+ * writing: a previous-version process never looks at a canonical row, so no
+ * check here could make the two contend while both run. They never do — one
+ * server process owns the workspaces directory (see `branchLifecycle` in the
+ * workflow service; this service's deletion gate is in-process for the same
+ * reason), and an upgrade stops the old process before the new one starts.
+ *
  * There is no transition handling for rows written under a raw spelling
  * before this landed: such a row is now unreachable by name and expires on
  * its own TTL. For one deploy an in-flight edit's lock can linger up to the
@@ -35,12 +57,13 @@
  * bounded by concurrent editors, not history, so lazy GC is fine.
  */
 
-import { and, eq, gt, lte } from 'drizzle-orm';
+import { and, eq, gt, inArray, lte } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { fileLocks } from '../database/schema.js';
 import type { AcquireLockResult, AuthUser, FileLock } from '@bevel-software/platform-shared';
 import { WorkflowValidationError } from '../../shared/domain-errors.js';
 import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
+import { branchForWorkspaceId, canonicalWorkspaceId } from '../../shared/workspace-id.js';
 
 /**
  * Lock lifetime without a heartbeat. The client is expected to heartbeat
@@ -51,6 +74,17 @@ import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
  */
 const LOCK_TTL_MS = 60_000;
 
+/**
+ * The workspace ids a lock row of canonical workspace `workspaceId` can sit
+ * under: the canonical one every write uses, then — for a slashed branch —
+ * the decoded one rows were written under before workspace ids were
+ * canonicalised. See the module comment.
+ */
+function workspaceSpellings(workspaceId: string): string[] {
+  const legacy = branchForWorkspaceId(workspaceId);
+  return legacy === workspaceId ? [workspaceId] : [workspaceId, legacy];
+}
+
 function rowToFileLock(row: typeof fileLocks.$inferSelect): FileLock {
   return {
     branch: row.branch,
@@ -125,13 +159,14 @@ export class FileLockService {
    * (or vice versa).
    */
   async acquire(
-    workspaceId: string,
+    rawWorkspaceId: string,
     branch: string,
     rawPath: string,
     user: AuthUser,
     opts?: { coordination?: boolean },
   ): Promise<AcquireLockResult> {
     const targetPath = canonicalFileIdentity(rawPath);
+    const workspaceId = canonicalWorkspaceId(rawWorkspaceId);
     if (this.closing.has(branch)) {
       throw new WorkflowValidationError(`"${branch}" is being deleted, so "${targetPath}" cannot be held for editing.`, {
         kind: 'branch-being-deleted',
@@ -190,6 +225,25 @@ export class FileLockService {
     // `heartbeat()` (which has its own same-user UPDATE), and the
     // editor's save flow detects "I already hold it" via `getLock` in
     // `workspace.routes.withLock` rather than re-acquiring.
+    // A live row under the pre-canonical spelling holds this file as surely
+    // as one under the canonical id; the upsert below cannot see it.
+    const legacy = workspaceSpellings(workspaceId).slice(1);
+    if (legacy.length > 0) {
+      const [held] = await this.db
+        .select()
+        .from(fileLocks)
+        .where(
+          and(
+            inArray(fileLocks.workspaceId, legacy),
+            eq(fileLocks.branch, branch),
+            eq(fileLocks.path, targetPath),
+            gt(fileLocks.expiresAt, now),
+          ),
+        )
+        .limit(1);
+      if (held) return { acquired: false, lock: rowToFileLock(held) };
+    }
+
     const mode = opts?.coordination ? 'coordination' : 'edit';
     const upsertResult = await this.db
       .insert(fileLocks)
@@ -255,12 +309,13 @@ export class FileLockService {
    * current holder.
    */
   async heartbeat(
-    workspaceId: string,
+    rawWorkspaceId: string,
     branch: string,
     rawPath: string,
     user: AuthUser,
   ): Promise<FileLock> {
     const targetPath = canonicalFileIdentity(rawPath);
+    const workspaceId = canonicalWorkspaceId(rawWorkspaceId);
     const now = new Date();
     const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
     // The expiry guard (`expiresAt > now`) matters because an expired
@@ -279,7 +334,7 @@ export class FileLockService {
       .set({ lastHeartbeatAt: now, expiresAt })
       .where(
         and(
-          eq(fileLocks.workspaceId, workspaceId),
+          inArray(fileLocks.workspaceId, workspaceSpellings(workspaceId)),
           eq(fileLocks.branch, branch),
           eq(fileLocks.path, targetPath),
           eq(fileLocks.holderUserId, user.id),
@@ -302,17 +357,18 @@ export class FileLockService {
    * over by someone else — that's not an error from the caller's POV).
    */
   async release(
-    workspaceId: string,
+    rawWorkspaceId: string,
     branch: string,
     rawPath: string,
     user: AuthUser,
   ): Promise<void> {
     const targetPath = canonicalFileIdentity(rawPath);
+    const workspaceId = canonicalWorkspaceId(rawWorkspaceId);
     await this.db
       .delete(fileLocks)
       .where(
         and(
-          eq(fileLocks.workspaceId, workspaceId),
+          inArray(fileLocks.workspaceId, workspaceSpellings(workspaceId)),
           eq(fileLocks.branch, branch),
           eq(fileLocks.path, targetPath),
           eq(fileLocks.holderUserId, user.id),
@@ -326,25 +382,30 @@ export class FileLockService {
    * are purged here lazily.
    */
   async get(
-    workspaceId: string,
+    rawWorkspaceId: string,
     branch: string,
     rawPath: string,
   ): Promise<FileLock | null> {
     const targetPath = canonicalFileIdentity(rawPath);
+    const workspaceId = canonicalWorkspaceId(rawWorkspaceId);
     const rows = await this.db
       .select()
       .from(fileLocks)
       .where(
         and(
-          eq(fileLocks.workspaceId, workspaceId),
+          inArray(fileLocks.workspaceId, workspaceSpellings(workspaceId)),
           eq(fileLocks.branch, branch),
           eq(fileLocks.path, targetPath),
         ),
-      )
-      .limit(1);
-    if (rows.length === 0) return null;
-    const row = rows[0];
-    if (row.expiresAt.getTime() <= Date.now()) {
+      );
+    // At most one row per spelling; the canonical one first.
+    rows.sort((x, y) => Number(x.workspaceId !== workspaceId) - Number(y.workspaceId !== workspaceId));
+    let live: (typeof rows)[number] | null = null;
+    for (const row of rows) {
+      if (row.expiresAt.getTime() > Date.now()) {
+        live ??= row;
+        continue;
+      }
       // Lazy GC — drop the stale row so the next `acquire` doesn't have
       // to bypass it. Bind the delete to this exact row's `expiresAt` so
       // a concurrent acquire that wrote a fresh row in the gap between
@@ -356,15 +417,14 @@ export class FileLockService {
         .delete(fileLocks)
         .where(
           and(
-            eq(fileLocks.workspaceId, workspaceId),
+            eq(fileLocks.workspaceId, row.workspaceId),
             eq(fileLocks.branch, branch),
             eq(fileLocks.path, targetPath),
             eq(fileLocks.expiresAt, row.expiresAt),
           ),
         );
-      return null;
     }
-    return rowToFileLock(row);
+    return live ? rowToFileLock(live) : null;
   }
 
   /**
@@ -406,11 +466,12 @@ export class FileLockService {
    * the "missed lock-release commit" the loud warning is for. Expired rows
    * don't count (their holder is gone; they explain nothing).
    */
-  async hasAnyActive(workspaceId: string): Promise<boolean> {
+  async hasAnyActive(rawWorkspaceId: string): Promise<boolean> {
+    const workspaceId = canonicalWorkspaceId(rawWorkspaceId);
     const rows = await this.db
       .select({ path: fileLocks.path })
       .from(fileLocks)
-      .where(and(eq(fileLocks.workspaceId, workspaceId), gt(fileLocks.expiresAt, new Date())))
+      .where(and(inArray(fileLocks.workspaceId, workspaceSpellings(workspaceId)), gt(fileLocks.expiresAt, new Date())))
       .limit(1);
     return rows.length > 0;
   }

package/src/modules/workflow/git/__tests__/git.service.changedPathsMemo.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { testKbContext } from '../../../../__tests__/kb-context.js';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import { WorkflowHooks } from '../../workflow-hooks.js';
+import { GitService } from '../git.service.js';
+import { WorkspaceMutex } from '../../../kb-fs/mutex.js';
+
+/**
+ * Every git process the service starts, by argv, so a test can say what a
+ * change-request read is allowed to cost. The fixture's own git runs through
+ * `execFile` and is not logged.
+ */
+const { spawnLog } = vi.hoisted(() => ({ spawnLog: [] as string[][] }));
+
+vi.mock('node:child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:child_process')>();
+  const spawn = ((file: string, args: string[], options: unknown) => {
+    if (file === 'git') spawnLog.push(args ?? []);
+    return (actual.spawn as unknown as (...a: unknown[]) => unknown)(file, args, options);
+  }) as unknown as typeof actual.spawn;
+  return { ...actual, spawn };
+});
+
+const execFileAsync = promisify(execFile);
+
+async function runGit(cwd: string, args: string[]): Promise<void> {
+  await execFileAsync('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'Test',
+      GIT_AUTHOR_EMAIL: 't@x.com',
+      GIT_COMMITTER_NAME: 'Test',
+      GIT_COMMITTER_EMAIL: 't@x.com',
+    },
+  });
+}
+
+const spawnsOf = (subcommand: string) => spawnLog.filter((argv) => argv.includes(subcommand)).length;
+
+/**
+ * What a change request's changed paths cost: the tips come from the ref
+ * files and the diff is read from git ONCE per pair of commits. A listing
+ * that nothing has moved under asks git for nothing; a push moves a tip,
+ * and that request alone is diffed again.
+ */
+describe('a change request is diffed once per pair of commits', () => {
+  let root: string;
+  let upstream: string;
+  let repo: string;
+  let other: string;
+  let svc: GitService;
+  const workspaceId = 'ws-main';
+  const secondWorkspaceId = 'ws-two';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-changed-memo-'));
+    upstream = path.join(root, 'upstream.git');
+    await runGit(root, ['init', '--bare', '-b', 'main', upstream]);
+    const seed = path.join(root, '.seed');
+    await fs.mkdir(seed);
+    await runGit(seed, ['init', '-b', 'main']);
+    await runGit(seed, ['remote', 'add', 'origin', upstream]);
+    await fs.writeFile(path.join(seed, 'base.md'), 'base\n');
+    await runGit(seed, ['add', '-A']);
+    await runGit(seed, ['commit', '-m', 'init']);
+    await runGit(seed, ['checkout', '-b', 'feature']);
+    await fs.writeFile(path.join(seed, 'one.md'), 'one\n');
+    await runGit(seed, ['add', '-A']);
+    await runGit(seed, ['commit', '-m', 'one']);
+    await runGit(seed, ['push', 'origin', 'main', 'feature']);
+    const workspaceDir = path.join(root, workspaceId);
+    repo = path.join(workspaceDir, 'knowledge-base');
+    await fs.mkdir(workspaceDir, { recursive: true });
+    await runGit(root, ['clone', upstream, repo]);
+    other = path.join(root, 'other');
+    await runGit(root, ['clone', upstream, other]);
+    // A second workspace of the same knowledge base, with its own reservation.
+    const secondDir = path.join(root, secondWorkspaceId);
+    await fs.mkdir(secondDir, { recursive: true });
+    await runGit(root, ['clone', upstream, path.join(secondDir, 'knowledge-base')]);
+    const workspace = {
+      getWorkspacePath: async (id: string) => {
+        if (id === workspaceId) return workspaceDir;
+        if (id === secondWorkspaceId) return secondDir;
+        throw new Error(`unexpected workspace ${id}`);
+      },
+    } as unknown as WorkspaceService;
+    svc = new GitService(
+      workspace,
+      new WorkflowHooks(),
+      testKbContext({ branchModel: { defaultBranch: 'main', protectedBranches: ['main'] } }),
+      new WorkspaceMutex(),
+    );
+    spawnLog.length = 0;
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('reads the tips from the ref files, diffs once, and asks git nothing the second time', async () => {
+    const first = await svc.changedPathsAndPairsForPr(workspaceId, 'main', 'feature', { fetch: false });
+    expect(first.paths).toEqual(['one.md']);
+    expect(first.pairs).toEqual([{ path: 'one.md' }]);
+    expect(spawnsOf('diff')).toBe(1);
+    expect(spawnsOf('rev-parse')).toBe(0);
+
+    spawnLog.length = 0;
+    const second = await svc.changedPathsAndPairsForPr(workspaceId, 'main', 'feature', { fetch: false });
+    expect(second).toEqual(first);
+    expect(spawnLog).toEqual([]);
+
+    // The access-check flavour reads the same pair: the memo answers it too.
+    spawnLog.length = 0;
+    expect(await svc.changedPathsForPr(workspaceId, 'main', 'feature', { fetch: false, forAccessCheck: true })).toEqual(['one.md']);
+    expect(spawnLog).toEqual([]);
+  });
+
+  it('diffs again, once, when a push moves a tip', async () => {
+    await svc.changedPathsAndPairsForPr(workspaceId, 'main', 'feature', { fetch: false });
+    // Someone else pushes to feature; the workspace fetches as a listing's
+    // whole-clone refresh does, which rewrites the ref file.
+    await runGit(other, ['checkout', 'feature']);
+    await fs.writeFile(path.join(other, 'two.md'), 'two\n');
+    await runGit(other, ['add', '-A']);
+    await runGit(other, ['commit', '-m', 'two']);
+    await runGit(other, ['push', 'origin', 'feature']);
+    await runGit(repo, ['fetch', 'origin']);
+
+    spawnLog.length = 0;
+    const after = await svc.changedPathsAndPairsForPr(workspaceId, 'main', 'feature', { fetch: false });
+    expect(after.paths.sort()).toEqual(['one.md', 'two.md']);
+    expect(spawnsOf('diff')).toBe(1);
+    expect(spawnsOf('rev-parse')).toBe(0);
+
+    spawnLog.length = 0;
+    expect(await svc.changedPathsAndPairsForPr(workspaceId, 'main', 'feature', { fetch: false })).toEqual(after);
+    expect(spawnLog).toEqual([]);
+  });
+
+  it('shares one diff between concurrent reads of a pair nobody has seen, even from two workspaces', async () => {
+    // Two workspaces take two reservations, so nothing serialises the two
+    // reads but the in-flight diff itself: both answer, one `diff` runs.
+    const [a, b] = await Promise.all([
+      svc.changedPathsAndPairsForPr(workspaceId, 'main', 'feature', { fetch: false }),
+      svc.changedPathsAndPairsForPr(secondWorkspaceId, 'main', 'feature', { fetch: false }),
+    ]);
+    expect(a).toEqual(b);
+    expect(a.paths).toEqual(['one.md']);
+    expect(spawnsOf('diff')).toBe(1);
+  });
+
+  it('still asks git about a branch the ref files do not hold, and answers as before', async () => {
+    // A branch this clone has never fetched: the files say missing for both
+    // of its names, which is rev-parse's answer too — and `fetch: false`
+    // then turns into the per-request fetch the caller was promised.
+    await runGit(other, ['checkout', '-b', 'later']);
+    await fs.writeFile(path.join(other, 'three.md'), 'three\n');
+    await runGit(other, ['add', '-A']);
+    await runGit(other, ['commit', '-m', 'three']);
+    await runGit(other, ['push', 'origin', 'later']);
+
+    spawnLog.length = 0;
+    const got = await svc.changedPathsAndPairsForPr(workspaceId, 'main', 'later', { fetch: false });
+    expect(got.paths).toEqual(['three.md']);
+    expect(spawnsOf('fetch')).toBe(1);
+    expect(spawnsOf('diff')).toBe(1);
+  });
+});

package/src/modules/workflow/git/__tests__/git.service.readFileAtRef.test.ts

@@ -100,3 +100,45 @@ describe('GitService.readFileAtRef', () => {
     ).rejects.toThrow();
   });
 });
+
+describe('GitService.commitAtRef', () => {
+  let root: string;
+  const workspaceId = 'ws-commit-at-ref-1';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-commit-at-ref-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  function makeSvc(workspaceDir: string) {
+    return new GitService(
+      stubWorkspaceService(workspaceId, workspaceDir),
+      new WorkflowHooks(),
+      testKbContext({ kbDirName: PROCESS_MAP_DIR }),
+    );
+  }
+
+  it('answers the commit a ref names, and null for a ref that names none', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const svc = makeSvc(workspaceDir);
+    // Unborn HEAD: a repository with no commit yet names none.
+    expect(await svc.commitAtRef(workspaceId, 'HEAD')).toBeNull();
+    await fs.writeFile(path.join(repo, 'roles.yaml'), 'roles: {}\n');
+    await runGit(repo, ['add', 'roles.yaml']);
+    await runGit(repo, ['commit', '-m', 'add roles']);
+    const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repo });
+    expect(await svc.commitAtRef(workspaceId, 'HEAD')).toBe(stdout.trim());
+    expect(await svc.commitAtRef(workspaceId, 'origin/does-not-exist')).toBeNull();
+  });
+
+  it('THROWS on a failure that is not "names no commit", such as no repository there', async () => {
+    // The workspace folder exists; the clone inside it does not. Git fails
+    // with "not a git repository", which must not read as an empty one.
+    const workspaceDir = path.join(root, workspaceId);
+    await fs.mkdir(path.join(workspaceDir, PROCESS_MAP_DIR), { recursive: true });
+    const svc = makeSvc(workspaceDir);
+    await expect(svc.commitAtRef(workspaceId, 'HEAD')).rejects.toThrow();
+  });
+});