@shipfox/api-integration-github 2.0.0

package/src/index.ts

@@ -0,0 +1,124 @@
+import type {
+  GetIntegrationConnectionByIdFn,
+  PublishIntegrationEventReceivedFn,
+  PublishSourcePushFn,
+  RecordDeliveryOnlyFn,
+} from '@shipfox/api-integration-core-dto';
+import type {NodePgDatabase} from 'drizzle-orm/node-postgres';
+import {createGithubApiClient, type GithubApiClient} from '#api/client.js';
+import type {GithubInstallationTokenProvider} from '#api/installation-token-provider.js';
+import {deleteGithubInstallationTokenSecret} from '#api/installation-token-provider.js';
+import {GithubAgentToolsProvider} from '#core/agent-tools.js';
+import {GithubSourceControlProvider} from '#core/source-control.js';
+import {closeDb, db} from '#db/db.js';
+import {getGithubInstallationByConnectionId} from '#db/installations.js';
+import {migrationsPath} from '#db/migrations.js';
+import {
+  type CreateGithubE2eRoutesOptions,
+  createGithubE2eRoutes,
+} from '#presentation/e2eRoutes/index.js';
+import {
+  type CreateGithubIntegrationRoutesOptions,
+  createGithubIntegrationRoutes,
+} from '#presentation/routes/install.js';
+import {createGithubWebhookRoutes} from '#presentation/routes/webhooks.js';
+
+export type {GithubApiClient} from '#api/client.js';
+export {
+  encodeInstallationTokenEnvelope,
+  githubInstallationTokenNamespace,
+} from '#api/installation-token-envelope.js';
+export {
+  createGithubInstallationTokenProvider,
+  type GithubInstallationTokenProvider,
+} from '#api/installation-token-provider.js';
+export {
+  type GithubAgentToolCatalogEntry,
+  type GithubAgentToolCategory,
+  type GithubAgentToolId,
+  type GithubAgentToolPermission,
+  type GithubAgentToolPermissionAccess,
+  type GithubAgentToolRequiredPermission,
+  type GithubAgentToolRequiredScope,
+  GithubAgentToolsProvider,
+  githubAgentToolCatalog,
+} from '#core/agent-tools.js';
+export {GithubIntegrationProviderError} from '#core/errors.js';
+export type {ConnectGithubInstallationInput} from '#core/install.js';
+export {handleGithubCallback} from '#core/install.js';
+export {signGithubInstallState, verifyGithubInstallState} from '#core/state.js';
+export type {HandleGithubEventOutcome} from '#core/webhook.js';
+export {handleGithubEvent} from '#core/webhook.js';
+export type {GithubInstallation, UpsertGithubInstallationParams} from '#db/installations.js';
+export {
+  getGithubInstallationByConnectionId,
+  getGithubInstallationByInstallationId,
+  upsertGithubInstallation,
+} from '#db/installations.js';
+export {type CreateGithubE2eRoutesOptions, closeDb, createGithubE2eRoutes, db, migrationsPath};
+
+export interface CreateGithubIntegrationProviderOptions
+  extends Omit<CreateGithubIntegrationRoutesOptions, 'github'> {
+  github?: GithubApiClient | undefined;
+  coreDb: () => NodePgDatabase<Record<string, unknown>>;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  publishSourcePush: PublishSourcePushFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+  getGithubInstallationByConnectionId?: typeof getGithubInstallationByConnectionId | undefined;
+  deleteSecrets?:
+    | ((params: {workspaceId: string; namespace: string}) => Promise<number>)
+    | undefined;
+  agentTools?: {tokenProvider: GithubInstallationTokenProvider} | undefined;
+}
+
+export function createGithubIntegrationProvider(options: CreateGithubIntegrationProviderOptions) {
+  const github = options.github ?? createGithubApiClient();
+  const getInstallationByConnectionId =
+    options.getGithubInstallationByConnectionId ?? getGithubInstallationByConnectionId;
+  const deleteSecrets = options.deleteSecrets;
+
+  return {
+    provider: 'github' as const,
+    displayName: 'GitHub',
+    adapters: {
+      source_control: new GithubSourceControlProvider(github),
+      agent_tools: new GithubAgentToolsProvider({
+        getInstallationByConnectionId: getInstallationByConnectionId,
+        tokenProvider: options.agentTools?.tokenProvider,
+      }),
+    },
+    async connectionExternalUrl(connection: {id: string}): Promise<string | undefined> {
+      const installation = await getInstallationByConnectionId(connection.id);
+      if (!installation) return undefined;
+      const installationId = encodeURIComponent(installation.installationId);
+      if (installation.accountType === 'Organization') {
+        const login = encodeURIComponent(installation.accountLogin);
+        return `https://github.com/organizations/${login}/settings/installations/${installationId}`;
+      }
+      return `https://github.com/settings/installations/${installationId}`;
+    },
+    routes: [
+      createGithubIntegrationRoutes({
+        github,
+        getExistingGithubConnection: options.getExistingGithubConnection,
+        connectGithubInstallation: options.connectGithubInstallation,
+      }),
+      createGithubWebhookRoutes({
+        coreDb: options.coreDb,
+        publishIntegrationEventReceived: options.publishIntegrationEventReceived,
+        publishSourcePush: options.publishSourcePush,
+        recordDeliveryOnly: options.recordDeliveryOnly,
+        getIntegrationConnectionById: options.getIntegrationConnectionById,
+        deleteInstallationTokenSecret: deleteSecrets
+          ? (params) =>
+              deleteGithubInstallationTokenSecret({
+                workspaceId: params.workspaceId,
+                installationId: params.installationId,
+                deleteSecrets,
+              })
+          : undefined,
+      }),
+    ],
+  };
+}

