@chidchanun/bcp 0.2.7 → 0.2.8

package/docs/background-jobs.md

@@ -0,0 +1,356 @@
+# Background Jobs Platform
+
+BCP Framework `0.2.8` adds a server-only background jobs contract through `bcp/jobs`.
+
+The goal is to provide one framework API for enqueueing and processing background work while keeping storage/queue providers replaceable.
+
+## Public entrypoint
+
+```ts
+import {
+    createJobQueue,
+    createMemoryJobQueueAdapter,
+} from "bcp/jobs";
+```
+
+`bcp/jobs` is server-only and must not be imported by pages or other client-bundled modules.
+
+## Create a queue
+
+```ts
+import {
+    createJobQueue,
+} from "bcp/jobs";
+
+export const jobs =
+    createJobQueue();
+```
+
+Without an explicit adapter BCP uses the process-local in-memory adapter.
+
+The memory adapter is intended for:
+
+- development,
+- unit/integration tests,
+- single-process prototypes,
+- applications where losing queued jobs during restart is acceptable.
+
+For durable production processing, implement `JobQueueAdapter` against shared infrastructure such as a database, Redis-backed queue, managed queue service, or another durable store.
+
+## Register handlers
+
+```ts
+jobs.register<{
+    userId: number;
+}>(
+    "email.welcome",
+    async ({
+        payload,
+        job,
+        signal,
+    }) => {
+        console.log(
+            "Attempt",
+            job.attempts
+        );
+
+        if (signal.aborted) {
+            return;
+        }
+
+        await sendWelcomeEmail(
+            payload.userId
+        );
+    }
+);
+```
+
+A job name can have only one registered handler within a queue instance.
+
+The unregister function returned by `register()` can remove the handler:
+
+```ts
+const unregister =
+    jobs.register(
+        "search.reindex",
+        reindexSearch
+    );
+
+unregister();
+```
+
+## Enqueue jobs
+
+```ts
+const job =
+    await jobs.enqueue(
+        "email.welcome",
+        {
+            userId: 42,
+        }
+    );
+```
+
+The returned record starts in `queued` state.
+
+Job states are:
+
+```text
+queued
+running
+succeeded
+failed
+cancelled
+```
+
+## Delayed jobs
+
+```ts
+await jobs.enqueue(
+    "invoice.reminder",
+    {
+        invoiceId: 9001,
+    },
+    {
+        delayMs:
+            15 * 60 * 1000,
+    }
+);
+```
+
+A delayed job remains queued until `availableAt` is reached.
+
+`delayMs` is a delay from enqueue time; `0` means the job is immediately eligible for reservation.
+
+## Retries
+
+The default maximum attempt count is `3`.
+
+```ts
+const jobs =
+    createJobQueue({
+        defaultMaxAttempts: 5,
+    });
+```
+
+Override per job:
+
+```ts
+await jobs.enqueue(
+    "payment.sync",
+    payload,
+    {
+        maxAttempts: 8,
+    }
+);
+```
+
+When a handler throws, the job is queued again while attempts remain.
+
+Default retry delay uses capped exponential backoff:
+
+```text
+attempt 1 -> 1 second
+attempt 2 -> 2 seconds
+attempt 3 -> 4 seconds
+...
+maximum   -> 30 seconds
+```
+
+Use a fixed delay:
+
+```ts
+createJobQueue({
+    retryDelayMs: 5_000,
+});
+```
+
+Or a custom backoff function:
+
+```ts
+createJobQueue({
+    retryDelayMs: attempt =>
+        attempt * 10_000,
+});
+```
+
+The callback receives the attempt number that just failed.
+
+## Manual processing
+
+`processNext()` reserves and processes one eligible job:
+
+```ts
+const processed =
+    await jobs.processNext();
+```
+
+It returns `false` when no eligible queued job is available.
+
+This form is useful for deterministic tests and custom process supervisors.
+
+## Start a worker
+
+```ts
+const worker =
+    jobs.startWorker({
+        concurrency: 4,
+        pollIntervalMs: 250,
+    });
+```
+
+`concurrency` controls the number of independent processing loops in the current process.
+
+Stop gracefully:
+
+```ts
+await worker.stop();
+```
+
+Closing the queue stops all workers created by that queue and then closes the adapter when it exposes `close()`:
+
+```ts
+await jobs.close();
+```
+
+## Cancellation
+
+```ts
+const cancelled =
+    await jobs.cancel(job.id);
+```
+
+Queued and running records can transition to `cancelled`. The in-memory adapter will not allow a later completion/failure write to replace a cancelled terminal state.
+
+Handlers receive an `AbortSignal` for worker lifecycle shutdown. Application handlers should check the signal during long-running operations when graceful cancellation matters.
+
+## Read queue state
+
+```ts
+const job =
+    await jobs.get(jobId);
+
+const allJobs =
+    await jobs.list();
+```
+
+These APIs are intended primarily for diagnostics/admin tooling and testing. Durable adapters may choose their own indexing/storage strategy behind the contract.
+
+## Adapter contract
+
+Production adapters implement:
+
+```ts
+import type {
+    JobQueueAdapter,
+} from "bcp/jobs";
+```
+
+Required operations:
+
+```text
+enqueue
+reserve
+complete
+fail
+cancel
+get
+list
+```
+
+Optional:
+
+```text
+close
+```
+
+`reserve(now)` must atomically claim one eligible queued job and increment its attempt count. This atomicity requirement is important for multi-worker or multi-instance adapters.
+
+For durable adapters, use storage-level locking/transactions/leases appropriate to the provider. Do not implement `reserve()` as an unlocked read followed by an unrelated write.
+
+## Unique job IDs
+
+BCP generates UUID job IDs by default.
+
+Applications can supply an explicit ID for idempotent enqueueing:
+
+```ts
+await jobs.enqueue(
+    "statement.generate",
+    {
+        accountId: 12,
+    },
+    {
+        id:
+            "statement-12-2026-08",
+    }
+);
+```
+
+The memory adapter rejects duplicate IDs.
+
+A durable adapter should enforce equivalent uniqueness at the storage layer.
+
+## Observability
+
+Background job infrastructure can be combined with `bcp/observability`.
+
+Recommended metrics include:
+
+```text
+jobs_enqueued_total
+jobs_completed_total
+jobs_failed_total
+jobs_retry_total
+jobs_active
+job_duration_seconds
+```
+
+Avoid putting job IDs, user IDs, email addresses, URLs, or other unbounded values into metric labels.
+
+Use a bounded job-name label when your application has a controlled handler catalog.
+
+## Deployment model
+
+The queue contract is intentionally independent from the web server lifecycle.
+
+A small deployment may start a worker in the same Node.js process as the application. Higher reliability deployments should normally run workers as separate processes/containers using a shared durable adapter.
+
+Example topology:
+
+```text
+BCP web application
+      |
+      | enqueue
+      v
+shared durable queue
+   /          \
+worker A    worker B
+```
+
+The built-in memory adapter cannot coordinate across processes or containers.
+
+## Delivery semantics
+
+BCP's adapter contract is designed for practical at-least-once processing semantics with durable adapters.
+
+A worker may retry a job after an error. Application handlers should therefore be idempotent when side effects cannot safely run twice.
+
+Examples:
+
+- use a unique database key before sending a one-time notification,
+- use idempotency keys with payment providers,
+- write processing state transactionally where possible,
+- avoid assuming one handler invocation means one side effect exactly once.
+
+## Security
+
+Job payloads are server-side application data. Do not expose `bcp/jobs` to client bundles.
+
+Avoid storing secrets in payloads when the backing adapter may persist or log the full job record. Prefer stable identifiers and load sensitive data inside the handler from the authoritative store.
+
+## 0.2.8 scope
+
+`0.2.8` provides the queue/worker contract and process-local reference adapter.
+
+It does not include a built-in Redis, PostgreSQL, SQS, RabbitMQ, Kafka, cron, or workflow-engine adapter. Those can be added behind `JobQueueAdapter` in later milestones without changing application-facing queue semantics.

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.7",
+  "versionTarget": "0.2.8",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -57,12 +57,13 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Middleware, observability, logging, caching, security and production hardening.",
+      "description": "Middleware, background jobs, observability, logging, caching, security and production hardening.",
       "pages": [
         { "route": "/docs/middleware", "source": "middleware.md", "title": "Middleware" },
         { "route": "/docs/hydration", "source": "hydration.md", "title": "Hydration" },
         { "route": "/docs/development-logging", "source": "development-logging.md", "title": "Logging" },
         { "route": "/docs/observability", "source": "observability.md", "title": "Observability Platform v2" },
+        { "route": "/docs/background-jobs", "source": "background-jobs.md", "title": "Background Jobs Platform" },
         { "route": "/docs/caching", "source": "caching.md", "title": "Caching" },
         { "route": "/docs/security", "source": "security.md", "title": "Security" },
         { "route": "/docs/production-hardening", "source": "production-hardening.md", "title": "Production Hardening" }
@@ -108,7 +109,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.7", "source": "releases/0.2.7.md", "version": "0.2.7", "state": "unreleased" },
+    { "route": "/releases/0.2.8", "source": "releases/0.2.8.md", "version": "0.2.8", "state": "unreleased" },
+    { "route": "/releases/0.2.7", "source": "releases/0.2.7.md", "version": "0.2.7" },
     { "route": "/releases/0.2.6", "source": "releases/0.2.6.md", "version": "0.2.6" },
     { "route": "/releases/0.2.5", "source": "releases/0.2.5.md", "version": "0.2.5" },
     { "route": "/releases/0.2.4", "source": "releases/0.2.4.md", "version": "0.2.4" },

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "releaseState": "unreleased",
-  "baseline": "observability-platform-v2",
+  "baseline": "background-jobs-platform",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -19,6 +19,7 @@
     "bcp/error",
     "bcp/database",
     "bcp/auth",
+    "bcp/jobs",
     "bcp/observability",
     "bcp/server",
     "bcp/server-only",
@@ -65,6 +66,13 @@
     "prometheusMetrics": true,
     "requestMetricsMiddleware": true,
     "healthChecks": true,
+    "backgroundJobsPlatform": true,
+    "jobQueueAdapterContract": true,
+    "inMemoryJobQueue": true,
+    "delayedJobs": true,
+    "jobRetries": true,
+    "jobWorkerConcurrency": true,
+    "jobCancellation": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -104,7 +112,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.6",
+    "previousBaseline": "0.2.7",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -121,7 +129,8 @@
     "authSessionStore": "auth-session-store.md",
     "authorizationSecurity": "authorization-security.md",
     "observability": "observability.md",
+    "backgroundJobs": "background-jobs.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.7.md"
+    "releaseNotes": "releases/0.2.8.md"
   }
 }

