@firtoz/websocket-do 1.0.0

package/README.md

@@ -0,0 +1,321 @@
+# @firtoz/websocket-do
+
+Type-safe WebSocket session management for Cloudflare Durable Objects with Hono integration.
+
+## Features
+
+- 🔒 **Type-safe** - Full TypeScript support with generic types for messages and session data
+- 🌐 **WebSocket Management** - Built on Cloudflare Durable Objects for stateful WebSocket connections
+- 🎯 **Session-based** - Abstract session class for easy implementation of custom WebSocket logic
+- 🔄 **State Persistence** - Automatic serialization/deserialization of session data
+- 📡 **Broadcasting** - Built-in support for broadcasting messages to all connected clients
+- 🚀 **Hono Integration** - Seamless integration with Hono framework for routing
+
+## Installation
+
+```bash
+bun add @firtoz/websocket-do
+```
+
+### Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```bash
+bun add hono @cloudflare/workers-types @firtoz/hono-fetcher
+```
+
+## Quick Start
+
+### 1. Define Your Message Types
+
+```typescript
+type ServerMessage = 
+  | { type: 'welcome'; userId: string }
+  | { type: 'chat'; message: string; from: string };
+
+type ClientMessage = 
+  | { type: 'chat'; message: string }
+  | { type: 'ping' };
+
+interface SessionData {
+  userId: string;
+  joinedAt: number;
+}
+```
+
+### 2. Implement Your Session
+
+```typescript
+import { BaseSession } from '@firtoz/websocket-do';
+import type { Context } from 'hono';
+
+class ChatSession extends BaseSession<
+  Env,
+  SessionData,
+  ServerMessage,
+  ClientMessage
+> {
+  protected createData(ctx: Context<{ Bindings: Env }>): SessionData {
+    return {
+      userId: crypto.randomUUID(),
+      joinedAt: Date.now(),
+    };
+  }
+
+  async handleMessage(message: ClientMessage): Promise<void> {
+    switch (message.type) {
+      case 'chat':
+        // Broadcast to all sessions
+        this.broadcast({
+          type: 'chat',
+          message: message.message,
+          from: this.data.userId,
+        });
+        break;
+      case 'ping':
+        this.send({ type: 'welcome', userId: this.data.userId });
+        break;
+    }
+  }
+
+  async handleBufferMessage(message: ArrayBuffer): Promise<void> {
+    // Handle binary messages if needed
+  }
+
+  async handleClose(): Promise<void> {
+    console.log(`Session closed for user ${this.data.userId}`);
+  }
+}
+```
+
+### 3. Implement Your Durable Object
+
+```typescript
+import { BaseWebSocketDO } from '@firtoz/websocket-do';
+import { Hono } from 'hono';
+
+export class ChatRoomDO extends BaseWebSocketDO<Env, ChatSession> {
+  app = this.getBaseApp()
+    .get('/info', (ctx) => {
+      return ctx.json({
+        connectedUsers: this.sessions.size,
+      });
+    });
+
+  protected createSession(websocket: WebSocket): ChatSession {
+    return new ChatSession(websocket, this.sessions);
+  }
+}
+```
+
+### 4. Configure Your Worker
+
+```typescript
+// wrangler.toml
+[[durable_objects.bindings]]
+name = "CHAT_ROOM"
+class_name = "ChatRoomDO"
+script_name = "your-worker-name"
+
+[[migrations]]
+tag = "v1"
+new_classes = ["ChatRoomDO"]
+```
+
+### 5. Access from Your Worker
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    
+    if (url.pathname === '/chat') {
+      const id = env.CHAT_ROOM.idFromName('global-chat');
+      const stub = env.CHAT_ROOM.get(id);
+      
+      // Proxy to the Durable Object
+      return stub.fetch(request);
+    }
+    
+    return new Response('Not found', { status: 404 });
+  }
+};
+```
+
+## API Reference
+
+### `BaseWebSocketDO<TEnv, TSession>`
+
+Abstract class for creating WebSocket-enabled Durable Objects.
+
+#### Type Parameters
+
+- `TEnv` - Your Cloudflare Worker environment bindings
+- `TSession` - Your session class extending `BaseSession`
+
+#### Methods
+
+- `abstract createSession(websocket: WebSocket): TSession | Promise<TSession>`
+  - Factory method to create session instances
+
+- `getBaseApp(): Hono`
+  - Returns a base Hono app with `/websocket` endpoint configured
+
+- `handleSession(ctx: Context, ws: WebSocket): Promise<void>`
+  - Handles new WebSocket connections
+
+#### Properties
+
+- `sessions: Map<WebSocket, TSession>` - Map of all active sessions
+- `app: Hono` - Your Hono application (must be implemented)
+
+### `BaseSession<TEnv, TData, TServerMessage, TClientMessage>`
+
+Abstract class for managing individual WebSocket sessions.
+
+#### Type Parameters
+
+- `TEnv` - Your Cloudflare Worker environment bindings
+- `TData` - Type of data stored in the session
+- `TServerMessage` - Union type of messages sent to clients
+- `TClientMessage` - Union type of messages received from clients
+
+#### Methods
+
+- `abstract createData(ctx: Context): TData`
+  - Creates initial session data
+
+- `abstract handleMessage(message: TClientMessage): Promise<void>`
+  - Handles text messages from client
+
+- `abstract handleBufferMessage(message: ArrayBuffer): Promise<void>`
+  - Handles binary messages from client
+
+- `abstract handleClose(): Promise<void>`
+  - Cleanup when session closes
+
+- `protected send(message: TServerMessage): void`
+  - Send message to this session's client
+
+- `protected broadcast(message: TServerMessage, excludeSelf?: boolean): void`
+  - Send message to all connected sessions
+
+- `startFresh(ctx: Context): void`
+  - Initialize new session (called automatically)
+
+- `resume(): void`
+  - Resume existing session after hibernation (called automatically)
+
+- `update(): void`
+  - Manually update serialized session data
+
+#### Properties
+
+- `data: TData` - Current session data
+- `websocket: WebSocket` - The underlying WebSocket
+
+### `WebsocketWrapper<TAttachment, TMessage>`
+
+Low-level wrapper for typed WebSocket operations.
+
+#### Methods
+
+- `send(message: TMessage): void`
+  - Send JSON-serialized message
+
+- `deserializeAttachment(): TAttachment`
+  - Get attached session data
+
+- `serializeAttachment(attachment: TAttachment): void`
+  - Update attached session data
+
+## Advanced Usage
+
+### Custom Routes
+
+You can extend the base app with custom routes:
+
+```typescript
+export class ChatRoomDO extends BaseWebSocketDO<Env, ChatSession> {
+  app = this.getBaseApp()
+    .get('/stats', (ctx) => {
+      const users = Array.from(this.sessions.values()).map(s => ({
+        userId: s.data.userId,
+        joinedAt: s.data.joinedAt,
+      }));
+      
+      return ctx.json({ users, count: users.length });
+    })
+    .post('/broadcast', async (ctx) => {
+      const { message } = await ctx.req.json();
+      
+      for (const session of this.sessions.values()) {
+        session.send({ type: 'admin', message });
+      }
+      
+      return ctx.json({ success: true });
+    });
+}
+```
+
+### State Persistence
+
+Session data is automatically serialized and persists across hibernation:
+
+```typescript
+class GameSession extends BaseSession<Env, GameData, ServerMsg, ClientMsg> {
+  protected createData(ctx: Context): GameData {
+    return {
+      playerName: ctx.req.query('name') || 'Anonymous',
+      score: 0,
+      inventory: [],
+    };
+  }
+
+  async handleMessage(message: ClientMsg): Promise<void> {
+    if (message.type === 'collectItem') {
+      this.data.inventory.push(message.item);
+      this.data.score += 10;
+      
+      // Persist changes
+      this.update();
+      
+      this.send({ type: 'scoreUpdate', score: this.data.score });
+    }
+  }
+}
+```
+
+### Error Handling
+
+Errors in message handlers are caught and logged, but don't crash the connection:
+
+```typescript
+async handleMessage(message: ClientMessage): Promise<void> {
+  try {
+    // Your logic here
+    if (message.type === 'dangerous') {
+      throw new Error('Invalid operation');
+    }
+  } catch (error) {
+    // Send error to client
+    this.send({ 
+      type: 'error', 
+      message: error instanceof Error ? error.message : 'Unknown error' 
+    });
+    
+    // Optionally close the connection
+    this.websocket.close(1008, 'Policy violation');
+  }
+}
+```
+
+## License
+
+MIT
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for details on how to contribute to this package.
+

