@chidchanun/bcp 0.1.25 → 0.1.26

package/docs/storage.md

@@ -1,80 +1,87 @@
 # Storage and File Delivery
 
-BCP Framework `0.1.25` adds a server-only storage abstraction and production file-delivery helpers through `bcp/server`.
+BCP Framework `0.1.25` introduced the server-only `StorageAdapter` abstraction and production file-delivery helpers through `bcp/server`.
 
-The initial adapter is local filesystem storage. The `StorageAdapter` contract keeps application code independent from the local implementation so later object-storage adapters can implement the same surface.
+BCP Framework `0.1.26` completes the next storage milestone with:
 
-## Create local storage
+- additive streaming reads/writes,
+- capability discovery,
+- local streaming I/O,
+- S3-compatible storage,
+- production multipart-to-storage streaming,
+- streamed full/ranged file delivery.
+
+Existing adapters written for `0.1.25` remain valid because `putStream()` and `readStream()` are optional.
+
+## Local storage
 
 ```ts
 import {
     createLocalStorage,
 } from "bcp/server";
 
-export const uploads =
+export const storage =
     createLocalStorage({
         directory:
             "./uploads",
     });
 ```
 
-Storage keys are relative forward-slash paths:
+Storage keys are logical relative paths:
 
 ```text
 avatars/user-101.webp
 documents/2026/report.pdf
 ```
 
-Absolute paths, `.` / `..` traversal segments and BCP's reserved metadata directory are rejected.
+Absolute paths, traversal segments and BCP's reserved metadata directory are rejected.
 
-## Write and read objects
+## S3-compatible storage
 
 ```ts
-const stored =
-    await uploads.put(
-        "notes/hello.txt",
-        "Hello BCP",
-        {
-            contentType:
-                "text/plain",
-        }
-    );
+import {
+    createS3Storage,
+} from "bcp/server";
 
-const bytes =
-    await uploads.read(
-        stored.key
-    );
+export const storage =
+    createS3Storage({
+        bucket:
+            process.env.S3_BUCKET!,
+        region:
+            process.env.S3_REGION!,
+        endpoint:
+            process.env.S3_ENDPOINT,
+        accessKeyId:
+            process.env.S3_ACCESS_KEY_ID,
+        secretAccessKey:
+            process.env.S3_SECRET_ACCESS_KEY,
+    });
 ```
 
-`put()` does not overwrite an existing object unless `overwrite: true` is explicitly supplied.
-
-The local adapter stores metadata separately from the object bytes so content type and SHA-256 identity survive process restarts.
+The same application-facing `StorageAdapter` surface works with local or S3-compatible backends.
 
-Object metadata contains:
-
-```ts
-{
-    key,
-    size,
-    contentType,
-    lastModified,
-    etag,
-    checksumSha256,
-}
-```
-
-Objects created through the local adapter use a strong SHA-256 ETag.
+Read more: [S3-Compatible Storage](s3-storage.md).
 
 ## Storage adapter contract
 
 ```ts
 interface StorageAdapter {
+    capabilities?: Partial<
+        StorageAdapterCapabilities
+    >;
+
     put(
         key: string,
         value: StorageWriteValue,
         options?: StoragePutOptions
     ): Promise<StorageObjectMetadata>;
 
+    putStream?(
+        key: string,
+        stream: ReadableStream<Uint8Array>,
+        options?: StoragePutStreamOptions
+    ): Promise<StorageObjectMetadata>;
+
     stat(
         key: string
     ): Promise<StorageObjectMetadata | null>;
@@ -84,6 +91,11 @@ interface StorageAdapter {
         options?: StorageReadOptions
     ): Promise<Uint8Array>;
 
+    readStream?(
+        key: string,
+        options?: StorageReadOptions
+    ): Promise<StorageReadableStream>;
+
     exists(
         key: string
     ): Promise<boolean>;
@@ -94,173 +106,274 @@ interface StorageAdapter {
 }
 ```
 
-`read()` supports inclusive byte ranges through `start` and `end`.
-
-## Upload directly into storage
+The original buffered methods remain required. Streaming methods are additive optional capabilities.
 
-BCP 0.1.24's multipart parser and validation helpers remain unchanged. `0.1.25` adds `storeUploadedFile()` as the bridge into a storage adapter.
+## Capabilities
 
 ```ts
 import {
-    createLocalStorage,
-    parseMultipartFormData,
-    requireUploadedFile,
-    storeUploadedFile,
+    getStorageCapabilities,
 } from "bcp/server";
 
-const uploads =
-    createLocalStorage({
-        directory:
-            "./uploads",
-    });
-
-export async function POST(
-    request: Request
-) {
-    const formData =
-        await parseMultipartFormData(
-            request,
-            {
-                maxBytes:
-                    8 * 1024 * 1024,
-            }
-        );
-
-    const file =
-        requireUploadedFile(
-            formData,
-            "file",
-            {
-                maxBytes:
-                    5 * 1024 * 1024,
-                allowedTypes: [
-                    "image/png",
-                    "image/jpeg",
-                    "image/webp",
-                ],
-            }
-        );
-
-    const stored =
-        await storeUploadedFile(
-            file,
-            {
-                storage:
-                    uploads,
-                key:
-                    `avatars/${crypto.randomUUID()}.webp`,
-            }
-        );
-
-    return Response.json(
-        stored
+const capabilities =
+    getStorageCapabilities(
+        storage
     );
+```
+
+The capability model currently reports:
+
+```ts
+{
+    streamingRead,
+    streamingWrite,
+    ranges,
+    signedUrls,
+    listing,
 }
 ```
 
