@hazejs/socket.io 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present hazejs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @hazejs/socket.io
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Socket.IO server integration for hazejs: namespaces from `app/socket/*.ts`, guard-based handshake auth, Redis adapter, Node and Bun.
+
+## Install
+
+```bash
+pnpm add @hazejs/socket.io socket.io
+```
+
+## Usage
+
+```ts
+// app/socket/chat.ts
+export default defineNamespace({
+  middleware: [
+    authenticate()
+  ],
+  connection(socket, io) {
+    socket.on('chat:send', text => io.of('/chat').emit('chat:message', text))
+  },
+})
+```
+
+Part of [hazejs](https://github.com/penna-org/haze) — see the main README for documentation.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,81 @@
+import { ConfigInput, ServiceProvider } from "@hazejs/core";
+import { Namespace, Server, ServerOptions, Socket } from "socket.io";
+declare const kNamespace: unique symbol;
+export interface SocketIOConfig {
+  /** 路径，默认 `/socket.io/`（与 socket.io-client 的默认值一致） */
+  path?: string;
+  /** CORS，默认沿用 config/cors.ts 的 origin；false 关闭（同源） */
+  cors?: ServerOptions['cors'] | false;
+  /** 多实例：官方 @socket.io/redis-adapter（需要 ioredis） */
+  adapter?: {
+    driver: 'redis';
+    url?: string;
+    key?: string;
+  };
+  /** 透传给 socket.io Server 的其它选项（pingInterval、connectionStateRecovery 等） */
+  options?: Partial<ServerOptions>;
+}
+/** `config/socketio.ts` 的默认导出 */
+export declare function defineSocketIOConfig(config: SocketIOConfig | (() => SocketIOConfig)): ConfigInput<SocketIOConfig>;
+export type SocketMiddleware = (socket: Socket, next: (error?: Error) => void) => unknown;
+export interface NamespaceDefinition {
+  readonly [kNamespace]: true;
+  /** 命名空间，默认由文件名决定：index → `/`，chat → `/chat` */
+  readonly name?: string;
+  readonly middleware: SocketMiddleware[];
+  readonly connection: (socket: Socket, io: Server, namespace: Namespace) => unknown;
+}
+/**
+ * 定义命名空间（app/socket/*.ts 的默认导出，自动注册）：
+ *
+ * ```ts
+ * export default defineNamespace({
+ *   middleware: [authenticate()],
+ *   connection(socket, io) {
+ *     socket.on('chat:send', (text, ack) => { io.of('/chat').emit('chat:message', text); ack?.('ok') })
+ *   },
+ * })
+ * ```
+ */
+export declare function defineNamespace(definition: {
+  name?: string;
+  middleware?: SocketMiddleware[];
+  connection: NamespaceDefinition['connection'];
+}): NamespaceDefinition;
+export declare function isNamespace(value: unknown): value is NamespaceDefinition;
+/** 注入令牌：`inject(SocketIOServer)` 取得 socket.io 的 Server */
+export declare const SocketIOServer: import("@hazejs/core").Token<Server<import("socket.io").DefaultEventsMap, import("socket.io").DefaultEventsMap, import("socket.io").DefaultEventsMap, any>>;
+/**
+ * Socket.IO 服务提供者（app/provider/SocketProvider.ts：`export default socketIoProvider()`）：
+ * 创建 socket.io Server（跨热更新保留），注册 app/socket 下的命名空间，挂到框架的 HTTP 服务器。
+ * 新连接总是使用最新的命名空间定义；Edge / Serverless 运行时上不启动。
+ */
+export declare function socketIoProvider(): ServiceProvider;
+/**
+ * 握手鉴权：按 config/auth.ts 的 Guard 识别用户，存入 `socket.data.user`。
+ * 令牌取 `io({ auth: { token } })` 或 Authorization 头；Session Guard 读握手请求的 Cookie。
+ * 未登录时拒绝连接，客户端收到 connect_error（message 为 unauthorized）。
+ */
+export declare function authenticate(options?: {
+  guard?: string;
+  optional?: boolean;
+}): SocketMiddleware;
+/**
+ * 服务端推送（HTTP 接口、任务、事件监听器中）：
+ *
+ * ```ts
+ * SocketIO.to(`user:${id}`).emit('notice', data)
+ * SocketIO.of('/chat').emit('chat:message', text)
+ * ```
+ */
+export interface SocketIOFacade {
+  readonly server: Server;
+  emit: (event: string, ...args: unknown[]) => boolean;
+  to: (room: string | string[]) => ReturnType<Server['to']>;
+  except: (room: string | string[]) => ReturnType<Server['except']>;
+  of: (namespace: string) => Namespace;
+}
+export declare const SocketIO: SocketIOFacade;
+/** 测试中释放（通常随 app.dispose() 自动释放） */
+export declare function closeSocketIO(): Promise<void>;
+export type { Namespace, Server, Socket };

package/dist/index.mjs

@@ -0,0 +1,204 @@
+import { createToken, definePersistent, registerServerExtension, unregisterServerExtension } from "@hazejs/core";
+// src/index.ts
+const kNamespace = Symbol.for("hazejs.socket.namespace");
+/** `config/socketio.ts` 的默认导出 */
+function defineSocketIOConfig(config) {
+	return config;
+}
+/**
+* 定义命名空间（app/socket/*.ts 的默认导出，自动注册）：
+*
+* ```ts
+* export default defineNamespace({
+*   middleware: [authenticate()],
+*   connection(socket, io) {
+*     socket.on('chat:send', (text, ack) => { io.of('/chat').emit('chat:message', text); ack?.('ok') })
+*   },
+* })
+* ```
+*/
+function defineNamespace(definition) {
+	return {
+		[kNamespace]: true,
+		middleware: [],
+		...definition
+	};
+}
+function isNamespace(value) {
+	return typeof value === "object" && value !== null && kNamespace in value;
+}
+/** 注入令牌：`inject(SocketIOServer)` 取得 socket.io 的 Server */
+const SocketIOServer = createToken("socket.io");
+function state() {
+	return definePersistent("socket.io", () => ({
+		io: void 0,
+		starting: void 0,
+		app: void 0,
+		definitions: /* @__PURE__ */ new Map(),
+		wired: /* @__PURE__ */ new Set(),
+		close: []
+	}), { dispose: async (value) => {
+		await closeServer(value.io);
+		for (const close of value.close.splice(0)) await close();
+		value.io = void 0;
+		value.starting = void 0;
+		value.wired.clear();
+	} });
+}
+/** 关闭 socket.io：未挂到任何 HTTP 服务器（如测试中）时 io.close() 会抛错，只断开连接 */
+async function closeServer(io) {
+	if (!io) return;
+	if (!io.engine) {
+		io.disconnectSockets(true);
+		return;
+	}
+	await new Promise((resolve) => {
+		io.close(() => resolve()).catch(() => resolve());
+	});
+}
+function namespaceName(file, definition) {
+	if (definition.name) return definition.name.startsWith("/") ? definition.name : `/${definition.name}`;
+	if (!file || file === "index") return "/";
+	return `/${file.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase()}`;
+}
+/** 按顺序执行中间件链 */
+function runMiddleware(middleware, socket, done) {
+	let index = 0;
+	const next = (error) => {
+		if (error || index >= middleware.length) return done(error);
+		const current = middleware[index++];
+		Promise.resolve(current(socket, next)).catch(next);
+	};
+	next();
+}
+function isWorkers() {
+	return typeof navigator !== "undefined" && navigator.userAgent === "Cloudflare-Workers";
+}
+async function createServer(app, current) {
+	const config = app.config.get("socketio", {});
+	const { Server } = await import("socket.io");
+	const path = config.path ?? "/socket.io/";
+	const cors = config.cors === false ? void 0 : config.cors ?? {
+		origin: app.config.get("cors.origin", void 0) ?? true,
+		credentials: true
+	};
+	const io = new Server({
+		path,
+		serveClient: false,
+		destroyUpgrade: false,
+		...cors && { cors },
+		...config.options
+	});
+	if (config.adapter?.driver === "redis") {
+		const [{ createAdapter }, ioredis] = await Promise.all([import("@socket.io/redis-adapter"), import("ioredis")]);
+		const pub = new (ioredis.Redis ?? ioredis.default)(config.adapter.url ?? "redis://127.0.0.1:6379");
+		const sub = pub.duplicate();
+		io.adapter(createAdapter(pub, sub, { key: config.adapter.key ?? "socket.io" }));
+		current.close.push(() => pub.quit(), () => sub.quit());
+	}
+	const prefix = path.replace(/\/$/, "");
+	const extension = {
+		name: "socket.io",
+		matches: (pathname) => pathname === prefix || pathname.startsWith(`${prefix}/`),
+		node: (server) => void io.attach(server)
+	};
+	if (globalThis.Bun) {
+		const { Server: Engine } = await import("@socket.io/bun-engine");
+		const engine = new Engine({
+			path,
+			...cors && { cors }
+		});
+		io.bind(engine);
+		const handler = engine.handler();
+		const registered = {
+			...extension,
+			bun: {
+				handle: (request, server) => engine.handleRequest(request, server),
+				owns: (ws) => typeof ws.data === "object" && ws.data !== null && "transport" in ws.data,
+				websocket: handler.websocket,
+				idleTimeout: handler.idleTimeout
+			}
+		};
+		registerServerExtension(registered);
+		current.close.push(() => unregisterServerExtension("socket.io", registered));
+	} else {
+		registerServerExtension(extension);
+		current.close.push(() => unregisterServerExtension("socket.io", extension));
+	}
+	return io;
+}
+/**
+* Socket.IO 服务提供者（app/provider/SocketProvider.ts：`export default socketIoProvider()`）：
+* 创建 socket.io Server（跨热更新保留），注册 app/socket 下的命名空间，挂到框架的 HTTP 服务器。
+* 新连接总是使用最新的命名空间定义；Edge / Serverless 运行时上不启动。
+*/
+function socketIoProvider() {
+	return { async register(container, app) {
+		if (isWorkers()) {
+			app.logger.warn("socket.io is not supported on Cloudflare Workers (use r.ws() with Durable Objects); socketIoProvider() is skipped");
+			return;
+		}
+		const current = state();
+		current.app = app;
+		current.starting ??= createServer(app, current).then((io) => current.io = io);
+		const io = await current.starting;
+		container.instance(SocketIOServer, io);
+		for (const [file, definition] of app.discovered("sockets")) {
+			if (!isNamespace(definition)) throw new TypeError("app/socket/*.ts must export default defineNamespace(...)");
+			const name = namespaceName(file, definition);
+			current.definitions.set(name, definition);
+			if (current.wired.has(name)) continue;
+			current.wired.add(name);
+			const namespace = io.of(name);
+			namespace.use((socket, next) => runMiddleware(current.definitions.get(name)?.middleware ?? [], socket, next));
+			namespace.on("connection", (socket) => {
+				Promise.resolve(current.definitions.get(name)?.connection(socket, io, namespace)).catch((error) => {
+					current.app?.logger.error(`socket.io ${name} connection handler failed`, error);
+				});
+			});
+		}
+	} };
+}
+/**
+* 握手鉴权：按 config/auth.ts 的 Guard 识别用户，存入 `socket.data.user`。
+* 令牌取 `io({ auth: { token } })` 或 Authorization 头；Session Guard 读握手请求的 Cookie。
+* 未登录时拒绝连接，客户端收到 connect_error（message 为 unauthorized）。
+*/
+function authenticate(options = {}) {
+	return async (socket, next) => {
+		const app = state().app;
+		if (!app) return next(/* @__PURE__ */ new Error("socket.io is not configured"));
+		const { headers, url, auth } = socket.handshake;
+		const requestHeaders = new Headers();
+		for (const [key, value] of Object.entries(headers)) if (value !== void 0) requestHeaders.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+		if (typeof auth?.token === "string") requestHeaders.set("authorization", `Bearer ${auth.token}`);
+		const target = /^https?:\/\//.test(url) ? url : `http://${headers.host ?? "localhost"}${url}`;
+		const user = await app.contextFor(new Request(target, { headers: requestHeaders })).auth.guard(options.guard).user().catch(() => void 0);
+		if (user === void 0 && !options.optional) return next(Object.assign(/* @__PURE__ */ new Error("unauthorized"), { data: { code: 401 } }));
+		socket.data.user = user;
+		next();
+	};
+}
+function server() {
+	const io = state().io;
+	if (!io) throw new Error("socket.io is not running: add socketIoProvider() in app/provider");
+	return io;
+}
+const SocketIO = {
+	get server() {
+		return server();
+	},
+	emit: (event, ...args) => server().emit(event, ...args),
+	to: (room) => server().to(room),
+	except: (room) => server().except(room),
+	of: (namespace) => server().of(namespace)
+};
+/** 测试中释放（通常随 app.dispose() 自动释放） */
+async function closeSocketIO() {
+	const current = state();
+	await closeServer(current.io);
+	current.io = void 0;
+	current.starting = void 0;
+	current.wired.clear();
+}
+export { SocketIO, SocketIOServer, authenticate, closeSocketIO, defineNamespace, defineSocketIOConfig, isNamespace, socketIoProvider };

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@hazejs/socket.io",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "0.1.1",
+  "description": "Socket.IO server integration for hazejs (namespaces, guard auth, Redis adapter, Node and Bun)",
+  "license": "MIT",
+  "homepage": "https://github.com/penna-org/haze/tree/main/packages/socketio#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/penna-org/haze.git",
+    "directory": "packages/socketio"
+  },
+  "bugs": {
+    "url": "https://github.com/penna-org/haze/issues"
+  },
+  "keywords": [
+    "hazejs",
+    "haze",
+    "nodejs",
+    "typescript",
+    "socket.io",
+    "websocket",
+    "realtime"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "peerDependencies": {
+    "@socket.io/bun-engine": "^0.1.2",
+    "@socket.io/redis-adapter": "^8.3.0",
+    "ioredis": "^6.0.0",
+    "socket.io": "^4.8.0",
+    "@hazejs/core": "^0.1.1"
+  },
+  "peerDependenciesMeta": {
+    "@socket.io/bun-engine": {
+      "optional": true
+    },
+    "@socket.io/redis-adapter": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@socket.io/bun-engine": "^0.1.2",
+    "@socket.io/redis-adapter": "^8.3.0",
+    "ioredis": "^6.0.0",
+    "socket.io": "^4.8.4",
+    "socket.io-client": "^4.8.4",
+    "@hazejs/core": "0.1.1",
+    "@hazejs/vite": "0.1.1"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
 }