feat(write-locks): record/consume/cleanup helpers

Author: Ripwords

apps/dashboard/server/lib/github-write-locks.test.ts

@@ -0,0 +1,183 @@
+// apps/dashboard/server/lib/github-write-locks.test.ts
+// Integration tests — these hit the real Postgres instance.
+// Run with: bun test apps/dashboard/server/lib/github-write-locks.test.ts
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { sql } from "drizzle-orm"
+import { db } from "../db"
+import { githubWriteLocks, projects, reports } from "../db/schema"
+import {
+  cleanupExpiredLocks,
+  consumeWriteLock,
+  recordWriteLock,
+  WRITE_LOCK_TTL_MS,
+} from "./github-write-locks"
+
+// We need a real report row to satisfy the FK
+let testProjectId: string
+let testReportId: string
+
+async function truncate() {
+  await db.execute(sql`TRUNCATE github_write_locks RESTART IDENTITY CASCADE`)
+}
+
+beforeEach(async () => {
+  await db.execute(
+    sql`TRUNCATE project_invitations, project_members, projects, "account", "session", "verification", "user" RESTART IDENTITY CASCADE`,
+  )
+  await db.execute(sql`TRUNCATE report_attachments, reports RESTART IDENTITY CASCADE`)
+  await truncate()
+
+  const [p] = await db
+    .insert(projects)
+    .values({
+      name: "test",
+      createdBy: "user-test",
+      publicKey: "rp_pk_writelocktest",
+      allowedOrigins: [],
+    })
+    .returning()
+  testProjectId = p.id
+
+  const [r] = await db
+    .insert(reports)
+    .values({
+      projectId: testProjectId,
+      title: "test report",
+      description: "test",
+      context: {
+        pageUrl: "http://example.com",
+        userAgent: "UA",
+        viewport: { w: 1, h: 1 },
+        timestamp: new Date().toISOString(),
+      },
+    })
+    .returning()
+  testReportId = r.id
+})
+
+afterEach(async () => {
+  await truncate()
+  await db.execute(sql`TRUNCATE report_attachments, reports RESTART IDENTITY CASCADE`)
+  await db.execute(
+    sql`TRUNCATE project_invitations, project_members, projects, "account", "session", "verification", "user" RESTART IDENTITY CASCADE`,
+  )
+})
+
+describe("recordWriteLock", () => {
+  test("inserts a row with correct fields", async () => {
+    await recordWriteLock(db, {
+      reportId: testReportId,
+      kind: "title",
+      signature: "abc123",
+    })
+
+    const rows = await db.select().from(githubWriteLocks)
+    expect(rows.length).toBe(1)
+    expect(rows[0]?.reportId).toBe(testReportId)
+    expect(rows[0]?.kind).toBe("title")
+    expect(rows[0]?.signature).toBe("abc123")
+    expect(rows[0]?.expiresAt.getTime()).toBeGreaterThan(Date.now())
+    expect(rows[0]?.expiresAt.getTime()).toBeLessThanOrEqual(Date.now() + WRITE_LOCK_TTL_MS + 1000)
+  })
+})
+
+describe("consumeWriteLock", () => {
+  test("returns true and deletes when matching live row exists", async () => {
+    await recordWriteLock(db, {
+      reportId: testReportId,
+      kind: "state",
+      signature: "sig-xyz",
+    })
+
+    const result = await consumeWriteLock(db, {
+      reportId: testReportId,
+      kind: "state",
+      signature: "sig-xyz",
+    })
+
+    expect(result).toBe(true)
+    const rows = await db.select().from(githubWriteLocks)
+    expect(rows.length).toBe(0)
+  })
+
+  test("returns false when no matching row", async () => {
+    const result = await consumeWriteLock(db, {
+      reportId: testReportId,
+      kind: "labels",
+      signature: "nonexistent",
+    })
+    expect(result).toBe(false)
+  })
+
+  test("returns false when signature differs", async () => {
+    await recordWriteLock(db, {
+      reportId: testReportId,
+      kind: "labels",
+      signature: "correct-sig",
+    })
+
+    const result = await consumeWriteLock(db, {
+      reportId: testReportId,
+      kind: "labels",
+      signature: "wrong-sig",
+    })
+    expect(result).toBe(false)
+  })
+
+  test("returns false for expired rows", async () => {
+    // Insert an already-expired lock directly
+    const expiresAt = new Date(Date.now() - 1000)
+    await db.insert(githubWriteLocks).values({
+      reportId: testReportId,
+      kind: "title",
+      signature: "expired-sig",
+      expiresAt,
+    })
+
+    const result = await consumeWriteLock(db, {
+      reportId: testReportId,
+      kind: "title",
+      signature: "expired-sig",
+    })
+    expect(result).toBe(false)
+  })
+})
+
+describe("cleanupExpiredLocks", () => {
+  test("removes only expired rows, leaves live rows", async () => {
+    // Insert one live and one expired lock
+    const expired = new Date(Date.now() - 1000)
+    await db.insert(githubWriteLocks).values([
+      {
+        reportId: testReportId,
+        kind: "labels",
+        signature: "live-sig",
+        expiresAt: new Date(Date.now() + WRITE_LOCK_TTL_MS),
+      },
+      {
+        reportId: testReportId,
+        kind: "state",
+        signature: "expired-sig",
+        expiresAt: expired,
+      },
+    ])
+
+    const count = await cleanupExpiredLocks(db)
+    expect(count).toBe(1)
+
+    const remaining = await db.select().from(githubWriteLocks)
+    expect(remaining.length).toBe(1)
+    expect(remaining[0]?.signature).toBe("live-sig")
+  })
+
+  test("returns 0 when no expired rows", async () => {
+    await recordWriteLock(db, {
+      reportId: testReportId,
+      kind: "title",
+      signature: "live",
+    })
+
+    const count = await cleanupExpiredLocks(db)
+    expect(count).toBe(0)
+  })
+})

