@shipfox/api-integration-gitea 2.0.0

package/src/presentation/routes/webhooks.test.ts

@@ -0,0 +1,188 @@
+import {createHmac, randomUUID} from 'node:crypto';
+import {closeApp, createApp} from '@shipfox/node-fastify';
+import type {FastifyInstance} from 'fastify';
+import {giteaPushPayload} from '#test/index.js';
+import {createGiteaWebhookRoutes} from './webhooks.js';
+
+// Must match GITEA_WEBHOOK_SECRET in test/env.ts.
+const WEBHOOK_SECRET = 'test-webhook-secret';
+
+interface TestApp {
+  app: FastifyInstance;
+  publishSourcePush: ReturnType<typeof vi.fn>;
+  recordDeliveryOnly: ReturnType<typeof vi.fn>;
+  getIntegrationConnectionById: ReturnType<typeof vi.fn>;
+}
+
+async function createTestApp(): Promise<TestApp> {
+  const publishSourcePush = vi.fn(() => Promise.resolve({published: true}));
+  const recordDeliveryOnly = vi.fn(() => Promise.resolve());
+  const getIntegrationConnectionById = vi.fn();
+  const routes = createGiteaWebhookRoutes({
+    coreDb: () =>
+      ({
+        transaction: (fn: (tx: unknown) => Promise<unknown>) => fn({}),
+      }) as never,
+    publishSourcePush,
+    recordDeliveryOnly,
+    getIntegrationConnectionById,
+  });
+  const app = await createApp({routes: [routes], swagger: false});
+  await app.ready();
+  return {app, publishSourcePush, recordDeliveryOnly, getIntegrationConnectionById};
+}
+
+function signedHeaders(rawBody: string, event: string, deliveryId: string) {
+  const signature = createHmac('sha256', WEBHOOK_SECRET).update(rawBody).digest('hex');
+  return {
+    'content-type': 'application/json',
+    'x-gitea-signature': signature,
+    'x-gitea-event': event,
+    'x-gitea-delivery': deliveryId,
+  };
+}
+
+describe('Gitea webhook route', () => {
+  beforeEach(async () => {
+    await closeApp();
+  });
+
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  it('accepts a signed non-push event and records the delivery', async () => {
+    const {app, publishSourcePush, recordDeliveryOnly} = await createTestApp();
+    const deliveryId = randomUUID();
+    const body = JSON.stringify({hello: 'world'});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/gitea',
+      headers: signedHeaders(body, 'create', deliveryId),
+      payload: body,
+    });
+
+    expect(res.statusCode).toBe(204);
+    expect(publishSourcePush).not.toHaveBeenCalled();
+    expect(recordDeliveryOnly).toHaveBeenCalledTimes(1);
+    expect(recordDeliveryOnly.mock.calls[0]?.[0]).toMatchObject({provider: 'gitea', deliveryId});
+  });
+
+  it('rejects an invalid signature with 401 and persists nothing', async () => {
+    const {app, publishSourcePush, recordDeliveryOnly} = await createTestApp();
+    const body = JSON.stringify(
+      giteaPushPayload({
+        owner: 'shipfox',
+        repo: 'api',
+        ref: 'refs/heads/main',
+        defaultBranch: 'main',
+        sha: 'zzz',
+      }),
+    );
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/gitea',
+      headers: {
+        'content-type': 'application/json',
+        'x-gitea-signature': 'deadbeef',
+        'x-gitea-event': 'push',
+        'x-gitea-delivery': randomUUID(),
+      },
+      payload: body,
+    });
+
+    expect(res.statusCode).toBe(401);
+    expect(publishSourcePush).not.toHaveBeenCalled();
+    expect(recordDeliveryOnly).not.toHaveBeenCalled();
+  });
+
+  it('rejects a request missing the delivery header with 400', async () => {
+    const {app} = await createTestApp();
+    const body = JSON.stringify({hello: 'world'});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/gitea',
+      headers: {
+        'content-type': 'application/json',
+        'x-gitea-signature': createHmac('sha256', WEBHOOK_SECRET).update(body).digest('hex'),
+        'x-gitea-event': 'push',
+      },
+      payload: body,
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('rejects a request missing the signature header with 401', async () => {
+    const {app} = await createTestApp();
+    const body = JSON.stringify({hello: 'world'});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/gitea',
+      headers: {
+        'content-type': 'application/json',
+        'x-gitea-event': 'push',
+        'x-gitea-delivery': randomUUID(),
+      },
+      payload: body,
+    });
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('rejects a request missing the event header with 400', async () => {
+    const {app} = await createTestApp();
+    const body = JSON.stringify({hello: 'world'});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/gitea',
+      headers: {
+        'content-type': 'application/json',
+        'x-gitea-signature': createHmac('sha256', WEBHOOK_SECRET).update(body).digest('hex'),
+        'x-gitea-delivery': randomUUID(),
+      },
+      payload: body,
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('rejects malformed JSON after a valid signature with 400', async () => {
+    const {app, publishSourcePush, recordDeliveryOnly} = await createTestApp();
+    const body = '{not valid json';
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/gitea',
+      headers: signedHeaders(body, 'push', randomUUID()),
+      payload: body,
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json()).toMatchObject({error: 'malformed JSON'});
+    expect(publishSourcePush).not.toHaveBeenCalled();
+    expect(recordDeliveryOnly).not.toHaveBeenCalled();
+  });
+
+  it('rejects push payloads that fail schema validation with 400', async () => {
+    const {app, publishSourcePush, recordDeliveryOnly} = await createTestApp();
+    const body = JSON.stringify({ref: 'refs/heads/main'});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/webhooks/integrations/gitea',
+      headers: signedHeaders(body, 'push', randomUUID()),
+      payload: body,
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json()).toMatchObject({error: 'malformed push payload'});
+    expect(publishSourcePush).not.toHaveBeenCalled();
+    expect(recordDeliveryOnly).not.toHaveBeenCalled();
+  });
+});

