docs(recipes): add object storage, graceful shutdown, and deploy guides

- Add a Graceful Shutdown recipe covering signal handling and drain
- Add an Object Storage recipe using the staticHandler hook
- Add a Production Deploy recipe covering permission flags and binaries
- Register the three recipes in the sidebar nav for both locales

Author: NeaByteLab

docs/.vitepress/config.ts

@@ -245,7 +245,10 @@ export default withMermaid(
                 collapsed: true,
                 items: [
                   { text: 'File Uploads', link: '/recipes/file-upload' },
-                  { text: 'Streaming Data', link: '/recipes/streaming-data' }
+                  { text: 'Streaming Data', link: '/recipes/streaming-data' },
+                  { text: 'Object Storage', link: '/recipes/object-storage' },
+                  { text: 'Graceful Shutdown', link: '/recipes/graceful-shutdown' },
+                  { text: 'Production Deploy', link: '/recipes/production-deploy' }
                 ]
               }
             ]
@@ -432,7 +435,10 @@ export default withMermaid(
                 collapsed: true,
                 items: [
                   { text: 'Upload File', link: '/id/recipes/file-upload' },
-                  { text: 'Streaming Data', link: '/id/recipes/streaming-data' }
+                  { text: 'Streaming Data', link: '/id/recipes/streaming-data' },
+                  { text: 'Object Storage', link: '/id/recipes/object-storage' },
+                  { text: 'Graceful Shutdown', link: '/id/recipes/graceful-shutdown' },
+                  { text: 'Production Deploy', link: '/id/recipes/production-deploy' }
                 ]
               }
             ]

docs/id/recipes/graceful-shutdown.md

