@manablox/workflows 0.2.0 → 0.3.0

package/src/engine.ts

@@ -1,499 +0,0 @@
-import type {
-  ContentHookContext,
-  ContentRecord,
-  Manablox,
-  WorkflowActor,
-  WorkflowCursor,
-  WorkflowEvent,
-  WorkflowEventTrigger,
-  WorkflowRunContext,
-  WorkflowStep,
-  WorkflowStepLog,
-} from '@manablox/core';
-import type { ContentRow, Repositories, WorkflowRow, WorkflowRunRow } from '@manablox/db';
-import { evaluateCondition } from './conditions.js';
-import { cronMatches, floorToMinute, parseCron } from './cron.js';
-import type { Mailer } from './mail.js';
-import type { Pusher } from './push.js';
-import { executeStep, type StepEnvironment } from './steps.js';
-
-export interface WorkflowEngineOptions {
-  mailer?: Mailer | null | undefined;
-  pusher?: Pusher | null | undefined;
-  fetch?: typeof fetch | undefined;
-  /** Where the admin lives, for links in mails and notifications. */
-  adminUrl?: string | undefined;
-  /**
-   * Hands a queued run to a worker. The default runs it in this process, off the
-   * request; a host with a queue passes `(runId) => jobs.enqueue('workflow:run', …)`.
-   */
-  dispatch?: ((runId: string) => Promise<void>) | undefined;
-  /** How often the scheduler looks at the clock. Every 20 s catches each minute once. */
-  tickMs?: number | undefined;
-  now?: (() => Date) | undefined;
-}
-
-type ChainOutcome =
-  | { kind: 'done' }
-  | { kind: 'wait' }
-  | { kind: 'stop'; cursor: WorkflowCursor }
-  | { kind: 'fail'; cursor: WorkflowCursor; error: string };
-
-/** The hook events a content change raises, and the trigger events each satisfies. */
-const EVENT_ALIASES: Record<WorkflowEvent, WorkflowEvent[]> = {
-  'content.created': ['content.created', 'content.saved'],
-  'content.updated': ['content.updated', 'content.saved'],
-  'content.saved': ['content.saved'],
-  'content.deleted': ['content.deleted'],
-  'content.published': ['content.published'],
-  'content.unpublished': ['content.unpublished'],
-};
-
-/**
- * Runs workflows: listens for content events, keeps the clock for scheduled ones, and
- * executes a run's steps one after another, pausing at a delay and picking it up again.
- *
- * A run is a row from the moment it is queued, so nothing is lost if the process goes
- * away mid-way: the next tick finds `waiting` runs whose time has come, and a worker
- * claims a run before touching it so two never execute the same one.
- */
-export class WorkflowEngine {
-  private readonly env: StepEnvironment;
-  private readonly dispatch: (runId: string) => Promise<void>;
-  private readonly now: () => Date;
-  private readonly tickMs: number;
-  private readonly pending = new Set<Promise<void>>();
-  private timer: ReturnType<typeof setInterval> | null = null;
-  private ticking = false;
-
-  constructor(
-    private readonly manablox: Manablox,
-    private readonly repos: Repositories,
-    options: WorkflowEngineOptions = {},
-  ) {
-    this.env = {
-      repos,
-      mailer: options.mailer ?? null,
-      pusher: options.pusher ?? null,
-      fetch: options.fetch ?? globalThis.fetch,
-      adminUrl: options.adminUrl ?? manablox.config.server.adminUrl,
-    };
-    this.dispatch = options.dispatch ?? ((runId) => this.background(this.run(runId)));
-    this.now = options.now ?? (() => new Date());
-    this.tickMs = options.tickMs ?? 20_000;
-  }
-
-  get adminUrl(): string {
-    return this.env.adminUrl;
-  }
-
-  /** Registers the content hooks. Call once, at boot. */
-  attach(): void {
-    const source = '@manablox/workflows';
-    const on =
-      (event: WorkflowEvent) => async (row: ContentRecord, context: ContentHookContext) => {
-        await this.onContentEvent(event, row, context);
-      };
-    this.manablox.hooks.on('content:afterCreate', on('content.created'), { source });
-    this.manablox.hooks.on('content:afterUpdate', on('content.updated'), { source });
-    this.manablox.hooks.on('content:afterPublish', on('content.published'), { source });
-    this.manablox.hooks.on(
-      'content:afterDelete',
-      async (payload, context) => {
-        await this.onContentEvent('content.deleted', payload.record, context);
-      },
-      { source },
-    );
-    this.manablox.hooks.on(
-      'content:afterUnpublish',
-      async (payload, context) => {
-        const row = await this.repos.content.findById(payload.id);
-        if (row) await this.onContentEvent('content.unpublished', row as never, context);
-      },
-      { source },
-    );
-  }
-
-  /** Starts the clock for scheduled workflows and paused runs. */
-  start(): void {
-    if (this.timer) return;
-    this.timer = setInterval(() => void this.tick(), this.tickMs);
-    this.timer.unref?.();
-    this.manablox.onDispose(() => this.stop());
-  }
-
-  async stop(): Promise<void> {
-    if (this.timer) clearInterval(this.timer);
-    this.timer = null;
-    await this.idle();
-  }
-
-  /** Resolves once every run started in this process has finished. For tests and shutdown. */
-  async idle(): Promise<void> {
-    while (this.pending.size) await Promise.allSettled([...this.pending]);
-  }
-
-  // --- event triggers --------------------------------------------------------
-
-  private async onContentEvent(
-    event: WorkflowEvent,
-    row: ContentRecord,
-    context: ContentHookContext,
-  ): Promise<void> {
-    const candidates = await this.repos.workflows.listEnabled(row.spaceId);
-    const matching = candidates.filter((workflow) => matchesEvent(workflow.trigger, event, row));
-    if (matching.length === 0) return;
-
-    const space = await this.spaceInfo(row.spaceId);
-    const actor = await this.actorInfo(context.actor?.userId ?? null);
-    const previous = context.previous ? serialise(context.previous) : null;
-
-    for (const workflow of matching) {
-      const runContext: WorkflowRunContext = {
-        event,
-        workflow: { id: workflow.id, name: workflow.name },
-        space,
-        content: serialise(row),
-        previous: event === 'content.updated' ? previous : null,
-        documents: [],
-        actor,
-        url: event === 'content.deleted' ? null : this.documentUrl(row.id),
-        at: this.now().toISOString(),
-      };
-      await this.enqueue(workflow, event, runContext);
-    }
-  }
-
-  // --- schedule ----------------------------------------------------------------
-
-  /**
-   * One look at the clock: start every scheduled workflow whose cron names this minute,
-   * and resume every paused run whose time has come. Safe to call from several
-   * processes — each claim is an atomic update.
-   */
-  async tick(now: Date = this.now()): Promise<void> {
-    if (this.ticking) return;
-    this.ticking = true;
-    try {
-      const minute = floorToMinute(now);
-      const enabled = await this.repos.workflows.listEnabled();
-      for (const workflow of enabled) {
-        if (workflow.trigger.kind !== 'schedule') continue;
-        const spec = parseCron(workflow.trigger.cron);
-        if (!spec || !cronMatches(spec, minute, workflow.trigger.timezone)) continue;
-        if (!(await this.repos.workflows.claimSchedule(workflow.id, minute))) continue;
-        await this.startScheduled(workflow);
-      }
-
-      for (const run of await this.repos.workflows.dueRuns(now)) {
-        await this.dispatch(run.id);
-      }
-    } catch (error) {
-      this.manablox.logger.error({ err: error }, 'workflow tick failed');
-    } finally {
-      this.ticking = false;
-    }
-  }
-
-  private async startScheduled(workflow: WorkflowRow): Promise<void> {
-    if (workflow.trigger.kind !== 'schedule') return;
-    const space = await this.spaceInfo(workflow.spaceId);
-    const selection = workflow.trigger.selection;
-    const documents = selection
-      ? (await this.repos.workflows.selectDocuments(workflow.spaceId, selection)).map(serialise)
-      : [];
-
-    const base = {
-      event: 'schedule',
-      workflow: { id: workflow.id, name: workflow.name },
-      space,
-      previous: null,
-      actor: null,
-      at: this.now().toISOString(),
-    };
-
-    if (workflow.trigger.perDocument) {
-      for (const document of documents) {
-        await this.enqueue(workflow, 'schedule', {
-          ...base,
-          content: document,
-          documents: [],
-          url: this.documentUrl(String(document.id)),
-        });
-      }
-      return;
-    }
-    await this.enqueue(workflow, 'schedule', { ...base, content: null, documents, url: null });
-  }
-
-  // --- manual ------------------------------------------------------------------
-
-  /** A run started by hand from the editor, executed inline so the caller sees the log. */
-  async runManually(workflow: WorkflowRow, document: ContentRow | null): Promise<WorkflowRunRow> {
-    const space = await this.spaceInfo(workflow.spaceId);
-    const documents =
-      workflow.trigger.kind === 'schedule' && workflow.trigger.selection && !document
-        ? (
-            await this.repos.workflows.selectDocuments(workflow.spaceId, workflow.trigger.selection)
-          ).map(serialise)
-        : [];
-    const run = await this.repos.workflows.createRun({
-      workflowId: workflow.id,
-      spaceId: workflow.spaceId,
-      trigger: 'manual',
-      context: {
-        event: 'manual',
-        workflow: { id: workflow.id, name: workflow.name },
-        space,
-        content: document ? serialise(document) : null,
-        previous: null,
-        documents,
-        actor: null,
-        url: document ? this.documentUrl(document.id) : null,
-        at: this.now().toISOString(),
-      },
-    });
-    await this.run(run.id);
-    return (await this.repos.workflows.findRun(run.id)) ?? run;
-  }
-
-  // --- execution ---------------------------------------------------------------
-
-  private async enqueue(
-    workflow: WorkflowRow,
-    trigger: string,
-    context: WorkflowRunContext,
-  ): Promise<void> {
-    const run = await this.repos.workflows.createRun({
-      workflowId: workflow.id,
-      spaceId: workflow.spaceId,
-      trigger,
-      context,
-    });
-    await this.dispatch(run.id);
-  }
-
-  private background(work: Promise<void>): Promise<void> {
-    const tracked = work
-      .catch((error) => {
-        this.manablox.logger.error({ err: error }, 'workflow run crashed');
-      })
-      .finally(() => {
-        this.pending.delete(tracked);
-      });
-    this.pending.add(tracked);
-    // Resolved at once: the caller queued the run, and does not wait for it to finish.
-    return Promise.resolve();
-  }
-
-  /** Executes a queued or paused run from where it stands. The worker entry point. */
-  async run(runId: string): Promise<void> {
-    const run = await this.repos.workflows.claimRun(runId);
-    if (!run) return;
-    const workflow = await this.repos.workflows.findById(run.workflowId);
-    if (!workflow) {
-      await this.repos.workflows.saveRunProgress(run.id, {
-        status: 'failed',
-        cursor: run.cursor,
-        log: run.log,
-        error: 'The workflow no longer exists',
-        finished: true,
-      });
-      return;
-    }
-
-    const log: WorkflowStepLog[] = [...run.log];
-    const outcome = await this.runChain(run, workflow, workflow.steps, [], run.cursor, log);
-    if (outcome.kind === 'done') await this.finish(run, workflow, 'succeeded', [], log, null);
-    else if (outcome.kind === 'stop')
-      await this.finish(run, workflow, 'skipped', outcome.cursor, log, null);
-    else if (outcome.kind === 'fail')
-      await this.finish(run, workflow, 'failed', outcome.cursor, log, outcome.error);
-    // `wait` has already been saved.
-  }
-
-  /**
-   * Walks one chain — the top level, or a side of a fork — from `resume` when the run is
-   * being picked up inside it. A fork's chosen side is walked recursively; the position
-   * saved at a delay is the full path, so a resume finds its way back down.
-   */
-  private async runChain(
-    run: WorkflowRunRow,
-    workflow: WorkflowRow,
-    steps: WorkflowStep[],
-    prefix: WorkflowCursor,
-    resume: WorkflowCursor | null,
-    log: WorkflowStepLog[],
-  ): Promise<ChainOutcome> {
-    let index = 0;
-    let inner: { side: 'then' | 'else'; cursor: WorkflowCursor } | null = null;
-    if (resume?.length) {
-      index = resume[0] as number;
-      const side = resume[1];
-      if (side === 'then' || side === 'else') inner = { side, cursor: resume.slice(2) };
-    }
-
-    for (; index < steps.length; index++) {
-      const step = steps[index];
-      if (!step) break;
-      const here: WorkflowCursor = [...prefix, index];
-      const startedAt = this.now();
-      const entry = (
-        status: WorkflowStepLog['status'],
-        message: string | null,
-        detail: Record<string, unknown> | null = null,
-      ): WorkflowStepLog => ({
-        stepId: step.id,
-        type: step.type,
-        name: step.name,
-        status,
-        message,
-        detail,
-        startedAt: startedAt.toISOString(),
-        ms: this.now().getTime() - startedAt.getTime(),
-      });
-
-      // Resuming inside a fork: skip the rules, they were decided before the pause.
-      if (inner) {
-        const { side, cursor } = inner;
-        inner = null;
-        if (step.type === 'branch') {
-          const outcome = await this.runChain(
-            run,
-            workflow,
-            step[side],
-            [...here, side],
-            cursor,
-            log,
-          );
-          if (outcome.kind !== 'done') return outcome;
-        }
-        continue;
-      }
-
-      if (!step.enabled) {
-        log.push(entry('skipped', 'Step is switched off'));
-        continue;
-      }
-
-      if (step.type === 'branch') {
-        const holds = evaluateCondition(step, run.context);
-        const side = holds ? 'then' : 'else';
-        log.push(
-          entry(
-            'ok',
-            holds ? 'Rules hold — taking the yes side' : 'Rules do not hold — taking the no side',
-            {
-              branch: side,
-            },
-          ),
-        );
-        const outcome = await this.runChain(run, workflow, step[side], [...here, side], null, log);
-        if (outcome.kind !== 'done') return outcome;
-        continue;
-      }
-
-      try {
-        const outcome = await executeStep(step, run.context, this.env);
-        if (outcome.kind === 'wait') {
-          const resumeAt = new Date(this.now().getTime() + outcome.minutes * 60_000);
-          log.push(
-            entry('waiting', `Waiting until ${resumeAt.toISOString()}`, {
-              resumeAt: resumeAt.toISOString(),
-            }),
-          );
-          await this.repos.workflows.saveRunProgress(run.id, {
-            status: 'waiting',
-            cursor: [...prefix, index + 1],
-            log,
-            resumeAt,
-          });
-          return { kind: 'wait' };
-        }
-        if (outcome.kind === 'stop') {
-          log.push(entry('stopped', outcome.message));
-          return { kind: 'stop', cursor: here };
-        }
-        log.push(entry('ok', outcome.message, outcome.detail));
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        const detail = (error as { detail?: Record<string, unknown> }).detail ?? null;
-        log.push(entry('failed', message, detail));
-        this.manablox.logger.warn(
-          { workflow: workflow.id, run: run.id, step: step.id, err: error },
-          'workflow step failed',
-        );
-        if (!step.continueOnError) return { kind: 'fail', cursor: here, error: message };
-      }
-    }
-    return { kind: 'done' };
-  }
-
-  private async finish(
-    run: WorkflowRunRow,
-    workflow: WorkflowRow,
-    status: 'succeeded' | 'failed' | 'skipped',
-    cursor: WorkflowCursor,
-    log: WorkflowStepLog[],
-    error: string | null,
-  ): Promise<void> {
-    await this.repos.workflows.saveRunProgress(run.id, {
-      status,
-      cursor,
-      log,
-      error,
-      finished: true,
-    });
-    await this.repos.workflows.touchRun(workflow.id, this.now());
-    await this.manablox.hooks.run(
-      'workflow:afterRun',
-      {
-        runId: run.id,
-        workflowId: workflow.id,
-        spaceId: workflow.spaceId,
-        status,
-        trigger: run.trigger,
-      },
-      { manablox: this.manablox, spaceId: workflow.spaceId },
-    );
-  }
-
-  // --- context helpers ---------------------------------------------------------
-
-  private async spaceInfo(spaceId: string): Promise<WorkflowRunContext['space']> {
-    const space = await this.repos.spaces.findById(spaceId);
-    return space
-      ? { id: space.id, name: space.name, machineName: space.machineName, url: space.url }
-      : { id: spaceId, name: '', machineName: '', url: '' };
-  }
-
-  private async actorInfo(userId: string | null): Promise<WorkflowActor | null> {
-    if (!userId) return null;
-    const user = await this.repos.users.findById(userId);
-    return user ? { id: user.id, name: user.name, email: user.email } : null;
-  }
-
-  private documentUrl(contentId: string): string {
-    return `${this.env.adminUrl.replace(/\/$/, '')}/content/${contentId}`;
-  }
-}
-
-/** Whether an event trigger wants this event for this document. */
-export function matchesEvent(
-  trigger: WorkflowRow['trigger'],
-  event: WorkflowEvent,
-  row: Pick<ContentRecord, 'typeId' | 'locale'>,
-): trigger is WorkflowEventTrigger {
-  if (trigger.kind !== 'event') return false;
-  const satisfied = EVENT_ALIASES[event];
-  if (!trigger.events.some((wanted) => satisfied.includes(wanted))) return false;
-  if (trigger.typeIds.length && !trigger.typeIds.includes(row.typeId)) return false;
-  if (trigger.locales.length && !trigger.locales.includes(row.locale)) return false;
-  return true;
-}
-
-/** A row as a template sees it: plain JSON, without the search machinery. */
-export function serialise(row: ContentRecord | ContentRow): Record<string, unknown> {
-  const { search: _search, searchText: _searchText, ...rest } = row as ContentRecord;
-  return JSON.parse(JSON.stringify(rest)) as Record<string, unknown>;
-}

