Skip to content

Commit e6ea3ad

Browse files
committed
docs(websocket): document boundary-aware listener matching
- Explain exact or slash-boundary path match with examples - Note trailing slash stripping and root listener behavior
1 parent a5cccf4 commit e6ea3ad

2 files changed

Lines changed: 16 additions & 12 deletions

File tree

docs/id/middleware/websocket.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,15 +38,17 @@ await router.serve(8000)
3838
Tentukan prefix path untuk upgrade WebSocket:
3939

4040
```typescript
41-
listener: '/ws' // Cocok /ws, /ws/chat, /ws/room/123, dll.
42-
listener: '/api/ws' // Cocok /api/ws, /api/ws/data, dll.
41+
listener: '/ws' // Cocok /ws, /ws/chat, /ws/room/123
42+
listener: '/api/ws' // Cocok /api/ws, /api/ws/data
4343
```
4444

45+
Pencocokan sadar-batas, jadi path harus sama persis dengan `listener` atau berlanjut dengan `/`. Dengan `listener: '/ws'`, request ke `/ws` atau `/ws/chat` di-upgrade, tapi `/wsfoo` tidak. Garis miring di akhir `listener` dipangkas, jadi `/ws/` berperilaku sama dengan `/ws`. Mengatur `listener: '/'` mencocokkan setiap path.
46+
4547
**Penting:** Middleware hanya mengupgrade request yang:
4648

4749
- Membawa header `Upgrade: websocket`
4850
- Memakai metode `GET`
49-
- Punya path yang dimulai dengan nilai `listener`
51+
- Cocok dengan path `listener` seperti dijelaskan di atas
5052

5153
Tanpa `listener`, middleware meneruskan setiap request dan tidak pernah mengupgrade.
5254

@@ -225,10 +227,10 @@ onConnect: (socket, event, ctx) => {
225227

226228
Handshake yang ditolak diarahkan lewat error handler alih-alih melempar saat setup:
227229

228-
- **Origin tidak diizinkan** mengembalikan **403** dengan pesan `WebSocket handshake rejected because the Origin is not allowed`.
229-
- **Upgrade tidak valid** mengembalikan **400** dengan pesan `WebSocket handshake is malformed because ...`.
230+
- **Origin tidak diizinkan** gagal dengan **403** dan pesan `WebSocket handshake rejected because the Origin is not allowed`.
231+
- **Upgrade tidak valid** gagal dengan **400** dan pesan `WebSocket handshake is malformed because ...`.
230232

231-
Untuk membentuk response ini, daftarkan satu handler dengan [`router.catch()`](/id/error-handling/object-details), atau andalkan [perilaku default](/id/error-handling/default-behavior).
233+
Keduanya dialirkan ke [error handler terpusat](/id/error-handling/object-details), jadi bentuk response di sana atau andalkan [perilaku default](/id/error-handling/default-behavior).
232234

233235
## Integrasi Dengan CORS
234236

docs/middleware/websocket.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,15 +38,17 @@ await router.serve(8000)
3838
Specify the path prefix for WebSocket upgrades:
3939

4040
```typescript
41-
listener: '/ws' // Matches /ws, /ws/chat, /ws/room/123, etc.
42-
listener: '/api/ws' // Matches /api/ws, /api/ws/data, etc.
41+
listener: '/ws' // Matches /ws, /ws/chat, /ws/room/123
42+
listener: '/api/ws' // Matches /api/ws, /api/ws/data
4343
```
4444

45+
Matching is boundary-aware, so the path must equal the `listener` exactly or continue with a `/`. With `listener: '/ws'`, a request to `/ws` or `/ws/chat` upgrades, but `/wsfoo` does not. A trailing slash on the `listener` is stripped, so `/ws/` behaves the same as `/ws`. Setting `listener: '/'` matches every path.
46+
4547
**Important:** The middleware only upgrades requests that:
4648

4749
- Carry the `Upgrade: websocket` header
4850
- Use the `GET` method
49-
- Have a path that starts with the `listener` value
51+
- Match the `listener` path as described above
5052

5153
Without a `listener`, the middleware passes every request through and never upgrades.
5254

@@ -225,10 +227,10 @@ onConnect: (socket, event, ctx) => {
225227

226228
A rejected handshake routes through the error handler instead of throwing at setup:
227229

228-
- **Disallowed origin** returns **403** with message `WebSocket handshake rejected because the Origin is not allowed`.
229-
- **Malformed upgrade** returns **400** with message `WebSocket handshake is malformed because ...`.
230+
- **Disallowed origin** fails with **403** and message `WebSocket handshake rejected because the Origin is not allowed`.
231+
- **Malformed upgrade** fails with **400** and message `WebSocket handshake is malformed because ...`.
230232

231-
To shape these responses, register a single handler with [`router.catch()`](/error-handling/object-details), or rely on the [default behavior](/error-handling/default-behavior).
233+
Both route through the [central error handler](/error-handling/object-details), so shape the response there or rely on the [default behavior](/error-handling/default-behavior).
232234

233235
## Integration with CORS
234236

0 commit comments

Comments
 (0)