@chidchanun/bcp 0.2.16 → 0.2.18

package/docs/deployment-platform-v2.md

@@ -0,0 +1,449 @@
+# Deployment Platform v2
+
+BCP Framework `0.2.18` adds a server-only deployment lifecycle layer through `bcp/deployment` and hardens published production entrypoints so application runtime code does not need to execute framework TypeScript directly.
+
+## Goals
+
+Deployment Platform v2 provides:
+
+- application resource startup ordering;
+- reverse-order graceful shutdown;
+- startup rollback when a later resource fails;
+- readiness checks for orchestrators/load balancers;
+- runtime diagnostics and deployment identity;
+- `SIGTERM` / `SIGINT` integration;
+- integration with the existing BCP shutdown-hook registry;
+- compiled production runtimes for key server entrypoints.
+
+It does not replace Kubernetes, Docker, systemd, PM2 or another process orchestrator. BCP provides lifecycle primitives that those systems can drive.
+
+## Create a deployment runtime
+
+```ts
+import {
+    createDeploymentRuntime,
+} from "bcp/deployment";
+
+export const deployment =
+    createDeploymentRuntime({
+        serviceName: "orders-api",
+        version: "1.4.0",
+    });
+```
+
+Runtime states are:
+
+```text
+idle
+starting
+ready
+draining
+stopped
+failed
+```
+
+## Register resources
+
+Resources are started in registration order and stopped in reverse order.
+
+```ts
+deployment.addResource({
+    name: "database",
+
+    async start() {
+        await db.connect();
+    },
+
+    async ready() {
+        return {
+            ok:
+                db.status ===
+                "ready",
+            detail:
+                db.status,
+        };
+    },
+
+    async stop() {
+        await db.close();
+    },
+
+    diagnostics() {
+        return {
+            provider:
+                "postgresql",
+        };
+    },
+});
+```
+
+Then register dependent services later:
+
+```ts
+deployment.addResource({
+    name: "jobs",
+
+    async start() {
+        workers.start();
+    },
+
+    async stop() {
+        await workers.stop();
+    },
+});
+```
+
+Starting:
+
+```ts
+await deployment.start();
+```
+
+produces:
+
+```text
+database.start()
+    ↓
+jobs.start()
+    ↓
+state = ready
+```
+
+Shutdown reverses the order:
+
+```text
+jobs.stop()
+    ↓
+database.stop()
+    ↓
+state = stopped
+```
+
+## Startup rollback
+
+If a resource fails during startup, already-started resources are stopped in reverse order.
+
+```text
+database.start() ✅
+jobs.start()     ✅
+realtime.start() ❌
+
+rollback:
+
+jobs.stop()
+database.stop()
+```
+
+The runtime moves to `failed` and `start()` rejects.
+
+## Resource context
+
+Lifecycle callbacks receive:
+
+```ts
+{
+    metadata,
+    signal,
+}
+```
+
+`signal` is aborted when shutdown begins. Long-running BCP/application components can use it to stop accepting new work or cancel background loops.
+
+## Readiness
+
+```ts
+const report =
+    await deployment.readiness();
+```
+
+A runtime is ready only when:
+
+1. runtime state is `ready`;
+2. all registered resources are in the started state;
+3. every resource readiness function reports success.
+
+Create an HTTP response directly:
+
+```ts
+import {
+    createDeploymentReadinessResponse,
+} from "bcp/deployment";
+
+export function GET() {
+    return createDeploymentReadinessResponse(
+        deployment
+    );
+}
+```
+
+Successful readiness returns HTTP `200`. A non-ready runtime returns `503`.
+
+The response uses:
+
+```text
+Cache-Control: no-store
+```
+
+Recommended route:
+
+```text
+/api/ready
+```
+
+Do not place authentication/user data in this endpoint when it is consumed by infrastructure health probes.
+
+## Diagnostics
+
+```ts
+const diagnostics =
+    await deployment.diagnostics();
+```
+
+The report includes:
+
+- service/deployment identity;
+- process ID;
+- Node version;
+- platform/architecture;
+- runtime state;
+- uptime;
+- lifecycle state for each registered resource;
+- optional resource-specific diagnostic metadata.
+
+An HTTP response helper is available:
+
+```ts
+import {
+    createDeploymentDiagnosticsResponse,
+} from "bcp/deployment";
+
+export function GET() {
+    return createDeploymentDiagnosticsResponse(
+        deployment
+    );
+}
+```
+
+Diagnostics can reveal infrastructure details. Protect the route when exposing it outside a trusted operations network.
+
+## Deployment metadata
+
+The runtime accepts explicit identifiers:
+
+```ts
+createDeploymentRuntime({
+    serviceName:
+        "orders-api",
+    deploymentId:
+        "deploy-20260831-01",
+    instanceId:
+        "orders-api-7f5d9",
+    release:
+        "2026.08.31",
+    environmentName:
+        "production",
+});
+```
+
+Or resolve them from runtime environment variables:
+
+```text
+BCP_DEPLOYMENT_ID
+BCP_INSTANCE_ID
+BCP_RELEASE
+NODE_ENV
+```
+
+If `BCP_DEPLOYMENT_ID` is not supplied, BCP generates a UUID for the process.
+
+## Shutdown timeout
+
+Default shutdown timeout:
+
+```text
+10 seconds
+```
+
+Configure it explicitly:
+
+```ts
+createDeploymentRuntime({
+    serviceName: "orders-api",
+    shutdownTimeoutMs:
+        30_000,
+});
+```
+
+or through:
+
+```dotenv
+BCP_SHUTDOWN_TIMEOUT_MS=30000
+```
+
+The timeout is shared by reverse-order resource shutdown. If a resource does not finish before the remaining deadline, shutdown records the failure and eventually rejects with `AggregateError`.
+
+## Signal handling
+
+Install handlers:
+
+```ts
+const removeSignals =
+    deployment.installSignalHandlers();
+```
+
+Default signals:
+
+```text
+SIGTERM
+SIGINT
+```
+
+The handlers start graceful shutdown and set `process.exitCode` rather than immediately calling `process.exit()`. This allows pending cleanup/microtasks to finish.
+
+Remove handlers when ownership moves elsewhere:
+
+```ts
+removeSignals();
+```
+
+Custom signal set:
+
+```ts
+deployment.installSignalHandlers({
+    signals: [
+        "SIGTERM",
+    ],
+});
+```
+
+## Existing BCP shutdown hooks
+
+Deployment runtime can participate in the existing production-hardening shutdown registry:
+
+```ts
+const unregister =
+    deployment.registerShutdownHook();
+```
+
+When the framework executes registered shutdown hooks, the deployment runtime drains its resources.
+
+Use either direct signal ownership or integrate with an application-level signal coordinator. Avoid installing multiple independent handlers that all own the same resource lifecycle.
+
+## Recommended topology
+
+```text
+Load balancer / orchestrator
+          │
+          ├── readiness probe
+          │       ↓
+          │   bcp/deployment
+          │
+          └── SIGTERM
+                  ↓
+          state = draining
+                  ↓
+        stop inbound/realtime
+                  ↓
+          stop workers/jobs
+                  ↓
+          close database
+                  ↓
+          state = stopped
+```
+
+## Jobs and workflow workers
+
+Register workers as resources so they stop before shared dependencies such as Redis or SQL connections:
+
+```ts
+deployment.addResource({
+    name: "workers",
+
+    start() {
+        worker =
+            jobs.startWorker();
+    },
+
+    async stop() {
+        await worker.stop();
+    },
+});
+```
+
+Register database/cache connections before workers. Reverse-order shutdown then naturally stops workers before closing their dependencies.
+
+## Realtime
+
+For realtime transports, mark the system not-ready before closing shared storage/transport resources. Runtime state changes to `draining` before resource stop hooks run, so readiness probes begin returning `503` while shutdown is in progress.
+
+## Observability
+
+Deployment metadata can be attached to logs/traces:
+
+```ts
+const metadata =
+    deployment.metadata;
+
+logger.info(
+    "runtime ready",
+    {
+        deploymentId:
+            metadata.deploymentId,
+        instanceId:
+            metadata.instanceId,
+        release:
+            metadata.release,
+    }
+);
+```
+
+Use `bcp/observability` for trace/span correlation and `bcp/deployment` for process/deployment identity and lifecycle state.
+
+## Compiled server runtimes
+
+Prepared `bcp` packages now compile these production entrypoints:
+
+```text
+bcp/cache          -> cache.mjs
+bcp/config         -> config.mjs
+bcp/database       -> database.mjs
+bcp/auth           -> auth.mjs
+bcp/jobs           -> jobs.mjs
+bcp/workflow       -> workflow.mjs
+bcp/events         -> events.mjs
+bcp/realtime       -> realtime.mjs
+bcp/testing        -> testing.mjs
+bcp/plugins        -> plugins.mjs
+bcp/observability  -> observability.mjs
+bcp/deployment     -> deployment.mjs
+bcp/server         -> server.mjs
+bcp/middleware     -> middleware.mjs
+```
+
+Type declarations/source types remain available from the TypeScript source entrypoint while runtime resolution points to compiled ESM in prepared npm packages.
+
+This reduces reliance on Node TypeScript stripping for server framework runtime entrypoints and provides a more deterministic production package.
+
+## Compatibility
+
+`0.2.18` is intended to be backward compatible with `0.2.17`.
+
+Existing:
+
+```text
+bcp build
+bcp package
+npm start
+registerShutdownHook()
+```
+
+remain available. `bcp/deployment` is additive.
+
+## Related guides
+
+- [Application Packaging](application-packaging.md)
+- [Deployment](deployment.md)
+- [Production Hardening](production-hardening.md)
+- [Observability Platform v3](observability-v3.md)
+- [Background Jobs](background-jobs.md)
+- [Realtime Platform](realtime-platform.md)

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.16",
+  "versionTarget": "0.2.18",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -58,12 +58,14 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Middleware, jobs, scheduling, workflows, event delivery, realtime channels, observability, distributed caching, security and production hardening.",
+      "description": "Middleware, jobs, scheduling, workflows, event delivery, realtime channels, observability, deployment lifecycle, distributed 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" },
         { "route": "/docs/observability", "source": "observability.md", "title": "Observability Platform v2" },