package/src/presentation/routes/webhooks.ts

@@ -0,0 +1,111 @@
+import {Buffer} from 'node:buffer';
+import type {
+  GetIntegrationConnectionByIdFn,
+  PublishSourcePushFn,
+  RecordDeliveryOnlyFn,
+} from '@shipfox/api-integration-core-dto';
+import {
+  defineRoute,
+  type RouteGroup,
+  rawBodyPlugin,
+  verifyHexHmacSignature,
+  WEBHOOK_BODY_LIMIT,
+} from '@shipfox/node-fastify';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {NodePgDatabase} from 'drizzle-orm/node-postgres';
+import {config} from '#config.js';
+import {
+  GiteaWebhookMalformedJsonError,
+  GiteaWebhookMalformedPushPayloadError,
+  handleGiteaWebhook,
+} from '#core/webhook.js';
+
+const SIGNATURE_HEADER = 'x-gitea-signature';
+const EVENT_HEADER = 'x-gitea-event';
+const DELIVERY_HEADER = 'x-gitea-delivery';
+
+export interface CreateGiteaWebhookRoutesOptions {
+  coreDb: () => NodePgDatabase<Record<string, unknown>>;
+  publishSourcePush: PublishSourcePushFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}
+
+export function createGiteaWebhookRoutes(options: CreateGiteaWebhookRoutesOptions): RouteGroup {
+  const pushRoute = defineRoute({
+    method: 'POST',
+    path: '/',
+    auth: [],
+    description: 'Gitea org webhook receiver.',
+    options: {bodyLimit: WEBHOOK_BODY_LIMIT},
+    handler: async (request, reply) => {
+      const deliveryId = request.headers[DELIVERY_HEADER];
+      const signature = request.headers[SIGNATURE_HEADER];
+      const event = request.headers[EVENT_HEADER];
+
+      if (typeof deliveryId !== 'string' || !deliveryId) {
+        reply.code(400);
+        return {error: 'missing X-Gitea-Delivery header'};
+      }
+      if (typeof signature !== 'string' || !signature) {
+        reply.code(401);
+        return {error: 'missing X-Gitea-Signature header'};
+      }
+      if (typeof event !== 'string' || !event) {
+        reply.code(400);
+        return {error: 'missing X-Gitea-Event header'};
+      }
+
+      const body = request.body;
+      if (!Buffer.isBuffer(body)) {
+        reply.code(400);
+        return {error: 'expected raw JSON body'};
+      }
+      const rawBody = body.toString('utf8');
+
+      if (!verifyHexHmacSignature({rawBody, signature, secret: config.GITEA_WEBHOOK_SECRET})) {
+        reply.code(401);
+        return {error: 'invalid signature'};
+      }
+
+      try {
+        await options.coreDb().transaction(async (tx) => {
+          await handleGiteaWebhook({
+            tx,
+            deliveryId,
+            event,
+            rawBody,
+            publishSourcePush: options.publishSourcePush,
+            recordDeliveryOnly: options.recordDeliveryOnly,
+            getIntegrationConnectionById: options.getIntegrationConnectionById,
+          });
+        });
+      } catch (error) {
+        if (error instanceof GiteaWebhookMalformedJsonError) {
+          logger().warn({deliveryId, err: error}, 'gitea webhook payload JSON parse failed');
+          reply.code(400);
+          return {error: 'malformed JSON'};
+        }
+        if (error instanceof GiteaWebhookMalformedPushPayloadError) {
+          logger().warn(
+            {deliveryId, issues: error.issues},
+            'gitea webhook push payload failed schema validation',
+          );
+          reply.code(400);
+          return {error: 'malformed push payload'};
+        }
+        throw error;
+      }
+
+      reply.code(204);
+      return null;
+    },
+  });
+
+  return {
+    prefix: '/webhooks/integrations/gitea',
+    auth: [],
+    plugins: [rawBodyPlugin],
+    routes: [pushRoute],
+  };
+}

