bxo 0.0.5-dev.76 → 0.0.5-dev.78

package/README.md

@@ -5,6 +5,7 @@ A fast, lightweight web framework for Bun with built-in Zod validation and lifec
 ## Features
 
 - **Type-safe routing** with Zod schema validation
+- **WebSocket support** with clean API
 - **Lifecycle hooks** for middleware and plugins
 - **Plugin system** for extending functionality
 - **Built-in CORS support** via plugin
@@ -33,6 +34,76 @@ app.get("/", (ctx) => ctx.json({ message: "Hello World!" }));
 app.start();
 ```
 
+## WebSocket Support
+
+BXO provides built-in WebSocket support with a clean, intuitive API:
+
+```typescript
+import BXO from "./src";
+
+const app = new BXO();
+
+// WebSocket route
+app.ws("/ws", {
+    open(ws) {
+        console.log("WebSocket connection opened");
+        ws.send("Welcome to BXO WebSocket!");
+    },
+    
+    message(ws, message) {
+        console.log("Received message:", message);
+        // Echo the message back
+        ws.send(`Echo: ${message}`);
+    },
+    
+    close(ws, code, reason) {
+        console.log(`WebSocket connection closed: ${code} ${reason}`);
+    },
+    
+    ping(ws, data) {
+        console.log("Ping received:", data);
+    },
+    
+    pong(ws, data) {
+        console.log("Pong received:", data);
+    }
+});
+
+// WebSocket with path parameters
+app.ws("/chat/:room", {
+    open(ws) {
+        const room = ws.data?.room || 'unknown';
+        console.log(`WebSocket connection opened for room: ${room}`);
+        ws.send(`Welcome to chat room: ${room}`);
+    },
+    
+    message(ws, message) {
+        const room = ws.data?.room || 'unknown';
+        console.log(`Message in room ${room}:`, message);
+        ws.send(`[${room}] Echo: ${message}`);
+    }
+});
+
+app.start();
+```
+
+### WebSocket Handler Events
+
+- `open(ws)` - Called when a WebSocket connection is established
+- `message(ws, message)` - Called when a message is received
+- `close(ws, code, reason)` - Called when the connection is closed
+- `drain(ws)` - Called when the WebSocket is ready for more data
+- `ping(ws, data)` - Called when a ping is received
+- `pong(ws, data)` - Called when a pong is received
+
+### WebSocket Features
+
+- **Path parameters** - Support for dynamic routes like `/chat/:room`
+- **Automatic upgrade** - HTTP requests to WebSocket routes are automatically upgraded
+- **Type safety** - Full TypeScript support with proper typing
+- **Error handling** - Built-in error handling for WebSocket events
+- **Data attachment** - Access to path information via `ws.data`
+
 ## Lifecycle Hooks
 
 BXO provides powerful lifecycle hooks that allow you to intercept and modify requests and responses at different stages:
@@ -220,6 +291,7 @@ Check out the `example/` directory for more usage examples:
 
 - `cors-example.ts` - Demonstrates CORS plugin and lifecycle hooks
 - `openapi-example.ts` - Demonstrates OpenAPI plugin with tags and security
+- `websocket-example.ts` - Demonstrates WebSocket functionality with interactive HTML client
 - `index.ts` - Basic routing example
 
 This project was created using `bun init` in bun v1.2.3. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/example/url-encoding-example.ts

@@ -0,0 +1,81 @@
+import BXO from "../src";
+
+async function main() {
+    const app = new BXO({ serve: { port: 3000 } });
+
+    // Route with space in the path
+    app.get("/api/resources/Workspace Item", (ctx) => {
+        return ctx.json({ 
+            message: "Found Workspace Item resource!",
+            path: ctx.request.url,
+            pathname: new URL(ctx.request.url).pathname
+        });
+    });
+
+    // Route with URL-encoded space
+    app.get("/api/resources/Workspace%20Item", (ctx) => {
+        return ctx.json({ 
+            message: "Found URL-encoded Workspace Item resource!",
+            path: ctx.request.url,
+            pathname: new URL(ctx.request.url).pathname
+        });
+    });
+
+    // Route with path parameter (recommended approach)
+    app.get("/api/resources/:resourceType", (ctx) => {
+        return ctx.json({ 
+            message: `Found resource type: ${ctx.params.resourceType}`,
+            path: ctx.request.url,
+            pathname: new URL(ctx.request.url).pathname,
+            params: ctx.params
+        });
+    });
+
+    // Test route to show the difference
+    app.get("/test", (ctx) => {
+        return ctx.text(`
+<!DOCTYPE html>
+<html>
+<head>
+    <title>URL Encoding Test</title>
+</head>
+<body>
+    <h1>URL Encoding Test</h1>
+    <p>Test the following URLs:</p>
+    <ul>
+        <li><a href="/api/resources/Workspace Item">/api/resources/Workspace Item</a> (with space)</li>
+        <li><a href="/api/resources/Workspace%20Item">/api/resources/Workspace%20Item</a> (URL encoded)</li>
+        <li><a href="/api/resources/My%20Resource">/api/resources/My%20Resource</a> (URL encoded with params)</li>
+    </ul>
+    
+    <h2>Test with JavaScript fetch:</h2>
+    <button onclick="testFetch('/api/resources/Workspace Item')">Test with space</button>
+    <button onclick="testFetch('/api/resources/Workspace%20Item')">Test URL encoded</button>
+    <button onclick="testFetch('/api/resources/My%20Resource')">Test with params</button>
+    
+    <div id="result"></div>
+    
+    <script>
+        async function testFetch(url) {
+            try {
+                const response = await fetch(url);
+                const data = await response.json();
+                document.getElementById('result').innerHTML = 
+                    '<h3>Result:</h3><pre>' + JSON.stringify(data, null, 2) + '</pre>';
+            } catch (error) {
+                document.getElementById('result').innerHTML = 
+                    '<h3>Error:</h3><pre>' + error.message + '</pre>';
+            }
+        }
+    </script>
+        `, 200, {
+            "Content-Type": "text/html"
+        });
+    });
+
+    app.start();
+    console.log(`Server is running on http://localhost:${app.server?.port}`);
+    console.log(`Test URL encoding at http://localhost:${app.server?.port}/test`);
+}
+
+main().catch(console.error);

