@fraqjs/fraq 0.2.0 → 0.3.0

package/README.md

@@ -23,11 +23,8 @@ Fraq 需要在 Node.js 22+ 环境（或其他的支持 WebSocket API 的服务
 ```typescript
 import { Context, msg, param } from '@fraqjs/fraq';
 
-const ctx = Context.create({
-  connect: {
-    baseUrl: '<替换成你的 Milky 协议端地址>',
-    // accessToken: '<如果你的 Milky 协议端配置了 token，请在这里添加>',
-  },
+const ctx = Context.fromUrl('<替换成你的 Milky 协议端地址>', {
+  // accessToken: '<如果你的 Milky 协议端配置了 token，请在这里添加>',
 });
 
 ctx.router.command(

package/dist/index.d.mts

@@ -5396,21 +5396,27 @@ type EventMap = {
 };
 //#endregion
 //#region src/protocol/client.d.ts
+interface MilkyEventSubscription {
+  closed: Promise<void>;
+  stop(): void | Promise<void>;
+}
+interface MilkyClient extends ApiEndpoints {
+  startEvents(onEvent: (event: Event) => void | Promise<void>): Promise<MilkyEventSubscription>;
+}
 declare class MilkyClientBase {
   readonly baseUrl: string;
   readonly wsBaseUrl: string;
   private readonly accessToken?;
   private readonly baseHeaders;
   constructor(
-    baseUrl: string,
+    baseUrl: string | URL,
     options?: {
       accessToken?: string;
     },
   );
   callApi(endpoint: string, params?: unknown): Promise<unknown>;
-  openEventWebSocket(onEvent: (event: MessageEvent) => void): Promise<WebSocket>;
+  startEvents(onEvent: (event: Event) => void | Promise<void>): Promise<MilkyEventSubscription>;
 }
-type MilkyClient = MilkyClientBase & ApiEndpoints;
 declare function createMilkyClient(...params: ConstructorParameters<typeof MilkyClientBase>): MilkyClient;
 //#endregion
 //#region src/routing/tokenizer.d.ts
@@ -5568,19 +5574,22 @@ declare function definePlugin<T extends ParameterList>(plugin: Plugin<T>): Plugi
 //#endregion
 //#region src/core/context.d.ts
 interface ContextOptions {
-  connect: {
-    baseUrl: string;
-    accessToken?: string;
-    initialReconnectDelay?: number;
-    maxReconnectDelay?: number;
+  reconnect?: {
+    initialDelayMs?: number;
+    maxDelayMs?: number;
   };
   logHandler?: (message: LogMessage) => void;
 }
+interface ContextUrlOptions {
+  accessToken?: string;
+}
 declare class Context {
   readonly client: MilkyClient;
   readonly router: Router;
   readonly logger: Logger;
+  readonly name: string;
   private readonly parent?;
+  private readonly filter?;
   private readonly eventBus;
   private readonly plugins;
   private readonly services;
@@ -5596,16 +5605,18 @@ declare class Context {
   resolve<T extends object>(service: ServiceClass<T>): T;
   tryResolve<T extends object>(service: ServiceClass<T>): T | undefined;
   isProvided<T extends object>(service: ServiceClass<T>): boolean;
-  fork(filter?: Filter): Context;
+  fork(name: string, filter?: Filter): Context;
   start(): Promise<void>;
+  private acceptsParentEvent;
   private applyPlugins;
   private sortPlugins;
   private collectAvailableServices;
   private createUnresolvablePluginError;
   private createProxyContextForPlugin;
-  private connectEventWebSocket;
+  private runEventStream;
   private createSession;
-  static create(options: ContextOptions): Context;
+  static fromUrl(baseUrl: string | URL, options?: ContextOptions & ContextUrlOptions): Context;
+  static fromClient(client: MilkyClient, options?: ContextOptions): Context;
 }
 //#endregion
 //#region src/protocol/segment.d.ts
@@ -5652,11 +5663,13 @@ export {
   ApiEndpoints,
   Context,
   ContextOptions,
+  ContextUrlOptions,
   EventMap,
   Filter,
   LogMessage,
   Logger,
   MilkyClient,
+  MilkyEventSubscription,
   Parameter,
   ParameterList,
   Plugin,

package/dist/index.mjs

@@ -6,7 +6,8 @@ var MilkyClientBase = class {
 	accessToken;
 	baseHeaders;
 	constructor(baseUrl, options) {
-		this.baseUrl = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+		const normalizedBaseUrl = baseUrl.toString();
+		this.baseUrl = normalizedBaseUrl.endsWith("/") ? normalizedBaseUrl.slice(0, -1) : normalizedBaseUrl;
 		this.wsBaseUrl = this.baseUrl.replace(/^http/, "ws");
 		this.accessToken = options?.accessToken;
 		this.baseHeaders = { "Content-Type": "application/json" };
@@ -18,18 +19,41 @@ var MilkyClientBase = class {
 			body: JSON.stringify(params ?? {}),
 			headers: this.baseHeaders
 		});
-		if (!response.ok) throw new Error(`API call failed with status ${response.status}`);
+		if (!response.ok) throw new Error(`API call ${endpoint} failed with HTTP status ${response.status}`);
 		const json = await response.json();
-		if (json.status === "failed") throw new Error(`API call failed with retcode ${json.retcode}: ${json.message}`);
+		if (json.status === "failed") throw new Error(`API call ${endpoint} failed with retcode ${json.retcode}: ${json.message}`);
 		return json.data;
 	}
-	async openEventWebSocket(onEvent) {
+	async startEvents(onEvent) {
 		const ws = new WebSocket(`${this.wsBaseUrl}/event${this.accessToken ? `?access_token=${this.accessToken}` : ""}`);
-		ws.addEventListener("message", onEvent);
-		return new Promise((resolve, reject) => {
-			ws.addEventListener("open", () => resolve(ws));
+		let closeSubscription = () => {};
+		const closed = new Promise((resolve, reject) => {
+			closeSubscription = (error) => {
+				if (error) reject(error);
+				else resolve();
+			};
+		});
+		ws.addEventListener("message", async (event) => {
+			try {
+				if (typeof event.data !== "string") throw new Error(`Expected text frame, got ${typeof event.data}`);
+				await onEvent(JSON.parse(event.data));
+			} catch (error) {
+				closeSubscription(error);
+				ws.close();
+			}
+		});
+		await new Promise((resolve, reject) => {
+			ws.addEventListener("open", () => resolve(), { once: true });
 			ws.addEventListener("error", (event) => reject(/* @__PURE__ */ new Error(`WebSocket error: ${event}`)));
 		});
+		ws.addEventListener("error", (event) => closeSubscription(/* @__PURE__ */ new Error(`WebSocket error: ${event}`)));
+		ws.addEventListener("close", () => closeSubscription(), { once: true });
+		return {
+			closed,
+			stop() {
+				ws.close();
+			}
+		};
 	}
 };
 function createMilkyClient(...params) {
@@ -288,8 +312,10 @@ const DEFAULT_MAX_RECONNECT_DELAY_MS = 3e4;
 var Context = class Context {
 	client;
 	router = new Router();
-	logger = new Logger((message) => this.logHandler?.(message), "context");
+	logger;
+	name;
 	parent;
+	filter;
 	eventBus = mitt();
 	plugins = [];
 	services = /* @__PURE__ */ new Map();
@@ -298,24 +324,24 @@ var Context = class Context {
 	maxReconnectDelayMs;
 	logHandler;
 	isStarted = false;
-	constructor(client, options, parent, filter) {
+	constructor(client, options, name, parent, filter) {
 		this.client = client;
-		this.initialReconnectDelayMs = options?.connect.initialReconnectDelay ?? DEFAULT_INITIAL_RECONNECT_DELAY_MS;
-		this.maxReconnectDelayMs = options?.connect.maxReconnectDelay ?? DEFAULT_MAX_RECONNECT_DELAY_MS;
+		this.initialReconnectDelayMs = options?.reconnect?.initialDelayMs ?? DEFAULT_INITIAL_RECONNECT_DELAY_MS;
+		this.maxReconnectDelayMs = options?.reconnect?.maxDelayMs ?? DEFAULT_MAX_RECONNECT_DELAY_MS;
 		this.logHandler = options?.logHandler ?? parent?.logHandler;
+		this.name = name ?? "root";
+		this.logger = new Logger((message) => this.logHandler?.(message), this.name);
 		this.parent = parent;
+		this.filter = filter;
 		parent?.eventBus.on("*", (type, event) => {
-			if (filter) {
-				const predicate = filter[type];
-				if (predicate && !predicate(event)) return;
-			}
+			if (!this.acceptsParentEvent(type, event)) return;
 			this.eventBus.emit(type, event);
 		});
 		this.eventBus.on("message_receive", async ({ data: message }) => {
 			try {
-				this.router.dispatch(this.createSession(message), message);
+				await this.router.dispatch(this.createSession(message), message);
 			} catch (error) {
-				console.error("Error routing command:", error);
+				this.logger.error(`Error routing command (scene=${message.message_scene} peer=${message.peer_id} sender=${message.sender_id} seq=${message.message_seq})`, error);
 			}
 		});
 	}
@@ -324,7 +350,7 @@ var Context = class Context {
 			try {
 				await handler(event);
 			} catch (error) {
-				console.error(`Error handling event ${type}:`, error);
+				this.logger.error(`Error handling event ${type}`, error);
 			}
 		});
 	}
@@ -350,8 +376,8 @@ var Context = class Context {
 	isProvided(service) {
 		return this.tryResolve(service) !== void 0;
 	}
-	fork(filter) {
-		const subContext = new Context(this.client, void 0, this, filter);
+	fork(name, filter) {
+		const subContext = new Context(this.client, void 0, name, this, filter);
 		this.subContexts.push(subContext);
 		return subContext;
 	}
@@ -360,13 +386,20 @@ var Context = class Context {
 		await this.applyPlugins();
 		for (const subContext of this.subContexts) await subContext.start();
 		this.isStarted = true;
-		if (!this.parent) this.connectEventWebSocket();
+		if (!this.parent) this.runEventStream();
+	}
+	acceptsParentEvent(type, event) {
+		if (!this.filter) return true;
+		const predicate = this.filter[type];
+		return predicate?.(event) === true;
 	}
 	async applyPlugins() {
 		for (const { plugin, args } of this.sortPlugins()) {
 			const providedBeforeApply = new Set(this.services.keys());
+			this.logger.info(`Applying plugin ${plugin.name}`);
 			await plugin.apply(this.createProxyContextForPlugin(plugin), ...args);
 			for (const service of plugin.provides ?? []) if (!this.services.has(service) || providedBeforeApply.has(service)) throw new Error(`${plugin.name} declares service ${getServiceName(service)} but did not provide it.`);
+			this.logger.debug(`Applied plugin ${plugin.name}`);
 		}
 	}
 	sortPlugins() {
@@ -417,25 +450,21 @@ var Context = class Context {
 			else return target[prop];
 		} });
 	}
-	async connectEventWebSocket() {
+	async runEventStream() {
 		let reconnectDelay = this.initialReconnectDelayMs;
 		while (this.isStarted) {
 			try {
-				const ws = await this.client.openEventWebSocket((event) => {
+				const subscription = await this.client.startEvents((event) => {
 					try {
-						if (typeof event.data !== "string") throw new Error(`Expected text frame, got ${typeof event.data}`);
-						const payload = JSON.parse(event.data);
-						this.eventBus.emit(payload.event_type, payload);
+						this.eventBus.emit(event.event_type, event);
 					} catch (error) {
-						console.error("Error handling WebSocket event:", error);
+						this.logger.error("Error handling event stream event", error);
 					}
 				});
 				reconnectDelay = this.initialReconnectDelayMs;
-				await new Promise((resolve) => {
-					ws.addEventListener("close", () => resolve(), { once: true });
-				});
+				await subscription.closed;
 			} catch (error) {
-				console.error("Error connecting event WebSocket:", error);
+				this.logger.error("Error connecting event stream", error);
 			}
 			await new Promise((resolve) => setTimeout(resolve, reconnectDelay));
 			reconnectDelay = Math.min(reconnectDelay * 2, this.maxReconnectDelayMs);
@@ -461,13 +490,16 @@ var Context = class Context {
 							break;
 					}
 				} catch (error) {
-					console.error("Error sending reply:", error);
+					this.logger.error(`Error sending reply (source msg: scene=${message.message_scene} peer=${message.peer_id} sender=${message.sender_id} seq=${message.message_seq})`, error);
 				}
 			}
 		};
 	}
-	static create(options) {
-		return new Context(createMilkyClient(options.connect.baseUrl, { accessToken: options.connect.accessToken }), options);
+	static fromUrl(baseUrl, options) {
+		return new Context(createMilkyClient(baseUrl, { accessToken: options?.accessToken }), options);
+	}
+	static fromClient(client, options) {
+		return new Context(client, options);
 	}
 };
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fraqjs/fraq",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Milky Bot framework",
   "files": [
     "dist"
@@ -23,7 +23,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsdown && node scripts/format-dts-comments.mjs && biome format --vcs-enabled=false --write dist/index.d.mts",
+    "build": "tsdown && tsx scripts/format-dts-comments.ts && biome format --vcs-enabled=false --write dist/index.d.mts",
     "test": "tsx --test test/*.test.ts"
   }
 }