@chidchanun/bcp 0.1.27 → 0.1.28

package/README.md

@@ -2,9 +2,9 @@
 
 BCP Framework is a React full-stack framework focused on file-based routing, SSR, server data loading, guarded application flows, API routes, authentication, database access, validation, logging, uploads, storage and standalone production deployment.
 
-> **Development target:** `0.1.27`
+> **Development target:** `0.1.28`
 >
-> BCP is pre-1.0. The `0.1.27` source adds the Storage Ecosystem and remains an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> BCP is pre-1.0. The `0.1.28` source adds Production Hardening and remains an unreleased development target until local validation, RC checks, tagging and npm publication complete.
 
 ## Current capabilities
 
@@ -25,7 +25,7 @@ BCP Framework is a React full-stack framework focused on file-based routing, SSR
 | Storage | Local + S3-compatible adapters, streaming, listing, copy/move, metadata, bulk delete and signed S3 URLs |
 | Caching | Response cache and revalidation primitives |
 | Developer tools | `doctor`, `inspect`, updater and route inspection |
-| Production | Standalone server build with production middleware pipeline |
+| Production | Standalone build, hardening gateway, graceful shutdown, trusted-proxy controls and HTTP timeouts |
 
 ## Requirements
 
@@ -229,6 +229,8 @@ const storage =
     });
 ```
 
+`create-bcp-app --storage local` creates `lib/storage.ts` plus a visible `storage/README.md` / `.gitkeep` scaffold. Runtime objects remain ignored by Git.
+
 ### S3 / R2 / MinIO
 
 ```ts
@@ -284,72 +286,9 @@ import {
 } from "bcp/server";
 ```
 
-Listing supports prefix filtering, limits and opaque cursors:
-
-```ts
-const page =
-    await listStorageObjects(
-        storage,
-        {
-            prefix: "documents/",
-            limit: 50,
-        }
-    );
-```
-
-Copy and move use native adapter operations when available, with portable fallback behavior where practical:
-
-```ts
-await copyStorageObject(
-    storage,
-    "incoming/report.pdf",
-    "archive/report.pdf"
-);
-
-await moveStorageObject(
-    storage,
-    "tmp/avatar.webp",
-    "users/42/avatar.webp"
-);
-```
-
-Portable user metadata is string-to-string metadata and is distinct from application authorization/business state:
-
-```ts
-await setStorageMetadata(
-    storage,
-    "archive/report.pdf",
-    {
-        owner: "user-42",
-        status: "approved",
-    }
-);
-```
-
-S3-compatible storage also supports short-lived presigned direct-transfer URLs:
+Listing supports prefix filtering, limits and opaque cursors. Copy and move use native adapter operations when available, with portable fallback behavior where practical. Portable user metadata is string-to-string metadata and is distinct from authorization/business state.
 
-```ts
-const downloadUrl =
-    await createStorageSignedReadUrl(
-        storage,
-        "videos/demo.mp4",
-        {
-            expiresIn: 300,
-        }
-    );
-
-const uploadUrl =
-    await createStorageSignedWriteUrl(
-        storage,
-        "uploads/demo.mp4",
-        {
-            expiresIn: 300,
-            contentType: "video/mp4",
-        }
-    );
-```
-
-Local storage intentionally does not emulate signed URLs. Signed URLs are temporary credentials and should only be generated after application authorization.
+S3-compatible storage also supports short-lived presigned direct-transfer URLs. Local storage intentionally does not emulate signed URLs.
 
 Read more: [Storage Ecosystem](docs/storage-ecosystem.md)
 
@@ -401,7 +340,38 @@ Standalone output is written under:
    └─ server.mjs
 ```
 
