@chidchanun/bcp 0.2.6 → 0.2.8

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, 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, observability, validation, uploads, storage and standalone Node.js production deployment.
 
-> **Development target:** `0.2.6 — Authorization & Security v2`
+> **Development target:** `0.2.8 — Background Jobs Platform`
 >
-> `0.2.6` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.8` 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, and `0.2.6` adds permission/policy authorization plus CSRF and same-origin request protection without intentionally removing the existing public application model.
+`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.
 
 Machine-readable platform contracts:
 
@@ -35,10 +35,11 @@ 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 |
+| 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 |
 | Database | Provider-neutral MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle and migrations |
-| Logging | Structured logger, request logger and request IDs |
 | Uploads | Buffered multipart helpers and production multipart streaming |
 | Storage | Local + S3-compatible storage, streaming, list/copy/move, metadata, bulk delete and signed URLs |
 | Caching | Response cache and revalidation primitives |
@@ -242,8 +243,6 @@ Read more:
 
 ## Authorization & Security v2 — 0.2.6
 
-### Permissions
-
 Use flat permissions directly from `bcp/auth`:
 
 ```ts
@@ -268,24 +267,7 @@ await requirePermission(
 );
 ```
 
-Route trees can use a permission guard:
-
-```ts
-import {
-    createPermissionGuard,
-} from "bcp/auth";
-
-export const guard =
-    createPermissionGuard(
-        "admin.access"
-    );
-```
-
-The default permission field is `permissions`. Applications can select another field such as `scopes`.
-
-### Resource policies
-
-For ownership, tenant or resource-state rules:
+Resource-aware policies:
 
 ```ts
 import {
@@ -312,17 +294,6 @@ await authorize(
 );
 ```
 
-Available policy helpers:
-
-```text
-can()
-cannot()
-authorize()
-AuthorizationError
-```
-
-### Same-origin and CSRF protection
-
 Request-security helpers are exposed from `bcp/server`:
 
 ```ts
@@ -333,43 +304,117 @@ import {
 } from "bcp/server";
 ```
 
-Protect an unsafe API/action mutation with origin validation:
+Read more: [Authorization & Security v2](docs/authorization-security.md)
+
+## Observability Platform v2 — 0.2.7
+
+Create one application metrics registry:
 
 ```ts
-await requireSameOriginRequest();
+import {
+    createMetricsRegistry,
+} from "bcp/observability";
+
+export const metrics =
+    createMetricsRegistry();
+```
+
+Supported metric types:
+
+```text
+counter
+gauge
+histogram
 ```
 
-For signed CSRF protection:
+Expose Prometheus-compatible text:
 
 ```ts
-const csrfToken =
-    await createCsrfToken();
+import {
+    createMetricsResponse,
+} from "bcp/observability";
+
+export function GET() {
+    return createMetricsResponse(
+        metrics
+    );
+}
+```
 
-// Render/send csrfToken through the trusted application UI.
+Health/readiness registry:
 
-await requireCsrfRequest({
-    token: submittedToken,
-});
+```ts
+import {
+    createHealthRegistry,
+} from "bcp/observability";
+
+export const health =
+    createHealthRegistry();
 ```
 
-Default CSRF header/cookie:
+Read more: [Observability Platform v2](docs/observability.md)
 
-```text
-X-BCP-CSRF
-bcp_csrf
+## Background Jobs Platform — 0.2.8
+
+Create a server-side queue:
+
+```ts
+import {
+    createJobQueue,
+} from "bcp/jobs";
+
+export const jobs =
+    createJobQueue();
 ```
 
-Secret resolution:
+Register a handler:
 
-```text
-explicit options.secret
-    ↓
-BCP_CSRF_SECRET
-    ↓
-BCP_SESSION_SECRET
+```ts
+jobs.register<{
+    userId: number;
+}>(
+    "email.welcome",
+    async ({ payload }) => {
+        await sendWelcomeEmail(
+            payload.userId
+        );
+    }
+);
 ```
 
-Read more: [Authorization & Security v2](docs/authorization-security.md)
+Enqueue immediately or with a delay:
+
+```ts
+await jobs.enqueue(
+    "email.welcome",
+    {
+        userId: 42,
+    },
+    {
+        delayMs: 5_000,
+        maxAttempts: 5,
+    }
+);
+```
+
+Start concurrent workers:
+
+```ts
+const worker =
+    jobs.startWorker({
+        concurrency: 4,
+        pollIntervalMs: 250,
+    });
+
+// graceful shutdown
+await worker.stop();
+```
+
+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.
+
+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()`.
+
+Read more: [Background Jobs Platform](docs/background-jobs.md)
 
 ## Public entrypoints
 
@@ -384,6 +429,8 @@ bcp/validation
 bcp/error
 bcp/database
 bcp/auth
+bcp/jobs
+bcp/observability
 bcp/server
 bcp/server-only
 bcp/middleware
@@ -446,6 +493,9 @@ Loader / action / API route
 React SSR
   ↓
 Hydration / SPA navigation
+
+Operational side channels:
+background jobs + structured logs + metrics + health/readiness
 ```
 
 ## Production build
