@chidchanun/bcp 0.2.15 → 0.2.17

package/README.md

@@ -1,10 +1,10 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, API routes, authentication, authorization, SQL databases, background jobs, scheduling, workflow orchestration, transactional events, realtime delivery, framework-native testing, plugin/module composition, observability, uploads, storage and standalone Node.js deployment.
+BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, API routes, authentication, authorization, SQL databases, background jobs, scheduling, workflow orchestration, transactional events, realtime delivery, framework-native testing, plugin/module composition, distributed caching, observability, uploads, storage and standalone Node.js deployment.
 
-> **Development target:** `0.2.15 — Plugin & Module Platform`
+> **Development target:** `0.2.17 — Observability Platform v3`
 >
-> `0.2.15` remains unreleased until local validation, RC checks, tagging and npm publication complete.
+> `0.2.17` remains unreleased until local validation, RC checks, tagging and npm publication complete.
 
 ## Current platform
 
@@ -27,9 +27,9 @@ BCP Framework is a React full-stack framework for file-based routing, SSR, SPA n
 | Realtime | Channels/rooms, presence, broker delivery, WebSocket adapter contract, SSE and heartbeat |
 | Testing | Request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test harnesses |
 | Plugins & modules | Dependency ordering, lifecycle hooks, config parsing, service registry and async extension hooks |
-| Observability | Structured logs, metrics, Prometheus output and health/readiness checks |
+| Caching | Legacy request/data cache plus Cache Platform v2 adapters, Redis-compatible cache/locks, stampede protection, TTL/tag/path invalidation and metrics |
+| Observability | Metrics, Prometheus, health/readiness, distributed tracing, W3C trace context and correlation IDs |
 | Uploads & storage | Multipart streaming, Local/S3-compatible storage and signed URLs |
-| Caching | Response cache and revalidation primitives |
 | Configuration | Typed config/environment validation and diagnostics |
 | Production | Standalone Node.js build, packaging, dependency pruning, Docker starter and graceful shutdown |
 | Documentation | Manifest-driven docs, platform metadata and API reference |
@@ -69,6 +69,7 @@ Generated projects normally use one framework dependency:
 ## Core backend entrypoints
 
 ```ts
+import { createCacheStore } from "bcp/cache";
 import { db } from "bcp/database";
 import { createAuth } from "bcp/auth";
 import { createJobQueue } from "bcp/jobs";
@@ -77,7 +78,10 @@ import { createTransactionalOutbox } from "bcp/events";
 import { createRealtime } from "bcp/realtime";
 import { createTestApp } from "bcp/testing";
 import { createPluginHost } from "bcp/plugins";
-import { createMetricsRegistry } from "bcp/observability";
+import {
+    createMetricsRegistry,
+    createTracer,
+} from "bcp/observability";
 ```
 
 ## Durable jobs and scheduling
@@ -116,7 +120,6 @@ export const onboarding =
                 "profile",
                 createProfile
             );
-
             workflow.parallel(
                 "initialize",
                 parallel => {
@@ -130,7 +133,6 @@ export const onboarding =
                     );
                 }
             );
