@chidchanun/bcp 0.2.16 → 0.2.17

package/README.md

@@ -2,9 +2,9 @@
 
 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.16 — Cache Platform v2`
+> **Development target:** `0.2.17 — Observability Platform v3`
 >
-> `0.2.16` 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
 
@@ -28,7 +28,7 @@ BCP Framework is a React full-stack framework for file-based routing, SSR, SPA n
 | 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 |
 | Caching | Legacy request/data cache plus Cache Platform v2 adapters, Redis-compatible cache/locks, stampede protection, TTL/tag/path invalidation and metrics |
-| Observability | Structured logs, metrics, Prometheus output and health/readiness checks |
+| Observability | Metrics, Prometheus, health/readiness, distributed tracing, W3C trace context and correlation IDs |
 | Uploads & storage | Multipart streaming, Local/S3-compatible storage and signed URLs |
 | Configuration | Typed config/environment validation and diagnostics |
 | Production | Standalone Node.js build, packaging, dependency pruning, Docker starter and graceful shutdown |
@@ -78,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
@@ -117,7 +120,6 @@ export const onboarding =
                 "profile",
                 createProfile
             );
-
             workflow.parallel(
                 "initialize",
                 parallel => {
@@ -131,7 +133,6 @@ export const onboarding =
                     );
                 }
             );
-
             workflow.delay(
                 "cooldown",
                 1_000
@@ -179,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 {
@@ -215,169 +195,31 @@ 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
-
-Create a real signed BCP session token instead of a fake test-only user header:
-
-```ts
-import {
-    createTestAuthSession,
-} from "bcp/testing";
-
-const session =
-    await createTestAuthSession(
-        {
-            id: 42,
-            role: "admin",
-        },
-        {
-            secret:
-                process.env.BCP_SESSION_SECRET,
-            store:
-                authSessionStore,
-        }
-    );
-
-app.setCookie(
-    session.cookieName,
-    session.token
-);
-```
-
-When `store` is provided, the matching server-side auth session record is inserted as well.
-
-### Rollback database tests
-
-```ts
-import {
-    withTestTransaction,
-} from "bcp/testing";
-
-await withTestTransaction(
-    db,
-    async tx => {
-        await tx.execute(
-            "INSERT INTO users ..."
-        );
-
-        // assertions run here
-    }
-);
-```
-
-The callback uses the real BCP transaction and is deliberately rolled back after the test callback succeeds.
-
-### Infrastructure harnesses
-
-```ts
-import {
-    createJobTestHarness,
-    createOutboxTestHarness,
-    createRealtimeTestHarness,
-    createWorkflowTestHarness,
-} from "bcp/testing";
-```
-
-These harnesses use the real platform contracts rather than separate mock implementations.
-
-Background jobs:
-
-```ts
-const jobTest =
-    createJobTestHarness(
-        jobs
-    );
-
-await jobTest.drain();
-
-await jobTest.expectCount(
-    1,
-    {
-        name: "email.welcome",
-        state: "succeeded",
-    }
-);
-```
-
-Realtime:
-
-```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",
-    }
-);
-
-realtimeTest.expectEvent(
-    socket,
-    "order.updated",
-    "orders:42"
-);
-```
-
-Other testing primitives include:
-
-```text
-createFakeClock()
-createSequenceIdFactory()
-runTestMiddleware()
-createRealtimeTestSocket()
-readSseEvents()
-```
-
 Read more: [Testing Platform](docs/testing-platform.md)
 
 ## Plugin & Module Platform — 0.2.15
 
-`0.2.15` adds the server-only `bcp/plugins` entrypoint for reusable application/framework extensions.
-
-Define plugins with explicit dependencies:
-
 ```ts
 import {
     createPluginHost,
@@ -393,12 +235,6 @@ const databasePlugin =
                 db
             );
         },
-        start() {
-            return db.connect();
-        },
-        stop() {
-            return db.disconnect();
-        },
     });
 
 const jobsPlugin =
@@ -409,137 +245,178 @@ const jobsPlugin =
         ],
     });
 
-const host =
+export const plugins =
     createPluginHost({
         plugins: [
             jobsPlugin,
             databasePlugin,
         ],
     });
