@chidchanun/bcp 0.1.26 → 0.1.28

package/docs/releases/0.1.27.md

@@ -0,0 +1,350 @@
+# BCP Framework 0.1.27
+
+BCP Framework `0.1.27` is the **Storage Ecosystem** milestone.
+
+> Release state: unreleased development target until local validation, RC checks, tagging and npm publication complete.
+
+## Highlights
+
+- Added object listing with prefix filtering, limits and opaque cursors.
+- Added generic and native copy/move operations.
+- Added application user metadata for local and S3-compatible storage.
+- Added bulk deletion helpers.
+- Added S3 presigned read and write URLs.
+- Expanded storage capability discovery without breaking the `0.1.26` `StorageAdapter` contract.
+- Preserved fallback copy/move/delete-many behavior for older custom adapters.
+- Added `create-bcp-app` storage provider selection for Local Server, Amazon S3 and Cloudflare R2.
+- Added provider-specific `lib/storage.ts` scaffolding and `.env.example` configuration.
+- Added local storage ecosystem unit coverage.
+- Added S3-compatible ecosystem integration coverage.
+- Extended packed-package smoke checks for the new runtime and presigner dependency.
+
+## Public API additions
+
+All new application APIs are available through `bcp/server`:
+
+```ts
+import {
+    copyStorageObject,
+    createStorageSignedReadUrl,
+    createStorageSignedWriteUrl,
+    deleteStorageObjects,
+    getStorageEcosystemCapabilities,
+    getStorageMetadata,
+    listStorageObjects,
+    moveStorageObject,
+    setStorageMetadata,
+} from "bcp/server";
+```
+
+New public types include:
+
+```text
+StorageEcosystemAdapter
+StorageEcosystemCapabilities
+StorageEcosystemPutOptions
+StorageEcosystemPutStreamOptions
+StorageListOptions
+StorageListResult
+StorageCopyOptions
+StorageDeleteManyResult
+StorageSignedUrlOptions
+StorageSignedWriteUrlOptions
+StorageUserMetadata
+S3StorageEcosystemAdapter
+```
+
+## Backward compatibility
+
+The original `StorageAdapter` remains valid. Ecosystem methods are additive and optional.
+
+Generic helpers select a native adapter method when available. Operations that can be implemented portably, such as copy/move/delete-many, also have compatibility fallbacks where practical.
+
+Custom `0.1.25` / `0.1.26` adapters therefore do not need to implement all `0.1.27` methods immediately.
+
+## create-bcp-app storage provider selection
+
+Interactive project creation now includes:
+
+```text
+Select storage provider:
+  None
+  Local Server
+  Amazon S3
+  Cloudflare R2
+```
+
+The same choices can be automated:
+
+```bash
+npx create-bcp-app my-app --storage local
+npx create-bcp-app my-app --storage amazon-s3
+npx create-bcp-app my-app --storage cloudflare-r2
+```
+
+Supported flag values are:
+
+```text
+none
+local
+amazon-s3
+cloudflare-r2
+```
+
+Selecting a provider creates `lib/storage.ts` and appends provider-specific settings to `.env.example`.
+
+### Local Server preset
+
+```dotenv
+STORAGE_LOCAL_DIRECTORY=./storage
+```
+
+The generated helper uses `createLocalStorage()` and adds `storage/` to `.gitignore`.
+
+### Amazon S3 preset
+
+```dotenv
+AWS_S3_BUCKET=
+AWS_REGION=ap-southeast-1
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_SESSION_TOKEN=
+AWS_S3_PREFIX=
+```
+
+The generated helper uses `createS3Storage()`. Explicit credentials are optional when the application deployment uses the AWS SDK server-side credential provider chain.
+
+### Cloudflare R2 preset
+
+```dotenv
+R2_ACCOUNT_ID=
+R2_BUCKET=
+R2_ACCESS_KEY_ID=
+R2_SECRET_ACCESS_KEY=
+R2_PREFIX=
+```
+
+The generated helper uses the S3-compatible adapter with `region: "auto"` and the Cloudflare account endpoint.
+
+All generated storage credentials remain server-only and must not be moved into `BCP_PUBLIC_*` environment variables.
+
+## Listing
+
+```ts
+const page =
+    await listStorageObjects(
+        storage,
+        {
+            prefix: "documents/",
+            limit: 50,
+        }
+    );
+```
+
+The result contains:
+
+```ts
+{
+    objects: StorageObjectMetadata[];
+    cursor?: string;
+}
+```
+
+Cursors are opaque. Applications should pass them back unchanged rather than decoding or constructing them.
+
+The built-in local adapter uses a stable key-order cursor. The S3 adapter maps the generic cursor to the provider continuation token.
+
+## Copy and move
+
+```ts
+await copyStorageObject(
+    storage,
+    "incoming/report.pdf",
+    "archive/report.pdf"
+);
+
+await moveStorageObject(
+    storage,
+    "incoming/avatar.webp",
+    "users/42/avatar.webp"
+);
+```
+
+S3 uses native `CopyObject`. Other adapters can fall back to streamed read/write copy behavior.
+
+Overwrite remains opt-in.
+
+## User metadata
+
+`0.1.27` adds portable string metadata separate from BCP's internal checksum metadata:
+
+```ts
+await storage.put(
+    "documents/report.pdf",
+    bytes,
+    {
+        contentType: "application/pdf",
+        metadata: {
+            owner: "user-42",
+            category: "report",
+        },
+    }
+);
+```
+
+Read or replace metadata independently:
+
+```ts
+const metadata =
+    await getStorageMetadata(
+        storage,
+        "documents/report.pdf"
+    );
+
+await setStorageMetadata(
+    storage,
+    "documents/report.pdf",
+    {
+        owner: "user-42",
+        state: "approved",
+    }
+);
+```
+
+Metadata keys are normalized to lowercase and must use portable storage-safe characters. The reserved `bcp_sha256` key cannot be set by applications.
+
+## Bulk deletion
+
+```ts
+const result =
+    await deleteStorageObjects(
+        storage,
+        [
+            "tmp/a.bin",
+            "tmp/b.bin",
+        ]
+    );
+```
+
+The result contains:
+
+```ts
+{
+    deleted: string[];
+    missing: string[];
+    failed: Array<{
+        key: string;
+        message: string;
+    }>;
+}
+```
+
+S3 deletion semantics treat deletion of a missing object as successful, so S3 normally reports those keys under `deleted` rather than `missing`.
+
+## Presigned URLs
+
+S3-compatible adapters expose direct read/write signing:
+
+```ts
+const downloadUrl =
+    await createStorageSignedReadUrl(
+        storage,
+        "videos/demo.mp4",
+        {
+            expiresIn: 300,
+        }
+    );
+
+const uploadUrl =
+    await createStorageSignedWriteUrl(
+        storage,
+        "uploads/demo.mp4",
+        {
+            expiresIn: 300,
+            contentType: "video/mp4",
+        }
+    );
+```
+
+Signed URLs are useful when browsers or other clients should transfer large files directly with object storage rather than proxying bytes through the application server.
+
+The default expiry is 15 minutes. `expiresIn` is limited to the S3 SigV4 maximum of seven days.
+
+Local filesystem storage intentionally does not emulate signed URLs.
+
+## Capabilities
+
+Use:
+
+```ts
+getStorageEcosystemCapabilities(storage)
+```
+
+The extended capability result includes:
+
+```ts
+{
+    streamingRead,
+    streamingWrite,
+    ranges,
+    signedUrls,
+    listing,
+    signedReadUrls,
+    signedWriteUrls,
+    copy,
+    move,
+    metadata,
+    bulkDelete,
+}
+```
+
+For the built-in S3 ecosystem adapter all of these capabilities are enabled.
+
+For local storage, listing/copy/move/metadata/bulk-delete are enabled while signed URL capabilities remain disabled.
+
+## Dependency change
+
+The framework package adds:
+
+```text
+@aws-sdk/s3-request-presigner
+```
+
+alongside the S3 client and multipart upload dependencies introduced in `0.1.26`.
+
+## Testing
+
+`0.1.27` adds regression coverage for:
+
+- local listing and pagination,
+- portable metadata,
+- metadata preservation during copy/move,
+- bulk deletion,
+- unsupported local signed URLs,
+- S3 listing,
+- S3 native copy/move,
+- S3 metadata replacement,
+- S3 bulk deletion,
+- S3 signed read/write URL generation,
+- create-app Local Server storage scaffolding,
+- create-app Amazon S3 storage scaffolding,
+- create-app Cloudflare R2 storage scaffolding,
+- non-interactive `--storage` CLI selection,
+- public package exports,
+- packed dependency/runtime presence.
+
+## Remaining release work
+
+Before publication:
+
+1. sync `package-lock.json` with `0.1.27` and the presigner dependency,
+2. run `npm run typecheck`,
+3. run unit/integration/E2E/package tests,
+4. run `npm run rc:check`,
+5. validate a packed `0.1.27` package in a representative application,
+6. create the `v0.1.27` tag only after the final release commit is known,
+7. publish and verify npm visibility.
+
+## Next milestone
+
+The planned next milestone is `0.1.28 — Production Hardening`, focused on graceful shutdown, proxy awareness, timeouts, security and Docker/standalone runtime reliability.