package/example/websocket-example.ts

@@ -0,0 +1,132 @@
+import BXO from "../src";
+
+async function main() {
+    const app = new BXO({ serve: { port: 3000 } });
+
+    // HTTP routes
+    app.get("/", (ctx) => {
+        return ctx.text(`
+<!DOCTYPE html>
+<html>
+<head>
+    <title>BXO WebSocket Example</title>
+</head>
+<body>
+    <h1>BXO WebSocket Example</h1>
+    <div id="messages"></div>
+    <input type="text" id="messageInput" placeholder="Type a message...">
+    <button onclick="sendMessage()">Send</button>
+    <button onclick="connect()">Connect</button>
+    <button onclick="disconnect()">Disconnect</button>
+    
+    <script>
+        let ws = null;
+        
+        function connect() {
+            ws = new WebSocket('ws://localhost:3000/ws');
+            
+            ws.onopen = function() {
+                addMessage('Connected to WebSocket');
+            };
+            
+            ws.onmessage = function(event) {
+                addMessage('Received: ' + event.data);
+            };
+            
+            ws.onclose = function() {
+                addMessage('Disconnected from WebSocket');
+            };
+            
+            ws.onerror = function(error) {
+                addMessage('Error: ' + error);
+            };
+        }
+        
+        function disconnect() {
+            if (ws) {
+                ws.close();
+                ws = null;
+            }
+        }
+        
+        function sendMessage() {
+            const input = document.getElementById('messageInput');
+            if (ws && input.value) {
+                ws.send(input.value);
+                addMessage('Sent: ' + input.value);
+                input.value = '';
+            }
+        }
+        
+        function addMessage(message) {
+            const messages = document.getElementById('messages');
+            const div = document.createElement('div');
+            div.textContent = new Date().toLocaleTimeString() + ': ' + message;
+            messages.appendChild(div);
+            messages.scrollTop = messages.scrollHeight;
+        }
+        
+        // Allow Enter key to send message
+        document.getElementById('messageInput').addEventListener('keypress', function(e) {
+            if (e.key === 'Enter') {
+                sendMessage();
+            }
+        });
+    </script>
+        `, 200, {
+            "Content-Type": "text/html"
+        });
+    });
+
+    // WebSocket route
+    app.ws("/ws", {
+        open(ws) {
+            console.log("WebSocket connection opened");
+            ws.send("Welcome to BXO WebSocket!");
+        },
+        
+        message(ws, message) {
+            console.log("Received message:", message);
+            // Echo the message back
+            ws.send(`Echo: ${message}`);
+        },
+        
+        close(ws, code, reason) {
+            console.log(`WebSocket connection closed: ${code} ${reason}`);
+        },
+        
+        ping(ws, data) {
+            console.log("Ping received:", data);
+        },
+        
+        pong(ws, data) {
+            console.log("Pong received:", data);
+        }
+    });
+
+    // Another WebSocket route with parameters
+    app.ws("/chat/:room", {
+        open(ws) {
+            console.log(`WebSocket connection opened for room: ${ws.data?.room || 'unknown'}`);
+            ws.send(`Welcome to chat room: ${ws.data?.room || 'unknown'}`);
+        },
+        
+        message(ws, message) {
+            const room = ws.data?.room || 'unknown';
+            console.log(`Message in room ${room}:`, message);
+            ws.send(`[${room}] Echo: ${message}`);
+        },
+        
+        close(ws, code, reason) {
+            const room = ws.data?.room || 'unknown';
+            console.log(`WebSocket connection closed for room ${room}: ${code} ${reason}`);
+        }
+    });
+
+    app.start();
+    console.log(`Server is running on http://localhost:${app.server?.port}`);
+    console.log(`WebSocket available at ws://localhost:${app.server?.port}/ws`);
+    console.log(`Chat WebSocket available at ws://localhost:${app.server?.port}/chat/:room`);
+}
+
+main().catch(console.error);