-
-await host.start();
 ```
 
-Dependency order is resolved automatically. Startup follows dependency order while stop/dispose runs in reverse order.
+Startup follows dependency order; stop/dispose runs in reverse order. Modules, config parsing, shared services and async hook buses are supported.
+
+Read more: [Plugin & Module Platform](docs/plugin-module-platform.md)
+
+## Cache Platform v2 — 0.2.16
 
-Modules group reusable plugin sets:
+`0.2.16` keeps the original `cache()` / `dedupe()` APIs and adds provider-neutral asynchronous cache stores.
 
 ```ts
 import {
-    defineModule,
-} from "bcp/plugins";
+    createCacheStore,
+    createRedisCacheAdapter,
+    createRedisCacheLockAdapter,
+} from "bcp/cache";
 
-const backendModule =
-    defineModule({
-        name: "backend",
-        plugins: [
-            databasePlugin,
-            jobsPlugin,
-        ],
+export const cache =
+    createCacheStore({
+        adapter:
+            createRedisCacheAdapter({
+                client: redisClient,
+            }),
+        lock:
+            createRedisCacheLockAdapter({
+                client: redisClient,
+            }),
     });
 ```
 
-Plugin configuration can be parsed at setup time and overridden through `createPluginHost({ configs })`.
-
-Plugins share a service registry and awaited in-process hook bus through `context.services` and `context.hooks`.
+Distributed `getOrSet()` supports local singleflight, owner-scoped lock leases, heartbeat renewal, double-check-after-lock and contention wait/poll.
 
-If startup fails, already-started plugins are stopped in reverse order before the lifecycle error is propagated.
-
-Read more: [Plugin & Module Platform](docs/plugin-module-platform.md)
+Read more: [Cache Platform v2](docs/cache-platform-v2.md)
 
-## Cache Platform v2 — 0.2.16
+## Observability Platform v3 — 0.2.17
 
-`0.2.16` keeps the original `cache()` and `dedupe()` APIs while adding provider-neutral asynchronous cache stores for production multi-instance applications.
+`0.2.17` keeps the metrics/Prometheus/health APIs from Observability v2 and adds provider-neutral tracing and correlation.
 
-Create a cache store:
+Create a tracer:
 
 ```ts
 import {
-    createCacheStore,
-} from "bcp/cache";
+    createMemoryTraceSpanExporter,
+    createTracer,
+} from "bcp/observability";
+
+const traces =
+    createMemoryTraceSpanExporter();
 
-export const applicationCache =
-    createCacheStore();
+export const tracer =
+    createTracer({
+        exporter: traces,
+        serviceName: "api",
+    });
 ```
 
-Cache-aside loading:
+Create root/child spans:
 
 ```ts
-const user =
-    await applicationCache.getOrSet(
-        "user:42",
-        async () =>
-            loadUser(42),
-        {
-            ttlMs: 60_000,
-            tags: [
-                "users",
-            ],
-            paths: [
-                "/users/42",
-            ],
-        }
-    );
+await tracer.withSpan(
+    "order.checkout",
+    async () => {
+        await tracer.withSpan(
+            "database.order.insert",
+            createOrder,
+            {
+                kind: "client",
+            }
+        );
+    }
+);
 ```
 
-Within one store, concurrent misses share one loader automatically.
+Tracing context flows through normal awaited async work via Node `AsyncLocalStorage`.
 
-For multiple application instances, use shared cache and lock adapters:
+### HTTP tracing
 
 ```ts
 import {
-    createRedisCacheAdapter,
-    createRedisCacheLockAdapter,
-} from "bcp/cache";
+    createRequestTracingMiddleware,
+} from "bcp/observability";
 
