@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

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

@@ -10,14 +10,14 @@ Every binding, endpoint, type, and internal mechanism of `StaticAssetComponent`.
 
 **Files:**
 
-- [`packages/core/src/components/static-asset/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/component.ts)
-- [`packages/core/src/components/static-asset/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/common/types.ts)
-- [`packages/core/src/components/static-asset/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/common/constants.ts)
-- [`packages/core/src/components/static-asset/common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/common/keys.ts)
-- [`packages/core/src/components/static-asset/controller/factory.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/controller/factory.ts)
-- [`packages/core/src/components/static-asset/controller/base.definition.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/controller/base.definition.ts)
-- [`packages/core/src/components/static-asset/models/base.model.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/models/base.model.ts)
-- [`packages/core/src/components/static-asset/repositories/base.repository.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/repositories/base.repository.ts)
+- [`packages/core-server/src/components/static-asset/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/static-asset/component.ts)
+- [`packages/core-server/src/components/static-asset/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/static-asset/common/types.ts)
+- [`packages/core-server/src/components/static-asset/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/static-asset/common/constants.ts)
+- [`packages/core-server/src/components/static-asset/common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/static-asset/common/keys.ts)
+- [`packages/core-server/src/components/static-asset/controller/factory.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/static-asset/controller/factory.ts)
+- [`packages/core-server/src/components/static-asset/controller/base.definition.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/static-asset/controller/base.definition.ts)
+- [`packages/core-server/src/components/static-asset/models/base.model.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/static-asset/models/base.model.ts)
+- [`packages/core-server/src/components/static-asset/repositories/base.repository.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/static-asset/repositories/base.repository.ts)
 - [`packages/helpers/src/modules/storage/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/storage/base.ts)
 - [`packages/helpers/src/modules/storage/disk/helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/storage/disk/helper.ts)
 - [`packages/helpers/src/modules/storage/minio/helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/storage/minio/helper.ts)
@@ -106,7 +106,7 @@ type TStaticAssetsComponentOptions = {
 | Field | Type | Default | Description |
 |-------|------|---------|--------------|
 | `controller.name` | `string` | - | Class name given to the generated controller (via `Object.defineProperty`) |
-| `controller.basePath` | `string` | - | Mount path, e.g. `'/assets'` |
+| `controller.basePath` | `string` | - | Mount path, for example `'/assets'` |
 | `controller.isStrict` | `boolean` | `true` | Passed through to `BaseRestController`'s strict routing mode |
 | `controller.routes` | object | `undefined` | Per-route overrides - see [Per-route overrides](#per-route-overrides) |
 | `storage` | `'disk' \| 'minio' \| 'bun-s3'` | - | Selects which `helper` type is required (discriminated union) |
@@ -149,7 +149,7 @@ type TStaticAssetExtraOptions = {
 ```
 
 > [!NOTE]
-> `normalizeNameFn` receives **both** `originalName` and `folderPath` - the second lets a custom implementation decide how to fold the target folder into the stored name. Omit `folderPath` handling and nested uploads flatten into the bucket root.
+> `normalizeNameFn` receives **both** `originalName` and `folderPath`. The second argument lets a custom implementation decide how to fold the target folder into the stored name. Omit `folderPath` handling and nested uploads flatten into the bucket root.
 
 | Field | Default | Notes |
 |-------|---------|-------|
@@ -170,7 +170,9 @@ type TStaticAssetExtraOptions = {
 };
 ```
 
-This is why every generated link points back at the `objects/{objectName}` stream route by default, regardless of storage backend. `BaseStorageHelper`'s own backend-specific `normalizeObjectLink()` (used when a helper's `upload()` is called directly, outside the component) is never reached through `StaticAssetComponent` - the component's default always takes priority when no `normalizeLinkFn` is set.
+This is why every generated link points back at the `objects/{objectName}` stream route by default, regardless of storage backend.
+
+`BaseStorageHelper` has its own backend-specific `normalizeObjectLink()`. It only runs when you call a helper's `upload()` directly, outside the component. Through `StaticAssetComponent`, the component's default `normalizeLinkFn` always takes priority instead.
 
 ## Storage types
 
@@ -294,9 +296,29 @@ interface IListObjectsOptions {
 
 ### Name and path validation (`BaseStorageHelper`)
 
-`isValidName(name)` rejects, in order: non-string input, empty string, `..`/`/`/`\` (path traversal), a leading `.` (hidden file), any of `;`, `\|`, `&`, `$`, `` ` ``, `<`, `>`, `{`, `}`, `[`, `]`, `!`, `#` (shell metacharacters), `\n`/`\r`/`\0` (control characters), length over 255, and whitespace-only input.
-
-`isValidPath(pathStr, { maxDepth })` trims leading/trailing slashes, rejects an empty result, rejects double slashes (empty segments), computes `folderDepth = segments.length - 1` and rejects it exceeding `maxDepth` (default `BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH = 2`), validates every segment through `isValidName()`, and rejects a normalized length over 1024 characters.
+`isValidName(name)` rejects any of the following, in order:
+
+| Check | Rejects |
+|-------|---------|
+| Type | Non-string input |
+| Empty | Empty string |
+| Path traversal | `..`, `/`, or `\` |
+| Hidden file | A leading `.` |
+| Shell metacharacters | `;`, `\|`, `&`, `$`, `` ` ``, `<`, `>`, `{`, `}`, `[`, `]`, `!`, `#` |
+| Control characters | `\n`, `\r`, `\0` |
+| Length | Over 255 characters |
+| Whitespace-only | Empty after trimming |
+
+`isValidPath(pathStr, { maxDepth })` runs these checks, in order:
+
+| Step | Behavior |
+|------|----------|
+| Normalize | Trims leading/trailing slashes |
+| Empty check | Rejects if the result is empty |
+| Double slashes | Rejects empty segments, for example `a//b` |
+| Folder depth | `folderDepth = segments.length - 1`; rejects if it exceeds `maxDepth` (default `BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH = 2`) |
+| Segment names | Every segment must pass `isValidName()` |
+| Path length | Rejects a normalized length over 1024 characters |
 
 ### `DiskHelper`
 
@@ -349,7 +371,7 @@ interface IBunS3HelperOptions {
 }
 ```
 
-Wraps Bun's native `S3Client`, imported from the `bun` builtin module - it only resolves under the Bun runtime, which is why it is exported from the separate `@venizia/ignis-helpers/bun-s3` subpath rather than the main entry point.
+Wraps Bun's native `S3Client`, imported from the `bun` builtin module. That module only resolves under the Bun runtime. This is why `BunS3Helper` is exported from the separate `@venizia/ignis-helpers/bun-s3` subpath, not the main entry point.
 
 ```typescript
 import { BunS3Helper } from '@venizia/ignis-helpers/bun-s3';
@@ -412,7 +434,7 @@ const MultipartBodySchema = z.object({
 |--------|------|-------|
 | `GET` | `/buckets` | No params. Returns `IBucketInfo[]` |
 | `GET` | <code v-pre>/buckets/{bucketName}</code> | Returns `IBucketInfo \| null` |
-| `POST` | <code v-pre>/buckets/{bucketName}</code> | Returns `IBucketInfo \| null` (`null` if creation failed, e.g. already exists) |
+| `POST` | <code v-pre>/buckets/{bucketName}</code> | Returns the created `IBucketInfo`. Throws if the bucket already exists or the name is invalid - see [Error Reference](./errors) |
 | `DELETE` | <code v-pre>/buckets/{bucketName}</code> | Returns <code v-pre>{ isDeleted: boolean }</code> |
 | `POST` | <code v-pre>/buckets/{bucketName}/upload</code> | `multipart/form-data` body; query: `principalType?`, `principalId?`, `variant?`, `folderPath?`. Returns `IUploadResult[]` |
 | `GET` | <code v-pre>/buckets/{bucketName}/objects</code> | Query: `prefix?`, `recursive?` (`'true'` string only), `maxKeys?` (positive integer string). Returns `IObjectInfo[]` |
@@ -424,25 +446,33 @@ const MultipartBodySchema = z.object({
 ### Upload validation order
 
 1. `bucketName` validated with `isValidName()` - `400 "Invalid bucket name"` on failure.
-2. If `folderPath` is present: trimmed of leading/trailing slashes, `400 "Invalid folder path"` if empty after trimming; segment count checked against `maxFolderDepth`, `400 "Folder path exceeds max depth of {n}"` if over; each segment checked with `isValidName()`, `400 "Invalid folder path segment: {segment}"` if any fails.
+2. If `folderPath` is present, three checks run in order:
+
+   | Check | Failure |
+   |-------|---------|
+   | Trim leading/trailing slashes | `400 "Invalid folder path"` if empty after trimming |
+   | Segment count vs. `maxFolderDepth` | `400 "Folder path exceeds max depth of {n}"` if over |
+   | Each segment via `isValidName()` | `400 "Invalid folder path segment: {segment}"` if any fails |
+
 3. `multipart/form-data` parsed via `parseMultipartBody()`.
-4. Each file's effective buffer (direct `buffer`, or `readFileSync(file.path)` when `storage: 'disk'` was used) checked non-empty - `400 "Empty file content | name: {originalName}"` if empty.
+4. Each file's effective buffer is checked non-empty - direct `buffer`, or `readFileSync(file.path)` when `storage: 'disk'` was used. Empty content returns `400 "Empty file content | name: {originalName}"`.
 5. `helper.upload()` runs the storage-helper-level checks below.
-6. Spool files written by `storage: 'disk'` parsing are removed in a `finally` block via `rmSync({ force: true })`, regardless of success or failure; removal errors are logged, never thrown.
+6. Spool files written by `storage: 'disk'` parsing are removed in a `finally` block via `rmSync({ force: true })` - regardless of success or failure. Removal errors are logged, never thrown.
 
 ### Storage-helper-level upload checks (`BaseStorageHelper.upload`)
 
-These run inside `helper.upload()`, independent of and in addition to the controller's own checks above - reachable even when a caller uses the storage helper directly:
+These run inside `helper.upload()`, separate from the controller checks above. They are reachable even when a caller uses the storage helper directly:
 
 | Check | Error message | Default status |
 |-------|----------------|-----------------|
 | Bucket does not exist (`isBucketExists()` false) | <code v-pre>[upload] Bucket does not exist \| name: {bucket}</code> | `400` |
 | `originalName` fails `isValidName()` | `[upload] Invalid original file name` | `400` |
-| `folderPath` exceeds depth or fails `isValidPath()` | `[upload] Invalid folder path` | `400` |
+| `folderPath` segment count exceeds `maxFolderDepth` | <code v-pre>[upload] Invalid folder path \| depth: {n} \| max: {m}</code> | `400` |
+| `folderPath` fails `isValidPath()` for any other reason | `[upload] Invalid folder path` | `400` |
 | `size` is `undefined`, `null`, or negative | <code v-pre>[upload] Invalid file size \| size: {size}</code> | `400` |
 | Normalized name (post `normalizeNameFn`) fails `isValidPath()` | <code v-pre>[upload] Invalid normalized object name \| name: {name}</code> | `400` |
 
-`getError()` defaults `statusCode` to `400` when the caller does not pass one explicitly - every message above is thrown without an explicit status, so all resolve to `400`.
+`getError()` defaults `statusCode` to `400` when the caller does not pass one explicitly. Every message above is thrown without an explicit status, so all resolve to `400`.
 
 ## Header sanitization
 
@@ -456,7 +486,9 @@ const WHITELIST_HEADERS = [
 ] as const;
 ```
 
-These correspond to `HTTP.Headers.CONTENT_TYPE`, `CONTENT_ENCODING`, `CACHE_CONTROL`, `ETAG`, and `LAST_MODIFIED` from `@venizia/ignis-helpers`. When streaming a file (both `objects/{objectName}` and `download/{objectName}`), the controller copies only these keys from the storage metadata onto the response; every other metadata header is dropped. Each forwarded value is sanitized with `String(value).replace(/[\r\n]/g, '')` before being set, to prevent HTTP header injection.
+These correspond to `HTTP.Headers.CONTENT_TYPE`, `CONTENT_ENCODING`, `CACHE_CONTROL`, `ETAG`, and `LAST_MODIFIED` from `@venizia/ignis-helpers`.
+
+When streaming a file - both `objects/{objectName}` and `download/{objectName}` - the controller copies only these keys from the storage metadata onto the response. Every other metadata header is dropped. Each forwarded value is sanitized with `String(value).replace(/[\r\n]/g, '')` before being set, to prevent HTTP header injection.
 
 All streaming responses also set:
 
@@ -471,7 +503,7 @@ Content-Disposition: attachment; filename="..."   (download endpoint only, via c
 
 Hono percent-decodes a path param before the handler reads it. The controller's `readObjectName()` is therefore a deliberate no-op - it does not run a second `decodeURIComponent()`:
 
-- `report_100%.pdf` is a legal object name. Its link is `.../objects/report_100%25.pdf`; Hono hands the handler back `report_100%.pdf`. A second decode would hit the invalid escape `%.p` and throw, making the object permanently unfetchable and undeletable.
+- `report_100%.pdf` is a legal object name. Its link is `.../objects/report_100%25.pdf`. Hono hands the handler back `report_100%.pdf`. A second decode would hit the invalid escape `%.p` and throw - the object would become permanently unfetchable and undeletable.
 - An object named `a%2Fb.png` would decode twice into `a/b.png` - a different object than the one requested.
 
 `isValidName()`/`isValidPath()` still run on the singly-decoded value, so a traversal payload is rejected exactly as before.
@@ -490,7 +522,12 @@ type TMetaLinkConfig<Schema extends TMetaLinkSchema = TMetaLinkSchema> = {
 };
 ```
 
-`BaseRelationalEntity` and `DefaultRelationalRepository` are the canonical class names (`packages/core/src/connectors/postgres/`); `BasePostgresEntity` and `DefaultCRUDRepository` are re-exported aliases of the same classes.
+| Canonical name | Alias |
+|----------------|-------|
+| `BaseRelationalEntity` | `BasePostgresEntity` |
+| `DefaultRelationalRepository` | `DefaultCRUDRepository` |
+
+Both canonical classes live in `packages/core-server/src/connectors/postgres/`. Each alias re-exports the same class under a different name.
 
 ## MetaLink SQL schema
 
@@ -510,19 +547,34 @@ type TMetaLinkConfig<Schema extends TMetaLinkSchema = TMetaLinkSchema> = {
 | `metadata` | JSONB | Yes | - | Additional file metadata |
 | `storage_type` | TEXT | No | - | `'disk'`, `'minio'`, or `'bun-s3'` |
 | `is_synced` | BOOLEAN | No | `false` | Set `true` on every upload and every meta-links sync |
-| `variant` | TEXT | Yes | - | Upload variant tag (e.g. `'thumbnail'`, `'original'`) |
+| `variant` | TEXT | Yes | - | Upload variant tag (for example `'thumbnail'`, `'original'`) |
 | `principal_type` | TEXT | Yes | - | Associated principal type |
 | `principal_id` | TEXT | Yes | - | Associated principal ID, always stored as a string |
 
 **Indexes:** `bucket_name`, `object_name`, `storage_type`, `is_synced`.
 
-`@model({ type: 'entity', skipMigrate: true })` on `BaseMetaLinkModel` means IGNIS's schema migration skips this table - it must be created manually, once, per database.
+`@model({ type: 'entity', skipMigrate: true })` on `BaseMetaLinkModel` means IGNIS's schema migration skips this table. Create it manually, once, per database.
 
 ### MetaLink lifecycle
 
-- **On upload:** creates one MetaLink row per uploaded file after fetching fresh stats via `helper.getStat()`. Uses `metaLink.createMetaLink()` when provided, otherwise a default insert covering every standard field. `principalType`, `principalId`, and `variant` are taken from the upload's query parameters. If the insert throws, the upload still succeeds and the file's entry in the response gets `metaLink: null` plus a `metaLinkError` string; the error is also logged.
-- **On delete:** storage delete happens first and is awaited; the MetaLink row delete (`deleteAll({ where: { bucketName, objectName } })`) is fired without awaiting it. The HTTP response returns as soon as the storage delete resolves - the database delete may still be in flight. Errors there are logged, never surfaced to the client.
-- **On sync (`PUT meta-links/:objectName`):** looks up an existing row by `bucketName` + `objectName`. If found, `updateById()` then re-fetches with `findById()`. If not found, `create()`. Either path always sets `isSynced: true` and returns `{ success: true, metaLink }`.
+- **On upload:**
+  - Creates one MetaLink row per uploaded file, after fetching fresh stats via `helper.getStat()`.
+  - Uses `metaLink.createMetaLink()` when provided, otherwise a default insert that covers every standard field.
+  - `principalType`, `principalId`, and `variant` come from the upload's query parameters.
+  - If the insert throws, the upload still succeeds. The file's response entry gets `metaLink: null` plus a `metaLinkError` string, and the error is logged.
+- **On delete:**
+  - The storage delete happens first and is awaited.
+  - The MetaLink row delete (`deleteAll({ where: { bucketName, objectName } })`) fires without being awaited.
+  - The HTTP response returns as soon as the storage delete resolves - the database delete may still be in flight.
+  - Errors there are logged, never surfaced to the client.
+- **On sync (`PUT meta-links/:objectName`):** looks up an existing row by `bucketName` + `objectName`.
+
+  | Row found? | Action |
+  |------------|--------|
+  | Yes | `updateById()`, then re-fetches with `findById()` |
+  | No | `create()` |
+
+  Either path sets `isSynced: true` and returns `{ success: true, metaLink }`.
 
 ## Component lifecycle
 
@@ -532,7 +584,7 @@ type TMetaLinkConfig<Schema extends TMetaLinkSchema = TMetaLinkSchema> = {
 4. Calls `AssetControllerFactory.defineAssetController()` and registers the result with `this.application.controller()`.
 5. Logs the storage key, storage type, and whether MetaLink is enabled for each registered backend.
 
-`StaticAssetComponent` itself performs no eager configuration validation beyond the options type - a missing `metaLink` when `useMetaLink: true` is caught at compile time by the discriminated union, not at `binding()` runtime.
+`StaticAssetComponent` itself performs no eager configuration validation beyond the options type. A missing `metaLink` when `useMetaLink: true` is caught at compile time by the discriminated union, not at `binding()` runtime.
 
 ## See also
 

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

@@ -21,18 +21,24 @@ Every error condition the static asset controller and storage helpers can raise,
 | <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) |
-| `[upload] Invalid folder path` | `helper.upload()`'s own `folderPath` depth/`isValidPath()` check failed | `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!` | `MinioHelper.createBucket()` called with a name failing `isValidName()` - only reachable calling the helper directly, the controller validates first | `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) |
 
 > [!NOTE]
-> Entries marked "default" pass no explicit `statusCode` to `getError()`; `ApplicationError` defaults `statusCode` to `400` in that case.
+> Entries marked "default" pass no explicit `statusCode` to `getError()`. `ApplicationError` defaults `statusCode` to `400` in that case.
 
 ## Name validation rules
 
-Bucket names are validated with `isValidName()` (single segment, no path separators). Object names, which may include folder segments (e.g. `2026/uploads/report.pdf`), are validated with `isValidPath()` - every segment still runs through `isValidName()`.
+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 |
 |---------|---------|--------|
@@ -51,7 +57,7 @@ Bucket names are validated with `isValidName()` (single segment, no path separat
 ### "Invalid bucket name" / "Invalid object name or path"
 
 - **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:** 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.
 
 ```typescript
 // Wrong - contains a path separator, rejected by isValidName()
@@ -77,11 +83,11 @@ await fetch('/assets/buckets/user-uploads', { method: 'POST' });
 ### "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.
+- **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:** `listObjects`'s `maxKeys` query string does not parse to a positive integer via `Number(maxKeys)` + `Number.isInteger()` - e.g. `maxKeys=abc` or `maxKeys=-1`.
+- **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.
 
 ```typescript
@@ -94,6 +100,11 @@ url.searchParams.set('maxKeys', '50'); // OK
 - **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.
 
+### "Bucket already exists"
+
+- **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.
+
 ### Controller not registering / no routes appear
 
 - **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.

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

@@ -45,12 +45,19 @@ This registers `GET`/`POST`/`DELETE` on `/assets/buckets/:bucketName`, `POST /as
 
 ## How it works
 
-- **One options key, one generated controller.** `TStaticAssetsComponentOptions` is a record - each key (`staticAsset` above) becomes an independently-configured storage backend with its own `basePath`, built by `AssetControllerFactory.defineAssetController()` inside `StaticAssetComponent.binding()`.
-- **`storage` and `helper` are a discriminated pair.** The options type forces `storage: 'disk'` with a `DiskHelper`, `'minio'` with a `MinioHelper`, or `'bun-s3'` with a `BunS3Helper` - mismatching them fails at compile time, not at runtime.
-- **Every backend implements the same `IStorageHelper` contract.** `DiskHelper`, `MinioHelper`, and `BunS3Helper` all extend `BaseStorageHelper`, so bucket/object operations, name validation (`isValidName`/`isValidPath`), and upload normalization behave identically regardless of backend.
-- **Object names can embed folder paths, encoded as one segment.** `objects/{objectName}` takes the whole `folder/file.ext` string percent-encoded (`encodeURIComponent`, which also escapes `/`) - Hono decodes it once before the handler reads it, so client code must encode but never decode a second time.
-- **MetaLink is opt-in.** Set `useMetaLink: true` and provide `metaLink.repository` to persist a database row (bucket, object, mimetype, size, etag, principal, variant) alongside every upload - useful for querying "which files does user X own" without listing a whole bucket.
-- **The default binding is empty.** `StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS` defaults to `{}` - bind it with at least one storage backend before `this.component(StaticAssetComponent)` produces any routes.
+- **One options key, one generated controller.** `TStaticAssetsComponentOptions` is a record. Each key (`staticAsset` above) becomes an independently configured storage backend with its own `basePath`. `AssetControllerFactory.defineAssetController()` builds the controller inside `StaticAssetComponent.binding()`.
+- **`storage` and `helper` are a discriminated pair.** Mismatching them fails at compile time, not at runtime:
+
+  | `storage` | Required `helper` |
+  |-----------|--------------------|
+  | `'disk'` | `DiskHelper` |
+  | `'minio'` | `MinioHelper` |
+  | `'bun-s3'` | `BunS3Helper` |
+
+- **Every backend implements the same `IStorageHelper` contract.** `DiskHelper`, `MinioHelper`, and `BunS3Helper` all extend `BaseStorageHelper`. Bucket/object operations, name validation (`isValidName`/`isValidPath`), and upload normalization behave identically regardless of backend.
+- **Object names can embed folder paths, encoded as one segment.** `objects/{objectName}` percent-encodes the whole `folder/file.ext` string via `encodeURIComponent()`, which also escapes `/`. Hono decodes it before your handler runs - encode the name client-side, and never decode it again.
+- **MetaLink is opt-in.** Set `useMetaLink: true` and provide `metaLink.repository`. IGNIS then persists a database row (`bucket/object/mimetype/size/etag/principal/variant`) alongside every upload. That row lets you query "which files does user X own" without listing a whole bucket.
+- **The default binding is empty.** `StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS` defaults to `{}`. Bind it with at least one storage backend before `this.component(StaticAssetComponent)` - an empty binding produces zero routes.
 
 ## Common tasks
 
@@ -145,9 +152,9 @@ extra: {
 
 **Files:**
 
-- [`packages/core/src/components/static-asset/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/component.ts) - `StaticAssetComponent`
-- [`packages/core/src/components/static-asset/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/common/types.ts) - `TStaticAssetsComponentOptions`, `TStaticAssetExtraOptions`, `TMetaLinkConfig`
-- [`packages/core/src/components/static-asset/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/common/constants.ts) - `StaticAssetStorageTypes`
-- [`packages/core/src/components/static-asset/controller/factory.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/controller/factory.ts) - `AssetControllerFactory`
-- [`packages/core/src/components/static-asset/models/base.model.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/models/base.model.ts) - `BaseMetaLinkModel`
+- [`packages/core-server/src/components/static-asset/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/static-asset/component.ts) - `StaticAssetComponent`
+- [`packages/core-server/src/components/static-asset/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/static-asset/common/types.ts) - `TStaticAssetsComponentOptions`, `TStaticAssetExtraOptions`, `TMetaLinkConfig`
+- [`packages/core-server/src/components/static-asset/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/static-asset/common/constants.ts) - `StaticAssetStorageTypes`
+- [`packages/core-server/src/components/static-asset/controller/factory.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/static-asset/controller/factory.ts) - `AssetControllerFactory`
+- [`packages/core-server/src/components/static-asset/models/base.model.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/static-asset/models/base.model.ts) - `BaseMetaLinkModel`
 - [`packages/helpers/src/modules/storage/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/storage/base.ts) - `BaseStorageHelper`, `IStorageHelper`

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

@@ -44,9 +44,14 @@ const [result] = await response.json();
 // { bucketName: 'user-uploads', objectName: 'invoices/2026/document.pdf', link: '/assets/buckets/user-uploads/objects/invoices%2F2026%2Fdocument.pdf' }
 ```
 
-- **`folderPath` is validated separately from the filename.** Each segment must pass `isValidName()`, and the segment count must not exceed `maxFolderDepth` (default `2`) - both return `400` before the file is even parsed.
+- **`folderPath` is validated separately from the filename.** Each segment must pass `isValidName()`. The segment count must stay within `maxFolderDepth` (default `2`). Both checks return `400` before the file is even parsed.
 - **`principalId` is always stored as a string**, coerced with `String()` regardless of whether you send a number or a string.
-- With MetaLink enabled, the response also carries `metaLink` (the created database record) or, if that write failed, `metaLink: null` plus a `metaLinkError` string - **the upload itself still succeeds either way**.
+- **With MetaLink enabled, the upload always succeeds - even if the tracking write fails.** The response carries one of two shapes:
+
+  | Outcome | Response field |
+  |---------|-----------------|
+  | MetaLink write succeeded | `metaLink`: the created database record |
+  | MetaLink write failed | `metaLink: null` plus a `metaLinkError` string |
 
 ## Stream or download an object
 
@@ -61,10 +66,10 @@ const downloadUrl = `/assets/buckets/user-uploads/download/${encodeURIComponent(
 window.open(downloadUrl, '_blank');
 ```
 
-Both routes validate `bucketName` with `isValidName()` and `objectName` with `isValidPath()`, then forward a fixed whitelist of metadata headers (`content-type`, `content-encoding`, `cache-control`, `etag`, `last-modified`) plus `X-Content-Type-Options: nosniff`. See [Header Sanitization](./api#header-sanitization) for the full list and why it exists.
+Both routes validate `bucketName` with `isValidName()` and `objectName` with `isValidPath()`. Both then forward a fixed whitelist of metadata headers - `content-type`, `content-encoding`, `cache-control`, `etag`, `last-modified` - plus `X-Content-Type-Options: nosniff`. See [Header Sanitization](./api#header-sanitization) for the full list and why it exists.
 
 > [!TIP]
-> `objectName` may embed folder segments (`invoices/2026/document.pdf`) - always pass the whole thing through `encodeURIComponent()`. Hono decodes it exactly once before the handler reads it, so a second `decodeURIComponent()` on your end is wrong and can corrupt names containing a literal `%`.
+> `objectName` may embed folder segments, for example `invoices/2026/document.pdf`. Always pass the whole thing through `encodeURIComponent()`. Hono decodes it exactly once before the handler reads it - a second `decodeURIComponent()` on your end is wrong. It can corrupt names that contain a literal `%`.
 
 ## List objects in a bucket
 
@@ -92,7 +97,7 @@ const { success } = await fetch(
 ```
 
 > [!NOTE]
-> When MetaLink is enabled, the database record deletion is **fire-and-forget** - the response returns as soon as the storage delete completes, without waiting on the `deleteAll()` call. Deletion errors are logged but never fail the request.
+> When MetaLink is enabled, the database record deletion is **fire-and-forget**. The response returns as soon as the storage delete completes - it does not wait on the `deleteAll()` call. Deletion errors are logged but never fail the request.
 
 ## Sync a MetaLink record manually
 
@@ -184,7 +189,7 @@ export class Application extends BaseApplication {
 
 ### Custom MetaLink creation
 
-Provide `createMetaLink` on `TMetaLinkConfig` to fully replace the default insert - e.g. to add extra fields or run validation before persisting.
+Provide `createMetaLink` on `TMetaLinkConfig` to fully replace the default insert - for example to add extra fields or run validation before persisting.
 
 ```typescript
 metaLink: {

package/content/extensions/components/template/index.md

@@ -69,9 +69,9 @@ When documenting a component, find source material here:
 
 | What | Path |
 |------|------|
-| Binding keys | `packages/core/src/components/{name}/common/keys.ts` |
-| Config types | `packages/core/src/components/{name}/common/types.ts` |
-| Error messages | `packages/core/src/components/{name}/component.ts` -- look for `throw getError()` |
+| Binding keys | `packages/core-server/src/components/{name}/common/keys.ts` |
+| Config types | `packages/core-server/src/components/{name}/common/types.ts` |
+| Error messages | `packages/core-server/src/components/{name}/component.ts` -- look for `throw getError()` |
 | Helper source | `packages/helpers/src/helpers/{name}/` |
 
 ## Callout Standard

package/content/extensions/components/websocket/api.md

@@ -10,9 +10,9 @@ Every binding key, configuration option, callback signature, and internal mechan
 
 **Files:**
 
-- [`packages/core/src/components/websocket/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/websocket/component.ts)
-- [`packages/core/src/components/websocket/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/websocket/common/types.ts)
-- [`packages/core/src/components/websocket/handlers/bun.handler.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/websocket/handlers/bun.handler.ts)
+- [`packages/core-server/src/components/websocket/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/websocket/component.ts)
+- [`packages/core-server/src/components/websocket/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/websocket/common/types.ts)
+- [`packages/core-server/src/components/websocket/handlers/bun.handler.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/websocket/handlers/bun.handler.ts)
 - [`packages/helpers/src/modules/socket/websocket/server/helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/socket/websocket/server/helper.ts)
 - [`packages/helpers/src/modules/socket/websocket/emitter/helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/socket/websocket/emitter/helper.ts)
 
@@ -65,7 +65,7 @@ import type {
 
 ## Configuration
 
-`WebSocketComponent`'s own `IServerOptions` interface is a **subset** of the helper's `IWebSocketServerOptions` - the component fills in `server`, `redisConnection`, callback functions, `authTimeout`, and `encryptedBatchLimit` from the DI container before constructing the helper.
+`WebSocketComponent`'s own `IServerOptions` interface is a **subset** of the helper's `IWebSocketServerOptions`. Before constructing the helper, the component fills in `server` and `redisConnection` from the running application, plus every callback function resolved from the DI container. It does not forward `authTimeout` or `encryptedBatchLimit` - see the note below.
 
 ```typescript
 interface IServerOptions {
@@ -162,7 +162,7 @@ Passed straight through to Bun's native WebSocket handler via `serverOptions` in
 | `CLIENT_CONNECTED_HANDLER` | `TWebSocketClientConnectedFn` | No | Called after successful authentication |
 | `CLIENT_DISCONNECTED_HANDLER` | `TWebSocketClientDisconnectedFn` | No | Called on disconnect, after cleanup |
 | `MESSAGE_HANDLER` | `TWebSocketMessageHandler` | No | Handles non-system messages from authenticated clients |
-| `OUTBOUND_TRANSFORMER` | `TWebSocketOutboundTransformer` | No | Transforms outbound messages (e.g. per-client encryption) |
+| `OUTBOUND_TRANSFORMER` | `TWebSocketOutboundTransformer` | No | Transforms outbound messages (for example per-client encryption) |
 | `HANDSHAKE_HANDLER` | `TWebSocketHandshakeFn` | When `requireEncryption: true` | Returns <code v-pre>{ serverPublicKey, salt }</code> or `null`/`false` to reject |
 
 ```typescript
@@ -205,14 +205,14 @@ type TWebSocketHandshakeFn<AuthDataType extends Record<string, unknown> = Record
 
 - **`VALIDATE_ROOM_HANDLER` receives sanitized rooms.** Internal `ws:`-prefixed rooms are already filtered out before this callback runs. Without it bound, **all** join requests are rejected.
 - **`CLIENT_CONNECTED_HANDLER` / `CLIENT_DISCONNECTED_HANDLER` errors are caught and logged**, never thrown - a broken hook cannot disconnect a client or crash the server.
-- **`MESSAGE_HANDLER` only sees non-system events** (`authenticate`, `connected`, `disconnect`, `join`, `leave`, `error`, `heartbeat`, `encrypted` are all handled internally). Unbound, non-system messages are silently dropped.
+- **`MESSAGE_HANDLER` only sees non-system events.** `authenticate`, `connected`, `disconnect`, `join`, `leave`, `error`, `heartbeat`, and `encrypted` are all handled internally. Unbound, non-system messages are silently dropped.
 - **`OUTBOUND_TRANSFORMER` only runs for encrypted clients** (`client.encrypted === true`). Non-encrypted clients bypass it entirely - zero overhead until encryption is enabled.
 
 ## Architecture
 
 ### Lifecycle integration
 
-The component uses the application's **post-start hook** system to solve a timing problem: WebSocket needs a running Bun server instance, but components initialize before the server starts.
+The component uses the application's **post-start hook** system to solve a timing problem. WebSocket needs a running Bun server instance, but components initialize before the server starts.
 
 ```
 preConfigure()          <- register WebSocketComponent here
@@ -252,7 +252,7 @@ function createBunFetchHandler(opts: {
 
 ## `WebSocketEmitter` API
 
-Standalone, lightweight Redis-only publisher for processes that do not run a `WebSocketServerHelper`. Extends `BaseHelper`; uses a single Redis pub client.
+Standalone, lightweight Redis-only publisher for processes that do not run a `WebSocketServerHelper`. Extends `BaseHelper`. Uses a single Redis pub client.
 
 ```typescript
 interface IWebSocketEmitterOptions {
@@ -261,8 +261,11 @@ interface IWebSocketEmitterOptions {
 }
 ```
 
-- **Constructor** calls `super({ scope })`, throws `"Invalid redis connection!"` if `redisConnection` is falsy, and calls `redisConnection.duplicateClient()` to create an isolated pub client.
-- **`EMITTER_SERVER_ID = 'emitter'`.** Every message the emitter publishes carries this fixed `serverId`. No `WebSocketServerHelper` ever has this ID (they use `crypto.randomUUID()`), so no server self-dedups an emitter message.
+- **Constructor:**
+  - Calls `super({ scope })`.
+  - Throws `"Invalid redis connection!"` if `redisConnection` is falsy.
+  - Calls `redisConnection.duplicateClient()` to create an isolated pub client.
+- **`EMITTER_SERVER_ID = 'emitter'`.** Every message the emitter publishes carries this fixed `serverId`. No `WebSocketServerHelper` ever has this ID - they use `crypto.randomUUID()` - so no server self-dedups an emitter message.
 
 | Method | Signature | Behavior |
 |--------|-----------|----------|
@@ -282,7 +285,7 @@ Reads all binding keys and validates the required ones, throwing before the post
 | Binding | Validation | Error on failure |
 |---------|-----------|------------------|
 | `SERVER_OPTIONS` | Optional, merged with `DEFAULT_SERVER_OPTIONS` via `Object.assign()` | -- |
-| `REDIS_CONNECTION` | Must be `instanceof AbstractRedisHelper` | `"Invalid instance of redisConnection ..."` |
+| `REDIS_CONNECTION` | Must pass `isRedisHelper()` | `"Invalid instance of redisConnection ..."` |
 | `AUTHENTICATE_HANDLER` | Must be truthy | `"Invalid authenticateFn to setup WebSocket server!"` |
 | `VALIDATE_ROOM_HANDLER` / `CLIENT_CONNECTED_HANDLER` / `CLIENT_DISCONNECTED_HANDLER` / `MESSAGE_HANDLER` / `OUTBOUND_TRANSFORMER` / `HANDSHAKE_HANDLER` | Optional, `null` coerced to `undefined` | -- |
 
@@ -290,7 +293,7 @@ Reads all binding keys and validates the required ones, throwing before the post
 
 Registers the `websocket-initialize` post-start hook:
 
-1. Gets the Bun server instance (`getServerInstance()`) and Hono server (`getServer()`) - throws `"[WebSocketComponent] Bun server instance not available!"` if the Bun instance is missing.
+1. Gets the Bun server instance via `getServerInstance()` and the Hono server via `getServer()`. Throws `"[WebSocketComponent] Bun server instance not available!"` if the Bun instance is missing.
 2. Constructs `WebSocketServerHelper` with all resolved bindings plus the running server instance.
 3. Awaits `wsHelper.configure()` - connects Redis clients, sets up subscriptions, starts the heartbeat timer.
 4. Binds the helper to `WEBSOCKET_INSTANCE`.
@@ -314,10 +317,21 @@ if (runtime === RuntimeModules.NODE) {
 | Callback | Responsibility |
 |----------|---------------|
 | `open` | Creates the `IWebSocketClient` entry in state `UNAUTHORIZED`, subscribes the socket to its own `clientId` topic, starts the auth timer (skips if `clientId` already exists) |
-| `message` | Updates `lastActivity`; parses JSON (sends `error` on failure); routes `heartbeat` (no-op), `authenticate`, other events on unauthenticated clients (`error`: `"Not authenticated"`), `join`, `leave`, or custom events to `messageHandler` |
+| `message` | Updates `lastActivity`, then routes the parsed event - see the table below |
 | `close` | Clears the auth timer, removes the client from `users`/`rooms`/`clients`, invokes `clientDisconnectedFn` (errors caught and logged) |
 | `drain` | Resets `client.backpressured = false` |
 
+The `message` callback routes each event like this:
+
+| Event | Handling |
+|-------|----------|
+| Not valid JSON | Sends an `error` event back to the client |
+| `heartbeat` | No-op - `lastActivity` was already updated |
+| `authenticate` | Runs the authentication flow |
+| Any other event, client not yet authenticated | Sends `error: "Not authenticated"` |
+| `join` / `leave` | Runs the room join/leave flow |
+| Any other event, client authenticated | Forwarded to `messageHandler` |
+
 ### `deliverToSocket()` backpressure handling
 
 | `socket.send()` return | Meaning | Action |
@@ -343,25 +357,42 @@ send({ destination, payload: { topic, data } })
 
 ### Room join / leave validation
 
-- **Server-side sanitization** always applies: room must be a non-empty string, at most 256 characters, and must not start with the reserved `ws:` prefix.
-- **`validateRoomFn` gates joins.** Only sanitized rooms reach it; it returns the subset the client may actually join. If unbound, every join is rejected with a warning log.
-- **Leave is filtered against joined rooms.** `handleLeave()` computes `rooms.filter(r => client.rooms.has(r))` before leaving, so a client can never unsubscribe from a room it never joined (or an internal topic). If nothing remains after filtering, the leave is silently ignored.
+- **Server-side sanitization always applies:**
+
+  | Rule | Requirement |
+  |------|-------------|
+  | Type | Non-empty string |
+  | Length | At most 256 characters |
+  | Prefix | Must not start with the reserved `ws:` prefix |
+
+- **`validateRoomFn` gates joins.** Only sanitized rooms reach it. It returns the subset the client may actually join. If unbound, every join is rejected with a warning log.
+- **Leave is filtered against joined rooms.** `handleLeave()` computes `rooms.filter(r => client.rooms.has(r))` before leaving. A client can never unsubscribe from a room it never joined - or an internal topic it was auto-subscribed to.
+  - If nothing remains after filtering, the leave is silently ignored.
 
 ### Graceful shutdown
 
+`WebSocketServerHelper` has a real `shutdown()` method, but `WebSocketComponent` never calls it automatically. Components have no `stop()` lifecycle, and the component does not register a post-stop hook for you.
+
+To disconnect clients cleanly when your application stops, register your own hook with `registerPostStopHook()` - the same mechanism IGNIS's secrets provider uses internally:
+
 ```typescript
-override async stop(): Promise<void> {
-  const wsHelper = this.get<WebSocketServerHelper>({
-    key: WebSocketBindingKeys.WEBSOCKET_INSTANCE,
-    isOptional: true,
-  });
-  if (wsHelper) {
-    await wsHelper.shutdown();
-  }
-  if (this.redisHelper) {
-    await this.redisHelper.disconnect();
+export class Application extends BaseApplication {
+  preConfigure(): ValueOrPromise<void> {
+    // ... bind REDIS_CONNECTION, AUTHENTICATE_HANDLER, register WebSocketComponent ...
+
+    this.registerPostStopHook({
+      identifier: 'websocket-shutdown',
+      hook: async () => {
+        const wsHelper = this.get<WebSocketServerHelper>({
+          key: WebSocketBindingKeys.WEBSOCKET_INSTANCE,
+          isOptional: true,
+        });
+        if (wsHelper) {
+          await wsHelper.shutdown();
+        }
+      },
+    });
   }
-  await super.stop();
 }
 ```
 

package/content/extensions/components/websocket/errors.md

@@ -32,7 +32,7 @@ Every error condition the WebSocket component and helper can raise, plus fixes f
 |--------|-----------|---------------|
 | `binding()` | `application` is falsy | `"[binding] Invalid application to bind WebSocketComponent"` |
 | `binding()` | Node.js runtime detected | `"[WebSocketComponent] Node.js runtime is not supported yet. Please use Bun runtime."` |
-| `resolveBindings()` | `REDIS_CONNECTION` not `instanceof AbstractRedisHelper` | `"[WebSocketComponent][resolveBindings] Invalid instance of redisConnection ..."` |
+| `resolveBindings()` | `REDIS_CONNECTION` fails `isRedisHelper()` | `"[WebSocketComponent][resolveBindings] Invalid instance of redisConnection ..."` |
 | `resolveBindings()` | `AUTHENTICATE_HANDLER` is falsy | `"[WebSocketComponent] Invalid authenticateFn to setup WebSocket server!"` |
 | `registerBunHook()` | Bun server instance not available | `"[WebSocketComponent] Bun server instance not available!"` |
 
@@ -40,12 +40,12 @@ Every error condition the WebSocket component and helper can raise, plus fixes f
 
 ### "WebSocket not initialized"
 
-- **Cause:** `WebSocketServerHelper` was accessed before the server started - e.g. during DI construction.
+- **Cause:** `WebSocketServerHelper` was accessed before the server started - for example during DI construction.
 - **Fix:** Use the lazy getter pattern from [Usage & Examples](./usage). Never `@inject` `WEBSOCKET_INSTANCE` in a constructor - it does not exist yet at that point.
 
 ### "Invalid instance of redisConnection"
 
-- **Cause:** The value bound to `REDIS_CONNECTION` is not an `AbstractRedisHelper` instance - i.e. not a `RedisSingleHelper`, `RedisClusterHelper`, or `RedisSentinelHelper`.
+- **Cause:** The value bound to `REDIS_CONNECTION` is not an `AbstractRedisHelper` instance. It is not a `RedisSingleHelper`, `RedisClusterHelper`, or `RedisSentinelHelper`.
 - **Fix:** Bind one of the concrete topology helpers, not a raw `ioredis` client.
 
 ```typescript