@chidchanun/bcp 0.2.15 → 0.2.17

package/docs/observability-v3.md

@@ -0,0 +1,402 @@
+# Observability Platform v3
+
+BCP Framework `0.2.17` extends `bcp/observability` from metrics/health into request-to-background distributed tracing and correlation.
+
+The existing Observability Platform v2 APIs remain available. v3 adds tracing without changing the public entrypoint.
+
+## Goals
+
+Observability v3 gives one logical operation a stable trace/correlation identity as it crosses HTTP middleware, background work, workflows, transactional events, realtime delivery and cache operations.
+
+```text
+HTTP request
+   |
+   +-- database
+   |
+   +-- outbox event
+   |      |
+   |      +-- durable job
+   |             |
+   |             +-- workflow
+   |                    |
+   |                    +-- realtime
+   |
+   +-- cache
+
+traceId + correlationId follow the operation.
+```
+
+BCP provides propagation primitives instead of coupling tracing to one vendor or collector.
+
+## Create a tracer
+
+```ts
+import {
+    createMemoryTraceSpanExporter,
+    createTracer,
+} from "bcp/observability";
+
+const exporter =
+    createMemoryTraceSpanExporter();
+
+export const tracer =
+    createTracer({
+        exporter,
+        serviceName: "api",
+        defaultAttributes: {
+            environment: "production",
+        },
+    });
+```
+
+`createMemoryTraceSpanExporter()` is mainly useful for tests and local inspection. Production applications can implement `TraceSpanExporter` and forward completed spans to an OpenTelemetry bridge, APM agent, log pipeline or another collector.
+
+## Root and child spans
+
+```ts
+await tracer.withSpan(
+    "order.checkout",
+    async span => {
+        span.setAttribute(
+            "order.id",
+            order.id
+        );
+
+        await tracer.withSpan(
+            "database.order.insert",
+            async () => {
+                await createOrder();
+            },
+            {
+                kind: "client",
+            }
+        );
+    }
+);
+```
+
+Nested `withSpan()` calls automatically reuse the active `traceId`, create a new `spanId`, and set the active span as `parentSpanId`.
+
+The active trace context uses Node `AsyncLocalStorage`, so it flows through normal awaited asynchronous work.
+
+## Span kinds
+
+Supported kinds are:
+
+```text
+internal
+server
+client
+producer
+consumer
+```
+
+Examples:
+
+- HTTP inbound request: `server`
+- SQL/HTTP/cache call: `client`
+- queue/outbox publish: `producer`
+- queue/event handler: `consumer`
+- framework/application operation: `internal`
+
+## Span attributes and events
+
+```ts
+await tracer.withSpan(
+    "payment.charge",
+    async span => {
+        span.setAttribute(
+            "payment.provider",
+            "example"
+        );
+
+        span.addEvent(
+            "payment.requested",
+            {
+                amount: 1490,
+            }
+        );
+    }
+);
+```
+
+Attribute values are intentionally limited to strings, finite numbers and booleans.
+
+If a `withSpan()` callback throws, BCP marks the span as `error`, records an `exception` event and rethrows the original application error.
+
+## HTTP request tracing
+
+Use the Middleware System v2 integration:
+
+```ts
+import {
+    createRequestTracingMiddleware,
+} from "bcp/observability";
+
+export const middleware =
+    createRequestTracingMiddleware(
+        tracer
+    );
+```
+
+The middleware:
+
+1. Reads an incoming W3C `traceparent` header when valid.
+2. Preserves the incoming `x-correlation-id` when supplied.
+3. Starts a server span.
+4. Makes the span context available through `AsyncLocalStorage`.
+5. Adds the current `traceparent` and `x-correlation-id` to the response.
+
+The default span name is `HTTP <METHOD>`. Applications can provide a lower-cardinality route name:
+
+```ts
+createRequestTracingMiddleware(
+    tracer,
+    {
+        spanName:
+            request =>
+                `route ${request.nextUrl.pathname}`,
+    }
+);
+```
+
+Avoid putting unbounded IDs directly into metric labels. Span names can also become labels when explicitly configured in trace metrics.
+
+## W3C trace context
+
+BCP supports W3C version `00` `traceparent` values:
+
+```text
+00-<32 hex trace id>-<16 hex span id>-<2 hex flags>
+```
+
+Helpers:
+
+```ts
+import {
+    extractTraceHeaders,
+    formatTraceparent,
+    injectTraceHeaders,
+    parseTraceparent,
+} from "bcp/observability";
+```
+
+Example outbound request:
+
+```ts
+const headers =
+    new Headers();
+
+injectTraceHeaders(
+    headers
+);
+
+await fetch(
+    serviceUrl,
+    {
+        headers,
+    }
+);
+```
+
+`injectTraceHeaders()` uses the current context by default.
+
+## Propagate through jobs, workflows and events
+
+For non-HTTP transports use a trace carrier:
+
+```ts
+import {
+    createTraceCarrier,
+} from "bcp/observability";
+
+const trace =
+    createTraceCarrier();
+
+await jobs.enqueue(
+    "order.process",
+    {
+        orderId,
+        trace,
+    }
+);
+```
+
+Consumer:
+
+```ts
+import {
+    runWithTraceCarrier,
+} from "bcp/observability";
+
+jobs.register(
+    "order.process",
+    async ({ payload }) =>
+        runWithTraceCarrier(
+            payload.trace,
+            () =>
+                tracer.withSpan(
+                    "job order.process",
+                    async () => {
+                        await processOrder(
+                            payload.orderId
+                        );
+                    },
+                    {
+                        kind: "consumer",
+                    }
+                )
+        )
+);
+```
+
+The same carrier can be stored in workflow input, outbox/event metadata or realtime payload metadata when the application needs trace continuity across those boundaries.
+
+BCP does not mutate durable job/event schemas automatically in `0.2.17`; propagation remains explicit and provider-neutral.
+
+## Correlation IDs
+
+Every root trace gets a `correlationId`. Incoming HTTP requests may supply one through:
+
+```text
+x-correlation-id
+```
+
+Access trace fields for structured logs:
+
+```ts
+import {
+    getTraceLogFields,
+} from "bcp/observability";
+
+logger.info(
+    "order created",
+    {
+        ...getTraceLogFields(),
+        orderId,
+    }
+);
+```
+
+Output fields are:
+
+```text
+traceId
+spanId
+correlationId
+```
+
+This keeps logs searchable even when the log backend does not understand tracing natively.
+
+## Trace metrics
+
+Bridge completed spans into the existing BCP metrics registry:
+
+```ts
+import {
+    createCompositeTraceSpanExporter,
+    createMetricsRegistry,
+    createTraceMetricsExporter,
+    createTracer,
+} from "bcp/observability";
+
+const metrics =
+    createMetricsRegistry();
+
+const traceMetrics =
+    createTraceMetricsExporter(
+        metrics
+    );
+
+const tracer =
+    createTracer({
+        exporter:
+            createCompositeTraceSpanExporter([
+                traceMetrics,
+                myProductionExporter,
+            ]),
+    });
+```
+
+Default metrics:
+
+```text
+bcp_trace_spans_total
+bcp_trace_span_duration_seconds
+```
+
+Default labels are only:
+
+```text
+kind
+status
+```
+
+`includeSpanName: true` adds a `span` label. Use it only when span names are controlled and low-cardinality.
+
+## Exporter failure behavior
+
+Span-export errors are intentionally isolated from application execution. A failing exporter does not turn a successful business operation into an application failure.
+
+Exporter lifecycle can be closed explicitly:
+
+```ts
+await tracer.shutdown();
+```
+
+Composite exporter shutdown runs in reverse registration order.
+
+## Production topology
+
+```text
+Application
+   |
+   +-- createTracer()
+   |      |
+   |      +-- memory exporter (tests)
+   |      +-- trace metrics exporter
+   |      +-- custom production exporter
+   |
+   +-- createRequestTracingMiddleware()
+   |
+   +-- createTraceCarrier()/runWithTraceCarrier()
+```
+
+BCP does not install an OpenTelemetry SDK or vendor APM client. Applications own collector/provider dependencies, authentication, batching and transport shutdown.
+
+## Compatibility
+
+`0.2.17` is intended to be backward-compatible with `0.2.16`.
+
+Existing APIs remain available:
+
+```text
+createMetricsRegistry()
+createMetricsResponse()
+createRequestMetricsMiddleware()
+createHealthRegistry()
+```
+
+The npm-prepared `bcp/observability` runtime is now compiled to `observability.mjs`, matching the hardened runtime packaging already used by cache/jobs/workflow/events/realtime/testing/plugins.
+
+## Validation
+
+Before releasing `0.2.17` 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
+```
+
+Related guides:
+
+- [Observability Platform v2](observability.md)
+- [Cache Platform v2](cache-platform-v2.md)
+- [Durable Jobs](durable-jobs.md)
+- [Workflow Orchestration](workflow-orchestration.md)
+- [Transactional Outbox & Events](transactional-outbox-events.md)
+- [Realtime Platform](realtime-platform.md)

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "releaseState": "unreleased",
-  "baseline": "plugin-module-platform",
+  "baseline": "observability-platform-v3",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -71,6 +71,17 @@
     "prometheusMetrics": true,
     "requestMetricsMiddleware": true,
     "healthChecks": true,
+    "observabilityPlatformV3": true,
+    "distributedTracing": true,
+    "traceContextPropagation": true,
+    "w3cTraceparent": true,
+    "correlationIds": true,
+    "requestTracingMiddleware": true,
+    "memorySpanExporter": true,
+    "compositeSpanExporter": true,
+    "traceMetricsExporter": true,
+    "traceLogFields": true,
+    "compiledObservabilityRuntime": true,
     "backgroundJobsPlatform": true,
     "jobQueueAdapterContract": true,
     "inMemoryJobQueue": true,
@@ -148,6 +159,19 @@
     "pluginServiceRegistry": true,
     "pluginHookBus": true,
     "pluginLifecycleRollback": true,
+    "cachePlatformV2": true,
+    "cacheAdapterContract": true,
+    "memoryCacheAdapter": true,
+    "redisCacheAdapter": true,
+    "cacheLockAdapter": true,
+    "redisCacheLockAdapter": true,
+    "cacheStampedeProtection": true,
+    "cacheLockHeartbeats": true,
+    "cacheTtl": true,
+    "cacheTagInvalidation": true,
+    "cachePathInvalidation": true,
+    "cacheMetrics": true,
+    "compiledCacheRuntime": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -187,7 +211,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.14",
+    "previousBaseline": "0.2.16",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -204,6 +228,7 @@
     "authSessionStore": "auth-session-store.md",
     "authorizationSecurity": "authorization-security.md",
     "observability": "observability.md",
+    "observabilityV3": "observability-v3.md",
     "backgroundJobs": "background-jobs.md",
     "jobScheduling": "job-scheduling.md",
     "durableJobs": "durable-jobs.md",
@@ -212,7 +237,8 @@
     "realtimePlatform": "realtime-platform.md",
     "testingPlatform": "testing-platform.md",
     "pluginModulePlatform": "plugin-module-platform.md",
+    "cachePlatformV2": "cache-platform-v2.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.15.md"
+    "releaseNotes": "releases/0.2.17.md"
   }
 }

package/docs/releases/0.2.16.md

@@ -0,0 +1,147 @@
+# BCP Framework 0.2.16
+
+**State:** unreleased
+
+## Cache Platform v2
+
+`0.2.16` upgrades the existing `bcp/cache` public entrypoint with provider-neutral asynchronous cache storage, distributed lock contracts, Redis-compatible reference adapters, cache-stampede protection and metrics integration.
+
+The existing `cache()`, `dedupe()`, `revalidateTag()` and `revalidatePath()` APIs remain available with their previous process-local behavior.
+
+## New public APIs
+
+```ts
+createCacheStore()
+createMemoryCacheAdapter()
+createMemoryCacheLockAdapter()
+createRedisCacheAdapter()
+createRedisCacheLockAdapter()
+createCacheMetrics()
+```
+
+New public contracts include:
+
+```text
+CacheAdapter
+CacheAdapterEntry
+CacheAdapterSetOptions
+CacheLockAdapter
+CacheStore
+CacheStoreOptions
+CacheStoreSetOptions
+CacheGetOrSetOptions
+CacheStoreStats
+CacheMetricsSink
+CacheMetricsRegistryLike
+RedisCacheCommandClient
+RedisCacheAdapterOptions
+RedisCacheLockAdapterOptions
+```
+
+## Cache-aside loading
+
+`CacheStore.getOrSet()` provides a framework-native cache-aside primitive.
+
+Within one process it deduplicates concurrent loaders for the same key. With a shared `CacheLockAdapter`, multiple BCP instances coordinate cache fills through distributed leases.
+
+## Distributed lock behavior
+
+The built-in lock implementations support:
+
+- acquire with owner identity and TTL
+- compare-and-release
+- optional compare-and-extend
+- heartbeat renewal while a loader is active
+- contention wait/poll against shared cache state
+- explicit timeout failure with `onLockTimeout: "error"`
+- availability-oriented unlocked fallback by default after timeout
+
+Distributed locks reduce duplicate cache fill work. They are not a substitute for database transactions or uniqueness constraints protecting business invariants.
+
+## Redis-compatible adapters
+
+BCP still does not depend on a Redis package.
+
+Applications provide a minimal command client:
+
+```ts
+interface RedisCacheCommandClient {
+    sendCommand(
+        command: string[]
+    ): Promise<unknown>;
+}
+```
+
+The default namespace is `bcp:{cache}` so related keys share a Redis Cluster hash slot.
+
+The reference adapter uses Lua for record/index changes, tag invalidation, lock release and lock renewal.
+
+Applications remain responsible for Redis authentication, TLS, Cluster/Sentinel configuration, reconnect behavior and connection shutdown.
+
+## TTL and invalidation
+
+Cache Store v2 supports:
+
+- millisecond TTL via `ttlMs`
+- tag invalidation
+- hierarchical path invalidation
+- adapter-wide clear
+- optional provider entry counts
+
+The older `cache()` API continues to accept `revalidate` in seconds for compatibility.
+
+## Observability
+
+`createCacheMetrics()` adapts Cache Store events to `bcp/observability`'s existing `MetricsRegistry` contract.
+
+Default metric families:
+
+```text
+bcp_cache_operations_total{event="..."}
+bcp_cache_in_flight
+```
+
+## Published runtime
+
+The prepared npm package now compiles `bcp/cache` to:
+
+```text
+packages/client/src/cache.mjs
+```
+
+The prepared package export points runtime imports at this compiled file while preserving `cache.ts` as the public type source.
+
+## Testing
+
+The `0.2.16` suite adds coverage for:
+
+- TTL expiration
+- tag/path invalidation
+- store statistics
+- local in-flight deduplication
+- cross-store distributed stampede protection
+- lock timeout errors
+- BCP metrics registry integration
+- Redis command/namespace contract
+- compiled prepared-package runtime smoke
+
+## Compatibility
+
+`0.2.16` has no intentional breaking changes from `0.2.15`.
+
+Existing application calls using the original cache APIs do not need to migrate.
+
+## Release validation
+
+Before publishing:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+Tag and publish only the exact commit that passes the complete RC sequence.