-If `key` is omitted, BCP creates a UUID-based storage key while preserving a sanitized extension.
+`createLocalStorage()` and `createS3Storage()` in `0.1.26` report:
+
+```ts
+{
+    streamingRead: true,
+    streamingWrite: true,
+    ranges: true,
+    signedUrls: false,
+    listing: false,
+}
+```
 
-## Deliver a stored file
+Signed URLs and listing are deferred to a later milestone.
 
-Use `createStorageResponse()` from a GET/HEAD API route:
+## Buffered writes
+
+```ts
+const stored =
+    await storage.put(
+        "notes/hello.txt",
+        "Hello BCP",
+        {
+            contentType:
+                "text/plain",
+        }
+    );
+```
+
+`put()` does not overwrite an existing object unless `overwrite: true` is supplied.
+
+Local storage persists content type and SHA-256 identity in sidecar metadata. Buffered S3 writes persist SHA-256 in S3 user metadata.
+
+## Streaming writes
+
+Use the generic helper so application code works with native or legacy adapters:
 
 ```ts
 import {
-    createLocalStorage,
-    createStorageResponse,
+    putStorageStream,
 } from "bcp/server";
 
-const uploads =
-    createLocalStorage({
-        directory:
-            "./uploads",
-    });
+await putStorageStream(
+    storage,
+    "imports/data.bin",
+    request.body!,
+    {
+        contentType:
+            "application/octet-stream",
+        maxBytes:
+            100 * 1024 * 1024,
+    }
+);
+```
 
