You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/patterns/websocket.md
+47-20Lines changed: 47 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,23 +1,25 @@
1
1
---
2
2
title: WebSocket Plugin - Elysia.js
3
3
head:
4
-
- - meta
5
-
- property: 'title'
6
-
content: WebSocket Plugin - Elysia.js
4
+
- - meta
5
+
- property: 'title'
6
+
content: WebSocket Plugin - Elysia.js
7
7
8
-
- - meta
9
-
- name: 'description'
10
-
content: Plugin for Elysia that add support for using WebSocket. Start by registering the plugin and declare WebSocket route with "ws".
8
+
- - meta
9
+
- name: 'description'
10
+
content: Plugin for Elysia that add support for using WebSocket. Start by registering the plugin and declare WebSocket route with "ws".
11
11
12
-
- - meta
13
-
- name: 'og:description'
14
-
content: Plugin for Elysia that add support for using WebSocket. Start by registering the plugin and declare WebSocket route with "ws".
12
+
- - meta
13
+
- name: 'og:description'
14
+
content: Plugin for Elysia that add support for using WebSocket. Start by registering the plugin and declare WebSocket route with "ws".
15
15
---
16
16
17
17
# WebSocket
18
+
18
19
Elysia WebSocket extends Bun's WebSocket which uses [uWebSocket](https://github.com/uNetworking/uWebSockets) under the hood.
19
20
20
21
To start working with a WebSocket, register the Elysia WebSocket plugin, and declare a WebSocket route with `.ws`.
22
+
21
23
```typescript
22
24
import { Elysia, ws } from'elysia'
23
25
@@ -31,47 +33,54 @@ new Elysia()
31
33
.listen(8080)
32
34
```
33
35
34
-
35
36
Just like normal route, WebSockets also accepts a **schema** object to strictly type and validate requests.
36
37
37
38
## Configuration
38
39
39
40
Elysia's WebSocket plugin extends Bun's WebSocket configuration so if you wish to configure the websocket you can refer to [Bun's WebSocket documentation](https://bun.sh/docs/api/websockets) to learn more about this.
40
41
41
-
Below is a config that extends from [Bun WebSocket](https://github.com/oven-sh/bun#websockets-with-bunserve)
42
+
Below is a config that extends from [Bun WebSocket](https://bun.sh/docs/api/websockets#create-a-websocket-server)
42
43
43
44
### perMessageDeflate
45
+
44
46
@default`false`
45
47
46
-
Enable compression for clients that support it.
48
+
Enable compression for clients that support it.
47
49
48
50
By default, compression is disabled.
49
51
50
52
### maxPayloadLength
53
+
51
54
The maximum size of a message.
52
55
53
56
### idleTimeout
57
+
54
58
@default`120`
55
59
56
60
After a connection has not received a message for this many seconds, it will be closed.
57
61
58
62
### backpressureLimit
63
+
59
64
@default`16777216` (16MB)
60
65
61
66
The maximum number of bytes that can be buffered for a single connection.
62
67
63
68
### closeOnBackpressureLimit
69
+
64
70
@default`false`
65
71
66
72
Close the connection if the backpressure limit is reached.
67
73
68
74
## Methods
75
+
69
76
Below are the new methods that are available to the WebSocket plugin
70
77
71
78
## ws
79
+
72
80
Create a websocket handler
73
81
74
82
Example:
83
+
75
84
```typescript
76
85
import { Elysia, ws } from'elysia'
77
86
@@ -86,35 +95,40 @@ new Elysia()
86
95
```
87
96
88
97
Type:
98
+
89
99
```typescript
90
100
.ws(endpoint: path, options: Partial<WebSocketHandler<Context>>): this
91
101
```
92
102
93
-
endpoint: A path to exposed as websocket handler
103
+
endpoint: A path to exposed as websocket handler
94
104
options: Customize WebSocket handler behavior
95
105
96
106
## WebSocketHandler
107
+
97
108
WebSocketHandler extends config from [config](#config).
98
109
99
110
Below is a config which accepted by `ws`.
100
111
101
112
## schema
113
+
102
114
Validatation for an incoming WebSocket request.
103
115
104
-
- headers: validate headers before upgrade to WebSocket
105
-
- params: validate path paramters
106
-
- query: validate query parameters
107
-
- body: validate websocket message
108
-
- response: validate websocket response
116
+
-headers: validate headers before upgrade to WebSocket
117
+
-params: validate path paramters
118
+
-query: validate query parameters
119
+
-body: validate websocket message
120
+
-response: validate websocket response
109
121
110
122
::: tip
111
123
It's recommended to use query parameters instead of path parameters in WebSocket, as parsing path parameters is expensive and sometime unrealiable for multiple data with long value.
112
124
:::
113
125
114
126
## open
127
+
115
128
Callback function for new websocket connection.
116
129
117
130
Type:
131
+
118
132
```typescript
119
133
open(ws: ServerWebSocket<{
120
134
// uid for each connection
@@ -124,26 +138,30 @@ open(ws: ServerWebSocket<{
124
138
```
125
139
126
140
## message
141
+
127
142
Callback function for incoming websocket message.
128
143
129
144
Type:
145
+
130
146
```typescript
131
147
message(
132
148
ws: ServerWebSocket<{
133
149
// uid for each connection
134
150
id:string
135
151
data:Context
136
-
}>,
152
+
}>,
137
153
message: Message
138
154
): this
139
155
```
140
156
141
157
`Message` type based on `schema.message`. Default is `string`.
142
158
143
159
## close
160
+
144
161
Callback function for closing websocket connection.
145
162
146
163
Type:
164
+
147
165
```typescript
148
166
close(ws: ServerWebSocket<{
149
167
// uid for each connection
@@ -153,42 +171,51 @@ close(ws: ServerWebSocket<{
153
171
```
154
172
155
173
## drain
174
+
156
175
Callback function for the server is ready to accept more data.
157
176
158
177
Type:
178
+
159
179
```typescript
160
180
drain(
161
181
ws: ServerWebSocket<{
162
182
// uid for each connection
163
183
id:string
164
184
data:Context
165
-
}>,
185
+
}>,
166
186
code: number,
167
187
reason: string
168
188
): this
169
189
```
170
190
171
191
## parse
192
+
172
193
`Parse` middleware to parse the request before upgrading the HTTP connection to WebSocket.
173
194
174
195
## beforeHandle
196
+
175
197
`Before Handle` middleware which execute before upgrading the HTTP connection to WebSocket.
176
198
177
199
Ideal place for validation.
178
200
179
201
## transform
202
+
180
203
`Transform` middleware which execute before validation.
181
204
182
205
## transformMessage
206
+
183
207
Like `transform`, but execute before validation of WebSocket message
184
208
185
209
## header
210
+
186
211
Additional headers to add before upgrade connection to WebSocket.
187
212
188
213
## Pattern
214
+
189
215
Below you can find the common patterns to use the plugin.
190
216
191
217
## WebSocket message validation:
218
+
192
219
Validate incoming WebSocket message.
193
220
194
221
By default Elysia will parse incoming stringified JSON message as Object for validation.
0 commit comments