package/docs/releases/0.1.28.md

@@ -0,0 +1,134 @@
+# BCP Framework 0.1.28
+
+BCP Framework `0.1.28` is the **Production Hardening** milestone.
+
+> Release state: unreleased development target until local validation, RC checks, tagging and npm publication complete.
+
+## Highlights
+
+- Added a public production hardening gateway around the existing standalone runtime.
+- Added configurable request, header, keep-alive and shutdown timeouts.
+- Added graceful `SIGTERM` / `SIGINT` handling for Docker and process managers.
+- Added application shutdown hooks through `registerShutdownHook()`.
+- Added trusted-proxy forwarding-header sanitization with secure default `BCP_TRUST_PROXY=false`.
+- Added force-close fallback after the configured graceful shutdown timeout.
+- Fixed `create-bcp-app --storage local` so generated projects no longer contain an unexplained empty storage directory.
+- Added `storage/README.md` and `storage/.gitkeep` while continuing to ignore runtime storage objects.
+- Added regression coverage for production hardening primitives and Local Server scaffolding.
+
+## 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
+```
+
+Defaults are production-safe and require no configuration for ordinary direct HTTP deployments.
+
+`BCP_HEADERS_TIMEOUT_MS` must be greater than `BCP_KEEP_ALIVE_TIMEOUT_MS`.
+
+## Graceful shutdown
+
+The standalone production runtime now handles:
+
+```text
+SIGTERM
+SIGINT
+```
+
+The runtime first stops/drains the public hardening gateway, then runs application shutdown hooks, then stops internal BCP runtime layers.
+
+After `BCP_SHUTDOWN_TIMEOUT_MS`, remaining public connections are force-closed.
+
+## Public API addition
+
+```ts
+import {
+    getProductionHardeningConfig,
+    registerShutdownHook,
+} from "bcp/server";
+```
+
+Example:
+
+```ts
+registerShutdownHook(
+    () => {
+        storage.destroy();
+    },
+    {
+        name: "storage",
+    }
+);
+```
+
+Hooks run in reverse registration order and can be unregistered with the cleanup function returned by `registerShutdownHook()`.
+
+## Trusted proxy behavior
+
+Trusted proxy mode is disabled by default.
+
+When disabled, BCP strips spoofable incoming forwarding headers at the public hardening gateway and writes forwarding information from the actual connection.
+
+When the application is intentionally deployed behind a trusted reverse proxy/load balancer, enable:
+
+```dotenv
+BCP_TRUST_PROXY=true
+```
+
+Only enable it when direct untrusted traffic cannot bypass the trusted proxy.
+
+## Local Server storage fix
+
+Before `0.1.28`, selecting Local Server generated `lib/storage.ts` and configured `./storage`, but the runtime directory had no explanatory scaffold before the first upload.
+
+`0.1.28` generates:
+
+```text
+storage/
+├─ .gitkeep
+└─ README.md
+```
+
+and uses Git ignore rules:
+
+```gitignore
+storage/*
+!storage/.gitkeep
+!storage/README.md
+```
+
+Runtime uploads and `.bcp-storage-meta` remain untracked while the directory structure is visible in a fresh project.
+
+## Testing
+
+`0.1.28` adds coverage for:
+
+- production timeout parsing,
+- invalid timeout relationships,
+- applying Node HTTP server timeout settings,
+- graceful HTTP server close,
+- shutdown hook ordering/unregistration,
+- generated Local Server storage directory scaffold,
+- generated Local Server Git ignore behavior.
+
+## Remaining release work
+
+Before publication:
+
+1. sync `package-lock.json` to `0.1.28`,
+2. run `npm run typecheck`,
+3. run unit/integration/E2E/package tests,
+4. run `npm run rc:check`,
+5. build a representative BCP application,
+6. run the standalone artifact in Docker,
+7. verify `docker stop` produces graceful shutdown logs,
+8. create the `v0.1.28` tag only after the final release commit is known,
+9. publish and verify npm visibility.
+
+## Next milestone
+
+The planned next milestone is `0.1.29 — Developer Experience`, focused on generators, richer `doctor` / `inspect`, improved diagnostics and create-app workflow improvements.