alepha 0.19.2 → 0.19.4

package/src/api/workflows/controllers/AdminWorkflowController.ts

@@ -0,0 +1,191 @@
+import { $inject, t } from "alepha";
+import { $secure } from "alepha/security";
+import { $action, okSchema } from "alepha/server";
+import {
+  workflowActivityPointSchema,
+  workflowActivityQuerySchema,
+} from "../schemas/workflowActivitySchema.ts";
+import { workflowExecutionDetailSchema } from "../schemas/workflowExecutionDetailSchema.ts";
+import { workflowExecutionQuerySchema } from "../schemas/workflowExecutionQuerySchema.ts";
+import { workflowExecutionResourceSchema } from "../schemas/workflowExecutionResourceSchema.ts";
+import { workflowRegistrationSchema } from "../schemas/workflowRegistrationSchema.ts";
+import { workflowStatsSchema } from "../schemas/workflowStatsSchema.ts";
+import { WorkflowService } from "../services/WorkflowService.ts";
+
+export class AdminWorkflowController {
+  protected readonly url: string = "/workflows";
+  protected readonly group: string = "admin:workflows";
+  protected readonly workflowService = $inject(WorkflowService);
+
+  public readonly getRegistry = $action({
+    path: this.url,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:workflow:read"] })],
+    schema: {
+      response: t.array(workflowRegistrationSchema),
+    },
+    handler: () => this.workflowService.getRegistry(),
+  });
+
+  public readonly getStats = $action({
+    path: `${this.url}/stats`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:workflow:read"] })],
+    schema: {
+      query: workflowActivityQuerySchema,
+      response: workflowStatsSchema,
+    },
+    handler: ({ query }) => this.workflowService.getStats(query.days),
+  });
+
+  public readonly getActivity = $action({
+    path: `${this.url}/activity`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:workflow:read"] })],
+    schema: {
+      query: workflowActivityQuerySchema,
+      response: t.array(workflowActivityPointSchema),
+    },
+    handler: ({ query }) => this.workflowService.getActivity(query.days),
+  });
+
+  public readonly findExecutions = $action({
+    path: `${this.url}/executions`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:workflow:read"] })],
+    schema: {
+      query: workflowExecutionQuerySchema,
+      response: t.page(workflowExecutionResourceSchema),
+    },
+    handler: ({ query }) => this.workflowService.findExecutions(query),
+  });
+
+  public readonly getExecution = $action({
+    path: `${this.url}/executions/:id`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:workflow:read"] })],
+    schema: {
+      params: t.object({
+        id: t.uuid(),
+      }),
+      response: workflowExecutionDetailSchema,
+    },
+    handler: ({ params }) => this.workflowService.getExecution(params.id),
+  });
+
+  public readonly startWorkflow = $action({
+    method: "POST",
+    path: `${this.url}/start`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:workflow:create"] })],
+    schema: {
+      body: t.object({
+        name: t.text(),
+        payload: t.optional(t.record(t.text(), t.any())),
+        key: t.optional(t.text()),
+        tags: t.optional(t.array(t.text())),
+      }),
+      response: t.object({ id: t.uuid() }),
+    },
+    handler: async ({ body, user }) => {
+      return this.workflowService.triggerWorkflow(body.name, body.payload, {
+        key: body.key,
+        tags: body.tags,
+        triggeredBy: user?.id,
+        triggeredByName: user?.name,
+      });
+    },
+  });
+
+  public readonly signalStep = $action({
+    method: "POST",
+    path: `${this.url}/executions/:id/signal`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:workflow:update"] })],
+    schema: {
+      params: t.object({
+        id: t.uuid(),
+      }),
+      body: t.object({
+        stepName: t.text(),
+        payload: t.optional(t.record(t.text(), t.any())),
+      }),
+      response: okSchema,
+    },
+    handler: async ({ params, body, user }) => {
+      return this.workflowService.signalExecution(
+        params.id,
+        body.stepName,
+        body.payload,
+        user?.id,
+      );
+    },
+  });
+
+  public readonly cancelExecution = $action({
+    method: "POST",
+    path: `${this.url}/executions/:id/cancel`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:workflow:update"] })],
+    schema: {
+      params: t.object({
+        id: t.uuid(),
+      }),
+      response: okSchema,
+    },
+    handler: async ({ params, user }) => {
+      return this.workflowService.cancelExecution(params.id, {
+        cancelledBy: user?.id,
+        cancelledByName: user?.name,
+      });
+    },
+  });
+
+  public readonly retryExecution = $action({
+    method: "POST",
+    path: `${this.url}/executions/:id/retry`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:workflow:update"] })],
+    schema: {
+      params: t.object({
+        id: t.uuid(),
+      }),
+      response: okSchema,
+    },
+    handler: async ({ params }) => {
+      return this.workflowService.retryExecution(params.id);
+    },
+  });
+
+  public readonly restartExecution = $action({
+    method: "POST",
+    path: `${this.url}/executions/:id/restart`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:workflow:create"] })],
+    schema: {
+      params: t.object({
+        id: t.uuid(),
+      }),
+      response: t.object({ id: t.uuid() }),
+    },
+    handler: async ({ params }) => {
+      return this.workflowService.restartExecution(params.id);
+    },
+  });
+
+  public readonly compensateExecution = $action({
+    method: "POST",
+    path: `${this.url}/executions/:id/compensate`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:workflow:update"] })],
+    schema: {
+      params: t.object({
+        id: t.uuid(),
+      }),
+      response: okSchema,
+    },
+    handler: async ({ params }) => {
+      return this.workflowService.compensateExecution(params.id);
+    },
+  });
+}