package/src/metrics/index.ts

@@ -0,0 +1 @@
+export * from './instance.js';

package/src/metrics/instance.ts

@@ -0,0 +1,82 @@
+import type {IntegrationProviderErrorReason} from '@shipfox/api-integration-core-dto';
+import {instanceMetrics} from '@shipfox/node-opentelemetry';
+import type {MintErrorClass} from '#api/installation-token-envelope.js';
+
+const meter = instanceMetrics.getMeter('github');
+
+export type GithubInstallationTokenLookupOutcome =
+  | 'ram-hit'
+  | 'db-hit'
+  | 'minted'
+  | 'served-stale'
+  | 'backoff'
+  | 'contended-poll';
+
+const installationTokenLookupCount = meter.createCounter<{
+  outcome: GithubInstallationTokenLookupOutcome;
+}>('github_installation_token_lookup', {
+  description: 'GitHub installation token cache lookups by serving outcome',
+});
+
+const installationTokenMintCount = meter.createCounter<{outcome: 'success' | 'failure'}>(
+  'github_installation_token_mint',
+  {description: 'GitHub installation token mint attempts by outcome'},
+);
+
+const installationTokenMintDuration = meter.createHistogram<Record<string, never>>(
+  'github_installation_token_mint_duration',
+  {
+    description: 'GitHub installation token mint duration',
+    unit: 'ms',
+    advice: {explicitBucketBoundaries: [10, 50, 100, 250, 500, 1000, 2500, 5000, 10000]},
+  },
+);
+
+const installationTokenLockWaitDuration = meter.createHistogram<Record<string, never>>(
+  'github_installation_token_lock_wait_duration',
+  {
+    description: 'GitHub installation token advisory lock acquire and hold duration',
+    unit: 'ms',
+    advice: {explicitBucketBoundaries: [0, 1, 5, 10, 25, 50, 100, 250, 500, 1000, 5000]},
+  },
+);
+
+const installationTokenBackoffCount = meter.createCounter<{
+  reason: IntegrationProviderErrorReason;
+  class: MintErrorClass;
+}>('github_installation_token_backoff', {
+  description: 'GitHub installation token mint backoff activations by reason and class',
+});
+
+function recordMetric(record: () => void): void {
+  try {
+    record();
+  } catch {
+    // Metrics must not affect GitHub provider outcomes.
+  }
+}
+
+export function recordInstallationTokenLookup(outcome: GithubInstallationTokenLookupOutcome): void {
+  recordMetric(() => installationTokenLookupCount.add(1, {outcome}));
+}
+
+export function recordInstallationTokenMint(params: {
+  outcome: 'success' | 'failure';
+  durationMs: number;
+}): void {
+  recordMetric(() => {
+    installationTokenMintCount.add(1, {outcome: params.outcome});
+    installationTokenMintDuration.record(params.durationMs);
+  });
+}
+
+export function recordInstallationTokenLockWait(durationMs: number): void {
+  recordMetric(() => installationTokenLockWaitDuration.record(durationMs));
+}
+
+export function recordInstallationTokenBackoff(params: {
+  reason: IntegrationProviderErrorReason;
+  class: MintErrorClass;
+}): void {
+  recordMetric(() => installationTokenBackoffCount.add(1, params));
+}

package/src/presentation/dto/integrations.ts