package/src/index.ts

@@ -1,9 +0,0 @@
-export * from './conditions.js';
-export * from './cron.js';
-export * from './engine.js';
-export * from './mail.js';
-export * from './push.js';
-export * from './service.js';
-export * from './steps.js';
-export * from './template.js';
-export * from './validate.js';

package/src/mail.ts

@@ -1,38 +0,0 @@
-import type { Logger, MailConfig } from '@manablox/core';
-import nodemailer from 'nodemailer';
-
-export interface MailMessage {
-  to: string[];
-  subject: string;
-  text: string;
-  html?: string | undefined;
-}
-
-/** What the email step needs from the outside world; the tests hand in a recorder. */
-export interface Mailer {
-  send(message: MailMessage): Promise<{ id: string | null }>;
-}
-
-/**
- * A mailer over the configured SMTP URL, or `null` when there is none — the step then
- * fails with `workflow.mail.notConfigured`, which the run log shows verbatim.
- */
-export function createMailer(config: MailConfig, logger: Logger): Mailer | null {
-  if (!config.smtpUrl) return null;
-  const transport = nodemailer.createTransport(config.smtpUrl);
-  const from = config.from ?? 'Manablox <no-reply@localhost>';
-
-  return {
-    async send(message) {
-      const info = await transport.sendMail({
-        from,
-        to: message.to,
-        subject: message.subject,
-        text: message.text,
-        ...(message.html ? { html: message.html } : {}),
-      });
-      logger.debug({ to: message.to, id: info.messageId }, 'workflow mail sent');
-      return { id: info.messageId ?? null };
-    },
-  };
-}

