@chidchanun/bcp 0.2.6 → 0.2.8

package/docs/observability.md

@@ -0,0 +1,445 @@
+# Observability Platform v2
+
+BCP Framework `0.2.7` adds a server-only observability layer through `bcp/observability`.
+
+The platform is dependency-free and provides:
+
+- in-process counters, gauges and histograms,
+- Prometheus text exposition,
+- HTTP request count and duration middleware,
+- health/readiness check registration,
+- health responses with HTTP `200` / `503` semantics.
+
+It complements the existing structured logger rather than replacing it.
+
+## Metrics registry
+
+Create one application-level registry:
+
+```ts
+import {
+    createMetricsRegistry,
+} from "bcp/observability";
+
+export const metrics =
+    createMetricsRegistry();
+```
+
+### Counter
+
+```ts
+const jobs =
+    metrics.counter(
+        "app_jobs_total",
+        {
+            help:
+                "Jobs processed by the application.",
+            labelNames: [
+                "queue",
+            ],
+        }
+    );
+
+jobs.inc(
+    1,
+    {
+        queue: "email",
+    }
+);
+```
+
+Counters cannot be decreased.
+
+### Gauge
+
+```ts
+const workers =
+    metrics.gauge(
+        "app_active_workers",
+        {
+            labelNames: [
+                "pool",
+            ],
+        }
+    );
+
+workers.set(
+    4,
+    {
+        pool: "default",
+    }
+);
+workers.inc(
+    1,
+    {
+        pool: "default",
+    }
+);
+workers.dec(
+    1,
+    {
+        pool: "default",
+    }
+);
+```
+
+### Histogram
+
+```ts
+const queryDuration =
+    metrics.histogram(
+        "app_query_duration_seconds",
+        {
+            labelNames: [
+                "operation",
+            ],
+            buckets: [
+                0.01,
+                0.05,
+                0.1,
+                0.5,
+                1,
+            ],
+        }
+    );
+
+queryDuration.observe(
+    0.032,
+    {
+        operation: "users.list",
+    }
+);
+```
+
+If no buckets are supplied, BCP uses a general-purpose HTTP/runtime latency bucket set.
+
+## Label contract
+
+Metric label names are declared when the metric is registered. Every update must provide exactly that set of labels.
+
+This fails intentionally:
+
+```ts
+const requests =
+    metrics.counter(
+        "app_requests_total",
+        {
+            labelNames: [
+                "method",
+            ],
+        }
+    );
+
+// Missing the declared method label.
+requests.inc();
+```
+
+BCP does not automatically attach request paths, user IDs, session IDs, emails or other high-cardinality identifiers to metrics.
+
+Avoid labels whose value set grows without a small bound.
+
+Good examples:
+
+```text
+method
+status
+queue
+provider
+operation
+```
+
+Risky examples:
+
+```text
+user_id
+session_id
+raw_url
+email
+request_id
+```
+
+## Prometheus exposition
+
+Use `createMetricsResponse()` from an API route:
+
+```ts
+import {
+    createMetricsResponse,
+} from "bcp/observability";
+import {
+    metrics,
+} from "@/lib/observability";
+
+export function GET() {
+    return createMetricsResponse(
+        metrics
+    );
+}
+```
+
+Typical output:
+
+```text
+# HELP app_requests_total Application requests.
+# TYPE app_requests_total counter
+app_requests_total{method="GET"} 42
+```
+
+The response content type is compatible with Prometheus text exposition and uses `Cache-Control: no-store`.
+
+### Protect the metrics endpoint
+
+Metrics frequently expose operational information. Do not assume `/metrics` should be public.
+
+Protect it using your deployment network, reverse proxy, authorization policy, internal service routing or another appropriate boundary.
+
+## HTTP request metrics middleware
+
+Create middleware from the same application registry:
+
+```ts
+import {
+    createMetricsRegistry,
+    createRequestMetricsMiddleware,
+} from "bcp/observability";
+
+export const metrics =
+    createMetricsRegistry();
+
+export const requestMetrics =
+    createRequestMetricsMiddleware(
+        metrics
+    );
+```
+
+Then include it in the application middleware pipeline:
+
+```ts
+import {
+    requestMetrics,
+} from "@/lib/observability";
+
+export const middleware = [
+    requestMetrics,
+];
+```
+
+Default series:
+
+```text
+bcp_http_requests_total{method,status}
+bcp_http_request_duration_seconds{method,status}
+```
+
+The default middleware intentionally does not label requests by raw path. This avoids generating one metric series per dynamic URL or identifier.
+
+Customize the prefix:
+
+```ts
+createRequestMetricsMiddleware(
+    metrics,
+    {
+        prefix: "shop",
+    }
+);
+```
+
+This produces metrics beginning with `shop_`.
+
+You can disable the method or status labels:
+
+```ts
+createRequestMetricsMiddleware(
+    metrics,
+    {
+        includeMethod: false,
+        includeStatus: false,
+    }
+);
+```
+
+## Health and readiness checks
+
+Create an application-level health registry:
+
+```ts
+import {
+    createHealthRegistry,
+} from "bcp/observability";
+
+export const health =
+    createHealthRegistry();
+```
+
+Register dependencies:
+
+```ts
+health.register(
+    "database",
+    async () => {
+        await db.query(
+            "SELECT 1"
+        );
+
+        return {
+            ok: true,
+            detail: "connected",
+        };
+    }
+);
+```
+
+A check may return:
+
+```ts
+true
+false
+```
+
+or:
+
+```ts
+{
+    ok: true,
+    detail: "connected",
+}
+```
+
+### Health endpoint
+
+```ts
+import {
+    health,
+} from "@/lib/observability";
+
+export function GET() {
+    return health.response();
+}
+```
+
+Healthy response:
+
+```text
+HTTP 200
+```
+
+If any registered check fails:
+
+```text
+HTTP 503
+```
+
+The JSON report contains:
+
+```ts
+{
+    ok: boolean;
+    status: "healthy" | "unhealthy";
+    checkedAt: string;
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        durationMs: number;
+        detail?: string;
+    }>;
+}
+```
+
+## Health check timeout
+
+The default timeout is 5 seconds per check.
+
+Override it when registering a check:
+
+```ts
+health.register(
+    "database",
+    checkDatabase,
+    {
+        timeoutMs: 1500,
+    }
+);
+```
+
+A timed-out or thrown check is reported as unhealthy instead of rejecting the complete health report.
+
+Timeout does not cancel the underlying application operation. Provider-specific cancellation remains the responsibility of the check implementation.
+
+## Liveness vs readiness
+
+Use lightweight liveness checks for whether the process/runtime is functioning.
+
+Use readiness checks for dependencies required before receiving traffic, for example:
+
+```text
+database
+cache
+message queue
+critical upstream API
+```
+
+A common deployment structure is:
+
+```text
+/api/health/live
+/api/health/ready
+/metrics
+```
+
+BCP provides the primitives but does not force endpoint names.
+
+## Process-local scope
+
+The built-in metrics registry is process-local.
+
+With multiple Node processes or containers:
+
+```text
+instance A -> its own registry
+instance B -> its own registry
+instance C -> its own registry
+```
+
+Prometheus-style monitoring should scrape each instance, or deployment infrastructure should aggregate metrics externally.
+
+BCP `0.2.7` does not provide distributed metric aggregation or an OpenTelemetry exporter.
+
+## Relationship to logging
+
+Structured logs remain available through `bcp/server`:
+
+```ts
+import {
+    logger,
+} from "bcp/server";
+```
+
+Use logs for event detail and debugging, and metrics for aggregate system behavior.
+
+A typical production model is:
+
+```text
+structured logs
+    +
+metrics
+    +
+health/readiness
+```
+
+## Server-only boundary
+
+`bcp/observability` is server-only.
+
+Do not import it into client components or browser islands. The package browser export maps to BCP's server-only guard.
+
+## Release scope
+
+`0.2.7` intentionally does not add:
+
+- distributed tracing,
+- OpenTelemetry exporters,
+- hosted monitoring integrations,
+- automatic raw-route labels,
+- cross-process metric aggregation.
+
+Those can be layered on later without changing the metric/health application contract introduced here.

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "releaseState": "unreleased",
-  "baseline": "authorization-security-v2",
+  "baseline": "background-jobs-platform",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -19,6 +19,8 @@
     "bcp/error",
     "bcp/database",
     "bcp/auth",
