@spfn/core 0.3.0-beta.4 → 0.3.0-beta.6

package/docs/file-upload.md

@@ -1,6 +1,13 @@
 # File Upload
 
-Complete guide for handling file uploads in SPFN applications.
+SPFN provides `FileSchema()` and `FileArraySchema()` for type-safe file uploads within [route definitions](../src/route/README.md). Files are received as standard `File` objects through `formData` input.
+
+> **They are functions — always call them.** `file: FileSchema()` is correct;
+> `file: FileSchema` passes the function reference and produces an invalid schema. The
+> same goes for `FileArraySchema()` and `OptionalFileSchema()`.
+>
+> `body` and `formData` are also mutually exclusive at runtime: the request's
+> `Content-Type` decides which one is parsed. A multipart request never populates `body`.
 
 ## Basic Usage
 
@@ -15,8 +22,8 @@ export const uploadAvatar = route.post('/users/:id/avatar')
         params: Type.Object({ id: Type.String() }),
         formData: Type.Object({
             file: FileSchema(),
-            description: Type.Optional(Type.String())
-        })
+            description: Type.Optional(Type.String()),
+        }),
     })
     .handler(async (c) =>
     {
@@ -30,7 +37,6 @@ export const uploadAvatar = route.post('/users/:id/avatar')
 
         // Read file content
         const buffer = await file.arrayBuffer();
-        const text = await file.text();  // for text files
 
         return c.created({ filename: file.name, size: file.size });
     });
@@ -45,8 +51,8 @@ export const uploadDocuments = route.post('/documents')
     .input({
         formData: Type.Object({
             files: FileArraySchema(),
-            category: Type.String()
-        })
+            category: Type.String(),
+        }),
     })
     .handler(async (c) =>
     {
@@ -57,7 +63,6 @@ export const uploadDocuments = route.post('/documents')
             files.map(async (file) =>
             {
                 const buffer = await file.arrayBuffer();
-                // Process each file...
                 return { name: file.name, size: file.size };
             })
         );
@@ -66,45 +71,44 @@ export const uploadDocuments = route.post('/documents')
     });
 ```
 
-### Mixed Fields
+### Mixed Fields (File + Text)
 
 ```typescript
+import { route, FileSchema } from '@spfn/core/route';
+
 export const createPost = route.post('/posts')
     .input({
         formData: Type.Object({
             title: Type.String(),
             content: Type.String(),
-            image: OptionalFileSchema(),
-            tags: Type.Optional(Type.String())  // JSON string
-        })
+            image: FileSchema(),
+            tags: Type.Optional(Type.String()),  // JSON string
+        }),
     })
     .handler(async (c) =>
     {
         const { formData } = await c.data();
-        const image = formData.image as File | undefined;
+        const image = formData.image as File;
 
         const post = await postRepo.create({
             title: formData.title,
             content: formData.content,
             tags: formData.tags ? JSON.parse(formData.tags) : [],
-            imageUrl: image ? await saveFile(image) : null
+            imageUrl: await saveFile(image),
         });
 
         return c.created(post);
     });
 ```
 
----
-
 ## Validation
 
 ### Declarative Validation (Recommended)
 
-Use schema options for automatic validation:
+Pass validation options directly to the schema for automatic enforcement:
 
 ```typescript
 import { route, FileSchema, FileArraySchema } from '@spfn/core/route';
-import { Type } from '@sinclair/typebox';
 
 // Single file with size and type constraints
 export const uploadAvatar = route.post('/avatars')
