@interactive-inc/flume 0.2.0 → 0.4.0

package/dist/discord.js

@@ -1,50 +1,8 @@
-import { n as createFlumeDefaultDeps, t as FlumeLogger } from "./logger-CpGB9WO_.js";
-import { a as FlumeConnectionError, i as FlumeParseError, n as FlumeReconnector, r as resolveFlumeReconnectConfig, t as scheduleFlumeReconnect } from "./schedule-reconnect-DSxZJG3h.js";
-import { t as FlumeSerialQueue } from "./serial-queue-ExmlnpzQ.js";
-import { n as isRecord, t as safeJsonParse } from "./safe-json-parse-WCg_x1JS.js";
+import { a as FlumeParseError, c as safeNormalizeError, i as FlumeStartError, l as safeErrorMessage, n as FlumeLogger, o as createFlumeDefaultDeps, r as safeNow, s as attempt, t as safeInvokeCallback } from "./safe-invoke-callback-EpWXwfwp.js";
+import { t as FlumeConnectionError } from "./connection-error-HUO3PC3G.js";
+import { a as FlumeReconnector, i as resolveFlumeReconnectConfig, n as isRecord, o as safeRandom, r as scheduleFlumeReconnect, t as safeStringify } from "./safe-stringify-BWS-uXZP.js";
+import { i as safeJsonParse, n as FlumeStatusEmitter, r as FlumeSignalRegistry, t as FlumeSerialQueue } from "./serial-queue-B9LoBc64.js";
 import { z } from "zod/v4";
-//#region lib/discord/extract-discord-meta.ts
-function extractDiscordMeta(eventName, eventData) {
-	const meta = { event_type: eventName };
-	if (typeof eventData.channel_id === "string") meta.channel_id = eventData.channel_id;
-	if (typeof eventData.guild_id === "string") meta.guild_id = eventData.guild_id;
-	if (isRecord(eventData.author) && typeof eventData.author.id === "string") meta.user_id = eventData.author.id;
-	return meta;
-}
-//#endregion
-//#region lib/discord/discord-heartbeat.ts
-var FlumeDiscordHeartbeat = class {
-	props;
-	timer = null;
-	ackReceived = true;
-	constructor(props) {
-		this.props = props;
-	}
-	start(intervalMs) {
-		this.stop();
-		this.ackReceived = true;
-		this.timer = this.props.deps.setInterval(() => {
-			if (!this.ackReceived) {
-				this.props.onZombie();
-				return;
-			}
-			this.ackReceived = false;
-			this.props.onSend();
-		}, intervalMs);
-	}
-	stop() {
-		if (this.timer === null) return;
-		this.props.deps.clearInterval(this.timer);
-		this.timer = null;
-	}
-	ack() {
-		this.ackReceived = true;
-	}
-	isRunning() {
-		return this.timer !== null;
-	}
-};
-//#endregion
 //#region lib/discord/discord-gateway-session.ts
 var FlumeDiscordGatewaySession = class FlumeDiscordGatewaySession {
 	sessionId;
@@ -85,27 +43,116 @@ var FlumeDiscordGatewaySession = class FlumeDiscordGatewaySession {
 	}
 };
 //#endregion
