@chidchanun/bcp 0.2.5 → 0.2.7

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.5",
+  "versionTarget": "0.2.7",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -35,12 +35,13 @@
     },
     {
       "id": "authentication",
-      "title": "Authentication",
-      "description": "Authentication Platform v2, revocable session stores, guest/auth route guards and JWT cookie sessions.",
+      "title": "Authentication & Authorization",
+      "description": "Authentication Platform v2, revocable sessions, permission/policy authorization, route guards and CSRF protection.",
       "pages": [
         { "route": "/docs/authentication", "source": "authentication.md", "title": "Authentication" },
         { "route": "/docs/auth-session-store", "source": "auth-session-store.md", "title": "Auth Session Stores" },
         { "route": "/docs/auth-route-guards", "source": "auth-route-guards.md", "title": "Auth Route Guards" },
+        { "route": "/docs/authorization-security", "source": "authorization-security.md", "title": "Authorization & Security v2" },
         { "route": "/docs/session-auth", "source": "session-auth.md", "title": "JWT Sessions" }
       ]
     },
@@ -56,11 +57,12 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Middleware, hydration, logging, caching, security and production hardening.",
+      "description": "Middleware, observability, logging, caching, security and production hardening.",
       "pages": [
         { "route": "/docs/middleware", "source": "middleware.md", "title": "Middleware" },
         { "route": "/docs/hydration", "source": "hydration.md", "title": "Hydration" },
-        { "route": "/docs/development-logging", "source": "development-logging.md", "title": "Logging & Observability" },
+        { "route": "/docs/development-logging", "source": "development-logging.md", "title": "Logging" },
+        { "route": "/docs/observability", "source": "observability.md", "title": "Observability Platform v2" },
         { "route": "/docs/caching", "source": "caching.md", "title": "Caching" },
         { "route": "/docs/security", "source": "security.md", "title": "Security" },
         { "route": "/docs/production-hardening", "source": "production-hardening.md", "title": "Production Hardening" }
@@ -106,7 +108,9 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.5", "source": "releases/0.2.5.md", "version": "0.2.5", "state": "unreleased" },
+    { "route": "/releases/0.2.7", "source": "releases/0.2.7.md", "version": "0.2.7", "state": "unreleased" },
+    { "route": "/releases/0.2.6", "source": "releases/0.2.6.md", "version": "0.2.6" },
+    { "route": "/releases/0.2.5", "source": "releases/0.2.5.md", "version": "0.2.5" },
     { "route": "/releases/0.2.4", "source": "releases/0.2.4.md", "version": "0.2.4" },
     { "route": "/releases/0.2.3", "source": "releases/0.2.3.md", "version": "0.2.3" },
     { "route": "/releases/0.2.2", "source": "releases/0.2.2.md", "version": "0.2.2" },

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.5",
+  "version": "0.2.7",
   "releaseState": "unreleased",
-  "baseline": "authentication-platform-v2",
+  "baseline": "observability-platform-v2",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -19,6 +19,7 @@
     "bcp/error",
     "bcp/database",
     "bcp/auth",
+    "bcp/observability",
     "bcp/server",
     "bcp/server-only",
     "bcp/middleware"
@@ -53,6 +54,17 @@
     "authLogoutAll": true,
     "authIdleTimeout": true,
     "authGuestGuard": true,
+    "authorizationSecurityV2": true,
+    "permissionAuthorization": true,
+    "authorizationPolicies": true,
+    "permissionRouteGuards": true,
+    "sameOriginProtection": true,
+    "csrfProtection": true,
+    "observabilityPlatformV2": true,
+    "metricsRegistry": true,
+    "prometheusMetrics": true,
+    "requestMetricsMiddleware": true,
+    "healthChecks": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -92,7 +104,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.4",
+    "previousBaseline": "0.2.6",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -107,7 +119,9 @@
     "applicationPackaging": "application-packaging.md",
     "authentication": "authentication.md",
     "authSessionStore": "auth-session-store.md",
+    "authorizationSecurity": "authorization-security.md",
+    "observability": "observability.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.5.md"
+    "releaseNotes": "releases/0.2.7.md"
   }
 }