package/src/push.ts

@@ -1,61 +0,0 @@
-import type { Logger, PushConfig } from '@manablox/core';
-import webpush from 'web-push';
-
-export interface PushTarget {
-  endpoint: string;
-  keys: { p256dh: string; auth: string };
-}
-
-/** What a notification carries; the admin's service worker reads exactly this. */
-export interface PushPayload {
-  title: string;
-  body: string;
-  url: string | null;
-}
-
-/** What the push step needs from the outside world; the tests hand in a recorder. */
-export interface Pusher {
-  /** `gone` means the push service no longer knows the subscription and the row should go. */
-  send(target: PushTarget, payload: PushPayload): Promise<'sent' | 'gone'>;
-  publicKey: string;
-}
-
-export function isPushConfigured(config: PushConfig): boolean {
-  return Boolean(config.vapidPublicKey && config.vapidPrivateKey);
-}
-
-/**
- * A Web Push sender over the configured VAPID keys, or `null` when there are none. The
- * keys are made once per installation with `pnpm --filter @manablox/api push:keys`.
- */
-export function createPusher(config: PushConfig, logger: Logger): Pusher | null {
-  if (!config.vapidPublicKey || !config.vapidPrivateKey) return null;
-  const subject = config.subject ?? 'mailto:admin@localhost';
-  const publicKey = config.vapidPublicKey;
-  const privateKey = config.vapidPrivateKey;
-
-  return {
-    publicKey,
-    async send(target, payload) {
-      try {
-        await webpush.sendNotification(target, JSON.stringify(payload), {
-          vapidDetails: { subject, publicKey, privateKey },
-          TTL: 60 * 60 * 24,
-        });
-        return 'sent';
-      } catch (error) {
-        const status = (error as { statusCode?: number }).statusCode;
-        if (status === 404 || status === 410) {
-          logger.debug({ endpoint: target.endpoint }, 'push subscription gone');
-          return 'gone';
-        }
-        throw error;
-      }
-    },
-  };
-}
-
-/** A fresh VAPID key pair, for the CLI that prints them. */
-export function generatePushKeys(): { publicKey: string; privateKey: string } {
-  return webpush.generateVAPIDKeys();
-}