package/package.json

@@ -5,7 +5,7 @@
     ".": "./src/index.ts",
     "./plugins": "./plugins/index.ts"
   },
-  "version": "0.0.5-dev.76",
+  "version": "0.0.5-dev.78",
   "type": "module",
   "devDependencies": {
     "@types/bun": "latest"

package/src/index.ts

@@ -7,7 +7,8 @@ type Method =
     | "PATCH"
     | "DELETE"
     | "OPTIONS"
-    | "HEAD";
+    | "HEAD"
+    | "WS";
 
 type PickWildcardName<S extends string> = S extends "" ? "wildcard" : S;
 
@@ -89,6 +90,16 @@ type Handler<P extends string, S extends RouteSchema | undefined = undefined> =
     app: BXO
 ) => Response | string | Promise<Response | string>;
 
+// WebSocket handler types
+export type WebSocketHandler<T = any> = {
+    message?(ws: Bun.ServerWebSocket<T>, message: string | Buffer): void | Promise<void>;
+    open?(ws: Bun.ServerWebSocket<T>): void | Promise<void>;
+    close?(ws: Bun.ServerWebSocket<T>, code: number, reason: string): void | Promise<void>;
+    drain?(ws: Bun.ServerWebSocket<T>): void | Promise<void>;
+    ping?(ws: Bun.ServerWebSocket<T>, data: Buffer): void | Promise<void>;
+    pong?(ws: Bun.ServerWebSocket<T>, data: Buffer): void | Promise<void>;
+};
+
 type InternalRoute = {
     method: Method | "DEFAULT";
     path: string;
@@ -96,6 +107,7 @@ type InternalRoute = {
     paramNames: string[];
     schema?: RouteSchema;
     handler: AnyHandler;
+    websocketHandler?: WebSocketHandler;
 };
 
 type ServeOptions = Partial<Parameters<typeof Bun.serve>[0]>;
@@ -305,6 +317,10 @@ export default class BXO {
         return this.add("DELETE", path, handler as AnyHandler, schema as RouteSchema | undefined);
     }
 
+    ws<P extends string>(path: P, handler: WebSocketHandler): this {
+        return this.addWebSocket("WS", path, handler);
+    }
+
     // default can accept a handler OR static content (including Bun HTML bundle)
     default<P extends string>(path: P, handler: Handler<P, undefined>): this;
     default<P extends string, S extends RouteSchema>(path: P, handler: (req: Request) => Response, schema: S): this;
@@ -314,6 +330,9 @@ export default class BXO {
     }
 
     start(): void {
+        // Check if we have any WebSocket routes
+        const hasWebSocketRoutes = this.routes.some(r => r.method === "WS");
+        
         // Build a basic routes map for Bun's native routes (exact paths only)
         const nativeRoutes: Record<string, Record<string, (req: Request) => Promise<Response> | Response>> = {};
 
@@ -322,6 +341,9 @@ export default class BXO {
                 case "DEFAULT":
                     nativeRoutes[r.path] = r.handler as any;
                     break;
+                case "WS":
+                    // Skip WebSocket routes in native routes - they'll be handled in websocket config
+                    break;
                 default:
                     nativeRoutes[r.path] ||= {} as Record<string, (req: Request) => Promise<Response> | Response>;
                     nativeRoutes[r.path][r.method] = (req: Request) => this.dispatch(r, req);
@@ -331,13 +353,61 @@ export default class BXO {
 
         this.serveOptions.port = this.serveOptions.port === undefined ? 3000 : this.serveOptions.port;
 
-        this.server = Bun.serve({
-            ...this.serveOptions,
-            routes: nativeRoutes as any,
-            fetch: (req: Request) => {
-                return new Response("Not Found", { status: 404 });
+        // Create WebSocket configuration if we have WebSocket routes
+        const websocketConfig = hasWebSocketRoutes ? {
+            message: (ws: Bun.ServerWebSocket<{ path: string }>, message: string | Buffer) => {
+                this.handleWebSocketMessage(ws, message);
+            },
+            open: (ws: Bun.ServerWebSocket<{ path: string }>) => {
+                this.handleWebSocketOpen(ws);
+            },
+            close: (ws: Bun.ServerWebSocket<{ path: string }>, code: number, reason: string) => {
+                this.handleWebSocketClose(ws, code, reason);
+            },
+            drain: (ws: Bun.ServerWebSocket<{ path: string }>) => {
+                this.handleWebSocketDrain(ws);
+            },
+            ping: (ws: Bun.ServerWebSocket<{ path: string }>, data: Buffer) => {
+                this.handleWebSocketPing(ws, data);
+            },
+            pong: (ws: Bun.ServerWebSocket<{ path: string }>, data: Buffer) => {
+                this.handleWebSocketPong(ws, data);
             }
-        });
+        } : undefined;
+
+        if (hasWebSocketRoutes) {
+            this.server = Bun.serve({
+                ...this.serveOptions,
+                routes: nativeRoutes as any,
+                websocket: websocketConfig as any,
+                fetch: (req: Request, server: Bun.Server) => {
+                    // Handle WebSocket upgrade requests
+                    if (req.headers.get("upgrade") === "websocket") {
+                        const url = new URL(req.url);
+                        const wsRoute = this.findWebSocketRoute(url.pathname);
+                        if (wsRoute) {
+                            const success = server.upgrade(req, {
+                                data: { path: url.pathname }
+                            });
+                            if (success) {
+                                return; // WebSocket upgrade successful
+                            }
+                        }
+                    }
+                    
+                    // Handle regular HTTP requests
+                    return this.dispatchAny(req, nativeRoutes);
+                }
+            } as any);
+        } else {
+            this.server = Bun.serve({
+                ...this.serveOptions,
+                routes: nativeRoutes as any,
+                fetch: (req: Request) => {
+                    return this.dispatchAny(req, nativeRoutes);
+                }
+            });
+        }
     }
 
     // Lifecycle hook methods
@@ -361,6 +431,93 @@ export default class BXO {
         return this;
     }
 
+    // WebSocket handler methods
+    private findWebSocketRoute(pathname: string): InternalRoute | null {
+        for (const route of this.routes) {
+            if (route.method === "WS") {
+                if (route.matcher === null) {
+                    // Exact match
+                    if (route.path === pathname) {
+                        return route;
+                    }
+                } else {
+                    // Pattern match
+                    const match = pathname.match(route.matcher);
+                    if (match) {
+                        return route;
+                    }
+                }
+            }
+        }
+        return null;
+    }
+
+    private handleWebSocketMessage(ws: Bun.ServerWebSocket<{ path: string }>, message: string | Buffer): void {
+        const route = this.findWebSocketRoute(ws.data?.path || "");
+        if (route?.websocketHandler?.message) {
+            try {
+                (route.websocketHandler as any).message(ws, message);
+            } catch (error) {
+                console.error("WebSocket message handler error:", error);
+            }
+        }
+    }
+
+    private handleWebSocketOpen(ws: Bun.ServerWebSocket<{ path: string }>): void {
+        const route = this.findWebSocketRoute(ws.data?.path || "");
+        if (route?.websocketHandler?.open) {
+            try {
+                (route.websocketHandler as any).open(ws);
+            } catch (error) {
+                console.error("WebSocket open handler error:", error);
+            }
+        }
+    }
+
+    private handleWebSocketClose(ws: Bun.ServerWebSocket<{ path: string }>, code: number, reason: string): void {
+        const route = this.findWebSocketRoute(ws.data?.path || "");
+        if (route?.websocketHandler?.close) {
+            try {
+                (route.websocketHandler as any).close(ws, code, reason);
+            } catch (error) {
+                console.error("WebSocket close handler error:", error);
+            }
+        }
+    }
+
+    private handleWebSocketDrain(ws: Bun.ServerWebSocket<{ path: string }>): void {
+        const route = this.findWebSocketRoute(ws.data?.path || "");
+        if (route?.websocketHandler?.drain) {
+            try {
+                (route.websocketHandler as any).drain(ws);
+            } catch (error) {
+                console.error("WebSocket drain handler error:", error);
+            }
+        }
+    }
+
+    private handleWebSocketPing(ws: Bun.ServerWebSocket<{ path: string }>, data: Buffer): void {
+        const route = this.findWebSocketRoute(ws.data?.path || "");
+        if (route?.websocketHandler?.ping) {
+            try {
+                (route.websocketHandler as any).ping(ws, data);
+            } catch (error) {
+                console.error("WebSocket ping handler error:", error);
+            }
+        }
+    }
+
+    private handleWebSocketPong(ws: Bun.ServerWebSocket<{ path: string }>, data: Buffer): void {
+        const route = this.findWebSocketRoute(ws.data?.path || "");
+        if (route?.websocketHandler?.pong) {
+            try {
+                (route.websocketHandler as any).pong(ws, data);
+            } catch (error) {
+                console.error("WebSocket pong handler error:", error);
+            }
+        }
+    }
+
     // Internal
     private add(method: Method | "DEFAULT", path: string, handler: AnyHandler, schema?: RouteSchema): this {
         const { regex, names } = buildMatcher(path);
@@ -368,6 +525,12 @@ export default class BXO {
         return this;
     }
 
+    private addWebSocket(method: "WS", path: string, handler: WebSocketHandler): this {
+        const { regex, names } = buildMatcher(path);
+        this.routes.push({ method, path, handler: () => new Response("WebSocket route", { status: 400 }), matcher: regex, paramNames: names, websocketHandler: handler });
+        return this;
+    }
+
     private async dispatch(route: InternalRoute, req: Request): Promise<Response> {
         // Run beforeRequest hooks
         for (const hook of this.beforeRequestHooks) {
@@ -636,6 +799,16 @@ export default class BXO {
             if (h) return await h(req);
         }
 
+        // 1.5) Try URL-decoded pathname for exact matches
+        const decodedPathname = decodeURIComponent(url.pathname);
+        if (decodedPathname !== url.pathname) {
+            const exactDecoded = nativeRoutes[decodedPathname];
+            if (exactDecoded) {
+                const h = exactDecoded[method] || exactDecoded["DEFAULT"];
+                if (h) return await h(req);
+            }
+        }
+
         // 2) Fallback to our matcher list
         for (const r of this.routes) {
             if (r.matcher === null) continue; // exact paths handled above
@@ -644,6 +817,16 @@ export default class BXO {
             if (m) return this.dispatch(r, req);
         }
 
+        // 2.5) Try URL-decoded pathname for pattern matches
+        if (decodedPathname !== url.pathname) {
+            for (const r of this.routes) {
+                if (r.matcher === null) continue; // exact paths handled above
+                if (r.method !== method && r.method !== "DEFAULT") continue;
+                const m = decodedPathname.match(r.matcher);
+                if (m) return this.dispatch(r, req);
+            }
+        }
+
         // Create 404 response
         let notFoundResponse = new Response("Not Found", { status: 404 });