@@ -112,9 +116,9 @@ export const uploadAvatar = route.post('/avatars')
         formData: Type.Object({
             avatar: FileSchema({
                 maxSize: 5 * 1024 * 1024,  // 5MB
-                allowedTypes: ['image/jpeg', 'image/png', 'image/webp']
-            })
-        })
+                allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],
+            }),
+        }),
     })
     .handler(async (c) =>
     {
@@ -132,9 +136,9 @@ export const uploadDocuments = route.post('/documents')
                 maxFiles: 5,
                 minFiles: 1,
                 maxSize: 10 * 1024 * 1024,  // 10MB per file
-                allowedTypes: ['application/pdf', 'application/msword']
-            })
-        })
+                allowedTypes: ['application/pdf', 'application/msword'],
+            }),
+        }),
     })
     .handler(async (c) =>
     {
@@ -144,20 +148,11 @@ export const uploadDocuments = route.post('/documents')
     });
 ```
 
-**Available Options:**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `maxSize` | number | Maximum file size in bytes |
-| `minSize` | number | Minimum file size in bytes |
-| `allowedTypes` | string[] | Allowed MIME types |
-| `maxFiles` | number | Maximum file count (FileArraySchema only) |
-| `minFiles` | number | Minimum file count (FileArraySchema only) |
-
-Validation errors are thrown automatically with 400 status code and structured error response:
+Validation errors are thrown automatically with a 400 status:
 
 ```json
 {
+    "__type": "ValidationError",
     "message": "Invalid form data",
     "fields": [
         {
@@ -165,13 +160,36 @@ Validation errors are thrown automatically with 400 status code and structured e
             "message": "File size 15.0MB exceeds maximum 5.0MB",
             "value": 15728640
         }
-    ]
+    ],
+    "error": {
+        "code": "ValidationError",
+        "message": "Invalid form data",
+        "requestId": "req_1754380000000_9f2c1ab4e7d0"
+    }
 }
 ```
 
----
+Every error body carries `__type` (what the web client restores an error class from) and
+an `error` envelope with `code` / `message` / `requestId` (what a client in another
+language classifies on). For a file-array field the `path` includes the index —
+`/files/2` for the third file, `/files` for a count violation (`maxFiles` / `minFiles`).
+
+> **A missing file field is not a validation error.** Validation walks the fields the
+> request actually sent, so a `FileSchema()` field the client omitted produces no error —
+> the handler just receives `undefined`. `formData.avatar as File` is a cast, not a
+> guarantee. Check for the file yourself before using it.
 
-### Manual Validation (Advanced)
+### Validation Options
+
+| Option | Type | Applies To | Description |
+|--------|------|------------|-------------|
+| `maxSize` | number | Both | Maximum file size in bytes |
+| `minSize` | number | Both | Minimum file size in bytes |
+| `allowedTypes` | string[] | Both | Allowed MIME types |
+| `maxFiles` | number | FileArraySchema | Maximum file count |
+| `minFiles` | number | FileArraySchema | Minimum file count |
+
+### Manual Validation
 
 For custom validation logic, validate in the handler:
 
@@ -183,15 +201,14 @@ const ALLOWED_IMAGE_TYPES = ['image/jpeg', 'image/png', 'image/webp', 'image/gif
 export const uploadImage = route.post('/images')
     .input({
         formData: Type.Object({
-            image: FileSchema()
-        })
+            image: FileSchema(),
+        }),
     })
     .handler(async (c) =>
     {
         const { formData } = await c.data();
         const file = formData.image as File;
 
-        // Custom validation logic
         if (!ALLOWED_IMAGE_TYPES.includes(file.type))
         {
             throw new ValidationError({
@@ -199,8 +216,8 @@ export const uploadImage = route.post('/images')
                 fields: [{
                     path: '/image',
                     message: `Allowed types: ${ALLOWED_IMAGE_TYPES.join(', ')}`,
-                    value: file.type
-                }]
+                    value: file.type,
+                }],
             });
         }
 
@@ -208,116 +225,75 @@ export const uploadImage = route.post('/images')
     });
 ```
 
-### File Size Validation
-
-```typescript
-const MAX_FILE_SIZE = 10 * 1024 * 1024;  // 10MB
-
-export const uploadFile = route.post('/files')
-    .input({
-        formData: Type.Object({
-            file: FileSchema()
-        })
-    })
-    .handler(async (c) =>
-    {
-        const { formData } = await c.data();
-        const file = formData.file as File;
-
-        if (file.size > MAX_FILE_SIZE)
-        {
-            throw new ValidationError({
-                message: 'File too large',
-                fields: [{
-                    path: '/file',
-                    message: `Maximum size: ${MAX_FILE_SIZE / 1024 / 1024}MB`,
-                    value: file.size
-                }]
-            });
-        }
+## Storage Patterns
 
-        // Process file...
-    });
-```
+### `@spfn/storage` (recommended)
 
