@ftisindia/create-app 0.1.5 → 0.2.0

package/template/test/forms-outbox.e2e-spec.ts

@@ -0,0 +1,570 @@
+import { INestApplication, ValidationPipe } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+import { ActionRegistry, OutboxHandlerRegistry } from '@ftisindia/form-builder';
+import type { EngineTx } from '@ftisindia/form-builder';
+import request from 'supertest';
+import { HttpExceptionFilter } from '../src/common/filters/http-exception.filter';
+import { PrismaService } from '../src/database/prisma/prisma.service';
+import { AuditService } from '../src/modules/audit/application/services/audit.service';
+import { OutboxDispatcherService } from '../src/modules/forms/application/services/outbox-dispatcher.service';
+import { PrismaOutboxStore } from '../src/modules/forms/infrastructure/stores/prisma-outbox.store';
+
+describe('Forms transactional outbox (e2e)', () => {
+  let app: INestApplication;
+  let prisma: PrismaService;
+  let dispatcher: OutboxDispatcherService;
+  let outboxStore: PrismaOutboxStore;
+  let owner: { accessToken: string; userId: string; orgId: string };
+
+  beforeAll(async () => {
+    process.env.DATABASE_URL = process.env.TEST_DATABASE_URL ?? process.env.DATABASE_URL;
+    process.env.JWT_SECRET ||= 'test-jwt-secret-at-least-16-chars';
+    process.env.AUTH_GOOGLE_ENABLED ||= 'false';
+    process.env.AUTH_EMAIL_PASSWORD_ENABLED ||= 'true';
+    process.env.NODE_ENV = 'test';
+    process.env.FORMS_OUTBOX_ENABLED = 'false';
+    process.env.FORMS_OUTBOX_HEARTBEAT_MS = '25';
+    process.env.FORMS_FILE_STORAGE_DIR = './var/test-uploads';
+
+    const { AppModule } = await import('../src/app.module');
+    const moduleRef = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleRef.createNestApplication();
+    app.useGlobalFilters(new HttpExceptionFilter());
+    app.useGlobalPipes(
+      new ValidationPipe({
+        forbidNonWhitelisted: true,
+        transform: true,
+        whitelist: true,
+      }),
+    );
+    await app.init();
+    prisma = app.get(PrismaService);
+    dispatcher = app.get(OutboxDispatcherService);
+    outboxStore = app.get(PrismaOutboxStore);
+
+    // Test-only extensions: a handler type that always throws, and a
+    // post-commit action that enqueues a job for it with a tight retry budget.
+    app.get(OutboxHandlerRegistry).register({
+      type: 'boom',
+      handle: () => {
+        return Promise.reject(new Error('boom handler failure'));
+      },
+    });
+    app.get(OutboxHandlerRegistry).register({
+      type: 'slow-heartbeat',
+      handle: () => new Promise((resolve) => setTimeout(resolve, 90)),
+    });
+    app.get(ActionRegistry).register({
+      name: 'enqueueBoom',
+      kind: 'post-commit',
+      execute: async (ctx) => {
+        await ctx.enqueue({ type: 'boom', payload: {}, maxAttempts: 2 });
+        return { queued: true };
+      },
+    });
+
+    // Park stray PENDING jobs left by earlier suites/runs so runOnce() cycles
+    // in this suite deterministically claim the jobs created here (the claim
+    // batch is ordered oldest-first and capped).
+    await prisma.formOutboxJob.updateMany({
+      where: { status: { in: ['PENDING', 'PROCESSING'] } },
+      data: {
+        status: 'FAILED',
+        claimedBy: null,
+        lastError: 'parked by forms-outbox e2e setup',
+      },
+    });
+
+    owner = await createUserAndOrg('outbox-owner');
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('enqueues atomically with the submission and delivers via runOnce()', async () => {
+    const key = await publishDefinition(registrationDefinition(uniqueFormKey('outbox-email')));
+
+    const response = await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms/${key}/submissions`)
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .send({
+        mode: 'submit',
+        data: {
+          fullName: 'Outbox Tester',
+          email: 'outbox@example.com',
+          ticketType: 'standard',
+        },
+      })
+      .expect(200);
+
+    const submissionId = response.body.submissionId as string;
+    expect(submissionId).toBeTruthy();
+
+    const job = await prisma.formOutboxJob.findFirst({
+      where: { idempotencyKey: { contains: submissionId } },
+    });
+    expect(job).not.toBeNull();
+    expect(job?.status).toBe('PENDING');
+    expect(job?.type).toBe('email');
+
+    await dispatcher.runOnce();
+
+    const delivered = await prisma.formOutboxJob.findUnique({
+      where: { id: job!.id },
+    });
+    expect(delivered?.status).toBe('DONE');
+    expect(delivered?.claimedBy).toBeNull();
+
+    const auditRow = await prisma.auditLog.findFirst({
+      where: { action: 'forms.outbox.delivered', targetId: job!.id },
+    });
+    expect(auditRow).not.toBeNull();
+    expect(auditRow?.orgId).toBe(owner.orgId);
+  });
+
+  it('retries a failing handler with backoff, then parks the job at maxAttempts', async () => {
+    const key = uniqueFormKey('outbox-boom');
+    await publishDefinition({
+      ...registrationDefinition(key),
+      actions: {
+        submit: ['validateAll', 'persist', 'enqueueBoom'],
+        saveDraft: ['persistDraft'],
+      },
+    });
+
+    const response = await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms/${key}/submissions`)
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .send({
+        mode: 'submit',
+        data: {
+          fullName: 'Boom Tester',
+          email: 'boom@example.com',
+          ticketType: 'vip',
+        },
+      })
+      .expect(200);
+
+    const submissionId = response.body.submissionId as string;
+    const job = await prisma.formOutboxJob.findFirst({
+      where: { type: 'boom', idempotencyKey: { contains: submissionId } },
+    });
+    expect(job).not.toBeNull();
+    expect(job?.maxAttempts).toBe(2);
+
+    // First attempt fails -> retried: back to PENDING with a future runAfter.
+    await dispatcher.runOnce();
+    const retried = await prisma.formOutboxJob.findUnique({
+      where: { id: job!.id },
+    });
+    expect(retried?.status).toBe('PENDING');
+    expect(retried?.claimedBy).toBeNull();
+    expect(retried?.attempts).toBe(1);
+    expect(retried?.runAfter).not.toBeNull();
+    expect(retried!.runAfter!.getTime()).toBeGreaterThan(Date.now());
+
+    // Make the retry due, then fail again -> parked as FAILED at maxAttempts.
+    await prisma.formOutboxJob.update({
+      where: { id: job!.id },
+      data: { runAfter: new Date(Date.now() - 1000) },
+    });
+    await dispatcher.runOnce();
+
+    const parked = await prisma.formOutboxJob.findUnique({
+      where: { id: job!.id },
+    });
+    expect(parked?.status).toBe('FAILED');
+    expect(parked?.claimedBy).toBeNull();
+    expect(parked?.attempts).toBe(2);
+  });
+
+  it('fails immediately when no handler is registered for the job type', async () => {
+    const orphan = await prisma.formOutboxJob.create({
+      data: {
+        type: `no-handler-${uniqueSuffix()}`,
+        payload: {},
+        status: 'PENDING',
+        attempts: 0,
+        maxAttempts: 5,
+      },
+    });
+
+    await dispatcher.runOnce();
+
+    const failed = await prisma.formOutboxJob.findUnique({
+      where: { id: orphan.id },
+    });
+    expect(failed?.status).toBe('FAILED');
+    expect(failed?.claimedBy).toBeNull();
+    expect(failed?.attempts).toBe(1);
+    expect(failed?.lastError).toMatch(/No handler registered/);
+  });
+
+  it('does not retry a delivered job when the success audit write fails', async () => {
+    const job = await prisma.formOutboxJob.create({
+      data: {
+        type: 'email',
+        payload: { to: 'audit-failure@example.com', template: 'test' },
+        status: 'PENDING',
+        attempts: 0,
+        maxAttempts: 3,
+        orgId: owner.orgId,
+        actorUserId: owner.userId,
+      },
+    });
+    const audit = app.get(AuditService);
+    const spy = jest.spyOn(audit, 'write').mockRejectedValueOnce(new Error('audit down'));
+
+    await dispatcher.runOnce();
+
+    const delivered = await prisma.formOutboxJob.findUnique({
+      where: { id: job.id },
+    });
+    expect(delivered?.status).toBe('DONE');
+    expect(delivered?.claimedBy).toBeNull();
+    expect(delivered?.attempts).toBe(0);
+    expect(delivered?.lastError).toBeNull();
+    spy.mockRestore();
+  });
+
+  it('reclaims stale PROCESSING jobs', async () => {
+    const staleTime = new Date(Date.now() - 10 * 60 * 1000);
+    const job = await prisma.formOutboxJob.create({
+      data: {
+        type: 'email',
+        payload: { to: 'stale@example.com', template: 'test' },
+        status: 'PROCESSING',
+        attempts: 0,
+        maxAttempts: 3,
+        orgId: owner.orgId,
+        actorUserId: owner.userId,
+        claimedBy: 'old-stale-claim',
+        createdAt: staleTime,
+        updatedAt: staleTime,
+      },
+    });
+
+    await dispatcher.runOnce();
+
+    const delivered = await prisma.formOutboxJob.findUnique({
+      where: { id: job.id },
+    });
+    expect(delivered?.status).toBe('DONE');
+    expect(delivered?.claimedBy).toBeNull();
+  });
+
+  // ── Helpers ────────────────────────────────────────────────────────────────
+
+  it('treats duplicate idempotency keys as enqueue no-ops', async () => {
+    const idempotencyKey = `dupe-${uniqueSuffix()}`;
+    await prisma.$transaction(async (tx) => {
+      const engineTx = tx as unknown as EngineTx;
+      await outboxStore.enqueue(
+        {
+          type: 'email',
+          payload: { to: 'dupe@example.com', template: 'test' },
+          idempotencyKey,
+          orgId: owner.orgId,
+          actorUserId: owner.userId,
+        },
+        engineTx,
+      );
+      await outboxStore.enqueue(
+        {
+          type: 'email',
+          payload: { to: 'dupe@example.com', template: 'test' },
+          idempotencyKey,
+          orgId: owner.orgId,
+          actorUserId: owner.userId,
+        },
+        engineTx,
+      );
+    });
+
+    await expect(prisma.formOutboxJob.count({ where: { idempotencyKey } })).resolves.toBe(1);
+    await prisma.formOutboxJob.updateMany({
+      where: { idempotencyKey },
+      data: {
+        status: 'FAILED',
+        claimedBy: null,
+        lastError: 'parked after duplicate idempotency test',
+      },
+    });
+  });
+
+  it('heartbeat keeps active PROCESSING jobs from stale reclaim', async () => {
+    const claimedBy = `heartbeat-${uniqueSuffix()}`;
+    const staleTime = new Date(Date.now() - 10 * 60 * 1000);
+    const job = await prisma.formOutboxJob.create({
+      data: {
+        type: 'email',
+        payload: { to: 'heartbeat@example.com', template: 'test' },
+        status: 'PROCESSING',
+        attempts: 0,
+        maxAttempts: 3,
+        orgId: owner.orgId,
+        actorUserId: owner.userId,
+        claimedBy,
+        createdAt: staleTime,
+        updatedAt: staleTime,
+      },
+    });
+
+    await expect(outboxStore.touchProcessing(job.id, claimedBy)).resolves.toBe(true);
+
+    const claimed = await outboxStore.claimDue(new Date(), 10);
+    expect(claimed.some((claimedJob) => claimedJob.id === job.id)).toBe(false);
+  });
+
+  it('guards terminal transitions with the claim token', async () => {
+    const jobs = await Promise.all(
+      ['done', 'retry', 'failed'].map((label) =>
+        prisma.formOutboxJob.create({
+          data: {
+            type: 'email',
+            payload: { to: `${label}@example.com`, template: 'test' },
+            status: 'PENDING',
+            attempts: 0,
+            maxAttempts: 3,
+            orgId: owner.orgId,
+            actorUserId: owner.userId,
+          },
+        }),
+      ),
+    );
+
+    const claimed = await outboxStore.claimDue(new Date(), 3);
+    expect(claimed).toHaveLength(3);
+    for (const job of claimed) {
+      expect(job.claimedBy).toEqual(expect.any(String));
+    }
+
+    const byId = new Map(claimed.map((job) => [job.id, job]));
+    const done = byId.get(jobs[0]!.id)!;
+    const retry = byId.get(jobs[1]!.id)!;
+    const failed = byId.get(jobs[2]!.id)!;
+
+    await expect(outboxStore.markDone(done.id, 'wrong-token')).resolves.toBe(false);
+    await expect(
+      outboxStore.markRetry(
+        retry.id,
+        'wrong-token',
+        1,
+        new Date(Date.now() + 30_000),
+        'retry later',
+      ),
+    ).resolves.toBe(false);
+    await expect(outboxStore.markFailed(failed.id, 'wrong-token', 1, 'failed')).resolves.toBe(
+      false,
+    );
+
+    await expect(outboxStore.markDone(done.id, done.claimedBy!)).resolves.toBe(true);
+    await expect(
+      outboxStore.markRetry(
+        retry.id,
+        retry.claimedBy!,
+        1,
+        new Date(Date.now() + 30_000),
+        'retry later',
+      ),
+    ).resolves.toBe(true);
+    await expect(outboxStore.markFailed(failed.id, failed.claimedBy!, 1, 'failed')).resolves.toBe(
+      true,
+    );
+
+    await expect(prisma.formOutboxJob.findUnique({ where: { id: done.id } })).resolves.toMatchObject(
+      { status: 'DONE', claimedBy: null },
+    );
+    await expect(
+      prisma.formOutboxJob.findUnique({ where: { id: retry.id } }),
+    ).resolves.toMatchObject({ status: 'PENDING', claimedBy: null, attempts: 1 });
+    await expect(
+      prisma.formOutboxJob.findUnique({ where: { id: failed.id } }),
+    ).resolves.toMatchObject({ status: 'FAILED', claimedBy: null, attempts: 1 });
+  });
+
+  it('prevents an old worker token from settling a reclaimed stale job', async () => {
+    const staleTime = new Date(Date.now() - 10 * 60 * 1000);
+    const job = await prisma.formOutboxJob.create({
+      data: {
+        type: 'email',
+        payload: { to: 'reclaimed@example.com', template: 'test' },
+        status: 'PROCESSING',
+        attempts: 0,
+        maxAttempts: 3,
+        orgId: owner.orgId,
+        actorUserId: owner.userId,
+        claimedBy: 'old-worker',
+        createdAt: staleTime,
+        updatedAt: staleTime,
+      },
+    });
+
+    const claimed = await outboxStore.claimDue(new Date(), 1);
+    expect(claimed).toHaveLength(1);
+    expect(claimed[0]!.id).toBe(job.id);
+    expect(claimed[0]!.claimedBy).not.toBe('old-worker');
+
+    await expect(outboxStore.markDone(job.id, 'old-worker')).resolves.toBe(false);
+    await expect(outboxStore.markDone(job.id, claimed[0]!.claimedBy!)).resolves.toBe(true);
+    await expect(prisma.formOutboxJob.findUnique({ where: { id: job.id } })).resolves.toMatchObject(
+      { status: 'DONE', claimedBy: null },
+    );
+  });
+
+  it('heartbeats through the dispatcher while a handler is still running', async () => {
+    const job = await prisma.formOutboxJob.create({
+      data: {
+        type: 'slow-heartbeat',
+        payload: {},
+        status: 'PENDING',
+        attempts: 0,
+        maxAttempts: 3,
+        orgId: owner.orgId,
+        actorUserId: owner.userId,
+      },
+    });
+    const heartbeat = jest.spyOn(outboxStore, 'touchProcessing');
+
+    await dispatcher.runOnce();
+
+    expect(heartbeat).toHaveBeenCalled();
+    expect(heartbeat.mock.calls.some(([id, claimedBy]) => id === job.id && claimedBy)).toBe(true);
+    const delivered = await prisma.formOutboxJob.findUnique({ where: { id: job.id } });
+    expect(delivered?.status).toBe('DONE');
+    expect(delivered?.claimedBy).toBeNull();
+    heartbeat.mockRestore();
+  });
+
+  it('does not double-claim due jobs across concurrent claimers', async () => {
+    await prisma.formOutboxJob.updateMany({
+      where: { status: { in: ['PENDING', 'PROCESSING'] } },
+      data: {
+        status: 'FAILED',
+        claimedBy: null,
+        lastError: 'parked before concurrent claim test',
+      },
+    });
+
+    await Promise.all(
+      Array.from({ length: 10 }, (_, index) =>
+        prisma.formOutboxJob.create({
+          data: {
+            type: 'email',
+            payload: { to: `claim-${index}@example.com`, template: 'test' },
+            status: 'PENDING',
+            attempts: 0,
+            maxAttempts: 3,
+            orgId: owner.orgId,
+            actorUserId: owner.userId,
+          },
+        }),
+      ),
+    );
+
+    const [first, second] = await Promise.all([
+      outboxStore.claimDue(new Date(), 5),
+      outboxStore.claimDue(new Date(), 5),
+    ]);
+
+    const claimedIds = [...first, ...second].map((job) => job.id);
+    expect(claimedIds).toHaveLength(10);
+    expect(new Set(claimedIds).size).toBe(10);
+    expect([...first, ...second].every((job) => typeof job.claimedBy === 'string')).toBe(true);
+  });
+
+  function uniqueSuffix() {
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+
+  function uniqueFormKey(label: string) {
+    return `${label}-${uniqueSuffix()}`.toLowerCase();
+  }
+
+  function registrationDefinition(key: string): Record<string, unknown> {
+    return {
+      key,
+      version: 1,
+      title: 'Event registration',
+      fields: [
+        {
+          type: 'text',
+          name: 'fullName',
+          label: 'Full name',
+          validators: { required: true, maxLength: 120 },
+          reportable: true,
+        },
+        {
+          type: 'email',
+          name: 'email',
+          label: 'Email address',
+          validators: { required: true },
+          reportable: true,
+        },
+        {
+          type: 'select',
+          name: 'ticketType',
+          label: 'Ticket type',
+          validators: {
+            required: true,
+            options: ['standard', 'student', 'vip'],
+          },
+          reportable: true,
+        },
+      ],
+      actions: {
+        submit: ['validateAll', 'persist', 'sendConfirmationEmail'],
+        saveDraft: ['persistDraft'],
+      },
+    };
+  }
+
+  async function publishDefinition(definition: Record<string, unknown>): Promise<string> {
+    const created = await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms`)
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .send({ definition })
+      .expect(201);
+
+    await request(app.getHttpServer())
+      .post(
+        `/organisations/${owner.orgId}/forms/${created.body.key as string}/versions/${created.body.version as number}/publish`,
+      )
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .expect(200);
+
+    return created.body.key as string;
+  }
+
+  async function createUserAndOrg(label: string) {
+    const suffix = uniqueSuffix();
+    const signup = await request(app.getHttpServer())
+      .post('/auth/signup')
+      .send({
+        email: `${label}-${suffix}@example.com`,
+        password: 'test-password-123',
+        displayName: label,
+      })
+      .expect(201);
+
+    const accessToken = signup.body.accessToken as string;
+    const org = await request(app.getHttpServer())
+      .post('/organisations')
+      .set('Authorization', `Bearer ${accessToken}`)
+      .send({
+        name: `${label} ${suffix}`,
+        slug: `${label}-${suffix}`,
+      })
+      .expect(201);
+
+    return {
+      accessToken,
+      userId: signup.body.user.id as string,
+      orgId: org.body.organisation.id as string,
+    };
+  }
+});

package/template/test/forms-permission-sync.spec.ts

@@ -0,0 +1,27 @@
+import { FORM_PERMISSION_KEYS } from '@ftisindia/form-builder';
+import { permissionKeys } from '../src/modules/access-control/types/permission-key';
+
+/**
+ * The template carries the form permission keys as literals (so the as-const
+ * tuple stays narrow and gen:module's insertion markers keep working); this
+ * test is the mechanical guarantee they can never drift from the engine's
+ * FORM_PERMISSION_KEYS export — in either direction.
+ */
+describe('forms permission sync', () => {
+  const templateFormKeys = permissionKeys.filter(
+    (key) =>
+      key.startsWith('forms.') ||
+      key.startsWith('formSubmissions.') ||
+      key.startsWith('formDataSources.'),
+  );
+
+  it('contains every engine form permission key', () => {
+    for (const key of FORM_PERMISSION_KEYS) {
+      expect(permissionKeys).toContain(key);
+    }
+  });
+
+  it('has no form keys the engine does not declare', () => {
+    expect([...templateFormKeys].sort()).toEqual([...FORM_PERMISSION_KEYS].sort());
+  });
+});