@@ -0,0 +1,8 @@
+import {
+  type IntegrationConnection,
+  toIntegrationConnectionDto as toCoreIntegrationConnectionDto,
+} from '@shipfox/api-integration-core-dto';
+
+export function toIntegrationConnectionDto(connection: IntegrationConnection<'github'>) {
+  return toCoreIntegrationConnectionDto(connection, {capabilities: ['source_control']});
+}

package/src/presentation/e2eRoutes/create-connection.ts

@@ -0,0 +1,70 @@
+import type {IntegrationCapability, IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {toIntegrationConnectionDto} from '@shipfox/api-integration-core-dto';
+import {
+  createE2eGithubConnectionBodySchema,
+  createE2eGithubConnectionResponseSchema,
+} from '@shipfox/api-integration-github-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import type {ConnectGithubInstallationInput} from '#core/install.js';
+
+export interface CreateE2eGithubConnectionRouteOptions {
+  getExistingGithubConnection: (input: {
+    installationId: string;
+  }) => Promise<IntegrationConnection<'github'> | undefined>;
+  connectGithubInstallation: (
+    input: ConnectGithubInstallationInput,
+  ) => Promise<IntegrationConnection<'github'>>;
+  connectionCapabilities: IntegrationCapability[];
+}
+
+export function createE2eGithubConnectionRoute(options: CreateE2eGithubConnectionRouteOptions) {
+  return defineRoute({
+    method: 'POST',
+    path: '/github-connections',
+    description: 'Create a synthetic GitHub connection for E2E tests.',
+    schema: {
+      body: createE2eGithubConnectionBodySchema,
+      response: {201: createE2eGithubConnectionResponseSchema},
+    },
+    handler: async (request, reply) => {
+      const body = request.body;
+      const installationId = String(body.installation_id);
+      const existing = await options.getExistingGithubConnection({installationId});
+      if (existing && existing.workspaceId !== body.workspace_id) {
+        throw new ClientError(
+          'GitHub installation is already connected to another workspace',
+          'github-connection-workspace-mismatch',
+          {status: 409},
+        );
+      }
+
+      const connection =
+        existing ??
+        (await options.connectGithubInstallation({
+          workspaceId: body.workspace_id,
+          installationId,
+          displayName: body.display_name,
+          installerUserId: body.installer_user_id,
+          installation: {
+            installationId,
+            accountLogin: body.account_login,
+            accountType: 'Organization',
+            repositorySelection: 'all',
+            suspendedAt: null,
+            deletedAt: null,
+            latestEvent: {
+              id: body.installation_id,
+              account: {login: body.account_login, type: 'Organization'},
+              repository_selection: 'all',
+            },
+            installerUserId: body.installer_user_id,
+          },
+        }));
+
+      reply.code(201);
+      return toIntegrationConnectionDto(connection, {
+        capabilities: options.connectionCapabilities,
+      });
+    },
+  });
+}

package/src/presentation/e2eRoutes/index.test.ts

@@ -0,0 +1,126 @@
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {closeApp, createApp} from '@shipfox/node-fastify';
+import {createGithubE2eRoutes} from './index.js';
+
+function connection(
+  overrides: Partial<IntegrationConnection<'github'>> = {},
+): IntegrationConnection<'github'> {
+  return {
+    id: '00000000-0000-4000-8000-000000000001',
+    workspaceId: '00000000-0000-4000-8000-000000000002',
+    provider: 'github',
+    externalAccountId: '1234',
+    slug: 'github_shipfox_e2e',
+    displayName: 'GitHub Shipfox E2E',
+    lifecycleStatus: 'active',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+describe('GitHub E2E routes', () => {
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  it('creates a synthetic GitHub connection and installation', async () => {
+    const connectGithubInstallation = vi.fn(() => Promise.resolve(connection()));
+    const app = await createApp({
+      routes: [
+        createGithubE2eRoutes({
+          getExistingGithubConnection: vi.fn(() => Promise.resolve(undefined)),
+          connectGithubInstallation,
+          connectionCapabilities: ['source_control', 'agent_tools'],
+        }),
+      ],
+      swagger: false,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/github-connections',
+      payload: {
+        workspace_id: '00000000-0000-4000-8000-000000000002',
+        installation_id: 1234,
+        account_login: 'shipfox-e2e',
+        display_name: 'GitHub Shipfox E2E',
+        installer_user_id: '00000000-0000-4000-8000-000000000004',
+      },
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toMatchObject({
+      id: '00000000-0000-4000-8000-000000000001',
+      provider: 'github',
+      capabilities: ['source_control', 'agent_tools'],
+    });
+    expect(connectGithubInstallation).toHaveBeenCalledWith({
+      workspaceId: '00000000-0000-4000-8000-000000000002',
+      installationId: '1234',
+      displayName: 'GitHub Shipfox E2E',
+      installerUserId: '00000000-0000-4000-8000-000000000004',
+      installation: expect.objectContaining({
+        installationId: '1234',
+        accountLogin: 'shipfox-e2e',
+        accountType: 'Organization',
+        repositorySelection: 'all',
+        installerUserId: '00000000-0000-4000-8000-000000000004',
+      }),
+    });
+  });
+
+  it('rejects malformed connection bodies', async () => {
+    const app = await createApp({
+      routes: [
+        createGithubE2eRoutes({
+          getExistingGithubConnection: vi.fn(() => Promise.resolve(undefined)),
+          connectGithubInstallation: vi.fn(() => Promise.resolve(connection())),
+          connectionCapabilities: ['source_control', 'agent_tools'],
+        }),
+      ],
+      swagger: false,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/github-connections',
+      payload: {workspace_id: 'not-a-uuid'},
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json()).toMatchObject({code: 'validation-error'});
+  });
+
+  it('rejects an installation connected to another workspace', async () => {
+    const connectGithubInstallation = vi.fn(() => Promise.resolve(connection()));
+    const app = await createApp({
+      routes: [
+        createGithubE2eRoutes({
+          getExistingGithubConnection: vi.fn(() =>
+            Promise.resolve(connection({workspaceId: '00000000-0000-4000-8000-000000000003'})),
+          ),
+          connectGithubInstallation,
+          connectionCapabilities: ['source_control', 'agent_tools'],
+        }),
+      ],
+      swagger: false,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/github-connections',
+      payload: {
+        workspace_id: '00000000-0000-4000-8000-000000000002',
+        installation_id: 1234,
+        account_login: 'shipfox-e2e',
+        display_name: 'GitHub Shipfox E2E',
+        installer_user_id: '00000000-0000-4000-8000-000000000004',
+      },
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json()).toMatchObject({code: 'github-connection-workspace-mismatch'});
+    expect(connectGithubInstallation).not.toHaveBeenCalled();
+  });
+});

package/src/presentation/e2eRoutes/index.ts

@@ -0,0 +1,14 @@
+import type {RouteGroup} from '@shipfox/node-fastify';
+import {
+  type CreateE2eGithubConnectionRouteOptions,
+  createE2eGithubConnectionRoute,
+} from './create-connection.js';
+
+export type CreateGithubE2eRoutesOptions = CreateE2eGithubConnectionRouteOptions;
+
+export function createGithubE2eRoutes(options: CreateGithubE2eRoutesOptions): RouteGroup {
+  return {
+    prefix: '/integrations',
+    routes: [createE2eGithubConnectionRoute(options)],
+  };
+}

package/src/presentation/routes/errors.ts

@@ -0,0 +1,43 @@
+import {
+  ConnectionSlugConflictError,
+  type IntegrationProviderErrorReason,
+} from '@shipfox/api-integration-core-dto';
+import {ClientError} from '@shipfox/node-fastify';
+import {
+  GithubInstallationAlreadyLinkedError,
+  GithubInstallationNotAuthorizedError,
+  GithubInstallStateActorMismatchError,
+  GithubInstallStateError,
+  GithubIntegrationProviderError,
+} from '#core/errors.js';
+
+function providerStatus(reason: IntegrationProviderErrorReason): number {
+  if (reason === 'rate-limited') return 429;
+  if (reason === 'timeout' || reason === 'provider-unavailable') return 503;
+  return 422;
+}
+
+export function githubRouteErrorHandler(error: unknown): never {
+  if (error instanceof GithubInstallStateError) {
+    throw new ClientError(error.message, 'invalid-github-install-state', {status: 400});
+  }
+  if (error instanceof GithubInstallStateActorMismatchError) {
+    throw new ClientError(error.message, 'github-install-state-actor-mismatch', {status: 403});
+  }
+  if (error instanceof GithubInstallationNotAuthorizedError) {
+    throw new ClientError(error.message, 'github-installation-not-authorized', {status: 403});
+  }
+  if (error instanceof GithubInstallationAlreadyLinkedError) {
+    throw new ClientError(error.message, 'github-installation-already-linked', {status: 409});
+  }
+  if (error instanceof ConnectionSlugConflictError) {
+    throw new ClientError(error.message, 'slug-conflict', {status: 409});
+  }
+  if (error instanceof GithubIntegrationProviderError) {
+    throw new ClientError(error.message, error.reason, {
+      details: {retry_after_seconds: error.retryAfterSeconds},
+      status: providerStatus(error.reason),
+    });
+  }
+  throw error;
+}