-### Reusable Validation Helper
+SPFN ships provider-agnostic object storage — S3-compatible services (S3, R2, MinIO,
+Wasabi), Google Cloud Storage, and the local filesystem behind one interface. Prefer it
+over calling a provider SDK directly: every object operation validates its key before it
+reaches the provider (rejecting `..` segments, leading `/`, backslashes, control
+characters and URLs), so a key built from user input cannot escape its prefix.
 
 ```typescript
-// lib/file-validation.ts
-import { ValidationError } from '@spfn/core/errors';
+import { getStorageService, randomKey } from '@spfn/storage/server';
 
-interface FileValidationOptions
+async function saveUpload(file: File): Promise<string>
 {
-    maxSize?: number;
-    allowedTypes?: string[];
-    required?: boolean;
+    const storage = await getStorageService();
+    const key = randomKey('public/uploads', file.name.split('.').pop() || 'bin');
+
+    await storage.upload(key, Buffer.from(await file.arrayBuffer()), file.type);
+
+    return storage.getPublicUrl(key);
 }
+```
 
-export function validateFile(
-    file: File | undefined,
-    fieldName: string,
-    options: FileValidationOptions = {}
-): void
-{
-    const { maxSize, allowedTypes, required = true } = options;
+The provider comes from `STORAGE_PROVIDER` (`local` / `s3` / `gcs`), defaulting to `local`
+in development and `s3` in production. Private objects are read back with
+`storage.getDownloadUrl(key)` (a presigned GET) or `storage.getStream(key)`.
 
-    if (!file)
-    {
-        if (required)
-        {
-            throw new ValidationError({
-                message: 'File required',
-                fields: [{ path: `/${fieldName}`, message: 'File is required', value: null }]
-            });
-        }
-        return;
-    }
+A `public/` key prefix is meaningful **on GCS only**, where it routes the object to the
+public bucket instead of the private one. On S3-compatible providers and local there is a
+single bucket, and `getPublicUrl()` just prepends the configured public base URL to any
+key — the prefix is a convention you must back with your own bucket policy.
 
-    if (maxSize && file.size > maxSize)
-    {
-        throw new ValidationError({
-            message: 'File too large',
-            fields: [{
-                path: `/${fieldName}`,
-                message: `Maximum size: ${(maxSize / 1024 / 1024).toFixed(1)}MB`,
-                value: file.size
-            }]
-        });
-    }
+### Presigned upload (large files)
 
-    if (allowedTypes && !allowedTypes.includes(file.type))
-    {
-        throw new ValidationError({
-            message: 'Invalid file type',
-            fields: [{
-                path: `/${fieldName}`,
-                message: `Allowed types: ${allowedTypes.join(', ')}`,
-                value: file.type
-            }]
-        });
-    }
-}
+For large files, don't route the bytes through your API process at all — sign an upload,
+let the browser `PUT` straight to the returned `uploadUrl`, then confirm it:
 