apps/dashboard/server/lib/github-write-locks.ts

@@ -0,0 +1,67 @@
+// apps/dashboard/server/lib/github-write-locks.ts
+// Helpers for recording and consuming write-locks. Write-locks prevent echo
+// loops: before we push an outbound change to GitHub we record a short-lived
+// lock; when the matching webhook arrives back we consume it and skip the
+// inbound application (it's our own echo).
+import { and, eq, gt, lt } from "drizzle-orm"
+import type { NodePgDatabase } from "drizzle-orm/node-postgres"
+import type * as schema from "../db/schema"
+import { githubWriteLocks } from "../db/schema"
+import type { githubWriteLockKinds } from "../db/schema"
+
+export const WRITE_LOCK_TTL_MS = 30_000 // 30 seconds
+
+type DB = NodePgDatabase<typeof schema>
+type LockKind = (typeof githubWriteLockKinds.enumValues)[number]
+
+export interface WriteLockInput {
+  reportId: string
+  kind: LockKind
+  signature: string
+}
+
+/** Record a write-lock row with a TTL of WRITE_LOCK_TTL_MS. */
+export async function recordWriteLock(db: DB, input: WriteLockInput): Promise<void> {
+  const expiresAt = new Date(Date.now() + WRITE_LOCK_TTL_MS)
+  await db.insert(githubWriteLocks).values({
+    reportId: input.reportId,
+    kind: input.kind,
+    signature: input.signature,
+    expiresAt,
+  })
+}
+
+/**
+ * Consume a write-lock. Returns true if a matching live row was deleted,
+ * false otherwise (no lock found, wrong signature, or already expired).
+ */
+export async function consumeWriteLock(db: DB, input: WriteLockInput): Promise<boolean> {
+  const now = new Date()
+  const deleted = await db
+    .delete(githubWriteLocks)
+    .where(
+      and(
+        eq(githubWriteLocks.reportId, input.reportId),
+        eq(githubWriteLocks.kind, input.kind),
+        eq(githubWriteLocks.signature, input.signature),
+        gt(githubWriteLocks.expiresAt, now),
+      ),
+    )
+    .returning({ id: githubWriteLocks.id })
+
+  return deleted.length > 0
+}
+
+/**
+ * Delete all expired write-lock rows. Returns the number of rows deleted.
+ * Suitable for a scheduled cleanup task.
+ */
+export async function cleanupExpiredLocks(db: DB): Promise<number> {
+  const now = new Date()
+  const deleted = await db
+    .delete(githubWriteLocks)
+    .where(lt(githubWriteLocks.expiresAt, now))
+    .returning({ id: githubWriteLocks.id })
+
+  return deleted.length
+}