@chidchanun/bcp 0.2.6 → 0.2.7

package/README.md

@@ -1,14 +1,14 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, authorization, database access, validation, uploads, storage and standalone Node.js production deployment.
+BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, authorization, database access, observability, validation, uploads, storage and standalone Node.js production deployment.
 
-> **Development target:** `0.2.6 — Authorization & Security v2`
+> **Development target:** `0.2.7 — Observability Platform v2`
 >
-> `0.2.6` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.7` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
 
 ## 0.2 platform
 
-`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, `0.2.2` added Configuration & Environment v2, `0.2.3` added Database Platform v2, `0.2.4` added Application Packaging, `0.2.5` added Authentication Platform v2, and `0.2.6` adds permission/policy authorization plus CSRF and same-origin request protection without intentionally removing the existing public application model.
+`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, `0.2.2` added Configuration & Environment v2, `0.2.3` added Database Platform v2, `0.2.4` added Application Packaging, `0.2.5` added Authentication Platform v2, `0.2.6` added Authorization & Security v2, and `0.2.7` adds dependency-free metrics, Prometheus exposition, request metrics and health/readiness checks without intentionally changing the existing application model.
 
 Machine-readable platform contracts:
 
@@ -35,10 +35,10 @@ docs/api-manifest.json
 | Authorization | Auth/guest/role/permission route guards, flat permissions and resource-aware policies |
 | Request security | Same-origin validation and signed CSRF tokens for unsafe mutations |
 | Middleware | Middleware System v2 with onion execution |
+| Observability | Structured logs, counters/gauges/histograms, Prometheus output, request metrics and health/readiness checks |
 | Validation | Typed validators and structured validation errors |
 | Error handling | HTTP error helpers and consistent error responses |
 | Database | Provider-neutral MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle and migrations |
-| Logging | Structured logger, request logger and request IDs |
 | Uploads | Buffered multipart helpers and production multipart streaming |
 | Storage | Local + S3-compatible storage, streaming, list/copy/move, metadata, bulk delete and signed URLs |
 | Caching | Response cache and revalidation primitives |
@@ -242,8 +242,6 @@ Read more:
 
 ## Authorization & Security v2 — 0.2.6
 
-### Permissions
-
 Use flat permissions directly from `bcp/auth`:
 
 ```ts
