@shipfox/api-integration-gitea 2.0.0

package/src/core/webhook.test.ts

@@ -0,0 +1,396 @@
+import {randomUUID} from 'node:crypto';
+import type {
+  GetIntegrationConnectionByIdFn,
+  IntegrationConnection,
+  PublishSourcePushFn,
+  RecordDeliveryOnlyFn,
+} from '@shipfox/api-integration-core-dto';
+import {db} from '#db/db.js';
+import {giteaConnections} from '#db/schema/connections.js';
+import {capturedGiteaPushPayload, giteaConnectionFactory, giteaPushPayload} from '#test/index.js';
+import {
+  GiteaWebhookMalformedJsonError,
+  GiteaWebhookMalformedPushPayloadError,
+  handleGiteaWebhook,
+} from './webhook.js';
+
+function fakeConnection(overrides: Partial<IntegrationConnection> = {}): IntegrationConnection {
+  return {
+    id: randomUUID(),
+    workspaceId: randomUUID(),
+    provider: 'gitea',
+    externalAccountId: 'shipfox',
+    slug: 'gitea_shipfox',
+    displayName: 'Gitea shipfox',
+    lifecycleStatus: 'active',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+function deps(options: {connection?: IntegrationConnection} = {}) {
+  return {
+    publishSourcePush: vi.fn<PublishSourcePushFn>(() => Promise.resolve({published: true})),
+    recordDeliveryOnly: vi.fn<RecordDeliveryOnlyFn>(() => Promise.resolve()),
+    getIntegrationConnectionById: vi.fn<GetIntegrationConnectionByIdFn>(() =>
+      Promise.resolve(options.connection ?? fakeConnection()),
+    ),
+  };
+}
+
+function firstPublishSourcePushCall(publishSourcePush: {
+  mock: {calls: Array<Parameters<PublishSourcePushFn>>};
+}): Parameters<PublishSourcePushFn>[0] {
+  const [call] = publishSourcePush.mock.calls;
+  if (!call) {
+    throw new Error('Expected publishSourcePush to be called');
+  }
+
+  return call[0];
+}
+
+function firstRecordDeliveryOnlyCall(recordDeliveryOnly: {
+  mock: {calls: Array<Parameters<RecordDeliveryOnlyFn>>};
+}): Parameters<RecordDeliveryOnlyFn>[0] {
+  const [call] = recordDeliveryOnly.mock.calls;
+  if (!call) {
+    throw new Error('Expected recordDeliveryOnly to be called');
+  }
+
+  return call[0];
+}
+
+async function seedConnection(org: string, connectionId?: string): Promise<void> {
+  await giteaConnectionFactory.create({
+    org,
+    ...(connectionId !== undefined && {connectionId}),
+  });
+}
+
+describe('handleGiteaWebhook', () => {
+  beforeEach(async () => {
+    await db().delete(giteaConnections);
+  });
+
+  it('publishes a mapped event for a valid push from a connected org', async () => {
+    const connection = fakeConnection();
+    await seedConnection('shipfox', connection.id);
+    const deliveryId = randomUUID();
+    const handlers = deps({connection});
+    const payload = giteaPushPayload({
+      owner: 'shipfox',
+      repo: 'api',
+      ref: 'refs/heads/main',
+      defaultBranch: 'main',
+      sha: 'abc123',
+    });
+    const rawBody = JSON.stringify(payload);
+
+    const result = await handleGiteaWebhook({
+      tx: db(),
+      deliveryId,
+      event: 'push',
+      rawBody,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('published');
+    expect(handlers.recordDeliveryOnly).not.toHaveBeenCalled();
+    expect(handlers.getIntegrationConnectionById).toHaveBeenCalledTimes(1);
+    expect(handlers.getIntegrationConnectionById).toHaveBeenCalledWith(
+      connection.id,
+      expect.objectContaining({tx: expect.anything()}),
+    );
+    expect(handlers.publishSourcePush).toHaveBeenCalledTimes(1);
+    const call = firstPublishSourcePushCall(handlers.publishSourcePush);
+    expect(call.tx).toBeDefined();
+    expect(call).toMatchObject({
+      provider: 'gitea',
+      source: connection.slug,
+      deliveryId,
+      workspaceId: connection.workspaceId,
+      connectionId: connection.id,
+      connectionName: connection.displayName,
+      rawPayload: payload,
+      push: {
+        externalRepositoryId: 'gitea:shipfox/api',
+        ref: 'main',
+        headCommitSha: 'abc123',
+        isDefaultBranch: true,
+      },
+    });
+  });
+
+  it('accepts the captured local Gitea push payload shape', async () => {
+    const connection = fakeConnection();
+    await seedConnection('shipfox', connection.id);
+    const handlers = deps({connection});
+    const deliveryId = randomUUID();
+
+    const result = await handleGiteaWebhook({
+      tx: db(),
+      deliveryId,
+      event: 'push',
+      rawBody: JSON.stringify(capturedGiteaPushPayload),
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('published');
+    expect(handlers.publishSourcePush).toHaveBeenCalledTimes(1);
+    expect(firstPublishSourcePushCall(handlers.publishSourcePush)).toMatchObject({
+      provider: 'gitea',
+      source: connection.slug,
+      deliveryId,
+      workspaceId: connection.workspaceId,
+      connectionId: connection.id,
+      rawPayload: capturedGiteaPushPayload,
+      push: {
+        externalRepositoryId: 'gitea:shipfox/api',
+        ref: 'main',
+        headCommitSha: capturedGiteaPushPayload.after,
+        defaultBranch: 'main',
+        isDefaultBranch: true,
+      },
+    });
+  });
+
+  it('publishes with isDefaultBranch=false when ref is not the default branch', async () => {
+    await seedConnection('shipfox');
+    const handlers = deps();
+    const rawBody = JSON.stringify(
+      giteaPushPayload({
+        owner: 'shipfox',
+        repo: 'api',
+        ref: 'refs/heads/feature/x',
+        defaultBranch: 'main',
+        sha: 'feat1',
+      }),
+    );
+
+    const result = await handleGiteaWebhook({
+      tx: db(),
+      deliveryId: randomUUID(),
+      event: 'push',
+      rawBody,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('published');
+    expect(handlers.publishSourcePush).toHaveBeenCalledTimes(1);
+    expect(firstPublishSourcePushCall(handlers.publishSourcePush).push).toMatchObject({
+      ref: 'feature/x',
+      isDefaultBranch: false,
+    });
+  });
+
+  it('resolves a mixed-case owner against the lower-cased stored org', async () => {
+    const connection = fakeConnection();
+    await seedConnection('shipfox', connection.id);
+    const handlers = deps({connection});
+    const rawBody = JSON.stringify(
+      giteaPushPayload({
+        owner: 'ShipFox',
+        repo: 'API',
+        ref: 'refs/heads/main',
+        defaultBranch: 'main',
+        sha: 'casing',
+      }),
+    );
+
+    const result = await handleGiteaWebhook({
+      tx: db(),
+      deliveryId: randomUUID(),
+      event: 'push',
+      rawBody,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('published');
+    expect(handlers.publishSourcePush).toHaveBeenCalledTimes(1);
+    // Repo id keeps the payload's verbatim casing to match the source-control adapter.
+    expect(firstPublishSourcePushCall(handlers.publishSourcePush).push.externalRepositoryId).toBe(
+      'gitea:ShipFox/API',
+    );
+  });
+
+  it('ignores a branch deletion without publishing', async () => {
+    const connection = fakeConnection();
+    await seedConnection('shipfox', connection.id);
+    const handlers = deps({connection});
+    const rawBody = JSON.stringify(
+      giteaPushPayload({
+        owner: 'shipfox',
+        repo: 'api',
+        ref: 'refs/heads/main',
+        defaultBranch: 'main',
+        sha: '0000000000000000000000000000000000000000',
+      }),
+    );
+
+    const result = await handleGiteaWebhook({
+      tx: db(),
+      deliveryId: randomUUID(),
+      event: 'push',
+      rawBody,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('deleted');
+    expect(handlers.publishSourcePush).not.toHaveBeenCalled();
+    expect(handlers.recordDeliveryOnly).not.toHaveBeenCalled();
+  });
+
+  it('records the delivery only for non-push events', async () => {
+    const handlers = deps();
+    const deliveryId = randomUUID();
+
+    const result = await handleGiteaWebhook({
+      tx: db(),
+      deliveryId,
+      event: 'create',
+      rawBody: JSON.stringify({hello: 'world'}),
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('recorded-only');
+    expect(handlers.publishSourcePush).not.toHaveBeenCalled();
+    expect(handlers.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+    expect(firstRecordDeliveryOnlyCall(handlers.recordDeliveryOnly)).toMatchObject({
+      provider: 'gitea',
+      deliveryId,
+    });
+  });
+
+  it('records the delivery only for pushes from an unknown org', async () => {
+    const handlers = deps();
+    const deliveryId = randomUUID();
+    const rawBody = JSON.stringify(
+      giteaPushPayload({
+        owner: 'ghost',
+        repo: 'api',
+        ref: 'refs/heads/main',
+        defaultBranch: 'main',
+        sha: 'orphan',
+      }),
+    );
+
+    const result = await handleGiteaWebhook({
+      tx: db(),
+      deliveryId,
+      event: 'push',
+      rawBody,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('unknown-org');
+    expect(handlers.publishSourcePush).not.toHaveBeenCalled();
+    expect(handlers.getIntegrationConnectionById).not.toHaveBeenCalled();
+    expect(handlers.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+    expect(firstRecordDeliveryOnlyCall(handlers.recordDeliveryOnly)).toMatchObject({
+      provider: 'gitea',
+      deliveryId,
+    });
+  });
+
+  it('records the delivery only when the org has no core connection', async () => {
+    const handlers = deps();
+    handlers.getIntegrationConnectionById.mockResolvedValue(undefined);
+    await seedConnection('shipfox');
+    const deliveryId = randomUUID();
+    const rawBody = JSON.stringify(
+      giteaPushPayload({
+        owner: 'shipfox',
+        repo: 'api',
+        ref: 'refs/heads/main',
+        defaultBranch: 'main',
+        sha: 'dangling',
+      }),
+    );
+
+    const result = await handleGiteaWebhook({
+      tx: db(),
+      deliveryId,
+      event: 'push',
+      rawBody,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('unknown-org');
+    expect(handlers.getIntegrationConnectionById).toHaveBeenCalledTimes(1);
+    expect(handlers.publishSourcePush).not.toHaveBeenCalled();
+    expect(handlers.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+    expect(firstRecordDeliveryOnlyCall(handlers.recordDeliveryOnly)).toMatchObject({
+      provider: 'gitea',
+      deliveryId,
+    });
+  });
+
+  it.each([
+    'disabled',
+    'error',
+  ] as const)('records the delivery only when the connection is %s', async (lifecycleStatus) => {
+    const connection = fakeConnection({lifecycleStatus});
+    await seedConnection('shipfox', connection.id);
+    const handlers = deps({connection});
+    const deliveryId = randomUUID();
+    const rawBody = JSON.stringify(
+      giteaPushPayload({
+        owner: 'shipfox',
+        repo: 'api',
+        ref: 'refs/heads/main',
+        defaultBranch: 'main',
+        sha: 'inactive',
+      }),
+    );
+
+    const result = await handleGiteaWebhook({
+      tx: db(),
+      deliveryId,
+      event: 'push',
+      rawBody,
+      ...handlers,
+    });
+
+    expect(result.outcome).toBe('inactive-connection');
+    expect(handlers.getIntegrationConnectionById).toHaveBeenCalledTimes(1);
+    expect(handlers.publishSourcePush).not.toHaveBeenCalled();
+    expect(handlers.recordDeliveryOnly).toHaveBeenCalledTimes(1);
+    expect(firstRecordDeliveryOnlyCall(handlers.recordDeliveryOnly)).toMatchObject({
+      provider: 'gitea',
+      deliveryId,
+    });
+  });
+
+  it('rejects malformed JSON', async () => {
+    const handlers = deps();
+
+    const result = handleGiteaWebhook({
+      tx: db(),
+      deliveryId: randomUUID(),
+      event: 'push',
+      rawBody: '{not valid json',
+      ...handlers,
+    });
+
+    await expect(result).rejects.toBeInstanceOf(GiteaWebhookMalformedJsonError);
+    expect(handlers.publishSourcePush).not.toHaveBeenCalled();
+    expect(handlers.recordDeliveryOnly).not.toHaveBeenCalled();
+  });
+
+  it('rejects push payloads that fail schema validation', async () => {
+    const handlers = deps();
+
+    const result = handleGiteaWebhook({
+      tx: db(),
+      deliveryId: randomUUID(),
+      event: 'push',
+      rawBody: JSON.stringify({ref: 'refs/heads/main'}),
+      ...handlers,
+    });
+
+    await expect(result).rejects.toBeInstanceOf(GiteaWebhookMalformedPushPayloadError);
+    expect(handlers.publishSourcePush).not.toHaveBeenCalled();
+    expect(handlers.recordDeliveryOnly).not.toHaveBeenCalled();
+  });
+});

package/src/core/webhook.ts

@@ -0,0 +1,203 @@
+import {
+  buildProviderRepositoryId,
+  type GetIntegrationConnectionByIdFn,
+  type IntegrationTx,
+  type PublishSourcePushFn,
+  type RecordDeliveryOnlyFn,
+  type SourcePushPayload,
+} from '@shipfox/api-integration-core-dto';
+import {
+  type GiteaPushPayloadDto,
+  giteaProviderKind,
+  giteaPushPayloadSchema,
+} from '@shipfox/api-integration-gitea-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import {getGiteaConnectionByOrg} from '#db/connections.js';
+
+const REFS_HEADS_PREFIX = 'refs/heads/';
+// Gitea sends a `push` webhook for a branch deletion with `after` set to this all-zero SHA.
+const DELETED_BRANCH_SHA = '0'.repeat(40);
+
+export class GiteaWebhookMalformedJsonError extends Error {
+  constructor(options: {cause: unknown}) {
+    super('Gitea webhook payload is not valid JSON', {cause: options.cause});
+    this.name = 'GiteaWebhookMalformedJsonError';
+  }
+}
+
+export class GiteaWebhookMalformedPushPayloadError extends Error {
+  constructor(public readonly issues: unknown) {
+    super('Gitea webhook push payload failed schema validation');
+    this.name = 'GiteaWebhookMalformedPushPayloadError';
+  }
+}
+
+export interface HandleGiteaWebhookParams {
+  tx: IntegrationTx;
+  deliveryId: string;
+  event: string;
+  rawBody: string;
+  publishSourcePush: PublishSourcePushFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}
+
+export interface HandleGiteaPushParams {
+  tx: IntegrationTx;
+  deliveryId: string;
+  payload: GiteaPushPayloadDto;
+  rawPayload: unknown;
+  publishSourcePush: PublishSourcePushFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}
+
+export type HandleGiteaPushOutcome =
+  | 'published'
+  | 'duplicate'
+  | 'deleted'
+  | 'unknown-org'
+  | 'inactive-connection';
+export type HandleGiteaWebhookOutcome = HandleGiteaPushOutcome | 'recorded-only';
+
+function isBranchDeletion(after: string): boolean {
+  return after === DELETED_BRANCH_SHA;
+}
+
+export async function handleGiteaWebhook(
+  params: HandleGiteaWebhookParams,
+): Promise<{outcome: HandleGiteaWebhookOutcome}> {
+  if (params.event !== 'push') {
+    await params.recordDeliveryOnly({
+      tx: params.tx,
+      provider: giteaProviderKind,
+      deliveryId: params.deliveryId,
+    });
+    return {outcome: 'recorded-only'};
+  }
+
+  const {payload, rawPayload} = parseGiteaPushPayload(params.rawBody);
+  return handleGiteaPush({
+    tx: params.tx,
+    deliveryId: params.deliveryId,
+    payload,
+    rawPayload,
+    publishSourcePush: params.publishSourcePush,
+    recordDeliveryOnly: params.recordDeliveryOnly,
+    getIntegrationConnectionById: params.getIntegrationConnectionById,
+  });
+}
+
+export async function handleGiteaPush(
+  params: HandleGiteaPushParams,
+): Promise<{outcome: HandleGiteaPushOutcome}> {
+  // Dropping deletes before `publishSourcePush` avoids project and trigger fan-out.
+  if (isBranchDeletion(params.payload.after)) {
+    return {outcome: 'deleted'};
+  }
+
+  const owner = params.payload.repository.owner.username;
+  // Gitea org routes are case-insensitive, and the connect flow stores them lower-cased.
+  const giteaConnection = await getGiteaConnectionByOrg(owner.toLowerCase(), {tx: params.tx});
+  if (!giteaConnection) {
+    logger().warn(
+      {deliveryId: params.deliveryId, org: owner},
+      'gitea webhook: unknown org, dropping',
+    );
+    await params.recordDeliveryOnly({
+      tx: params.tx,
+      provider: giteaProviderKind,
+      deliveryId: params.deliveryId,
+    });
+    return {outcome: 'unknown-org'};
+  }
+
+  const connection = await params.getIntegrationConnectionById(giteaConnection.connectionId, {
+    tx: params.tx,
+  });
+  if (!connection) {
+    logger().warn(
+      {deliveryId: params.deliveryId, org: owner, connectionId: giteaConnection.connectionId},
+      'gitea webhook: org has no connection, dropping',
+    );
+    await params.recordDeliveryOnly({
+      tx: params.tx,
+      provider: giteaProviderKind,
+      deliveryId: params.deliveryId,
+    });
+    return {outcome: 'unknown-org'};
+  }
+
+  if (connection.lifecycleStatus !== 'active') {
+    const logContext = {
+      deliveryId: params.deliveryId,
+      org: owner,
+      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, 'gitea webhook: connection in error state, dropping');
+    } else {
+      logger().info(logContext, 'gitea webhook: connection disabled, dropping');
+    }
+    await params.recordDeliveryOnly({
+      tx: params.tx,
+      provider: giteaProviderKind,
+      deliveryId: params.deliveryId,
+    });
+    return {outcome: 'inactive-connection'};
+  }
+
+  const ref = stripRefsHeads(params.payload.ref);
+  const defaultBranch = params.payload.repository.default_branch;
+  const push: SourcePushPayload = {
+    // Match the source-control adapter's owner/name repository id.
+    externalRepositoryId: buildProviderRepositoryId(
+      giteaProviderKind,
+      `${owner}/${params.payload.repository.name}`,
+    ),
+    ref,
+    headCommitSha: params.payload.after,
+    defaultBranch,
+    isDefaultBranch: ref === defaultBranch,
+  };
+  const result = await params.publishSourcePush({
+    tx: params.tx,
+    provider: giteaProviderKind,
+    source: connection.slug,
+    workspaceId: connection.workspaceId,
+    connectionId: connection.id,
+    connectionName: connection.displayName,
+    deliveryId: params.deliveryId,
+    receivedAt: new Date().toISOString(),
+    rawPayload: params.rawPayload,
+    push,
+  });
+
+  return {outcome: result.published ? 'published' : 'duplicate'};
+}
+
+function stripRefsHeads(ref: string): string {
+  return ref.startsWith(REFS_HEADS_PREFIX) ? ref.slice(REFS_HEADS_PREFIX.length) : ref;
+}
+
+function parseGiteaPushPayload(rawBody: string): {
+  payload: GiteaPushPayloadDto;
+  rawPayload: unknown;
+} {
+  let parsedJson: unknown;
+  try {
+    parsedJson = JSON.parse(rawBody);
+  } catch (error) {
+    throw new GiteaWebhookMalformedJsonError({cause: error});
+  }
+
+  const validated = giteaPushPayloadSchema.safeParse(parsedJson);
+  if (!validated.success) {
+    throw new GiteaWebhookMalformedPushPayloadError(validated.error.issues);
+  }
+
+  return {payload: validated.data, rawPayload: parsedJson};
+}

package/src/db/connections.test.ts

@@ -0,0 +1,69 @@
+import {randomUUID} from 'node:crypto';
+import {GiteaOrgAlreadyLinkedError} from '#core/errors.js';
+import {
+  getGiteaConnectionByConnectionId,
+  getGiteaConnectionByOrg,
+  type UpsertGiteaConnectionParams,
+  upsertGiteaConnection,
+} from './connections.js';
+import {db} from './db.js';
+import {giteaConnections} from './schema/connections.js';
+
+function connectionParams(
+  overrides: Partial<UpsertGiteaConnectionParams> = {},
+): UpsertGiteaConnectionParams {
+  return {
+    connectionId: randomUUID(),
+    org: `org-${Math.floor(Math.random() * 1_000_000)}`,
+    ...overrides,
+  };
+}
+
+describe('gitea connections persistence', () => {
+  beforeEach(async () => {
+    await db().delete(giteaConnections);
+  });
+
+  test('upsert updates in place when the same connection reconnects, without duplicating', async () => {
+    const org = `org-${Date.now()}`;
+    const connectionId = randomUUID();
+    await upsertGiteaConnection(connectionParams({connectionId, org}));
+
+    const updated = await upsertGiteaConnection(connectionParams({connectionId, org}));
+
+    expect(updated.connectionId).toBe(connectionId);
+    const fetched = await getGiteaConnectionByOrg(org);
+    expect(fetched?.connectionId).toBe(connectionId);
+  });
+
+  test('upsert rejects linking an org already owned by another connection (TOCTOU guard)', async () => {
+    const org = `org-${Date.now()}`;
+    const firstConnectionId = randomUUID();
+    const secondConnectionId = randomUUID();
+    await upsertGiteaConnection(connectionParams({connectionId: firstConnectionId, org}));
+
+    const takeover = upsertGiteaConnection(
+      connectionParams({connectionId: secondConnectionId, org}),
+    );
+
+    await expect(takeover).rejects.toBeInstanceOf(GiteaOrgAlreadyLinkedError);
+    const fetched = await getGiteaConnectionByOrg(org);
+    expect(fetched?.connectionId).toBe(firstConnectionId);
+  });
+
+  test('getGiteaConnectionByConnectionId returns the row for a known connection', async () => {
+    const connectionId = randomUUID();
+    const org = `org-${Date.now()}`;
+    await upsertGiteaConnection(connectionParams({connectionId, org}));
+
+    const fetched = await getGiteaConnectionByConnectionId(connectionId);
+
+    expect(fetched?.org).toBe(org);
+  });
+
+  test('getGiteaConnectionByOrg returns undefined for a miss', async () => {
+    const result = await getGiteaConnectionByOrg('missing');
+
+    expect(result).toBeUndefined();
+  });
+});