feat(deserve): request timeout, session HMAC signing, and docs alignment 🔐

- Add requestTimeoutMs to Handler and Router, return 503 on timeout
- Body limit: remove redundant return so body stream wrapping runs when no early reject
- Docs (EN+ID): body-limit stream behavior, global middleware signature and hang note
- Docs (EN+ID): request timeout in routes-config and server-config
- Docs (EN+ID): session cookieSecret required, setSession async, HMAC
- Session: require cookieSecret, sign cookie with HMAC-SHA256, async setSession
- Types: HandlerOptions and RouterOptions requestTimeoutMs, SessionOptions cookieSecret required
- Update session tests for cookieSecret and async setSession

Author: NeaByteLab

docs/en/getting-started/routes-configuration.md

@@ -4,15 +4,16 @@ Configure Deserve routes directory to match your project structure.
 
 ## Router Options
 
-The `Router` constructor accepts configuration options. The main one is `routesDir` (directory for your route files):
+The `Router` constructor accepts configuration options. Main options: `routesDir` (directory for route files), `requestTimeoutMs` (request timeout), and optional `errorResponseBuilder` / `staticHandler`.
 
 ```typescript
 // 1. Import Router
 import { Router } from '@neabyte/deserve'
 
-// 2. Set custom routesDir (default: ./routes)
+// 2. Set custom routesDir and optional request timeout (default: ./routes, no timeout)
 const router = new Router({
-  routesDir: 'src/routes'
+  routesDir: 'src/routes',
+  requestTimeoutMs: 30_000
 })
 ```
 
@@ -32,6 +33,17 @@ const router = new Router({
 })
 ```
 
+### `requestTimeoutMs`
+
+Optional timeout in milliseconds for the full request (middleware + route handler). If exceeded, the server responds with **503 Service Unavailable**. Omit or leave undefined for no timeout.
+
+```typescript
+const router = new Router({
+  routesDir: 'routes',
+  requestTimeoutMs: 30_000
+})
+```
+
 ## Supported File Extensions
 
 Deserve automatically detects and supports these file extensions:

docs/en/getting-started/server-configuration.md

@@ -57,6 +57,19 @@ await router.serve(8000, '127.0.0.1')
 await router.serve(8000, '0.0.0.0')
 ```
 
+## Request Timeout
+
+You can set a request timeout when creating the router. If middleware and route handler do not finish within that time, the server responds with **503 Service Unavailable**:
+
+```typescript
+const router = new Router({
+  requestTimeoutMs: 30_000
+})
+await router.serve(8000)
+```
+
+Omit `requestTimeoutMs` for no timeout (default).
+
 ## Graceful Shutdown
 
 Use `AbortSignal` for graceful server shutdown:

docs/en/middleware/body-limit.md

