@shipfox/api-triggers 2.0.0

package/src/db/cron-schedules.test.ts

@@ -0,0 +1,358 @@
+import {and, eq} from 'drizzle-orm';
+import {getCronScheduleBySubscriptionId} from './cron-schedules.js';
+import {db} from './db.js';
+import {triggersCronSchedules} from './schema/cron-schedules.js';
+import {triggerSubscriptions} from './schema/subscriptions.js';
+import {deleteSubscriptionsForDefinition, projectDefinitionTriggers} from './subscriptions.js';
+
+describe('cron schedule projection', () => {
+  let workspaceId: string;
+  let projectId: string;
+  let workflowDefinitionId: string;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+    workspaceId = crypto.randomUUID();
+    projectId = crypto.randomUUID();
+    workflowDefinitionId = crypto.randomUUID();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  test('creates a cron schedule row with a future next fire time', async () => {
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: '0 2 * * *', timezone: 'UTC'},
+        },
+      },
+    });
+    const subscription = await getSubscriptionByName(workflowDefinitionId, 'nightly');
+
+    const schedule = await getCronScheduleBySubscriptionId(subscription.id);
+
+    expect(schedule).toMatchObject({
+      subscriptionId: subscription.id,
+      workspaceId,
+      cronExpression: '0 2 * * *',
+      timezone: 'UTC',
+      lastFiredAt: null,
+    });
+    expect(schedule?.nextFireAt.getTime()).toBeGreaterThan(Date.now());
+  });
+
+  test('preserves next fire and last fired when the expression and timezone are unchanged', async () => {
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: '0 2 * * *', timezone: 'UTC'},
+        },
+      },
+    });
+    const subscription = await getSubscriptionByName(workflowDefinitionId, 'nightly');
+    const before = await getRequiredCronSchedule(subscription.id);
+    const lastFiredAt = new Date('2026-01-01T02:00:00.000Z');
+    await db()
+      .update(triggersCronSchedules)
+      .set({lastFiredAt})
+      .where(eq(triggersCronSchedules.subscriptionId, subscription.id));
+    vi.setSystemTime(new Date('2026-01-01T01:00:00.000Z'));
+
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: '0 2 * * *', timezone: 'UTC'},
+        },
+      },
+    });
+    const after = await getRequiredCronSchedule(subscription.id);
+
+    expect(after.nextFireAt).toEqual(before.nextFireAt);
+    expect(after.lastFiredAt).toEqual(lastFiredAt);
+    expect(after.updatedAt).toEqual(before.updatedAt);
+  });
+
+  test('recomputes next fire when the expression changes', async () => {
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: '0 2 * * *', timezone: 'UTC'},
+        },
+      },
+    });
+    const subscription = await getSubscriptionByName(workflowDefinitionId, 'nightly');
+    const before = await getRequiredCronSchedule(subscription.id);
+
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: '0 3 * * *', timezone: 'UTC'},
+        },
+      },
+    });
+    const after = await getRequiredCronSchedule(subscription.id);
+
+    expect(after.cronExpression).toBe('0 3 * * *');
+    expect(after.nextFireAt).not.toEqual(before.nextFireAt);
+    expect(after.nextFireAt).toEqual(new Date('2026-01-01T03:00:00.000Z'));
+  });
+
+  test('recomputes next fire when the timezone changes', async () => {
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: '0 2 * * *', timezone: 'UTC'},
+        },
+      },
+    });
+    const subscription = await getSubscriptionByName(workflowDefinitionId, 'nightly');
+    const before = await getRequiredCronSchedule(subscription.id);
+
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: '0 2 * * *', timezone: 'America/New_York'},
+        },
+      },
+    });
+    const after = await getRequiredCronSchedule(subscription.id);
+
+    expect(after.timezone).toBe('America/New_York');
+    expect(after.nextFireAt).not.toEqual(before.nextFireAt);
+    expect(after.nextFireAt).toEqual(new Date('2026-01-01T07:00:00.000Z'));
+  });
+
+  test('drops a cron schedule when the trigger source changes in place', async () => {
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: '0 2 * * *', timezone: 'UTC'},
+        },
+      },
+    });
+    const subscription = await getSubscriptionByName(workflowDefinitionId, 'nightly');
+
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {source: 'github', event: 'push'},
+      },
+    });
+    const schedule = await getCronScheduleBySubscriptionId(subscription.id);
+
+    expect(schedule).toBeUndefined();
+  });
+
+  test('drops a cron schedule when the trigger is removed', async () => {
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: '0 2 * * *', timezone: 'UTC'},
+        },
+      },
+    });
+    const subscription = await getSubscriptionByName(workflowDefinitionId, 'nightly');
+
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {},
+    });
+    const schedule = await getCronScheduleBySubscriptionId(subscription.id);
+
+    expect(schedule).toBeUndefined();
+  });
+
+  test('drops a cron schedule when definition subscriptions are deleted', async () => {
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: '0 2 * * *', timezone: 'UTC'},
+        },
+      },
+    });
+    const subscription = await getSubscriptionByName(workflowDefinitionId, 'nightly');
+
+    const deletedCount = await deleteSubscriptionsForDefinition({workflowDefinitionId});
+    const schedule = await getCronScheduleBySubscriptionId(subscription.id);
+
+    expect(deletedCount).toBe(1);
+    expect(schedule).toBeUndefined();
+  });
+
+  test.each([
+    {name: 'missing schedule', config: {}},
+    {name: 'invalid expression', config: {schedule: 'not a cron', timezone: 'UTC'}},
+  ])('drops a stale cron schedule when resynced with $name', async ({config}) => {
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: '0 2 * * *', timezone: 'UTC'},
+        },
+      },
+    });
+    const subscription = await getSubscriptionByName(workflowDefinitionId, 'nightly');
+
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {source: 'cron', event: 'tick', config},
+      },
+    });
+    const schedule = await getCronScheduleBySubscriptionId(subscription.id);
+
+    expect(schedule).toBeUndefined();
+  });
+
+  test('skips invalid cron config without blocking sibling trigger sync', async () => {
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        malformed: {source: 'cron', event: 'tick', config: {}},
+        bad_expression: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: 'not a cron', timezone: 'UTC'},
+        },
+        on_push: {source: 'github', event: 'push'},
+      },
+    });
+    const malformed = await getSubscriptionByName(workflowDefinitionId, 'malformed');
+    const badExpression = await getSubscriptionByName(workflowDefinitionId, 'bad_expression');
+    const onPush = await getSubscriptionByName(workflowDefinitionId, 'on_push');
+
+    const malformedSchedule = await getCronScheduleBySubscriptionId(malformed.id);
+    const badExpressionSchedule = await getCronScheduleBySubscriptionId(badExpression.id);
+
+    expect(malformedSchedule).toBeUndefined();
+    expect(badExpressionSchedule).toBeUndefined();
+    expect(onPush.source).toBe('github');
+  });
+
+  test('defaults a missing timezone to UTC defensively', async () => {
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        hourly: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: '0 * * * *'},
+        },
+      },
+    });
+    const subscription = await getSubscriptionByName(workflowDefinitionId, 'hourly');
+
+    const schedule = await getRequiredCronSchedule(subscription.id);
+
+    expect(schedule.timezone).toBe('UTC');
+  });
+
+  test('stores only with and filter in the subscription config', async () => {
+    await projectDefinitionTriggers({
+      workspaceId,
+      projectId,
+      workflowDefinitionId,
+      triggers: {
+        nightly: {
+          source: 'cron',
+          event: 'tick',
+          with: {branch: 'main'},
+          filter: 'true',
+          config: {schedule: '0 2 * * *', timezone: 'UTC'},
+        },
+      },
+    });
+
+    const subscription = await getSubscriptionByName(workflowDefinitionId, 'nightly');
+
+    expect(subscription.config).toEqual({with: {branch: 'main'}, filter: 'true'});
+  });
+});
+
+async function getSubscriptionByName(workflowDefinitionId: string, name: string) {
+  const [row] = await db()
+    .select()
+    .from(triggerSubscriptions)
+    .where(
+      and(
+        eq(triggerSubscriptions.workflowDefinitionId, workflowDefinitionId),
+        eq(triggerSubscriptions.name, name),
+      ),
+    )
+    .limit(1);
+  if (!row) throw new Error(`Expected subscription ${name} to exist`);
+  return row;
+}
+
+async function getRequiredCronSchedule(subscriptionId: string) {
+  const schedule = await getCronScheduleBySubscriptionId(subscriptionId);
+  if (!schedule) throw new Error(`Expected cron schedule for subscription ${subscriptionId}`);
+  return schedule;
+}