-// Usage
-export const uploadImage = route.post('/images')
-    .input({ formData: Type.Object({ image: FileSchema() }) })
-    .handler(async (c) =>
-    {
-        const { formData } = await c.data();
-        const file = formData.image as File;
+```typescript
+const { uploadUrl, requiredHeaders } = await storage.getUploadUrl({
+    key,
+    contentType: 'image/webp',
+    contentLength: exactSize,   // signed on both S3 and GCS
+    temp: true,                 // unconfirmed until finalized
+});
 
-        validateFile(file, 'image', {
-            maxSize: 5 * 1024 * 1024,
-            allowedTypes: ['image/jpeg', 'image/png', 'image/webp']
-        });
+// browser PUTs to uploadUrl, sending every requiredHeaders entry verbatim
 
-        // File is valid...
-    });
+await storage.finalizeObject(key);
 ```
 
----
+Three constraints decide whether this is safe:
 
-## Storage Patterns
+| Constraint | Behaviour |
+|---|---|
+| `contentLength` (exact size) | Signed on **both** S3-compatible and GCS. A mismatched size fails. |
+| `maxBytes` (upper bound) | Enforced on **GCS only**. A presigned PUT cannot sign a size range, so S3, R2, MinIO and Wasabi **ignore it silently**. |
+| Local filesystem provider | Presigned upload is **not supported** — `getUploadUrl()` throws. Use the direct `upload()` path in local dev. |
+
+A client can declare one size and send another, so a server-side check of a
+client-declared size binds nothing. If you only know an upper bound and must enforce it on
+S3, verify the size after upload.
+
+`temp: true` marks the upload unconfirmed so abandoned uploads don't accumulate, and
+`finalizeObject(key)` confirms it (idempotent; it rejects if neither the temp nor the final
+object exists). The package does **not** delete orphans itself — it tags them
+(`lifecycle=temp` on S3) or stages them under `tmp/<key>` (GCS), and you configure the
+bucket lifecycle rule that expires them. On GCS a temp object is not readable at its final
+key until finalized; on S3 it is.
 
 ### Local File System
 
@@ -342,18 +318,6 @@ async function saveToLocal(file: File, subdir: string = ''): Promise<string>
 
     return filepath;
 }
-
-export const uploadFile = route.post('/files')
-    .input({ formData: Type.Object({ file: FileSchema() }) })
-    .handler(async (c) =>
-    {
-        const { formData } = await c.data();
-        const file = formData.file as File;
-
-        const path = await saveToLocal(file, 'documents');
-
-        return c.created({ path, originalName: file.name });
-    });
 ```
 
 ### AWS S3
@@ -375,47 +339,26 @@ async function uploadToS3(file: File, prefix: string = ''): Promise<string>
         Key: key,
         Body: Buffer.from(await file.arrayBuffer()),
         ContentType: file.type,
-        Metadata: {
-            originalName: file.name
-        }
+        Metadata: { originalName: file.name },
     }));
 
     return `https://${BUCKET}.s3.amazonaws.com/${key}`;
 }
-
-export const uploadAvatar = route.post('/avatars')
-    .input({
-        formData: Type.Object({
-            image: FileSchema({
-                maxSize: 2 * 1024 * 1024,
-                allowedTypes: ['image/jpeg', 'image/png']
-            })
-        })
-    })
-    .handler(async (c) =>
-    {
-        const { formData } = await c.data();
-        const file = formData.image as File;
-        // File already validated via schema
-
-        const url = await uploadToS3(file, 'avatars/');
-
-        return c.created({ url });
-    });
 ```
 
 ### Cloudflare R2
 
 ```typescript
 import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { randomUUID } from 'crypto';
 
 const r2 = new S3Client({
     region: 'auto',
     endpoint: `https://${process.env.CF_ACCOUNT_ID}.r2.cloudflarestorage.com`,
     credentials: {
         accessKeyId: process.env.R2_ACCESS_KEY_ID!,
-        secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!
-    }
+        secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+    },
 });
 
 async function uploadToR2(file: File, prefix: string = ''): Promise<string>
@@ -426,15 +369,13 @@ async function uploadToR2(file: File, prefix: string = ''): Promise<string>
         Bucket: process.env.R2_BUCKET,
         Key: key,
         Body: Buffer.from(await file.arrayBuffer()),
-        ContentType: file.type
+        ContentType: file.type,
     }));
 
     return `${process.env.R2_PUBLIC_URL}/${key}`;
 }
 ```
 
----
-
 ## Streaming (Large Files)
 
 For large files, use streaming to avoid memory issues:
@@ -443,6 +384,7 @@ For large files, use streaming to avoid memory issues:
 import { Readable } from 'stream';
 import { createWriteStream } from 'fs';
 import { pipeline } from 'stream/promises';
+import { randomUUID } from 'crypto';
 
 export const uploadLargeFile = route.post('/large-files')
     .handler(async (c) =>
@@ -456,11 +398,9 @@ export const uploadLargeFile = route.post('/large-files')
             throw new ValidationError({ message: 'File required' });
         }
 
-        // Stream to disk
         const outputPath = `./uploads/${randomUUID()}.bin`;
         const writeStream = createWriteStream(outputPath);
 
-        // Convert File to Node.js Readable stream
         const reader = file.stream().getReader();
         const nodeStream = new Readable({
             async read()
@@ -474,7 +414,7 @@ export const uploadLargeFile = route.post('/large-files')
                 {
                     this.push(Buffer.from(value));
                 }
-            }
+            },
         });
 
         await pipeline(nodeStream, writeStream);
@@ -483,17 +423,70 @@ export const uploadLargeFile = route.post('/large-files')
     });
 ```
 