package/test/env.ts

@@ -0,0 +1,11 @@
+process.env.POSTGRES_HOST ??= 'localhost';
+process.env.POSTGRES_PORT ??= '5432';
+process.env.POSTGRES_USERNAME ??= 'shipfox';
+process.env.POSTGRES_PASSWORD ??= 'password';
+process.env.POSTGRES_DATABASE = 'api_test';
+process.env.POSTGRES_MAX_CONNECTIONS ??= '5';
+process.env.TZ = 'UTC';
+process.env.GITEA_BASE_URL = 'https://gitea.example.com';
+process.env.GITEA_SERVICE_USERNAME = 'shipfox-bot';
+process.env.GITEA_SERVICE_TOKEN = 'test-service-token';
+process.env.GITEA_WEBHOOK_SECRET = 'test-webhook-secret';

package/test/factories/gitea-connection.ts

@@ -0,0 +1,19 @@
+import {Factory} from 'fishery';
+import {type GiteaConnection, upsertGiteaConnection} from '#db/connections.js';
+
+export const giteaConnectionFactory = Factory.define<GiteaConnection>(({sequence, onCreate}) => {
+  onCreate((connection) =>
+    upsertGiteaConnection({
+      connectionId: connection.connectionId,
+      org: connection.org,
+    }),
+  );
+
+  return {
+    id: crypto.randomUUID(),
+    connectionId: crypto.randomUUID(),
+    org: `org-${sequence + 1}`,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+});

package/test/factories/index.ts

@@ -0,0 +1 @@
+export {giteaConnectionFactory} from './gitea-connection.js';

package/test/fixtures/gitea-webhook.ts

@@ -0,0 +1,237 @@
+// Real Gitea 1.26.2 push payload fixture; keep extra fields to catch schema drift.
+export const capturedGiteaPushPayload = {
+  ref: 'refs/heads/main',
+  before: '119a2bb6566c3ec17be9b1aaa8090055aa776034',
+  after: 'abd1bff3de1a1f5c375a3e6bd06324469141819e',
+  compare_url:
+    'http://localhost:3000/shipfox/api/compare/119a2bb6566c3ec17be9b1aaa8090055aa776034...abd1bff3de1a1f5c375a3e6bd06324469141819e',
+  commits: [
+    {
+      id: 'abd1bff3de1a1f5c375a3e6bd06324469141819e',
+      message: 'Seed test/handler.test.js\n',
+      url: 'http://localhost:3000/shipfox/api/commit/abd1bff3de1a1f5c375a3e6bd06324469141819e',
+      author: {
+        name: 'gitea-admin',
+        email: 'gitea-admin@shipfox.local',
+        username: 'gitea-admin',
+      },
+      committer: {
+        name: 'gitea-admin',
+        email: 'gitea-admin@shipfox.local',
+        username: 'gitea-admin',
+      },
+      verification: null,
+      timestamp: '2026-06-21T03:08:17Z',
+      added: ['test/handler.test.js'],
+      removed: [],
+      modified: [],
+    },
+  ],
+  total_commits: 1,
+  head_commit: {
+    id: 'abd1bff3de1a1f5c375a3e6bd06324469141819e',
+    message: 'Seed test/handler.test.js\n',
+    url: 'http://localhost:3000/shipfox/api/commit/abd1bff3de1a1f5c375a3e6bd06324469141819e',
+    author: {
+      name: 'gitea-admin',
+      email: 'gitea-admin@shipfox.local',
+      username: 'gitea-admin',
+    },
+    committer: {
+      name: 'gitea-admin',
+      email: 'gitea-admin@shipfox.local',
+      username: 'gitea-admin',
+    },
+    verification: null,
+    timestamp: '2026-06-21T03:08:17Z',
+    added: ['test/handler.test.js'],
+    removed: [],
+    modified: [],
+  },
+  repository: {
+    id: 1,
+    owner: {
+      id: 3,
+      login: 'shipfox',
+      login_name: '',
+      source_id: 0,
+      full_name: '',
+      email: '',
+      avatar_url: 'http://localhost:3000/avatars/d02dc28a1b62136b6e1d5dbc3700c59d',
+      html_url: 'http://localhost:3000/shipfox',
+      language: '',
+      is_admin: false,
+      last_login: '0001-01-01T00:00:00Z',
+      created: '2026-06-21T03:08:17Z',
+      restricted: false,
+      active: false,
+      prohibit_login: false,
+      location: '',
+      website: '',
+      description: '',
+      visibility: 'public',
+      followers_count: 0,
+      following_count: 0,
+      starred_repos_count: 0,
+      username: 'shipfox',
+    },
+    name: 'api',
+    full_name: 'shipfox/api',
+    description: '',
+    empty: false,
+    private: true,
+    fork: false,
+    template: false,
+    mirror: false,
+    size: 23,
+    language: '',
+    languages_url: 'http://localhost:3000/api/v1/repos/shipfox/api/languages',
+    html_url: 'http://localhost:3000/shipfox/api',
+    url: 'http://localhost:3000/api/v1/repos/shipfox/api',
+    link: '',
+    ssh_url: 'ssh://git@localhost:2222/shipfox/api.git',
+    clone_url: 'http://localhost:3000/shipfox/api.git',
+    original_url: '',
+    website: '',
+    stars_count: 0,
+    forks_count: 0,
+    watchers_count: 2,
+    branch_count: 1,
+    open_issues_count: 0,
+    open_pr_counter: 0,
+    release_counter: 0,
+    default_branch: 'main',
+    archived: false,
+    created_at: '2026-06-21T03:08:17Z',
+    updated_at: '2026-06-21T03:08:17Z',
+    archived_at: '1970-01-01T00:00:00Z',
+    permissions: {
+      admin: true,
+      push: true,
+      pull: true,
+    },
+    has_code: true,
+    has_issues: true,
+    internal_tracker: {
+      enable_time_tracker: true,
+      allow_only_contributors_to_track_time: true,
+      enable_issue_dependencies: true,
+    },
+    has_wiki: true,
+    has_pull_requests: true,
+    has_projects: true,
+    projects_mode: 'all',
+    has_releases: true,
+    has_packages: true,
+    has_actions: true,
+    ignore_whitespace_conflicts: false,
+    allow_merge_commits: true,
+    allow_rebase: true,
+    allow_rebase_explicit: true,
+    allow_squash_merge: true,
+    allow_fast_forward_only_merge: true,
+    allow_rebase_update: true,
+    allow_manual_merge: false,
+    autodetect_manual_merge: false,
+    default_delete_branch_after_merge: false,
+    default_merge_style: 'merge',
+    default_allow_maintainer_edit: true,
+    avatar_url: '',
+    internal: false,
+    mirror_interval: '',
+    object_format_name: 'sha1',
+    mirror_updated: '0001-01-01T00:00:00Z',
+    topics: [],
+    licenses: [],
+  },
+  pusher: {
+    id: 1,
+    login: 'gitea-admin',
+    login_name: '',
+    source_id: 0,
+    full_name: '',
+    email: '1+gitea-admin@noreply.localhost',
+    avatar_url: 'http://localhost:3000/avatars/857daf2f94a39d8007c7ac02f123c830',
+    html_url: 'http://localhost:3000/gitea-admin',
+    language: '',
+    is_admin: false,
+    last_login: '0001-01-01T00:00:00Z',
+    created: '2026-06-21T03:08:17Z',
+    restricted: false,
+    active: false,
+    prohibit_login: false,
+    location: '',
+    website: '',
+    description: '',
+    visibility: 'public',
+    followers_count: 0,
+    following_count: 0,
+    starred_repos_count: 0,
+    username: 'gitea-admin',
+  },
+  sender: {
+    id: 1,
+    login: 'gitea-admin',
+    login_name: '',
+    source_id: 0,
+    full_name: '',
+    email: '1+gitea-admin@noreply.localhost',
+    avatar_url: 'http://localhost:3000/avatars/857daf2f94a39d8007c7ac02f123c830',
+    html_url: 'http://localhost:3000/gitea-admin',
+    language: '',
+    is_admin: false,
+    last_login: '0001-01-01T00:00:00Z',
+    created: '2026-06-21T03:08:17Z',
+    restricted: false,
+    active: false,
+    prohibit_login: false,
+    location: '',
+    website: '',
+    description: '',
+    visibility: 'public',
+    followers_count: 0,
+    following_count: 0,
+    starred_repos_count: 0,
+    username: 'gitea-admin',
+  },
+} as const;
+
+export interface GiteaPushPayloadOptions {
+  owner: string;
+  repo: string;
+  ref: string;
+  defaultBranch: string;
+  sha: string;
+}
+
+export function giteaPushPayload(options: GiteaPushPayloadOptions) {
+  const fullName = `${options.owner}/${options.repo}`;
+
+  return {
+    ...capturedGiteaPushPayload,
+    ref: options.ref,
+    after: options.sha,
+    commits: capturedGiteaPushPayload.commits.map((commit) => ({
+      ...commit,
+      id: options.sha,
+      url: `http://localhost:3000/${fullName}/commit/${options.sha}`,
+    })),
+    head_commit: {
+      ...capturedGiteaPushPayload.head_commit,
+      id: options.sha,
+      url: `http://localhost:3000/${fullName}/commit/${options.sha}`,
+    },
+    repository: {
+      ...capturedGiteaPushPayload.repository,
+      name: options.repo,
+      full_name: fullName,
+      default_branch: options.defaultBranch,
+      owner: {
+        ...capturedGiteaPushPayload.repository.owner,
+        login: options.owner,
+        username: options.owner,
+        html_url: `http://localhost:3000/${options.owner}`,
+      },
+    },
+  };
+}

package/test/globalSetup.ts

@@ -0,0 +1,14 @@
+import './env.js';
+import {runMigrations} from '@shipfox/node-drizzle';
+import {closePostgresClient, createPostgresClient} from '@shipfox/node-postgres';
+import {closeDb, db} from '#db/db.js';
+import {migrationsPath} from '#db/migrations.js';
+
+export async function setup() {
+  createPostgresClient();
+
+  await runMigrations(db(), migrationsPath, '__drizzle_migrations_integrations_gitea');
+
+  closeDb();
+  await closePostgresClient();
+}

package/test/index.ts

@@ -0,0 +1,6 @@
+export {giteaConnectionFactory} from './factories/gitea-connection.js';
+export {
+  capturedGiteaPushPayload,
+  type GiteaPushPayloadOptions,
+  giteaPushPayload,
+} from './fixtures/gitea-webhook.js';

package/test/setup.ts

@@ -0,0 +1,17 @@
+import './env.js';
+import {closePostgresClient, createPostgresClient} from '@shipfox/node-postgres';
+import {afterAll, afterEach, beforeAll, vi} from '@shipfox/vitest/vi';
+import {closeDb} from '#db/db.js';
+
+beforeAll(() => {
+  createPostgresClient();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+afterAll(async () => {
+  closeDb();
+  await closePostgresClient();
+});

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@shipfox/ts-config/node",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["**/*.test.tsx", "**/*.test.ts"]
+}