feat(docs): document worker queue limits and subsystem events

- Add maxQueueDepth and maxQueueWaitMs worker-pool options
- Add worker, session, and csrf lifecycle event reference entries
- Update taskTimeoutMs default to 5000 and note fault events
- Update type definitions for the new options and events

Author: NeaByteLab

docs/.vitepress/deserve-types.ts

@@ -459,6 +459,10 @@ export interface WebSocketOptions {
 
 /** Worker pool creation options. */
 export interface WorkerPoolOptions {
+  /** Maximum pending tasks before fast-rejecting */
+  readonly maxQueueDepth?: number
+  /** Maximum projected queue wait in ms */
+  readonly maxQueueWaitMs?: number
   /** Number of workers in pool */
   readonly poolSize?: number
   /** URL to worker script module */
@@ -571,8 +575,12 @@ export interface RouterOptions {
   readonly trustProxy?: TrustProxyConfig
   /** Directory path for template views */
   readonly viewsDir?: string
-  /** Maximum loop iterations allowed */
+  /** Maximum loop iterations per #each block */
   readonly maxIterations?: number
+  /** Maximum #each body executions per render */
+  readonly maxRenderIterations?: number
+  /** Maximum total output characters per render */
+  readonly maxOutputSize?: number
   /** Worker pool configuration options */
   readonly worker?: WorkerPoolOptions
 }
@@ -633,6 +641,18 @@ export type EventBase =
       error?: Error
     }
   >
+  | LifecycleEvent<'worker:timeout', { workerIndex: number; timeoutMs: number; error: Error }>
+  | LifecycleEvent<'worker:crash', { workerIndex: number; error: Error }>
+  | LifecycleEvent<'worker:respawn', { workerIndex: number }>
+  | LifecycleEvent<
+    'worker:rejected',
+    { reason: 'queue-depth' | 'queue-wait'; queueDepth: number; maxQueueDepth: number }
+  >
+  | LifecycleEvent<
+    'session:invalid',
+    { cookieName: string; reason: 'tampered' | 'expired' | 'malformed' }
+  >
+  | LifecycleEvent<'csrf:rule-error', { rule: 'origin' | 'secFetchSite'; error: Error }>
 
 /** Discriminant value of a lifecycle event. */
 export type EventKind = EventBase['kind']

docs/core-concepts/worker-pool.md

@@ -76,10 +76,21 @@ import type { Context, WorkerRunHandle } from '@neabyte/deserve'
 export async function GET(ctx: Context): Promise<Response> {
   const worker = ctx.getState<WorkerRunHandle>('worker' as never)
   if (!worker) {
-    return ctx.send.json({ error: 'Worker not enabled' }, { status: 503 })
+    return ctx.send.json(
+      {
+        error: 'Worker not enabled'
+      },
+      {
+        status: 503
+      }
+    )
   }
-  const result = await worker.run<{ done: boolean; value: number }>({ iterations: 50_000 })
-  return ctx.send.json({ value: result?.value })
+  const result = await worker.run<{ done: boolean; value: number }>({
+    iterations: 50_000
+  })
+  return ctx.send.json({
+    value: result?.value
+  })
 }
 ```
 
@@ -105,7 +116,7 @@ worker: {
 
 ### `taskTimeoutMs`
 
-Per-task timeout in milliseconds. Default is **30000**. A task that runs longer rejects with a timeout error and the worker is respawned.
+Per-task timeout in milliseconds. Default is **5000**. A task that runs longer rejects with a timeout error, the slot is reclaimed, and the worker is respawned. The reclaim surfaces as a [`worker:timeout`](/middleware/observability/events#workers) event followed by [`worker:respawn`](/middleware/observability/events#workers).
 
 ```typescript
 worker: {
@@ -114,6 +125,31 @@ worker: {
 }
 ```
 
+### `maxQueueDepth`
+
+Maximum accepted-but-unsettled tasks the pool holds before turning new work away. Default is the worker count times **8**, so a pool of 4 holds up to 32. Once the ceiling is hit a new dispatch is refused immediately rather than queued, which keeps a flood of work from piling up without bound:
+
+```typescript
+worker: {
+  scriptURL: workerScriptUrl,
+  poolSize: 4,
+  maxQueueDepth: 64
+}
+```
+
+### `maxQueueWaitMs`
+
+Maximum projected wait, measured as the chosen slot's pending count times `taskTimeoutMs`, before a dispatch is refused. Default is **2000**. A task that would otherwise sit behind a long backlog is turned away fast instead of waiting:
+
+```typescript
+worker: {
+  scriptURL: workerScriptUrl,
+  maxQueueWaitMs: 5_000
+}
+```
+
+A refused dispatch rejects right away and surfaces as a [`worker:rejected`](/middleware/observability/events#workers) event, with `reason` saying whether `maxQueueDepth` or `maxQueueWaitMs` tripped it.
+
 ## Complete Example (Inline Worker)
 
 Using an inline worker script with `Blob` and `createObjectURL`:
@@ -127,13 +163,21 @@ self.onmessage = (e) => {
   const n = Math.max(0, Number(data.iterations) || 50000)
   let value = 0
   for (let i = 0; i < n; i++) value += Math.sqrt(i)
-  self.postMessage({ done: true, value })
+  self.postMessage({
+    done: true,
+    value
+  })
 }
 export {}
 `
 
 const workerScriptUrl = URL.createObjectURL(
-  new Blob([workerCode], { type: 'application/javascript' })
+  new Blob(
+    [workerCode],
+    {
+      type: 'application/javascript'
+    }
+  )
 )
 
 const router = new Router({
@@ -151,10 +195,11 @@ await router.serve(8000)
 
 - **No pool:** A router created without `worker` leaves `ctx.getState('worker' as never)` undefined. Return 503 or a clear message when the route requires a worker.
 - **Worker error:** When the worker calls `postMessage({ error: true, message: '...' })`, `worker.run()` rejects with an `Error` carrying that message. Without a message, the error reads `Worker returned an error with no message`.
-- **Worker crash:** When the worker throws or crashes, `run()` rejects with `Worker task failed before responding`.
-- **Task timeout:** When a task runs past `taskTimeoutMs` (default 30000), `run()` rejects with `Worker task exceeded <ms>ms timeout`.
+- **Worker crash:** When the worker throws or crashes, `run()` rejects with `Worker task failed before responding`, and the slot recovers on its own.
+- **Task timeout:** When a task runs past `taskTimeoutMs` (default 5000), `run()` rejects with `Worker task exceeded <ms>ms timeout`.
+- **Refused under load:** When the pool is at `maxQueueDepth` or the projected wait passes `maxQueueWaitMs`, `run()` rejects with a queue-full or slot-busy error before the task ever starts.
 
-Catch a rejected task and forward it to the [centralized error handler](/error-handling/object-details):
+Every one of these faults also streams through the observability bus as a [worker event](/middleware/observability/events#workers), so a stall, crash, recovery, or refusal is visible without touching the request path. Catch a rejected task and forward it to the [centralized error handler](/error-handling/object-details):
 
 ```typescript
 try {

docs/id/core-concepts/worker-pool.md

@@ -67,7 +67,7 @@ self.postMessage({
 
 ### 3. Pakai di Rute
 
-Handle worker tinggal di framework state, jadi `ctx.getState` menjangkaunya dengan tipe `WorkerRunHandle`. Router yang dibuat tanpa `worker` membiarkan handle undefined, yang merupakan momen untuk mengembalikan 503:
+Handle worker tinggal di framework state, jadi `ctx.getState` menjangkaunya dengan tipe `WorkerRunHandle`. Router yang dibuat tanpa `worker` membiarkan handle undefined, dan di situlah saatnya mengembalikan 503:
 
 ```typescript twoslash
 // routes/heavy.ts
@@ -76,10 +76,21 @@ import type { Context, WorkerRunHandle } from '@neabyte/deserve'
 export async function GET(ctx: Context): Promise<Response> {
   const worker = ctx.getState<WorkerRunHandle>('worker' as never)
   if (!worker) {
-    return ctx.send.json({ error: 'Worker not enabled' }, { status: 503 })
+    return ctx.send.json(
+      {
+        error: 'Worker not enabled'
+      },
+      {
+        status: 503
+      }
+    )
   }
-  const result = await worker.run<{ done: boolean; value: number }>({ iterations: 50_000 })
-  return ctx.send.json({ value: result?.value })
+  const result = await worker.run<{ done: boolean; value: number }>({
+    iterations: 50_000
+  })
+  return ctx.send.json({
+    value: result?.value
+  })
 }
 ```
 
@@ -105,7 +116,7 @@ worker: {
 
 ### `taskTimeoutMs`
 
-Timeout per tugas dalam milidetik. Default adalah **30000**. Tugas yang berjalan lebih lama ditolak dengan error timeout dan worker dilahirkan ulang.
+Timeout per tugas dalam milidetik. Default adalah **5000**. Tugas yang berjalan lebih lama ditolak dengan error timeout, slot direklaim, dan worker dijalankan ulang. Reklaim ini muncul sebagai event [`worker:timeout`](/id/middleware/observability/events#worker) lalu [`worker:respawn`](/id/middleware/observability/events#worker).
 
 ```typescript
 worker: {
@@ -114,6 +125,31 @@ worker: {
 }
 ```
 
+### `maxQueueDepth`
+
+Maksimum tugas diterima-tapi-belum-selesai yang ditahan pool sebelum menolak pekerjaan baru. Default adalah jumlah worker dikali **8**, jadi pool 4 menahan hingga 32. Begitu batas tercapai, dispatch baru ditolak langsung alih-alih diantrekan, sehingga banjir pekerjaan tidak menumpuk tanpa batas:
+
+```typescript
+worker: {
+  scriptURL: workerScriptUrl,
+  poolSize: 4,
+  maxQueueDepth: 64
+}
+```
+
+### `maxQueueWaitMs`
+
+Maksimum proyeksi tunggu, diukur sebagai jumlah tugas pending pada slot terpilih dikali `taskTimeoutMs`, sebelum dispatch ditolak. Default adalah **2000**. Tugas yang seharusnya menunggu di belakang antrean panjang ditolak cepat alih-alih menunggu:
+
+```typescript
+worker: {
+  scriptURL: workerScriptUrl,
+  maxQueueWaitMs: 5_000
+}
+```
+
+Dispatch yang ditolak langsung gagal dan muncul sebagai event [`worker:rejected`](/id/middleware/observability/events#worker), dengan `reason` menyebut apakah `maxQueueDepth` atau `maxQueueWaitMs` yang memicunya.
+
 ## Contoh Lengkap (Worker Inline)
 
 Memakai script worker inline dengan `Blob` dan `createObjectURL`:
@@ -127,13 +163,21 @@ self.onmessage = (e) => {
   const n = Math.max(0, Number(data.iterations) || 50000)
   let value = 0
   for (let i = 0; i < n; i++) value += Math.sqrt(i)
-  self.postMessage({ done: true, value })
+  self.postMessage({
+    done: true,
+    value
+  })
 }
 export {}
 `
 
 const workerScriptUrl = URL.createObjectURL(
-  new Blob([workerCode], { type: 'application/javascript' })
+  new Blob(
+    [workerCode],
+    {
+      type: 'application/javascript'
+    }
+  )
 )
 
 const router = new Router({
@@ -151,10 +195,11 @@ await router.serve(8000)
 
 - **Tanpa pool:** Router yang dibuat tanpa `worker` membiarkan `ctx.getState('worker' as never)` undefined. Kembalikan 503 atau pesan jelas ketika rute butuh worker.
 - **Error worker:** Ketika worker memanggil `postMessage({ error: true, message: '...' })`, `worker.run()` ditolak dengan `Error` yang membawa pesan itu. Tanpa pesan, error berbunyi `Worker returned an error with no message`.
-- **Crash worker:** Ketika worker melempar atau crash, `run()` ditolak dengan `Worker task failed before responding`.
-- **Timeout tugas:** Ketika tugas berjalan melewati `taskTimeoutMs` (default 30000), `run()` ditolak dengan `Worker task exceeded <ms>ms timeout`.
+- **Crash worker:** Ketika worker melempar atau crash, `run()` ditolak dengan `Worker task failed before responding`, dan slot pulih dengan sendirinya.
+- **Timeout tugas:** Ketika tugas berjalan melewati `taskTimeoutMs` (default 5000), `run()` ditolak dengan `Worker task exceeded <ms>ms timeout`.
+- **Ditolak di bawah beban:** Ketika pool mencapai `maxQueueDepth` atau proyeksi tunggu melewati `maxQueueWaitMs`, `run()` ditolak dengan error antrean-penuh atau slot-sibuk sebelum tugas sempat mulai.
 
-Tangkap tugas yang ditolak dan teruskan ke [error handler terpusat](/id/error-handling/object-details):
+Setiap kesalahan ini juga mengalir lewat bus observability sebagai [event worker](/id/middleware/observability/events#worker), jadi stall, crash, pemulihan, atau penolakan terlihat tanpa menyentuh jalur request. Tangkap tugas yang ditolak dan teruskan ke [error handler terpusat](/id/error-handling/object-details):
 
 ```typescript
 try {

docs/id/middleware/csrf.md

@@ -35,7 +35,9 @@ import { Mware, Router } from '@neabyte/deserve'
 const router = new Router()
 // ---cut---
 // Satu origin tepercaya
-router.use(Mware.csrf({ origin: 'https://app.example.com' }))
+router.use(Mware.csrf({
+  origin: 'https://app.example.com'
+}))
 
 // Daftar origin tepercaya
 router.use(
@@ -99,3 +101,5 @@ type CsrfRulePredicate = (value: string, ctx: Context) => boolean
 ## Penanganan Error
 
 Ketika request diblokir, middleware mengembalikan pesan `Request blocked by CSRF protection` dengan **status code 403**. Untuk membentuk response itu, daftarkan satu handler dengan [`router.catch()`](/id/error-handling/object-details), atau andalkan [perilaku default](/id/error-handling/default-behavior).
+
+Aturan `origin` atau `secFetchSite` kustom yang melempar gagal pemeriksaannya sendiri dan jatuh aman ke penolakan, dan kesalahannya muncul sebagai event [`csrf:rule-error`](/id/middleware/observability/events#middleware) yang menyebut aturan mana yang rusak alih-alih tetap tersembunyi.

docs/id/middleware/observability/errors.md

@@ -13,7 +13,9 @@ Error muncul di bus [`router.on()`](/id/middleware/observability/overview) yang
 ```typescript twoslash
 import { Router } from '@neabyte/deserve'
 
-const router = new Router({ routesDir: './routes' })
+const router = new Router({
+  routesDir: './routes'
+})
 
 // Catat setiap request gagal
 router.on((event) => {
@@ -40,7 +42,9 @@ await router.serve(8000)
 ```typescript twoslash
 import { Router } from '@neabyte/deserve'
 
-const router = new Router({ routesDir: './routes' })
+const router = new Router({
+  routesDir: './routes'
+})
 // ---cut---
 router.on((event) => {
   if (event.kind === 'process:error') {
@@ -51,9 +55,28 @@ router.on((event) => {
 })
 ```
 
+## Menangkap Kesalahan Subsistem
+
+Listener yang sama menangkap kesalahan dari worker pool dan middleware bawaan. Task yang timeout, worker yang crash, dispatch yang ditolak di bawah beban, cookie session yang gagal didekode, dan aturan CSRF yang melempar masing-masing tiba sebagai event-nya sendiri. Saring berdasarkan kind yang terdaftar di [Referensi Event](/id/middleware/observability/events#worker) untuk merutekannya ke tempat log:
+
+```typescript twoslash
+import { Router } from '@neabyte/deserve'
+
+const router = new Router({
+  routesDir: './routes'
+})
+// ---cut---
+router.on((event) => {
+  // Bereaksi pada kesalahan worker dan middleware
+  if (event.kind === 'worker:crash' || event.kind === 'session:invalid') {
+    console.error(event.kind, event.metadata)
+  }
+})
+```
+
 ## Memasangkan Dengan Penanganan Error
 
-Dua hook menutup tugas berbeda:
+Dua hook menangani tugas berbeda:
 
 - [`router.catch()`](/id/error-handling/object-details) membentuk response yang diterima klien.
 - `router.on()` mencatat apa yang terjadi untuk log dan metrik.
@@ -65,11 +88,20 @@ Pakai `catch` untuk mengontrol balasan, dan `on` untuk mengamatinya. Pengaturan
 ```typescript twoslash
 import { Router } from '@neabyte/deserve'
 
-const router = new Router({ routesDir: './routes' })
+const router = new Router({
+  routesDir: './routes'
+})
 // ---cut---
 // Bentuk response klien
 router.catch((ctx, info) => {
-  return ctx.send.json({ error: 'Something went wrong' }, { status: info.statusCode })
+  return ctx.send.json(
+    {
+      error: 'Something went wrong'
+    },
+    {
+      status: info.statusCode
+    }
+  )
 })
 
 // Catat kegagalan untuk nanti

docs/id/middleware/observability/events.md

@@ -6,7 +6,7 @@ description: "Referensi semua event siklus hidup dan error yang dipancarkan rout
 
 Setiap event dari [`router.on()`](/id/middleware/observability/overview) membawa diskriminan `kind` dan objek `metadata`. Halaman ini mendaftar setiap jenis dan field yang disediakannya.
 
-![Event request bernilai external secara default tapi jadi internal ketika timeout, error framework, atau context yang hilang yang memicunya, sementara setiap kind non-request selalu internal, jadi merutekan berdasarkan field type menjaga lalu lintas klien normal tetap di luar kanal alert kesalahan](/diagrams/obs-event-channel.png)
+![Event request bernilai external secara default tapi jadi internal ketika dipicu oleh timeout, error framework, atau context yang hilang, sementara setiap kind non-request selalu internal, jadi merutekan berdasarkan field type menjaga lalu lintas klien normal tetap di luar kanal alert kesalahan](/diagrams/obs-event-channel.png)
 
 ## Server
 
@@ -15,7 +15,7 @@ Setiap event dari [`router.on()`](/id/middleware/observability/overview) membawa
 | `server:listening`  | `port`, `hostname`        |
 | `server:shutdown`   | tidak ada                 |
 
-`server:listening` menyala saat server mengikat port. `server:shutdown` menyala setelah server selesai dikuras.
+`server:listening` menyala saat server mengikat port. `server:shutdown` menyala setelah server selesai menuntaskan request berjalan.
 
 ## Rute
 
@@ -41,6 +41,26 @@ Event reload datang dari hot reload saat berkas berubah di disk.
 
 Event view datang dari [mesin rendering DVE](/id/rendering/).
 
+## Worker
+
+| Kind              | Metadata                                          |
+| ----------------- | ------------------------------------------------- |
+| `worker:timeout`  | `workerIndex`, `timeoutMs`, `error`               |
+| `worker:crash`    | `workerIndex`, `error`                            |
+| `worker:respawn`  | `workerIndex`                                     |
+| `worker:rejected` | `reason` (`queue-depth`, `queue-wait`), `queueDepth`, `maxQueueDepth` |
+
+`worker:timeout` menyala saat sebuah task melewati tenggatnya, `worker:crash` saat worker mati di tengah task, dan `worker:respawn` saat slot yang dibebaskan diganti. `worker:rejected` menyala saat sebuah dispatch ditolak di bawah beban, dengan `reason` menyebut apakah kedalaman antrean atau proyeksi tunggu yang memicu batas. Ini datang dari [worker pool](/id/core-concepts/worker-pool).
+
+## Middleware
+
+| Kind              | Metadata                                          |
+| ----------------- | ------------------------------------------------- |
+| `session:invalid` | `cookieName`, `reason` (`tampered`, `expired`, `malformed`) |
+| `csrf:rule-error` | `rule` (`origin`, `secFetchSite`), `error`        |
+
+`session:invalid` menyala saat cookie bertanda tangan gagal didekode, dengan `reason` menyebut apakah nilainya dirusak, sudah lewat `maxAge`, atau malformed, sementara request lanjut tanpa session terpasang. Ini datang dari [middleware session](/id/middleware/session). `csrf:rule-error` menyala saat aturan CSRF kustom melempar, menyebut aturan mana yang rusak sementara pemeriksaan tetap jatuh aman ke penolakan. Ini datang dari [middleware CSRF](/id/middleware/csrf).
+
 ## Request
 
 | Kind                | Metadata                                            |