package/docs/releases/0.2.8.md

@@ -0,0 +1,150 @@
+# BCP Framework 0.2.8
+
+**Milestone:** Background Jobs Platform
+
+`0.2.8` adds a framework-native server-side background-job queue contract with a process-local reference adapter, delayed execution, retries/backoff, worker concurrency and cancellation.
+
+> Release state: unreleased until the final RC sequence, tag and npm publication complete.
+
+## New public entrypoint
+
+```ts
+import {
+    createJobQueue,
+    createMemoryJobQueueAdapter,
+} from "bcp/jobs";
+```
+
+`bcp/jobs` is server-only and is protected by both package browser exports and the BCP client-boundary validator.
+
+## Queue adapter contract
+
+Applications and ecosystem packages can implement `JobQueueAdapter` for durable/shared infrastructure.
+
+The contract covers:
+
+```text
+enqueue
+reserve
+complete
+fail
+cancel
+get
+list
+close (optional)
+```
+
+`reserve()` is the adapter's atomic claim boundary for multi-worker processing.
+
+## In-memory reference adapter
+
+`createMemoryJobQueueAdapter()` provides a dependency-free process-local adapter for development, tests and prototypes.
+
+The memory adapter is intentionally not durable and cannot coordinate multiple Node.js processes or containers.
+
+## Delayed jobs
+
+```ts
+await jobs.enqueue(
+    "report.generate",
+    payload,
+    {
+        delayMs: 60_000,
+    }
+);
+```
+
+Jobs are eligible for reservation only after `availableAt`.
+
+## Retry and backoff
+
+Queues default to three maximum attempts and capped exponential retry delay.
+
+Applications can configure a fixed delay or callback:
+
+```ts
+createJobQueue({
+    defaultMaxAttempts: 5,
+    retryDelayMs: attempt =>
+        attempt * 5_000,
+});
+```
+
+Per-job `maxAttempts` overrides the queue default.
+
+## Workers
+
+```ts
+const worker =
+    jobs.startWorker({
+        concurrency: 4,
+        pollIntervalMs: 250,
+    });
+```
+
+Workers run concurrent processing loops and can be stopped gracefully.
+
+`jobs.close()` stops all workers started by that queue and closes the adapter when supported.
+
+## Cancellation
+
+```ts
+await jobs.cancel(jobId);
+```
+
+Cancelled records remain terminal; later worker completion/failure writes do not overwrite cancellation in the memory adapter.
+
+## Manual processing
+
+`processNext()` remains available for deterministic tests and custom supervisors.
+
+```ts
+const processed =
+    await jobs.processNext();
+```
+
+## Package and platform contracts
+
+`0.2.8` adds:
+
+- `bcp/jobs` to the framework package export map,
+- TypeScript path mapping for repository development,
+- server-only client-boundary enforcement,
+- Background Jobs capability metadata in `platform-manifest.json`,
+- API-manifest ownership and docs-web navigation,
+- prepared-package smoke coverage.
+
+## Compatibility
+
+`0.2.8` does not intentionally remove or rename existing `0.2.7` public APIs.
+
+Existing applications do not need to adopt background jobs.
+
+The built-in queue is opt-in and no additional runtime dependency is installed.
+
+## Delivery semantics
+
+Durable adapters should be designed for at-least-once processing. Job handlers should be idempotent when duplicate side effects are unsafe.
+
+`0.2.8` does not promise exactly-once execution.
+
+## Not included
+
+This milestone does not ship built-in adapters for Redis, PostgreSQL, SQS, RabbitMQ, Kafka, cron scheduling or workflow orchestration.
+
+Those providers/features can be layered behind the new queue contract in later versions.
+
+## Validation
+
+Before tagging/publishing `0.2.8` run:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+The final release tag must point to the exact commit that passed the complete RC sequence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -62,6 +62,11 @@
       "browser": "./packages/client/src/server-only.browser.mjs",
       "default": "./packages/client/src/auth.ts"
     },
+    "./jobs": {
+      "types": "./packages/client/src/jobs.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/jobs.ts"
+    },
     "./observability": {
       "types": "./packages/client/src/observability.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

package/packages/bundler/src/client-boundary.ts

@@ -28,6 +28,7 @@ const SERVER_ONLY_IMPORTS =
         "bcp/server-only",
         "bcp/database",
         "bcp/auth",
+        "bcp/jobs",
         "bcp/observability",
     ]);
 

package/packages/client/src/jobs.ts

@@ -0,0 +1,16 @@
+export {
+    createJobQueue,
+    createMemoryJobQueueAdapter,
+    type BackgroundJobQueue,
+    type EnqueueJobOptions,
+    type JobHandler,
+    type JobHandlerContext,
+    type JobQueueAdapter,
+    type JobQueueOptions,
+    type JobRecord,
+    type JobRetryDelay,
+    type JobState,
+    type JobWorker,
+    type MemoryJobQueueAdapter,
+    type StartJobWorkerOptions,
+} from "../../server/src/jobs.js";