@chidchanun/bcp 0.2.7 → 0.2.9

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.9",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -57,12 +57,14 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Middleware, observability, logging, caching, security and production hardening.",
+      "description": "Middleware, background jobs, scheduling, 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/job-scheduling", "source": "job-scheduling.md", "title": "Job Scheduling 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 +110,9 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.7", "source": "releases/0.2.7.md", "version": "0.2.7", "state": "unreleased" },
+    { "route": "/releases/0.2.9", "source": "releases/0.2.9.md", "version": "0.2.9", "state": "unreleased" },
+    { "route": "/releases/0.2.8", "source": "releases/0.2.8.md", "version": "0.2.8" },
+    { "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" },