package/package.json

@@ -0,0 +1,62 @@
+{
+	"name": "@firtoz/websocket-do",
+	"version": "1.0.0",
+	"description": "Type-safe WebSocket session management for Cloudflare Durable Objects with Hono integration",
+	"main": "./src/index.ts",
+	"module": "./src/index.ts",
+	"types": "./src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts",
+			"require": "./src/index.ts"
+		}
+	},
+	"files": [
+		"src/**/*.ts",
+		"!src/**/*.test.ts",
+		"README.md"
+	],
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"lint": "biome lint src --write",
+		"format": "biome format src --write",
+		"test": "bun test",
+		"test:watch": "bun test --watch"
+	},
+	"keywords": [
+		"typescript",
+		"websocket",
+		"durable-objects",
+		"cloudflare",
+		"cloudflare-workers",
+		"hono",
+		"session-management",
+		"type-safe"
+	],
+	"author": "Firtina Ozbalikchi <firtoz@github.com>",
+	"license": "MIT",
+	"homepage": "https://github.com/firtoz/fullstack-toolkit#readme",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/firtoz/fullstack-toolkit.git",
+		"directory": "packages/websocket-do"
+	},
+	"bugs": {
+		"url": "https://github.com/firtoz/fullstack-toolkit/issues"
+	},
+	"peerDependencies": {
+		"@cloudflare/workers-types": "^4.20251004.0",
+		"@firtoz/hono-fetcher": "workspace:*",
+		"hono": "^4.9.9"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"devDependencies": {
+		"bun-types": "^1.2.23"
+	}
+}