+//#region lib/discord/discord-heartbeat.ts
+/**
+* Discord Gateway のハートビート。
+* 初回送信は `random()*heartbeat_interval` ms 後 (spec)、以降は heartbeat_interval ごと。
+* 前回送信に対する ACK が来ていなければ zombie 通知。すべての callback / timer body は throw を
+* 飲み込みログ記録する (host の timer queue に uncaught を漏らさない)
+*/
+var FlumeDiscordHeartbeat = class {
+	props;
+	initialTimer = null;
+	intervalTimer = null;
+	ackReceived = true;
+	constructor(props) {
+		this.props = props;
+	}
+	start(intervalMs) {
+		this.stop();
+		this.ackReceived = true;
+		const initialDelay = safeRandom({ deps: this.props.deps }) * intervalMs;
+		const initialResult = attempt(() => this.props.deps.setTimeout(() => {
+			this.initialTimer = null;
+			this.safeFire();
+			const intervalResult = attempt(() => this.props.deps.setInterval(() => this.safeFire(), intervalMs));
+			if (intervalResult instanceof Error) {
+				this.props.log.error({
+					action: "heartbeat.interval.schedule.error",
+					message: safeErrorMessage({ error: intervalResult }),
+					error: intervalResult
+				});
+				this.intervalTimer = null;
+			} else this.intervalTimer = intervalResult;
+		}, initialDelay));
+		if (initialResult instanceof Error) {
+			this.props.log.error({
+				action: "heartbeat.initial.schedule.error",
+				message: safeErrorMessage({ error: initialResult }),
+				error: initialResult
+			});
+			this.initialTimer = null;
+		} else this.initialTimer = initialResult;
+	}
+	stop() {
+		if (this.initialTimer !== null) {
+			const handle = this.initialTimer;
+			const r = attempt(() => this.props.deps.clearTimeout(handle));
+			if (r instanceof Error) this.props.log.error({
+				action: "heartbeat.initial.clear.error",
+				message: safeErrorMessage({ error: r }),
+				error: r
+			});
+			this.initialTimer = null;
+		}
+		if (this.intervalTimer !== null) {
+			const handle = this.intervalTimer;
+			const r = attempt(() => this.props.deps.clearInterval(handle));
+			if (r instanceof Error) this.props.log.error({
+				action: "heartbeat.interval.clear.error",
+				message: safeErrorMessage({ error: r }),
+				error: r
+			});
+			this.intervalTimer = null;
+		}
+	}
+	ack() {
+		this.ackReceived = true;
+	}
+	isRunning() {
+		return this.initialTimer !== null || this.intervalTimer !== null;
+	}
+	safeFire() {
+		safeInvokeCallback({
+			fn: () => this.fire(),
+			onError: (error) => {
+				this.props.log.error({
+					action: "heartbeat.fire.error",
+					message: safeErrorMessage({ error }),
+					error
+				});
+			}
+		});
+	}
+	fire() {
+		if (!this.ackReceived) {
+			this.props.onZombie();
+			return;
+		}
+		this.ackReceived = false;
+		this.props.onSend();
+	}
+};
+//#endregion
 //#region lib/discord/discord-gateway-message-schema.ts
 const FlumeGatewayMessageSchema = z.object({
 	op: z.number(),
-	d: z.record(z.string(), z.unknown()).nullable(),
+	d: z.unknown(),
 	s: z.number().nullable(),
 	t: z.string().nullable()
 });
 //#endregion
 //#region lib/discord/parse-discord-gateway-message.ts