@@ -491,7 +541,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.6` adds Authorization & Security v2 unit and prepared-package smoke checks covering permission matching, policy authorization, permission route guards, same-origin mutation validation and signed CSRF tokens.
+`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.
 
 Do not tag or publish until the final release commit passes the complete RC sequence.
 
@@ -512,12 +562,14 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.4` | Application Packaging |
 | `0.2.5` | Authentication Platform v2 |
 | `0.2.6` | Authorization & Security v2 |
+| `0.2.7` | Observability Platform v2 |
+| `0.2.8` | Background Jobs Platform |
 
 ## Roadmap
 
-`0.2.6 — Authorization & Security v2` establishes the permission/policy and browser-mutation security layer on top of Authentication Platform v2.
+`0.2.8 — Background Jobs Platform` establishes a provider-neutral queue/worker contract on top of the existing server runtime and lifecycle model.
 
-The next `0.2.x` milestone can build on the existing runtime, database, auth, security and packaging contracts. Native `.exe`, desktop and mobile compilation remain later roadmap work.
+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.
 
 ## License
 

package/docs/README.md

@@ -2,7 +2,7 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.2.6 — Authorization & Security v2`
+> **Documentation target:** BCP Framework `0.2.8 — Background Jobs Platform`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -52,66 +52,51 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.4` | Application Packaging |
 | `0.2.5` | Authentication Platform v2 |
 | `0.2.6` | Authorization & Security v2 |
+| `0.2.7` | Observability Platform v2 |
+| `0.2.8` | Background Jobs Platform |
 
-## 0.2.6 — Authorization & Security v2
+## 0.2.8 — Background Jobs Platform
 
-`0.2.6` adds server-side permission checks, resource-aware authorization policies, permission route guards, same-origin mutation validation and signed CSRF protection.
+`0.2.8` adds a server-only provider-neutral queue/worker layer without adding a third-party queue dependency.
 
 New/updated documentation sources:
 
 | Source | Purpose |
 | --- | --- |
-| `authorization-security.md` | Permissions, policies, permission guards, same-origin validation and CSRF APIs |
-| `auth-route-guards.md` | Auth/guest/role/permission route guard guidance |
-| `api-reference.md` | Public authorization and request-security exports |
-| `platform-manifest.json` | Authorization/security capability flags |
-| `api-manifest.json` | `bcp/auth` and `bcp/server` guide ownership |
-| `releases/0.2.6.md` | Authorization & Security v2 release notes |
+| `background-jobs.md` | Queue contract, memory adapter, delay, retries, workers and production guidance |
+| `api-reference.md` | Public `bcp/jobs` exports |
+| `platform-manifest.json` | Background Jobs capability flags and public entrypoint |
+| `api-manifest.json` | `bcp/jobs` guide ownership |
+| `docs-web-manifest.json` | Background Jobs navigation and `0.2.8` release route |
+| `releases/0.2.8.md` | Background Jobs Platform release notes |
 
-Primary authorization APIs:
+Primary APIs:
 
 ```ts
 import {
-    authorize,
-    can,
-    createPermissionGuard,
-    defineAuthorizationPolicy,
-    hasPermission,
-    requirePermission,
-} from "bcp/auth";
+    createJobQueue,
+    createMemoryJobQueueAdapter,
+} from "bcp/jobs";
 ```
 
-Primary browser-mutation security APIs:
-
-```ts
-import {
-    createCsrfToken,
-    requireCsrfRequest,
-    requireSameOriginRequest,
-} from "bcp/server";
-```
-
-## Security model
-
-The `0.2.6` server model separates concerns:
+Runtime model:
 
 ```text
-authentication
-    -> identify a signed/revocable session
-
-authorization
-    -> permissions + policies + route guards
-
-request security
-    -> Origin/Referer validation + signed CSRF token
-
-input validation
-    -> application schema/domain checks
+web/API/action
+    |
+    | enqueue
+    v
+JobQueueAdapter
+    |
+    v
+worker loop(s)
+    |
+    +-> success
+    +-> retry/backoff
+    +-> failed/cancelled
 ```
 
-All authorization decisions must remain server-side. Client UI permission checks may improve presentation but do not replace route/action/API enforcement.
-
-CSRF tokens use `BCP_CSRF_SECRET` when configured and otherwise fall back to `BCP_SESSION_SECRET`. Security secrets must contain at least 32 UTF-8 bytes.
+The built-in memory adapter is process-local and not durable. Multi-process/container production deployments should implement `JobQueueAdapter` against shared durable infrastructure.
 
 ## Update rule
 
@@ -150,13 +135,14 @@ Important current routes:
 | Website route | Markdown source |
 | --- | --- |
 | `/docs/authentication` | `authentication.md` |
-| `/docs/auth-session-store` | `auth-session-store.md` |
-| `/docs/auth-route-guards` | `auth-route-guards.md` |
 | `/docs/authorization-security` | `authorization-security.md` |
+| `/docs/observability` | `observability.md` |
+| `/docs/background-jobs` | `background-jobs.md` |
+| `/docs/development-logging` | `development-logging.md` |
 | `/docs/application-packaging` | `application-packaging.md` |
 | `/docs/database` | `database.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.6` | `releases/0.2.6.md` |
+| `/releases/0.2.8` | `releases/0.2.8.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -196,6 +182,8 @@ bcp/validation
 bcp/error
 bcp/database
 bcp/auth
