@shipfox/annotations 2.0.0

package/src/core/write-annotations.test.ts

@@ -0,0 +1,261 @@
+import {eq} from 'drizzle-orm';
+import {withAnnotationLock} from '#db/annotations.js';
+import {db} from '#db/db.js';
+import {annotations} from '#db/schema/annotations.js';
+import {annotationFactory} from '#test/index.js';
+import {
+  AnnotationBodyTooLargeError,
+  AnnotationCountLimitExceededError,
+  AnnotationTotalBytesLimitExceededError,
+} from './errors.js';
+import {type WriteAnnotationsParams, writeAnnotations} from './write-annotations.js';
+
+describe('writeAnnotations', () => {
+  let params: WriteAnnotationsParams;
+
+  beforeEach(() => {
+    params = {
+      workspaceId: crypto.randomUUID(),
+      projectId: crypto.randomUUID(),
+      workflowRunId: crypto.randomUUID(),
+      workflowRunAttempt: 1,
+      workflowRunAttemptId: crypto.randomUUID(),
+      jobId: crypto.randomUUID(),
+      jobExecutionId: crypto.randomUUID(),
+      originStepId: crypto.randomUUID(),
+      originStepAttempt: 1,
+      operations: [],
+    };
+  });
+
+  it('replaces by context and preserves sequence across updates', async () => {
+    const created = await writeAnnotations({
+      ...params,
+      operations: [{context: 'deploy', style: 'success', op: 'replace', body: 'first'}],
+    });
+
+    const updated = await writeAnnotations({
+      ...params,
+      originStepId: crypto.randomUUID(),
+      originStepAttempt: 2,
+      operations: [{context: 'deploy', style: 'warning', op: 'replace', body: 'second'}],
+    });
+
+    const rows = await db()
+      .select()
+      .from(annotations)
+      .where(eq(annotations.jobExecutionId, params.jobExecutionId));
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      id: created.annotations[0]?.id,
+      context: 'deploy',
+      style: 'warning',
+      body: 'second',
+      sequence: 1,
+      originStepAttempt: 2,
+    });
+    expect(updated.annotations[0]?.id).toBe(created.annotations[0]?.id);
+    expect(updated.accounting).toEqual({annotationCount: 1, totalBodyBytes: 6});
+  });
+
+  it('skips unchanged replace writes and preserves original attribution', async () => {
+    const created = await writeAnnotations({
+      ...params,
+      operations: [{context: 'deploy', style: 'warning', op: 'replace', body: 'same'}],
+    });
+    const originalOriginStepId = params.originStepId;
+
+    const unchanged = await writeAnnotations({
+      ...params,
+      originStepId: crypto.randomUUID(),
+      originStepAttempt: 2,
+      operations: [{context: 'deploy', style: 'warning', op: 'replace', body: 'same'}],
+    });
+
+    const rows = await db()
+      .select()
+      .from(annotations)
+      .where(eq(annotations.jobExecutionId, params.jobExecutionId));
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      id: created.annotations[0]?.id,
+      context: 'deploy',
+      style: 'warning',
+      body: 'same',
+      sequence: 1,
+      originStepId: originalOriginStepId,
+      originStepAttempt: 1,
+    });
+    expect(unchanged.annotations[0]?.id).toBe(created.annotations[0]?.id);
+    expect(unchanged.accounting).toEqual({annotationCount: 1, totalBodyBytes: 4});
+  });
+
+  it('appends to an existing context', async () => {
+    await annotationFactory.create({
+      ...params,
+      id: crypto.randomUUID(),
+      context: 'summary',
+      style: 'info',
+      body: 'hello',
+      bodyBytes: Buffer.byteLength('hello'),
+      sequence: 1,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const result = await writeAnnotations({
+      ...params,
+      operations: [{context: 'summary', style: 'info', op: 'append', body: ' world'}],
+    });
+
+    const rows = await db()
+      .select()
+      .from(annotations)
+      .where(eq(annotations.jobExecutionId, params.jobExecutionId));
+    expect(rows[0]).toMatchObject({context: 'summary', body: 'hello world', sequence: 1});
+    expect(result.accounting).toEqual({annotationCount: 1, totalBodyBytes: 11});
+  });
+
+  it('removes a context and returns null for the removed annotation id', async () => {
+    await annotationFactory.create({
+      ...params,
+      id: crypto.randomUUID(),
+      context: 'summary',
+      body: 'remove me',
+      bodyBytes: Buffer.byteLength('remove me'),
+      sequence: 1,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const result = await writeAnnotations({
+      ...params,
+      operations: [{context: 'summary', style: 'default', op: 'remove'}],
+    });
+
+    const rows = await db()
+      .select()
+      .from(annotations)
+      .where(eq(annotations.jobExecutionId, params.jobExecutionId));
+    expect(rows).toHaveLength(0);
+    expect(result).toEqual({
+      annotations: [{context: 'summary', id: null}],
+      accounting: {annotationCount: 0, totalBodyBytes: 0},
+    });
+  });
+
+  it('assigns sequence only on first create of a context', async () => {
+    const result = await writeAnnotations({
+      ...params,
+      operations: [
+        {context: 'first', style: 'default', op: 'replace', body: 'one'},
+        {context: 'second', style: 'default', op: 'replace', body: 'two'},
+        {context: 'first', style: 'default', op: 'append', body: ' more'},
+      ],
+    });
+
+    const rows = await db()
+      .select()
+      .from(annotations)
+      .where(eq(annotations.jobExecutionId, params.jobExecutionId));
+    expect(rows).toHaveLength(2);
+    expect(rows.find((row) => row.context === 'first')).toMatchObject({
+      body: 'one more',
+      sequence: 1,
+    });
+    expect(rows.find((row) => row.context === 'second')).toMatchObject({sequence: 2});
+    expect(result.accounting).toEqual({annotationCount: 2, totalBodyBytes: 11});
+  });
+
+  it('rejects an annotation body over the byte budget', async () => {
+    const body = 'x'.repeat(1048577);
+
+    const write = writeAnnotations({
+      ...params,
+      operations: [{context: 'huge', style: 'default', op: 'replace', body}],
+    });
+
+    await expect(write).rejects.toBeInstanceOf(AnnotationBodyTooLargeError);
+  });
+
+  it('rejects an execution over the annotation count budget', async () => {
+    const operations = Array.from({length: 51}, (_, index) => ({
+      context: `context-${index}`,
+      style: 'default' as const,
+      op: 'replace' as const,
+      body: 'x',
+    }));
+
+    const write = writeAnnotations({...params, operations});
+
+    await expect(write).rejects.toBeInstanceOf(AnnotationCountLimitExceededError);
+  });
+
+  it('rejects an execution over the total byte budget', async () => {
+    const operations = Array.from({length: 5}, (_, index) => ({
+      context: `context-${index}`,
+      style: 'default' as const,
+      op: 'replace' as const,
+      body: 'x'.repeat(900000),
+    }));
+
+    const write = writeAnnotations({...params, operations});
+
+    await expect(write).rejects.toBeInstanceOf(AnnotationTotalBytesLimitExceededError);
+  });
+
+  it('rolls back the whole request when one operation exceeds a budget', async () => {
+    const write = writeAnnotations({
+      ...params,
+      operations: [
+        {context: 'created-first', style: 'default', op: 'replace', body: 'ok'},
+        {
+          context: 'huge',
+          style: 'default',
+          op: 'replace',
+          body: 'x'.repeat(1048577),
+        },
+      ],
+    });
+
+    await expect(write).rejects.toBeInstanceOf(AnnotationBodyTooLargeError);
+
+    const rows = await db()
+      .select()
+      .from(annotations)
+      .where(eq(annotations.jobExecutionId, params.jobExecutionId));
+    expect(rows).toHaveLength(0);
+  });
+
+  it('waits for the per-execution advisory transaction lock before writing', async () => {
+    let releaseLock!: () => void;
+    const lockReleased = new Promise<void>((resolve) => {
+      releaseLock = resolve;
+    });
+    let lockAcquired!: () => void;
+    const lockReady = new Promise<void>((resolve) => {
+      lockAcquired = resolve;
+    });
+    const blocker = withAnnotationLock(params.jobExecutionId, async () => {
+      lockAcquired();
+      await lockReleased;
+    });
+    await lockReady;
+
+    const write = writeAnnotations({
+      ...params,
+      operations: [{context: 'blocked', style: 'default', op: 'replace', body: 'after'}],
+    });
+    const stateBeforeRelease = await Promise.race([
+      write.then(() => 'completed'),
+      new Promise<'blocked'>((resolve) => setTimeout(() => resolve('blocked'), 50)),
+    ]);
+    releaseLock();
+    await blocker;
+
+    const result = await write;
+
+    expect(stateBeforeRelease).toBe('blocked');
+    expect(result.accounting).toEqual({annotationCount: 1, totalBodyBytes: 5});
+  });
+});

package/src/core/write-annotations.ts

@@ -0,0 +1,142 @@
+import type {LeasedWriteAnnotationOperationDto} from '@shipfox/annotations-dto';
+import {config} from '#config.js';
+import {type StoredAnnotation, withAnnotationLock} from '#db/annotations.js';
+import {
+  AnnotationBodyTooLargeError,
+  AnnotationCountLimitExceededError,
+  AnnotationTotalBytesLimitExceededError,
+} from './errors.js';
+
+export interface WriteAnnotationsParams {
+  workspaceId: string;
+  projectId: string;
+  workflowRunId: string;
+  workflowRunAttempt: number;
+  workflowRunAttemptId: string;
+  jobId: string;
+  jobExecutionId: string;
+  originStepId: string;
+  originStepAttempt: number;
+  operations: readonly LeasedWriteAnnotationOperationDto[];
+}
+
+export interface WriteAnnotationsResult {
+  annotations: Array<{context: string; id: string | null}>;
+  accounting: {
+    annotationCount: number;
+    totalBodyBytes: number;
+  };
+}
+
+export function writeAnnotations(params: WriteAnnotationsParams): Promise<WriteAnnotationsResult> {
+  return withAnnotationLock(params.jobExecutionId, async (repo) => {
+    const current = await repo.loadCurrentAnnotations(params.jobExecutionId);
+    let nextSequence =
+      Math.max(0, ...Array.from(current.values()).map((annotation) => annotation.sequence)) + 1;
+    const results: WriteAnnotationsResult['annotations'] = [];
+
+    for (const operation of params.operations) {
+      if (operation.op === 'remove') {
+        await repo.removeAnnotation(params.jobExecutionId, operation.context);
+        current.delete(operation.context);
+        results.push({context: operation.context, id: null});
+        continue;
+      }
+
+      const existing = current.get(operation.context);
+      const body =
+        operation.op === 'append' ? `${existing?.body ?? ''}${operation.body}` : operation.body;
+      const bodyBytes = Buffer.byteLength(body);
+      ensureBodyBudget(bodyBytes);
+
+      const isUnchangedReplace =
+        operation.op === 'replace' &&
+        existing !== undefined &&
+        existing.body === body &&
+        existing.style === operation.style;
+      if (isUnchangedReplace) {
+        results.push({context: operation.context, id: existing.id});
+        continue;
+      }
+
+      const draft = new Map(current);
+      draft.set(operation.context, {
+        id: existing?.id ?? '',
+        context: operation.context,
+        style: operation.style,
+        body,
+        bodyBytes,
+        sequence: existing?.sequence ?? nextSequence,
+      });
+      ensureExecutionBudgets(draft);
+
+      const row = existing
+        ? await repo.updateAnnotation({
+            id: existing.id,
+            originStepId: params.originStepId,
+            originStepAttempt: params.originStepAttempt,
+            style: operation.style,
+            body,
+            bodyBytes,
+          })
+        : await repo.createAnnotation({
+            workspaceId: params.workspaceId,
+            projectId: params.projectId,
+            workflowRunId: params.workflowRunId,
+            workflowRunAttempt: params.workflowRunAttempt,
+            workflowRunAttemptId: params.workflowRunAttemptId,
+            jobId: params.jobId,
+            jobExecutionId: params.jobExecutionId,
+            originStepId: params.originStepId,
+            originStepAttempt: params.originStepAttempt,
+            context: operation.context,
+            style: operation.style,
+            body,
+            bodyBytes,
+            sequence: nextSequence,
+          });
+
+      current.set(operation.context, {
+        id: row.id,
+        context: row.context,
+        style: row.style,
+        body: row.body,
+        bodyBytes: row.bodyBytes,
+        sequence: row.sequence,
+      });
+      if (!existing) nextSequence += 1;
+      results.push({context: operation.context, id: row.id});
+    }
+
+    return {
+      annotations: results,
+      accounting: currentAccounting(current),
+    };
+  });
+}
+
+function ensureBodyBudget(bodyBytes: number): void {
+  if (bodyBytes > config.ANNOTATIONS_MAX_BODY_BYTES) {
+    throw new AnnotationBodyTooLargeError(config.ANNOTATIONS_MAX_BODY_BYTES);
+  }
+}
+
+function ensureExecutionBudgets(annotationsByContext: ReadonlyMap<string, StoredAnnotation>): void {
+  const accounting = currentAccounting(annotationsByContext);
+  if (accounting.annotationCount > config.ANNOTATIONS_MAX_PER_EXECUTION) {
+    throw new AnnotationCountLimitExceededError(config.ANNOTATIONS_MAX_PER_EXECUTION);
+  }
+  if (accounting.totalBodyBytes > config.ANNOTATIONS_MAX_TOTAL_BYTES) {
+    throw new AnnotationTotalBytesLimitExceededError(config.ANNOTATIONS_MAX_TOTAL_BYTES);
+  }
+}
+
+function currentAccounting(annotationsByContext: ReadonlyMap<string, StoredAnnotation>) {
+  return {
+    annotationCount: annotationsByContext.size,
+    totalBodyBytes: Array.from(annotationsByContext.values()).reduce(
+      (total, annotation) => total + annotation.bodyBytes,
+      0,
+    ),
+  };
+}

package/src/db/annotations.test.ts

@@ -0,0 +1,261 @@
+import {annotationFactory} from '#test/index.js';
+import {listAnnotationsForRunAttempt} from './annotations.js';
+
+describe('listAnnotationsForRunAttempt', () => {
+  it('lists annotations for the requested run attempt and workspace in sequence order', async () => {
+    const workspaceId = crypto.randomUUID();
+    const workflowRunId = crypto.randomUUID();
+    const [second, first] = await Promise.all([
+      annotationFactory.create({
+        workspaceId,
+        workflowRunId,
+        workflowRunAttempt: 2,
+        jobExecutionId: crypto.randomUUID(),
+        context: 'a-second',
+        sequence: 2,
+      }),
+      annotationFactory.create({
+        workspaceId,
+        workflowRunId,
+        workflowRunAttempt: 2,
+        jobExecutionId: crypto.randomUUID(),
+        context: 'z-first',
+        sequence: 1,
+      }),
+    ]);
+
+    const result = await listAnnotationsForRunAttempt({
+      workflowRunId,
+      workflowRunAttempt: 2,
+      workspaceIds: [workspaceId],
+    });
+
+    expect(result).toEqual({annotations: [first, second], hasMore: false, nextCursor: null});
+  });
+
+  it('excludes annotations from other run attempts, runs, and workspaces', async () => {
+    const workspaceId = crypto.randomUUID();
+    const workflowRunId = crypto.randomUUID();
+    const visible = await annotationFactory.create({
+      workspaceId,
+      workflowRunId,
+      workflowRunAttempt: 1,
+    });
+    await annotationFactory.create({
+      workspaceId,
+      workflowRunId,
+      workflowRunAttempt: 2,
+      jobExecutionId: crypto.randomUUID(),
+      context: 'other-attempt',
+    });
+    await annotationFactory.create({
+      workspaceId,
+      workflowRunId: crypto.randomUUID(),
+      jobExecutionId: crypto.randomUUID(),
+      context: 'other-run',
+    });
+    await annotationFactory.create({
+      workspaceId: crypto.randomUUID(),
+      workflowRunId,
+      jobExecutionId: crypto.randomUUID(),
+      context: 'other-workspace',
+    });
+
+    const result = await listAnnotationsForRunAttempt({
+      workflowRunId,
+      workflowRunAttempt: 1,
+      workspaceIds: [workspaceId],
+    });
+
+    expect(result).toEqual({annotations: [visible], hasMore: false, nextCursor: null});
+  });
+
+  it('filters by job execution when provided', async () => {
+    const workspaceId = crypto.randomUUID();
+    const workflowRunId = crypto.randomUUID();
+    const jobExecutionId = crypto.randomUUID();
+    const visible = await annotationFactory.create({
+      workspaceId,
+      workflowRunId,
+      jobExecutionId,
+      context: 'visible',
+    });
+    await annotationFactory.create({
+      workspaceId,
+      workflowRunId,
+      jobExecutionId: crypto.randomUUID(),
+      context: 'hidden',
+    });
+
+    const result = await listAnnotationsForRunAttempt({
+      workflowRunId,
+      workflowRunAttempt: 1,
+      workspaceIds: [workspaceId],
+      jobExecutionId,
+    });
+
+    expect(result).toEqual({annotations: [visible], hasMore: false, nextCursor: null});
+  });
+
+  it('limits returned annotations and reports more rows', async () => {
+    const workspaceId = crypto.randomUUID();
+    const workflowRunId = crypto.randomUUID();
+    const [first] = await Promise.all([
+      annotationFactory.create({
+        workspaceId,
+        workflowRunId,
+        jobExecutionId: crypto.randomUUID(),
+        context: 'first',
+        sequence: 1,
+      }),
+      annotationFactory.create({
+        workspaceId,
+        workflowRunId,
+        jobExecutionId: crypto.randomUUID(),
+        context: 'second',
+        sequence: 2,
+      }),
+    ]);
+
+    const result = await listAnnotationsForRunAttempt({
+      workflowRunId,
+      workflowRunAttempt: 1,
+      workspaceIds: [workspaceId],
+      limit: 1,
+    });
+
+    expect(result).toEqual({
+      annotations: [first],
+      hasMore: true,
+      nextCursor: {sequence: first.sequence, id: first.id},
+    });
+  });
+
+  it('continues listing after the sequence and id cursor', async () => {
+    const workspaceId = crypto.randomUUID();
+    const workflowRunId = crypto.randomUUID();
+    const [first, second, third] = await Promise.all([
+      annotationFactory.create({
+        workspaceId,
+        workflowRunId,
+        jobExecutionId: crypto.randomUUID(),
+        context: 'first',
+        sequence: 1,
+      }),
+      annotationFactory.create({
+        workspaceId,
+        workflowRunId,
+        jobExecutionId: crypto.randomUUID(),
+        context: 'second',
+        sequence: 2,
+      }),
+      annotationFactory.create({
+        workspaceId,
+        workflowRunId,
+        jobExecutionId: crypto.randomUUID(),
+        context: 'third',
+        sequence: 3,
+      }),
+    ]);
+
+    const firstPage = await listAnnotationsForRunAttempt({
+      workflowRunId,
+      workflowRunAttempt: 1,
+      workspaceIds: [workspaceId],
+      limit: 1,
+    });
+    const secondPage = await listAnnotationsForRunAttempt({
+      workflowRunId,
+      workflowRunAttempt: 1,
+      workspaceIds: [workspaceId],
+      after: firstPage.nextCursor ?? undefined,
+      limit: 1,
+    });
+    const thirdPage = await listAnnotationsForRunAttempt({
+      workflowRunId,
+      workflowRunAttempt: 1,
+      workspaceIds: [workspaceId],
+      after: secondPage.nextCursor ?? undefined,
+      limit: 1,
+    });
+
+    expect(firstPage).toEqual({
+      annotations: [first],
+      hasMore: true,
+      nextCursor: {sequence: first.sequence, id: first.id},
+    });
+    expect(secondPage).toEqual({
+      annotations: [second],
+      hasMore: true,
+      nextCursor: {sequence: second.sequence, id: second.id},
+    });
+    expect(thirdPage).toEqual({
+      annotations: [third],
+      hasMore: false,
+      nextCursor: null,
+    });
+  });
+
+  it('uses id as the cursor tie-breaker for duplicate sequences', async () => {
+    const workspaceId = crypto.randomUUID();
+    const workflowRunId = crypto.randomUUID();
+    const duplicates = await Promise.all([
+      annotationFactory.create({
+        workspaceId,
+        workflowRunId,
+        jobExecutionId: crypto.randomUUID(),
+        context: 'same-sequence-a',
+        sequence: 1,
+      }),
+      annotationFactory.create({
+        workspaceId,
+        workflowRunId,
+        jobExecutionId: crypto.randomUUID(),
+        context: 'same-sequence-b',
+        sequence: 1,
+      }),
+    ]);
+    const ordered = [...duplicates].sort((left, right) => left.id.localeCompare(right.id));
+    const first = ordered[0];
+    const second = ordered[1];
+    if (!first || !second) throw new Error('Expected duplicate annotation fixtures');
+
+    const firstPage = await listAnnotationsForRunAttempt({
+      workflowRunId,
+      workflowRunAttempt: 1,
+      workspaceIds: [workspaceId],
+      limit: 1,
+    });
+    const secondPage = await listAnnotationsForRunAttempt({
+      workflowRunId,
+      workflowRunAttempt: 1,
+      workspaceIds: [workspaceId],
+      after: firstPage.nextCursor ?? undefined,
+      limit: 1,
+    });
+
+    expect(firstPage).toEqual({
+      annotations: [first],
+      hasMore: true,
+      nextCursor: {sequence: first.sequence, id: first.id},
+    });
+    expect(secondPage).toEqual({
+      annotations: [second],
+      hasMore: false,
+      nextCursor: null,
+    });
+  });
+
+  it('returns an empty list when the user has no workspace memberships', async () => {
+    const workflowRunId = crypto.randomUUID();
+    await annotationFactory.create({workflowRunId});
+
+    const result = await listAnnotationsForRunAttempt({
+      workflowRunId,
+      workflowRunAttempt: 1,
+      workspaceIds: [],
+    });
+
+    expect(result).toEqual({annotations: [], hasMore: false, nextCursor: null});
+  });
+});