package/src/api/workflows/entities/workflowExecutions.ts

@@ -0,0 +1,74 @@
+import { type Static, t } from "alepha";
+import { $entity, db, sql } from "alepha/orm";
+
+export const workflowExecutions = $entity({
+  name: "workflow_executions",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+
+    workflowName: t.text(),
+    tags: t.optional(t.array(t.text())),
+
+    payload: t.optional(t.record(t.text(), t.any())),
+
+    status: db.default(
+      t.enum([
+        "pending",
+        "running",
+        "waiting_for_signal",
+        "completed",
+        "failed",
+        "timed_out",
+        "compensating",
+        "compensated",
+        "compensation_failed",
+        "cancelled",
+      ]),
+      "pending",
+    ),
+    currentStep: t.optional(t.text()),
+
+    startedAt: t.optional(t.datetime()),
+    completedAt: t.optional(t.datetime()),
+    deadlineAt: t.optional(t.datetime()),
+
+    error: t.optional(t.text()),
+    errorStep: t.optional(t.text()),
+
+    triggeredBy: t.optional(t.text()),
+    triggeredByName: t.optional(t.text()),
+    cancelledBy: t.optional(t.text()),
+    cancelledByName: t.optional(t.text()),
+
+    key: t.optional(t.nullable(t.text())),
+
+    priority: db.default(t.integer({ minimum: 0, maximum: 3 }), 2),
+  }),
+  indexes: [
+    { columns: ["workflowName", "status"] },
+    { columns: ["workflowName", "status", "createdAt"] },
+    {
+      columns: ["workflowName", "key"],
+      unique: true,
+      where: sql`status NOT IN ('completed', 'failed', 'compensated', 'compensation_failed', 'cancelled')`,
+    },
+    { columns: ["status", "deadlineAt"] },
+    { columns: ["completedAt"] },
+  ],
+});
+
+export type WorkflowExecutionEntity = Static<typeof workflowExecutions.schema>;
+
+export type WorkflowStatus =
+  | "pending"
+  | "running"
+  | "waiting_for_signal"
+  | "completed"
+  | "failed"
+  | "timed_out"
+  | "compensating"
+  | "compensated"
+  | "compensation_failed"
+  | "cancelled";

package/src/api/workflows/entities/workflowStepExecutions.ts

@@ -0,0 +1,74 @@
+import { type Static, t } from "alepha";
+import { $entity, db } from "alepha/orm";
+import { workflowExecutions } from "./workflowExecutions.ts";
+
+export const workflowStepExecutions = $entity({
+  name: "workflow_step_executions",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+
+    workflowExecutionId: db.ref(t.uuid(), () => workflowExecutions.cols.id, {
+      onDelete: "cascade",
+    }),
+
+    stepName: t.text(),
+    stepIndex: t.integer(),
+    stepType: db.default(t.enum(["handler", "signal", "parallel"]), "handler"),
+
+    parentStepId: t.optional(t.uuid()),
+    branchName: t.optional(t.text()),
+
+    status: db.default(
+      t.enum([
+        "pending",
+        "running",
+        "completed",
+        "failed",
+        "skipped",
+        "waiting",
+        "compensating",
+        "compensated",
+        "compensation_failed",
+        "cancelled",
+      ]),
+      "pending",
+    ),
+    attempt: db.default(t.integer(), 0),
+    maxAttempts: db.default(t.integer(), 1),
+
+    result: t.optional(t.record(t.text(), t.any())),
+    error: t.optional(t.text()),
+
+    startedAt: t.optional(t.datetime()),
+    completedAt: t.optional(t.datetime()),
+    deadlineAt: t.optional(t.datetime()),
+
+    signalPayload: t.optional(t.record(t.text(), t.any())),
+    signalledBy: t.optional(t.text()),
+    signalledAt: t.optional(t.datetime()),
+  }),
+  indexes: [
+    { columns: ["workflowExecutionId", "stepName"] },
+    { columns: ["workflowExecutionId", "stepIndex"] },
+    { columns: ["workflowExecutionId", "status"] },
+    { columns: ["status", "deadlineAt"] },
+  ],
+});
+
+export type WorkflowStepExecutionEntity = Static<
+  typeof workflowStepExecutions.schema
+>;
+
+export type WorkflowStepStatus =
+  | "pending"
+  | "running"
+  | "completed"
+  | "failed"
+  | "skipped"
+  | "waiting"
+  | "compensating"
+  | "compensated"
+  | "compensation_failed"
+  | "cancelled";