package/src/db/cron-schedules.ts

@@ -0,0 +1,163 @@
+import {logger} from '@shipfox/node-opentelemetry';
+import {triggerSourceConfigSchemas} from '@shipfox/workflow-document';
+import {eq, lte, sql} from 'drizzle-orm';
+import {config} from '#config.js';
+import {computeNextFireAt} from '#core/compute-next-fire-at.js';
+import type {CronSchedule} from '#core/entities/cron-schedule.js';
+import {db, type Executor, type Tx} from './db.js';
+import {toCronSchedule, triggersCronSchedules} from './schema/cron-schedules.js';
+
+const defaultCronTimezone = 'UTC';
+
+export interface SyncCronScheduleParams {
+  readonly tx: Tx;
+  readonly subscriptionId: string;
+  readonly workspaceId: string;
+  readonly triggerConfig: Record<string, unknown> | undefined;
+}
+
+export async function syncCronSchedule(params: SyncCronScheduleParams): Promise<void> {
+  const parsed = triggerSourceConfigSchemas.cron.safeParse(params.triggerConfig ?? {});
+  if (!parsed.success || parsed.data.schedule === undefined) {
+    logger().warn(
+      {subscriptionId: params.subscriptionId},
+      'cron trigger missing/invalid schedule config; skipping cron row',
+    );
+    await deleteCronScheduleForSubscription(params);
+    return;
+  }
+
+  const schedule = parsed.data.schedule;
+  const timezone = parsed.data.timezone ?? defaultCronTimezone;
+  let nextFireAt: Date;
+  try {
+    nextFireAt = computeNextFireAt({
+      cronExpression: schedule,
+      timezone,
+      from: new Date(),
+      subscriptionId: params.subscriptionId,
+      jitterWindowSeconds: config.TRIGGER_CRON_JITTER_WINDOW_SECONDS,
+    });
+  } catch (error) {
+    logger().warn(
+      {err: error, reason: errorMessage(error), subscriptionId: params.subscriptionId},
+      'cron trigger schedule could not be parsed; skipping cron row',
+    );
+    await deleteCronScheduleForSubscription(params);
+    return;
+  }
+
+  await params.tx
+    .insert(triggersCronSchedules)
+    .values({
+      subscriptionId: params.subscriptionId,
+      workspaceId: params.workspaceId,
+      cronExpression: schedule,
+      timezone,
+      nextFireAt,
+    })
+    .onConflictDoUpdate({
+      target: triggersCronSchedules.subscriptionId,
+      set: {
+        workspaceId: sql`excluded.workspace_id`,
+        cronExpression: sql`excluded.cron_expression`,
+        timezone: sql`excluded.timezone`,
+        updatedAt: sql`case when ${triggersCronSchedules.workspaceId} <> excluded.workspace_id or ${triggersCronSchedules.cronExpression} <> excluded.cron_expression or ${triggersCronSchedules.timezone} <> excluded.timezone then ${new Date()} else ${triggersCronSchedules.updatedAt} end`,
+        nextFireAt: sql`case when ${triggersCronSchedules.cronExpression} <> excluded.cron_expression or ${triggersCronSchedules.timezone} <> excluded.timezone then excluded.next_fire_at else ${triggersCronSchedules.nextFireAt} end`,
+      },
+    });
+}
+
+export interface DeleteCronScheduleForSubscriptionParams {
+  readonly tx: Tx;
+  readonly subscriptionId: string;
+}
+
+export async function deleteCronScheduleForSubscription(
+  params: DeleteCronScheduleForSubscriptionParams,
+): Promise<void> {
+  await params.tx
+    .delete(triggersCronSchedules)
+    .where(eq(triggersCronSchedules.subscriptionId, params.subscriptionId));
+}
+
+// Reads the database clock so a tick's due check and its next-fire computation share
+// one time reference, immune to application/database clock skew.
+export async function selectDbNow(executor: Executor): Promise<Date> {
+  const result = await executor.execute<{now: Date | string}>(sql`select now() as now`);
+  const raw = result.rows[0]?.now;
+  if (raw === undefined) throw new Error('Failed to read the database clock');
+  return raw instanceof Date ? raw : new Date(raw);
+}
+
+export interface ClaimDueCronSchedulesParams {
+  readonly tx: Tx;
+  readonly limit: number;
+  readonly now: Date;
+}
+
+/**
+ * Claims schedules due as of `now` (the shared database clock captured for this tick)
+ * and holds `FOR UPDATE SKIP LOCKED` locks until the caller's transaction ends, so
+ * concurrent drains partition due rows instead of double-claiming them.
+ */
+export async function claimDueCronSchedules(
+  params: ClaimDueCronSchedulesParams,
+): Promise<CronSchedule[]> {
+  const rows = await params.tx
+    .select()
+    .from(triggersCronSchedules)
+    .where(lte(triggersCronSchedules.nextFireAt, params.now))
+    .orderBy(triggersCronSchedules.nextFireAt)
+    .limit(params.limit)
+    .for('update', {skipLocked: true});
+  return rows.map(toCronSchedule);
+}
+
+export interface AdvanceCronScheduleParams {
+  readonly tx: Tx;
+  readonly subscriptionId: string;
+  readonly nextFireAt: Date;
+  readonly lastFiredAt: Date;
+}
+
+export async function advanceCronSchedule(params: AdvanceCronScheduleParams): Promise<void> {
+  await params.tx
+    .update(triggersCronSchedules)
+    .set({
+      nextFireAt: params.nextFireAt,
+      lastFiredAt: params.lastFiredAt,
+      updatedAt: new Date(),
+    })
+    .where(eq(triggersCronSchedules.subscriptionId, params.subscriptionId));
+}
+
+export async function countDueCronSchedules(): Promise<number> {
+  const [row] = await db()
+    .select({count: sql<number>`count(*)::int`})
+    .from(triggersCronSchedules)
+    .where(lte(triggersCronSchedules.nextFireAt, sql`now()`));
+  return row?.count ?? 0;
+}
+
+export async function getCronScheduleBySubscriptionId(
+  subscriptionId: string,
+): Promise<CronSchedule | undefined> {
+  const rows = await db()
+    .select()
+    .from(triggersCronSchedules)
+    .where(eq(triggersCronSchedules.subscriptionId, subscriptionId))
+    .limit(1);
+  const row = rows[0];
+  if (!row) return undefined;
+  return toCronSchedule(row);
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  try {
+    return String(error);
+  } catch {
+    return '[unprintable thrown value]';
+  }
+}

package/src/db/db.ts

@@ -0,0 +1,31 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {triggersCronSchedules} from './schema/cron-schedules.js';
+import {triggersDecisions} from './schema/decisions.js';
+import {jobListenerSubscriptions} from './schema/job-listener-subscriptions.js';
+import {triggersOutbox} from './schema/outbox.js';
+import {triggersReceivedEvents} from './schema/received-events.js';
+import {triggerSubscriptions} from './schema/subscriptions.js';
+
+export const schema = {
+  triggersCronSchedules,
+  jobListenerSubscriptions,
+  triggerSubscriptions,
+  triggersOutbox,
+  triggersReceivedEvents,
+  triggersDecisions,
+};
+
+let _db: NodePgDatabase<typeof schema> | undefined;
+
+export function db() {
+  if (!_db) _db = drizzle(pgClient(), {schema});
+  return _db;
+}
+
+export type Tx = Parameters<Parameters<ReturnType<typeof db>['transaction']>[0]>[0];
+export type Executor = ReturnType<typeof db> | Tx;
+
+export function closeDb(): void {
+  _db = undefined;
+}