+        { "route": "/docs/observability-v3", "source": "observability-v3.md", "title": "Observability Platform v3" },
+        { "route": "/docs/deployment-platform-v2", "source": "deployment-platform-v2.md", "title": "Deployment Platform v2" },
         { "route": "/docs/background-jobs", "source": "background-jobs.md", "title": "Background Jobs Platform" },
         { "route": "/docs/job-scheduling", "source": "job-scheduling.md", "title": "Job Scheduling Platform" },
         { "route": "/docs/durable-jobs", "source": "durable-jobs.md", "title": "Durable Jobs Platform" },
@@ -117,7 +119,9 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.16", "source": "releases/0.2.16.md", "version": "0.2.16", "state": "unreleased" },
+    { "route": "/releases/0.2.18", "source": "releases/0.2.18.md", "version": "0.2.18", "state": "unreleased" },
+    { "route": "/releases/0.2.17", "source": "releases/0.2.17.md", "version": "0.2.17" },
+    { "route": "/releases/0.2.16", "source": "releases/0.2.16.md", "version": "0.2.16" },
     { "route": "/releases/0.2.15", "source": "releases/0.2.15.md", "version": "0.2.15" },
     { "route": "/releases/0.2.14", "source": "releases/0.2.14.md", "version": "0.2.14" },
     { "route": "/releases/0.2.13", "source": "releases/0.2.13.md", "version": "0.2.13" },