@shipfox/api-integration-github 2.0.0

package/src/core/webhook.ts

@@ -0,0 +1,296 @@
+import {
+  buildProviderRepositoryId,
+  type GetIntegrationConnectionByIdFn,
+  type IntegrationTx,
+  type PublishIntegrationEventReceivedFn,
+  type PublishSourcePushFn,
+  type RecordDeliveryOnlyFn,
+  type SourcePushPayload,
+} from '@shipfox/api-integration-core-dto';
+import {
+  type GithubPushPayloadDto,
+  githubPushPayloadSchema,
+  githubWebhookActionSchema,
+  githubWebhookInstallationSchema,
+} from '@shipfox/api-integration-github-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import {getGithubInstallationByInstallationId} from '#db/installations.js';
+
+const REFS_HEADS_PREFIX = 'refs/heads/';
+const GITHUB_SOURCE = 'github';
+// GitHub sends a `push` webhook for a branch deletion with `after` set to this all-zero SHA.
+const DELETED_BRANCH_SHA = '0'.repeat(40);
+
+export interface HandleGithubEventParams {
+  tx: IntegrationTx;
+  deliveryId: string;
+  event: string;
+  payload: unknown;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  publishSourcePush: PublishSourcePushFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+  deleteInstallationTokenSecret?:
+    | ((params: {workspaceId: string; installationId: number}) => Promise<unknown>)
+    | undefined;
+}
+
+export type HandleGithubEventOutcome =
+  | 'published'
+  | 'duplicate'
+  | 'published-envelope'
+  | 'duplicate-envelope'
+  | 'published-push-envelope-only'
+  | 'duplicate-push-envelope-only'
+  | 'unknown-installation'
+  | 'missing-connection'
+  | 'inactive-connection'
+  | 'no-installation-id';
+
+function isBranchDeletion(after: string): boolean {
+  return after === DELETED_BRANCH_SHA;
+}
+
+export async function handleGithubEvent(
+  params: HandleGithubEventParams,
+): Promise<{outcome: HandleGithubEventOutcome}> {
+  const actionEnvelope = githubWebhookActionSchema.safeParse(params.payload);
+  const action = actionEnvelope.success ? actionEnvelope.data.action : undefined;
+  const installationEnvelope = githubWebhookInstallationSchema.safeParse(params.payload);
+  const installationId = installationEnvelope.success
+    ? installationEnvelope.data.installation?.id
+    : undefined;
+  if (installationId === undefined) {
+    await params.recordDeliveryOnly({
+      tx: params.tx,
+      provider: GITHUB_SOURCE,
+      deliveryId: params.deliveryId,
+    });
+    return {outcome: 'no-installation-id'};
+  }
+
+  const installation = await getGithubInstallationByInstallationId(String(installationId), {
+    tx: params.tx,
+  });
+  if (!installation) {
+    logger().warn(
+      {deliveryId: params.deliveryId, installationId},
+      'github webhook: unknown installation, dropping',
+    );
+    await params.recordDeliveryOnly({
+      tx: params.tx,
+      provider: GITHUB_SOURCE,
+      deliveryId: params.deliveryId,
+    });
+    return {outcome: 'unknown-installation'};
+  }
+
+  const connection = await params.getIntegrationConnectionById(installation.connectionId, {
+    tx: params.tx,
+  });
+  if (!connection) {
+    logger().warn(
+      {deliveryId: params.deliveryId, installationId, connectionId: installation.connectionId},
+      'github webhook: installation has no connection, dropping',
+    );
+    await params.recordDeliveryOnly({
+      tx: params.tx,
+      provider: GITHUB_SOURCE,
+      deliveryId: params.deliveryId,
+    });
+    return {outcome: 'missing-connection'};
+  }
+
+  if (connection.lifecycleStatus !== 'active') {
+    const logContext = {
+      deliveryId: params.deliveryId,
+      installationId,
+      connectionId: connection.id,
+      workspaceId: connection.workspaceId,
+      lifecycleStatus: connection.lifecycleStatus,
+    };
+    // `disabled` is an expected steady state; only `error` is anomalous.
+    if (connection.lifecycleStatus === 'error') {
+      logger().warn(logContext, 'github webhook: connection in error state, dropping');
+    } else {
+      logger().info(logContext, 'github webhook: connection disabled, dropping');
+    }
+    await params.recordDeliveryOnly({
+      tx: params.tx,
+      provider: GITHUB_SOURCE,
+      deliveryId: params.deliveryId,
+    });
+    return {outcome: 'inactive-connection'};
+  }
+
+  if (params.event === 'push') {
+    const validated = githubPushPayloadSchema.safeParse(params.payload);
+    if (!validated.success) {
+      logger().warn(
+        {deliveryId: params.deliveryId, issues: validated.error.issues},
+        'github webhook push payload failed schema validation; publishing generic envelope only',
+      );
+      return publishGithubEnvelopeOnly({
+        tx: params.tx,
+        deliveryId: params.deliveryId,
+        payload: params.payload,
+        publishIntegrationEventReceived: params.publishIntegrationEventReceived,
+        connection,
+        event: 'push',
+      });
+    }
+
+    return publishGithubPush({
+      ...params,
+      eventPayload: validated.data,
+      rawPayload: params.payload,
+      connection,
+    });
+  }
+
+  const eventName = action ? `${params.event}.${action}` : params.event;
+  const result = await publishGithubEnvelopeOnly({
+    tx: params.tx,
+    deliveryId: params.deliveryId,
+    payload: params.payload,
+    publishIntegrationEventReceived: params.publishIntegrationEventReceived,
+    connection,
+    event: eventName,
+  });
+  if (result.outcome === 'published-envelope') {
+    await deleteInstallationTokenSecretBestEffort({
+      deleteInstallationTokenSecret: params.deleteInstallationTokenSecret,
+      event: params.event,
+      action,
+      deliveryId: params.deliveryId,
+      workspaceId: connection.workspaceId,
+      installationId,
+    });
+  }
+  return result;
+}
+
+function shouldDeleteInstallationTokenSecret(event: string, action: string | undefined): boolean {
+  return event === 'installation' && (action === 'deleted' || action === 'suspend');
+}
+
+async function deleteInstallationTokenSecretBestEffort(params: {
+  deleteInstallationTokenSecret:
+    | ((params: {workspaceId: string; installationId: number}) => Promise<unknown>)
+    | undefined;
+  event: string;
+  action: string | undefined;
+  deliveryId: string;
+  workspaceId: string;
+  installationId: number;
+}): Promise<void> {
+  if (!shouldDeleteInstallationTokenSecret(params.event, params.action)) return;
+
+  try {
+    await params.deleteInstallationTokenSecret?.({
+      workspaceId: params.workspaceId,
+      installationId: params.installationId,
+    });
+  } catch (error) {
+    logger().warn(
+      {
+        deliveryId: params.deliveryId,
+        installationId: params.installationId,
+        workspaceId: params.workspaceId,
+        error,
+      },
+      'github webhook installation token cleanup failed',
+    );
+  }
+}
+
+async function publishGithubPush(params: {
+  tx: IntegrationTx;
+  deliveryId: string;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  publishSourcePush: PublishSourcePushFn;
+  eventPayload: GithubPushPayloadDto;
+  rawPayload: unknown;
+  connection: {
+    id: string;
+    workspaceId: string;
+    slug: string;
+    displayName: string;
+  };
+}): Promise<{outcome: HandleGithubEventOutcome}> {
+  if (isBranchDeletion(params.eventPayload.after)) {
+    const result = await params.publishIntegrationEventReceived({
+      tx: params.tx,
+      event: {
+        provider: GITHUB_SOURCE,
+        source: params.connection.slug,
+        event: 'push',
+        workspaceId: params.connection.workspaceId,
+        connectionId: params.connection.id,
+        connectionName: params.connection.displayName,
+        deliveryId: params.deliveryId,
+        receivedAt: new Date().toISOString(),
+        payload: params.rawPayload,
+      },
+    });
+    return {
+      outcome: result.published ? 'published-push-envelope-only' : 'duplicate-push-envelope-only',
+    };
+  }
+
+  const ref = stripRefsHeads(params.eventPayload.ref);
+  const defaultBranch = params.eventPayload.repository.default_branch;
+  const push: SourcePushPayload = {
+    externalRepositoryId: buildProviderRepositoryId(
+      GITHUB_SOURCE,
+      String(params.eventPayload.repository.id),
+    ),
+    ref,
+    headCommitSha: params.eventPayload.after,
+    defaultBranch,
+    isDefaultBranch: ref === defaultBranch,
+  };
+  const result = await params.publishSourcePush({
+    tx: params.tx,
+    provider: GITHUB_SOURCE,
+    source: params.connection.slug,
+    workspaceId: params.connection.workspaceId,
+    connectionId: params.connection.id,
+    connectionName: params.connection.displayName,
+    deliveryId: params.deliveryId,
+    receivedAt: new Date().toISOString(),
+    rawPayload: params.rawPayload,
+    push,
+  });
+
+  return {outcome: result.published ? 'published' : 'duplicate'};
+}
+
+async function publishGithubEnvelopeOnly(params: {
+  tx: IntegrationTx;
+  deliveryId: string;
+  payload: unknown;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  connection: {id: string; workspaceId: string; slug: string; displayName: string};
+  event: string;
+}): Promise<{outcome: HandleGithubEventOutcome}> {
+  const result = await params.publishIntegrationEventReceived({
+    tx: params.tx,
+    event: {
+      provider: GITHUB_SOURCE,
+      source: params.connection.slug,
+      event: params.event,
+      workspaceId: params.connection.workspaceId,
+      connectionId: params.connection.id,
+      connectionName: params.connection.displayName,
+      deliveryId: params.deliveryId,
+      receivedAt: new Date().toISOString(),
+      payload: params.payload,
+    },
+  });
+  return {outcome: result.published ? 'published-envelope' : 'duplicate-envelope'};
+}
+
+function stripRefsHeads(ref: string): string {
+  return ref.startsWith(REFS_HEADS_PREFIX) ? ref.slice(REFS_HEADS_PREFIX.length) : ref;
+}