-Read more: [Deployment](docs/deployment.md)
+### Production Hardening — 0.1.28
+
+The standalone runtime is wrapped by a public hardening gateway with configurable HTTP and shutdown behavior:
+
+```dotenv
+BCP_REQUEST_TIMEOUT_MS=120000
+BCP_HEADERS_TIMEOUT_MS=66000
+BCP_KEEP_ALIVE_TIMEOUT_MS=65000
+BCP_SHUTDOWN_TIMEOUT_MS=10000
+BCP_TRUST_PROXY=false
+```
+
+Standalone production handles `SIGTERM` and `SIGINT`, drains the public listener, runs application cleanup hooks and then stops internal runtime layers.
+
+```ts
+import {
+    registerShutdownHook,
+} from "bcp/server";
+
+registerShutdownHook(
+    () => {
+        storage.destroy();
+    },
+    {
+        name: "storage",
+    }
+);
+```
+
+Trusted proxy mode is disabled by default. Enable `BCP_TRUST_PROXY=true` only when direct untrusted traffic cannot bypass the trusted reverse proxy/load balancer.
+
+Read more: [Production Hardening](docs/production-hardening.md)
 
 ## Windows CLI
 
@@ -428,7 +398,7 @@ Read more: [Developer Tools](docs/developer-tools.md)
 bcp update
 bcp update --check
 bcp update --dry-run
