@shipfox/api-projects 2.0.0

package/src/core/projects.ts

@@ -0,0 +1,97 @@
+import type {IntegrationSourceControlService} from '@shipfox/api-integration-core';
+import {
+  PROJECT_CREATED,
+  PROJECT_SOURCE_BOUND,
+  type ProjectsEventMap,
+} from '@shipfox/api-projects-dto';
+import {writeOutboxEvent} from '@shipfox/node-outbox';
+import {and, eq} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {projectsOutbox} from '#db/schema/outbox.js';
+import {projects, toProject} from '#db/schema/projects.js';
+import {recordProjectCreated} from '#metrics/instance.js';
+import type {Project} from './entities/project.js';
+import {ProjectAlreadyExistsError} from './errors.js';
+
+export interface CreateProjectFromSourceParams {
+  actorId: string;
+  workspaceId: string;
+  name: string;
+  sourceConnectionId: string;
+  sourceExternalRepositoryId: string;
+  sourceControl: IntegrationSourceControlService;
+}
+
+export async function createProjectFromSource(
+  params: CreateProjectFromSourceParams,
+): Promise<Project> {
+  const source = await params.sourceControl.resolveRepository({
+    workspaceId: params.workspaceId,
+    connectionId: params.sourceConnectionId,
+    externalRepositoryId: params.sourceExternalRepositoryId,
+  });
+
+  const project = await db().transaction(async (tx) => {
+    const [projectRow] = await tx
+      .insert(projects)
+      .values({
+        workspaceId: params.workspaceId,
+        sourceConnectionId: source.connection.id,
+        sourceExternalRepositoryId: source.repository.externalRepositoryId,
+        name: params.name,
+      })
+      .onConflictDoNothing({
+        target: [projects.sourceConnectionId, projects.sourceExternalRepositoryId],
+      })
+      .returning();
+
+    if (!projectRow) {
+      const [existing] = await tx
+        .select()
+        .from(projects)
+        .where(
+          and(
+            eq(projects.sourceConnectionId, source.connection.id),
+            eq(projects.sourceExternalRepositoryId, source.repository.externalRepositoryId),
+          ),
+        )
+        .limit(1);
+      if (existing) {
+        throw new ProjectAlreadyExistsError(
+          existing.id,
+          source.connection.id,
+          source.repository.externalRepositoryId,
+        );
+      }
+      throw new Error('Project insert returned no rows');
+    }
+
+    const project = toProject(projectRow);
+
+    await writeOutboxEvent<ProjectsEventMap>(tx, projectsOutbox, {
+      type: PROJECT_CREATED,
+      payload: {
+        actorId: params.actorId,
+        workspaceId: project.workspaceId,
+        projectId: project.id,
+        sourceConnectionId: project.sourceConnectionId,
+        sourceExternalRepositoryId: project.sourceExternalRepositoryId,
+      },
+    });
+    await writeOutboxEvent<ProjectsEventMap>(tx, projectsOutbox, {
+      type: PROJECT_SOURCE_BOUND,
+      payload: {
+        actorId: params.actorId,
+        workspaceId: project.workspaceId,
+        projectId: project.id,
+        sourceConnectionId: project.sourceConnectionId,
+        provider: source.connection.provider,
+        externalRepositoryId: project.sourceExternalRepositoryId,
+      },
+    });
+
+    return project;
+  });
+  recordProjectCreated();
+  return project;
+}

package/src/db/db.ts

@@ -0,0 +1,22 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {projectsIntegrationEventDedup} from './schema/integration-event-dedup.js';
+import {projectsOutbox} from './schema/outbox.js';
+import {projects} from './schema/projects.js';
+
+export const schema = {
+  projects,
+  projectsOutbox,
+  projectsIntegrationEventDedup,
+};
+
+let _db: NodePgDatabase<typeof schema> | undefined;
+
+export function db() {
+  if (!_db) _db = drizzle(pgClient(), {schema});
+  return _db;
+}
+
+export function closeDb(): void {
+  _db = undefined;
+}

package/src/db/index.ts

