alepha 0.20.1 → 0.20.2

package/src/api/jobs/controllers/AdminJobController.ts

@@ -1,210 +1,101 @@
 import { $inject, t } from "alepha";
 import { $secure } from "alepha/security";
 import { $action, okSchema } from "alepha/server";
-import {
-  jobActivityPointSchema,
-  jobActivityQuerySchema,
-} from "../schemas/jobActivitySchema.ts";
-import { jobCronInfoSchema } from "../schemas/jobCronInfoSchema.ts";
-import { jobExecutionDetailResourceSchema } from "../schemas/jobExecutionDetailResourceSchema.ts";
 import { jobExecutionQuerySchema } from "../schemas/jobExecutionQuerySchema.ts";
 import { jobExecutionResourceSchema } from "../schemas/jobExecutionResourceSchema.ts";
-import { jobFailureSchema } from "../schemas/jobFailureSchema.ts";
-import { jobQueueDepthSchema } from "../schemas/jobQueueDepthSchema.ts";
 import { jobRegistrationSchema } from "../schemas/jobRegistrationSchema.ts";
-import { jobStatsSchema } from "../schemas/jobStatsSchema.ts";
 import { triggerJobSchema } from "../schemas/triggerJobSchema.ts";
 import { JobService } from "../services/JobService.ts";
 