-bcp update 0.1.27
+bcp update 0.1.28
 bcp update next
 ```
 
@@ -468,6 +438,7 @@ Recommended starting points:
 - [Storage and File Delivery](docs/storage.md)
 - [Storage Ecosystem](docs/storage-ecosystem.md)
 - [S3-Compatible Storage](docs/s3-storage.md)
+- [Production Hardening](docs/production-hardening.md)
 - [Authentication](docs/authentication.md)
 - [Database](docs/database.md)
 - [Middleware](docs/middleware.md)
@@ -487,20 +458,19 @@ Recommended starting points:
 | `0.1.25` | Storage Adapters and File Delivery |
 | `0.1.26` | S3-Compatible Storage and Production Streaming |
 | `0.1.27` | Storage Ecosystem |
+| `0.1.28` | Production Hardening |
 
 ## Next direction
 
-After `0.1.27`, the planned milestone is **`0.1.28 — Production Hardening`**:
+After `0.1.28`, the planned milestone is **`0.1.29 — Developer Experience`**:
 
-1. graceful HTTP shutdown and active-request draining,
-2. database/S3 resource cleanup,
-3. trusted proxy and forwarded-header handling,
-4. request/server timeout controls,
-5. security hardening,
-6. Docker and standalone-runtime regression coverage,
-7. stronger startup/runtime diagnostics.
+1. route/API/middleware/migration generators,
+2. richer `doctor` and `inspect` diagnostics,
+3. clearer build/runtime error messages,
+4. improved create-app presets and automation flags,
+5. production configuration diagnostics.
 
-These are roadmap items, not `0.1.27` guarantees.
+These are roadmap items, not `0.1.28` guarantees.
 
 ## License
 

package/docs/README.md

@@ -1,10 +1,10 @@
 # BCP Framework Documentation Source
 
-The `docs/` directory is the documentation source of truth for BCP Framework and is intentionally organized for the future **`bcp-docs-web`** website.
+The `docs/` directory is the documentation source of truth for BCP Framework and is intentionally organized for the **`bcp-docs-web`** website.
 
-> **Documentation target:** BCP Framework `0.1.27`
+> **Documentation target:** BCP Framework `0.1.28`
 >
-> **Release state:** unreleased development target. Do not label `0.1.27` as published until RC validation and npm publication complete.
+> **Release state:** unreleased development target. Do not label `0.1.28` as published until RC validation and npm publication complete.
 
 ## Documentation flow
 
@@ -88,6 +88,7 @@ Releases
 | `/docs/development-logging` | `development-logging.md` | Logging/observability |
 | `/docs/caching` | `caching.md` | Cache/revalidation |
 | `/docs/security` | `security.md` | Security/body limits |
+| `/docs/production-hardening` | `production-hardening.md` | Graceful shutdown, trusted proxy and production timeouts |
 
 ### Storage & Uploads
 
@@ -117,7 +118,7 @@ bcp/middleware
 | Entrypoint | Primary guide |
 | --- | --- |
 | `bcp` | `routing.md`, `server-data-loaders.md`, `form-actions.md` |
-| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `storage-ecosystem.md`, `s3-storage.md`, `development-logging.md` |
+| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `storage-ecosystem.md`, `s3-storage.md`, `development-logging.md`, `production-hardening.md` |
 | `bcp/auth` | `authentication.md`, `auth-route-guards.md` |
 | `bcp/database` | `database.md`, `database-migrations.md` |
 | `bcp/validation` | `validation.md` |
@@ -139,7 +140,7 @@ bcp/middleware
 - client islands / partial hydration
 - Fast Refresh
 
-### Server
+### Server and production runtime
 
 - request-scoped APIs/cookies/redirects/request IDs
 - JWT sessions/authentication
@@ -147,6 +148,11 @@ bcp/middleware
 - validation/structured errors
 - structured logging
 - response caching/security gateway
+- production hardening gateway
+- configurable request/header/keep-alive/shutdown timeouts
+- `SIGTERM` / `SIGINT` graceful shutdown
+- application shutdown hooks
+- trusted-proxy forwarding-header controls
 
 ### Storage & Uploads
 
@@ -163,6 +169,7 @@ bcp/middleware
 - portable user metadata
 - bulk deletion
 - S3 presigned read/write URLs
+- create-app Local Server / Amazon S3 / Cloudflare R2 presets
 
 ### Database
 
@@ -182,66 +189,56 @@ bcp/middleware
 - standalone production build
 - unit/integration/E2E/package/RC checks
 
-## BCP 0.1.27 documentation focus
+## BCP 0.1.28 documentation focus
 
-### Storage ecosystem
+### Production hardening
 
-New generic helpers include:
+Public cleanup API:
 
 ```ts
 import {
-    copyStorageObject,
-    createStorageSignedReadUrl,
-    createStorageSignedWriteUrl,
-    deleteStorageObjects,
-    getStorageEcosystemCapabilities,
-    getStorageMetadata,
-    listStorageObjects,
-    moveStorageObject,
-    setStorageMetadata,
+    getProductionHardeningConfig,
+    registerShutdownHook,
 } from "bcp/server";
 ```
 
+Production environment controls:
+
+```dotenv
+BCP_REQUEST_TIMEOUT_MS=120000
+BCP_HEADERS_TIMEOUT_MS=66000
+BCP_KEEP_ALIVE_TIMEOUT_MS=65000
+BCP_SHUTDOWN_TIMEOUT_MS=10000
+BCP_TRUST_PROXY=false
+```
+
 Document these boundaries clearly:
 
-- ecosystem methods are additive and do not invalidate older `StorageAdapter` implementations,
-- listing cursors are opaque,
-- overwrite remains opt-in,
-- move is copy + delete rather than an atomic distributed transaction,
-- application metadata is portable string metadata and not authorization/business state,
-- `bcp_sha256` is reserved for framework checksum metadata,
-- local storage does not emulate signed URLs,
-- S3 direct-transfer URLs are temporary credentials and require application authorization before issuance.
+- trusted proxy mode is off by default,
+- forwarding headers are sanitized when trust is disabled,
+- enable trust only behind a trusted reverse proxy/load balancer,
+- Docker/process-manager `SIGTERM` triggers graceful shutdown,
+- shutdown hooks are process-lifetime resource cleanup, not request cleanup,
+- shutdown force-closes remaining public connections after the configured timeout.
 
-See `storage-ecosystem.md`.
+See `production-hardening.md`.
 
-### S3 ecosystem
+### Local Server generator fix
 
-`createS3Storage()` keeps the same public constructor and now adds:
+`create-bcp-app --storage local` now generates:
 
 ```text