----
+## Client Usage
+
+### SPFN API Client (Recommended)
+
+The generated API client handles `FormData` construction automatically:
+
+```typescript
+import { api } from '@/lib/api';
+
+// Single file upload
+const result = await api.uploadAvatar.call({
+    params: { id: '123' },
+    formData: {
+        file: fileInput.files[0],
+        description: 'Profile photo',
+    },
+});
+
+// Multiple files
+const docs = await api.uploadDocuments.call({
+    formData: {
+        files: Array.from(fileInput.files),
+        category: 'reports',
+    },
+});
+```
+
+### Fetch API
+
+For direct backend calls (bypassing RPC proxy):
+
+```typescript
+const formData = new FormData();
+formData.append('file', fileInput.files[0]);
+formData.append('description', 'My file');
+
+const response = await fetch('/api/upload', {
+    method: 'POST',
+    body: formData,
+    // Don't set Content-Type - browser sets it with boundary
+});
+```
+
+### curl
+
+```bash
+# Single file
+curl -X POST http://localhost:3000/upload \
+  -F "file=@./document.pdf" \
+  -F "description=Important document"
+
+# Multiple files
+curl -X POST http://localhost:3000/upload-multiple \
+  -F "files=@./file1.txt" \
+  -F "files=@./file2.txt"
+```
 
 ## Security Best Practices
 
 ### 1. Always Validate MIME Types
 
 ```typescript
-// Don't trust the file extension - check MIME type
-const file = formData.file as File;
-
-// Also consider using magic bytes for true type detection
+// Don't trust file extensions - check MIME type
+// Consider using magic bytes for true type detection
 import { fileTypeFromBuffer } from 'file-type';
 
 const buffer = Buffer.from(await file.arrayBuffer());
@@ -509,9 +502,6 @@ if (!detected || !ALLOWED_TYPES.includes(detected.mime))
 
 ```typescript
 // Never use user-provided filenames directly
-const userFilename = file.name;  // potentially malicious
-
-// Generate safe filename
 const safeFilename = `${randomUUID()}.${getExtension(file.type)}`;
 
 function getExtension(mimeType: string): string
@@ -520,39 +510,13 @@ function getExtension(mimeType: string): string
         'image/jpeg': 'jpg',
         'image/png': 'png',
         'image/webp': 'webp',
-        'application/pdf': 'pdf'
+        'application/pdf': 'pdf',
     };
     return map[mimeType] || 'bin';
 }
 ```
 
-### 3. Limit File Size at Server Level
-
-```typescript
-// server.config.ts
-export default defineServerConfig()
-    .lifecycle({
-        beforeRoutes: async (app) =>
-        {
-            // Global body size limit (Hono middleware)
-            app.use('*', async (c, next) =>
-            {
-                const contentLength = parseInt(c.req.header('content-length') || '0');
-                const MAX_BODY_SIZE = 50 * 1024 * 1024;  // 50MB
-
-                if (contentLength > MAX_BODY_SIZE)
-                {
-                    return c.json({ error: 'Request too large' }, 413);
-                }
-
-                await next();
-            });
-        }
-    })
-    .build();
-```
-
-### 4. Store Outside Web Root
+### 3. Store Outside Web Root
 
 ```typescript
 // Files should not be directly accessible via URL
@@ -568,127 +532,24 @@ export const getFile = route.get('/files/:id')
 
         if (!file || !canAccess(c.raw.get('user'), file))
         {
-            throw new NotFoundError();
+            throw new NotFoundError({ resource: 'File' });
         }
 