package/src/db/db.ts

@@ -0,0 +1,18 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {githubInstallations} from './schema/installations.js';
+
+export const schema = {
+  githubInstallations,
+};
+
+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/installation-token-lock.test.ts

@@ -0,0 +1,68 @@
+import {withInstallationTokenLock} from './installation-token-lock.js';
+
+describe('withInstallationTokenLock', () => {
+  it('allows one holder per installation and fails contenders fast', async () => {
+    const first = holdInstallationTokenLock(9001, 'winner');
+
+    await first.ready;
+    const contender = await withInstallationTokenLock(9001, async () => 'contender');
+    const different = await withInstallationTokenLock(9002, async () => 'different');
+    first.release();
+    const winner = await first.result;
+
+    expect(contender).toEqual({acquired: false});
+    expect(different).toEqual({acquired: true, value: 'different'});
+    expect(winner).toEqual({acquired: true, value: 'winner'});
+  });
+
+  it('does not collide installations that differ outside the 32-bit range', async () => {
+    const holder = holdInstallationTokenLock(1, 'holder');
+
+    await holder.ready;
+    const different = await withInstallationTokenLock(1 + 2 ** 32, async () => 'different');
+    holder.release();
+    const held = await holder.result;
+
+    expect(different).toEqual({acquired: true, value: 'different'});
+    expect(held).toEqual({acquired: true, value: 'holder'});
+  });
+
+  it('does not exhaust a small pool when many contenders miss the try-lock', async () => {
+    const holder = holdInstallationTokenLock(9010, 'holder');
+
+    await holder.ready;
+    const contenders = await Promise.all(
+      Array.from({length: 20}, () => withInstallationTokenLock(9010, async () => 'contender')),
+    );
+    holder.release();
+    const held = await holder.result;
+
+    expect(contenders).toEqual(Array.from({length: 20}, () => ({acquired: false})));
+    expect(held).toEqual({acquired: true, value: 'holder'});
+  });
+});
+
+function holdInstallationTokenLock(installationId: number, value: string) {
+  let releaseLock: (() => void) | undefined;
+  let markReady: () => void = () => undefined;
+  const ready = new Promise<void>((resolve) => {
+    markReady = resolve;
+  });
+  const result = withInstallationTokenLock(
+    installationId,
+    () =>
+      new Promise<string>((resolve) => {
+        releaseLock = () => resolve(value);
+        markReady();
+      }),
+  );
+
+  return {
+    ready,
+    release: () => {
+      if (!releaseLock) throw new Error('releaseLock was not initialized');
+      releaseLock();
+    },
+    result,
+  };
+}