-ListObjectsV2
-CopyObject
-DeleteObjects
-presigned GetObject
-presigned PutObject
-application metadata
+lib/storage.ts
+storage/
+├─ .gitkeep
+└─ README.md
 ```
 
-See `s3-storage.md`.
-
-### 0.1.26 foundations remain supported
+Runtime objects remain ignored while the scaffold stays visible/tracked.
 
-The following remain part of the storage stack:
+### 0.1.27 storage ecosystem remains supported
 
-```text
-putStorageStream()
-readStorageStream()
-storeMultipartFile()
-createStorageResponse()
-```
-
-`0.1.27` builds on these rather than replacing them.
+The storage ecosystem continues to include listing, copy/move, portable metadata, bulk deletion and S3 signed URLs. `0.1.28` hardens deployment/runtime behavior rather than replacing those APIs.
 
 ## CLI commands
 
@@ -285,12 +282,11 @@ docs/releases/
 Recommended routes:
 
 ```text
+/releases/0.1.28
 /releases/0.1.27
 /releases/0.1.26
 /releases/0.1.25
 /releases/0.1.24
-/releases/0.1.23
-/releases/0.1.22
 ```
 
 Use one of these release states:
@@ -319,8 +315,6 @@ interface DocPage {
 }
 ```
 
-The first `bcp-docs-web` implementation can keep this mapping in a route manifest and consume Markdown directly.
-
 ## Suggested website features
 
 1. Sidebar navigation from this source map.