@@ -268,24 +266,7 @@ await requirePermission(
 );
 ```
 
-Route trees can use a permission guard:
-
-```ts
-import {
-    createPermissionGuard,
-} from "bcp/auth";
-
-export const guard =
-    createPermissionGuard(
-        "admin.access"
-    );
-```
-
-The default permission field is `permissions`. Applications can select another field such as `scopes`.
-
-### Resource policies
-
-For ownership, tenant or resource-state rules:
+Resource-aware policies:
 
 ```ts
 import {
@@ -312,17 +293,6 @@ await authorize(
 );
 ```
 
-Available policy helpers:
-
-```text
-can()
-cannot()
-authorize()
-AuthorizationError
-```
-
-### Same-origin and CSRF protection
-
 Request-security helpers are exposed from `bcp/server`:
 
 ```ts
@@ -333,43 +303,93 @@ import {
 } from "bcp/server";
 ```
 
-Protect an unsafe API/action mutation with origin validation:
+Read more: [Authorization & Security v2](docs/authorization-security.md)
+
+## Observability Platform v2 — 0.2.7
+
+Create one application metrics registry:
 
 ```ts
-await requireSameOriginRequest();
+import {
+    createMetricsRegistry,
+} from "bcp/observability";
+
+export const metrics =
+    createMetricsRegistry();
+```
+
+Supported metric types:
+
+```text
+counter
+gauge
+histogram
 ```
 
-For signed CSRF protection:
+Expose Prometheus-compatible text:
 
 ```ts
-const csrfToken =
-    await createCsrfToken();
+import {
+    createMetricsResponse,
+} from "bcp/observability";
 
-// Render/send csrfToken through the trusted application UI.
+export function GET() {
+    return createMetricsResponse(
+        metrics
+    );
+}
+```
+
+Instrument HTTP requests through Middleware System v2:
+
+```ts
+import {
+    createRequestMetricsMiddleware,
+} from "bcp/observability";
 
-await requireCsrfRequest({
-    token: submittedToken,
-});
+export const requestMetrics =
+    createRequestMetricsMiddleware(
+        metrics
+    );
 ```
 
-Default CSRF header/cookie:
+Default request metrics use only bounded labels:
 
 ```text
-X-BCP-CSRF
-bcp_csrf
+bcp_http_requests_total{method,status}
+bcp_http_request_duration_seconds{method,status}
 ```
 
-Secret resolution:
+Raw paths are not attached by default.
 
-```text
-explicit options.secret
-    ↓
-BCP_CSRF_SECRET
-    ↓
-BCP_SESSION_SECRET
+Health/readiness registry:
+
+```ts
+import {
+    createHealthRegistry,
+} from "bcp/observability";
+
+export const health =
+    createHealthRegistry();
+
+health.register(
+    "database",
+    async () => {
+        await db.query("SELECT 1");
+        return true;
+    }
+);
 ```
 
-Read more: [Authorization & Security v2](docs/authorization-security.md)
+Use:
+
+```ts
+return health.response();
+```
+
+Health responses return `200` when every check passes and `503` when any registered dependency is unhealthy or times out.
+
+Read more: [Observability Platform v2](docs/observability.md)
 
 ## Public entrypoints
 
@@ -384,6 +404,7 @@ bcp/validation
 bcp/error
 bcp/database
 bcp/auth
+bcp/observability
 bcp/server
 bcp/server-only
 bcp/middleware
@@ -446,6 +467,9 @@ Loader / action / API route
 React SSR
   ↓
 Hydration / SPA navigation
+
+Operational side channels:
+structured logs + metrics + health/readiness
 ```
 
 ## Production build
@@ -491,7 +515,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.6` adds Authorization & Security v2 unit and prepared-package smoke checks covering permission matching, policy authorization, permission route guards, same-origin mutation validation and signed CSRF tokens.
+`0.2.7` adds Observability Platform v2 unit and prepared-package smoke checks covering metrics, Prometheus exposition, request timing, cardinality-safe default labels, health/readiness responses and timeout handling.
 
 Do not tag or publish until the final release commit passes the complete RC sequence.
 
@@ -512,12 +536,13 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.4` | Application Packaging |
 | `0.2.5` | Authentication Platform v2 |
 | `0.2.6` | Authorization & Security v2 |
+| `0.2.7` | Observability Platform v2 |
 
 ## Roadmap
 
-`0.2.6 — Authorization & Security v2` establishes the permission/policy and browser-mutation security layer on top of Authentication Platform v2.
+`0.2.7 — Observability Platform v2` establishes process-level metrics and health/readiness contracts on top of the existing structured logging and Middleware System v2 runtime.
 
-The next `0.2.x` milestone can build on the existing runtime, database, auth, security and packaging contracts. Native `.exe`, desktop and mobile compilation remain later roadmap work.
+Future `0.2.x` work can add distributed tracing or exporter integrations without changing the application metrics/health contract introduced here. Native `.exe`, desktop and mobile compilation remain later roadmap work.
 
 ## License
 

package/docs/README.md

@@ -2,7 +2,7 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.2.6 — Authorization & Security v2`
+> **Documentation target:** BCP Framework `0.2.7 — Observability Platform v2`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -52,66 +52,49 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.4` | Application Packaging |
 | `0.2.5` | Authentication Platform v2 |
 | `0.2.6` | Authorization & Security v2 |
+| `0.2.7` | Observability Platform v2 |
 
-## 0.2.6 — Authorization & Security v2
+## 0.2.7 — Observability Platform v2
 
-`0.2.6` adds server-side permission checks, resource-aware authorization policies, permission route guards, same-origin mutation validation and signed CSRF protection.
+`0.2.7` adds a server-only observability layer without adding third-party runtime dependencies.
 
 New/updated documentation sources:
 
 | Source | Purpose |
 | --- | --- |
-| `authorization-security.md` | Permissions, policies, permission guards, same-origin validation and CSRF APIs |
-| `auth-route-guards.md` | Auth/guest/role/permission route guard guidance |
-| `api-reference.md` | Public authorization and request-security exports |
-| `platform-manifest.json` | Authorization/security capability flags |
-| `api-manifest.json` | `bcp/auth` and `bcp/server` guide ownership |
-| `releases/0.2.6.md` | Authorization & Security v2 release notes |
+| `observability.md` | Metrics registry, Prometheus output, request metrics and health/readiness checks |
+| `api-reference.md` | Public `bcp/observability` exports |
+| `platform-manifest.json` | Observability capability flags and new public entrypoint |
+| `api-manifest.json` | `bcp/observability` guide ownership |
+| `docs-web-manifest.json` | Observability navigation and `0.2.7` release route |
+| `releases/0.2.7.md` | Observability Platform v2 release notes |
 
-Primary authorization APIs:
+Primary APIs:
 
 ```ts
 import {
-    authorize,
-    can,
-    createPermissionGuard,
-    defineAuthorizationPolicy,
-    hasPermission,
-    requirePermission,
-} from "bcp/auth";
+    createHealthRegistry,
+    createMetricsRegistry,
+    createMetricsResponse,
+    createRequestMetricsMiddleware,
+} from "bcp/observability";
 ```
 
-Primary browser-mutation security APIs:
-
-```ts
-import {
-    createCsrfToken,
-    requireCsrfRequest,
-    requireSameOriginRequest,
-} from "bcp/server";
-```
-
-## Security model
-
-The `0.2.6` server model separates concerns:
+Runtime model:
 
 ```text
