alepha 0.20.4 → 0.20.6

package/src/api/audits/controllers/AdminAuditController.ts

@@ -1,6 +1,8 @@
 import { $inject, t } from "alepha";
+import { $repository } from "alepha/orm";
 import { $secure } from "alepha/security";
 import { $action } from "alepha/server";
+import { audits } from "../entities/audits.ts";
 import { auditQuerySchema } from "../schemas/auditQuerySchema.ts";
 import { auditResourceSchema } from "../schemas/auditResourceSchema.ts";
 import { createAuditSchema } from "../schemas/createAuditSchema.ts";
@@ -19,6 +21,7 @@ export class AdminAuditController {
   protected readonly url = "/audits";
   protected readonly group = "admin:audits";
   protected readonly auditService = $inject(AuditService);
+  protected readonly repo = $repository(audits);
 
   /**
    * Find audit entries with filtering and pagination.
@@ -52,6 +55,32 @@ export class AdminAuditController {
     handler: ({ params }) => this.auditService.getById(params.id),
   });
 
+  /**
+   * Delete many audit entries by id in one repository call. Use with care —
+   * audit logs are usually retained for compliance reasons.
+   */
+  public readonly deleteAudits = $action({
+    method: "POST",
+    path: `${this.url}/delete`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:audit:delete"] })],
+    description: "Delete many audit entries",
+    schema: {
+      body: t.object({
+        ids: t.array(t.text(), { minItems: 1, maxItems: 1000 }),
+      }),
+      response: t.object({
+        deleted: t.array(t.text()),
+      }),
+    },
+    handler: async ({ body }) => {
+      const deleted = await this.repo.deleteMany({
+        id: { inArray: body.ids },
+      });
+      return { deleted: deleted.map(String) };
+    },
+  });
+
   /**
    * Create a new audit entry.
    * System-only — this permission should never be assigned to human roles.

package/src/api/files/controllers/FileController.ts

@@ -50,6 +50,30 @@ export class FileController {
     handler: ({ params }) => this.fileService.deleteFile(params.id),
   });
 
+  /**
+   * POST /files/delete - Delete many files in one request, batching the
+   * underlying bucket calls per bucket (R2/S3 batch where supported).
+   */
+  public readonly deleteFiles = $action({
+    method: "POST",
+    path: `${this.url}/delete`,
+    group: `admin:${this.group}`,
+    use: [$secure({ permissions: ["admin:file:delete"] })],
+    description: "Delete many files",
+    schema: {
+      body: t.object({
+        ids: t.array(t.uuid(), { minItems: 1, maxItems: 1000 }),
+      }),
+      response: t.object({
+        deleted: t.array(t.string()),
+      }),
+    },
+    handler: async ({ body }) => {
+      const deleted = await this.fileService.deleteFiles(body.ids);
+      return { deleted };
+    },
+  });
+
   /**
    * POST /files - Uploads a new file to storage.
    * Creates a database record with metadata and calculates checksum.

package/src/api/files/services/FileService.ts

@@ -324,6 +324,47 @@ export class FileService {
     return { ok: true, id: String(file.id) };
   }
 
+  /**
+   * Delete many files in one round-trip per bucket. The database rows are
+   * removed in a single `deleteMany`, and each affected bucket gets a single
+   * `bucket.deleteMany` call (R2/S3 batch where supported).
+   */
+  public async deleteFiles(ids: string[]): Promise<string[]> {
+    if (ids.length === 0) return [];
+
+    const files = await this.fileRepository.findMany({
+      where: { id: { inArray: ids } },
+      columns: ["id", "bucket", "blobId"],
+    });
+    if (files.length === 0) return [];
+
+    const dbDeleted = await this.fileRepository.deleteMany({
+      id: { inArray: files.map((f) => f.id) },
+    });
+
+    const blobsByBucket = new Map<string, string[]>();
+    for (const f of files) {
+      const list = blobsByBucket.get(f.bucket) ?? [];
+      list.push(f.blobId);
+      blobsByBucket.set(f.bucket, list);
+    }
+
+    for (const [bucketName, blobIds] of blobsByBucket) {
+      try {
+        await this.bucket(bucketName).deleteMany(blobIds, true);
+      } catch (e) {
+        // DB rows already gone — log and continue. Orphaned blobs are
+        // recoverable; orphaned DB rows would be worse.
+        this.log.warn(
+          `Failed to bulk-delete ${blobIds.length} files from bucket ${bucketName}`,
+          e,
+        );
+      }
+    }
+
+    return dbDeleted.map(String);
+  }
+
   /**
    * Retrieves a file entity by its ID.
    * If already an entity object, returns it as-is (convenience method).

package/src/api/jobs/__tests__/$job.spec.ts

@@ -1,4 +1,5 @@
 import { Alepha, AlephaError, t } from "alepha";
+import { LockProvider, MemoryLockProvider } from "alepha/lock";
 import { $repository } from "alepha/orm";
 import { AlephaOrmPostgres } from "alepha/orm/postgres";
 import { describe, it } from "vitest";
@@ -6,6 +7,7 @@ import {
   $job,
   AlephaApiJobs,
   AlephaApiJobsQueue,
+  JobProvider,
   jobExecutionEntity,
 } from "../index.ts";
 
@@ -15,6 +17,10 @@ const makeApp = () =>
     .with(AlephaApiJobs)
     .with(AlephaApiJobsQueue);
 
+/** App without `AlephaApiJobsQueue` — exercises *direct* mode. */
+const makeAppDirect = () =>
+  Alepha.create().with(AlephaOrmPostgres).with(AlephaApiJobs);
+
 describe("$job — registration validation", () => {
   it("rejects jobs declaring both cron and schema", async ({ expect }) => {
     const alepha = makeApp();
@@ -240,7 +246,7 @@ describe("$job — queue mode (outbox)", () => {
     expect(seen.sort()).toEqual([1, 2, 3]);
   });
 
-  it("retry: failed queue job is re-scheduled with backoff", async ({
+  it("retry: failed queue job is rescheduled for the next sweep tick", async ({
     expect,
   }) => {
     const alepha = makeApp();
@@ -249,7 +255,7 @@ describe("$job — queue mode (outbox)", () => {
       executions = $repository(jobExecutionEntity);
       work = $job({
         schema: t.object({ v: t.integer() }),
-        retry: { retries: 2, backoff: [10, "seconds"] },
+        retry: { retries: 2 },
         handler: async () => {
           attempts++;
           throw new Error("fail");
@@ -267,6 +273,11 @@ describe("$job — queue mode (outbox)", () => {
     expect(rows[0].status).toBe("scheduled");
     expect(rows[0].attempt).toBe(1);
     expect(attempts).toBe(1);
+    // scheduledAt is "now" (no backoff), proving we no longer wait for an
+    // exponential delay — the row is immediately eligible at the next sweep.
+    expect(rows[0].scheduledAt).toBeTruthy();
+    const sched = new Date(rows[0].scheduledAt!).getTime();
+    expect(Math.abs(sched - Date.now())).toBeLessThan(2_000);
   });
 
   it("retry: terminal error after all retries exhausted", async ({
@@ -349,4 +360,418 @@ describe("$job — admin service", () => {
     expect(byName.get("App.queueB")?.type).toBe("queue");
     expect(byName.get("App.cronA")?.recent.ok).toBe(0);
   });
+
+  it("listJobs reports 'direct' when AlephaApiJobsQueue is not loaded", async ({
+    expect,
+  }) => {
+    const alepha = makeAppDirect();
+    class App {
+      worker = $job({
+        schema: t.object({ v: t.integer() }),
+        handler: async () => {},
+      });
+    }
+    alepha.inject(App);
+    await alepha.start();
+
+    const { JobService } = await import("../services/JobService.ts");
+    const svc = alepha.inject(JobService);
+    const list = await svc.listJobs();
+
+    expect(list.find((j) => j.name === "App.worker")?.type).toBe("direct");
+  });
+});
+
+// ---------------------------------------------------------------------------
+
+describe("$job — direct mode (no AlephaApiJobsQueue)", () => {
+  it("push without a queue dispatcher processes the row in-process", async ({
+    expect,
+  }) => {
+    const alepha = makeAppDirect();
+    let received: { n: number } | undefined;
+    class App {
+      executions = $repository(jobExecutionEntity);
+      work = $job({
+        schema: t.object({ n: t.integer() }),
+        handler: async ({ payload }) => {
+          received = payload;
+        },
+      });
+    }
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    expect(alepha.inject(JobProvider).effectiveMode("App.work")).toBe("direct");
+
+    await app.work.push({ n: 7 });
+
+    // Direct mode is fire-and-track; give the microtask queue a moment.
+    const deadline = Date.now() + 1500;
+    while (received === undefined && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 25));
+    }
+
+    expect(received).toEqual({ n: 7 });
+    // Default record: 'error' → success deletes the row.
+    const rows = await app.executions.findMany({
+      where: { jobName: { eq: "App.work" } },
+    });
+    expect(rows).toHaveLength(0);
+  });
+
+  it("direct mode failure schedules the row for the next sweep", async ({
+    expect,
+  }) => {
+    const alepha = makeAppDirect();
+    class App {
+      executions = $repository(jobExecutionEntity);
+      work = $job({
+        schema: t.object({ n: t.integer() }),
+        retry: { retries: 2 },
+        handler: async () => {
+          throw new Error("nope");
+        },
+      });
+    }
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    await app.work.push({ n: 1 });
+
+    // Wait for the in-process attempt to fail.
+    const deadline = Date.now() + 2000;
+    let row: any;
+    while (Date.now() < deadline) {
+      const rows = await app.executions.findMany({
+        where: { jobName: { eq: "App.work" } },
+      });
+      if (rows[0]?.status === "scheduled") {
+        row = rows[0];
+        break;
+      }
+      await new Promise((r) => setTimeout(r, 25));
+    }
+
+    expect(row).toBeTruthy();
+    expect(row.status).toBe("scheduled");
+    expect(row.attempt).toBe(1);
+    expect(row.error).toBe("nope");
+    // scheduledAt should be "now" (no backoff).
+    const sched = new Date(row.scheduledAt).getTime();
+    expect(Math.abs(sched - Date.now())).toBeLessThan(2_000);
+  });
+});
+
+// ---------------------------------------------------------------------------
+
+/**
+ * Shared in-process key/value to simulate a cross-instance lock store
+ * (mirrors the pattern used in scheduler tests).
+ */
+const sharedLockStore: Record<string, string> = {};
+class SharedMemoryLockProvider extends MemoryLockProvider {
+  override store = sharedLockStore;
+}
+
+describe("$job — cron lock (multi-instance)", () => {
+  it("only one instance fires the cron handler when sharing a LockProvider", async ({
+    expect,
+  }) => {
+    // Reset store between tests.
+    for (const k of Object.keys(sharedLockStore)) delete sharedLockStore[k];
+
+    let fired = 0;
+    class App {
+      tick = $job({
+        cron: "0 0 * * *",
+        handler: async () => {
+          fired++;
+        },
+      });
+    }
+
+    const make = () =>
+      Alepha.create()
+        // Substitute the LockProvider BEFORE AlephaApiJobs imports AlephaLock,
+        // otherwise the module's default `optional` MemoryLockProvider wins.
+        .with({ provide: LockProvider, use: SharedMemoryLockProvider })
+        .with(AlephaOrmPostgres)
+        .with(AlephaApiJobs);
+
+    const a = make();
+    const b = make();
+    a.inject(App);
+    b.inject(App);
+    await a.start();
+    await b.start();
+
+    // Trigger the tick from both instances: only one should win the lock.
+    await Promise.all([
+      a.inject(App).tick.trigger(),
+      b.inject(App).tick.trigger(),
+    ]);
+
+    expect(fired).toBe(1);
+  });
+
+  it("lock: false lets every instance fire (opt-out behavior)", async ({
+    expect,
+  }) => {
+    for (const k of Object.keys(sharedLockStore)) delete sharedLockStore[k];
+
+    let fired = 0;
+    class App {
+      tick = $job({
+        cron: "0 0 * * *",
+        lock: false,
+        handler: async () => {
+          fired++;
+        },
+      });
+    }
+
+    const make = () =>
+      Alepha.create()
+        // Substitute the LockProvider BEFORE AlephaApiJobs imports AlephaLock,
+        // otherwise the module's default `optional` MemoryLockProvider wins.
+        .with({ provide: LockProvider, use: SharedMemoryLockProvider })
+        .with(AlephaOrmPostgres)
+        .with(AlephaApiJobs);
+
+    const a = make();
+    const b = make();
+    a.inject(App);
+    b.inject(App);
+    await a.start();
+    await b.start();
+
+    await Promise.all([
+      a.inject(App).tick.trigger(),
+      b.inject(App).tick.trigger(),
+    ]);
+
+    expect(fired).toBe(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+
+describe("$job — retry semantics", () => {
+  it("retries: 2 runs the handler 3 times before the row is terminal", async ({
+    expect,
+  }) => {
+    const alepha = makeApp();
+    let attempts = 0;
+    class App {
+      executions = $repository(jobExecutionEntity);
+      work = $job({
+        schema: t.object({ v: t.integer() }),
+        retry: { retries: 2 },
+        handler: async () => {
+          attempts++;
+          throw new Error("boom");
+        },
+      });
+    }
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    await app.work.push({ v: 1 });
+
+    // First attempt runs immediately. Subsequent retries are sweep-driven.
+    await new Promise((r) => setTimeout(r, 100));
+    expect(attempts).toBe(1);
+
+    const provider = alepha.inject(JobProvider);
+    // Trigger sweeps manually — each one should claim and run the next attempt.
+    await (provider as any).sweep();
+    await new Promise((r) => setTimeout(r, 50));
+    expect(attempts).toBe(2);
+
+    await (provider as any).sweep();
+    await new Promise((r) => setTimeout(r, 50));
+    expect(attempts).toBe(3);
+
+    // After 3 attempts the row is terminal — no more retries.
+    const finalRow = (
+      await app.executions.findMany({ where: { jobName: { eq: "App.work" } } })
+    )[0];
+    expect(finalRow.status).toBe("error");
+    expect(finalRow.attempt).toBe(3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+
+describe("$job — cancel race", () => {
+  it("cancel during a running handler keeps the row 'cancelled' (not 'error')", async ({
+    expect,
+  }) => {
+    const alepha = makeApp();
+    class App {
+      executions = $repository(jobExecutionEntity);
+      slow = $job({
+        schema: t.object({ v: t.integer() }),
+        retry: { retries: 0 },
+        handler: async ({ signal }) => {
+          // Wait for cancellation, then throw — without the guard this throw
+          // would write `status: error` after `status: cancelled`.
+          await new Promise<void>((_, reject) => {
+            signal.addEventListener("abort", () => {
+              reject(new Error("aborted"));
+            });
+          });
+        },
+      });
+    }
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const id = await app.slow.push({ v: 1 });
+
+    // Wait for the handler to be `running`.
+    const deadline = Date.now() + 1500;
+    while (Date.now() < deadline) {
+      const row = await app.executions.findById(id);
+      if (row?.status === "running") break;
+      await new Promise((r) => setTimeout(r, 20));
+    }
+
+    await app.slow.cancel(id);
+
+    // Give the handler's abort path a moment to execute and (without the
+    // guard) try to overwrite the row.
+    await new Promise((r) => setTimeout(r, 100));
+
+    const final = await app.executions.findById(id);
+    expect(final?.status).toBe("cancelled");
+    expect(final?.error).toBeFalsy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+
+describe("$job — cron + retry (outbox path)", () => {
+  it("a failing cron job with retry is rescheduled by the sweep, not next tick", async ({
+    expect,
+  }) => {
+    const alepha = makeAppDirect();
+    let attempts = 0;
+    class App {
+      executions = $repository(jobExecutionEntity);
+      tick = $job({
+        cron: "0 0 * * *",
+        retry: { retries: 1 },
+        handler: async () => {
+          attempts++;
+          throw new Error("transient");
+        },
+      });
+    }
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    // Manually fire the cron tick (admin trigger path goes through the
+    // same lock-aware runner as the scheduled tick).
+    await app.tick.trigger();
+
+    // Direct-mode dispatch is fire-and-track. Wait for the first attempt
+    // to land in the DB.
+    const deadline = Date.now() + 1500;
+    while (attempts < 1 && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 25));
+    }
+    expect(attempts).toBe(1);
+
+    // The row exists in the outbox after the cron tick (unlike inline crons,
+    // which only persist on error).
+    const provider = alepha.inject(JobProvider);
+    const rows1 = await app.executions.findMany({
+      where: { jobName: { eq: "App.tick" } },
+    });
+    expect(rows1).toHaveLength(1);
+    expect(rows1[0].status).toBe("scheduled");
+
+    // Sweep picks it up and runs attempt 2 → terminal.
+    await (provider as any).sweep();
+    await new Promise((r) => setTimeout(r, 100));
+    expect(attempts).toBe(2);
+    const rows2 = await app.executions.findMany({
+      where: { jobName: { eq: "App.tick" } },
+    });
+    expect(rows2[0].status).toBe("error");
+  });
+});
+
+// ---------------------------------------------------------------------------
+
+describe("$job — dispatchMany (queue mode)", () => {
+  it("pushMany hands the dispatcher a single batch", async ({ expect }) => {
+    const alepha = makeApp();
+    class App {
+      bulk = $job({
+        schema: t.object({ n: t.integer() }),
+        handler: async () => {},
+      });
+    }
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const provider = alepha.inject(JobProvider);
+    const dispatcher = (provider as any).dispatcher as {
+      dispatchMany: (
+        items: Array<{ jobName: string; executionId: string }>,
+      ) => Promise<void>;
+    };
+
+    let batched: Array<{ jobName: string; executionId: string }> = [];
+    const original = dispatcher.dispatchMany.bind(dispatcher);
+    dispatcher.dispatchMany = async (items) => {
+      batched = items;
+      await original(items);
+    };
+
+    await app.bulk.pushMany([
+      { payload: { n: 1 } },
+      { payload: { n: 2 } },
+      { payload: { n: 3 } },
+    ]);
+
+    expect(batched).toHaveLength(3);
+    for (const it of batched) {
+      expect(it.jobName).toBe("App.bulk");
+      expect(it.executionId).toBeTruthy();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+
+describe("$job — admin resource shape", () => {
+  it("execution resource exposes priority as the enum string", async ({
+    expect,
+  }) => {
+    const alepha = makeApp();
+    class App {
+      work = $job({
+        schema: t.object({ v: t.integer() }),
+        priority: "high",
+        record: "all",
+        handler: async () => {},
+      });
+    }
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const id = await app.work.push({ v: 1 });
+    // Wait for the handler to finish so the row is `ok` (record: all keeps it).
+    await new Promise((r) => setTimeout(r, 100));
+
+    const { JobService } = await import("../services/JobService.ts");
+    const svc = alepha.inject(JobService);
+    const resource = await svc.getExecution(id);
+    expect(resource.priority).toBe("high");
+    expect(typeof resource.priority).toBe("string");
+  });
 });

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

@@ -10,11 +10,11 @@ import { $entity, db } from "alepha/orm";
  * the last N rows per job (configurable via `jobConfig.keepLastSuccess`).
  *
  * Status transitions:
- * - queue push            → pending
+ * - queue push            → pending (or `scheduled` if `delay`/`scheduledAt` was given)
  * - worker claim          → running
- * - success               → ok
+ * - success               → ok (or row deleted, depending on `record` and `keepLastSuccess`)
  * - terminal failure      → error
- * - retry                 → scheduled (with scheduledAt = now + backoff)
+ * - retryable failure     → scheduled (with scheduledAt = now; sweep picks it up)
  * - delay                 → scheduled (with scheduledAt = now + delay)
  * - sweep picks due ones  → pending
  * - cancel                → cancelled