@podosoft/podokit 1.0.2 → 1.1.4

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/jobs.module.ts

@@ -1,16 +1,16 @@
 import { AppException } from "@podosoft/podokit-contracts";
-import { Queue } from "bullmq";
+import { JOBS } from "@podosoft/podokit-runtime";
 import { Elysia, t } from "elysia";
-import type { AppPlugin, PodokitModule, ServiceKey } from "../core/services";
-import { DEMO_QUEUE, redisConnection } from "./queue";
-
-export const JOB_QUEUE = Symbol("job-queue") as ServiceKey<Queue>;
+import { PROVIDERS } from "../config/providers";
+import type { AppPlugin, PodokitModule } from "../core/services";
+import { BullMqJobQueue } from "./bullmq-job.queue";
 
 const jobsPlugin: AppPlugin = ({ services }) => {
-  const queue = services.resolve(JOB_QUEUE);
+  if (PROVIDERS.jobs !== "bullmq") return new Elysia({ name: "podokit.jobs.inactive" });
+  const queue = services.resolve(JOBS);
   return new Elysia({ name: "podokit.jobs" })
     .post("/jobs", async ({ body, set }) => {
-      const job = await queue.add("demo", { text: body.text });
+      const job = await queue.enqueue("demo", { text: body.text });
       set.status = 201;
       return { id: job.id };
     }, {
@@ -18,9 +18,9 @@ const jobsPlugin: AppPlugin = ({ services }) => {
       detail: { tags: ["jobs"], summary: "Enqueue a job" },
     })
     .get("/jobs/:id", async ({ params }) => {
-      const job = await queue.getJob(params.id);
+      const job = await queue.get(params.id);
       if (!job) throw new AppException("JOB_NOT_FOUND", `Job ${params.id} not found`, 404);
-      return { id: job.id, state: await job.getState(), result: job.returnvalue ?? null };
+      return { id: job.id, state: job.status, result: job.result ?? null };
     }, {
       params: t.Object({ id: t.String({ minLength: 1 }) }),
       detail: { tags: ["jobs"], summary: "Read job status" },
@@ -30,8 +30,9 @@ const jobsPlugin: AppPlugin = ({ services }) => {
 export const jobsModule: PodokitModule = {
   name: "bullmq",
   configure: (_env, services): void => {
-    const queue = new Queue(DEMO_QUEUE, { connection: redisConnection() });
-    services.register(JOB_QUEUE, queue, () => queue.close());
+    if (PROVIDERS.jobs !== "bullmq") return;
+    const queue = new BullMqJobQueue();
+    services.register(JOBS, queue, () => queue.close());
   },
   plugin: jobsPlugin,
 };

package/dist/templates/modules/bullmq/files/apps/api/src/main-worker.ts

@@ -1,6 +1,11 @@
 import "dotenv/config";
+import { PROVIDERS } from "./config/providers";
 import { startWorkers } from "./jobs/worker.module";
 
+if (PROVIDERS.jobs !== "bullmq") {
+  throw new Error("The BullMQ worker cannot start unless jobs=bullmq is selected");
+}
+
 const workers = startWorkers();
 
 for (const worker of workers) {

package/dist/templates/modules/bullmq/module.manifest.json

@@ -1,10 +1,17 @@
 {
+  "manifestVersion": 3,
   "name": "bullmq",
   "description": "Background jobs with BullMQ: a demo queue, a separate worker process, and enqueue/status endpoints (needs Redis).",
   "requires": [],
+  "provides": { "jobs": "bullmq" },
   "requiredProjectFiles": [
+    "apps/api/src/config/providers.ts",
     "apps/api/src/config/redis.connection.ts"
   ],
+  "managedGlobs": [
+    "apps/api/src/jobs/**",
+    "apps/api/src/main-worker.ts"
+  ],
   "targetApp": "api",
   "dependencies": {
     "bullmq": "^5.34.0"

package/dist/templates/modules/cache-memory/files/apps/api/src/cache-memory/cache-memory.module.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "bun:test";
+import { MemoryCacheStore } from "@podosoft/podokit-runtime";
+
+describe("memory cache provider", () => {
+  it("expires values and enforces a fixed-window limit", async () => {
+    let now = 1_000;
+    const cache = new MemoryCacheStore({ now: () => now });
+    await cache.set("short", "value", { ttlMs: 10 });
+    now += 10;
+    expect(await cache.get("short")).toBeNull();
+    expect((await cache.incrementFixedWindow("user", { windowMs: 1_000, limit: 1 })).allowed)
+      .toBe(true);
+    expect((await cache.incrementFixedWindow("user", { windowMs: 1_000, limit: 1 })).allowed)
+      .toBe(false);
+  });
+});

package/dist/templates/modules/cache-memory/files/apps/api/src/cache-memory/cache-memory.module.ts

@@ -0,0 +1,12 @@
+import { CACHE, MemoryCacheStore } from "@podosoft/podokit-runtime";
+import type { PodokitModule } from "../core/services";
+import { PROVIDERS } from "../config/providers";
+
+export const cacheMemoryModule: PodokitModule = {
+  name: "cache-memory",
+  configure: (_env, services): void => {
+    if (PROVIDERS.cache !== "memory") return;
+    const cache = new MemoryCacheStore();
+    services.register(CACHE, cache, () => cache.close());
+  },
+};

package/dist/templates/modules/cache-memory/module.manifest.json

@@ -0,0 +1,30 @@
+{
+  "manifestVersion": 3,
+  "name": "cache-memory",
+  "description": "Bounded in-process cache with TTL and fixed-window counters for a single API process.",
+  "provides": { "cache": "memory" },
+  "runtimeConstraints": { "maxApiReplicas": 1 },
+  "requiredProjectFiles": [
+    "apps/api/src/config/providers.ts"
+  ],
+  "managedGlobs": [
+    "apps/api/src/cache-memory/**"
+  ],
+  "targetApp": "api",
+  "env": [],
+  "inject": [
+    {
+      "file": "apps/api/src/app.ts",
+      "marker": "// podokit:end:imports",
+      "text": "import { cacheMemoryModule } from \"./cache-memory/cache-memory.module\";"
+    },
+    {
+      "file": "apps/api/src/app.ts",
+      "marker": "// podokit:end:modules",
+      "text": "cacheMemoryModule,"
+    }
+  ],
+  "instructions": [
+    "Memory cache is process-local. Keep the API at one replica or select the Redis provider."
+  ]
+}

package/dist/templates/modules/events-memory/files/apps/api/src/events-provider-memory/events-memory.module.ts

@@ -0,0 +1,14 @@
+import { EVENTS, MemoryEventBus } from "@podosoft/podokit-runtime";
+import type { PodokitModule } from "../core/services";
+import { PROVIDERS } from "../config/providers";
+
+export const eventsMemoryModule: PodokitModule = {
+  name: "events-memory",
+  configure: (_env, services): void => {
+    if (PROVIDERS.events !== "memory") return;
+    const events = new MemoryEventBus({
+      maxEventBytes: Number(process.env.SSE_MAX_EVENT_BYTES ?? 65_536),
+    });
+    services.register(EVENTS, events, () => events.close());
+  },
+};

package/dist/templates/modules/events-memory/module.manifest.json

@@ -0,0 +1,30 @@
+{
+  "manifestVersion": 3,
+  "name": "events-memory",
+  "description": "In-process event bus for desktop and single API process applications.",
+  "provides": { "events": "memory" },
+  "runtimeConstraints": { "maxApiReplicas": 1 },
+  "requiredProjectFiles": [
+    "apps/api/src/config/providers.ts"
+  ],
+  "managedGlobs": [
+    "apps/api/src/events-provider-memory/**"
+  ],
+  "targetApp": "api",
+  "env": [],
+  "inject": [
+    {
+      "file": "apps/api/src/app.ts",
+      "marker": "// podokit:end:imports",
+      "text": "import { eventsMemoryModule } from \"./events-provider-memory/events-memory.module\";"
+    },
+    {
+      "file": "apps/api/src/app.ts",
+      "marker": "// podokit:end:modules",
+      "text": "eventsMemoryModule,"
+    }
+  ],
+  "instructions": [
+    "Memory events are process-local. Keep the API at one replica or select the Redis events provider."
+  ]
+}

package/dist/templates/modules/events-redis/files/apps/api/src/events-provider-redis/events-redis.module.ts

@@ -0,0 +1,16 @@
+import { EVENTS } from "@podosoft/podokit-runtime";
+import type { PodokitModule } from "../core/services";
+import { PROVIDERS } from "../config/providers";
+import { RedisEventBus } from "./redis-event.bus";
+
+export const eventsRedisModule: PodokitModule = {
+  name: "events-redis",
+  configure: (_env, services): void => {
+    if (PROVIDERS.events !== "redis") return;
+    const events = new RedisEventBus();
+    services.register(EVENTS, events, async () => {
+      await events.close();
+    });
+    services.onStart(() => events.ready());
+  },
+};

package/dist/templates/modules/events-redis/files/apps/api/src/events-provider-redis/redis-event.bus.ts

@@ -0,0 +1,75 @@
+import { RedisClient } from "bun";
+import type { EventBus, EventHandler, Unsubscribe } from "@podosoft/podokit-runtime";
+import { redisConnectionUrl } from "../config/redis.connection";
+
+export class RedisEventBus implements EventBus {
+  private readonly publisher: RedisClient;
+  private readonly subscriber: RedisClient;
+  private readonly channel: string;
+  private readonly maxEventBytes: number;
+  private readonly handlers = new Map<string, Set<EventHandler>>();
+  private listener?: (message: string) => void;
+
+  constructor(env: NodeJS.ProcessEnv = process.env) {
+    this.publisher = new RedisClient(redisConnectionUrl(env), { connectionTimeout: 5_000 });
+    this.subscriber = new RedisClient(redisConnectionUrl(env), { connectionTimeout: 5_000 });
+    this.channel = env.EVENTS_REDIS_CHANNEL?.trim() || "podokit:events";
+    this.maxEventBytes = Number(env.SSE_MAX_EVENT_BYTES ?? 65_536);
+    if (!Number.isSafeInteger(this.maxEventBytes) || this.maxEventBytes < 1) {
+      throw new Error("SSE_MAX_EVENT_BYTES must be a positive integer");
+    }
+  }
+
+  async connect(): Promise<void> {
+    if (this.listener) return;
+    await Promise.all([this.publisher.connect(), this.subscriber.connect()]);
+    this.listener = (message: string): void => {
+      if (Buffer.byteLength(message, "utf8") > this.maxEventBytes) return;
+      try {
+        const envelope = JSON.parse(message) as unknown;
+        if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) return;
+        const record = envelope as Record<string, unknown>;
+        if (typeof record.topic !== "string") return;
+        for (const handler of this.handlers.get(record.topic) ?? []) {
+          void Promise.resolve(handler(record.event)).catch(() => undefined);
+        }
+      } catch {
+        process.stderr.write("Discard malformed event transport message\n");
+      }
+    };
+    await this.subscriber.subscribe(this.channel, this.listener);
+  }
+
+  async ready(): Promise<void> {
+    await this.connect();
+    await this.publisher.ping();
+  }
+
+  async publish(topic: string, event: unknown): Promise<void> {
+    const message = JSON.stringify({ topic, event });
+    if (message === undefined) throw new Error("Event must be JSON serializable");
+    if (Buffer.byteLength(message, "utf8") > this.maxEventBytes) {
+      throw new Error(`Event exceeds maxEventBytes (${this.maxEventBytes})`);
+    }
+    await this.publisher.publish(this.channel, message);
+  }
+
+  async subscribe(topic: string, handler: EventHandler): Promise<Unsubscribe> {
+    await this.connect();
+    const handlers = this.handlers.get(topic) ?? new Set<EventHandler>();
+    handlers.add(handler);
+    this.handlers.set(topic, handlers);
+    return () => {
+      handlers.delete(handler);
+      if (handlers.size === 0) this.handlers.delete(topic);
+    };
+  }
+
+  async close(): Promise<void> {
+    if (this.listener) await this.subscriber.unsubscribe(this.channel, this.listener);
+    this.handlers.clear();
+    this.listener = undefined;
+    this.publisher.close();
+    this.subscriber.close();
+  }
+}

package/dist/templates/modules/events-redis/module.manifest.json

@@ -0,0 +1,32 @@
+{
+  "manifestVersion": 3,
+  "name": "events-redis",
+  "description": "Redis publish/subscribe event bus for delivery across API replicas.",
+  "provides": { "events": "redis" },
+  "requiredProjectFiles": [
+    "apps/api/src/config/providers.ts",
+    "apps/api/src/config/redis.connection.ts"
+  ],
+  "managedGlobs": [
+    "apps/api/src/events-provider-redis/**"
+  ],
+  "targetApp": "api",
+  "env": [
+    "EVENTS_REDIS_CHANNEL=podokit:events"
+  ],
+  "inject": [
+    {
+      "file": "apps/api/src/app.ts",
+      "marker": "// podokit:end:imports",
+      "text": "import { eventsRedisModule } from \"./events-provider-redis/events-redis.module\";"
+    },
+    {
+      "file": "apps/api/src/app.ts",
+      "marker": "// podokit:end:modules",
+      "text": "eventsRedisModule,"
+    }
+  ],
+  "instructions": [
+    "Redis events use REDIS_URL or the shared individual Redis settings."
+  ]
+}

package/dist/templates/modules/file-upload/files/apps/api/src/files/files.module.ts

@@ -1,22 +1,26 @@
 import { Elysia, t } from "elysia";
+import { OBJECT_STORAGE } from "@podosoft/podokit-runtime";
 import type { AppPlugin, PodokitModule } from "../core/services";
-import { STORAGE } from "../storage/storage.module";
 
 const filesPlugin: AppPlugin = ({ services }) => {
-  const storage = services.resolve(STORAGE);
+  const storage = services.resolve(OBJECT_STORAGE);
   return new Elysia({ name: "podokit.files" })
     .post("/files", async ({ body, set }) => {
       const safeName = body.file.name.replace(/[^\w.-]+/g, "_");
       const key = `uploads/${crypto.randomUUID()}-${safeName}`;
-      await storage.put(key, new Uint8Array(await body.file.arrayBuffer()), body.file.type);
+      await storage.put(
+        key,
+        new Uint8Array(await body.file.arrayBuffer()),
+        { contentType: body.file.type },
+      );
       set.status = 201;
-      return { key, url: await storage.presignedGetUrl(key) };
+      return { key, url: await storage.getDownloadUrl(key) };
     }, {
       body: t.Object({ file: t.File() }),
       detail: { tags: ["files"], summary: "Upload a file" },
     })
     .get("/files/:key/url", async ({ params }) => ({
-      url: await storage.presignedGetUrl(params.key),
+      url: await storage.getDownloadUrl(params.key),
     }), {
       params: t.Object({ key: t.String({ minLength: 1 }) }),
       detail: { tags: ["files"], summary: "Presign a file download" },

package/dist/templates/modules/file-upload/files/tests/api/files.api.spec.ts

@@ -16,7 +16,7 @@ test("file upload: multipart upload returns a key and url @smoke", async ({ play
     multipart: { file: { name: "hello.txt", mimeType: "text/plain", buffer: Buffer.from("hi there") } },
   });
   const responseText = await res.text();
-  test.skip(res.status() >= 500, "object storage (MinIO/S3) not reachable");
+  test.skip(res.status() >= 500, "selected object storage is not reachable");
   expect(res.ok(), `upload returned ${res.status()}: ${responseText}`).toBeTruthy();
   const body = JSON.parse(responseText) as unknown;
   expect(typeof body).toBe("object");

package/dist/templates/modules/file-upload/module.manifest.json

@@ -1,7 +1,8 @@
 {
+  "manifestVersion": 3,
   "name": "file-upload",
   "description": "Multipart file upload endpoint that stores files via object storage and returns a presigned URL.",
-  "requires": ["object-storage-s3"],
+  "requiresCapabilities": ["object-storage"],
   "targetApp": "api",
   "env": [],
   "inject": [
@@ -9,8 +10,8 @@
     { "file": "apps/api/src/app.ts", "marker": "// podokit:end:modules", "text": "filesModule," }
   ],
   "instructions": [
-    "Start MinIO (or configure AWS S3):  docker compose -f infra/docker/docker-compose.yml -f infra/docker/minio.compose.yml up -d",
+    "Configure the selected object-storage provider before uploading files.",
     "Upload a file:  curl -F 'file=@./some.png' localhost:5002/files",
-    "The response includes { key, url } — a presigned download URL."
+    "The response includes { key, url } — an S3 presigned URL or a local download URL."
   ]
 }

package/dist/templates/modules/job-progress/files/apps/api/src/progress/job-progress.module.ts

@@ -1,19 +1,39 @@
-import { Queue } from "bullmq";
+import { JOBS, type JobQueue, type Unsubscribe } from "@podosoft/podokit-runtime";
 import { Elysia, t } from "elysia";
 import type { AppPlugin, PodokitModule, ServiceKey } from "../core/services";
-import { EVENTS } from "../events/events.module";
-import { redisConnection } from "../jobs/queue";
-import { REDIS } from "../redis/redis.module";
-import { ProgressBridge } from "./progress.bridge";
+import { SSE_EVENTS } from "../events/events.module";
+import { processProgress } from "./progress.processor";
 
-const PROGRESS_QUEUE = Symbol("progress-queue") as ServiceKey<Queue>;
-const PROGRESS_BRIDGE = Symbol("progress-bridge") as ServiceKey<ProgressBridge>;
+class ProgressWorker {
+  private unsubscribe?: Unsubscribe;
+
+  constructor(
+    private readonly queue: JobQueue,
+    private readonly publish: (event: unknown) => Promise<void>,
+  ) {}
+
+  async connect(): Promise<void> {
+    this.unsubscribe = await this.queue.process("progress", async (payload, job) => {
+      await processProgress(payload, (progress) => this.publish({
+        type: "job-progress",
+        jobId: job.id,
+        progress,
+      }));
+    });
+  }
+
+  async close(): Promise<void> {
+    await this.unsubscribe?.();
+  }
+}
+
+const PROGRESS_WORKER = Symbol("progress-worker") as ServiceKey<ProgressWorker>;
 
 const progressPlugin: AppPlugin = ({ services }) => {
-  const queue = services.resolve(PROGRESS_QUEUE);
+  const queue = services.resolve(JOBS);
   return new Elysia({ name: "podokit.job-progress" })
     .post("/progress", async ({ body, set }) => {
-      const job = await queue.add("progress", { steps: body.steps ?? 5 });
+      const job = await queue.enqueue("progress", { steps: body.steps ?? 5 });
       set.status = 201;
       return { jobId: job.id };
     }, {
@@ -25,11 +45,13 @@ const progressPlugin: AppPlugin = ({ services }) => {
 export const jobProgressModule: PodokitModule = {
   name: "job-progress",
   configure: (_env, services): void => {
-    const queue = new Queue("progress", { connection: redisConnection() });
-    const bridge = new ProgressBridge(services.resolve(REDIS), services.resolve(EVENTS));
-    services.register(PROGRESS_QUEUE, queue, () => queue.close());
-    services.register(PROGRESS_BRIDGE, bridge, () => bridge.close());
-    services.onStart(() => bridge.connect());
+    const events = services.resolve(SSE_EVENTS);
+    const worker = new ProgressWorker(
+      services.resolve(JOBS),
+      (event) => events.publishAsync(event),
+    );
+    services.register(PROGRESS_WORKER, worker, () => worker.close());
+    services.onStart(() => worker.connect());
   },
   plugin: progressPlugin,
 };

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.bridge.spec.ts

@@ -1,36 +1,13 @@
 import { describe, expect, it, mock } from "bun:test";
-import type { EventsService } from "../events/events.service";
-import type { RedisService } from "../redis/redis.service";
-import { ProgressBridge } from "./progress.bridge";
-import { PROGRESS_CHANNEL } from "./progress.processor";
+import { processProgress } from "./progress.processor";
 
-describe("ProgressBridge", () => {
-  it("delivers worker fan-out locally without republishing it", async () => {
-    let handler: ((message: string) => void) | undefined;
-    const unsubscribe = mock<() => Promise<void>>(() => Promise.resolve());
-    const subscribe = mock(
-      (channel: string, listener: (message: string) => void): Promise<() => Promise<void>> => {
-        expect(channel).toBe(PROGRESS_CHANNEL);
-        handler = listener;
-        return Promise.resolve(unsubscribe);
-      },
-    );
-    const publishLocal = mock<(data: unknown) => void>();
-    const redis = { subscribe } as unknown as RedisService;
-    const events = { publishLocal } as unknown as EventsService;
-    const bridge = new ProgressBridge(redis, events);
-
-    await bridge.connect();
-    handler?.('{"jobId":"1","progress":50}');
-    handler?.("invalid");
-
-    expect(publishLocal).toHaveBeenCalledTimes(1);
-    expect(publishLocal).toHaveBeenCalledWith({
-      type: "job-progress",
-      jobId: "1",
-      progress: 50,
-    });
-    await bridge.close();
-    expect(unsubscribe).toHaveBeenCalledTimes(1);
+describe("progress processor", () => {
+  it("publishes provider-neutral progress updates", async () => {
+    const values: number[] = [];
+    const publish = mock(async (value: number): Promise<void> => { values.push(value); });
+    const delay = mock(async (): Promise<void> => undefined);
+    await expect(processProgress({ steps: 4 }, publish, delay)).resolves.toEqual({ done: true });
+    expect(values).toEqual([25, 50, 75, 100]);
+    expect(delay).toHaveBeenCalledTimes(4);
   });
 });

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.processor.ts

@@ -1,18 +1,23 @@
-import { RedisClient } from "bun";
-import type { Job } from "bullmq";
-import { redisConnectionUrl } from "../config/redis.connection";
-
-export const PROGRESS_CHANNEL = "job:progress";
+export interface ProgressPayload {
+  steps?: number;
+}
 
-const redis = new RedisClient(redisConnectionUrl());
+function payload(value: unknown): ProgressPayload {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const steps = (value as Record<string, unknown>).steps;
+  return typeof steps === "number" ? { steps } : {};
+}
 
-export async function processProgressJob(job: Job<{ steps?: number }>): Promise<{ done: true }> {
-  const steps = job.data.steps ?? 5;
+export async function processProgress(
+  value: unknown,
+  publish: (progress: number) => Promise<void>,
+  delay: (milliseconds: number) => Promise<unknown> = Bun.sleep,
+): Promise<{ done: true }> {
+  const steps = payload(value).steps ?? 5;
   for (let index = 1; index <= steps; index += 1) {
-    await Bun.sleep(400);
+    await delay(400);
     const progress = Math.round((index / steps) * 100);
-    await job.updateProgress(progress);
-    await redis.publish(PROGRESS_CHANNEL, JSON.stringify({ jobId: job.id, progress }));
+    await publish(progress);
   }
   return { done: true };
 }

package/dist/templates/modules/job-progress/module.manifest.json

@@ -1,20 +1,19 @@
 {
   "name": "job-progress",
-  "description": "Live job progress: a worker reports progress over Redis pub/sub and the API relays it to SSE clients (combines bullmq + redis + sse).",
-  "requires": ["bullmq", "sse", "redis"],
+  "manifestVersion": 3,
+  "description": "Live job progress over the selected jobs and events providers, streamed to clients with SSE.",
+  "requires": ["sse"],
+  "requiresCapabilities": ["jobs", "events"],
   "targetApp": "api",
   "env": [],
   "inject": [
     { "file": "apps/api/src/app.ts", "marker": "// podokit:end:imports", "text": "import { jobProgressModule } from \"./progress/job-progress.module\";" },
-    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:modules", "text": "jobProgressModule," },
-    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-imports", "text": "import { processProgressJob } from \"../progress/progress.processor\";" },
-    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:end:worker-processors", "text": "{ queue: \"progress\", processor: processProgressJob }," }
+    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:modules", "text": "jobProgressModule," }
   ],
   "instructions": [
-    "Start Redis + Postgres:  docker compose -f infra/docker/docker-compose.yml up -d",
-    "Run API and worker in separate terminals:  {{rootRun}} dev   /   {{apiRun}} dev:worker{{apiWorkspaceArg}}",
+    "Configure the selected jobs and events providers before starting the API.",
     "Watch progress:  curl -N localhost:5002/events/stream",
     "Start a job:     curl -XPOST localhost:5002/progress -H 'content-type: application/json' -d '{\"steps\":5}'",
-    "The stream shows job-progress events 20 -> 40 -> ... -> 100 pushed from the worker via Redis."
+    "The stream shows job-progress events 20 -> 40 -> ... -> 100 through the selected events provider."
   ]
 }

package/dist/templates/modules/jobs-local/files/apps/api/src/jobs-local/jobs-local.module.ts

@@ -0,0 +1,42 @@
+import { AppException } from "@podosoft/podokit-contracts";
+import { JOBS } from "@podosoft/podokit-runtime";
+import { Elysia, t } from "elysia";
+import { PROVIDERS } from "../config/providers";
+import { DATABASE, type AppPlugin, type PodokitModule } from "../core/services";
+import { LocalJobQueue } from "./local-job.queue";
+
+const localJobsPlugin: AppPlugin = ({ services }) => {
+  if (PROVIDERS.jobs !== "local") return new Elysia({ name: "podokit.jobs-local.inactive" });
+  const queue = services.resolve(JOBS);
+  return new Elysia({ name: "podokit.jobs-local" })
+    .post("/jobs", async ({ body, set }) => {
+      const job = await queue.enqueue("demo", { text: body.text });
+      set.status = 201;
+      return { id: job.id };
+    }, {
+      body: t.Object({ text: t.String({ minLength: 1 }) }),
+      detail: { tags: ["jobs"], summary: "Enqueue a job" },
+    })
+    .get("/jobs/:id", async ({ params }) => {
+      const job = await queue.get(params.id);
+      if (!job) throw new AppException("JOB_NOT_FOUND", `Job ${params.id} not found`, 404);
+      return { id: job.id, state: job.status, error: job.error ?? null };
+    }, {
+      params: t.Object({ id: t.String({ minLength: 1 }) }),
+      detail: { tags: ["jobs"], summary: "Read job status" },
+    });
+};
+
+export const jobsLocalModule: PodokitModule = {
+  name: "jobs-local",
+  configure: (_env, services): void => {
+    if (PROVIDERS.jobs !== "local") return;
+    const queue = new LocalJobQueue(services.resolve(DATABASE).sql, {
+      pollIntervalMs: Number(process.env.LOCAL_JOBS_POLL_INTERVAL_MS ?? 250),
+    });
+    void queue.process("demo", () => undefined);
+    services.register(JOBS, queue, () => queue.close());
+    services.onStart(() => queue.start());
+  },
+  plugin: localJobsPlugin,
+};

package/dist/templates/modules/jobs-local/files/apps/api/src/jobs-local/local-job.queue.spec.ts

@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { SQL } from "bun";
+import { LocalJobQueue } from "./local-job.queue";
+
+let sql: SQL | undefined;
+
+afterEach(async () => {
+  await sql?.close();
+  sql = undefined;
+});
+
+describe("local job queue", () => {
+  it("persists and processes a job", async () => {
+    sql = new SQL(":memory:");
+    const queue = new LocalJobQueue(sql, { pollIntervalMs: 10 });
+    const payloads: unknown[] = [];
+    await queue.process("demo", (payload) => { payloads.push(payload); });
+    const job = await queue.enqueue("demo", { text: "hello" });
+    expect(await queue.runOnce()).toBe(true);
+    expect(payloads).toEqual([{ text: "hello" }]);
+    await expect(queue.get(job.id)).resolves.toMatchObject({
+      status: "completed",
+      attempts: 1,
+    });
+    queue.close();
+  });
+
+  it("retries failures and records the final error", async () => {
+    sql = new SQL(":memory:");
+    let now = 1_000;
+    const queue = new LocalJobQueue(sql, { pollIntervalMs: 10, now: () => now });
+    await queue.process("fail", () => { throw new Error("expected failure"); });
+    const job = await queue.enqueue("fail", {}, { attempts: 2 });
+    expect(await queue.runOnce()).toBe(true);
+    expect((await queue.get(job.id))?.status).toBe("waiting");
+    now += 10;
+    expect(await queue.runOnce()).toBe(true);
+    await expect(queue.get(job.id)).resolves.toMatchObject({
+      status: "failed",
+      attempts: 2,
+      error: "expected failure",
+    });
+    queue.close();
+  });
+});