-authentication
-    -> identify a signed/revocable session
-
-authorization
-    -> permissions + policies + route guards
-
-request security
-    -> Origin/Referer validation + signed CSRF token
-
-input validation
-    -> application schema/domain checks
+structured logs
+    +
+process-local metrics
+    +
+Prometheus exposition
+    +
+health/readiness checks
 ```
 
-All authorization decisions must remain server-side. Client UI permission checks may improve presentation but do not replace route/action/API enforcement.
+The request metrics middleware intentionally uses bounded `method` and `status` labels by default rather than raw paths.
 
-CSRF tokens use `BCP_CSRF_SECRET` when configured and otherwise fall back to `BCP_SESSION_SECRET`. Security secrets must contain at least 32 UTF-8 bytes.
+The built-in metrics registry is process-local; distributed aggregation remains deployment infrastructure or future exporter work.
 
 ## Update rule
 
@@ -150,13 +133,13 @@ Important current routes:
 | Website route | Markdown source |
 | --- | --- |
 | `/docs/authentication` | `authentication.md` |
-| `/docs/auth-session-store` | `auth-session-store.md` |
-| `/docs/auth-route-guards` | `auth-route-guards.md` |
 | `/docs/authorization-security` | `authorization-security.md` |
+| `/docs/observability` | `observability.md` |
+| `/docs/development-logging` | `development-logging.md` |
 | `/docs/application-packaging` | `application-packaging.md` |
 | `/docs/database` | `database.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.6` | `releases/0.2.6.md` |
+| `/releases/0.2.7` | `releases/0.2.7.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -196,6 +179,7 @@ bcp/validation
 bcp/error
 bcp/database
 bcp/auth
+bcp/observability
 bcp/server
 bcp/server-only
 bcp/middleware
@@ -235,7 +219,7 @@ synchronize CMS/search/navigation
 
 ## Release validation
 
-Before publishing `0.2.6`:
+Before publishing `0.2.7`:
 
 ```bash
 npm run typecheck
@@ -246,16 +230,16 @@ npm run test:e2e
 npm run rc:check
 ```
 
-Authorization & Security v2 validation covers:
+Observability Platform v2 validation covers:
 
-- permission normalization and any/all matching,
-- permission route guards,
-- sync/async authorization policies,
-- `AuthorizationError` denial behavior,
-- same-origin mutation checks,
-- signed CSRF tokens,
-- malformed/cross-origin rejection,
-- public `bcp/auth` and `bcp/server` exports,
+- counter/gauge/histogram behavior,
+- Prometheus exposition,
+- metric definition validation,
+- request count and duration middleware,
+- cardinality-safe default request labels,
+- health/readiness response semantics,
+- health check timeout handling,
+- public `bcp/observability` exports,
 - prepared npm package contents,
 - docs/platform/API version parity.
 

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -94,6 +94,17 @@
         "/docs/session-auth"
       ]
     },