-const redisCache =
-    createRedisCacheAdapter({
-        client: redisClient,
-    });
-
-const redisLock =
-    createRedisCacheLockAdapter({
-        client: redisClient,
-    });
-
-export const cache =
-    createCacheStore({
-        adapter: redisCache,
-        lock: redisLock,
-    });
+export const middleware =
+    createRequestTracingMiddleware(
+        tracer
+    );
 ```
 
-The default Redis namespace is `bcp:{cache}`. BCP does not install or own a Redis library/connection.
+The middleware continues valid W3C `traceparent` headers, preserves `x-correlation-id`, creates a server span and returns current trace headers on the response.
 
-Distributed `getOrSet()` uses owner-scoped lock leases, heartbeat renewal when supported, double-check-after-lock, contention wait/poll and configurable lock-timeout behavior.
-
-Tag/path invalidation remains available through the new async store:
+### Jobs / workflow / events / realtime propagation
 
 ```ts
-await cache.revalidateTag(
-    "users"
+import {
+    createTraceCarrier,
+    runWithTraceCarrier,
+} from "bcp/observability";
+
+const trace =
+    createTraceCarrier();
+
+await jobs.enqueue(
+    "order.process",
+    {
+        orderId,
+        trace,
+    }
 );
+```
 
-await cache.revalidatePath(
-    "/dashboard"
+Consumer:
+
+```ts
+await runWithTraceCarrier(
+    payload.trace,
+    () =>
+        tracer.withSpan(
+            "job order.process",
+            handler,
+            {
+                kind: "consumer",
+            }
+        )
 );
 ```
 
-Connect cache events to BCP metrics:
+The same carrier can be placed in workflow input, outbox/event metadata and realtime payloads when trace continuity is needed across those boundaries.
+
+### Trace-to-metrics and logs
 
 ```ts
-const cache =
-    createCacheStore({
-        metrics:
-            createCacheMetrics(
-                metricsRegistry
-            ),
-    });
+import {
+    createCompositeTraceSpanExporter,
+    createMetricsRegistry,
+    createTraceMetricsExporter,
+    getTraceLogFields,
+} from "bcp/observability";
+
+const metrics =
+    createMetricsRegistry();
+
+const exporter =
+    createCompositeTraceSpanExporter([
+        createTraceMetricsExporter(
+            metrics
+        ),
+        productionTraceExporter,
+    ]);
+
+logger.info(
+    "order created",
+    {
+        ...getTraceLogFields(),
+        orderId,
+    }
+);
 ```
 
-Prepared npm packages compile `bcp/cache` to `cache.mjs` for standalone Node runtime use.
+Default trace metrics use low-cardinality `kind` and `status` labels. Span-name labels are opt-in.
 
-Read more: [Cache Platform v2](docs/cache-platform-v2.md)
+BCP does not install an OpenTelemetry SDK or vendor APM package; production exporters remain application-owned through `TraceSpanExporter`.
+
+Prepared npm packages compile `bcp/observability` to `observability.mjs` for standalone Node runtime use.
+
+Read more: [Observability Platform v3](docs/observability-v3.md)
 
 ## Public entrypoints
 
@@ -604,7 +481,7 @@ bcp generate migration create_users
 ```text
 Browser / API / Realtime clients
               |
-      security + auth
+       tracing + security
               |
           Plugin Host
        /      |       \
@@ -615,10 +492,11 @@ Browser / API / Realtime clients
            durable state
               |
        shared cache layer
-          Redis / other
+              |
+      metrics + trace export
 ```
 
-Cache is an optimization layer and must not replace durable application truth or transactional invariants.
+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
 
@@ -645,7 +523,7 @@ docs/api-manifest.json
 
 ## Release validation
 
-Before publishing `0.2.16`:
+Before publishing `0.2.17`:
 
 ```bash
 npm run typecheck
@@ -656,7 +534,7 @@ npm run test:package
 npm run rc:check
 ```
 
-`0.2.16` adds unit and prepared-package smoke coverage for TTL/tag/path invalidation, local singleflight, distributed lock contention, lock timeout behavior, Redis cache/lock command contracts, cache metrics and compiled `cache.mjs` execution.
+`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.
 
@@ -687,12 +565,15 @@ Do not tag or publish until the exact final release commit passes the full RC se
 | `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.16` establishes provider-neutral shared caching and distributed cache-fill coordination while preserving the original process-local cache API.
+`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.17 — Observability Platform v3`**, focused on tracing, correlation across HTTP/jobs/workflows/events/realtime/cache, richer runtime metrics and exporter/provider integration.
+`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.