@shipfox/annotations 2.0.0

package/drizzle/0000_initial.sql

@@ -0,0 +1,32 @@
+CREATE TYPE "public"."annotations_style" AS ENUM('default', 'info', 'success', 'warning', 'error');--> statement-breakpoint
+CREATE TABLE "annotations_annotations" (
+	"id" uuid PRIMARY KEY DEFAULT uuidv7() NOT NULL,
+	"workspace_id" uuid NOT NULL,
+	"project_id" uuid NOT NULL,
+	"workflow_run_id" uuid NOT NULL,
+	"workflow_run_attempt" integer NOT NULL,
+	"workflow_run_attempt_id" uuid NOT NULL,
+	"job_id" uuid NOT NULL,
+	"job_execution_id" uuid NOT NULL,
+	"origin_step_id" uuid NOT NULL,
+	"origin_step_attempt" integer NOT NULL,
+	"context" text NOT NULL,
+	"style" "annotations_style" DEFAULT 'default' NOT NULL,
+	"body" text NOT NULL,
+	"body_bytes" integer NOT NULL,
+	"sequence" integer NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "annotations_workflow_run_attempt_positive_ck" CHECK ("annotations_annotations"."workflow_run_attempt" > 0),
+	CONSTRAINT "annotations_origin_step_attempt_positive_ck" CHECK ("annotations_annotations"."origin_step_attempt" > 0),
+	CONSTRAINT "annotations_body_bytes_matches_body_ck" CHECK ("annotations_annotations"."body_bytes" = octet_length("annotations_annotations"."body")),
+	CONSTRAINT "annotations_sequence_positive_ck" CHECK ("annotations_annotations"."sequence" > 0),
+	CONSTRAINT "annotations_context_not_empty_ck" CHECK (length("annotations_annotations"."context") > 0),
+	CONSTRAINT "annotations_context_trimmed_ck" CHECK ("annotations_annotations"."context" = btrim("annotations_annotations"."context", concat(chr(9), chr(10), chr(11), chr(12), chr(13), chr(32), chr(160), chr(5760), chr(8192), chr(8193), chr(8194), chr(8195), chr(8196), chr(8197), chr(8198), chr(8199), chr(8200), chr(8201), chr(8202), chr(8232), chr(8233), chr(8239), chr(8287), chr(12288), chr(65279)))),
+	CONSTRAINT "annotations_context_max_length_ck" CHECK (length("annotations_annotations"."context") <= 255)
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "annotations_job_execution_context_unique" ON "annotations_annotations" USING btree ("job_execution_id","context");--> statement-breakpoint
+CREATE INDEX "annotations_workflow_run_attempt_idx" ON "annotations_annotations" USING btree ("workflow_run_id","workflow_run_attempt");--> statement-breakpoint
+CREATE INDEX "annotations_workflow_run_attempt_id_idx" ON "annotations_annotations" USING btree ("workflow_run_attempt_id");--> statement-breakpoint
+CREATE INDEX "annotations_job_execution_id_idx" ON "annotations_annotations" USING btree ("job_execution_id");

package/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,247 @@
+{
+  "id": "b920fb4a-f313-42df-88bf-a2f929f35884",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.annotations_annotations": {
+      "name": "annotations_annotations",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "uuidv7()"
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "workflow_run_id": {
+          "name": "workflow_run_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "workflow_run_attempt": {
+          "name": "workflow_run_attempt",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "workflow_run_attempt_id": {
+          "name": "workflow_run_attempt_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "job_id": {
+          "name": "job_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "job_execution_id": {
+          "name": "job_execution_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "origin_step_id": {
+          "name": "origin_step_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "origin_step_attempt": {
+          "name": "origin_step_attempt",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "context": {
+          "name": "context",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "style": {
+          "name": "style",
+          "type": "annotations_style",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'default'"
+        },
+        "body": {
+          "name": "body",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "body_bytes": {
+          "name": "body_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sequence": {
+          "name": "sequence",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotations_job_execution_context_unique": {
+          "name": "annotations_job_execution_context_unique",
+          "columns": [
+            {
+              "expression": "job_execution_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "context",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotations_workflow_run_attempt_idx": {
+          "name": "annotations_workflow_run_attempt_idx",
+          "columns": [
+            {
+              "expression": "workflow_run_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "workflow_run_attempt",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotations_workflow_run_attempt_id_idx": {
+          "name": "annotations_workflow_run_attempt_id_idx",
+          "columns": [
+            {
+              "expression": "workflow_run_attempt_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotations_job_execution_id_idx": {
+          "name": "annotations_job_execution_id_idx",
+          "columns": [
+            {
+              "expression": "job_execution_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotations_workflow_run_attempt_positive_ck": {
+          "name": "annotations_workflow_run_attempt_positive_ck",
+          "value": "\"annotations_annotations\".\"workflow_run_attempt\" > 0"
+        },
+        "annotations_origin_step_attempt_positive_ck": {
+          "name": "annotations_origin_step_attempt_positive_ck",
+          "value": "\"annotations_annotations\".\"origin_step_attempt\" > 0"
+        },
+        "annotations_body_bytes_matches_body_ck": {
+          "name": "annotations_body_bytes_matches_body_ck",
+          "value": "\"annotations_annotations\".\"body_bytes\" = octet_length(\"annotations_annotations\".\"body\")"
+        },
+        "annotations_sequence_positive_ck": {
+          "name": "annotations_sequence_positive_ck",
+          "value": "\"annotations_annotations\".\"sequence\" > 0"
+        },
+        "annotations_context_not_empty_ck": {
+          "name": "annotations_context_not_empty_ck",
+          "value": "length(\"annotations_annotations\".\"context\") > 0"
+        },
+        "annotations_context_trimmed_ck": {
+          "name": "annotations_context_trimmed_ck",
+          "value": "\"annotations_annotations\".\"context\" = btrim(\"annotations_annotations\".\"context\", concat(chr(9), chr(10), chr(11), chr(12), chr(13), chr(32), chr(160), chr(5760), chr(8192), chr(8193), chr(8194), chr(8195), chr(8196), chr(8197), chr(8198), chr(8199), chr(8200), chr(8201), chr(8202), chr(8232), chr(8233), chr(8239), chr(8287), chr(12288), chr(65279)))"
+        },
+        "annotations_context_max_length_ck": {
+          "name": "annotations_context_max_length_ck",
+          "value": "length(\"annotations_annotations\".\"context\") <= 255"
+        }
+      },
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {
+    "public.annotations_style": {
+      "name": "annotations_style",
+      "schema": "public",
+      "values": ["default", "info", "success", "warning", "error"]
+    }
+  },
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1782017246000,
+      "tag": "0000_initial",
+      "breakpoints": true
+    }
+  ]
+}

package/drizzle.config.ts

@@ -0,0 +1,7 @@
+import {defineConfig} from 'drizzle-kit';
+
+export default defineConfig({
+  schema: './src/db/schema/*.ts',
+  out: './drizzle',
+  dialect: 'postgresql',
+});

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@shipfox/annotations",
+  "license": "MIT",
+  "version": "2.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/api/annotations"
+  },
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#test/*": "./test/*",
+    "#*": {
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    }
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "zod": "^4.4.3",
+    "@shipfox/annotations-dto": "2.0.0",
+    "@shipfox/api-auth-context": "2.0.0",
+    "@shipfox/node-drizzle": "0.2.1",
+    "@shipfox/node-fastify": "0.2.1",
+    "@shipfox/config": "1.2.1",
+    "@shipfox/node-module": "0.2.0",
+    "@shipfox/node-postgres": "0.4.1"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.15.5",
+    "drizzle-kit": "^0.31.10",
+    "fastify": "^5.3.3",
+    "fastify-type-provider-zod": "^6.0.0",
+    "fishery": "^2.2.2",
+    "@shipfox/api-auth-dto": "2.0.0",
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/node-jwt": "0.2.0",
+    "@shipfox/ts-config": "1.3.8",
+    "@shipfox/swc": "1.2.5",
+    "@shipfox/typescript": "1.1.6",
+    "@shipfox/vitest": "1.2.2",
+    "@shipfox/api-auth": "2.0.0"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/config.test.ts

@@ -0,0 +1,45 @@
+import {vi} from '@shipfox/vitest/vi';
+
+describe.each([
+  'ANNOTATIONS_MAX_BODY_BYTES',
+  'ANNOTATIONS_MAX_PER_EXECUTION',
+  'ANNOTATIONS_MAX_TOTAL_BYTES',
+] as const)('%s validation', (name) => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it.each(['0', '-5', '1.5'])('fails startup when the value is %s', async (value) => {
+    vi.stubEnv(name, value);
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow(name);
+  });
+
+  it('accepts a whole number greater than 0', async () => {
+    vi.stubEnv(name, '1');
+    vi.resetModules();
+
+    const {config} = await import('#config.js');
+
+    expect(config[name]).toBe(1);
+  });
+});
+
+describe('annotation config defaults', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it('uses the documented annotation budget defaults', async () => {
+    vi.resetModules();
+
+    const {config} = await import('#config.js');
+
+    expect(config.ANNOTATIONS_MAX_BODY_BYTES).toBe(1048576);
+    expect(config.ANNOTATIONS_MAX_PER_EXECUTION).toBe(50);
+    expect(config.ANNOTATIONS_MAX_TOTAL_BYTES).toBe(4194304);
+  });
+});

package/src/config.ts

@@ -0,0 +1,26 @@
+import {createConfig, num} from '@shipfox/config';
+
+export const config = createConfig({
+  ANNOTATIONS_MAX_BODY_BYTES: num({
+    desc: 'Maximum UTF-8 byte size of one annotation body. Writes that would make an annotation body larger than this are rejected.',
+    default: 1048576,
+  }),
+  ANNOTATIONS_MAX_PER_EXECUTION: num({
+    desc: 'Maximum number of distinct annotation contexts one job execution may store.',
+    default: 50,
+  }),
+  ANNOTATIONS_MAX_TOTAL_BYTES: num({
+    desc: 'Maximum total UTF-8 bytes of annotation bodies one job execution may store.',
+    default: 4194304,
+  }),
+});
+
+for (const name of [
+  'ANNOTATIONS_MAX_BODY_BYTES',
+  'ANNOTATIONS_MAX_PER_EXECUTION',
+  'ANNOTATIONS_MAX_TOTAL_BYTES',
+] as const) {
+  if (!Number.isInteger(config[name]) || config[name] < 1) {
+    throw new Error(`${name} (${config[name]}) must be a whole number greater than 0.`);
+  }
+}

package/src/core/entities/annotation.ts

@@ -0,0 +1,21 @@
+import type {AnnotationStyleDto} from '@shipfox/annotations-dto';
+
+export interface Annotation {
+  id: string;
+  workspaceId: string;
+  projectId: string;
+  workflowRunId: string;
+  workflowRunAttempt: number;
+  workflowRunAttemptId: string;
+  jobId: string;
+  jobExecutionId: string;
+  originStepId: string;
+  originStepAttempt: number;
+  context: string;
+  style: AnnotationStyleDto;
+  body: string;
+  bodyBytes: number;
+  sequence: number;
+  createdAt: Date;
+  updatedAt: Date;
+}

package/src/core/entities/index.ts

@@ -0,0 +1 @@
+export type {Annotation} from './annotation.js';

package/src/core/errors.ts

@@ -0,0 +1,20 @@
+export class AnnotationBodyTooLargeError extends Error {
+  constructor(public readonly maxBytes: number) {
+    super(`Annotation body exceeds ${maxBytes} bytes`);
+    this.name = 'AnnotationBodyTooLargeError';
+  }
+}
+
+export class AnnotationCountLimitExceededError extends Error {
+  constructor(public readonly maxAnnotations: number) {
+    super(`Annotation count exceeds ${maxAnnotations}`);
+    this.name = 'AnnotationCountLimitExceededError';
+  }
+}
+
+export class AnnotationTotalBytesLimitExceededError extends Error {
+  constructor(public readonly maxBytes: number) {
+    super(`Annotation total body bytes exceed ${maxBytes}`);
+    this.name = 'AnnotationTotalBytesLimitExceededError';
+  }
+}