+    {
+      "package": "bcp/observability",
+      "source": "packages/client/src/observability.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-observability",
+      "summary": "In-process metrics, Prometheus exposition, request metrics middleware and health/readiness checks.",
+      "guides": [
+        "/docs/observability",
+        "/docs/development-logging"
+      ]
+    },
     {
       "package": "bcp/server",
       "source": "packages/client/src/server.ts",

package/docs/api-reference.md

@@ -226,6 +226,42 @@ Authorization & Security v2 adds permission checks, permission route guards and
 
 Related guides: [Authentication](authentication.md), [Auth Session Stores](auth-session-store.md), [Auth Route Guards](auth-route-guards.md), [Authorization & Security v2](authorization-security.md), [JWT Sessions](session-auth.md).
 
+## `bcp/observability`
+
+Server-only Observability Platform v2 APIs.
+
+```ts
+import {
+    createHealthRegistry,
+    createMetricsRegistry,
+    createMetricsResponse,
+    createRequestMetricsMiddleware,
+    type CounterMetric,
+    type GaugeMetric,
+    type HealthCheck,
+    type HealthCheckOptions,
+    type HealthCheckReportItem,
+    type HealthCheckResult,
+    type HealthRegistry,
+    type HealthReport,
+    type HistogramMetric,
+    type HistogramOptions,
+    type MetricDefinitionOptions,
+    type MetricLabels,
+    type MetricLabelValue,
+    type MetricsRegistry,
+    type RequestMetricsOptions,
+} from "bcp/observability";
+```
+
+`createMetricsRegistry()` provides process-local counters, gauges and histograms. `createMetricsResponse()` renders Prometheus-compatible text exposition. `createRequestMetricsMiddleware()` measures HTTP request counts and duration using bounded `method` / `status` labels by default and intentionally does not label by raw path.
+
+`createHealthRegistry()` registers synchronous or asynchronous liveness/readiness checks, applies per-check timeouts and produces JSON health responses with HTTP `200` when all checks pass or `503` when any check fails.
+
+The built-in registry is process-local. Multi-instance deployments should scrape each process/container or aggregate through external monitoring infrastructure.
+
+Related guides: [Observability Platform v2](observability.md), [Logging](development-logging.md).
+
 ## `bcp/server`
 
 Server request/runtime APIs.

package/docs/development-logging.md

@@ -1,6 +1,21 @@
 # Logging and observability
 
-BCP Framework 0.1.23 adds a structured server logger and upgrades development request timing output while keeping framework-internal browser/bootstrap traffic quiet by default.
+BCP Framework 0.1.23 added the structured server logger and development request timing output. BCP Framework `0.2.7` complements that logging layer with process-local metrics and health/readiness primitives through `bcp/observability`.
+
+Use these layers together:
+
+```text
+bcp/server
+  -> structured event/request logs
+
+bcp/observability
+  -> counters, gauges, histograms
+  -> Prometheus exposition
+  -> request metrics middleware
+  -> health/readiness checks
+```
+
+See [Observability Platform v2](observability.md) for the `0.2.7` metrics and health APIs.
 
 ## Server logger
 
@@ -205,6 +220,34 @@ ssr.render
 
 They are therefore visible when `BCP_LOG_LEVEL=debug` and stay out of normal `info` output.
 
+## Metrics vs logs
+
+Logs and metrics serve different purposes.
+
+Use structured logs when you need per-event context:
+
+```text
+request ID
+operation
+error stack
+resource identity
+diagnostic fields
+```
+
+Use metrics when you need aggregate trends:
+
+```text
+request count
+status distribution
+latency buckets
+queue depth
+worker count
+```
+
+Avoid copying high-cardinality log fields such as request IDs, user IDs or raw paths into metric labels.
+
+The `0.2.7` request metrics middleware follows this rule by using `method` and `status` labels by default.
+
 ## Errors
 
 Pass an `Error` as a structured field:

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.6",
+  "versionTarget": "0.2.7",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -57,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" }
@@ -107,7 +108,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.6", "source": "releases/0.2.6.md", "version": "0.2.6", "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" },