+/**
+ * Minimal admin surface for the job system. Six endpoints.
+ */
 export class AdminJobController {
   protected readonly url: string = "/jobs";
   protected readonly group: string = "admin:jobs";
   protected readonly jobService = $inject(JobService);
 
-  public readonly getJobStats = $action({
-    path: `${this.url}/stats`,
-    group: this.group,
-    use: [$secure({ permissions: ["admin:job:read"] })],
-    schema: {
-      query: jobActivityQuerySchema,
-      response: jobStatsSchema,
-    },
-    handler: ({ query }) => this.jobService.getStats(query.days),
-  });
-
-  public readonly getJobRegistry = $action({
+  public readonly listJobs = $action({
     path: this.url,
     group: this.group,
     use: [$secure({ permissions: ["admin:job:read"] })],
     schema: {
       response: t.array(jobRegistrationSchema),
     },
-    handler: () => this.jobService.getRegistry(),
+    handler: () => this.jobService.listJobs(),
   });
 
-  public readonly findJobExecutions = $action({
-    path: `${this.url}/executions`,
+  public readonly listExecutions = $action({
+    path: `${this.url}/:name/executions`,
     group: this.group,
     use: [$secure({ permissions: ["admin:job:read"] })],
     schema: {
+      params: t.object({ name: t.text() }),
       query: jobExecutionQuerySchema,
-      response: t.page(jobExecutionResourceSchema),
+      response: t.array(jobExecutionResourceSchema),
     },
-    handler: ({ query }) => this.jobService.findExecutions(query),
+    handler: ({ params, query }) =>
+      this.jobService.getExecutions(params.name, query),
   });
 
-  public readonly getJobExecution = $action({
+  public readonly getExecution = $action({
     path: `${this.url}/executions/:id`,
     group: this.group,
     use: [$secure({ permissions: ["admin:job:read"] })],
     schema: {
-      params: t.object({
-        id: t.uuid(),
-      }),
-      response: jobExecutionDetailResourceSchema,
+      params: t.object({ id: t.uuid() }),
+      response: jobExecutionResourceSchema,
     },
     handler: ({ params }) => this.jobService.getExecution(params.id),
   });
 
   public readonly triggerJob = $action({
     method: "POST",
-    path: `${this.url}/trigger`,
+    path: `${this.url}/:name/trigger`,
     group: this.group,
     use: [$secure({ permissions: ["admin:job:trigger"] })],
     schema: {
+      params: t.object({ name: t.text() }),
       body: triggerJobSchema,
       response: okSchema,
     },
-    handler: async ({ body, user }) => {
-      return this.jobService.triggerJob(body.name, {
+    handler: ({ params, body, user }) =>
+      this.jobService.triggerJob(params.name, {
         payload: body.payload,
         triggeredBy: user?.id,
         triggeredByName: user?.name,
-      });
-    },
+      }),
   });
 
-  public readonly retryJobExecution = $action({
+  public readonly retryExecution = $action({
     method: "POST",
     path: `${this.url}/executions/:id/retry`,
     group: this.group,
     use: [$secure({ permissions: ["admin:job:trigger"] })],
     schema: {
-      params: t.object({
-        id: t.uuid(),
-      }),
+      params: t.object({ id: t.uuid() }),
       response: okSchema,
     },
-    handler: async ({ params, user }) => {
-      return this.jobService.retryExecution(params.id, {
+    handler: ({ params, user }) =>
+      this.jobService.retryExecution(params.id, {
         triggeredBy: user?.id,
         triggeredByName: user?.name,
-      });
-    },
+      }),
   });
 
-  public readonly cancelJobExecution = $action({
+  public readonly cancelExecution = $action({
     method: "POST",
     path: `${this.url}/executions/:id/cancel`,
     group: this.group,
     use: [$secure({ permissions: ["admin:job:cancel"] })],
     schema: {
-      params: t.object({
-        id: t.uuid(),
-      }),
+      params: t.object({ id: t.uuid() }),
       response: okSchema,
     },
-    handler: async ({ params, user }) => {
-      return this.jobService.cancelExecution(params.id, {
+    handler: ({ params, user }) =>
+      this.jobService.cancelExecution(params.id, {
         cancelledBy: user?.id,
         cancelledByName: user?.name,
-      });
-    },
-  });
-
-  public readonly getJobActivity = $action({
-    path: `${this.url}/activity`,
-    group: this.group,
-    use: [$secure({ permissions: ["admin:job:read"] })],
-    schema: {
-      query: jobActivityQuerySchema,
-      response: t.array(jobActivityPointSchema),
-    },
-    handler: ({ query }) => this.jobService.getActivity(query.days),
-  });
-
-  public readonly getCronJobs = $action({
-    path: `${this.url}/cron`,
-    group: this.group,
-    use: [$secure({ permissions: ["admin:job:read"] })],
-    schema: {
-      response: t.array(jobCronInfoSchema),
-    },
-    handler: () => this.jobService.getCronJobs(),
-  });
-
-  public readonly getJobQueueDepth = $action({
-    path: `${this.url}/queue`,
-    group: this.group,
-    use: [$secure({ permissions: ["admin:job:read"] })],
-    schema: {
-      response: t.array(jobQueueDepthSchema),
-    },
-    handler: () => this.jobService.getQueueDepth(),
-  });
-
-  public readonly getJobTopFailures = $action({
-    path: `${this.url}/failures`,
-    group: this.group,
-    use: [$secure({ permissions: ["admin:job:read"] })],
-    schema: {
-      query: jobActivityQuerySchema,
-      response: t.array(jobFailureSchema),
-    },
-    handler: ({ query }) => this.jobService.getTopFailures(query.days),
-  });
-
-  public readonly pauseJob = $action({
-    method: "POST",
-    path: `${this.url}/pause`,
-    group: this.group,
-    use: [$secure({ permissions: ["admin:job:trigger"] })],
-    schema: {
-      body: t.object({ name: t.text() }),
-      response: okSchema,
-    },
-    handler: ({ body, user }) => {
-      return this.jobService.pauseJob(body.name, {
-        pausedBy: user?.id,
-        pausedByName: user?.name,
-      });
-    },
-  });
-
-  public readonly resumeJob = $action({
-    method: "POST",
-    path: `${this.url}/resume`,
-    group: this.group,
-    use: [$secure({ permissions: ["admin:job:trigger"] })],
-    schema: {
-      body: t.object({ name: t.text() }),
-      response: okSchema,
-    },
-    handler: async ({ body, user }) => {
-      return this.jobService.resumeJob(body.name, {
-        resumedBy: user?.id,
-        resumedByName: user?.name,
-      });
-    },
-  });
-
-  public readonly getPausedJobs = $action({
-    path: `${this.url}/paused`,
-    group: this.group,
-    use: [$secure({ permissions: ["admin:job:read"] })],
-    schema: {
-      response: t.array(t.text()),
-    },
-    handler: () => this.jobService.getPausedJobs(),
+      }),
   });
 }

package/src/api/jobs/entities/jobExecutionEntity.ts

@@ -1,6 +1,24 @@
 import { type Static, t } from "alepha";
+import { logEntrySchema } from "alepha/logger";
 import { $entity, db } from "alepha/orm";
 
+/**
+ * Job execution record.
+ *
+ * Stores durable state for queue-mode jobs (outbox pattern) and error records
+ * for cron-mode jobs. Successful executions are trimmed by the sweep to keep
+ * the last N rows per job (configurable via `jobConfig.keepLastSuccess`).
+ *
+ * Status transitions:
+ * - queue push            → pending
+ * - worker claim          → running
+ * - success               → ok
+ * - terminal failure      → error
+ * - retry                 → scheduled (with scheduledAt = now + backoff)
+ * - delay                 → scheduled (with scheduledAt = now + delay)
+ * - sweep picks due ones  → pending
+ * - cancel                → cancelled
+ */
 export const jobExecutionEntity = $entity({
   name: "job_executions",
   schema: t.object({
@@ -11,17 +29,8 @@ export const jobExecutionEntity = $entity({
     jobName: t.text(),
     key: t.optional(t.nullable(t.text())),
 
-    payload: t.optional(t.record(t.text(), t.any())),
     status: db.default(
-      t.enum([
-        "pending",
-        "scheduled",
-        "retrying",
-        "running",
-        "completed",
-        "dead",
-        "cancelled",
-      ]),
+      t.enum(["pending", "running", "scheduled", "ok", "error", "cancelled"]),
       "pending",
     ),
     priority: db.default(t.integer({ minimum: 0, maximum: 3 }), 2),
@@ -29,13 +38,14 @@ export const jobExecutionEntity = $entity({
     attempt: db.default(t.integer(), 0),
     maxAttempts: db.default(t.integer(), 1),
 
+    payload: t.optional(t.record(t.text(), t.any())),
+
     scheduledAt: t.optional(t.datetime()),
     startedAt: t.optional(t.datetime()),
     completedAt: t.optional(t.datetime()),
 
-    result: t.optional(t.record(t.text(), t.any())),
     error: t.optional(t.text()),
-    workerId: t.optional(t.text()),
+    logs: t.optional(t.array(logEntrySchema)),
 
     triggeredBy: t.optional(t.text()),
     triggeredByName: t.optional(t.text()),
@@ -43,9 +53,8 @@ export const jobExecutionEntity = $entity({
     cancelledByName: t.optional(t.text()),
   }),
   indexes: [
-    { columns: ["jobName", "status", "priority", "scheduledAt"] },
-    { columns: ["jobName", "status", "startedAt"] },
-    { columns: ["jobName", "completedAt"] },
+    { columns: ["jobName", "status", "scheduledAt"] },
+    { columns: ["jobName", "startedAt"] },
     { columns: ["jobName", "key"], unique: true },
   ],
 });
@@ -54,9 +63,8 @@ export type JobExecutionEntity = Static<typeof jobExecutionEntity.schema>;
 
 export type JobStatus =
   | "pending"
-  | "scheduled"
-  | "retrying"
   | "running"
-  | "completed"
-  | "dead"
+  | "scheduled"
+  | "ok"
+  | "error"
   | "cancelled";

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

@@ -3,17 +3,10 @@ import { $module } from "alepha";
 // -----------------------------------------------------------------------------------------------------------------
 
 export * from "./entities/jobExecutionEntity.ts";
-export * from "./entities/jobExecutionLogEntity.ts";
-export * from "./schemas/jobActivitySchema.ts";
 export * from "./schemas/jobConfigAtom.ts";
-export * from "./schemas/jobCronInfoSchema.ts";
-export * from "./schemas/jobExecutionDetailResourceSchema.ts";
 export * from "./schemas/jobExecutionQuerySchema.ts";
 export * from "./schemas/jobExecutionResourceSchema.ts";
-export * from "./schemas/jobFailureSchema.ts";
-export * from "./schemas/jobQueueDepthSchema.ts";
 export * from "./schemas/jobRegistrationSchema.ts";
-export * from "./schemas/jobStatsSchema.ts";
 export * from "./schemas/triggerJobSchema.ts";
 
 // -----------------------------------------------------------------------------------------------------------------
@@ -22,3 +15,8 @@ export const AlephaApiJobs = $module({
   name: "alepha.api.jobs",
   services: [],
 });
+
+export const AlephaApiJobsQueue = $module({
+  name: "alepha.api.jobs.queue",
+  services: [],
+});

package/src/api/jobs/index.ts

@@ -1,4 +1,4 @@
-import { $module, type Alepha, type Static, t } from "alepha";
+import { $module } from "alepha";
 import type { DateTime } from "alepha/datetime";
 import { AlephaLock } from "alepha/lock";
 import { AlephaQueue } from "alepha/queue";
@@ -12,28 +12,19 @@ import { JobService } from "./services/JobService.ts";
 
 export * from "./controllers/AdminJobController.ts";
 export * from "./entities/jobExecutionEntity.ts";
-export * from "./entities/jobExecutionLogEntity.ts";
 export * from "./primitives/$job.ts";
 export * from "./providers/JobProvider.ts";
 export * from "./providers/JobQueueProvider.ts";
-export * from "./schemas/jobActivitySchema.ts";
 export * from "./schemas/jobConfigAtom.ts";
-export * from "./schemas/jobCronInfoSchema.ts";
-export * from "./schemas/jobExecutionDetailResourceSchema.ts";
 export * from "./schemas/jobExecutionQuerySchema.ts";
 export * from "./schemas/jobExecutionResourceSchema.ts";
-export * from "./schemas/jobFailureSchema.ts";
-export * from "./schemas/jobQueueDepthSchema.ts";
 export * from "./schemas/jobRegistrationSchema.ts";
-export * from "./schemas/jobStatsSchema.ts";
 export * from "./schemas/triggerJobSchema.ts";
 export * from "./services/JobService.ts";
 
 // -----------------------------------------------------------------------------------------------------------------
 
 declare module "alepha" {
-  interface Env extends Partial<Static<typeof jobEnvSchema>> {}
-
   interface Hooks {
     "job:begin": { name: string; now: DateTime; executionId: string };
     "job:success": { name: string; executionId: string };
@@ -45,34 +36,17 @@ declare module "alepha" {
 
 // -----------------------------------------------------------------------------------------------------------------
 
-const jobEnvSchema = t.object({
-  /**
-   * Controls whether the job system dispatches work through a queue or executes inline.
-   *
-   * - `1` — always use queue (force queue even in serverless)
-   * - `0` — never use queue (force inline, useful for testing)
-   * - not set — auto: use queue when NOT serverless (default)
-   */
-  ALEPHA_JOBS_QUEUE: t.optional(
-    t.integer({
-      description:
-        "Set to 1 to always use queue, 0 to disable queue (default: auto-detect based on environment)",
-    }),
-  ),
-});
-
-// -----------------------------------------------------------------------------------------------------------------
-
 /**
- * Job execution framework — unified primitive for deferred, scheduled, and queued work.
+ * Job execution framework — cron and durable queue work with a single primitive.
+ *
+ * A `$job` is either **cron-only** (declares `cron`) or **queue-only** (declares `schema`).
+ * Cron jobs run inline on their schedule and only record errors by default.
+ * Queue jobs use the outbox pattern: push commits to DB first, then notifies via queue.
  *
- * **Features:**
- * - Push-based jobs with typed payloads
- * - Cron scheduling with execution tracking
- * - Retry with exponential backoff
- * - Priority, delay, cancellation
- * - Deduplication via unique keys
- * - Per-execution log capture
+ * **This module provides cron support only.** To enable queue-mode jobs, also
+ * import {@link AlephaApiJobsQueue} — it brings in the queue layer and infrastructure
+ * binding (e.g. Cloudflare Queues). Cron-only deployments (Vercel, CF-without-Queues)
+ * do not need `AlephaApiJobsQueue`.
  *
  * @module alepha.api.jobs
  */
@@ -80,20 +54,18 @@ export const AlephaApiJobs = $module({
   name: "alepha.api.jobs",
   imports: [AlephaScheduler, AlephaLock],
   services: [JobProvider, JobService, AdminJobController],
-  // AlephaQueue + JobQueueProvider are conditional — injected only when queue is enabled.
-  variants: [JobQueueProvider],
-  register: (alepha: Alepha) => {
-    const env = alepha.parseEnv(jobEnvSchema);
-    const useQueue =
-      env.ALEPHA_JOBS_QUEUE === 1
-        ? true
-        : env.ALEPHA_JOBS_QUEUE === 0
-          ? false
-          : !alepha.isServerless();
+});
 
-    if (useQueue) {
-      alepha.with(AlephaQueue);
-      alepha.with(JobQueueProvider);
-    }
-  },
+/**
+ * Queue support for `$job`. Import alongside {@link AlephaApiJobs} when your
+ * app declares queue-mode jobs (any `$job` with a `schema`).
+ *
+ * Adds `JobQueueProvider` which plumbs the outbox dispatch through `AlephaQueue`.
+ *
+ * @module alepha.api.jobs.queue
+ */
+export const AlephaApiJobsQueue = $module({
+  name: "alepha.api.jobs.queue",
+  imports: [AlephaApiJobs, AlephaQueue],
+  services: [JobQueueProvider],
 });

package/src/api/jobs/primitives/$job.ts

@@ -17,7 +17,12 @@ import {
 } from "../providers/JobProvider.ts";
 
 /**
- * Job primitive for defining scheduled and on-demand tasks with payload validation and retry policies.
+ * Job primitive for defining scheduled (cron) or queued (push) tasks.
+ *
+ * A job must be either **cron-only** (pass `cron`) or **queue-only**
+ * (pass `schema`), never both. To run scheduled work that processes
+ * payloads, compose two jobs: a cron that pushes payloads, and a
+ * queue job that handles them.
  */
 export const $job = <T extends TSchema = TSchema>(
   options: JobPrimitiveOptions<T>,
@@ -27,16 +32,12 @@ export const $job = <T extends TSchema = TSchema>(
 
 // -----------------------------------------------------------------------------------------------------------------
 
-export interface JobItem<T extends TSchema = TSchema> {
-  id: string;
+export interface JobHandlerArgs<T extends TSchema = TSchema> {
   payload: Static<T>;
   attempt: number;
-}
-
-export interface JobHandlerArgs<T extends TSchema = TSchema> {
-  items: Array<JobItem<T>>;
   now: DateTime;
   signal: AbortSignal;
+  executionId: string;
 }
 
 export interface JobRetryBackoff {
@@ -57,45 +58,75 @@ export type JobPriority = "critical" | "high" | "normal" | "low";
 export interface JobPrimitiveOptions<T extends TSchema = TSchema>
   extends PipelinePrimitiveOptions {
   /**
-   * Payload schema (TypeBox). Optional for cron-only jobs.
+   * Optional explicit job name. Defaults to `ClassName.propertyKey`.
+   * Recommended convention for framework-internal jobs: `api:module:jobName`.
    */
-  schema?: T;
+  name?: string;
 
   /**
-   * Cron expression for automatic scheduling.
+   * Human-readable description (shown in the admin UI).
    */
-  cron?: string;
+  description?: string;
 
   /**
-   * Whether to use a distributed lock for cron execution.
-   * @default true
+   * Payload schema (TypeBox). When set, the job is queue-mode.
+   * Must not be combined with `cron`.
    */
-  lock?: boolean;
+  schema?: T;
 
   /**
-   * Retry policy for failed executions.
+   * Cron expression for recurring execution. When set, the job is cron-mode.
+   * Must not be combined with `schema`.
    */
-  retry?: JobRetryOptions;
+  cron?: string;
 
   /**
-   * Max execution time per attempt.
+   * Retry policy for queue-mode jobs.
+   * Cron-mode jobs do not retry — the next tick re-runs.
    */
-  timeout?: DurationLike;
+  retry?: JobRetryOptions;
 
   /**
-   * Max parallel executions.
-   * @default 1
+   * Max execution time per attempt. Handler receives an `AbortSignal`.
    */
-  concurrency?: number;
+  timeout?: DurationLike;
 
   /**
-   * Default priority for pushed jobs.
+   * Default priority for pushed jobs. Used by the sweep to order
+   * dispatch when there is a backlog. Real-time queue consumption
+   * is FIFO.
    * @default "normal"
    */
   priority?: JobPriority;
 
   /**
-   * Handler function for job execution.
+   * Whether to record successful executions.
+   *
+   * - `"error"` (default for cron, default for queue): only error/cancelled rows kept
+   * - `"all"`: keep success rows too (bounded by `keepLastSuccess`)
+   * - `"none"`: fire-and-forget, no row even on error
+   *
+   * Note: queue-mode jobs always write a `pending` row at push time (outbox).
+   * This setting controls whether that row is kept on success.
+   */
+  record?: "error" | "all" | "none";
+
+  /**
+   * Override the global ring-buffer trim for this job.
+   *
+   * - `{ ok: 0, error: 0 }` — **keep forever** (no sweep trim). Useful for
+   *   audit-heavy jobs where retention is time-based (handled by a separate
+   *   cron) rather than count-based.
+   * - `{ ok: 50 }` — keep last 50 successes; fall back to global default for errors.
+   * - omitted — use global `keepLastSuccess` / `keepLastError` from `jobConfig`.
+   */
+  keep?: {
+    ok?: number;
+    error?: number;
+  };
+
+  /**
+   * Handler function. For cron-mode, `payload` is `undefined`.
    */
   handler: (args: JobHandlerArgs<T>) => Async<void>;
 }
@@ -108,7 +139,10 @@ export class JobPrimitive<
   protected readonly jobProvider = $inject(JobProvider);
 
   public get name(): string {
-    return `${this.config.service.name}.${this.config.propertyKey}`;
+    return (
+      this.options.name ??
+      `${this.config.service.name}.${this.config.propertyKey}`
+    );
   }
 
   protected onInit() {
@@ -117,62 +151,36 @@ export class JobPrimitive<
   }
 
   /**
-   * Push a single payload or an array of payloads.
+   * Push a single payload to the queue (queue-mode only).
    */
   public async push(
-    payload: Static<T> | Array<Static<T>>,
+    payload: Static<T>,
     options?: PushOptions,
-  ): Promise<string | string[]> {
-    if (Array.isArray(payload)) {
-      const ids = await Promise.all(
-        payload.map((p) => this.jobProvider.push(this.name, p, options)),
-      );
-      return ids;
-    }
+  ): Promise<string> {
     return this.jobProvider.push(this.name, payload, options);
   }
 
   /**
-   * Push multiple payloads with per-item options.
+   * Push multiple payloads at once (queue-mode only).
+   * Batched INSERT + batched queue send when supported.
    */
   public async pushMany(items: Array<PushManyItem<T>>): Promise<string[]> {
     return this.jobProvider.pushMany(this.name, items);
   }
 
   /**
-   * Cancel a running or pending execution.
+   * Cancel a pending or running execution.
    */
   public async cancel(executionId: string): Promise<void> {
     return this.jobProvider.cancel(executionId);
   }
 
   /**
-   * Manually trigger the job (admin / CLI).
+   * Manually fire a cron-mode job, or trigger a queue-mode job with an explicit payload.
    */
-  public async trigger(context?: JobTriggerContext): Promise<void> {
+  public async trigger(context?: JobTriggerContext<T>): Promise<void> {
     return this.jobProvider.trigger(this.name, context);
   }
-
-  /**
-   * Pause this job. Pushed items are still accepted but processing is held.
-   */
-  public pause(): void {
-    this.jobProvider.pauseJob(this.name);
-  }
-
-  /**
-   * Resume a paused job and dispatch any pending items.
-   */
-  public async resume(): Promise<void> {
-    return this.jobProvider.resumeJob(this.name);
-  }
-
-  /**
-   * Whether this job is currently paused.
-   */
-  public get paused(): boolean {
-    return this.jobProvider.isJobPaused(this.name);
-  }
 }
 
 $job[KIND] = JobPrimitive;