package/src/api/workflows/entities/workflowStepLogs.ts

@@ -0,0 +1,13 @@
+import { type Static, t } from "alepha";
+import { logEntrySchema } from "alepha/logger";
+import { $entity, db } from "alepha/orm";
+
+export const workflowStepLogs = $entity({
+  name: "workflow_step_logs",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    logs: t.array(logEntrySchema),
+  }),
+});
+
+export type WorkflowStepLogEntity = Static<typeof workflowStepLogs.schema>;

package/src/api/workflows/index.browser.ts

@@ -0,0 +1,22 @@
+import { $module } from "alepha";
+
+// -----------------------------------------------------------------------------------------------------------------
+
+export * from "./entities/workflowExecutions.ts";
+export * from "./entities/workflowStepExecutions.ts";
+export * from "./entities/workflowStepLogs.ts";
+export * from "./schemas/workflowActivitySchema.ts";
+export * from "./schemas/workflowConfigAtom.ts";
+export * from "./schemas/workflowExecutionDetailSchema.ts";
+export * from "./schemas/workflowExecutionQuerySchema.ts";
+export * from "./schemas/workflowExecutionResourceSchema.ts";
+export * from "./schemas/workflowRegistrationSchema.ts";
+export * from "./schemas/workflowStatsSchema.ts";
+export * from "./schemas/workflowStepExecutionResourceSchema.ts";
+
+// -----------------------------------------------------------------------------------------------------------------
+
+export const AlephaApiWorkflows = $module({
+  name: "alepha.api.workflows",
+  services: [],
+});

package/src/api/workflows/index.ts