-
             workflow.delay(
                 "cooldown",
                 1_000
@@ -178,34 +180,13 @@ export const realtime =
     createRealtime();
 ```
 
-Join a channel and broadcast:
-
-```ts
-const connection =
-    await realtime.connect();
-
-await connection.join(
-    "orders:42"
-);
-
-await realtime.broadcast(
-    "orders:42",
-    "order.updated",
-    {
-        status: "paid",
-    }
-);
-```
-
 BCP intentionally does not install a WebSocket server library. Applications adapt `ws`, uWebSockets.js or another transport to `RealtimeSocket`. SSE is built in through Web `Response`.
 
 Read more: [Realtime Platform](docs/realtime-platform.md)
 
 ## Testing Platform — 0.2.14
 
-`0.2.14` adds the server-only `bcp/testing` entrypoint. It is test-runner neutral and does not add Jest or Vitest as framework dependencies.
-
-### Request and route tests
+`bcp/testing` provides runner-neutral request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test helpers.
 
 ```ts
 import {
@@ -214,237 +195,228 @@ import {
     expectResponse,
 } from "bcp/testing";
 
-const handler =
-    createRouteTestHandler({
-        GET() {
-            return {
-                ok: true,
-            };
-        },
-    });
-
 const app =
     createTestApp({
-        handler,
+        handler:
+            createRouteTestHandler({
+                GET() {
+                    return {
+                        ok: true,
+                    };
+                },
+            }),
     });
 
-const response =
-    await app.get(
-        "/api/health"
-    );
-
-await expectResponse(response)
+await expectResponse(
+    await app.get("/api/health")
+)
     .status(200)
     .json({
         ok: true,
     });
 ```
 
-`createTestApp()` keeps an in-memory cookie jar, supports default headers and can send JSON bodies directly.
-
-### Authentication tests
+Read more: [Testing Platform](docs/testing-platform.md)
 
-Create a real signed BCP session token instead of a fake test-only user header:
+## Plugin & Module Platform — 0.2.15
 
 ```ts
 import {
-    createTestAuthSession,
-} from "bcp/testing";
+    createPluginHost,
+    definePlugin,
+} from "bcp/plugins";
 
-const session =
-    await createTestAuthSession(
-        {
-            id: 42,
-            role: "admin",
+const databasePlugin =
+    definePlugin({
+        name: "database",
+        setup(context) {
+            context.services.provide(
+                "database",
+                db
+            );
         },
-        {
-            secret:
-                process.env.BCP_SESSION_SECRET,
-            store:
-                authSessionStore,
-        }
-    );
+    });
 
-app.setCookie(
-    session.cookieName,
-    session.token
-);
+const jobsPlugin =
+    definePlugin({
+        name: "jobs",
+        requires: [
+            "database",
+        ],
+    });
+
+export const plugins =
+    createPluginHost({
+        plugins: [
+            jobsPlugin,
+            databasePlugin,
+        ],
+    });
 ```
 
-When `store` is provided, the matching server-side auth session record is inserted as well.
+Startup follows dependency order; stop/dispose runs in reverse order. Modules, config parsing, shared services and async hook buses are supported.
 
-### Rollback database tests
+Read more: [Plugin & Module Platform](docs/plugin-module-platform.md)
 
-```ts
-import {
-    withTestTransaction,
-} from "bcp/testing";
+## Cache Platform v2 — 0.2.16
 
-await withTestTransaction(
-    db,
-    async tx => {
-        await tx.execute(
-            "INSERT INTO users ..."
-        );
+`0.2.16` keeps the original `cache()` / `dedupe()` APIs and adds provider-neutral asynchronous cache stores.
 
-        // assertions run here
-    }
-);
+```ts
+import {
+    createCacheStore,
+    createRedisCacheAdapter,
+    createRedisCacheLockAdapter,
+} from "bcp/cache";
+
+export const cache =
+    createCacheStore({
+        adapter:
+            createRedisCacheAdapter({
+                client: redisClient,
+            }),
+        lock:
+            createRedisCacheLockAdapter({
+                client: redisClient,
+            }),
+    });
 ```
 
-The callback uses the real BCP transaction and is deliberately rolled back after the test callback succeeds.
+Distributed `getOrSet()` supports local singleflight, owner-scoped lock leases, heartbeat renewal, double-check-after-lock and contention wait/poll.
 
-### Infrastructure harnesses
+Read more: [Cache Platform v2](docs/cache-platform-v2.md)
 
-```ts
-import {
-    createJobTestHarness,
-    createOutboxTestHarness,
-    createRealtimeTestHarness,
-    createWorkflowTestHarness,
-} from "bcp/testing";
-```
+## Observability Platform v3 — 0.2.17
 
-These harnesses use the real platform contracts rather than separate mock implementations.
+`0.2.17` keeps the metrics/Prometheus/health APIs from Observability v2 and adds provider-neutral tracing and correlation.
 
-Background jobs:
+Create a tracer:
 
 ```ts
-const jobTest =
-    createJobTestHarness(
-        jobs
-    );
+import {
+    createMemoryTraceSpanExporter,
+    createTracer,
+} from "bcp/observability";
 
-await jobTest.drain();
+const traces =
+    createMemoryTraceSpanExporter();
 
-await jobTest.expectCount(
-    1,
-    {
-        name: "email.welcome",
-        state: "succeeded",
-    }
-);
+export const tracer =
+    createTracer({
+        exporter: traces,
+        serviceName: "api",
+    });
 ```
 
-Realtime:
+Create root/child spans:
 
 ```ts
-const realtimeTest =
-    createRealtimeTestHarness(
-        realtime
-    );
-
-const {
-    socket,
-    connection,
-} =
-    await realtimeTest.connect();
-
-await connection.join(
-    "orders:42"
-);
-
-await realtime.broadcast(
-    "orders:42",
-    "order.updated",
-    {
-        status: "paid",
+await tracer.withSpan(
+    "order.checkout",
+    async () => {
+        await tracer.withSpan(
+            "database.order.insert",
+            createOrder,
+            {
+                kind: "client",
+            }
+        );
     }
 );
-
-realtimeTest.expectEvent(
-    socket,
-    "order.updated",
-    "orders:42"
-);
 ```
 
-Other testing primitives include:
+Tracing context flows through normal awaited async work via Node `AsyncLocalStorage`.
 
-```text
-createFakeClock()
-createSequenceIdFactory()
-runTestMiddleware()
-createRealtimeTestSocket()
-readSseEvents()
-```
+### HTTP tracing
 
-Read more: [Testing Platform](docs/testing-platform.md)
+```ts
+import {
+    createRequestTracingMiddleware,
+} from "bcp/observability";
 
-## Plugin & Module Platform — 0.2.15
+export const middleware =
+    createRequestTracingMiddleware(
+        tracer
+    );
+```
 
-`0.2.15` adds the server-only `bcp/plugins` entrypoint for reusable application/framework extensions.
+The middleware continues valid W3C `traceparent` headers, preserves `x-correlation-id`, creates a server span and returns current trace headers on the response.
 
-Define plugins with explicit dependencies:
+### Jobs / workflow / events / realtime propagation
 
 ```ts
 import {
-    createPluginHost,
-    definePlugin,
-} from "bcp/plugins";
+    createTraceCarrier,
+    runWithTraceCarrier,
+} from "bcp/observability";
 
-const databasePlugin =
-    definePlugin({
-        name: "database",
-        setup(context) {
-            context.services.provide(
-                "database",
-                db
-            );
-        },
-        start() {
-            return db.connect();
-        },
-        stop() {
-            return db.disconnect();
-        },
-    });
+const trace =
+    createTraceCarrier();
 
-const jobsPlugin =
-    definePlugin({
-        name: "jobs",
-        requires: [
-            "database",
-        ],
-    });
+await jobs.enqueue(
+    "order.process",
+    {
+        orderId,
+        trace,
+    }
+);
+```
 
-const host =
-    createPluginHost({
-        plugins: [
-            jobsPlugin,
-            databasePlugin,
-        ],
-    });
+Consumer:
 
-await host.start();
+```ts
+await runWithTraceCarrier(
+    payload.trace,
+    () =>
+        tracer.withSpan(
+            "job order.process",
+            handler,
+            {
+                kind: "consumer",
+            }
+        )
+);
 ```
 
-Dependency order is resolved automatically. Startup follows dependency order while stop/dispose runs in reverse order.
+The same carrier can be placed in workflow input, outbox/event metadata and realtime payloads when trace continuity is needed across those boundaries.
 
-Modules group reusable plugin sets:
+### Trace-to-metrics and logs
 
 ```ts
 import {
-    defineModule,
-} from "bcp/plugins";
-
-const backendModule =
-    defineModule({
-        name: "backend",
-        plugins: [
-            databasePlugin,
-            jobsPlugin,
-        ],
-    });
+    createCompositeTraceSpanExporter,
+    createMetricsRegistry,
+    createTraceMetricsExporter,
+    getTraceLogFields,
+} from "bcp/observability";
+
+const metrics =
+    createMetricsRegistry();
+
+const exporter =
+    createCompositeTraceSpanExporter([
+        createTraceMetricsExporter(
+            metrics
+        ),
+        productionTraceExporter,
+    ]);
+
+logger.info(
+    "order created",
+    {
+        ...getTraceLogFields(),
+        orderId,
+    }
+);
 ```
 
-Plugin configuration can be parsed at setup time and overridden through `createPluginHost({ configs })`.
+Default trace metrics use low-cardinality `kind` and `status` labels. Span-name labels are opt-in.
 
-Plugins share a service registry and awaited in-process hook bus through `context.services` and `context.hooks`.
+BCP does not install an OpenTelemetry SDK or vendor APM package; production exporters remain application-owned through `TraceSpanExporter`.
 
-If startup fails, already-started plugins are stopped in reverse order before the lifecycle error is propagated.
+Prepared npm packages compile `bcp/observability` to `observability.mjs` for standalone Node runtime use.
 
-Read more: [Plugin & Module Platform](docs/plugin-module-platform.md)
+Read more: [Observability Platform v3](docs/observability-v3.md)
 
 ## Public entrypoints
 
@@ -509,7 +481,7 @@ bcp generate migration create_users
 ```text
 Browser / API / Realtime clients
               |
-      security + auth
+       tracing + security
               |
           Plugin Host
        /      |       \
@@ -518,10 +490,14 @@ Browser / API / Realtime clients
  outbox       jobs       |
     \__________|_________/
            durable state
-
-Testing Platform exercises these server contracts without becoming part of browser runtime.
+              |
+       shared cache layer
+              |
+      metrics + trace export
 ```
 
+Cache remains an optimization layer. Database/outbox/jobs/workflows remain the durable truth. Realtime remains transient delivery. Tracing correlates those operations without replacing their state contracts.
+
 ## Packaging
 
 ```bash
@@ -547,7 +523,7 @@ docs/api-manifest.json
 
 ## Release validation
 
-Before publishing `0.2.15`:
+Before publishing `0.2.17`:
 
 ```bash
 npm run typecheck
@@ -558,7 +534,7 @@ npm run test:package
 npm run rc:check
 ```
 
-`0.2.15` adds unit and prepared-package smoke coverage for plugin dependency ordering, missing/cyclic dependencies, modules, config parsing, shared services, async hooks, lifecycle rollback, compiled `plugins.mjs` execution and browser boundary enforcement.
+`0.2.17` adds unit and prepared-package smoke coverage for root/child spans, async context propagation, W3C trace headers, correlation carriers, request tracing, error spans, trace metrics and compiled `observability.mjs` execution.
 
 Do not tag or publish until the exact final release commit passes the full RC sequence.
 
@@ -588,12 +564,16 @@ Do not tag or publish until the exact final release commit passes the full RC se
 | `0.2.13` | Realtime Platform |
 | `0.2.14` | Testing Platform |
 | `0.2.15` | Plugin & Module Platform |
+| `0.2.16` | Cache Platform v2 |
+| `0.2.17` | Observability Platform v3 |
 
 ## Roadmap
 
-`0.2.15` establishes reusable server-side extension composition while keeping BCP subsystem contracts provider-neutral and independently testable.
+`0.2.17` establishes trace/correlation continuity across the current server platform without coupling BCP to a specific telemetry vendor.
+
+The next logical milestone is **`0.2.18 — Deployment Platform v2`**, focused on completing compiled production entrypoints, deployment/runtime adapters, process lifecycle integration, container/runtime metadata and production diagnostics.
 
-The next logical milestone is **`0.2.16 — Cache Platform v2`**, focused on distributed cache adapters, Redis-compatible caching, locking, stampede protection and production cache observability.
+`0.2.19` is planned as the stabilization/API-freeze pass before the next `0.3.0` platform baseline.
 
 Native desktop/mobile compilation remains later roadmap work.