@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/extensions/components/static-asset/errors.md

@@ -1,91 +1,159 @@
-# Static Asset -- Error Reference
+---
+title: Static Asset Component - Error Reference
+description: Every error condition StaticAssetComponent and its storage helpers can raise, plus fixes
+difficulty: intermediate
+---
+
+# Error Reference
+
+Every error condition the static asset controller and storage helpers can raise, with cause and fix.
+
+## Error conditions
+
+| Message | Cause | HTTP Status |
+|---------|-------|-------------|
+| `"Invalid bucket name"` | `bucketName` fails `isValidName()` | `400` |
+| `"Invalid object name or path"` | `objectName` fails `isValidPath()` | `400` |
+| `"Invalid folder path"` | Upload's `folderPath` query param is empty after trimming leading/trailing slashes | `400` |
+| <code v-pre>"Folder path exceeds max depth of {n}"</code> | Upload's `folderPath` has more segments than `maxFolderDepth` (default `2`) | `400` |
+| <code v-pre>"Invalid folder path segment: {segment}"</code> | One `folderPath` segment fails `isValidName()` | `400` |
+| <code v-pre>"Empty file content \| name: {originalName}"</code> | The uploaded file's buffer is empty after multipart parsing (or after re-reading a disk-spooled file) | `400` |
+| <code v-pre>"Invalid maxKeys \| Expected a positive integer \| value: {value}"</code> | `listObjects`'s `maxKeys` query param does not parse to a positive integer | `400` |
+| <code v-pre>[upload] Bucket does not exist \| name: {bucket}</code> | `helper.upload()` found no matching bucket via `isBucketExists()` | `400` (default) |
+| `[upload] Invalid original file name` | A file's `originalName` fails `isValidName()`, checked inside `helper.upload()` | `400` (default) |
+| <code v-pre>[upload] Invalid folder path \| depth: {n} \| max: {m}</code> | `helper.upload()`'s own check found more `folderPath` segments than `maxFolderDepth` allows | `400` (default) |
+| `[upload] Invalid folder path` | `helper.upload()`'s own `isValidPath()` check failed for any other reason | `400` (default) |
+| <code v-pre>[upload] Invalid file size \| size: {size}</code> | A file's `size` is `undefined`, `null`, or negative | `400` (default) |
+| <code v-pre>[upload] Invalid normalized object name \| name: {name}</code> | The name returned by `normalizeNameFn` fails `isValidPath()` | `400` (default) |
+| `[createBucket] Invalid name to create bucket!` | `createBucket()` called with a name failing `isValidName()` - only reachable calling a helper directly, the controller validates first | `400` (default) |
+| <code v-pre>[createBucket] Bucket already exists \| name: {name}</code> | `DiskHelper.createBucket()` called with a name that already exists on disk. `MinioHelper` and `BunS3Helper` throw their own SDK/S3 error text for the same case instead | `400` (default) |
+| `[removeBucket] Invalid name to remove bucket!` | `removeBucket()` called with a name failing `isValidName()` - only reachable calling a helper directly | `400` (default) |
+| <code v-pre>[removeBucket] Bucket does not exist \| name: {name}</code> | `DiskHelper.removeBucket()` - no directory at that bucket name | `400` (default) |
+| <code v-pre>[removeBucket] Bucket is not empty \| name: {name}</code> | `DiskHelper.removeBucket()` - the bucket directory still has files in it | `400` (default) |
+| <code v-pre>[getFile] File not found \| bucket: {bucket} \| name: {name}</code> (also `[getStat]`, `[removeObject]`) | `DiskHelper` - no file at that bucket/object path | `400` (default) |
+| <code v-pre>[parseMultipartBody] storage: {storage} \| Invalid storage type \| Valids: ['memory', 'disk']</code> | `extra.parseMultipartBody.storage` set to something other than `'memory'`/`'disk'` - a configuration error, not user input | `400` (default) |
 
-> Name validation rules and troubleshooting guide for common issues.
+> [!NOTE]
+> Entries marked "default" pass no explicit `statusCode` to `getError()`. `ApplicationError` defaults `statusCode` to `400` in that case.
 
-## Name Validation
+## Name validation rules
 
