spooder 4.4.11 → 4.5.1

package/README.md

@@ -57,6 +57,8 @@ The `CLI` component of `spooder` is a global command-line tool for running serve
 	- [`server.sse(path: string, handler: ServerSentEventHandler)`](#api-routing-server-sse)
 - [API > Routing > Webhooks](#api-routing-webhooks)
 	- [`server.webhook(secret: string, path: string, handler: WebhookHandler)`](#api-routing-server-webhook)
+- [API > Routing > WebSockets](#api-routing-websockets)
+	- [`server.websocket(path: string, handlers: WebsocketHandlers)`](#api-routing-server-websocket)
 - [API > Server Control](#api-server-control)
 	- [`server.stop(immediate: boolean)`](#api-server-control-server-stop)
 - [API > Error Handling](#api-error-handling)
@@ -915,6 +917,58 @@ A webhook callback will only be called if the following critera is met by a requ
 > [!NOTE]
 > Constant-time comparison is used to prevent timing attacks when comparing the HMAC signature.
 
+<a id="api-routing-websockets"></a>
+## API > Routing > WebSockets
+
+<a id="api-routing-server-websocket"></a>
+### 🔧 `server.websocket(path: string, handlers: WebSocketHandlers)`
+
+Register a route which handles websocket connections.
+
+```ts
+server.websocket('/path/to/websocket', {
+	// all of these handlers are OPTIONAL
+
+	accept: (req) => {
+		// validates a request before it is upgraded
+		// returns HTTP 401 if FALSE is returned
+		// allows you to check headers/authentication
+		return true;
+	},
+
+	open: (ws) => {
+		// called when a websocket client connects
+	},
+
+	close: (ws, code, reason) => {
+		// called when a websocket client disconnects
+	},
+
+	message: (ws, message) => {
+		// called when a websocket message is received
+		// message is a string
+	},
+
+	message_json: (ws, data) => {
+		// called when a websocket message is received
+		// payload is parsed as JSON
+
+		// if payload cannot be parsed, socket will be
+		// closed with error 1003: Unsupported Data
+
+		// messages are only internally parsed if this
+		// handler is present
+	},
+
+	drain: (ws) => {
+		// called when a websocket with backpressure drains
+	}
+});
+```
+
+> [!IMPORTANT]
+> While it is possible to register multiple routes for websockets, the only handler which is unique per route is `accept()`. The last handlers provided to any route (with the exception of `accept()`) will apply to ALL websocket routes. This is a limitation in Bun.
+
 <a id="api-server-control"></a>
 ## API > Server Control
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "spooder",
 	"type": "module",
-	"version": "4.4.11",
+	"version": "4.5.1",
 	"exports": {
 		".": {
 			"bun": "./src/api.ts",

package/src/api.ts

@@ -104,6 +104,15 @@ export async function caution(err_message_or_obj: string | object, ...err: objec
 	await handle_error('caution: ', err_message_or_obj, ...err);
 }
 
+type WebsocketHandlers = {
+	accept?: (req: Request) => boolean | Promise<boolean>,
+	message?: (ws: WebSocket, message: string) => void,
+	message_json?: (ws: WebSocket, message: JsonSerializable) => void,
+	open?: (ws: WebSocket) => void,
+	close?: (ws: WebSocket, code: number, reason: string) => void,
+	drain?: (ws: WebSocket) => void
+};
+
 type CallableFunction = (...args: any[]) => any;
 type Callable = Promise<any> | CallableFunction;
 
@@ -722,6 +731,12 @@ export function serve(port: number) {
 
 	const slow_requests = new WeakSet();
 
+	let ws_message_handler: any = undefined;
+	let ws_message_json_handler: any = undefined;
+	let ws_open_handler: any = undefined;
+	let ws_close_handler: any = undefined;
+	let ws_drain_handler: any = undefined;
+
 	const server = Bun.serve({
 		port,
 		development: false,
@@ -741,6 +756,38 @@ export function serve(port: number) {
 				slow_requests.delete(req);
 
 			return print_request_info(req, response, url, request_time);
+		},
+
+		websocket: {
+			message(ws, message) {
+				ws_message_handler?.(ws, message);
+
+				if (ws_message_json_handler) {
+					try {
+						if (message instanceof ArrayBuffer)
+							message = new TextDecoder().decode(message);
+						else if (message instanceof Buffer)
+							message = message.toString('utf8');
+
+						const parsed = JSON.parse(message as string);
+						ws_message_json_handler(ws, parsed);
+					} catch (e) {
+						ws.close(1003, 'Unsupported Data');
+					}
+				}
+			},
+
+			open(ws) {
+				ws_open_handler?.(ws);
+			},
+
+			close(ws, code, reason) {
+				ws_close_handler?.(ws, code, reason);
+			},
+
+			drain(ws) {
+				ws_drain_handler?.(ws);
+			}
 		}
 	});
 
@@ -760,6 +807,25 @@ export function serve(port: number) {
 			routes.push([[...path.split('/'), '*'], route_directory(path, dir, handler ?? default_directory_handler), method]);
 		},
 
+		/** Add a route to upgrade connections to websockets. */
+		websocket: (path: string, handlers: WebsocketHandlers): void => {
+			routes.push([path.split('/'), async (req: Request, url: URL) => {
+				if (await handlers.accept?.(req) === false)
+					return 401; // Unauthorized
+
+				if (server.upgrade(req))
+					return 101; // Switching Protocols
+
+				return new Response('WebSocket upgrade failed', { status: 500 });
+			}, 'GET']);
+
+			ws_message_json_handler = handlers.message_json;
+			ws_open_handler = handlers.open;
+			ws_close_handler = handlers.close;
+			ws_message_handler = handlers.message;
+			ws_drain_handler = handlers.drain;
+		},
+
 		webhook: (secret: string, path: string, handler: WebhookHandler): void => {
 			routes.push([path.split('/'), async (req: Request, url: URL) => {
 				if (req.headers.get('Content-Type') !== 'application/json')