package/src/BaseSession.ts

@@ -0,0 +1,75 @@
+import type { Context } from "hono";
+import { WebsocketWrapper } from "./WebsocketWrapper";
+
+export type SessionClientMessage<TSession extends BaseSession> =
+	TSession extends BaseSession<never, never, infer TClientMessage, never>
+		? TClientMessage
+		: never;
+
+export abstract class BaseSession<
+	// biome-ignore lint/suspicious/noExplicitAny: Generic type parameter with flexible default
+	TEnv extends object = any,
+	// biome-ignore lint/suspicious/noExplicitAny: Generic type parameter with flexible default
+	TData = any,
+	// biome-ignore lint/suspicious/noExplicitAny: Generic type parameter with flexible default
+	TServerMessage = any,
+	// biome-ignore lint/suspicious/noExplicitAny: Generic type parameter with flexible default
+	TClientMessage = any,
+> {
+	private _data!: TData;
+
+	public get data(): TData {
+		return this._data;
+	}
+
+	private set data(data: TData) {
+		this._data = data;
+	}
+
+	private readonly wrapper: WebsocketWrapper<TData, TServerMessage>;
+
+	constructor(
+		public websocket: WebSocket,
+		protected sessions: Map<
+			WebSocket,
+			BaseSession<TEnv, TData, TServerMessage, TClientMessage>
+		>,
+	) {
+		this.wrapper = new WebsocketWrapper<TData, TServerMessage>(websocket);
+	}
+
+	public startFresh(ctx: Context<{ Bindings: TEnv }>) {
+		this.data = this.createData(ctx);
+		this.wrapper.serializeAttachment(this.data);
+	}
+
+	public resume() {
+		const existingData = this.wrapper.deserializeAttachment();
+		if (existingData) {
+			this.data = existingData;
+		} else {
+			throw new Error("No data to resume");
+		}
+	}
+
+	public update() {
+		this.wrapper.serializeAttachment(this.data);
+	}
+
+	protected abstract createData(ctx: Context<{ Bindings: TEnv }>): TData;
+
+	protected broadcast(message: TServerMessage, excludeSelf = false) {
+		for (const session of this.sessions.values()) {
+			if (excludeSelf && session === this) continue;
+			session.send(message);
+		}
+	}
+
+	protected send(message: TServerMessage) {
+		this.wrapper.send(message);
+	}
+
+	abstract handleMessage(message: TClientMessage): Promise<void>;
+	abstract handleBufferMessage(message: ArrayBuffer): Promise<void>;
+	abstract handleClose(): Promise<void>;
+}

package/src/BaseWebSocketDO.ts

