@chidchanun/bcp 0.1.26 → 0.1.28

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.26`
+> **Documentation target:** BCP Framework `0.1.28`
 >
-> **Release state:** release-candidate source. Do not label `0.1.26` 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
 
@@ -95,7 +96,8 @@ Releases
 | --- | --- | --- |
 | `/docs/file-upload` | `file-upload.md` | Buffered + streaming multipart uploads |
 | `/docs/storage` | `storage.md` | StorageAdapter, streaming and file delivery |
-| `/docs/s3-storage` | `s3-storage.md` | S3-compatible adapter/configuration |
+| `/docs/storage-ecosystem` | `storage-ecosystem.md` | Listing, copy/move, metadata, bulk delete, signed URLs |
+| `/docs/s3-storage` | `s3-storage.md` | S3/R2/MinIO adapter and direct object access |
 
 ## API Reference ownership
 
@@ -116,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`, `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` |
@@ -138,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
@@ -146,18 +148,28 @@ 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
 
 - buffered multipart `FormData` upload APIs
 - production streaming multipart upload (`storeMultipartFile()`)
-- `StorageAdapter` contract
-- local filesystem adapter
-- S3-compatible adapter
-- streaming reads/writes
-- byte ranges
+- backward-compatible `StorageAdapter` contract
+- local filesystem storage
+- S3/R2/MinIO-compatible storage
+- streaming reads/writes and byte ranges
 - ETag/Last-Modified file delivery
 - upload/storage limits and abort cleanup
+- object listing with cursors
+- native/fallback copy and move
+- portable user metadata
+- bulk deletion
+- S3 presigned read/write URLs
+- create-app Local Server / Amazon S3 / Cloudflare R2 presets
 
 ### Database
 
@@ -177,64 +189,56 @@ bcp/middleware
 - standalone production build
 - unit/integration/E2E/package/RC checks
 
-## BCP 0.1.26 documentation focus
+## BCP 0.1.28 documentation focus
 
-### Storage streaming
+### Production hardening
 
-Public additions include:
+Public cleanup API:
 
 ```ts
 import {
-    getStorageCapabilities,
-    putStorageStream,
-    readStorageStream,
+    getProductionHardeningConfig,
+    registerShutdownHook,
 } from "bcp/server";
 ```
 
-Streaming methods remain optional on custom adapters for `0.1.25` compatibility.
+Production environment controls:
 
-### S3-compatible storage
-
-```ts
-import {
-    createS3Storage,
-} from "bcp/server";
+```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:
+Document these boundaries clearly:
 
-- bucket/region/endpoint setup,
-- optional explicit credentials,
-- AWS default credential chain behavior,
-- `forcePathStyle` for compatible services such as MinIO,
-- prefix handling,
-- multipart streaming,
-- ranges/ETag metadata,
-- overwrite limitations for concurrent multipart writers,
-- server-only credential/security requirements.
+- 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 `s3-storage.md`.
+See `production-hardening.md`.
 
-### Production multipart streaming
+### Local Server generator fix
 
-```ts
-import {
-    storeMultipartFile,
-} from "bcp/server";
+`create-bcp-app --storage local` now generates:
+
+```text
+lib/storage.ts
+storage/
+├─ .gitkeep
+└─ README.md
 ```
 
-Document:
+Runtime objects remain ignored while the scaffold stays visible/tracked.
 
-- one named streamed file field per operation,
-- total request limit,
-- per-file limit,
-- MIME/extension validation,
-- fixed/callback storage keys,
-- AbortSignal behavior,
-- direct local/S3 streaming,
-- difference from `request.formData()` / buffered APIs.
+### 0.1.27 storage ecosystem remains supported
 
-See `file-upload.md`.
+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
 
@@ -278,11 +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:
@@ -311,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.
@@ -357,15 +359,9 @@ npm run test:package
 npm run rc:check
 ```
 
-For `0.1.26`, package validation must also confirm the staged npm artifact contains:
-
-```text
-@aws-sdk/client-s3
-@aws-sdk/lib-storage
-busboy
-```
+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.
 
-and the S3/multipart streaming source files/public exports.
+A representative Docker app should also be built and stopped with `docker stop` to verify graceful `SIGTERM` shutdown.
 
 ## Documentation QA checklist
 
@@ -374,33 +370,24 @@ and the S3/multipart streaming source files/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.26
+## Next direction after 0.1.28
 
-Recommended `0.1.27` direction:
+Planned `0.1.29 — Developer Experience` focus:
 
-- signed URLs where needed,
-- object listing/copy/move capabilities,
-- broader production hardening,
-- graceful shutdown/resource cleanup,
-- stronger storage/provider diagnostics.
+- generators for common framework files,
+- richer `doctor` and `inspect`,
+- improved build/runtime diagnostics,
+- create-app preset improvements,
+- production configuration diagnostics.
 
-These are roadmap items, not `0.1.26` guarantees.
+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.