@chidchanun/bcp 0.2.8 → 0.2.10

package/README.md

@@ -1,14 +1,14 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, authorization, database access, background jobs, observability, validation, uploads, storage and standalone Node.js production deployment.
+BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, authorization, database access, background jobs, recurring scheduling, observability, validation, uploads, storage and standalone Node.js production deployment.
 
-> **Development target:** `0.2.8 — Background Jobs Platform`
+> **Development target:** `0.2.10 — Durable Jobs Platform`
 >
-> `0.2.8` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.10` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
 
 ## 0.2 platform
 
-`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, `0.2.2` added Configuration & Environment v2, `0.2.3` added Database Platform v2, `0.2.4` added Application Packaging, `0.2.5` added Authentication Platform v2, `0.2.6` added Authorization & Security v2, `0.2.7` added Observability Platform v2, and `0.2.8` adds a provider-neutral background-job queue/worker contract with delayed work, retry/backoff, cancellation and process-local reference storage.
+`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, `0.2.2` added Configuration & Environment v2, `0.2.3` added Database Platform v2, `0.2.4` added Application Packaging, `0.2.5` added Authentication Platform v2, `0.2.6` added Authorization & Security v2, `0.2.7` added Observability Platform v2, `0.2.8` added Background Jobs Platform, `0.2.9` added recurring scheduling, and `0.2.10` adds durable worker leases, DLQ maintenance and Redis-compatible queue/scheduler adapters.
 
 Machine-readable platform contracts:
 
@@ -35,7 +35,9 @@ docs/api-manifest.json
 | Authorization | Auth/guest/role/permission route guards, flat permissions and resource-aware policies |
 | Request security | Same-origin validation and signed CSRF tokens for unsafe mutations |
 | Middleware | Middleware System v2 with onion execution |
-| Background jobs | Adapter contract, in-memory queue, delayed jobs, retries/backoff, cancellation and concurrent workers |
+| Background jobs | Delayed jobs, retries/backoff, cancellation, concurrent workers, visibility leases, heartbeat, stale recovery and DLQ |
+| Scheduling | Recurring interval jobs, UTC cron, schedule-store leases and deterministic scheduled run IDs |
+| Durable jobs | Redis-compatible queue/schedule adapters, retention cleanup, requeue and queue statistics |
 | Observability | Structured logs, counters/gauges/histograms, Prometheus output, request metrics and health/readiness checks |
 | Validation | Typed validators and structured validation errors |
 | Error handling | HTTP error helpers and consistent error responses |
@@ -130,8 +132,6 @@ Read more:
 
 ## Database Platform v2 — 0.2.3
 
-Application code uses one server-only database entrypoint across supported SQL providers:
-
 ```ts
 import {
     db,
@@ -147,16 +147,6 @@ postgresql
 sqlite
 ```
 
-Lifecycle control:
-
-```ts
-await db.connect();
-
-// application work
-
-await db.disconnect();
-```
-
 Migration CLI:
 
 ```bash
@@ -179,23 +169,10 @@ Create a fresh production build and deployment package:
 bcp package
 ```
 
-Output:
+Output is written under:
 
 ```text
 .bcp-framework/package/
-├─ client/
-├─ server/
-│  └─ server.mjs
-├─ public/                 # when present
-├─ manifest.json
-├─ package.json
-├─ package-lock.json       # when a safe npm v3 production lock can be derived
-├─ bcp.package.json
-├─ bcp.deployment.json
-├─ bcp.env.json
-├─ Dockerfile
-├─ .dockerignore
-└─ README.md
 ```
 
 Read more:
@@ -205,35 +182,17 @@ Read more:
 
 ## Authentication Platform v2 — 0.2.5
 
-Stateless signed JWT-cookie authentication remains supported:
-
 ```ts
 import {
     auth,
-    login,
-    logout,
-} from "bcp/auth";
-```
-
-Applications that need centralized revocation can add a server-side session store:
-
-```ts
-import {
     createAuth,
     createMemoryAuthSessionStore,
+    login,
+    logout,
 } from "bcp/auth";
-
-const sessionStore =
-    createMemoryAuthSessionStore();
-
-export const appAuth =
-    createAuth({
-        store: sessionStore,
-        idleTimeout: 60 * 30,
-    });
 ```
 
-With a store configured, authentication requires both a valid signed JWT cookie and an active `sid` record. The built-in memory store is intended for development/tests; production multi-instance deployments should implement `AuthSessionStore` with shared storage.
+Stateless signed JWT-cookie authentication remains supported. Applications that need centralized revocation can configure an `AuthSessionStore`.
 
 Read more:
 
@@ -243,55 +202,12 @@ Read more:
 
 ## Authorization & Security v2 — 0.2.6
 
-Use flat permissions directly from `bcp/auth`:
-
 ```ts
 import {
+    authorize,
     hasPermission,
     requirePermission,
 } from "bcp/auth";
-
-hasPermission(
-    user,
-    "users.read"
-);
-
-await requirePermission(
-    [
-        "users.read",
-        "users.write",
-    ],
-    {
-        match: "all",
-    }
-);
-```
-
-Resource-aware policies:
-
-```ts
-import {
-    authorize,
-    defineAuthorizationPolicy,
-} from "bcp/auth";
-
-const updateProject =
-    defineAuthorizationPolicy(
-        ({
-            user,
-            resource,
-        }) =>
-            resource.ownerId ===
-            user.id
-    );
-
-await authorize(
-    updateProject,
-    {
-        user,
-        resource: project,
-    }
-);
 ```
 
 Request-security helpers are exposed from `bcp/server`:
@@ -308,56 +224,18 @@ Read more: [Authorization & Security v2](docs/authorization-security.md)
 
 ## Observability Platform v2 — 0.2.7
 
-Create one application metrics registry:
-
 ```ts
 import {
+    createHealthRegistry,
     createMetricsRegistry,
-} from "bcp/observability";
-
-export const metrics =
-    createMetricsRegistry();
-```
-
-Supported metric types:
-
-```text
-counter
-gauge
-histogram
-```
-
-Expose Prometheus-compatible text:
-
-```ts
-import {
     createMetricsResponse,
 } from "bcp/observability";
-
-export function GET() {
-    return createMetricsResponse(
-        metrics
-    );
-}
-```
-
-Health/readiness registry:
-
-```ts
-import {
-    createHealthRegistry,
-} from "bcp/observability";
-
-export const health =
-    createHealthRegistry();
 ```
 
 Read more: [Observability Platform v2](docs/observability.md)
 
 ## Background Jobs Platform — 0.2.8
 
-Create a server-side queue:
-
 ```ts
 import {
     createJobQueue,
@@ -367,7 +245,7 @@ export const jobs =
     createJobQueue();
 ```
 
-Register a handler:
+Register work:
 
 ```ts
 jobs.register<{
@@ -382,7 +260,7 @@ jobs.register<{
 );
 ```
 
-Enqueue immediately or with a delay:
+Enqueue work:
 
 ```ts
 await jobs.enqueue(
@@ -397,24 +275,153 @@ await jobs.enqueue(
 );
 ```
 
-Start concurrent workers:
+Read more: [Background Jobs Platform](docs/background-jobs.md)
+
+## Job Scheduling Platform — 0.2.9
+
+```ts
+import {
+    createJobScheduler,
+} from "bcp/jobs";
+
+export const scheduler =
+    createJobScheduler({
+        queue: jobs,
+    });
+```
+
+Interval schedule:
+
+```ts
+await scheduler.schedule(
+    "cache.cleanup",
+    {},
+    {
+        id: "cache-cleanup",
+        everyMs: 5 * 60 * 1000,
+    }
+);
+```
+
+UTC cron schedule:
+
+```ts
+await scheduler.schedule(
+    "report.weekday",
+    {},
+    {
+        cron: "30 9 * * 1-5",
+    }
+);
+```
+
+Read more: [Job Scheduling Platform](docs/job-scheduling.md)
+
+## Durable Jobs Platform — 0.2.10
+
+Workers now support visibility leases, heartbeat renewal and stale-running recovery when the configured adapter implements those capabilities:
 
 ```ts
 const worker =
     jobs.startWorker({
+        workerId: "email-worker",
         concurrency: 4,
+        visibilityTimeoutMs: 30_000,
+        heartbeatIntervalMs: 10_000,
         pollIntervalMs: 250,
     });
+```
+
+Retry-exhausted jobs can be inspected and requeued:
+
+```ts
+const failed =
+    await jobs.deadLetters();
+
+await jobs.requeueDeadLetter(
+    failed[0].id,
+    {
+        delayMs: 5_000,
+        resetAttempts: true,
+    }
+);
+```
+
+Operational helpers:
+
+```ts
+await jobs.recoverStale({
+    limit: 100,
+});
+
+const stats =
+    await jobs.stats();
+
+await jobs.cleanup({
+    before:
+        Date.now() -
+        7 * 24 * 60 * 60 * 1000,
+});
+```
+
+### Redis-compatible durable queue
+
+BCP does not install a Redis client library. Supply an application-owned client that implements:
+
+```ts
+interface RedisCommandClient {
+    sendCommand(
+        command: string[]
+    ): Promise<unknown>;
+}
+```
+
+Then create the adapters:
+
+```ts
+import {
+    createJobQueue,
+    createJobScheduler,
+    createRedisJobQueueAdapter,
+    createRedisJobScheduleStore,
+} from "bcp/jobs";
+
+const queueAdapter =
+    createRedisJobQueueAdapter({
+        client: redisCommandClient,
+        namespace: "my-app:{jobs}",
+    });
+
+export const jobs =
+    createJobQueue({
+        adapter: queueAdapter,
+    });
+
+const scheduleStore =
+    createRedisJobScheduleStore({
+        client: redisCommandClient,
+        namespace: "my-app:{jobs}",
+    });
 
-// graceful shutdown
-await worker.stop();
+export const scheduler =
+    createJobScheduler({
+        queue: jobs,
+        store: scheduleStore,
+        ownerId: "scheduler-a",
+    });
 ```
 
-The default in-memory adapter is process-local and is intended for development/tests/prototypes. Durable multi-process deployments should implement `JobQueueAdapter` against shared infrastructure. Adapter `reserve()` must atomically claim work.
+The Redis reference adapters use atomic Lua operations for reservations, visibility leases, heartbeat, stale recovery, DLQ requeue and scheduler leasing. The default namespace is `bcp:{jobs}` so keys share one Redis Cluster hash slot.
 
-Retry behavior is configurable with fixed or callback-based backoff. The default is capped exponential backoff. Jobs can also be cancelled and inspected with `get()` / `list()`.
+A typical application may configure its Redis client with:
 
-Read more: [Background Jobs Platform](docs/background-jobs.md)
+```dotenv
+REDIS_URL=redis://localhost:6379
+```
+
+BCP does not read `REDIS_URL` automatically; connection creation, TLS/Cluster settings and credentials remain application-owned.
+
+Read more: [Durable Jobs Platform](docs/durable-jobs.md)
 
 ## Public entrypoints
 
@@ -479,27 +486,21 @@ bcp generate middleware
 bcp generate migration create_users
 ```
 
-## Application model
+## Production model
 
 ```text
-Browser
-  ↓
-Origin / CSRF / middleware / cache
-  ↓
-Authentication + authorization guard
-  ↓
-Loader / action / API route
-  ↓
-React SSR
-  ↓
-Hydration / SPA navigation
+Browser / API clients
+        ↓
+security + middleware + auth
+        ↓
+loaders / actions / API routes
+        ↓
+SSR / application responses
 
 Operational side channels:
-background jobs + structured logs + metrics + health/readiness
+shared jobs + scheduler + structured logs + metrics + health/readiness
 ```
 
-## Production build
-
 Raw standalone build:
 
 ```bash
@@ -513,8 +514,6 @@ Deployment package:
 bcp package
 ```
 
-Both current targets remain Node.js `standalone-node` applications.
-
 ## Documentation Platform
 
 The framework repository is the documentation source of truth.
@@ -541,7 +540,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.8` adds Background Jobs Platform unit and prepared-package smoke checks covering delayed work, retries/backoff, cancellation, worker concurrency, server-only boundaries and the public `bcp/jobs` package surface.
+`0.2.10` adds Durable Jobs Platform unit and prepared-package smoke checks covering visibility leases, heartbeat renewal, stale recovery, DLQ/requeue, retention/statistics, Redis queue/scheduler command contracts and the compiled `bcp/jobs` runtime.
 
 Do not tag or publish until the final release commit passes the complete RC sequence.
 
@@ -564,12 +563,14 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.6` | Authorization & Security v2 |
 | `0.2.7` | Observability Platform v2 |
 | `0.2.8` | Background Jobs Platform |
+| `0.2.9` | Job Scheduling Platform |
+| `0.2.10` | Durable Jobs Platform |
 
 ## Roadmap
 
-`0.2.8 — Background Jobs Platform` establishes a provider-neutral queue/worker contract on top of the existing server runtime and lifecycle model.
+`0.2.10 — Durable Jobs Platform` establishes shared production queue/scheduler adapters and worker recovery semantics while keeping the provider-neutral `bcp/jobs` contract.
 
-Later `0.2.x` work can add durable queue providers, recurring schedules, distributed leases or workflow orchestration without changing the base enqueue/worker contract. Native `.exe`, desktop and mobile compilation remain later roadmap work.
+Later `0.2.x` work can add workflow orchestration, transactional outbox helpers or additional durable providers without changing the base queue/scheduler model. Native `.exe`, desktop and mobile compilation remain later roadmap work.
 
 ## License