@@ -0,0 +1,178 @@
+import { DurableObject } from "cloudflare:workers";
+import type { DOWithHonoApp } from "@firtoz/hono-fetcher/honoDoFetcher";
+import { type Context, Hono } from "hono";
+import type { BaseSession, SessionClientMessage } from "./BaseSession";
+
+export abstract class BaseWebSocketDO<
+		TEnv extends object,
+		TSession extends BaseSession<TEnv>,
+	>
+	extends DurableObject<TEnv>
+	implements DOWithHonoApp
+{
+	protected readonly sessions = new Map<WebSocket, TSession>();
+
+	constructor(ctx: DurableObjectState, env: TEnv) {
+		super(ctx, env);
+
+		this.ctx.blockConcurrencyWhile(async () => {
+			const websockets = this.ctx.getWebSockets();
+			await Promise.all(
+				websockets.map(async (websocket) => {
+					try {
+						const session = await this.createSession(websocket);
+						session.resume();
+						this.sessions.set(websocket, session);
+					} catch (error) {
+						console.error(`Error during session setup: ${error}`);
+						await this.webSocketError(websocket, error);
+					}
+				}),
+			);
+		});
+	}
+
+	protected getBaseApp() {
+		return new Hono<{ Bindings: TEnv }>().get(
+			"/websocket",
+			async (ctx): Promise<Response> => {
+				const { req } = ctx;
+				if (req.header("Upgrade") !== "websocket") {
+					console.error("Expected websocket");
+					return ctx.text("Expected websocket", 400);
+				}
+
+				const [client, server] = Object.values(new WebSocketPair()) as [
+					WebSocket,
+					WebSocket,
+				];
+
+				try {
+					await this.handleSession(ctx, server);
+					return new Response(null, { status: 101, webSocket: client });
+				} catch (error) {
+					console.error(error);
+					client.accept();
+					client.send(
+						JSON.stringify({
+							error: "Uncaught exception during session setup.",
+						}),
+					);
+					client.close(1011, "Uncaught exception during session setup.");
+					return new Response(null, { status: 101, webSocket: client });
+				}
+			},
+		);
+	}
+
+	abstract app: Hono<{ Bindings: TEnv }>;
+
+	protected abstract createSession(
+		websocket: WebSocket,
+	): TSession | Promise<TSession>;
+
+	async handleSession(
+		ctx: Context<{ Bindings: TEnv }>,
+		ws: WebSocket,
+	): Promise<void> {
+		this.ctx.acceptWebSocket(ws);
+		try {
+			const session = await this.createSession(ws);
+			session.startFresh(ctx);
+			this.sessions.set(ws, session);
+		} catch (error) {
+			console.error(`Error during session setup: ${error}`);
+			await this.webSocketError(ws, error);
+		}
+	}
+
+	override async webSocketMessage(
+		ws: WebSocket,
+		message: string | ArrayBuffer,
+	): Promise<void> {
+		const session = this.sessions.get(ws);
+		if (!session) return;
+
+		try {
+			if (message instanceof ArrayBuffer) {
+				await session.handleBufferMessage(message);
+				return;
+			}
+
+			const parsed = JSON.parse(message) as SessionClientMessage<TSession>;
+			await session.handleMessage(parsed);
+		} catch (error) {
+			console.error(`Error during session message: ${error}`);
+			// Let the implementer decide how to handle errors in their session implementation
+			// The session can optionally implement error handling that closes the connection if needed
+		}
+	}
+
+	override async webSocketClose(
+		ws: WebSocket,
+		_code: number,
+		_reason: string,
+		_wasClean: boolean,
+	) {
+		const session = this.sessions.get(ws);
+		if (!session) return;
+
+		try {
+			await this.#handleClose(session);
+		} catch (error) {
+			console.error(`Error during session close: ${error}`);
+		} finally {
+			// Call close() for both OPEN and CLOSING states
+			// For CLOSING, this can help ensure the WebSocket fully transitions to CLOSED
+			if (
+				ws.readyState === WebSocket.OPEN ||
+				ws.readyState === WebSocket.CLOSING
+			) {
+				ws.close(1000, "Normal closure");
+			}
+		}
+	}
+
+	override async webSocketError(ws: WebSocket, error: unknown) {
+		const session = this.sessions.get(ws);
+		if (!session) {
+			// Call close() for both OPEN and CLOSING states
+			if (
+				ws.readyState === WebSocket.OPEN ||
+				ws.readyState === WebSocket.CLOSING
+			) {
+				ws.close(1011, "Error during session setup.");
+			}
+			return;
+		}
+
+		console.error(`Error for session: ${error}`);
+		try {
+			await this.#handleClose(session);
+		} catch (error) {
+			console.error(`Error during session close: ${error}`);
+		} finally {
+			// Call close() for both OPEN and CLOSING states
+			if (
+				ws.readyState === WebSocket.OPEN ||
+				ws.readyState === WebSocket.CLOSING
+			) {
+				ws.close(1011, "Error during session.");
+			}
+		}
+	}
+
+	async #handleClose(session: TSession) {
+		try {
+			await session.handleClose();
+		} catch (error) {
+			console.error(`Error during session close: ${error}`);
+		} finally {
+			this.sessions.delete(session.websocket);
+		}
+	}
+
+	override fetch(request: Request): Response | Promise<Response> {
+		return this.app.fetch(request, this.env);
+	}
+}

package/src/WebsocketWrapper.ts

@@ -0,0 +1,16 @@
+export class WebsocketWrapper<TAttachment, TMessage> {
+	public constructor(public webSocket: WebSocket) {}
+
+	public send(message: TMessage) {
+		if (this.webSocket.readyState !== WebSocket.OPEN) return;
+		this.webSocket.send(JSON.stringify(message));
+	}
+
+	public deserializeAttachment() {
+		return this.webSocket.deserializeAttachment() as TAttachment;
+	}
+
+	public serializeAttachment(attachment: TAttachment) {
+		this.webSocket.serializeAttachment(attachment);
+	}
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { BaseSession, type SessionClientMessage } from "./BaseSession";
+export { BaseWebSocketDO } from "./BaseWebSocketDO";
+export { WebsocketWrapper } from "./WebsocketWrapper";