@@ -0,0 +1,26 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+export {closeDb, db, schema} from './db.js';
+export {
+  pruneIntegrationEventDedup,
+  recordIntegrationEventForProject,
+} from './integration-event-dedup.js';
+export type {
+  CreateProjectParams,
+  GetProjectBySourceParams,
+  ListProjectsParams,
+  ListProjectsResult,
+} from './projects.js';
+export {
+  createProject,
+  getProjectById,
+  getProjectBySource,
+  getProjectCount,
+  listProjects,
+  requireProjectForWorkspace,
+} from './projects.js';
+export {projectsIntegrationEventDedup} from './schema/integration-event-dedup.js';
+export {projectsOutbox} from './schema/outbox.js';
+
+export const migrationsPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../drizzle');

package/src/db/integration-event-dedup.ts

@@ -0,0 +1,45 @@
+import {lt} from 'drizzle-orm';
+import {db} from './db.js';
+import {projectsIntegrationEventDedup} from './schema/integration-event-dedup.js';
+
+// biome-ignore lint/suspicious/noExplicitAny: cross-module drizzle tx without a portable exported type
+type DrizzleTxLike = any;
+
+export interface RecordIntegrationEventForProjectParams {
+  tx: DrizzleTxLike;
+  integrationEventId: string;
+  projectId: string;
+}
+
+export async function recordIntegrationEventForProject(
+  params: RecordIntegrationEventForProjectParams,
+): Promise<{firstSeen: boolean}> {
+  const inserted = await params.tx
+    .insert(projectsIntegrationEventDedup)
+    .values({
+      integrationEventId: params.integrationEventId,
+      projectId: params.projectId,
+    })
+    .onConflictDoNothing({
+      target: [
+        projectsIntegrationEventDedup.integrationEventId,
+        projectsIntegrationEventDedup.projectId,
+      ],
+    })
+    .returning({projectId: projectsIntegrationEventDedup.projectId});
+
+  return {firstSeen: inserted.length > 0};
+}
+
+export interface PruneIntegrationEventDedupParams {
+  olderThan: Date;
+}
+
+export async function pruneIntegrationEventDedup(
+  params: PruneIntegrationEventDedupParams,
+): Promise<{deleted: number}> {
+  const result = await db()
+    .delete(projectsIntegrationEventDedup)
+    .where(lt(projectsIntegrationEventDedup.receivedAt, params.olderThan));
+  return {deleted: result.rowCount ?? 0};
+}

package/src/db/projects.test.ts

@@ -0,0 +1,22 @@
+import {projectFactory} from '#test/index.js';
+import {getProjectCount} from './projects.js';
+
+describe('getProjectCount', () => {
+  it('reports the current project count', async () => {
+    const before = await getProjectCount();
+
+    const after = await getProjectCount();
+
+    expect(after - before).toBe(0);
+  });
+
+  it('counts newly created projects', async () => {
+    const before = await getProjectCount();
+    await projectFactory.create();
+    await projectFactory.create();
+
+    const after = await getProjectCount();
+
+    expect(after - before).toBe(2);
+  });
+});

package/src/db/projects.ts