+    "bcp/jobs",
+    "bcp/observability",
     "bcp/server",
     "bcp/server-only",
     "bcp/middleware"
@@ -59,6 +61,18 @@
     "permissionRouteGuards": true,
     "sameOriginProtection": true,
     "csrfProtection": true,
+    "observabilityPlatformV2": true,
+    "metricsRegistry": true,
+    "prometheusMetrics": true,
+    "requestMetricsMiddleware": true,
+    "healthChecks": true,
+    "backgroundJobsPlatform": true,
+    "jobQueueAdapterContract": true,
+    "inMemoryJobQueue": true,
+    "delayedJobs": true,
+    "jobRetries": true,
+    "jobWorkerConcurrency": true,
+    "jobCancellation": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -98,7 +112,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.5",
+    "previousBaseline": "0.2.7",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -114,7 +128,9 @@
     "authentication": "authentication.md",
     "authSessionStore": "auth-session-store.md",
     "authorizationSecurity": "authorization-security.md",
+    "observability": "observability.md",
+    "backgroundJobs": "background-jobs.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.6.md"
+    "releaseNotes": "releases/0.2.8.md"
   }
 }

package/docs/releases/0.2.7.md

@@ -0,0 +1,205 @@
+# BCP Framework 0.2.7 — Observability Platform v2
+
+> Release state: unreleased until RC validation, tagging and npm publication complete.
+
+BCP Framework `0.2.7` adds a dependency-free server observability platform while preserving the existing logging/runtime model.
+
+## Highlights
+
+### New `bcp/observability` entrypoint
+
+```ts
+import {
+    createHealthRegistry,
+    createMetricsRegistry,
+    createMetricsResponse,
+    createRequestMetricsMiddleware,
+} from "bcp/observability";
+```
+
+The entrypoint is server-only and uses the same browser boundary as other server runtime APIs.
+
+### Metrics registry
+
+Applications can create process-local:
+
+- counters,
+- gauges,
+- histograms.
+
+Example:
+
+```ts
+const metrics =
+    createMetricsRegistry();
+
+const requests =
+    metrics.counter(
+        "app_requests_total",
+        {
+            labelNames: [
+                "method",
+            ],
+        }
+    );
+
+requests.inc(
+    1,
+    {
+        method: "GET",
+    }
+);
+```
+
+Metric definitions validate names, labels and number values. Re-registering the same metric with an incompatible type, label set or histogram buckets fails explicitly.
+
+### Prometheus text output
+
+```ts
+return createMetricsResponse(
+    metrics
+);
+```
+
+The generated response uses Prometheus-compatible text exposition metadata and `Cache-Control: no-store`.
+
+### HTTP request metrics middleware
+
+```ts
+const requestMetrics =
+    createRequestMetricsMiddleware(
+        metrics
+    );
+```
+
+Default metrics:
+
+```text
+bcp_http_requests_total
+bcp_http_request_duration_seconds
+```
+
+Default labels:
+
+```text
+method
+status
+```
+
+Raw URL paths are intentionally not included by default to avoid unbounded metric cardinality.
+
+### Health and readiness checks
+
+```ts
+const health =
+    createHealthRegistry();
+
+health.register(
+    "database",
+    async () => {
+        await db.query(
+            "SELECT 1"
+        );
+
+        return true;
+    }
+);
+```
+
+Health responses use:
+
+```text
+200 healthy
+503 unhealthy
+```
+
+Checks run independently and include duration metadata.
+
+### Health timeouts
+
+Each health check has a default timeout of 5 seconds and may configure its own timeout.
+
+Thrown or timed-out checks become unhealthy report items rather than rejecting the whole health operation.
+
+## Public APIs
+
+### Metrics
+
+```text
+createMetricsRegistry()
+createMetricsResponse()
+createRequestMetricsMiddleware()
+```
+
+Metric interfaces:
+
+```text
+CounterMetric
+GaugeMetric
+HistogramMetric
+MetricsRegistry
+MetricLabels
+MetricDefinitionOptions
+HistogramOptions
+RequestMetricsOptions
+```
+
+### Health
+
+```text
+createHealthRegistry()
+```
+
+Health interfaces:
+
+```text
+HealthRegistry
+HealthCheck
+HealthCheckResult
+HealthCheckOptions
+HealthReport
+HealthCheckReportItem
+```
+
+## Compatibility
+
+`0.2.7` has no intentional breaking changes from `0.2.6`.
+
+Existing applications do not need to create a metrics or health registry. The new platform is opt-in.
+
+Existing structured logging through `bcp/server` remains unchanged.
+
+## Operational notes
+
+Metrics are process-local. Multi-process and multi-container deployments should expose/scrape metrics for each instance or aggregate through deployment infrastructure.
+
+The built-in platform does not provide distributed aggregation or an OpenTelemetry exporter in this release.
+
+Health check error details may contain operational information. Applications should decide whether health endpoints are publicly accessible and avoid returning secrets from custom check details.
+
+Metrics endpoints should normally be protected by an internal network, reverse proxy or application authorization boundary when operational data is sensitive.
+
+## Validation coverage
+
+`0.2.7` adds unit and prepared-package checks for:
+
+- counter accumulation,
+- gauge set/increment/decrement,
+- histogram bucket/count output,
+- Prometheus response metadata,
+- incompatible metric registration,
+- request status/method timing metrics,
+- no raw path labels in default request metrics,
+- healthy/unhealthy reports,
+- HTTP 503 readiness behavior,
+- health check timeout handling,
+- `bcp/observability` npm export availability,
+- documentation/platform/API manifest parity.
+
+## Documentation
+
+See:
+
+- [Observability Platform v2](../observability.md)
+- [Logging](../development-logging.md)
+- [API Reference](../api-reference.md)