package/src/db/installation-token-lock.ts

@@ -0,0 +1,39 @@
+import {sql} from 'drizzle-orm';
+import {recordInstallationTokenLockWait} from '#metrics/index.js';
+import {db} from './db.js';
+
+export type InstallationTokenLockResult<T> = {acquired: true; value: T} | {acquired: false};
+
+export function withInstallationTokenLock<T>(
+  installationId: number,
+  fn: () => Promise<T>,
+): Promise<InstallationTokenLockResult<T>> {
+  const lockKey = installationTokenLockKey(installationId);
+  return db().transaction(async (tx) => {
+    const startedAt = Date.now();
+    const lock = await tx.execute<{acquired: boolean}>(sql`
+      SELECT pg_try_advisory_xact_lock(${lockKey}::bigint) AS acquired
+    `);
+    const acquired = lock.rows[0]?.acquired === true;
+    if (!acquired) {
+      recordInstallationTokenLockWait(Date.now() - startedAt);
+      return {acquired: false};
+    }
+
+    try {
+      const value = await fn();
+      return {acquired: true, value};
+    } finally {
+      recordInstallationTokenLockWait(Date.now() - startedAt);
+    }
+  });
+}
+
+function installationTokenLockKey(installationId: number): string {
+  if (!Number.isSafeInteger(installationId) || installationId < 0) {
+    throw new Error(`Invalid GitHub installation id for advisory lock: ${installationId}`);
+  }
+
+  // Keep these exact per-installation keys away from positive advisory-lock ids.
+  return String(-BigInt(installationId) - 1n);
+}