@@ -0,0 +1,158 @@
+import {and, count, desc, eq, ilike, lt, or, type SQL} from 'drizzle-orm';
+import type {Project} from '#core/entities/project.js';
+import {ProjectAlreadyExistsError, ProjectNotFoundError} from '#core/errors.js';
+import {recordProjectCreated} from '#metrics/instance.js';
+import {db} from './db.js';
+import {projects, toProject} from './schema/projects.js';
+
+export interface CreateProjectParams {
+  workspaceId: string;
+  sourceConnectionId: string;
+  sourceExternalRepositoryId: string;
+  name: string;
+}
+
+export interface ProjectCursor {
+  createdAt: Date;
+  id: string;
+}
+
+export interface ListProjectsParams {
+  workspaceId: string;
+  limit: number;
+  cursor?: ProjectCursor | undefined;
+  search?: string | undefined;
+}
+
+function escapeIlikePattern(value: string): string {
+  return value.replace(/[\\%_]/g, (char) => `\\${char}`);
+}
+
+export interface ListProjectsResult {
+  projects: Project[];
+  nextCursor: ProjectCursor | null;
+}
+
+function cursorWhere(params: ListProjectsParams): SQL | undefined {
+  if (!params.cursor) return undefined;
+  return or(
+    lt(projects.createdAt, params.cursor.createdAt),
+    and(eq(projects.createdAt, params.cursor.createdAt), lt(projects.id, params.cursor.id)),
+  );
+}
+
+export async function createProject(params: CreateProjectParams): Promise<Project> {
+  const project = await db().transaction(async (tx) => {
+    const [projectRow] = await tx
+      .insert(projects)
+      .values({
+        workspaceId: params.workspaceId,
+        sourceConnectionId: params.sourceConnectionId,
+        sourceExternalRepositoryId: params.sourceExternalRepositoryId,
+        name: params.name,
+      })
+      .onConflictDoNothing({
+        target: [projects.sourceConnectionId, projects.sourceExternalRepositoryId],
+      })
+      .returning();
+
+    if (!projectRow) {
+      const [conflict] = await tx
+        .select()
+        .from(projects)
+        .where(
+          and(
+            eq(projects.sourceConnectionId, params.sourceConnectionId),
+            eq(projects.sourceExternalRepositoryId, params.sourceExternalRepositoryId),
+          ),
+        )
+        .limit(1);
+      if (conflict) {
+        throw new ProjectAlreadyExistsError(
+          conflict.id,
+          params.sourceConnectionId,
+          params.sourceExternalRepositoryId,
+        );
+      }
+      throw new Error('Insert returned no rows');
+    }
+
+    return toProject(projectRow);
+  });
+  recordProjectCreated();
+  return project;
+}
+
+export async function getProjectById(id: string): Promise<Project | undefined> {
+  const rows = await db().select().from(projects).where(eq(projects.id, id)).limit(1);
+
+  const row = rows[0];
+  if (!row) return undefined;
+  return toProject(row);
+}
+
+export interface GetProjectBySourceParams {
+  workspaceId: string;
+  sourceConnectionId: string;
+  sourceExternalRepositoryId: string;
+}
+
+export async function getProjectBySource(
+  params: GetProjectBySourceParams,
+): Promise<Project | undefined> {
+  const rows = await db()
+    .select()
+    .from(projects)
+    .where(
+      and(
+        eq(projects.workspaceId, params.workspaceId),
+        eq(projects.sourceConnectionId, params.sourceConnectionId),
+        eq(projects.sourceExternalRepositoryId, params.sourceExternalRepositoryId),
+      ),
+    )
+    .limit(1);
+
+  const row = rows[0];
+  if (!row) return undefined;
+  return toProject(row);
+}
+
+export async function requireProjectForWorkspace(params: {
+  projectId: string;
+  workspaceId: string;
+}): Promise<Project> {
+  const project = await getProjectById(params.projectId);
+  if (!project) throw new ProjectNotFoundError(params.projectId);
+  if (project.workspaceId !== params.workspaceId) throw new ProjectNotFoundError(params.projectId);
+  return project;
+}
+
+export async function listProjects(params: ListProjectsParams): Promise<ListProjectsResult> {
+  const conditions = [eq(projects.workspaceId, params.workspaceId)];
+  const cursorCondition = cursorWhere(params);
+  if (cursorCondition) conditions.push(cursorCondition);
+  if (params.search) {
+    conditions.push(ilike(projects.name, `%${escapeIlikePattern(params.search)}%`));
+  }
+
+  const rows = await db()
+    .select()
+    .from(projects)
+    .where(and(...conditions))
+    .orderBy(desc(projects.createdAt), desc(projects.id))
+    .limit(params.limit + 1);
+
+  const hasMore = rows.length > params.limit;
+  const pageRows = hasMore ? rows.slice(0, params.limit) : rows;
+  const last = pageRows.at(-1);
+
+  return {
+    projects: pageRows.map(toProject),
+    nextCursor: hasMore && last ? {createdAt: last.createdAt, id: last.id} : null,
+  };
+}
+
+export async function getProjectCount(): Promise<number> {
+  const [row] = await db().select({value: count()}).from(projects);
+  return row?.value ?? 0;
+}

package/src/db/schema/common.ts

@@ -0,0 +1,3 @@
+import {pgTableCreator} from 'drizzle-orm/pg-core';
+
+export const pgTable = pgTableCreator((name) => `projects_${name}`);

package/src/db/schema/integration-event-dedup.ts

