@chidchanun/bcp 0.1.24 → 0.1.25

package/docs/storage.md

@@ -0,0 +1,285 @@
+# Storage and File Delivery
+
+BCP Framework `0.1.25` adds a server-only storage 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.
+
+## Create local storage
+
+```ts
+import {
+    createLocalStorage,
+} from "bcp/server";
+
+export const uploads =
+    createLocalStorage({
+        directory:
+            "./uploads",
+    });
+```
+
+Storage keys are relative forward-slash paths:
+
+```text
+avatars/user-101.webp
+documents/2026/report.pdf
+```
+
+Absolute paths, `.` / `..` traversal segments and BCP's reserved metadata directory are rejected.
+
+## Write and read objects
+
+```ts
+const stored =
+    await uploads.put(
+        "notes/hello.txt",
+        "Hello BCP",
+        {
+            contentType:
+                "text/plain",
+        }
+    );
+
+const bytes =
+    await uploads.read(
+        stored.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.
+
+Object metadata contains:
+
+```ts
+{
+    key,
+    size,
+    contentType,
+    lastModified,
+    etag,
+    checksumSha256,
+}
+```
+
+Objects created through the local adapter use a strong SHA-256 ETag.
+
+## Storage adapter contract
+
+```ts
+interface StorageAdapter {
+    put(
+        key: string,
+        value: StorageWriteValue,
+        options?: StoragePutOptions
+    ): Promise<StorageObjectMetadata>;
+
+    stat(
+        key: string
+    ): Promise<StorageObjectMetadata | null>;
+
+    read(
+        key: string,
+        options?: StorageReadOptions
+    ): Promise<Uint8Array>;
+
+    exists(
+        key: string
+    ): Promise<boolean>;
+
+    delete(
+        key: string
+    ): Promise<boolean>;
+}
+```
+
+`read()` supports inclusive byte ranges through `start` and `end`.
+
+## Upload directly into storage
+
+BCP 0.1.24's multipart parser and validation helpers remain unchanged. `0.1.25` adds `storeUploadedFile()` as the bridge into a storage adapter.
+
+```ts
+import {
+    createLocalStorage,
+    parseMultipartFormData,
+    requireUploadedFile,
+    storeUploadedFile,
+} 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
+    );
+}
+```
+
+If `key` is omitted, BCP creates a UUID-based storage key while preserving a sanitized extension.
+
+## Deliver a stored file
+
+Use `createStorageResponse()` from a GET/HEAD API route:
+
+```ts
+import {
+    createLocalStorage,
+    createStorageResponse,
+} from "bcp/server";
+
+const uploads =
+    createLocalStorage({
+        directory:
+            "./uploads",
+    });
+
+export function GET(
+    request: Request,
+    {
+        params,
+    }: {
+        params: {
+            key: string;
+        };
+    }
+) {
+    return createStorageResponse(
+        request,
+        uploads,
+        params.key,
+        {
+            cacheControl:
+                "private, max-age=3600",
+        }
+    );
+}
+```
+
+The response helper supports:
+
+- `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.
+
+Multiple byte ranges are intentionally not supported in this milestone. They return `416` rather than generating a multipart range response.
+
+## Downloads
+
+```ts
+return createStorageResponse(
+    request,
+    uploads,
+    "reports/monthly.pdf",
+    {
+        disposition:
+            "attachment",
+        downloadName:
+            "monthly-report.pdf",
+    }
+);
+```
+
+BCP strips path and control characters from the header filename and also emits an RFC 5987 UTF-8 filename parameter.
+
+## Cache defaults
+
+The default file response policy is conservative:
+
+```text
+Cache-Control: private, max-age=0, must-revalidate
+```
+
+Public immutable files must opt in explicitly, for example:
+
+```ts
+{
+    cacheControl:
+        "public, max-age=31536000, immutable",
+}
+```
+
+Do not mark authorization-protected or user-private files as public.
+
+## Errors
+
+Storage operations throw `StorageError` with a stable code and HTTP-oriented status:
+
+```ts
+import {
+    StorageError,
+} from "bcp/server";
+```
+
+Current codes:
+
+```text
+INVALID_KEY
+OBJECT_NOT_FOUND
+OBJECT_EXISTS
+RANGE_NOT_SATISFIABLE
+```
+
+`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.
+
+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 types are metadata and are not file-signature verification. Continue validating upload content when the threat model requires it.
+
+## Adapter scope
+
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "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",

package/packages/client/src/server.ts

@@ -46,6 +46,30 @@ export {
     type UploadErrorCode,
 } from "../../server/src/upload.js";
 
+export {
+    createLocalStorage,
+    normalizeStorageKey,
+    StorageError,
+    storeUploadedFile,
+
+    type LocalStorageOptions,
+    type StorageAdapter,
+    type StorageErrorCode,
+    type StorageObjectMetadata,
+    type StoragePutOptions,
+    type StorageReadOptions,
+    type StorageWriteValue,
+    type StoredUploadedObject,
+    type StoreUploadedFileOptions,
+} from "../../server/src/storage.js";
+
+export {
+    createStorageResponse,
+    isStorageRangeError,
+
+    type StorageResponseOptions,
+} from "../../server/src/file-delivery.js";
+
 export {
     json,
     redirect,