+bcp/jobs
+bcp/observability
 bcp/server
 bcp/server-only
 bcp/middleware
@@ -235,7 +223,7 @@ synchronize CMS/search/navigation
 
 ## Release validation
 
-Before publishing `0.2.6`:
+Before publishing `0.2.8`:
 
 ```bash
 npm run typecheck
@@ -246,16 +234,15 @@ npm run test:e2e
 npm run rc:check
 ```
 
-Authorization & Security v2 validation covers:
+Background Jobs Platform validation covers:
 
-- permission normalization and any/all matching,
-- permission route guards,
-- sync/async authorization policies,
-- `AuthorizationError` denial behavior,
-- same-origin mutation checks,
-- signed CSRF tokens,
-- malformed/cross-origin rejection,
-- public `bcp/auth` and `bcp/server` exports,
+- immediate and delayed jobs,
+- retry/backoff behavior,
+- terminal success/failure/cancellation states,
+- duplicate job IDs,
+- worker concurrency and graceful stop,
+- public `bcp/jobs` exports,
+- server-only browser/client boundaries,
 - prepared npm package contents,
 - docs/platform/API version parity.
 

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -94,6 +94,28 @@
         "/docs/session-auth"
       ]
     },
+    {
+      "package": "bcp/jobs",
+      "source": "packages/client/src/jobs.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-jobs",
+      "summary": "Background job queue contract with in-memory adapter, delayed jobs, retry/backoff, cancellation and concurrent workers.",
+      "guides": [
+        "/docs/background-jobs",
+        "/docs/observability"
+      ]
+    },
+    {
+      "package": "bcp/observability",
+      "source": "packages/client/src/observability.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-observability",
+      "summary": "In-process metrics, Prometheus exposition, request metrics middleware and health/readiness checks.",
+      "guides": [
+        "/docs/observability",
+        "/docs/development-logging"
+      ]
+    },
     {
       "package": "bcp/server",
       "source": "packages/client/src/server.ts",

package/docs/api-reference.md

@@ -226,6 +226,73 @@ Authorization & Security v2 adds permission checks, permission route guards and
 
 Related guides: [Authentication](authentication.md), [Auth Session Stores](auth-session-store.md), [Auth Route Guards](auth-route-guards.md), [Authorization & Security v2](authorization-security.md), [JWT Sessions](session-auth.md).
 
+## `bcp/jobs`
+
+Server-only Background Jobs Platform APIs.
+
+```ts
+import {
+    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 "bcp/jobs";
+```
+
+`createJobQueue()` provides delayed enqueueing, retry/backoff, cancellation, manual `processNext()` execution and concurrent workers. The default adapter is process-local memory storage and is intended for development, tests and single-process prototypes.
+
+Production applications that require durable processing should implement `JobQueueAdapter` against shared infrastructure. Adapter `reserve()` must atomically claim one eligible queued job so multiple workers cannot process the same reservation concurrently.
+
+The queue contract is designed for practical at-least-once processing; handlers should be idempotent when duplicate side effects are unsafe.
+
+Related guides: [Background Jobs Platform](background-jobs.md), [Observability Platform v2](observability.md).
+
+## `bcp/observability`
+
+Server-only Observability Platform v2 APIs.
+
+```ts
+import {
+    createHealthRegistry,
+    createMetricsRegistry,
+    createMetricsResponse,
+    createRequestMetricsMiddleware,
+    type CounterMetric,
+    type GaugeMetric,
+    type HealthCheck,
+    type HealthCheckOptions,
+    type HealthCheckReportItem,
+    type HealthCheckResult,
+    type HealthRegistry,
+    type HealthReport,
+    type HistogramMetric,
+    type HistogramOptions,
+    type MetricDefinitionOptions,
+    type MetricLabels,
+    type MetricLabelValue,
+    type MetricsRegistry,
+    type RequestMetricsOptions,
+} from "bcp/observability";
+```
+
+`createMetricsRegistry()` provides process-local counters, gauges and histograms. `createMetricsResponse()` renders Prometheus-compatible text exposition. `createRequestMetricsMiddleware()` measures HTTP request counts and duration using bounded `method` / `status` labels by default and intentionally does not label by raw path.
+
+`createHealthRegistry()` registers synchronous or asynchronous liveness/readiness checks, applies per-check timeouts and produces JSON health responses with HTTP `200` when all checks pass or `503` when any check fails.
+
+The built-in registry is process-local. Multi-instance deployments should scrape each process/container or aggregate through external monitoring infrastructure.
+
+Related guides: [Observability Platform v2](observability.md), [Logging](development-logging.md).
+
 ## `bcp/server`
 
 Server request/runtime APIs.