@@ -0,0 +1,124 @@
+import { $module, type Alepha } from "alepha";
+import { AlephaApiJobs } from "alepha/api/jobs";
+import { AlephaLock } from "alepha/lock";
+import { AdminWorkflowController } from "./controllers/AdminWorkflowController.ts";
+import { WorkflowJobs } from "./jobs/WorkflowJobs.ts";
+import { $workflow } from "./primitives/$workflow.ts";
+import { WorkflowProvider } from "./providers/WorkflowProvider.ts";
+import { WorkflowService } from "./services/WorkflowService.ts";
+
+// -----------------------------------------------------------------------------------------------------------------
+
+export * from "./controllers/AdminWorkflowController.ts";
+export * from "./entities/workflowExecutions.ts";
+export * from "./entities/workflowStepExecutions.ts";
+export * from "./entities/workflowStepLogs.ts";
+export * from "./primitives/$workflow.ts";
+export * from "./providers/WorkflowProvider.ts";
+export * from "./schemas/workflowActivitySchema.ts";
+export * from "./schemas/workflowConfigAtom.ts";
+export * from "./schemas/workflowExecutionDetailSchema.ts";
+export * from "./schemas/workflowExecutionQuerySchema.ts";
+export * from "./schemas/workflowExecutionResourceSchema.ts";
+export * from "./schemas/workflowRegistrationSchema.ts";
+export * from "./schemas/workflowStatsSchema.ts";
+export * from "./schemas/workflowStepExecutionResourceSchema.ts";
+export * from "./services/WorkflowService.ts";
+
+// -----------------------------------------------------------------------------------------------------------------
+
+declare module "alepha" {
+  interface Hooks {
+    "workflow:started": { workflowName: string; workflowId: string };
+    "workflow:step:begin": {
+      workflowName: string;
+      workflowId: string;
+      stepName: string;
+    };
+    "workflow:step:completed": {
+      workflowName: string;
+      workflowId: string;
+      stepName: string;
+      result: unknown;
+    };
+    "workflow:step:failed": {
+      workflowName: string;
+      workflowId: string;
+      stepName: string;
+      error: Error;
+    };
+    "workflow:step:skipped": {
+      workflowName: string;
+      workflowId: string;
+      stepName: string;
+    };
+    "workflow:signal:received": {
+      workflowName: string;
+      workflowId: string;
+      stepName: string;
+      payload: unknown;
+    };
+    "workflow:signal:timeout": {
+      workflowName: string;
+      workflowId: string;
+      stepName: string;
+    };
+    "workflow:completed": { workflowName: string; workflowId: string };
+    "workflow:failed": {
+      workflowName: string;
+      workflowId: string;
+      error: Error;
+      stepName: string;
+    };
+    "workflow:compensating": {
+      workflowName: string;
+      workflowId: string;
+      stepName: string;
+    };
+    "workflow:compensated": { workflowName: string; workflowId: string };
+    "workflow:compensation:failed": {
+      workflowName: string;
+      workflowId: string;
+      stepName: string;
+      error: Error;
+    };
+    "workflow:cancelled": { workflowName: string; workflowId: string };
+    "workflow:timed_out": { workflowName: string; workflowId: string };
+  }
+}
+
+// -----------------------------------------------------------------------------------------------------------------
+
+/**
+ * Durable workflow engine for long-running business processes.
+ *
+ * **Features:**
+ * - Declarative, multi-step workflows with typed payloads
+ * - Saga-pattern compensation for failure recovery
+ * - Per-step retry with exponential backoff
+ * - Workflow-level timeout and cancellation
+ * - Deduplication via unique keys
+ * - Per-execution log capture
+ *
+ * @module alepha.api.workflows
+ */
+export const AlephaApiWorkflows = $module({
+  name: "alepha.api.workflows",
+  primitives: [$workflow],
+  services: [
+    AlephaApiJobs,
+    AlephaLock,
+    WorkflowProvider,
+    WorkflowService,
+    WorkflowJobs,
+    AdminWorkflowController,
+  ],
+  register: (alepha: Alepha) => {
+    alepha.with(AlephaApiJobs);
+    alepha.with(AlephaLock);
+    alepha.with(WorkflowProvider);
+    alepha.with(WorkflowService);
+    alepha.with(WorkflowJobs);
+    alepha.with(AdminWorkflowController);
+  },
+});

package/src/api/workflows/jobs/WorkflowJobs.ts

@@ -0,0 +1,77 @@
+import { $hook, $inject, t } from "alepha";
+import { $job } from "alepha/api/jobs";
+import { WorkflowProvider } from "../providers/WorkflowProvider.ts";
+
+// -----------------------------------------------------------------------------------------------------------------
+
+export class WorkflowJobs {
+  protected readonly workflowProvider = $inject(WorkflowProvider);
+
+  protected readonly dispatchStep = $job({
+    schema: t.object({
+      workflowId: t.uuid(),
+      stepName: t.text(),
+    }),
+    retry: { retries: 2, backoff: [1, "second"] },
+    timeout: [10, "minute"],
+    concurrency: 10,
+    handler: async ({ items }) => {
+      for (const item of items) {
+        await this.workflowProvider.processStep(
+          item.payload.workflowId,
+          item.payload.stepName,
+        );
+      }
+    },
+  });
+
+  protected readonly timeoutSweep = $job({
+    cron: "* * * * *",
+    lock: true,
+    handler: async () => {
+      await this.workflowProvider.timeoutSweep();
+    },
+  });
+
+  protected readonly purge = $job({
+    cron: "0 3 * * *",
+    lock: true,
+    handler: async () => {
+      await this.workflowProvider.purge();
+    },
+  });
+
+  protected readonly recoverySweep = $job({
+    cron: "*/5 * * * *",
+    lock: true,
+    handler: async () => {
+      await this.workflowProvider.recoverySweep();
+    },
+  });
+
+  protected readonly onStart = $hook({
+    on: "start",
+    handler: async () => {
+      // Wire up queue dispatch
+      this.workflowProvider.stepDispatch = async (
+        workflowId,
+        stepName,
+        priority,
+      ) => {
+        const priorityMap: Record<
+          number,
+          "critical" | "high" | "normal" | "low"
+        > = {
+          0: "critical",
+          1: "high",
+          2: "normal",
+          3: "low",
+        };
+        await this.dispatchStep.push(
+          { workflowId, stepName },
+          { priority: priorityMap[priority] ?? "normal" },
+        );
+      };
+    },
+  });
+}