package/src/db/installations.test.ts

@@ -0,0 +1,67 @@
+import {randomUUID} from 'node:crypto';
+import {GithubInstallationAlreadyLinkedError} from '#core/errors.js';
+import {db} from './db.js';
+import {
+  getGithubInstallationByInstallationId,
+  type UpsertGithubInstallationParams,
+  upsertGithubInstallation,
+} from './installations.js';
+import {githubInstallations} from './schema/installations.js';
+
+function installationParams(
+  overrides: Partial<UpsertGithubInstallationParams> = {},
+): UpsertGithubInstallationParams {
+  return {
+    connectionId: randomUUID(),
+    installationId: `${Math.floor(Math.random() * 1_000_000)}`,
+    accountLogin: 'shipfox',
+    accountType: 'Organization',
+    repositorySelection: 'all',
+    latestEvent: {id: 1},
+    ...overrides,
+  };
+}
+
+describe('github installations persistence', () => {
+  beforeEach(async () => {
+    await db().delete(githubInstallations);
+  });
+
+  test('upsert updates in place when the same connection reconnects, without duplicating', async () => {
+    const installationId = `${Date.now()}`;
+    const connectionId = randomUUID();
+    await upsertGithubInstallation(installationParams({connectionId, installationId}));
+
+    const updated = await upsertGithubInstallation(
+      installationParams({connectionId, installationId, accountLogin: 'shipfox-renamed'}),
+    );
+
+    expect(updated.connectionId).toBe(connectionId);
+    expect(updated.accountLogin).toBe('shipfox-renamed');
+    const fetched = await getGithubInstallationByInstallationId(installationId);
+    expect(fetched?.accountLogin).toBe('shipfox-renamed');
+  });
+
+  test('upsert rejects repointing an installation to a different connection (TOCTOU guard)', async () => {
+    const installationId = `${Date.now()}`;
+    const firstConnectionId = randomUUID();
+    const secondConnectionId = randomUUID();
+    await upsertGithubInstallation(
+      installationParams({connectionId: firstConnectionId, installationId}),
+    );
+
+    const repoint = upsertGithubInstallation(
+      installationParams({connectionId: secondConnectionId, installationId}),
+    );
+
+    await expect(repoint).rejects.toBeInstanceOf(GithubInstallationAlreadyLinkedError);
+    const fetched = await getGithubInstallationByInstallationId(installationId);
+    expect(fetched?.connectionId).toBe(firstConnectionId);
+  });
+
+  test('getGithubInstallationByInstallationId returns undefined for a miss', async () => {
+    const result = await getGithubInstallationByInstallationId('missing');
+
+    expect(result).toBeUndefined();
+  });
+});

package/src/db/installations.ts

