@chidchanun/bcp 0.1.23 → 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.23",
+  "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/bundler/src/server-production-actions.ts

@@ -131,6 +131,11 @@ export async function buildProductionActions(
             frameworkDirectory,
             "../../client/src/server.ts"
         );
+    const frameworkAuthEntry =
+        path.resolve(
+            frameworkDirectory,
+            "../../client/src/auth.ts"
+        );
     const frameworkServerOnlyEntry =
         path.resolve(
             frameworkDirectory,
@@ -187,6 +192,16 @@ export async function buildProductionActions(
                                     frameworkServerEntry,
                             })
                         );
+                        buildApi.onResolve(
+                            {
+                                filter:
+                                    /^bcp\/auth$/,
+                            },
+                            () => ({
+                                path:
+                                    frameworkAuthEntry,
+                            })
+                        );
                         buildApi.onResolve(
                             {
                                 filter:

package/packages/bundler/src/server-production-guards.ts

@@ -118,6 +118,11 @@ export async function buildProductionGuards(
             frameworkDirectory,
             "../../client/src/server.ts"
         );
+    const frameworkAuthEntry =
+        path.resolve(
+            frameworkDirectory,
+            "../../client/src/auth.ts"
+        );
     const frameworkServerOnlyEntry =
         path.resolve(
             frameworkDirectory,
@@ -174,6 +179,16 @@ export async function buildProductionGuards(
                                     frameworkServerEntry,
                             })
                         );
+                        buildApi.onResolve(
+                            {
+                                filter:
+                                    /^bcp\/auth$/,
+                            },
+                            () => ({
+                                path:
+                                    frameworkAuthEntry,
+                            })
+                        );
                         buildApi.onResolve(
                             {
                                 filter:

package/packages/client/src/server.ts

@@ -30,6 +30,46 @@ export {
     type LoggerOptions,
 } from "../../server/src/logger.js";
 
+export {
+    getUploadedFile,
+    parseMultipartFormData,
+    requireUploadedFile,
+    sanitizeUploadFileName,
+    saveUploadedFile,
+    UploadError,
+    validateUploadedFile,
+
+    type MultipartUploadOptions,
+    type SaveUploadedFileOptions,
+    type SavedUploadedFile,
+    type UploadConstraints,
+    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,

package/packages/server/src/dev-route-graph.ts

@@ -0,0 +1,91 @@
+export interface DevRouteGraphEntry {
+    pathname: string;
+    filePath: string;
+    layouts: string[];
+}
+
+export function hasDevClientRouteGraphChanged(
+    currentRoutes: DevRouteGraphEntry[],
+    nextRoutes: DevRouteGraphEntry[]
+): boolean {
+    if (
+        currentRoutes.length !==
+        nextRoutes.length
+    ) {
+        return true;
+    }
+
+    const current =
+        normalizeRouteGraph(
+            currentRoutes
+        );
+    const next =
+        normalizeRouteGraph(
+            nextRoutes
+        );
+
+    for (
+        let index = 0;
+        index < current.length;
+        index++
+    ) {
+        const left =
+            current[index];
+        const right =
+            next[index];
+
+        if (
+            left.pathname !==
+                right.pathname ||
+            left.filePath !==
+                right.filePath ||
+            left.layouts.length !==
+                right.layouts.length
+        ) {
+            return true;
+        }
+
+        for (
+            let layoutIndex = 0;
+            layoutIndex <
+                left.layouts.length;
+            layoutIndex++
+        ) {
+            if (
+                left.layouts[
+                    layoutIndex
+                ] !==
+                right.layouts[
+                    layoutIndex
+                ]
+            ) {
+                return true;
+            }
+        }
+    }
+
+    return false;
+}
+
+function normalizeRouteGraph(
+    routes: DevRouteGraphEntry[]
+): DevRouteGraphEntry[] {
+    return routes
+        .map(
+            (route) => ({
+                pathname:
+                    route.pathname,
+                filePath:
+                    route.filePath,
+                layouts: [
+                    ...route.layouts,
+                ],
+            })
+        )
+        .sort(
+            (left, right) =>
+                left.pathname.localeCompare(
+                    right.pathname
+                )
+        );
+}