-function parseDiscordGatewayMessage(raw) {
+function parseFlumeDiscordGatewayMessage(raw) {
 	const json = safeJsonParse(raw);
+	if (json instanceof FlumeParseError) return json;
 	const parsed = FlumeGatewayMessageSchema.safeParse(json);
-	if (!parsed.success) return new FlumeParseError(`invalid gateway message: ${raw.slice(0, 200)}`);
+	if (!parsed.success) return new FlumeParseError(`invalid gateway message frame (${raw.length} bytes)`, { cause: parsed.error });
 	return parsed.data;
 }
 //#endregion
 //#region lib/discord/discord-gateway.ts
 const GATEWAY_URL = "wss://gateway.discord.gg/?v=10&encoding=json";
-function framePreview(raw) {
-	return raw.length > 200 ? `${raw.slice(0, 200)}... (${raw.length} bytes)` : raw;
-}
 const OP_DISPATCH = 0;
 const OP_HEARTBEAT = 1;
 const OP_IDENTIFY = 2;
@@ -124,15 +171,33 @@ const OP_NAMES = {
 	[OP_HELLO]: "HELLO",
 	[OP_HEARTBEAT_ACK]: "HEARTBEAT_ACK"
 };
+const WS_OPEN = 1;
+const TERMINAL_CLOSE_CODES = new Set([
+	4004,
+	4010,
+	4011,
+	4012,
+	4013,
+	4014
+]);
+/**
+* Discord Gateway v10 の最小実装。HELLO -> IDENTIFY/RESUME -> READY/RESUMED -> dispatch を扱う。
+* READY 後の WebSocket 切断のみ `onStatus("disconnected")` を発火し source 側で再接続する。
+* 終端 close code (4004 / 401x) を受けた場合は stopped 化して再接続を抑止。
+* IO 境界は全て `attempt` 経由で扱い、コンストラクタ throw も `FlumeConnectionError` として返す
+* (`connect()` は決して reject しない)
+*/
 var FlumeDiscordGateway = class {
 	props;
 	log;
 	ws = null;
 	heartbeat = null;
-	session = FlumeDiscordGatewaySession.empty();
-	stopped = false;
+	currentSession = FlumeDiscordGatewaySession.empty();
+	isStoppedFlag = false;
+	hasConnected = false;
 	pendingResolve = null;
 	pendingResolved = false;
+	invalidSessionTimer = null;
 	constructor(props) {
 		this.props = props;
 		this.log = new FlumeLogger({
@@ -141,20 +206,65 @@ var FlumeDiscordGateway = class {
 			deps: props.deps
 		});
 	}
+	get session() {
+		return this.currentSession;
+	}
+	get isStopped() {
+		return this.isStoppedFlag;
+	}
 	connect(url) {
+		const WS = this.props.deps.WebSocket;
+		if (!WS) {
+			const error = new FlumeConnectionError("WebSocket runtime not available");
+			this.log.error({
+				action: "ws.error",
+				message: safeErrorMessage({ error }),
+				error
+			});
+			return Promise.resolve(error);
+		}
 		const target = url ?? GATEWAY_URL;
+		const hostResult = attempt(() => new URL(target).hostname);
+		const host = hostResult instanceof Error ? "unknown" : hostResult;
 		this.log.info({
 			action: "connect.start",
-			message: `url=${new URL(target).hostname}`
+			message: `host=${host}`
 		});
 		this.pendingResolved = false;
+		this.hasConnected = false;
 		return new Promise((resolve) => {
 			this.pendingResolve = resolve;
-			const socket = new this.props.deps.WebSocket(target);
+			const socketResult = attempt(() => new WS(target));
+			if (socketResult instanceof Error) {
+				const error = new FlumeConnectionError(`WebSocket construction failed: ${safeErrorMessage({ error: socketResult })}`, { cause: socketResult });
+				this.log.error({
+					action: "ws.construct.error",
+					message: safeErrorMessage({ error }),
+					error
+				});
+				this.ws = null;
+				this.pendingResolved = true;
+				resolve(error);
+				return;
+			}
+			const socket = socketResult;
 			this.ws = socket;
-			socket.addEventListener("message", (ev) => this.onMessage(String(ev.data), socket));
-			socket.addEventListener("close", (ev) => this.onClose(ev));
-			socket.addEventListener("error", () => this.onError());
+			const listenerResult = attempt(() => {
+				socket.addEventListener("message", (ev) => this.safeOnMessage(ev, socket));
+				socket.addEventListener("close", (ev) => this.safeOnClose(ev));
+				socket.addEventListener("error", () => this.safeOnError());
+			});
+			if (listenerResult instanceof Error) {
+				const error = new FlumeConnectionError(`WebSocket listener registration failed: ${safeErrorMessage({ error: listenerResult })}`, { cause: listenerResult });
+				this.log.error({
+					action: "ws.listener.error",
+					message: safeErrorMessage({ error }),
+					error
+				});
+				this.ws = null;
+				this.pendingResolved = true;
+				resolve(error);
+			}
 		});
 	}
 	disconnect() {
@@ -162,45 +272,71 @@ var FlumeDiscordGateway = class {
 			action: "disconnect",
 			message: "shutting down gateway"
 		});
-		this.stopped = true;
+		this.isStoppedFlag = true;
 		this.heartbeat?.stop();
-		if (this.ws) {
-			this.ws.close(1e3, "shutdown");
-			this.ws = null;
-		}
+		this.clearInvalidSessionTimer();
+		this.closeSocket({
+			ws: this.ws,
+			code: 1e3,
+			reason: "shutdown"
+		});
+		this.ws = null;
 	}
 	isConnected() {
-		return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+		return this.ws !== null && this.ws.readyState === WS_OPEN;
 	}
 	completeConnect(error) {
 		if (this.pendingResolved || !this.pendingResolve) return;
 		this.pendingResolved = true;
 		this.pendingResolve(error);
 	}
-	onMessage(raw, socket) {
-		this.log.debug({
-			action: "ws.recv",
-			message: framePreview(raw)
+	safeOnMessage(ev, socket) {
+		const r = attempt(() => this.onMessage(String(ev.data), socket));
+		if (r instanceof Error) this.log.error({
+			action: "ws.message.threw",
+			message: safeErrorMessage({ error: r }),
+			error: r
+		});
+	}
+	safeOnClose(ev) {
+		const r = attempt(() => this.onClose(ev));
+		if (r instanceof Error) this.log.error({
+			action: "ws.close.threw",
+			message: safeErrorMessage({ error: r }),
+			error: r
 		});
-		const parsed = parseDiscordGatewayMessage(raw);
+	}
+	safeOnError() {
+		const r = attempt(() => this.onError());
+		if (r instanceof Error) this.log.error({
+			action: "ws.error.threw",
+			message: safeErrorMessage({ error: r }),
+			error: r
+		});
+	}
+	onMessage(raw, socket) {
+		if (this.isStoppedFlag) return;
+		const parsed = parseFlumeDiscordGatewayMessage(raw);
 		if (parsed instanceof FlumeParseError) {
 			this.log.error({
-				action: "ws.parse-error",
+				action: "ws.parse.error",
 				message: parsed.message,
-				error: parsed
+				error: parsed,
+				detail: { length: raw.length }
 			});
 			return;
 		}
 		this.log.debug({
-			action: "ws.frame",
-			message: `op=${OP_NAMES[parsed.op] ?? parsed.op} t=${parsed.t ?? "-"} s=${parsed.s ?? "-"}`,
+			action: "ws.recv",
+			message: `op=${OP_NAMES[parsed.op] ?? parsed.op} t=${parsed.t ?? "-"} s=${parsed.s ?? "-"} length=${raw.length}`,
 			detail: {
 				op: parsed.op,
 				t: parsed.t,
-				s: parsed.s
+				s: parsed.s,
+				length: raw.length
 			}
 		});
-		if (parsed.s !== null) this.session = this.session.withSeq(parsed.s);
+		if (parsed.s !== null) this.currentSession = this.currentSession.withSeq(parsed.s);
 		if (parsed.op === OP_HELLO) return this.onHello(parsed);
 		if (parsed.op === OP_HEARTBEAT_ACK) return this.onHeartbeatAck();
 		if (parsed.op === OP_HEARTBEAT) return this.onHeartbeatRequest();
@@ -208,27 +344,31 @@ var FlumeDiscordGateway = class {
 		if (parsed.op === OP_INVALID_SESSION) return this.onInvalidSession(parsed, socket);
 		if (parsed.op === OP_DISPATCH) return this.onDispatch(parsed);
 		this.log.warn({
-			action: "ws.unknown-op",
+			action: "ws.op.unknown",
 			message: `unknown op=${parsed.op}`,
 			detail: { op: parsed.op }
 		});
 	}
 	onHello(msg) {
-		const interval = typeof msg.d?.heartbeat_interval === "number" ? msg.d.heartbeat_interval : 0;
+		const d = isRecord(msg.d) ? msg.d : null;
+		const interval = d && typeof d.heartbeat_interval === "number" ? d.heartbeat_interval : 0;
 		this.log.info({
-			action: "hello",
-			message: `heartbeat_interval=${interval}ms`
+			action: "gateway.hello",
+			message: `heartbeat_interval=${interval}ms`,
+			detail: { interval }
 		});
+		this.heartbeat?.stop();
 		this.heartbeat = new FlumeDiscordHeartbeat({
+			log: this.log,
 			deps: this.props.deps,
 			onSend: () => {
 				this.log.debug({
 					action: "heartbeat.send",
-					message: `seq=${this.session.seq}`
+					message: `seq=${this.currentSession.seq}`
 				});
 				this.send({
 					op: OP_HEARTBEAT,
-					d: this.session.seq
+					d: this.currentSession.seq
 				});
 			},
 			onZombie: () => {
@@ -236,11 +376,15 @@ var FlumeDiscordGateway = class {
 					action: "heartbeat.zombie",
 					message: "no ACK received, closing connection"
 				});
-				this.ws?.close(4009, "zombie connection");
+				this.closeSocket({
+					ws: this.ws,
+					code: 4009,
+					reason: "zombie connection"
+				});
 			}
 		});
 		this.heartbeat.start(interval);
-		if (this.session.canResume()) this.sendResume();
+		if (this.currentSession.canResume()) this.sendResume();
 		else this.sendIdentify();
 	}
 	onHeartbeatAck() {
@@ -257,95 +401,185 @@ var FlumeDiscordGateway = class {
 		});
 		this.send({
 			op: OP_HEARTBEAT,
-			d: this.session.seq
+			d: this.currentSession.seq
 		});
 	}
 	onReconnectRequest(socket) {
 		this.log.info({
-			action: "reconnect.requested",
+			action: "ws.reconnect.requested",
 			message: "server requested reconnect"
 		});
-		socket.close(4e3, "reconnect requested");
+		this.closeSocket({
+			ws: socket,
+			code: 4e3,
+			reason: "reconnect requested"
+		});
 	}
 	onInvalidSession(msg, socket) {
-		const resumable = !!msg.d;
+		const resumable = msg.d === true || isRecord(msg.d) && msg.d.resumable === true;
 		this.log.warn({
-			action: "invalid-session",
-			message: `resumable=${resumable}`
-		});
-		this.session = this.session.withReset();
-		if (resumable) {
-			const delay = 1e3 + this.props.deps.random() * 4e3;
-			this.log.info({
-				action: "identify.delayed",
-				message: `re-identify in ${Math.round(delay)}ms`
+			action: "session.invalid",
+			message: `resumable=${resumable}`,
+			detail: { resumable }
+		});
+		const delay = 1e3 + safeRandom({ deps: this.props.deps }) * 4e3;
+		if (!resumable) this.currentSession = this.currentSession.withReset();
+		this.clearInvalidSessionTimer();
+		const timerResult = attempt(() => this.props.deps.setTimeout(() => {
+			this.invalidSessionTimer = null;
+			this.closeSocket({
+				ws: socket,
+				code: 4e3,
+				reason: "invalid session"
+			});
+		}, delay));
+		if (timerResult instanceof Error) {
+			this.log.error({
+				action: "session.invalid.timer.error",
+				message: safeErrorMessage({ error: timerResult }),
+				error: timerResult
 			});
-			this.props.deps.setTimeout(() => this.sendIdentify(), delay);
-		} else socket.close(4e3, "invalid session");
+			this.invalidSessionTimer = null;
+		} else this.invalidSessionTimer = timerResult;
 	}
 	onDispatch(msg) {
-		if (msg.t === "READY" && msg.d) {
-			const sessionId = typeof msg.d.session_id === "string" ? msg.d.session_id : "";
-			const resumeUrl = typeof msg.d.resume_gateway_url === "string" ? msg.d.resume_gateway_url : "";
-			this.session = this.session.withReady(sessionId, resumeUrl);
+		const d = isRecord(msg.d) ? msg.d : null;
+		if (msg.t === "READY" && d) {
+			const sessionId = typeof d.session_id === "string" ? d.session_id : "";
+			const resumeUrl = typeof d.resume_gateway_url === "string" ? d.resume_gateway_url : "";
+			this.currentSession = this.currentSession.withReady(sessionId, resumeUrl);
 			this.log.info({
-				action: "ready",
-				message: `session=${sessionId}`
+				action: "gateway.ready",
+				message: `session ready`,
+				detail: { hasResumeUrl: resumeUrl !== "" }
 			});
+			this.hasConnected = true;
 			this.props.onStatus("connected");
 			this.completeConnect(null);
 		}
 		if (msg.t === "RESUMED") {
 			this.log.info({
-				action: "resumed",
-				message: `session=${this.session.sessionId} seq=${this.session.seq}`
+				action: "gateway.resumed",
+				message: `seq=${this.currentSession.seq}`
 			});
+			this.hasConnected = true;
 			this.props.onStatus("connected");
 			this.completeConnect(null);
 		}
-		if (msg.t && msg.d) this.props.onDispatch(msg.t, msg.d);
-		else if (msg.t) this.props.onDispatch(msg.t, {});
+		if (msg.t && d) this.props.onDispatch(msg.t, d);
+		else if (msg.t) this.log.debug({
+			action: "dispatch.empty",
+			message: `dropped ${msg.t} (no payload)`,
+			detail: { type: msg.t }
+		});
 	}
 	onClose(ev) {
+		const terminal = TERMINAL_CLOSE_CODES.has(ev.code);
 		this.log.info({
 			action: "ws.close",
-			message: `code=${ev.code} reason=${ev.reason || "none"}`,
+			message: `code=${ev.code} reason=${ev.reason || "none"}${terminal ? " (terminal)" : ""}`,
 			detail: {
 				code: ev.code,
-				reason: ev.reason
+				reason: ev.reason,
+				terminal
 			}
 		});
 		this.ws = null;
 		this.heartbeat?.stop();
-		this.props.onStatus("disconnected");
-		this.completeConnect(new FlumeConnectionError(`WebSocket closed before ready (code=${ev.code})`));
+		this.clearInvalidSessionTimer();
+		if (terminal) this.isStoppedFlag = true;
+		if (this.hasConnected || terminal) this.props.onStatus("disconnected");
+		if (!this.pendingResolved) {
+			const error = new FlumeConnectionError(`WebSocket closed before ready (code=${ev.code})`, { code: ev.code });
+			this.completeConnect(error);
+		}
 	}
 	onError() {
+		const error = new FlumeConnectionError("WebSocket connection error");
 		this.log.error({
 			action: "ws.error",
-			message: "WebSocket error event"
+			message: safeErrorMessage({ error }),
+			error
 		});
-		this.completeConnect(new FlumeConnectionError("WebSocket connection error"));
+		this.completeConnect(error);
 	}
-	send(input) {
-		const payload = JSON.stringify({
-			op: input.op,
-			d: input.d ?? null
+	clearInvalidSessionTimer() {
+		if (this.invalidSessionTimer === null) return;
+		const handle = this.invalidSessionTimer;
+		const result = attempt(() => this.props.deps.clearTimeout(handle));
+		if (result instanceof Error) this.log.error({
+			action: "session.invalid.timer.clear.error",
+			message: safeErrorMessage({ error: result }),
+			error: result
 		});
+		this.invalidSessionTimer = null;
+	}
+	closeSocket(input) {
+		if (input.ws === null) return;
+		const ws = input.ws;
+		const result = attempt(() => {
+			if (input.code !== void 0) ws.close(input.code, input.reason ?? "");
+			else ws.close();
+		});
+		if (result instanceof Error) this.log.error({
+			action: "ws.close.error",
+			message: safeErrorMessage({ error: result }),
+			error: result
+		});
+	}
+	send(input) {
+		const payload = this.safeSerialize(input);
+		if (payload === null) return;
 		this.log.debug({
 			action: "ws.send",
-			message: `op=${OP_NAMES[input.op] ?? input.op}`,
-			detail: { op: input.op }
+			message: `op=${OP_NAMES[input.op] ?? input.op} length=${payload.length}`,
+			detail: {
+				op: input.op,
+				length: payload.length
+			}
 		});
-		this.ws?.send(payload);
-		this.log.debug({
-			action: "ws.sent",
-			message: framePreview(payload)
+		const ws = this.ws;
+		if (ws === null) {
+			this.log.warn({
+				action: "ws.send",
+				message: "ws.send skipped: socket is null"
+			});
+			return;
+		}
+		if (ws.readyState !== WS_OPEN) {
+			this.log.warn({
+				action: "ws.send",
+				message: `ws.send skipped: readyState=${ws.readyState} (not OPEN)`,
+				detail: { readyState: ws.readyState }
+			});
+			return;
+		}
+		const result = attempt(() => ws.send(payload));
+		if (result instanceof Error) this.log.error({
+			action: "ws.send",
+			message: `ws.send failed: ${safeErrorMessage({ error: result })}`,
+			error: result
 		});
 	}
+	safeSerialize(input) {
+		const result = safeStringify({
+			op: input.op,
+			d: input.d ?? null
+		});
+		if (result instanceof Error) {
+			this.log.error({
+				action: "ws.send.serialize.error",
+				message: safeErrorMessage({ error: result }),
+				error: result,
+				detail: { op: input.op }
+			});
+			return null;
+		}
+		return result;
+	}
 	sendIdentify() {
 		this.log.info({
-			action: "identify",
+			action: "gateway.identify",
 			message: `intents=${this.props.intents}`
 		});
 		this.send({
@@ -363,15 +597,15 @@ var FlumeDiscordGateway = class {
 	}
 	sendResume() {
 		this.log.info({
-			action: "resume",
-			message: `session=${this.session.sessionId} seq=${this.session.seq}`
+			action: "gateway.resume",
+			message: `seq=${this.currentSession.seq}`
 		});
 		this.send({
 			op: OP_RESUME,
 			d: {
 				token: this.props.token,
-				session_id: this.session.sessionId,
-				seq: this.session.seq
+				session_id: this.currentSession.sessionId,
+				seq: this.currentSession.seq
 			}
 		});
 	}
@@ -402,18 +636,40 @@ const FlumeDiscordGatewayIntents = {
 	DirectMessagePolls: 1 << 25
 };
 //#endregion
+//#region lib/discord/extract-discord-meta.ts
+function flumeExtractDiscordMeta(eventName, eventData) {
+	const meta = { event_type: eventName };
+	if (typeof eventData.channel_id === "string") meta.channel_id = eventData.channel_id;
+	if (typeof eventData.guild_id === "string") meta.guild_id = eventData.guild_id;
+	if (isRecord(eventData.author) && typeof eventData.author.id === "string") meta.user_id = eventData.author.id;
+	return meta;
+}
+//#endregion
 //#region lib/discord/discord-source.ts
-const DEFAULT_INTENTS = FlumeDiscordGatewayIntents.Guilds | FlumeDiscordGatewayIntents.GuildMessages | FlumeDiscordGatewayIntents.DirectMessages | FlumeDiscordGatewayIntents.MessageContent;
+const DEFAULT_INTENTS = FlumeDiscordGatewayIntents.Guilds | FlumeDiscordGatewayIntents.GuildMessages | FlumeDiscordGatewayIntents.DirectMessages;
 var FlumeDiscordSource = class {
 	options;
 	name = "discord";
 	gateway = null;
 	reconnector = null;
 	handler = null;
-	currentStatus = "disconnected";
 	log;
 	deps;
 	queue = new FlumeSerialQueue();
+	signals;
+	statusEmitter;
+	onSignalAbort = () => {
+		safeInvokeCallback({
+			fn: () => this.stop(),
+			onError: (error) => {
+				this.log.error({
+					action: "signal.abort.stop.failed",
+					message: safeErrorMessage({ error }),
+					error
+				});
+			}
+		});
+	};
 	constructor(options) {
 		this.options = options;
 		this.deps = options.deps ?? createFlumeDefaultDeps();
@@ -422,25 +678,37 @@ var FlumeDiscordSource = class {
 			handler: options.onLog,
 			deps: this.deps
 		});
+		this.signals = new FlumeSignalRegistry({
+			log: this.log,
+			onAbort: this.onSignalAbort
+		});
+		this.statusEmitter = new FlumeStatusEmitter({
+			log: this.log,
+			onStatus: options.onStatus
+		});
 		const rc = resolveFlumeReconnectConfig(options.reconnect);
 		if (rc) this.reconnector = new FlumeReconnector({
 			...rc,
+			log: this.log,
 			deps: this.deps
 		});
 	}
-	async start(handler) {
-		if (this.options.signal?.aborted) return /* @__PURE__ */ new Error("Discord source: signal already aborted");
-		this.options.signal?.addEventListener("abort", () => this.stop(), { once: true });
+	async start(handler, options) {
+		if (this.signals.isAnyAborted(this.options.signal) || this.signals.isAnyAborted(options?.signal)) return new FlumeStartError("Discord source: signal already aborted");
+		if (!this.hasWebSocket()) return new FlumeStartError("Discord source: deps.WebSocket is null (no WebSocket runtime available)");
+		this.signals.register(this.options.signal);
+		this.signals.register(options?.signal);
 		this.handler = handler;
 		this.log.info({
-			action: "start",
+			action: "source.start",
 			message: "starting Discord source"
 		});
-		return this.connectInternal();
+		return await this.connectInternal();
 	}
 	async stop() {
+		this.signals.unregisterAll();
 		this.log.info({
-			action: "stop",
+			action: "source.stop",
 			message: "stopping Discord source"
 		});
 		if (this.reconnector && !this.reconnector.aborted) this.log.debug({
@@ -449,16 +717,29 @@ var FlumeDiscordSource = class {
 		});
 		this.reconnector?.cancel();
 		this.gateway?.disconnect();
+		await this.queue.drain();
 		this.gateway = null;
 		this.handler = null;
-		await this.queue.drain();
-		this.setStatus("disconnected");
+		this.statusEmitter.set("disconnected");
 	}
 	status() {
-		return this.currentStatus;
+		return this.statusEmitter.value;
+	}
+	hasWebSocket() {
+		const result = attempt(() => Boolean(this.deps.WebSocket));
+		if (result instanceof Error) {
+			const error = safeNormalizeError({ value: result });
+			this.log.error({
+				action: "deps.web-socket.read.error",
+				message: safeErrorMessage({ error }),
+				error
+			});
+			return false;
+		}
+		return result;
 	}
 	async connectInternal(resumeUrl) {
-		this.setStatus("connecting");
+		this.statusEmitter.set("connecting");
 		this.gateway = new FlumeDiscordGateway({
 			token: this.options.token,
 			intents: this.options.intents ?? DEFAULT_INTENTS,
@@ -471,36 +752,50 @@ var FlumeDiscordSource = class {
 		if (error instanceof FlumeConnectionError) {
 			this.log.error({
 				action: "connect.failed",
-				message: error.message,
+				message: safeErrorMessage({ error }),
 				error
 			});
-			if (!this.reconnector || this.reconnector.aborted) {
-				this.setStatus("disconnected");
+			if (this.gateway.isStopped || !this.reconnector || this.reconnector.aborted) {
+				this.statusEmitter.set("disconnected");
 				return error;
 			}
 			this.scheduleReconnect();
 		}
+		return null;
 	}
 	handleDispatch(eventName, eventData) {
-		const event = {
-			source: "discord",
-			type: eventName,
-			data: eventData,
-			meta: extractDiscordMeta(eventName, eventData),
-			receivedAt: this.deps.now()
-		};
+		const handler = this.handler;
+		if (!handler) return;
 		this.queue.add(async () => {
-			try {
-				await this.handler?.(event);
-			} catch (err) {
-				this.log.error({
-					action: "handler.error",
-					message: "user handler threw",
-					error: err instanceof Error ? err : new Error(String(err))
-				});
-			}
+			const event = {
+				source: "discord",
+				type: eventName,
+				data: eventData,
+				meta: this.safeExtractMeta(eventName, eventData),
+				receivedAt: safeNow({ deps: this.deps })
+			};
+			const r = await attempt(() => Promise.resolve(handler(event)));
+			if (r instanceof Error) this.log.error({
+				action: "handler.error",
+				message: safeErrorMessage({ error: r }),
+				error: r
+			});
 		});
 	}
+	safeExtractMeta(eventName, eventData) {
+		const result = attempt(() => flumeExtractDiscordMeta(eventName, eventData));
+		if (result instanceof Error) {
+			const error = safeNormalizeError({ value: result });
+			this.log.warn({
+				action: "meta.extract.error",
+				message: safeErrorMessage({ error }),
+				error,
+				detail: { eventName }
+			});
+			return { event_type: eventName };
+		}
+		return result;
+	}
 	handleGatewayStatus(status) {
 		if (status === "connected") {
 			if (this.reconnector && this.reconnector.attempt > 0) this.log.info({
@@ -508,30 +803,34 @@ var FlumeDiscordSource = class {
 				message: `cleared ${this.reconnector.attempt} attempts`
 			});
 			this.reconnector?.reset();
-			this.setStatus("connected");
+			this.statusEmitter.set("connected");
+			return;
+		}
+		if (this.gateway?.isStopped) {
+			this.statusEmitter.set("disconnected");
+			return;
 		}
-		if (status === "disconnected" && !this.gateway?.stopped) this.scheduleReconnect();
+		this.scheduleReconnect();
 	}
 	scheduleReconnect() {
 		const url = this.gateway?.session.resumeUrl ?? void 0;
 		scheduleFlumeReconnect({
 			reconnector: this.reconnector,
 			log: this.log,
-			setStatus: (status) => this.setStatus(status),
+			setStatus: (status) => this.statusEmitter.set(status),
 			retry: () => {
-				this.connectInternal(url);
+				this.connectInternal(url).catch((err) => {
+					const error = safeNormalizeError({ value: err });
+					this.log.error({
+						action: "reconnect.unhandled",
+						message: safeErrorMessage({ error }),
+						error
+					});
+					this.statusEmitter.set("disconnected");
+				});
 			}
 		});
 	}
-	setStatus(next) {
-		if (this.currentStatus === next) return;
-		this.log.info({
-			action: "status",
-			message: `${this.currentStatus} → ${next}`
-		});
-		this.currentStatus = next;
-		this.options.onStatus?.(next);
-	}
 };
 //#endregion
-export { FlumeDiscordGateway, FlumeDiscordGatewayIntents, FlumeDiscordGatewaySession, FlumeDiscordHeartbeat, FlumeDiscordSource, FlumeGatewayMessageSchema, extractDiscordMeta, parseDiscordGatewayMessage };
+export { FlumeDiscordGatewayIntents, FlumeDiscordSource, flumeExtractDiscordMeta };