@@ -0,0 +1,108 @@
+import {eq} from 'drizzle-orm';
+import {GithubInstallationAlreadyLinkedError} from '#core/errors.js';
+import {db} from './db.js';
+import {githubInstallations, toGithubInstallation} from './schema/installations.js';
+
+export interface GithubInstallation {
+  id: string;
+  connectionId: string;
+  installationId: string;
+  accountLogin: string;
+  accountType: string;
+  repositorySelection: string;
+  suspendedAt: Date | null;
+  deletedAt: Date | null;
+  latestEvent: Record<string, unknown>;
+  installerUserId: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface UpsertGithubInstallationParams {
+  connectionId: string;
+  installationId: string;
+  accountLogin: string;
+  accountType: string;
+  repositorySelection: string;
+  suspendedAt?: Date | null | undefined;
+  deletedAt?: Date | null | undefined;
+  latestEvent: Record<string, unknown>;
+  installerUserId?: string | null | undefined;
+}
+
+type GithubDb = ReturnType<typeof db>;
+type GithubTx = Parameters<Parameters<GithubDb['transaction']>[0]>[0];
+
+export async function upsertGithubInstallation(
+  params: UpsertGithubInstallationParams,
+  options: {tx?: unknown} = {},
+): Promise<GithubInstallation> {
+  const executor = (options.tx ?? db()) as GithubDb | GithubTx;
+  const now = new Date();
+  const [row] = await executor
+    .insert(githubInstallations)
+    .values({
+      connectionId: params.connectionId,
+      installationId: params.installationId,
+      accountLogin: params.accountLogin,
+      accountType: params.accountType,
+      repositorySelection: params.repositorySelection,
+      suspendedAt: params.suspendedAt ?? null,
+      deletedAt: params.deletedAt ?? null,
+      latestEvent: params.latestEvent,
+      installerUserId: params.installerUserId ?? null,
+    })
+    .onConflictDoUpdate({
+      target: githubInstallations.installationId,
+      // TOCTOU guard: only (re)point this installation at the connection that
+      // already owns it. A concurrent connect of the same installation to a
+      // different workspace inserts its own connection row, so its connectionId
+      // differs here; the predicate is false, Postgres updates nothing, and the
+      // empty RETURNING below rolls the losing transaction back instead of
+      // silently repointing the installation (cross-tenant event misroute).
+      setWhere: eq(githubInstallations.connectionId, params.connectionId),
+      set: {
+        connectionId: params.connectionId,
+        accountLogin: params.accountLogin,
+        accountType: params.accountType,
+        repositorySelection: params.repositorySelection,
+        suspendedAt: params.suspendedAt ?? null,
+        deletedAt: params.deletedAt ?? null,
+        latestEvent: params.latestEvent,
+        installerUserId: params.installerUserId ?? null,
+        updatedAt: now,
+      },
+    })
+    .returning();
+
+  if (!row) throw new GithubInstallationAlreadyLinkedError(params.installationId);
+  return toGithubInstallation(row);
+}
+
+export async function getGithubInstallationByConnectionId(
+  connectionId: string,
+): Promise<GithubInstallation | undefined> {
+  const rows = await db()
+    .select()
+    .from(githubInstallations)
+    .where(eq(githubInstallations.connectionId, connectionId))
+    .limit(1);
+  const row = rows[0];
+  if (!row) return undefined;
+  return toGithubInstallation(row);
+}
+
+export async function getGithubInstallationByInstallationId(
+  installationId: string,
+  options: {tx?: unknown} = {},
+): Promise<GithubInstallation | undefined> {
+  const executor = (options.tx ?? db()) as GithubDb | GithubTx;
+  const rows = await executor
+    .select()
+    .from(githubInstallations)
+    .where(eq(githubInstallations.installationId, installationId))
+    .limit(1);
+  const row = rows[0];
+  if (!row) return undefined;
+  return toGithubInstallation(row);
+}

package/src/db/migrations.ts

@@ -0,0 +1,4 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+export const migrationsPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../drizzle');

package/src/db/schema/common.ts

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

package/src/db/schema/installations.ts

@@ -0,0 +1,46 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {jsonb, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import type {GithubInstallation} from '#db/installations.js';
+import {pgTable} from './common.js';
+
+export const githubInstallations = pgTable(
+  'installations',
+  {
+    id: uuidv7PrimaryKey(),
+    connectionId: uuid('connection_id').notNull(),
+    installationId: text('installation_id').notNull(),
+    accountLogin: text('account_login').notNull(),
+    accountType: text('account_type').notNull(),
+    repositorySelection: text('repository_selection').notNull(),
+    suspendedAt: timestamp('suspended_at', {withTimezone: true}),
+    deletedAt: timestamp('deleted_at', {withTimezone: true}),
+    latestEvent: jsonb('latest_event').notNull().$type<Record<string, unknown>>(),
+    installerUserId: uuid('installer_user_id'),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('integrations_github_installations_connection_unique').on(table.connectionId),
+    uniqueIndex('integrations_github_installations_installation_unique').on(table.installationId),
+  ],
+);
+
+export type GithubInstallationDb = typeof githubInstallations.$inferSelect;
+export type GithubInstallationCreateDb = typeof githubInstallations.$inferInsert;
+
+export function toGithubInstallation(row: GithubInstallationDb): GithubInstallation {
+  return {
+    id: row.id,
+    connectionId: row.connectionId,
+    installationId: row.installationId,
+    accountLogin: row.accountLogin,
+    accountType: row.accountType,
+    repositorySelection: row.repositorySelection,
+    suspendedAt: row.suspendedAt,
+    deletedAt: row.deletedAt,
+    latestEvent: row.latestEvent,
+    installerUserId: row.installerUserId,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}