@@ -0,0 +1,76 @@
+---
+description: 'Hentikan server Deserve dengan bersih pada SIGINT atau SIGTERM, kuras request yang sedang berjalan, dan jalankan kerja shutdown dengan AbortSignal.'
+---
+
+# Graceful Shutdown
+
+Graceful shutdown menghentikan server menerima koneksi baru sambil membiarkan request yang sedang berjalan selesai, jadi deploy atau restart kontainer tidak pernah memotong response di tengah jalan. Deserve menangani ini secara bawaan, dan sebuah [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) membuka jalan untuk memicunya dari kode.
+
+## Penanganan Sinyal Bawaan
+
+`router.serve()` polos sudah mendengarkan sinyal yang dikirim process manager saat berhenti. Pada `SIGINT` (`Ctrl+C` di terminal) atau `SIGTERM` (yang dikirim Docker dan kebanyakan orchestrator), server berhenti menerima request baru, menguras yang masih berjalan, lalu meresolusi promise `serve()`:
+
+```typescript twoslash
+import { Router } from '@neabyte/deserve'
+
+const router = new Router({
+  routesDir: './routes'
+})
+
+// Resolusi setelah pengurasan selesai
+await router.serve(8000)
+
+// Tercapai hanya setelah shutdown bersih
+console.log('Server stopped')
+```
+
+Windows mendengarkan `SIGINT` saja, karena `SIGTERM` tidak dikirim di sana. Tidak ada penyetelan yang diperlukan untuk jalur ini, jadi server dalam kontainer sudah keluar dengan bersih saat `docker stop`.
+
+## Memicu Shutdown Dari Kode
+
+Meneruskan `AbortSignal` sebagai argumen ketiga menyerahkan pemicu ke aplikasi, yang cocok untuk test yang perlu menghentikan server atau route admin yang mengakhiri proses. Membatalkan controller menguras server dengan cara yang sama seperti sinyal:
+
+```typescript twoslash
+import { Router } from '@neabyte/deserve'
+
+const router = new Router({
+  routesDir: './routes'
+})
+// ---cut---
+const controller = new AbortController()
+
+// Hentikan server setelah tiga puluh detik
+setTimeout(() => controller.abort(), 30_000)
+
+// Abort menguras, lalu serve resolusi
+await router.serve(8000, '0.0.0.0', controller.signal)
+```
+
+Menyerahkan `AbortSignal` mengambil alih pemicu berhenti, jadi listener bawaan `SIGINT` dan `SIGTERM` tetap mati dan controller menjadi satu-satunya cara berhenti. Saat keduanya diinginkan, sambungkan dengan membatalkan controller dari dalam listener sinyal.
+
+## Menjalankan Kerja Saat Shutdown
+
+Pembersihan seperti menutup pool basis data atau membilas buffer berada setelah pengurasan, bukan di dalamnya. Event [`server:shutdown`](/id/middleware/observability/events#server) menyala setelah server selesai dikuras, jadi satu listener [observability](/id/middleware/observability/overview) menjaga kerja shutdown tetap di satu tempat:
+
+```typescript twoslash
+import { Router } from '@neabyte/deserve'
+
+const router = new Router({
+  routesDir: './routes'
+})
+// ---cut---
+router.on((event) => {
+  // Berjalan setelah pengurasan selesai
+  if (event.kind === 'server:shutdown') {
+    console.log('Closing resources')
+  }
+})
+
+await router.serve(8000)
+```
+
+Event pasangannya [`server:listening`](/id/middleware/observability/events#server) menyala saat server mengikat port, jadi kait startup dan shutdown berdampingan di bus yang sama.
+
+## Arti Pengurasan Bagi Sebuah Request
+
+Request yang sedang berjalan saat pengurasan mulai akan tuntas sampai selesai, dan response-nya tetap terkirim. Koneksi yang tiba setelah pengurasan dimulai ditolak, karena listener sudah berhenti menerima. Response berumur panjang adalah satu hal yang perlu diperhatikan, karena [stream](/id/recipes/streaming-data) atau [WebSocket](/id/middleware/websocket) yang terbuka menahan pengurasan sampai koneksi itu ditutup. Membatasi berapa lama satu request boleh berjalan dengan [`requestTimeoutMs`](/id/getting-started/routes-configuration#requesttimeoutms) menjaga pengurasan tidak menunggu selamanya pada handler yang lambat.

docs/id/recipes/object-storage.md

@@ -0,0 +1,151 @@
+---
+description: 'Sajikan berkas dari S3, R2, atau object storage apa pun di Deserve lewat hook staticHandler atau route handler.'
+---
+
+# Object Storage
+
+[Static serving](/id/static-file/basic) bawaan membaca dari filesystem lokal, jadi `router.static()` saja tidak bisa menjangkau bucket di S3, Cloudflare R2, atau Google Cloud Storage. Jembatannya adalah opsi [`staticHandler`](/id/getting-started/routes-configuration#statichandler), sebuah hook yang mempertahankan route static yang familiar sambil menukar pembacaan berkas dengan fetch ke object storage. Route tetap terdaftar lewat `router.static()`, dan handler menjawab tiap request dari bucket alih-alih dari disk.
+
+## Kenapa Hook dan Bukan Path
+
+Opsi `path` pada [static serving](/id/static-file/basic#path) memetakan prefix URL ke folder yang bisa diresolusi `Deno.stat` dan `Deno.realPath`, yang merupakan kontrak disk lokal. Object storage tidak punya path nyata di disk, jadi pemeriksaan traversal yang aman dan streaming lewat file handle tidak berlaku. Hook `staticHandler` menyerahkan seluruh langkah serve, jadi bucket menjadi sumber kebenaran sementara permukaan route tetap sama.
+
+## Menyajikan Dari Bucket
+
+Sebagian besar object store mengekspos endpoint HTTPS per objek, jadi `fetch` ke `${endpoint}/${key}` menarik byte-nya. Handler memotong prefix URL dari `ctx.pathname` untuk memulihkan kunci objek, lalu mengalirkan body response langsung lewat [`ctx.send.stream`](/id/response/stream):
+
+```typescript twoslash
+import { Router, type Context, type ServeOptions } from '@neabyte/deserve'
+
+// Endpoint dasar bucket
+const endpoint = 'https://my-bucket.s3.amazonaws.com'
+
+const router = new Router({
+  routesDir: 'routes',
+  staticHandler: {
+    // Sajikan tiap objek dari bucket
+    async serve(ctx: Context, options: ServeOptions, urlPath: string) {
+      // Pulihkan kunci objek dari path
+      const key = ctx.pathname.slice(urlPath.length).replace(/^\//, '')
+      const object = await fetch(`${endpoint}/${key}`)
+      if (!object.ok || !object.body) {
+        return ctx.handleError(404, new Deno.errors.NotFound('Object not found'))
+      }
+      // Alirkan body bucket ke klien
+      const contentType = object.headers.get('content-type') ?? 'application/octet-stream'
+      return ctx.send.stream(object.body, undefined, contentType)
+    }
+  }
+})
+
+// Daftarkan route yang dipenuhi handler
+router.static(
+  '/assets',
+  {
+    path: 's3'
+  }
+)
+
+await router.serve(8000)
+```
+
+Nilai `path` tetap harus diset pada [`router.static()`](/id/static-file/basic) karena wajib, namun handler mengabaikannya di sini karena bucket menggantikan folder lokal. Request ke `/assets/logo.png` menjadi fetch untuk kunci `logo.png`.
+
+## Meneruskan Byte Range
+
+Static serving menjawab [byte range](/id/static-file/basic#permintaan-byte-range) sendiri, tapi handler kustom kini memegang tugas itu. Meneruskan header `Range` yang masuk ke bucket membiarkan store mengembalikan konten parsial, dan meneruskan kembali status serta header range menjaga penggeser video atau unduhan yang bisa dilanjutkan tetap bekerja:
+
+```typescript twoslash
+import type { Context, ServeOptions } from '@neabyte/deserve'
+declare const endpoint: string
+// ---cut---
+async function serve(ctx: Context, options: ServeOptions, urlPath: string) {
+  const key = ctx.pathname.slice(urlPath.length).replace(/^\//, '')
+  const range = ctx.header('range')
+
+  // Teruskan header Range bila ada
+  const object = await fetch(`${endpoint}/${key}`, {
+    headers: range ? { Range: range } : {}
+  })
+  if (!object.ok || !object.body) {
+    return ctx.handleError(404, new Deno.errors.NotFound('Object not found'))
+  }
+
+  // Cerminkan header range ke klien
+  const contentType = object.headers.get('content-type') ?? 'application/octet-stream'
+  const contentRange = object.headers.get('content-range')
+  if (contentRange) {
+    ctx.setHeader('Content-Range', contentRange)
+    ctx.setHeader('Accept-Ranges', 'bytes')
+  }
+  return ctx.send.custom(object.body, {
+    status: object.status,
+    headers: {
+      'Content-Type': contentType
+    }
+  })
+}
+```
+
+Sebuah `206 Partial Content` dari bucket mengalir balik tanpa berubah, karena `ctx.send.custom` mempertahankan status yang dipilih bucket.
+
+## Memakai Route Handler Sebagai Ganti
+
+Hook `staticHandler` mencakup satu prefix URL utuh, yang cocok untuk folder aset publik. Satu unduhan di balik auth atau logika bisnis lebih cocok dengan [route handler](/id/core-concepts/file-based-routing) biasa, tempat middleware berjalan lebih dulu dan kunci datang dari [route param](/id/core-concepts/route-patterns):
+
+```typescript twoslash
+import type { Context } from '@neabyte/deserve'
+declare const endpoint: string
+// ---cut---
+// routes/files/[key].ts
+export async function GET(ctx: Context): Promise<Response> {
+  const key = ctx.param('key')
+  const object = await fetch(`${endpoint}/${key}`)
+  if (!object.ok || !object.body) {
+    return ctx.handleError(404, new Deno.errors.NotFound('Object not found'))
+  }
+  // Alirkan objek langsung apa adanya
+  const contentType = object.headers.get('content-type') ?? 'application/octet-stream'
+  return ctx.send.stream(object.body, undefined, contentType)
+}
+```
+
+Jalur ini menjalankan rantai middleware penuh, jadi menjaganya dengan [basic auth](/id/middleware/basic-auth) atau pemeriksaan [session](/id/middleware/session) terjadi sebelum bucket disentuh sama sekali.
+
+## Menandatangani Request
+
+Bucket privat butuh request yang ditandatangani, bukan `fetch` polos. Dua jalur cocok:
+
+- **URL presigned** - SDK menandatangani URL berumur pendek, dan handler bisa mengalihkan dengan [`ctx.redirect`](/id/response/redirect) atau mengambilnya sisi server.
+- **SDK sisi server** - klien resmi menandatangani tiap request, misalnya [AWS SDK for JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html) untuk S3 atau binding Cloudflare R2 untuk [Workers](https://developers.cloudflare.com/r2/api/workers/workers-api-reference/).
+
+Jalur mana pun yang menandatangani request, body response tetap mengalir lewat `ctx.send.stream`, jadi bentuk penyajiannya tetap sama.
+
+## Menangani Kegagalan
+
+Object storage menambah panggilan jaringan yang bisa timeout atau ditolak, jadi tiap fetch meneruskan kegagalannya ke [penanganan error terpusat](/id/error-handling/object-details) alih-alih membocorkan error mentah. Objek yang hilang dipetakan ke **404**, sementara gangguan upstream dipetakan ke **502** agar penyebabnya tetap terbaca:
+
+```typescript twoslash
+import type { Context } from '@neabyte/deserve'
+declare const endpoint: string
+// ---cut---
+export async function GET(ctx: Context): Promise<Response> {
+  const key = ctx.param('key')
+  try {
+    const object = await fetch(`${endpoint}/${key}`)
+    if (object.status === 404) {
+      return await ctx.handleError(404, new Deno.errors.NotFound('Object not found'))
+    }
+    // Petakan kegagalan upstream ke 502
+    if (!object.ok || !object.body) {
+      return await ctx.handleError(502, new Error('Object storage unavailable'))
+    }
+    return ctx.send.stream(object.body, undefined, 'application/octet-stream')
+  } catch (error) {
+    // Rutekan tiap gangguan jaringan ke error handling
+    return await ctx.handleError(502, error as Error)
+  }
+}
+```
+
+Membentuk ini menjadi satu response klien tinggal di [Penanganan Error](/id/error-handling/object-details), dan menangkapnya untuk log tinggal di [Pelaporan Error](/id/middleware/observability/errors).

docs/id/recipes/production-deploy.md

@@ -0,0 +1,82 @@
+---
+description: 'Kirim server Deserve ke produksi dengan flag permission Deno yang tepat, perintah run yang terkunci, dan binary terkompilasi mandiri.'
+---
+
+# Production Deploy
+
+Deno berjalan [tanpa permission secara bawaan](https://docs.deno.com/runtime/fundamentals/security/), jadi server produksi hanya mendapat akses yang diserahkan lewat command line. Server Deserve butuh sekumpulan kecil flag yang bisa diprediksi, dan [Deno CLI](https://docs.deno.com/runtime/reference/cli/) yang sama yang menjalankannya secara lokal juga mengompilasinya menjadi satu binary mandiri untuk deploy.
+
+## Daftar Periksa Permission
+
+Server Deserve menyentuh jaringan untuk mengikat port dan disk untuk membaca rute, view, dan berkas statis. Itu memetakan ke tiga flag, sisanya tetap mati kecuali sebuah app membutuhkannya:
+
+| Flag             | Kenapa Deserve membutuhkannya                                | Wajib             |
+| ---------------- | ------------------------------------------------------------ | ----------------- |
+| `--allow-net`    | Mengikat port lewat `Deno.serve` dan menggerakkan `fetch`    | Ya                |
+| `--allow-read`   | Meresolusi folder rute, view, dan berkas statis di disk      | Ya                |
+| `--allow-env`    | Membaca variabel `PORT` saat port datang dari host           | Hanya dengan env  |
+| `--allow-write`  | Tidak dipakai framework, hanya oleh app yang menyimpan berkas | Hanya saat menulis |
+
+Permission write tetap mati untuk server biasa. Route yang menyimpan unggahan ke disk adalah alasan umum menambahkannya, dibatasi ke satu folder seperti pada [Upload File](/id/recipes/file-upload#menyimpan-ke-disk).
+
+## Mengunci Permission
+
+Permission `*` berguna saat membangun, namun produksi lebih terbaca saat tiap flag menyebut persis apa yang boleh disentuhnya. Membatasi `--allow-read` ke folder aset dan `--allow-env` ke satu variabel menjaga permukaan tetap kecil:
+
+```bash
+# Batasi tiap permission ke kebutuhannya
+deno run \
+  --allow-net \
+  --allow-read=./routes,./views,./public \
+  --allow-env=PORT \
+  main.ts
+```
+
+Sebuah [`deno task`](https://docs.deno.com/runtime/reference/cli/task/) di `deno.json` menyimpan perintah panjang itu dan memberi deploy satu nama untuk dipanggil:
+
+```json
+{
+  "tasks": {
+    "start": "deno run --allow-net --allow-read=./routes,./views,./public --allow-env=PORT main.ts"
+  }
+}
+```
+
+Menjalankan `deno task start` lalu meluncurkan server dengan flag terkunci tiap kali.
+
+## Membaca Port Dari Environment
+
+Host biasanya menetapkan port lewat variabel `PORT`. Memanggil `serve()` tanpa port membaca `PORT` lebih dulu dan kembali ke `8000` sebagai default, jadi binary yang sama cocok untuk run lokal dan host terkelola:
+
+```typescript twoslash
+import { Router } from '@neabyte/deserve'
+
+const router = new Router({
+  routesDir: './routes'
+})
+// ---cut---
+// Baca env PORT, fallback ke 8000
+await router.serve()
+```
+
+Membaca variabel itulah yang dicakup `--allow-env=PORT`. Memberi angka eksplisit seperti `serve(8000)` melewati pencarian, jadi flag env jadi tidak relevan saat port di-hardcode. Argumen host dan sinyal lengkap ada di [Graceful Shutdown](/id/recipes/graceful-shutdown).
+
+## Mengompilasi Binary Mandiri
+
+[`deno compile`](https://docs.deno.com/runtime/reference/cli/compile/) menyatukan server dan permission-nya menjadi satu executable yang berjalan tanpa Deno terpasang, yang cocok untuk kontainer ramping atau host polos. Flag permission berada pada perintah compile agar binary membawanya:
+
+```bash
+# Satukan server dan flag-nya jadi binary
+deno compile \
+  --allow-net \
+  --allow-read=./routes,./views,./public \
+  --allow-env=PORT \
+  --output server \
+  main.ts
+```
+
+Hasilnya berjalan langsung dari `./server` dengan flag sudah di dalam. Satu catatan cocok untuk Deserve, karena [hot reload](/id/core-concepts/hot-reload) memantau berkas di disk dan binary terkompilasi menyajikan snapshot tetap, jadi suntingan setelah build perlu compile baru alih-alih pertukaran langsung.
+
+## Mengawasinya Berjalan
+
+Produksi butuh mata pada server tanpa membanjiri konsol dengan cetakan, yang merupakan tujuan [bus event observability](/id/middleware/observability/overview). Satu listener [`router.on()`](/id/middleware/observability/events) meneruskan event lifecycle, request, dan kesalahan ke apa pun yang mengumpulkan log, dan [pelaporan error](/id/middleware/observability/errors) merutekan kegagalan ke tempat yang sama. Berhenti bersih saat deploy dicakup oleh [Graceful Shutdown](/id/recipes/graceful-shutdown), dan memindahkan kerja berat tanpa memblokir server dicakup oleh [worker pool](/id/core-concepts/worker-pool).