@chidchanun/bcp 0.1.26 → 0.1.27

package/docs/storage-ecosystem.md

@@ -0,0 +1,434 @@
+# Storage Ecosystem
+
+BCP Framework `0.1.27` expands the `0.1.25` storage abstraction and `0.1.26` streaming/cloud work into a broader object-storage ecosystem.
+
+> Version target: `0.1.27` unreleased development target until RC validation and publication complete.
+
+The public APIs are available through `bcp/server`.
+
+## Capabilities
+
+Use `getStorageEcosystemCapabilities()` when code needs to select an optimized path:
+
+```ts
+import {
+    getStorageEcosystemCapabilities,
+} from "bcp/server";
+
+const capabilities =
+    getStorageEcosystemCapabilities(
+        storage
+    );
+```
+
+The result includes the original storage capabilities plus the `0.1.27` ecosystem surface:
+
+```ts
+{
+    streamingRead: boolean;
+    streamingWrite: boolean;
+    ranges: boolean;
+    signedUrls: boolean;
+    listing: boolean;
+    signedReadUrls: boolean;
+    signedWriteUrls: boolean;
+    copy: boolean;
+    move: boolean;
+    metadata: boolean;
+    bulkDelete: boolean;
+}
+```
+
+Built-in local storage supports listing, copy, move, metadata and bulk deletion. It intentionally does not provide signed URLs.
+
+Built-in S3-compatible storage supports the complete capability set.
+
+## List objects
+
+```ts
+import {
+    listStorageObjects,
+} from "bcp/server";
+
+const page =
+    await listStorageObjects(
+        storage,
+        {
+            prefix:
+                "documents/",
+            limit:
+                50,
+        }
+    );
+```
+
+Result:
+
+```ts
+{
+    objects: StorageObjectMetadata[];
+    cursor?: string;
+}
+```
+
+Use the cursor returned by the previous page:
+
+```ts
+const next =
+    await listStorageObjects(
+        storage,
+        {
+            prefix:
+                "documents/",
+            limit:
+                50,
+            cursor:
+                page.cursor,
+        }
+    );
+```
+
+Cursors are opaque provider/application tokens. Do not decode them or persist assumptions about their internal format.
+
+`limit` defaults to `100` and accepts values from `1` through `1000`.
+
+### Prefix behavior
+
+Both of these are valid:
+
+```ts
+prefix: "documents"
+prefix: "documents/"
+```
+
+A trailing slash is preserved when supplied, which is useful when application keys are organized as logical folders.
+
+Storage listing is not a filesystem directory API. Keys remain object keys, and consumers should not infer authorization from prefixes.
+
+## Copy objects
+
+```ts
+import {
+    copyStorageObject,
+} from "bcp/server";
+
+const copied =
+    await copyStorageObject(
+        storage,
+        "incoming/report.pdf",
+        "archive/report.pdf"
+    );
+```
+
+By default an existing destination is rejected with `StorageError` code `OBJECT_EXISTS`.
+
+Intentional replacement must opt in:
+
+```ts
+await copyStorageObject(
+    storage,
+    source,
+    destination,
+    {
+        overwrite:
+            true,
+    }
+);
+```
+
+S3-compatible storage uses native `CopyObject`.
+
+When a custom adapter does not expose a native `copy()` method, the helper can fall back to streamed read/write copy using the existing `StorageAdapter` APIs.
+
+If the adapter supports user metadata, the compatibility copy path preserves it.
+
+## Move objects
+
+```ts
+import {
+    moveStorageObject,
+} from "bcp/server";
+
+await moveStorageObject(
+    storage,
+    "tmp/avatar.webp",
+    "users/42/avatar.webp"
+);
+```
+
+A move is implemented as a successful copy followed by deletion of the source.
+
+This has an important distributed-storage implication: copy and delete are not one atomic transaction across generic object stores. If the delete fails after the copy succeeds, both source and destination can temporarily exist.
+
+Application workflows that need stronger business-level atomicity should coordinate the move with database state rather than assuming the storage operation is transactional.
+
+## User metadata
+
+Portable application metadata is represented as:
+
+```ts
+Record<string, string>
+```
+
+Store metadata with an object:
+
+```ts
+const stored =
+    await storage.put(
+        "documents/report.pdf",
+        bytes,
+        {
+            contentType:
+                "application/pdf",
+            metadata: {
+                owner:
+                    "user-42",
+                category:
+                    "report",
+            },
+        }
+    );
+```
+
+The same option is available on the ecosystem `putStream()` contract.
+
+Read metadata independently:
+
+```ts
+import {
+    getStorageMetadata,
+} from "bcp/server";
+
+const metadata =
+    await getStorageMetadata(
+        storage,
+        stored.key
+    );
+```
+
+Replace it:
+
+```ts
+import {
+    setStorageMetadata,
+} from "bcp/server";
+
+await setStorageMetadata(
+    storage,
+    stored.key,
+    {
+        owner:
+            "user-42",
+        status:
+            "approved",
+    }
+);
+```
+
+`setStorageMetadata()` replaces the application metadata map rather than merging it.
+
+### Metadata rules
+
+BCP normalizes metadata keys to lowercase.
+
+Keys must use a portable subset:
+
+```text
+letters
+numbers
+underscore
+hyphen
+dot
+```
+
+The framework reserves:
+
+```text
+bcp_sha256
+```
+
+for internal checksum metadata.
+
+Metadata values must be strings and cannot contain CR/LF or NUL characters.
+
+Metadata is useful for lightweight object context, but it should not replace application authorization or relational data that needs querying/transactions.
+
+## Local metadata implementation
+
+Local storage keeps BCP-internal and application metadata under the existing reserved metadata directory rather than mixing it with user-visible object keys.
+
+The reserved directory is excluded from object listings.
+
+Deleting or replacing an object also clears or replaces its application metadata as appropriate.
+
+## S3 metadata implementation
+
+S3-compatible storage maps application metadata to S3 user metadata.
+
+BCP preserves its internal `bcp_sha256` metadata when application metadata is replaced.
+
+Updating S3 object metadata uses S3's copy-to-self metadata replacement behavior. This means metadata mutation is a provider object operation, not merely a local in-memory change.
+
+## Bulk deletion
+
+```ts
+import {
+    deleteStorageObjects,
+} from "bcp/server";
+
+const result =
+    await deleteStorageObjects(
+        storage,
+        [
+            "tmp/a.bin",
+            "tmp/b.bin",
+            "tmp/c.bin",
+        ]
+    );
+```
+
+Result:
+
+```ts
+{
+    deleted: string[];
+    missing: string[];
+    failed: Array<{
+        key: string;
+        message: string;
+    }>;
+}
+```
+
+Duplicate input keys are normalized to one deletion request.
+
+Local/custom fallback deletion can distinguish missing keys.
+
+S3's delete-object semantics treat a delete for a missing key as successful, so S3-compatible bulk deletion normally reports those keys as `deleted` rather than `missing`.
+
+S3 requests are batched to the provider's 1000-object multi-delete limit.
+
+## Signed read URLs
+
+Signed URLs are intended primarily for object-storage adapters such as S3/R2/MinIO.
+
+```ts
+import {
+    createStorageSignedReadUrl,
+} from "bcp/server";
+
+const url =
+    await createStorageSignedReadUrl(
+        storage,
+        "videos/demo.mp4",
+        {
+            expiresIn:
+                5 * 60,
+        }
+    );
+```
+
+The URL lets a client fetch the object directly from the object-storage endpoint for the configured lifetime.
+
+BCP defaults to 15 minutes and accepts an expiry from 1 second through 7 days.
+
+## Signed write URLs
+
+```ts
+import {
+    createStorageSignedWriteUrl,
+} from "bcp/server";
+
+const url =
+    await createStorageSignedWriteUrl(
+        storage,
+        "uploads/video.mp4",
+        {
+            expiresIn:
+                5 * 60,
+            contentType:
+                "video/mp4",
+            metadata: {
+                owner:
+                    "user-42",
+            },
+        }
+    );
+```
+
+A common direct-upload flow is:
+
+```text
+Browser
+  ↓ request upload authorization
+BCP application
+  ↓ returns short-lived signed URL
+Browser
+  ↓ PUT bytes directly
+S3 / R2 / MinIO
+```
+
+This avoids proxying very large file bytes through the BCP application server.
+
+If the signed request includes content type or metadata headers, the direct uploader must send the corresponding headers required by the generated signature/provider behavior.
+
+## Signed URL security
+
+A signed URL is a temporary credential. Anyone who obtains a valid URL can normally perform the signed operation until it expires.
+
+Recommended practices:
+
+- generate signed URLs only after authorization,
+- use short expirations,
+- choose server-generated object keys instead of trusting arbitrary client paths,
+- limit the signed operation to one object/action,
+- do not log full signed URLs when query strings contain credentials,
+- keep buckets private by default,
+- configure bucket CORS only for intended browser origins/methods,
+- persist upload ownership in application data before or immediately after issuing upload authorization.
+
+## Unsupported operations
+
+A helper that requires an adapter capability which cannot be provided generically throws `StorageEcosystemError`:
+
+```text
+code: UNSUPPORTED_OPERATION
+status: 501
+```
+
+For example, local filesystem storage does not fabricate a signed URL API.
+
+Other ecosystem validation errors include:
+
+```text
+INVALID_CURSOR
+INVALID_METADATA
+```
+
+## Compatibility model
+
+`StorageAdapter` itself remains the stable minimum contract from earlier releases.
+
+`StorageEcosystemAdapter` layers optional capabilities on top of it. This allows older custom adapters to continue compiling while applications gradually adopt richer operations.
+
+Prefer the public helper functions when code should work across adapters:
+
+```text
+listStorageObjects
+copyStorageObject
+moveStorageObject
+deleteStorageObjects
+getStorageMetadata
+setStorageMetadata
+createStorageSignedReadUrl
+createStorageSignedWriteUrl
+```
+
+Using the helpers also gives the framework a place to provide compatibility fallbacks when an operation can be implemented safely through the base adapter contract.
+
+## Related documentation
+
+- [Storage and File Delivery](storage.md)
+- [S3-Compatible Storage](s3-storage.md)
+- [File Upload](file-upload.md)
+- [BCP Framework 0.1.27](releases/0.1.27.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "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",
@@ -81,6 +81,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1119.0",
     "@aws-sdk/lib-storage": "^3.1119.0",
+    "@aws-sdk/s3-request-presigner": "^3.1121.0",
     "@babel/core": "^8.0.1",
     "@babel/preset-react": "^8.0.1",
     "@babel/preset-typescript": "^8.0.1",

package/packages/client/src/server.ts

@@ -55,7 +55,6 @@ export {
 } from "../../server/src/upload-stream.js";
 
 export {
-    createLocalStorage,
     getStorageCapabilities,
     normalizeStorageKey,
     putStorageStream,
@@ -78,13 +77,45 @@ export {
 } from "../../server/src/storage.js";
 
 export {
-    createS3Storage,
+    copyStorageObject,
+    createLocalStorage,
+    createStorageSignedReadUrl,
+    createStorageSignedWriteUrl,
+    deleteStorageObjects,
+    getStorageEcosystemCapabilities,
+    getStorageMetadata,
+    listStorageObjects,
+    moveStorageObject,
+    setStorageMetadata,
+    StorageEcosystemError,
+
+    type StorageCopyOptions,
+    type StorageDeleteManyFailure,
+    type StorageDeleteManyResult,
+    type StorageEcosystemAdapter,
+    type StorageEcosystemCapabilities,
+    type StorageEcosystemErrorCode,
+    type StorageEcosystemPutOptions,
+    type StorageEcosystemPutStreamOptions,
+    type StorageListOptions,
+    type StorageListResult,
+    type StorageSignedUrlOptions,
+    type StorageSignedWriteUrlOptions,
+    type StorageUserMetadata,
+} from "../../server/src/storage-ecosystem.js";
 
+export {
     type S3StorageAdapter,
     type S3StorageMultipartOptions,
     type S3StorageOptions,
 } from "../../server/src/storage-s3.js";
 
+export {
+    createS3Storage,
+
+    type S3StorageEcosystemAdapter,
+} from "../../server/src/storage-s3-ecosystem.js";
+
 export {
     createStorageResponse,
     isStorageRangeError,