-Bucket names are validated with `helper.isValidName()` (single segment - no path separators allowed). Object names, which may include folder segments (e.g., `2025/uploads/report.pdf`), are validated with `helper.isValidPath()`. The validation blocks:
+Bucket names are validated with `isValidName()` (single segment, no path separators). Object names, which may include folder segments (for example `2026/uploads/report.pdf`), are validated with `isValidPath()` - every segment still runs through `isValidName()`.
 
 | Pattern | Example | Reason |
 |---------|---------|--------|
 | Path traversal | `../etc/passwd` | Contains `..`, `/`, or `\` |
 | Hidden files | `.hidden` | Starts with `.` |
-| Shell injection | `file;rm -rf /` | Contains `;`, `\|`, `&`, `$`, etc. |
-| Header injection | `file\ninjected` | Contains `\n`, `\r`, or `\0` |
-| Long names | 256+ chars | Exceeds 255 character limit |
+| Shell metacharacters | `file;rm -rf /` | Contains `;`, `\|`, `&`, `$`, `` ` ``, `<`, `>`, `{`, `}`, `[`, `]`, `!`, or `#` |
+| Control characters | `file\ninjected` | Contains `\n`, `\r`, or `\0` |
+| Long names | 256+ characters | Exceeds the 255-character limit |
 | Empty names | `""`, `"  "` | Empty or whitespace-only |
-
-Every endpoint that accepts `bucketName` validates it and returns HTTP 400 `"Invalid bucket name"` on failure. Every endpoint that accepts `objectName` validates it separately and returns HTTP 400 `"Invalid object name or path"` on failure.
+| Double slashes (path only) | `a//b.png` | `isValidPath()` rejects empty segments |
+| Excess folder depth (path only) | `a/b/c/d.png` with `maxFolderDepth: 2` | `folderDepth = segments.length - 1` exceeds the limit |
+| Long paths (path only) | 1025+ characters | Exceeds the 1024-character normalized-path limit |
 
 ## Troubleshooting
 
-### "Invalid bucket/object name"
+### "Invalid bucket name" / "Invalid object name or path"
 
-**Cause:** Bucket name validation: fails `isValidName()` - bucket names are single segments and cannot contain `..`, `/`, or `\`, shell special characters, or start with `.`, and must be <= 255 characters. Object name validation: fails `isValidPath()` - object names may contain `/` for folder structure but each segment must pass the same single-segment rules, and the folder depth must not exceed the configured limit.
+- **Cause:** the name fails the rules above.
+- **Fix:** strip path separators, leading dots, shell metacharacters, and control characters. Keep names under 255 characters (1024 for a full object path). Never send an empty or whitespace-only value.
 
-**Fix:** Ensure names follow these rules:
-- No path separators (`..`, `/`, `\`)
-- No leading dot (`.hidden`)
-- No shell special characters (`;`, `|`, `&`, `$`, `` ` ``, `<`, `>`, `{`, `}`, `[`, `]`, `!`, `#`)
-- No control characters (`\n`, `\r`, `\0`)
-- 255 characters or fewer
-- Not empty or whitespace-only
-
-> [!NOTE]
-> Every bucket-related endpoint (`GET`, `POST`, `DELETE` on `/buckets/:bucketName`) validates the bucket name and returns HTTP 400 with `"Invalid bucket name"` if validation fails. Object-related endpoints validate both bucket and object names.
+```typescript
+// Wrong - contains a path separator, rejected by isValidName()
+await fetch('/assets/buckets/user/uploads', { method: 'POST' });
 
-### "Controller not registering"
+// Right - one segment
+await fetch('/assets/buckets/user-uploads', { method: 'POST' });
+```
 
-**Cause:** Configuration key might be invalid or missing required fields.
+### "Folder path exceeds max depth" / "Invalid folder path segment"
 
-**Fix:** Ensure each storage configuration has all required fields:
+- **Cause:** the upload's `folderPath` query parameter has more segments than `maxFolderDepth` allows (default `2`), or one segment fails `isValidName()`.
+- **Fix:** flatten the folder structure, or raise the limit via `extra.maxFolderDepth` when registering the backend.
 
 ```typescript
-import { StaticAssetStorageTypes } from '@venizia/ignis/static-asset';
-
 {
-  [uniqueKey]: {
-    controller: { name, basePath, isStrict },
-    storage: StaticAssetStorageTypes.DISK | StaticAssetStorageTypes.MINIO | StaticAssetStorageTypes.BUN_S3,
-    helper: IStorageHelper,
-    extra: {}
-  }
+  storage: StaticAssetStorageTypes.DISK,
+  helper: new DiskHelper({ basePath: './uploads' }),
+  extra: { maxFolderDepth: 4 },
 }
 ```
 
-### "Files not uploading (DiskHelper)"
+### "Empty file content"
+
+- **Cause:** the uploaded file's buffer is empty - either the client sent a zero-byte file field, or `parseMultipartBody` produced no readable content.
+- **Fix:** verify the `FormData` field actually carries file bytes before submitting. A zero-byte file is rejected - this is not a size-limit issue.
+
+### "Invalid maxKeys"
 