@@ -2,7 +2,7 @@
 
 > **Reference**: [RFC 7230 HTTP/1.1 Message Syntax and Routing](https://datatracker.ietf.org/doc/html/rfc7230#section-3.3.1)
 
-Body Limit middleware enforces maximum request body size by checking the `Content-Length` header. Prevents large payloads from overwhelming your server.
+Body Limit middleware enforces maximum request body size. When a body is present, the body stream is always wrapped with a limiter so size is enforced regardless of headers. Prevents large payloads from overwhelming your server.
 
 ## Basic Usage
 
@@ -60,20 +60,16 @@ limit: 10 * 1024 * 1024
 
 ## How It Works
 
-The middleware checks the `Content-Length` header before the body is read:
+When a request has a body, the middleware wraps the body stream with a byte limiter so the size is enforced as the body is read (not only via headers):
 
-1. **GET/HEAD requests** - Automatically skipped (no body)
-2. **Content-Length present** - Validates against limit
-3. **Transfer-Encoding present** - Passes through (chunked encoding)
-4. **No headers** - Passes through (size unknown)
+1. **GET/HEAD or no body** - No wrapping; request passes through.
+2. **Body present** - Body stream is always wrapped with the limiter. If the client sends more bytes than `limit`, reading stops and the middleware responds with **413 Request Entity Too Large**.
+3. **Content-Length** - When present and above `limit`, the middleware may reject the request before reading the body (early reject).
 
-### RFC 7230 Compliance
+### RFC 7230
 
-The middleware follows RFC 7230:
-
-- If both `Transfer-Encoding` and `Content-Length` are present, `Transfer-Encoding` takes precedence and body size is not validated
-- Only validates `Content-Length` when `Transfer-Encoding` is absent
-- Handles chunked encoding by passing through (can't check size upfront)
+- If both `Transfer-Encoding` and `Content-Length` are present, `Transfer-Encoding` takes precedence.
+- Chunked or unknown-length bodies are still limited by the wrapped stream; only the bytes read count toward the limit.
 
 ## Complete Example
 

docs/en/middleware/global.md

@@ -26,12 +26,17 @@ await router.serve(8000)
 ## Middleware Function Signature
 
 ```typescript
-type Middleware = (ctx: Context, next: () => Promise<Response>) => Response | Promise<Response>
+type Middleware = (
+  ctx: Context,
+  next: () => Promise<Response | undefined>
+) => Response | Promise<Response | undefined>
 ```
 
-- **Return `await next()`** - Always called to continue to next middleware or route handler, allows response modification and inspection
-- **Return `Response`** - Stop processing and return response immediately
-- **Return `undefined`** - Pass through middleware (automatically calls `next()`)
+- **Return `await next()`** - Continue to next middleware or route handler; allows response modification and inspection.
+- **Return `Response`** - Stop processing and return that response immediately.
+- **Return `undefined`** - Treated as pass-through (chain continues as if `next()` were called).
+
+Middleware must either call `next()` and use its result or return a `Response`. If it does neither (e.g. never calls `next()` and returns nothing), the request can hang; use `requestTimeoutMs` in `Router` to cap request duration and get a 503 instead.
 
 ## Common Global Middleware Patterns
 

docs/en/middleware/session.md

@@ -1,10 +1,10 @@
 # Session Middleware
 
-Session middleware stores session data in a cookie and exposes it via `ctx.state`, suitable for login, preferences, or per-user state without a session database.
+Session middleware stores session data in a signed cookie and exposes it via `ctx.state`, suitable for login, preferences, or per-user state without a session database. The cookie payload is signed with HMAC-SHA256; **`cookieSecret` is required**.
 
 ## Basic Usage
 
-Use `Mware.session()` to add cookie-based session:
+Use `Mware.session({ cookieSecret })` to add cookie-based session:
 
 ```typescript
 // 1. Import Router and Mware
@@ -13,17 +13,21 @@ import { Router, Mware } from '@neabyte/deserve'
 // 2. Create router
 const router = new Router()
 
-// 3. Apply session middleware (cookie-based)
-router.use(Mware.session())
+// 3. Apply session middleware (cookieSecret required for signing)
+router.use(
+  Mware.session({
+    cookieSecret: Deno.env.get('SESSION_SECRET') ?? 'your-secret-min-32-chars'
+  })
+)
 
 // 4. Start server
 await router.serve(8000)
 ```
 
 After that, in route handlers or middleware:
 
-- **`ctx.state.session`** - Session data (object or `null` if none yet)
-- **`ctx.state.setSession(data)`** - Save data to session (sets cookie)
+- **`ctx.state.session`** - Session data (object or `null` if none or invalid signature)
+- **`ctx.state.setSession(data)`** - Async; saves data to session (sets signed cookie). Use `await ctx.state.setSession(data)`.
 - **`ctx.state.clearSession()`** - Clear session (clear cookie)
 
 ## Example: Login And Logout
@@ -35,9 +39,10 @@ import type { Context } from '@neabyte/deserve'
 export async function POST(ctx: Context): Promise<Response> {
   // 1. Read JSON body (username, password)
   const body = await ctx.json()
-  // 2. Check credentials; if valid, save to session
+  // 2. Check credentials; if valid, save to session (setSession is async)
   if (body?.username === 'admin' && body?.password === 'secret') {
-    ctx.state.setSession({ userId: '1', username: 'admin' })
+    const setSession = ctx.state.setSession as (data: Record<string, unknown>) => Promise<void>
+    await setSession({ userId: '1', username: 'admin' })
     return ctx.send.json({ ok: true })
   }
   // 3. Invalid → 401
@@ -65,12 +70,13 @@ export function DELETE(ctx: Context): Response {
 
 ## Session Options
 
-You can change cookie name, max age, path, and security attributes:
+**`cookieSecret`** is required (used for HMAC-SHA256 signing). You can also set cookie name, max age, path, and security attributes:
 
 ```typescript
-// 1. Apply session with custom options
+// 1. Apply session with cookieSecret and custom options
 router.use(
   Mware.session({
+    cookieSecret: Deno.env.get('SESSION_SECRET') ?? 'fallback-secret-min-32-chars',
     cookieName: 'sid',
     maxAge: 3600,
     path: '/',
@@ -80,15 +86,16 @@ router.use(
 )
 ```
 
-| Option       | Default     | Description                          |
-| ------------ | ----------- | ------------------------------------ |
-| `cookieName` | `'session'` | Cookie name                          |
-| `maxAge`     | `86400`     | Cookie age in seconds (24 hours)     |
-| `path`       | `'/'`       | Cookie path                          |
-| `sameSite`   | `'Lax'`     | `'Strict' \| 'Lax' \| 'None'`       |
-| `httpOnly`   | `true`      | Cookie not accessible from JavaScript |
+| Option         | Default     | Description                                  |
+| -------------- | ----------- | -------------------------------------------- |
+| `cookieSecret` | —           | **Required.** Secret for signing the cookie. |
+| `cookieName`   | `'session'` | Cookie name                                  |
+| `maxAge`       | `86400`     | Cookie age in seconds (24 hours)             |
+| `path`         | `'/'`       | Cookie path                                  |
+| `sameSite`     | `'Lax'`     | `'Strict' \| 'Lax' \| 'None'`                |
+| `httpOnly`     | `true`      | Cookie not accessible from JavaScript        |
 
 ## Limitations
 
-- Session data is stored in the cookie (base64 + JSON). Do not store large or sensitive data; use only for identifiers or small data.
+- Session data is stored in the cookie and signed with HMAC-SHA256. Do not store large or highly sensitive data; use only for identifiers or small data.
 - For server-side or token-based session, use another mechanism (JWT, Redis, etc.) outside this middleware.

docs/id/getting-started/routes-configuration.md

@@ -4,15 +4,16 @@ Konfigurasi direktori routes Deserve agar sesuai dengan struktur proyek Anda.
 
 ## Opsi Router
 
-Konstruktor `Router` menerima opsi konfigurasi. Opsi utama yang sering dipakai adalah `routesDir` (direktori tempat file route Anda):
+Konstruktor `Router` menerima opsi konfigurasi. Opsi utama: `routesDir` (direktori file route), `requestTimeoutMs` (timeout request), serta opsional `errorResponseBuilder` / `staticHandler`.
 
 ```typescript
 // 1. Import Router
 import { Router } from '@neabyte/deserve'
 
-// 2. Beri routesDir custom (default: ./routes)
+// 2. routesDir custom dan opsional request timeout (default: ./routes, tanpa timeout)
 const router = new Router({
-  routesDir: 'src/routes'
+  routesDir: 'src/routes',
+  requestTimeoutMs: 30_000
 })
 ```
 
@@ -32,6 +33,17 @@ const router = new Router({
 })
 ```
 
+### `requestTimeoutMs`
+
+Opsi timeout dalam milidetik untuk seluruh request (middleware + route handler). Jika terlampaui, server merespons **503 Service Unavailable**. Omit atau biarkan undefined untuk tanpa timeout.
+
+```typescript
+const router = new Router({
+  routesDir: 'routes',
+  requestTimeoutMs: 30_000
+})
+```
+
 ## Ekstensi File Yang Didukung
 
 Deserve secara otomatis mendeteksi dan mendukung ekstensi file ini:

docs/id/getting-started/server-configuration.md

@@ -57,6 +57,19 @@ await router.serve(8000, '127.0.0.1')
 await router.serve(8000, '0.0.0.0')
 ```
 
+## Request Timeout
+
+Anda bisa mengatur timeout request saat membuat router. Jika middleware dan route handler tidak selesai dalam waktu tersebut, server merespons **503 Service Unavailable**:
+
+```typescript
+const router = new Router({
+  requestTimeoutMs: 30_000
+})
+await router.serve(8000)
+```
+
+Omit `requestTimeoutMs` untuk tanpa timeout (default).
+
 ## Graceful Shutdown
 
 Gunakan `AbortSignal` untuk graceful server shutdown:

docs/id/middleware/body-limit.md

@@ -2,7 +2,7 @@
 
 > **Referensi**: [RFC 7230 HTTP/1.1 Message Syntax and Routing](https://datatracker.ietf.org/doc/html/rfc7230#section-3.3.1)
 
-Middleware Body Limit menegakkan ukuran body request maksimum dengan memeriksa header `Content-Length`. Mencegah payload besar yang dapat membebani server Anda.
+Middleware Body Limit menegakkan ukuran body request maksimum. Jika body ada, stream body selalu dibungkus dengan limiter sehingga ukuran ditegakkan terlepas dari header. Mencegah payload besar yang dapat membebani server Anda.
 
 ## Penggunaan Dasar
 
@@ -60,20 +60,16 @@ limit: 10 * 1024 * 1024
 
 ## Cara Kerja Body Limit
 
-Middleware memeriksa header `Content-Length` sebelum body dibaca:
+Jika request punya body, middleware membungkus stream body dengan byte limiter sehingga ukuran ditegakkan saat body dibaca (bukan hanya lewat header):
 
-1. **Request GET/HEAD** - Secara otomatis dilewati (tidak ada body)
-2. **Content-Length ada** - Memvalidasi terhadap limit
-3. **Transfer-Encoding ada** - Melewati (chunked encoding)
-4. **Tidak ada header** - Melewati (ukuran tidak diketahui)
+1. **GET/HEAD atau tanpa body** - Tidak dibungkus; request dilewati.
+2. **Body ada** - Stream body selalu dibungkus dengan limiter. Jika klien mengirim byte lebih dari `limit`, pembacaan dihentikan dan middleware merespons **413 Request Entity Too Large**.
+3. **Content-Length** - Jika ada dan di atas `limit`, middleware bisa menolak request sebelum membaca body (early reject).
 
-### Kepatuhan RFC 7230
+### RFC 7230
 
-Middleware mengikuti RFC 7230:
-
-- Jika `Transfer-Encoding` dan `Content-Length` keduanya ada, `Transfer-Encoding` memiliki prioritas dan ukuran body tidak divalidasi
-- Hanya memvalidasi `Content-Length` ketika `Transfer-Encoding` tidak ada
-- Menangani chunked encoding dengan melewati (tidak dapat memeriksa ukuran sebelumnya)
+- Jika `Transfer-Encoding` dan `Content-Length` keduanya ada, `Transfer-Encoding` diutamakan.
+- Body chunked atau ukuran tidak diketahui tetap dibatasi oleh stream yang dibungkus; hanya byte yang dibaca yang dihitung ke limit.
 
 ## Contoh Lengkap
 

docs/id/middleware/global.md

@@ -26,12 +26,17 @@ await router.serve(8000)
 ## Signature Fungsi Middleware
 
 ```typescript
-type Middleware = (ctx: Context, next: () => Promise<Response>) => Response | Promise<Response>
+type Middleware = (
+  ctx: Context,
+  next: () => Promise<Response | undefined>
+) => Response | Promise<Response | undefined>
 ```
 
-- **Return `await next()`** - Selalu dipanggil untuk melanjutkan ke middleware atau route handler berikutnya, memungkinkan modifikasi dan inspeksi response
-- **Return `Response`** - Hentikan pemrosesan dan kembalikan response segera
-- **Return `undefined`** - Lewati middleware (otomatis memanggil `next()`)
+- **Return `await next()`** - Lanjut ke middleware atau route handler berikutnya; memungkinkan modifikasi dan inspeksi response.
+- **Return `Response`** - Hentikan pemrosesan dan kembalikan response tersebut.
+- **Return `undefined`** - Dianggap pass-through (rantai berlanjut seperti `next()` dipanggil).
+
+Middleware harus memanggil `next()` dan memakai hasilnya atau mengembalikan `Response`. Jika tidak (mis. tidak pernah memanggil `next()` dan tidak return apa-apa), request bisa hang; gunakan `requestTimeoutMs` di `Router` untuk membatasi durasi request dan mendapat 503.
 
 ## Pola Middleware Global Umum
 
@@ -67,7 +72,8 @@ router.use(async (ctx, next) => {
   if (!isValidToken(token)) {
     return ctx.send.text('Invalid token', { status: 401 })
   }
-  // 4. Valid → lanjut ke next (return await next())
+  // 4. Valid → lanjut
+  return await next()
 })
 ```