@@ -365,16 +359,9 @@ npm run test:package
 npm run rc:check
 ```
 
-For `0.1.27`, package validation must also confirm the staged artifact includes:
+For `0.1.28`, package validation must confirm the staged artifact includes the production hardening runtime/gateway, shutdown APIs, Local Server generator fix, and the existing S3 runtime dependencies.
 
-```text
-@aws-sdk/client-s3
-@aws-sdk/lib-storage
-@aws-sdk/s3-request-presigner
-busboy
-```
-
-and the ecosystem runtime/public exports.
+A representative Docker app should also be built and stopped with `docker stop` to verify graceful `SIGTERM` shutdown.
 
 ## Documentation QA checklist
 
@@ -383,36 +370,24 @@ and the ecosystem runtime/public exports.
 - version/release states are current,
 - Windows direct CLI examples use `npm exec -- bcp-framework`,
 - upload/storage/auth security caveats are present,
-- route names match the current router,
 - release notes match the framework version,
 - S3 credentials are never shown as public browser variables,
 - signed URLs are documented as temporary credentials,
+- proxy trust is documented as opt-in,
 - roadmap APIs are not presented as published guarantees.
 
-## Next direction after 0.1.27
+## Next direction after 0.1.28
 
-Planned `0.1.28 — Production Hardening` focus:
+Planned `0.1.29 — Developer Experience` focus:
 
-- graceful HTTP shutdown and active-request draining,
-- database/S3 resource cleanup,
-- trusted proxy and forwarded-header handling,
-- timeout controls,
-- security hardening,
-- Docker/standalone runtime regression coverage,
-- startup/runtime dependency diagnostics.
+- generators for common framework files,
+- richer `doctor` and `inspect`,
+- improved build/runtime diagnostics,
+- create-app preset improvements,
+- production configuration diagnostics.
 
 These remain roadmap items until their source/tests land.
 
 ## Repository authority
 
-The framework repository remains authoritative for:
-
-```text
-source
-public exports
-tests
-docs
-release notes
-```
-
-`bcp-docs-web` is the presentation/search/navigation layer for this content.
+The framework repository remains authoritative for source, public exports, tests, docs and release notes. `bcp-docs-web` is the presentation/search/navigation layer for this content.

package/docs/production-hardening.md

@@ -0,0 +1,152 @@
+# Production Hardening
+
+BCP Framework `0.1.28` adds a production hardening gateway around the standalone runtime.
+
+The gateway is the public HTTP listener. Existing security, cache, critical CSS, page/API and SSR runtimes remain bound to internal loopback ports behind it.
+
+## Default production behavior
+
+The hardening gateway configures Node HTTP timeouts and graceful shutdown defaults:
+
+```text
+Request timeout:    120000 ms
+Headers timeout:     66000 ms
+Keep-alive timeout:  65000 ms
+Shutdown timeout:    10000 ms
+Trust proxy:         false
+```
+
+Override them with server-only environment variables:
+
+```dotenv
+BCP_REQUEST_TIMEOUT_MS=120000
+BCP_HEADERS_TIMEOUT_MS=66000
+BCP_KEEP_ALIVE_TIMEOUT_MS=65000
+BCP_SHUTDOWN_TIMEOUT_MS=10000
+BCP_TRUST_PROXY=false
+```
+
+`BCP_HEADERS_TIMEOUT_MS` must be greater than `BCP_KEEP_ALIVE_TIMEOUT_MS`.
+
+## Graceful shutdown
+
+Standalone production now handles `SIGTERM` and `SIGINT`.
+
+This is especially important for Docker, Kubernetes and process managers that send `SIGTERM` before stopping a process.
+
+Shutdown order:
+
+```text
+stop accepting public traffic
+        ↓
+drain/close public HTTP connections
+        ↓
+run application shutdown hooks
+        ↓
+stop internal BCP runtime layers
+        ↓
+process exits naturally
+```
+
+If the public server does not close before `BCP_SHUTDOWN_TIMEOUT_MS`, BCP force-closes remaining connections.
+
+## Application shutdown hooks
+
+Register cleanup work through `bcp/server`:
+
+```ts
+import {
+    registerShutdownHook,
+} from "bcp/server";
+
+const unregister =
+    registerShutdownHook(
+        async () => {
+            await closeApplicationResources();
+        },
+        {
+            name: "application-resources",
+        }
+    );
+```
+
+Hooks run in reverse registration order. Calling the returned function unregisters the hook.
+
+For S3-compatible storage, an application can register the adapter client cleanup when it owns the adapter for the lifetime of the process:
+
+```ts
+registerShutdownHook(
+    () => {
+        storage.destroy();
+    },
+    {
+        name: "s3-storage",
+    }
+);
+```
+
+Do not register request-scoped resources as process shutdown hooks.
+
+## Trusted proxy mode
+
+The hardening gateway sanitizes forwarding headers by default.
+
+```dotenv
+BCP_TRUST_PROXY=false
+```
+
+This prevents a direct client from spoofing headers such as:
+
+```text
+Forwarded
+X-Forwarded-For
+X-Forwarded-Host
+X-Forwarded-Proto
+X-Real-IP
+```
+
+When BCP is deployed only behind a trusted reverse proxy such as Nginx, Cloudflare Tunnel or a trusted load balancer, enable:
+
+```dotenv
+BCP_TRUST_PROXY=true
+```
+
+BCP then preserves the trusted proxy forwarding chain and appends the immediate peer address where appropriate.
+
+Only enable trusted proxy mode when direct untrusted traffic cannot bypass the trusted proxy.
+
+## Docker
+
+A production compose service can use:
+
+```yaml
+services:
+  app:
+    init: true
+    restart: unless-stopped
+    environment:
+      NODE_ENV: production
+      BCP_HOSTNAME: 0.0.0.0
+      BCP_PORT: 3000
+      BCP_SHUTDOWN_TIMEOUT_MS: 10000
+      BCP_TRUST_PROXY: "true"
+```
+
+Set `BCP_TRUST_PROXY=true` only when the container receives requests exclusively from a trusted reverse proxy/network path.
+
+Docker's stop grace period should be longer than `BCP_SHUTDOWN_TIMEOUT_MS` so BCP gets time to drain connections and cleanup resources.
+
+## Local Server storage scaffold
+
+`create-bcp-app --storage local` now creates:
+
+```text
+lib/storage.ts
+storage/
+├─ .gitkeep
+└─ README.md
+```
+
+Runtime objects inside `storage/` are ignored while the scaffold files remain tracked. The generated README explains that BCP writes objects and `.bcp-storage-meta` metadata there at runtime.
+
+The directory therefore no longer appears as an unexplained empty folder before the first upload.