-**Cause:** The `basePath` directory does not exist or the process lacks filesystem permissions.
+- **Cause:** `listObjects`'s `maxKeys` query string does not parse to a positive integer via `Number(maxKeys)` + `Number.isInteger()` - for example `maxKeys=abc` or `maxKeys=-1`.
+- **Fix:** only send positive integer strings, or omit the parameter entirely.
 
-**Fix:** Ensure the `basePath` directory exists or can be created, and verify the process has read/write permissions to the target path.
+```typescript
+url.searchParams.set('maxKeys', '50'); // OK
+// url.searchParams.set('maxKeys', 'all'); // 400
+```
 
-### "Files not uploading (MinioHelper)"
+### "[upload] Bucket does not exist"
 
-**Cause:** MinIO server connectivity or authentication failure.
+- **Cause:** `helper.upload()` checked `isBucketExists()` and found no match - the bucket was never created, or was deleted between requests.
+- **Fix:** create the bucket first with `POST /buckets/:bucketName`, or check `GET /buckets/:bucketName` before uploading.
 
-**Fix:**
-- Verify MinIO server is running
-- Check credentials (`accessKey`, `secretKey`)
-- Verify network connectivity (`endPoint`, `port`)
-- Check if `useSSL` matches your server configuration
+### "Bucket already exists"
 
-### "Large file uploads failing"
+- **Cause:** `POST /buckets/:bucketName` was called for a bucket that already exists. `createBucket()` throws rather than returning `null` - it does not silently succeed on a duplicate.
+- **Fix:** check `GET /buckets/:bucketName` first, or treat the throw as "already there" and continue.
 
-**Cause:** Memory-based multipart parsing cannot handle the file size.
+### Controller not registering / no routes appear
 
-**Fix:** Switch to disk-based multipart parsing:
+- **Cause:** `STATIC_ASSET_COMPONENT_OPTIONS` was never bound, or was bound to `{}` - the component's default. `binding()` iterates the options object and produces zero controllers for an empty map, without throwing.
+- **Fix:** bind a non-empty options object before `this.component(StaticAssetComponent)`:
 
 ```typescript
-extra: {
-  parseMultipartBody: {
-    storage: 'disk',
-    uploadDir: './uploads',
+this.bind<TStaticAssetsComponentOptions>({
+  key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
+}).toValue({
+  [uniqueKey]: {
+    controller: { name: 'AssetController', basePath: '/assets' },
+    storage: StaticAssetStorageTypes.DISK,
+    helper: new DiskHelper({ basePath: './uploads' }),
   },
+});
+this.component(StaticAssetComponent);
+```
+
+### Files not uploading (`DiskHelper`)
+
+- **Cause:** the process lacks filesystem permissions on `basePath`, or the disk is out of space. `DiskHelper`'s constructor already creates `basePath` if it does not exist, so a missing directory is rarely the issue.
+- **Fix:** verify the process has read/write permissions to the target path and enough free space.
+
+### Files not uploading (`MinioHelper`)
+
+- **Cause:** MinIO server connectivity or authentication failure.
+- **Fix:**
+  - Confirm the MinIO server is reachable at `endPoint`/`port`.
+  - Verify `accessKey`/`secretKey`.
+  - Check `useSSL` matches the server's actual TLS configuration.
+
+### Large file uploads failing or timing out
+
+- **Cause:** `parseMultipartBody: { storage: 'memory' }` (the default) buffers the entire file in process memory before writing it to the backend.
+- **Fix:** switch to disk-based spooling:
+
+```typescript
+extra: {
+  parseMultipartBody: { storage: 'disk', uploadDir: './tmp/uploads' },
 }
 ```
 
-## See Also
+### `BunS3Helper` fails to construct or import
+
+- **Cause:** running on Node.js. `BunS3Helper` imports `S3Client` from the `bun` builtin module, which only resolves under the Bun runtime.
+- **Fix:** use `MinioHelper` (also S3-compatible) on Node.js, or run the app under Bun.
+
+## See also
 
-- [Setup & Configuration](./) - Quick Reference, Setup Steps, Configuration Options
-- [Usage & Examples](./usage) - API Endpoints and Frontend Integration
-- [API Reference](./api) - Controller Factory, Storage Interface, MetaLink Schema
+- [Overview](./) - quick start, imports, and common configuration tasks
+- [Usage & Examples](./usage) - task-oriented walkthroughs for every endpoint and MetaLink setup
+- [Full Reference](./api) - controller factory, `IStorageHelper` interface, MetaLink schema, internals