@@ -0,0 +1,15 @@
+import {index, primaryKey, timestamp, uuid} from 'drizzle-orm/pg-core';
+import {pgTable} from './common.js';
+
+export const projectsIntegrationEventDedup = pgTable(
+  'integration_event_dedup',
+  {
+    integrationEventId: uuid('integration_event_id').notNull(),
+    projectId: uuid('project_id').notNull(),
+    receivedAt: timestamp('received_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    primaryKey({columns: [table.integrationEventId, table.projectId]}),
+    index('projects_integration_event_dedup_received_at_idx').on(table.receivedAt),
+  ],
+);

package/src/db/schema/outbox.ts

@@ -0,0 +1,4 @@
+import {createOutboxTable} from '@shipfox/node-outbox';
+import {pgTable} from './common.js';
+
+export const projectsOutbox = createOutboxTable(pgTable);

package/src/db/schema/projects.ts

@@ -0,0 +1,39 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {index, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import type {Project} from '#core/entities/project.js';
+import {pgTable} from './common.js';
+
+export const projects = pgTable(
+  'projects',
+  {
+    id: uuidv7PrimaryKey(),
+    workspaceId: uuid('workspace_id').notNull(),
+    sourceConnectionId: uuid('source_connection_id').notNull(),
+    sourceExternalRepositoryId: text('source_external_repository_id').notNull(),
+    name: text('name').notNull(),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('projects_source_unique').on(
+      table.sourceConnectionId,
+      table.sourceExternalRepositoryId,
+    ),
+    index('projects_workspace_created_id_idx').on(table.workspaceId, table.createdAt, table.id),
+  ],
+);
+
+export type ProjectDb = typeof projects.$inferSelect;
+export type ProjectCreateDb = typeof projects.$inferInsert;
+
+export function toProject(row: ProjectDb): Project {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    sourceConnectionId: row.sourceConnectionId,
+    sourceExternalRepositoryId: row.sourceExternalRepositoryId,
+    name: row.name,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import type {IntegrationSourceControlService} from '@shipfox/api-integration-core';
+import {
+  INTEGRATION_SOURCE_COMMIT_PUSHED,
+  type IntegrationsEventMap,
+} from '@shipfox/api-integration-core-dto';
+import {projectsEventSchemas} from '@shipfox/api-projects-dto';
+import {type ShipfoxModule, subscriberFactory} from '@shipfox/node-module';
+import {db, migrationsPath, projectsOutbox} from '#db/index.js';
+import {registerProjectsServiceMetrics} from '#metrics/index.js';
+import {projectsE2eRoutes} from '#presentation/e2eRoutes/index.js';
+import {createProjectRoutes} from '#presentation/index.js';
+import {onSourceCommitPushed} from '#presentation/subscribers/index.js';
+import {createProjectsMaintenanceActivities} from '#temporal/activities/index.js';
+import {PROJECTS_MAINTENANCE_TASK_QUEUE} from '#temporal/constants.js';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const maintenanceWorkflowsPath = resolve(packageRoot, 'dist/temporal/workflows/index.js');
+
+const subscriber = subscriberFactory<IntegrationsEventMap>();
+
+export type {Project} from '#core/index.js';
+export {
+  createProjectFromSource,
+  ProjectAccessDeniedError,
+  ProjectAlreadyExistsError,
+  ProjectNotFoundError,
+} from '#core/index.js';
+export type {GetProjectBySourceParams} from '#db/index.js';
+export {
+  createProject,
+  db,
+  getProjectById,
+  getProjectBySource,
+  listProjects,
+  migrationsPath,
+  projectsOutbox,
+  requireProjectForWorkspace,
+} from '#db/index.js';
+export {createProjectRoutes, requireProjectAccess} from '#presentation/index.js';
+
+export interface CreateProjectsModuleOptions {
+  sourceControl: IntegrationSourceControlService;
+}
+
+export function createProjectsModule({sourceControl}: CreateProjectsModuleOptions): ShipfoxModule {
+  return {
+    name: 'projects',
+    database: {db, migrationsPath},
+    routes: createProjectRoutes(sourceControl),
+    e2eRoutes: [projectsE2eRoutes],
+    metrics: registerProjectsServiceMetrics,
+    publishers: [{name: 'projects', table: projectsOutbox, db, eventSchemas: projectsEventSchemas}],
+    subscribers: [subscriber(INTEGRATION_SOURCE_COMMIT_PUSHED, onSourceCommitPushed)],
+    workers: [
+      {
+        taskQueue: PROJECTS_MAINTENANCE_TASK_QUEUE,
+        workflowsPath: maintenanceWorkflowsPath,
+        activities: createProjectsMaintenanceActivities,
+        workflows: [
+          {
+            name: 'pruneIntegrationEventDedupCron',
+            id: 'projects-prune-integration-event-dedup',
+            cronSchedule: '0 3 * * *',
+          },
+        ],
+      },
+    ],
+  };
+}

package/src/metrics/index.ts

@@ -0,0 +1,2 @@
+export {recordProjectCreated, recordSourceCommitPushed} from './instance.js';
+export {registerProjectsServiceMetrics} from './service.js';

package/src/metrics/instance.ts

@@ -0,0 +1,34 @@
+import {instanceMetrics} from '@shipfox/node-opentelemetry';
+
+const meter = instanceMetrics.getMeter('projects');
+
+const projectsCreatedCount = meter.createCounter<Record<string, never>>('projects_created', {
+  description: 'Projects created',
+});
+
+export type SourceCommitPushedOutcome =
+  | 'duplicate'
+  | 'non_default_branch'
+  | 'observed'
+  | 'unbound_source';
+
+const sourceCommitPushedCount = meter.createCounter<{outcome: SourceCommitPushedOutcome}>(
+  'projects_source_commit_pushed',
+  {description: 'Source commit pushed events handled by outcome'},
+);
+
+function recordMetric(record: () => void): void {
+  try {
+    record();
+  } catch {
+    // Metrics must not affect project writes or subscriber acknowledgements.
+  }
+}
+
+export function recordProjectCreated(): void {
+  recordMetric(() => projectsCreatedCount.add(1));
+}
+
+export function recordSourceCommitPushed(outcome: SourceCommitPushedOutcome): void {
+  recordMetric(() => sourceCommitPushedCount.add(1, {outcome}));
+}

package/src/metrics/service.ts

@@ -0,0 +1,17 @@
+import {getServiceMetricsProvider} from '@shipfox/node-opentelemetry';
+import {getProjectCount} from '#db/projects.js';
+
+export function registerProjectsServiceMetrics(): void {
+  const meter = getServiceMetricsProvider().getMeter('projects');
+
+  const projectCount = meter.createObservableGauge('projects_project_count', {
+    description: 'Projects currently stored',
+  });
+
+  meter.addBatchObservableCallback(
+    async (observer) => {
+      observer.observe(projectCount, await getProjectCount());
+    },
+    [projectCount],
+  );
+}

package/src/presentation/auth/require-project-access.ts

@@ -0,0 +1,29 @@
+import {getUserContext, requireWorkspaceAccess} from '@shipfox/api-auth-context';
+import {ClientError} from '@shipfox/node-fastify';
+import type {FastifyRequest} from 'fastify';
+import type {Project} from '#core/entities/index.js';
+import {getProjectById} from '#db/index.js';
+
+export interface RequireProjectAccessParams {
+  request: FastifyRequest;
+  projectId: string;
+}
+
+export interface RequireProjectAccessResult {
+  project: Project;
+  workspaceId: string;
+}
+
+export async function requireProjectAccess(
+  params: RequireProjectAccessParams,
+): Promise<RequireProjectAccessResult> {
+  const userContext = getUserContext(params.request);
+  if (!userContext) {
+    throw new ClientError('Authentication required', 'unauthorized', {status: 401});
+  }
+
+  const project = await getProjectById(params.projectId);
+  if (!project) throw new ClientError('Project not found', 'project-not-found', {status: 404});
+  requireWorkspaceAccess({request: params.request, workspaceId: project.workspaceId});
+  return {project, workspaceId: project.workspaceId};
+}

package/src/presentation/dto/index.ts

@@ -0,0 +1 @@
+export {toProjectDto} from './project.js';

package/src/presentation/dto/project.ts

@@ -0,0 +1,15 @@
+import type {Project} from '#core/entities/index.js';
+
+export function toProjectDto(project: Project) {
+  return {
+    id: project.id,
+    workspace_id: project.workspaceId,
+    name: project.name,
+    source: {
+      connection_id: project.sourceConnectionId,
+      external_repository_id: project.sourceExternalRepositoryId,
+    },
+    created_at: project.createdAt.toISOString(),
+    updated_at: project.updatedAt.toISOString(),
+  };
+}