-export function GET(
-    request: Request,
+When an adapter provides `putStream()`, BCP uses it. Legacy adapters fall back to collecting the stream and calling `put()`.
+
+The local adapter writes chunks directly to disk and calculates SHA-256 while streaming.
+
+The S3 adapter uses the AWS SDK multipart upload helper so streams whose final size is not known at the start can still be uploaded without buffering the complete object.
+
+### Size limits and abort
+
+```ts
+await putStorageStream(
+    storage,
+    key,
+    source,
     {
-        params,
-    }: {
-        params: {
-            key: string;
-        };
+        maxBytes:
+            50 * 1024 * 1024,
+        signal:
+            abortController.signal,
     }
-) {
-    return createStorageResponse(
-        request,
-        uploads,
-        params.key,
+);
+```
+
+If the stream exceeds `maxBytes`, BCP throws:
+
+```text
+StorageError
+code: STREAM_TOO_LARGE
+status: 413
+```
+
+Native adapters clean up/abort incomplete writes where supported.
+
+## Streaming reads
+
+```ts
+import {
+    readStorageStream,
+} from "bcp/server";
+
+const stream =
+    await readStorageStream(
+        storage,
+        "videos/demo.mp4"
+    );
+```
+
+Inclusive byte ranges are supported:
+
+```ts
+const stream =
+    await readStorageStream(
+        storage,
+        "videos/demo.mp4",
         {
-            cacheControl:
-                "private, max-age=3600",
+            start: 0,
+            end: 1023,
         }
     );
-}
 ```
 
-The response helper supports:
+Legacy adapters fall back to `read()` and expose the result as a stream.
 
-- `GET` and `HEAD`.
-- `Accept-Ranges: bytes`.
-- single byte ranges with `206 Partial Content`.
-- open-ended ranges such as `bytes=500-`.
-- suffix ranges such as `bytes=-500`.
-- `416 Range Not Satisfiable` for invalid/unsupported ranges.
-- `ETag` and `If-None-Match` validation.
-- `Last-Modified` and `If-Modified-Since` validation.
-- `If-Range` handling.
-- configurable `Cache-Control`.
-- safe `Content-Disposition` filenames.
+## Multipart uploads
 
-Multiple byte ranges are intentionally not supported in this milestone. They return `416` rather than generating a multipart range response.
-
-## Downloads
+Small forms can continue using the buffered `FormData` API:
 
 ```ts
-return createStorageResponse(
-    request,
-    uploads,
-    "reports/monthly.pdf",
+const formData =
+    await parseMultipartFormData(
+        request
+    );
+
+const file =
+    requireUploadedFile(
+        formData,
+        "file"
+    );
+
+await storeUploadedFile(
+    file,
     {
-        disposition:
-            "attachment",
-        downloadName:
-            "monthly-report.pdf",
+        storage,
     }
 );
 ```
 
-BCP strips path and control characters from the header filename and also emits an RFC 5987 UTF-8 filename parameter.
+For large production uploads, `0.1.26` adds direct multipart-to-storage streaming:
 
-## Cache defaults
-
-The default file response policy is conservative:
+```ts
+import {
+    storeMultipartFile,
+} from "bcp/server";
 
-```text
-Cache-Control: private, max-age=0, must-revalidate
+const stored =
+    await storeMultipartFile(
+        request,
+        {
+            storage,
+            fieldName:
+                "file",
+            key:
+                "documents/report.pdf",
+            maxBytes:
+                100 * 1024 * 1024,
+            constraints: {
+                maxBytes:
+                    80 * 1024 * 1024,
+                allowedTypes: [
+                    "application/pdf",
+                ],
+                allowedExtensions: [
+                    ".pdf",
+                ],
+            },
+        }
+    );
 ```
 
-Public immutable files must opt in explicitly, for example:
+The multipart parser and storage write operate concurrently, so the complete file is not converted to a `File` / `ArrayBuffer` first.
+
+Read more: [File Upload](file-upload.md).
+
+## File delivery
 
 ```ts
-{
-    cacheControl:
-        "public, max-age=31536000, immutable",
+import {
+    createStorageResponse,
+} from "bcp/server";
+
+export function GET(
+    request: Request
+) {
+    return createStorageResponse(
+        request,
+        storage,
+        "documents/report.pdf",
+        {
+            disposition:
+                "attachment",
+            downloadName:
+                "report.pdf",
+        }
+    );
 }
 ```
 
-Do not mark authorization-protected or user-private files as public.
+`createStorageResponse()` uses `readStorageStream()` and supports:
 
-## Errors
+- `GET` and `HEAD`,
+- `ETag` / `If-None-Match`,
+- `Last-Modified` / `If-Modified-Since`,
+- `If-Range`,
+- single byte ranges with `206 Partial Content`,
+- `304 Not Modified`,
+- `416 Range Not Satisfiable`,
+- safe `Content-Disposition` filenames,
+- configurable cache control.
+
+The default cache policy is:
+
+```text
+Cache-Control: private, max-age=0, must-revalidate
+```
 
-Storage operations throw `StorageError` with a stable code and HTTP-oriented status:
+Public immutable caching must be enabled explicitly.
+
+Multiple byte ranges are intentionally unsupported in `0.1.26`.
+
+## Object metadata
 
 ```ts
-import {
-    StorageError,
-} from "bcp/server";
+interface StorageObjectMetadata {
+    key: string;
+    size: number;
+    contentType: string;
+    lastModified: Date;
+    etag: string;
+    checksumSha256?: string;
+}
 ```
 
+`checksumSha256` is optional because not every cloud provider exposes a portable whole-object SHA-256 value for multipart objects.
+
+Do not assume an S3 ETag is an MD5 hash.
+
+## Storage errors
+
 Current codes:
 
 ```text
@@ -268,18 +381,21 @@ INVALID_KEY
 OBJECT_NOT_FOUND
 OBJECT_EXISTS
 RANGE_NOT_SATISFIABLE
+STREAM_TOO_LARGE
 ```
 
-`createStorageResponse()` converts ordinary missing objects and invalid HTTP ranges into `404` / `416` responses directly.
-
 ## Security boundary
 
-Storage keys are not authorization. Always perform authentication/authorization before passing a user-selected key to the storage layer.
+Storage keys are not authorization. Authenticate and authorize requests before allowing access to user-selected keys.
 
-The local adapter prevents traversal outside its configured directory, but applications are still responsible for deciding which authenticated user can read, overwrite or delete each logical object.
+MIME type and extension checks are metadata validation, not file-signature verification.
 
-MIME types are metadata and are not file-signature verification. Continue validating upload content when the threat model requires it.
+Streaming limits do not replace the framework/proxy request body limit. Configure `server.bodyLimit` / `BCP_BODY_LIMIT` large enough for intended uploads while keeping an explicit outer request boundary.
 
-## Adapter scope
+For S3/object storage:
 
-BCP 0.1.25 ships only `createLocalStorage()` as a built-in adapter. S3-compatible/cloud adapters are expected to implement `StorageAdapter` without changing application upload and delivery code.
+- keep credentials server-only,
+- prefer private buckets,
+- scope IAM/provider permissions,
+- use provider-side encryption/retention policies where required,
+- validate provider CORS only when direct browser access is intentionally enabled.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -55,7 +55,7 @@
     "./database": {
       "types": "./packages/client/src/database.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",
-      "default": "./packages/client/src/database.ts"
+      "default": "./packages/client/src/database.mjs"
     },
     "./auth": {
       "types": "./packages/client/src/auth.ts",
@@ -79,9 +79,12 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1119.0",
+    "@aws-sdk/lib-storage": "^3.1119.0",
     "@babel/core": "^8.0.1",
     "@babel/preset-react": "^8.0.1",
     "@babel/preset-typescript": "^8.0.1",
+    "busboy": "^1.6.0",
     "chokidar": "^5.0.0",
     "esbuild": "^0.28.2",
     "react-refresh": "^0.18.0",