alepha 0.20.5 → 0.20.7

package/src/api/jobs/providers/JobQueueProvider.ts

@@ -1,42 +1,67 @@
-import { $inject, t } from "alepha";
+import { $inject, Alepha, t } from "alepha";
 import { $queue } from "alepha/queue";
+import { JobDispatcher } from "./JobDispatcher.ts";
 import { JobProvider } from "./JobProvider.ts";
 
 /**
- * Plumbs outbox-style dispatch through `AlephaQueue`.
+ * Queue-backed `JobDispatcher` registered by `AlephaApiJobsQueue`.
  *
- * Registered only when the app imports `AlephaApiJobsQueue`. Sets
- * `JobProvider.queueDispatch` eagerly at instantiation so queue-mode jobs
- * can dispatch regardless of start-hook ordering.
+ * Extends {@link JobDispatcher} and substitutes the default
+ * `DirectJobDispatcher` so that `$job.push()` is delivered through
+ * `AlephaQueue` (e.g. Cloudflare Queues, Redis, in-memory) instead of
+ * being processed in-process.
+ *
+ * The class is also kept as a `JobQueueProvider` export name for backwards
+ * compatibility — it has always been the queue path's entry point.
  */
-export class JobQueueProvider {
-  protected readonly jobProvider = $inject(JobProvider);
+export class JobQueueProvider extends JobDispatcher {
+  public readonly kind = "queue" as const;
+  protected readonly alepha = $inject(Alepha);
+
+  // Lazy to avoid the JobProvider ↔ JobDispatcher injection cycle
+  // (JobProvider injects JobDispatcher; the queue consumer needs
+  // JobProvider to process). Resolved at message-receive time.
+  protected jobProviderRef?: JobProvider;
+  protected getJobProvider(): JobProvider {
+    if (!this.jobProviderRef) {
+      this.jobProviderRef = this.alepha.inject(JobProvider);
+    }
+    return this.jobProviderRef;
+  }
 
   protected readonly queue = $queue({
     name: "api:jobs:dispatch",
     schema: t.object({ jobName: t.text(), executionId: t.text() }),
     handler: async (msg) => {
-      await this.jobProvider.processExecution(
+      await this.getJobProvider().processExecution(
         msg.payload.jobName,
         msg.payload.executionId,
       );
     },
   });
 
-  constructor() {
-    // Install the dispatcher immediately — before any start hook runs,
-    // so JobProvider can validate presence and queue-mode push works
-    // from any lifecycle point.
-    this.wireDispatcher();
+  public async dispatch(jobName: string, executionId: string): Promise<void> {
+    await this.queue.push({ jobName, executionId });
   }
 
-  protected wireDispatcher(): void {
-    // `$inject` is resolved by the time constructor runs; assignment is safe.
-    this.jobProvider.queueDispatch = (jobName, executionId) =>
-      this.push(jobName, executionId);
+  /**
+   * Fan-out to a single variadic `queue.push(...payloads)` call so the
+   * underlying queue provider can batch the network round-trips when it
+   * supports it (Cloudflare Queues, Redis pipelines).
+   */
+  public override async dispatchMany(
+    items: Array<{ jobName: string; executionId: string }>,
+  ): Promise<void> {
+    if (items.length === 0) return;
+    await this.queue.push(...items);
   }
 
+  /**
+   * Backwards-compatible alias for {@link dispatch}. Older code paths called
+   * `JobQueueProvider.push(jobName, executionId)` directly; new code should
+   * go through the `JobDispatcher.dispatch` API.
+   */
   public async push(jobName: string, executionId: string): Promise<void> {
-    await this.queue.push({ jobName, executionId });
+    return this.dispatch(jobName, executionId);
   }
 }

package/src/api/jobs/schemas/jobConfigAtom.ts

@@ -4,8 +4,13 @@ export const jobConfig = $atom({
   name: "alepha.jobs",
   description: "Configuration for the $job primitive.",
   schema: t.object({
-    sweepInterval: t.integer({
-      description: "Sweep cron interval in milliseconds.",
+    sweepCron: t.text({
+      description:
+        "Cron expression for the sweep tick. Must be minute-granular at minimum (cron resolution). On Cloudflare Workers this expression is emitted into wrangler.jsonc by the build.",
+    }),
+    trimCron: t.text({
+      description:
+        "Cron expression for the ring-buffer trim tick (per-job keepLastSuccess/keepLastError enforcement). Decoupled from `sweepCron` because trim is bounded by job execution rate, not retry latency — running it every sweep is wasted work for most apps.",
     }),
     staleThreshold: t.integer({
       description: "Pending age (ms) before the sweep re-dispatches it.",
@@ -29,7 +34,8 @@ export const jobConfig = $atom({
     }),
   }),
   default: {
-    sweepInterval: 300_000,
+    sweepCron: "*/5 * * * *",
+    trimCron: "0 * * * *",
     staleThreshold: 300_000,
     runTimeout: 1_800_000,
     keepLastSuccess: 10,

package/src/api/jobs/schemas/jobExecutionResourceSchema.ts

@@ -1,9 +1,20 @@
 import { type Static, t } from "alepha";
 import { jobExecutionEntity } from "../entities/jobExecutionEntity.ts";
 
+/**
+ * Public-facing schema for a job execution row.
+ *
+ * Diverges from the raw entity in two places, both for API ergonomics:
+ *
+ * - `priority` is exposed as the **string enum** (`critical`/`high`/...)
+ *   instead of the numeric value used internally for SQL ordering. The
+ *   `JobService` is responsible for the int → string transform.
+ * - `can` derives the available admin actions from the row's status.
+ */
 export const jobExecutionResourceSchema = t.extend(
   jobExecutionEntity.schema,
   {
+    priority: t.enum(["critical", "high", "normal", "low"]),
     can: t.object({
       retry: t.boolean(),
       cancel: t.boolean(),

package/src/api/jobs/schemas/jobRegistrationSchema.ts

@@ -3,14 +3,16 @@ import { type Static, t } from "alepha";
 export const jobRegistrationSchema = t.object({
   name: t.text(),
   description: t.optional(t.text()),
-  type: t.enum(["cron", "queue"]),
+  type: t.enum(["cron", "queue", "direct"], {
+    description:
+      "Effective runtime mode. 'cron' = scheduled. 'queue' = push-driven, dispatched via AlephaApiJobsQueue. 'direct' = push-driven, processed in-process (no queue infrastructure loaded), with the sweep as the safety net.",
+  }),
   priority: t.enum(["critical", "high", "normal", "low"]),
   cron: t.optional(t.text()),
   timeout: t.optional(t.text()),
   retry: t.optional(
     t.object({
       retries: t.integer(),
-      hasBackoff: t.boolean(),
     }),
   ),
   recent: t.object({

package/src/api/jobs/services/JobService.ts

@@ -5,8 +5,9 @@ import { NotFoundError } from "alepha/server";
 import { jobExecutionEntity } from "../entities/jobExecutionEntity.ts";
 import { $job } from "../primitives/$job.ts";
 import type { JobTriggerContext } from "../providers/JobProvider.ts";
-import { JobProvider } from "../providers/JobProvider.ts";
+import { JobProvider, PRIORITY_REVERSE } from "../providers/JobProvider.ts";
 import type { JobExecutionQuery } from "../schemas/jobExecutionQuerySchema.ts";
+import type { JobExecutionResource } from "../schemas/jobExecutionResourceSchema.ts";
 import type { JobRegistration } from "../schemas/jobRegistrationSchema.ts";
 
 /**
@@ -31,6 +32,22 @@ export class JobService {
     };
   }
 
+  /**
+   * Convert the int-priority storage column into the public enum string.
+   * The cast through `unknown` skips TypeScript's structural check between
+   * the entity-level row (`priority: number`) and the resource schema
+   * (`priority: enum`); the runtime values are correct.
+   */
+  protected toResource<T extends { priority: number; status: string }>(
+    row: T,
+  ): JobExecutionResource {
+    return {
+      ...row,
+      priority: PRIORITY_REVERSE[row.priority] ?? "normal",
+      can: this.computeCan(row.status),
+    } as unknown as JobExecutionResource;
+  }
+
   /**
    * List every registered job with recent ok/error counts and lastRun.
    * One aggregate query covers all jobs.
@@ -87,14 +104,13 @@ export class JobService {
       result.push({
         name,
         description: opts.description,
-        type: reg.type,
+        type: this.jobProvider.effectiveMode(name),
         cron: opts.cron,
         priority: (opts.priority ?? "normal") as JobRegistration["priority"],
         timeout: opts.timeout ? String(opts.timeout) : undefined,
         retry: opts.retry
           ? {
               retries: opts.retry.retries,
-              hasBackoff: Boolean(opts.retry.backoff),
             }
           : undefined,
         recent: counts,
@@ -121,10 +137,7 @@ export class JobService {
       orderBy: { column: "startedAt", direction: "desc" },
       limit: query.limit ?? 20,
     });
-    return rows.map((row) => ({
-      ...row,
-      can: this.computeCan(row.status),
-    }));
+    return rows.map((row) => this.toResource(row));
   }
 
   /**
@@ -135,10 +148,7 @@ export class JobService {
     if (!execution) {
       throw new NotFoundError(`Execution not found: ${id}`);
     }
-    return {
-      ...execution,
-      can: this.computeCan(execution.status),
-    };
+    return this.toResource(execution);
   }
 
   /**

package/src/api/keys/controllers/AdminApiKeyController.ts

@@ -73,4 +73,27 @@ export class AdminApiKeyController {
       return { ok: true, id: params.id };
     },
   });
+
+  /**
+   * Revoke many API keys in one request.
+   */
+  public readonly revokeApiKeys = $action({
+    method: "POST",
+    path: `${this.url}/revoke`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:api-key:delete"] })],
+    description: "Revoke many API keys",
+    schema: {
+      body: t.object({
+        ids: t.array(t.uuid(), { minItems: 1, maxItems: 1000 }),
+      }),
+      response: t.object({
+        revoked: t.array(t.uuid()),
+      }),
+    },
+    handler: async ({ body }) => {
+      const revoked = await this.apiKeyService.revokeManyByAdmin(body.ids);
+      return { revoked };
+    },
+  });
 }

package/src/api/keys/entities/apiKeyEntity.ts

@@ -7,6 +7,7 @@ export const apiKeyEntity = $entity({
     id: db.primaryKey(t.uuid()),
     createdAt: db.createdAt(),
     updatedAt: db.updatedAt(),
+    organizationId: db.organization(),
 
     // Owner
     userId: t.uuid(),

package/src/api/keys/services/ApiKeyService.ts

@@ -16,8 +16,21 @@ export class ApiKeyService {
 
   /**
    * Cache validated API keys for 15 minutes.
+   *
+   * Pinned to per-isolate memory:
+   * - The cache replaces a single indexed SELECT on `api_keys`. Routing it
+   *   through a distributed K/V (KV/Redis) buys little — the SELECT is
+   *   already cheap — and pinning to DB would actively trade one SQL read
+   *   for another.
+   * - Cold-start gives a fresh DB read on every new isolate, which is
+   *   *better* for revocation visibility than a distributed cache that
+   *   keeps serving stale entries until its own TTL.
+   * - Avoids provisioning KV/Redis just for this one cache. Users who need
+   *   cross-isolate sharing for high-throughput API auth can override
+   *   globally via `alepha.with({ provide: CacheProvider, use: ... })`.
    */
   protected readonly validationCache = $cache<ApiKeyEntity | null, [string]>({
+    provider: "memory",
     name: "api:keys:validation",
     ttl: [15, "minutes"],
   });
@@ -180,6 +193,35 @@ export class ApiKeyService {
     });
   }
 
+  /**
+   * Revoke many API keys in one repository call (admin only). Already-revoked
+   * keys are silently skipped. Returns the ids that were actually revoked.
+   */
+  public async revokeManyByAdmin(ids: string[]): Promise<string[]> {
+    if (ids.length === 0) return [];
+
+    const keys = await this.repo.findMany({
+      where: { id: { inArray: ids } },
+      columns: ["id", "tokenHash", "revokedAt"],
+    });
+    const toRevoke = keys.filter((k) => !k.revokedAt);
+    if (toRevoke.length === 0) return [];
+
+    await Promise.all(
+      toRevoke.map((k) => this.validationCache.invalidate(k.tokenHash)),
+    );
+
+    await this.repo.updateMany(
+      { id: { inArray: toRevoke.map((k) => k.id) } },
+      {
+        revokedAt: this.dateTimeProvider.now().toISOString(),
+      },
+    );
+
+    this.log.info("API keys revoked by admin", { count: toRevoke.length });
+    return toRevoke.map((k) => k.id);
+  }
+
   // -------------------------------------------------------------------------
   // User Operations
   // -------------------------------------------------------------------------

package/src/api/notifications/__tests__/AlephaApiNotifications.spec.ts

@@ -0,0 +1,63 @@
+import { Alepha, t } from "alepha";
+import { AlephaApiJobs, JobProvider } from "alepha/api/jobs";
+import { AlephaEmail, MemoryEmailProvider } from "alepha/email";
+import { AlephaOrmPostgres } from "alepha/orm/postgres";
+import { AlephaSms } from "alepha/sms";
+import { describe, it } from "vitest";
+import {
+  $notification,
+  AlephaApiNotifications,
+  NotificationJobs,
+} from "../index.ts";
+
+/**
+ * The notifications module historically forced `AlephaApiJobsQueue`. After
+ * the direct-mode change it must boot without any queue infrastructure and
+ * deliver via direct mode (push → process in-process → row removed on success).
+ */
+describe("AlephaApiNotifications — runs without AlephaApiJobsQueue", () => {
+  it("module starts in direct mode and delivers an email notification", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create()
+      .with(AlephaOrmPostgres)
+      .with(AlephaEmail)
+      .with(AlephaSms)
+      .with(AlephaApiJobs)
+      .with(AlephaApiNotifications);
+
+    class Templates {
+      readonly welcome = $notification({
+        name: "welcome-email",
+        schema: t.object({ name: t.text() }),
+        email: {
+          subject: "Welcome",
+          body: (vars) => `Hello ${vars.name}`,
+        },
+      });
+    }
+
+    const templates = alepha.inject(Templates);
+    await alepha.start();
+
+    // Confirm the underlying $job runs in direct mode (no queue loaded).
+    const jobs = alepha.inject(JobProvider);
+    const sendName = alepha.inject(NotificationJobs).sendNotification.name;
+    expect(jobs.effectiveMode(sendName)).toBe("direct");
+
+    await templates.welcome.push({
+      contact: "alice@example.com",
+      variables: { name: "Alice" },
+    });
+
+    const mail = alepha.inject(MemoryEmailProvider);
+    const deadline = Date.now() + 1500;
+    while (mail.records.length === 0 && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 25));
+    }
+    expect(mail.records).toHaveLength(1);
+    expect(mail.records[0].to).toBe("alice@example.com");
+    expect(mail.records[0].subject).toBe("Welcome");
+    expect(mail.records[0].body).toBe("Hello Alice");
+  });
+});

package/src/api/notifications/controllers/AdminNotificationController.ts

@@ -2,7 +2,7 @@ import { $inject, t } from "alepha";
 import { jobExecutionEntity } from "alepha/api/jobs";
 import { $repository } from "alepha/orm";
 import { $secure } from "alepha/security";
-import { $action, NotFoundError } from "alepha/server";
+import { $action, NotFoundError, okSchema } from "alepha/server";
 import { NotificationJobs } from "../jobs/NotificationJobs.ts";
 import { notificationDetailResourceSchema } from "../schemas/notificationDetailResourceSchema.ts";
 import { notificationQuerySchema } from "../schemas/notificationQuerySchema.ts";
@@ -61,6 +61,53 @@ export class AdminNotificationController {
     },
   });
 
+  public readonly deleteNotification = $action({
+    method: "DELETE",
+    path: `${this.url}/:id`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:notification:delete"] })],
+    description: "Delete a notification record",
+    schema: {
+      params: t.object({
+        id: t.uuid(),
+      }),
+      response: okSchema,
+    },
+    handler: async ({ params }) => {
+      const exec = await this.executions.findById(params.id);
+      if (!exec || exec.jobName !== this.jobName) {
+        throw new NotFoundError(`Notification not found: ${params.id}`);
+      }
+      await this.executions.deleteById(params.id);
+      return { ok: true, id: params.id };
+    },
+  });
+
+  public readonly deleteNotifications = $action({
+    method: "POST",
+    path: `${this.url}/delete`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:notification:delete"] })],
+    description: "Delete many notification records in one call",
+    schema: {
+      body: t.object({
+        ids: t.array(t.uuid(), { minItems: 1, maxItems: 1000 }),
+      }),
+      response: t.object({
+        deleted: t.array(t.uuid()),
+      }),
+    },
+    handler: async ({ body }) => {
+      // Constrain to this job's executions so an admin can't delete arbitrary
+      // job rows through this endpoint.
+      const deleted = await this.executions.deleteMany({
+        id: { inArray: body.ids },
+        jobName: { eq: this.jobName },
+      });
+      return { deleted: deleted.map(String) };
+    },
+  });
+
   protected toResource(exec: Record<string, unknown>) {
     const payload = (exec.payload ?? {}) as Record<string, unknown>;
     return {

package/src/api/notifications/index.ts

@@ -1,5 +1,5 @@
 import { $module } from "alepha";
-import { AlephaApiJobsQueue } from "alepha/api/jobs";
+import { AlephaApiJobs } from "alepha/api/jobs";
 import { AlephaApiParameters } from "alepha/api/parameters";
 import { AdminNotificationController } from "./controllers/AdminNotificationController.ts";
 import { NotificationJobs } from "./jobs/NotificationJobs.ts";
@@ -26,15 +26,25 @@ export * from "./services/NotificationSenderService.ts";
  *
  * **Features:**
  * - Notification definitions (email/SMS templates)
- * - Queue-based delivery with retry and audit trail (`record: "all"` + no ring buffer trim)
+ * - Delivery via `$job` with retry and audit trail (`record: "all"` + no ring buffer trim)
  * - Runtime-editable retention window via `$parameter` — purge cron respects it live
  * - Admin API for inspecting sent notifications
  *
+ * **Delivery mode** is decided at runtime by the `$job` system:
+ * - If your app loads `AlephaApiJobsQueue` (and thus `AlephaQueue`), notifications
+ *   go through the queue (best for high-volume systems).
+ * - Otherwise, notifications run in **direct** mode: pushed to the outbox table
+ *   and processed in the same process right after the HTTP response is returned.
+ *   The reconciliation sweep is the safety net for crashes / retries.
+ *
+ * Direct mode is the recommended default for small / cheap deployments
+ * (Cloudflare Workers, single-instance Node) — no queue infrastructure required.
+ *
  * @module alepha.api.notifications
  */
 export const AlephaApiNotifications = $module({
   name: "alepha.api.notifications",
-  imports: [AlephaApiJobsQueue, AlephaApiParameters],
+  imports: [AlephaApiJobs, AlephaApiParameters],
   primitives: [$notification],
   services: [
     NotificationSenderService,

package/src/api/notifications/jobs/NotificationJobs.ts

@@ -55,12 +55,6 @@ export class NotificationJobs {
     schema: notificationPayloadSchema,
     retry: {
       retries: 3,
-      backoff: {
-        initial: [5, "seconds"],
-        factor: 4,
-        max: [10, "minutes"],
-        jitter: true,
-      },
     },
     timeout: [30, "seconds"],
     record: "all",

package/src/api/parameters/controllers/AdminParameterController.ts

@@ -267,4 +267,30 @@ export class AdminParameterController {
       return { ok: true };
     },
   });
+
+  /**
+   * Delete many parameters (all versions of each) in one request.
+   */
+  deleteParameters = $action({
+    group: this.group,
+    use: [$secure({ permissions: ["admin:parameter:delete"] })],
+    description: "Delete all versions of many parameters by name.",
+    path: "/parameters/delete",
+    method: "POST",
+    schema: {
+      body: t.object({
+        names: t.array(t.string({ minLength: 1 }), {
+          minItems: 1,
+          maxItems: 1000,
+        }),
+      }),
+      response: t.object({
+        deleted: t.array(t.string()),
+      }),
+    },
+    handler: async ({ body }) => {
+      const deleted = await this.provider.deleteMany(body.names);
+      return { deleted };
+    },
+  });
 }

package/src/api/parameters/services/ParameterProvider.ts

@@ -486,6 +486,24 @@ export class ParameterProvider {
     this.log.info("Parameter deleted", { name });
   }
 
+  /**
+   * Delete all versions of many parameters by name in one repository call.
+   */
+  public async deleteMany(names: string[]): Promise<string[]> {
+    if (names.length === 0) return [];
+    await this.repo.deleteMany({ name: { inArray: names } });
+    for (const name of names) {
+      this.cachedCurrent.delete(name);
+      this.cachedNext.delete(name);
+      this.loaded.delete(name);
+      this.loadPromises.delete(name);
+      this.loadGeneration.delete(name);
+      this.migrationChecked.delete(name);
+    }
+    this.log.info("Parameters deleted", { count: names.length });
+    return names;
+  }
+
   /**
    * Get a specific version of a parameter.
    */