-        // Stream file from secure location
         const buffer = await readFile(file.path);
         return new Response(buffer, {
             headers: {
                 'Content-Type': file.mimeType,
-                'Content-Disposition': `attachment; filename="${file.originalName}"`
-            }
+                'Content-Disposition': `attachment; filename="${file.originalName}"`,
+            },
         });
     });
 ```
 
-### 5. Scan for Malware (Production)
-
-```typescript
-import { ClamScan } from 'clamscan';
-
-const clam = new ClamScan({ clamdscan: { host: 'localhost', port: 3310 } });
-
-async function scanFile(buffer: Buffer): Promise<boolean>
-{
-    const { isInfected } = await clam.scanBuffer(buffer);
-    return !isInfected;
-}
-
-export const uploadFile = route.post('/files')
-    .handler(async (c) =>
-    {
-        const { formData } = await c.data();
-        const file = formData.file as File;
-        const buffer = Buffer.from(await file.arrayBuffer());
-
-        const isSafe = await scanFile(buffer);
-        if (!isSafe)
-        {
-            throw new ValidationError({ message: 'File rejected by security scan' });
-        }
-
-        // Proceed with safe file...
-    });
-```
-
----
+A handler that returns a raw `Response` has it passed through as-is, but the typed client
+then infers the response as `Response` rather than a concrete shape. That trade-off is
+fine for a file download and wrong for a JSON endpoint.
 
-## Client Usage
-
-### SPFN API Client (Recommended)
-
-Type-safe file upload with full type inference:
-
-```typescript
-import { createApi } from '@spfn/core/nextjs';
-import type { AppRouter } from '@/server/router';
-
-const api = createApi<AppRouter>();
-
-// Single file upload
-const result = await api.uploadAvatar.call({
-    params: { id: '123' },
-    formData: {
-        file: fileInput.files[0],      // File object - type-safe!
-        description: 'Profile photo'    // string field
-    }
-});
-
-// Multiple files
-const docs = await api.uploadDocuments.call({
-    formData: {
-        files: Array.from(fileInput.files),  // File[]
-        category: 'reports'
-    }
-});
-
-// With additional options
-const result = await api.uploadFile
-    .headers({ 'X-Custom': 'value' })
-    .call({
-        formData: { file: myFile }
-    });
-```
-
-**How it works:**
-1. Client builds `FormData` with files and metadata
-2. RPC Proxy parses multipart and forwards to backend
-3. Backend route receives typed `formData` via `c.data()`
-
-### Fetch API
-
-For direct backend calls (bypassing RPC proxy):
-
-```typescript
-const formData = new FormData();
-formData.append('file', fileInput.files[0]);
-formData.append('description', 'My file');
-
-const response = await fetch('/api/upload', {
-    method: 'POST',
-    body: formData
-    // Note: Don't set Content-Type header - browser sets it with boundary
-});
-```
-
-### curl
-
-```bash
-# Single file
-curl -X POST http://localhost:3000/upload \
-  -F "file=@./document.pdf" \
-  -F "description=Important document"
-
-# Multiple files
-curl -X POST http://localhost:3000/upload-multiple \
-  -F "files=@./file1.txt" \
-  -F "files=@./file2.txt"
-```
-
----
-
-## Summary
+## Schema Reference
 
 | Schema | Description |
 |--------|-------------|
@@ -699,19 +560,20 @@ curl -X POST http://localhost:3000/upload-multiple \
 | `OptionalFileSchema()` | Optional single File |
 | `OptionalFileSchema(options)` | Optional File with validation |
 
-| Validation Option | Type | Description |
-|-------------------|------|-------------|
-| `maxSize` | number | Maximum file size in bytes |
-| `minSize` | number | Minimum file size in bytes |
-| `allowedTypes` | string[] | Allowed MIME types |
-| `maxFiles` | number | Maximum file count (FileArraySchema only) |
-| `minFiles` | number | Minimum file count (FileArraySchema only) |
+## File Properties
 
-| File Property | Type | Description |
-|---------------|------|-------------|
+| Property | Type | Description |
+|----------|------|-------------|
 | `file.name` | string | Original filename |
 | `file.size` | number | Size in bytes |
 | `file.type` | string | MIME type |
 | `file.arrayBuffer()` | Promise\<ArrayBuffer\> | File content as buffer |
 | `file.text()` | Promise\<string\> | File content as text |
 | `file.stream()` | ReadableStream | File as stream |
+
+## Related
+
+- `@spfn/storage` - object storage (S3 / GCS / local), presigned uploads, key validation
+- [Route Definition](../src/route/README.md) - `formData` input type
+- [Next.js Integration](../src/nextjs/README.md) - Upload files through RPC proxy
+- [Error Handling](../src/errors/README.md) - `ValidationError` for file errors