Skip to content

Commit 5992f08

Browse files
authored
Merge pull request #32 from gtrabanco/fix/bun_link
fix: wrong link to documentation of Bun.serve using websockets
2 parents 6b106b8 + 397e36b commit 5992f08

File tree

1 file changed

+47
-20
lines changed

1 file changed

+47
-20
lines changed

docs/patterns/websocket.md

Lines changed: 47 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,25 @@
11
---
22
title: WebSocket Plugin - Elysia.js
33
head:
4-
- - meta
5-
- property: 'title'
6-
content: WebSocket Plugin - Elysia.js
4+
- - meta
5+
- property: 'title'
6+
content: WebSocket Plugin - Elysia.js
77

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".
1111

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".
1515
---
1616

1717
# WebSocket
18+
1819
Elysia WebSocket extends Bun's WebSocket which uses [uWebSocket](https://github.com/uNetworking/uWebSockets) under the hood.
1920

2021
To start working with a WebSocket, register the Elysia WebSocket plugin, and declare a WebSocket route with `.ws`.
22+
2123
```typescript
2224
import { Elysia, ws } from 'elysia'
2325

@@ -31,47 +33,54 @@ new Elysia()
3133
.listen(8080)
3234
```
3335

34-
3536
Just like normal route, WebSockets also accepts a **schema** object to strictly type and validate requests.
3637

3738
## Configuration
3839

3940
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.
4041

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)
4243

4344
### perMessageDeflate
45+
4446
@default `false`
4547

46-
Enable compression for clients that support it.
48+
Enable compression for clients that support it.
4749

4850
By default, compression is disabled.
4951

5052
### maxPayloadLength
53+
5154
The maximum size of a message.
5255

5356
### idleTimeout
57+
5458
@default `120`
5559

5660
After a connection has not received a message for this many seconds, it will be closed.
5761

5862
### backpressureLimit
63+
5964
@default `16777216` (16MB)
6065

6166
The maximum number of bytes that can be buffered for a single connection.
6267

6368
### closeOnBackpressureLimit
69+
6470
@default `false`
6571

6672
Close the connection if the backpressure limit is reached.
6773

6874
## Methods
75+
6976
Below are the new methods that are available to the WebSocket plugin
7077

7178
## ws
79+
7280
Create a websocket handler
7381

7482
Example:
83+
7584
```typescript
7685
import { Elysia, ws } from 'elysia'
7786

@@ -86,35 +95,40 @@ new Elysia()
8695
```
8796

8897
Type:
98+
8999
```typescript
90100
.ws(endpoint: path, options: Partial<WebSocketHandler<Context>>): this
91101
```
92102

93-
endpoint: A path to exposed as websocket handler
103+
endpoint: A path to exposed as websocket handler
94104
options: Customize WebSocket handler behavior
95105

96106
## WebSocketHandler
107+
97108
WebSocketHandler extends config from [config](#config).
98109

99110
Below is a config which accepted by `ws`.
100111

101112
## schema
113+
102114
Validatation for an incoming WebSocket request.
103115

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
109121

110122
::: tip
111123
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.
112124
:::
113125

114126
## open
127+
115128
Callback function for new websocket connection.
116129

117130
Type:
131+
118132
```typescript
119133
open(ws: ServerWebSocket<{
120134
// uid for each connection
@@ -124,26 +138,30 @@ open(ws: ServerWebSocket<{
124138
```
125139

126140
## message
141+
127142
Callback function for incoming websocket message.
128143

129144
Type:
145+
130146
```typescript
131147
message(
132148
ws: ServerWebSocket<{
133149
// uid for each connection
134150
id: string
135151
data: Context
136-
}>,
152+
}>,
137153
message: Message
138154
): this
139155
```
140156

141157
`Message` type based on `schema.message`. Default is `string`.
142158

143159
## close
160+
144161
Callback function for closing websocket connection.
145162

146163
Type:
164+
147165
```typescript
148166
close(ws: ServerWebSocket<{
149167
// uid for each connection
@@ -153,42 +171,51 @@ close(ws: ServerWebSocket<{
153171
```
154172

155173
## drain
174+
156175
Callback function for the server is ready to accept more data.
157176

158177
Type:
178+
159179
```typescript
160180
drain(
161181
ws: ServerWebSocket<{
162182
// uid for each connection
163183
id: string
164184
data: Context
165-
}>,
185+
}>,
166186
code: number,
167187
reason: string
168188
): this
169189
```
170190

171191
## parse
192+
172193
`Parse` middleware to parse the request before upgrading the HTTP connection to WebSocket.
173194

174195
## beforeHandle
196+
175197
`Before Handle` middleware which execute before upgrading the HTTP connection to WebSocket.
176198

177199
Ideal place for validation.
178200

179201
## transform
202+
180203
`Transform` middleware which execute before validation.
181204

182205
## transformMessage
206+
183207
Like `transform`, but execute before validation of WebSocket message
184208

185209
## header
210+
186211
Additional headers to add before upgrade connection to WebSocket.
187212

188213
## Pattern
214+
189215
Below you can find the common patterns to use the plugin.
190216

191217
## WebSocket message validation:
218+
192219
Validate incoming WebSocket message.
193220

194221
By default Elysia will parse incoming stringified JSON message as Object for validation.

0 commit comments

Comments
 (0)