diff --git a/packages/common/package.json b/packages/common/package.json
index fafb638e..4d0243dd 100644
--- a/packages/common/package.json
+++ b/packages/common/package.json
@@ -24,6 +24,10 @@
"types": "./src/env.ts",
"default": "./src/env.ts"
},
+ "./notification-templates": {
+ "types": "./src/notification-templates.ts",
+ "default": "./src/notification-templates.ts"
+ },
"./single-flight-cache": {
"types": "./src/single-flight-cache.ts",
"default": "./src/single-flight-cache.ts"
diff --git a/packages/common/src/notification-templates.ts b/packages/common/src/notification-templates.ts
new file mode 100644
index 00000000..cbba4056
--- /dev/null
+++ b/packages/common/src/notification-templates.ts
@@ -0,0 +1,14 @@
+export const DEFAULT_WEBHOOK_BODY = `{
+ "title": "账号状态通知:{event}",
+ "desp": "您的账号状态发生了改变。\\n\\n**昵称**:{nickname}\\n**QQ号**:{uin}\\n**当前状态**:{event}\\n**进程状态**:{status}\\n**时间**:{time}"
+}`;
+
+export const DEFAULT_EMAIL_SUBJECT = '账号{event}:{nickname} ({uin})';
+
+export const DEFAULT_EMAIL_BODY = `账号状态发生了改变。
+
+昵称:{nickname}
+QQ号:{uin}
+当前状态:{event}
+进程状态:{status}
+时间:{time}`;
diff --git a/packages/core/src/bridge/bridge.ts b/packages/core/src/bridge/bridge.ts
index dd5a9341..e0fc521e 100644
--- a/packages/core/src/bridge/bridge.ts
+++ b/packages/core/src/bridge/bridge.ts
@@ -16,19 +16,19 @@ const log = createLogger('Bridge');
const runtimeLog = createLogger('Bridge.Runtime');
const VERBOSE_WARMUP = process.env.SNOWLUMA_VERBOSE_WARMUP === '1';
+interface ProcessConnection {
+ pid: number;
+ client: PacketSender;
+ receiveHealthy: boolean;
+}
+
export class Bridge implements BridgeInterface {
readonly identity: IdentityService;
- private pids_ = new Set();
- private readonly receiveHealthByPid_ = new Map();
- /** Packet senders keyed by their owning QQ process. Keeping the sender and
- * PID together is what makes disconnect fallback deterministic: a sender
- * can never outlive the PID that supplied it. */
- private readonly packetClientsByPid_ = new Map();
+ /** Insertion order tracks login recency; the newest connection sends packets. */
+ private readonly connections = new Map();
readonly events = new BridgeEventBus();
readonly apis: ApiHub;
private readonly pipeline: IncomingPacketPipeline;
- private packetClient_: PacketSender | null = null;
- private packetClientPid_: number | null = null;
private static readonly UPLOADED_FILE_CACHE_MAX = 1024;
private uploadedFileMeta_ = new Map();
private clientSeq_ = 100000000 + (Date.now() % 1000000000);
@@ -40,9 +40,10 @@ export class Bridge implements BridgeInterface {
private disposePromise_: Promise | null = null;
private readonly pendingPackets_ = new Set>();
private rosterWarmupStarted_ = false;
- private rosterWarmupSettled_ = false;
- private rosterWarmupResult_: RosterWarmupResult | null = null;
- private readonly rosterWarmupWaiters_: Array<(result: RosterWarmupResult) => void> = [];
+ private settleRosterWarmup!: (result: RosterWarmupResult) => void;
+ private readonly rosterWarmup = new Promise((resolve) => {
+ this.settleRosterWarmup = resolve;
+ });
constructor(identity: IdentityService) {
this.identity = identity;
@@ -151,11 +152,7 @@ export class Bridge implements BridgeInterface {
this.disposed_ = true;
this.settleRosterWarmup({ friendsLoaded: false, groupsLoaded: false });
- this.pids_.clear();
- this.receiveHealthByPid_.clear();
- this.packetClientsByPid_.clear();
- this.packetClient_ = null;
- this.packetClientPid_ = null;
+ this.connections.clear();
this.onlineClients_ = null;
this.disposePromise_ = (async () => {
try {
@@ -168,22 +165,6 @@ export class Bridge implements BridgeInterface {
return this.disposePromise_;
}
- /** Legacy two-step setter retained for external compatibility. It assigns
- * the sender to the most recently attached PID when one exists. New
- * BridgeManager code uses bindPid() for an atomic transition. */
- setPacketClient(client: PacketSender): void {
- this.packetClient_ = client;
- const pids = [...this.pids_];
- const pid = pids.length > 0 ? pids[pids.length - 1]! : null;
- this.packetClientPid_ = pid;
-
- if (pid !== null) {
- this.packetClientsByPid_.set(pid, client);
- }
-
- this.maybeStartRosterWarmup();
- }
-
registerCmd(cmd: string, parser: CmdParser): void {
this.pipeline.registerCmd(cmd, parser);
}
@@ -192,34 +173,18 @@ export class Bridge implements BridgeInterface {
return this.pipeline.handlesCmd(cmd);
}
- /** Attach a process without a sender. Retained for compatibility; the
- * manager uses bindPid() for the atomic PID+sender transition. Re-attaching
- * deliberately refreshes recency. */
- attachPid(pid: number): void {
- this.pids_.delete(pid);
- this.pids_.add(pid);
- // A fresh/rebound login starts UNKNOWN-but-compatible. The receive
- // watchdog only flips this false after observing QQ's own heartbeat and
- // then missing the full stale + confirmation window.
- this.receiveHealthByPid_.set(pid, true);
- }
-
- /** Atomically attach a process and make its sender the active sender.
- * Set insertion order is the recency order used for fallback. */
bindPid(pid: number, client: PacketSender): void {
- const previousPid = this.packetClientPid_;
- const previousClient = this.packetClient_;
- this.attachPid(pid);
- this.packetClientsByPid_.set(pid, client);
- this.packetClient_ = client;
- this.packetClientPid_ = pid;
+ const previous = this.activeConnection;
+ this.connections.delete(pid);
+ // A new login stays healthy until the watchdog confirms a failure.
+ this.connections.set(pid, { pid, client, receiveHealthy: true });
- if (previousPid !== pid || previousClient !== client) {
+ if (previous?.pid !== pid || previous.client !== client) {
runtimeLog.trace(
'bridge_sender_fact event=selected uin=%j pid=%d previousPid=%j',
this.identity.uin,
pid,
- previousPid,
+ previous?.pid ?? null,
);
}
@@ -229,84 +194,59 @@ export class Bridge implements BridgeInterface {
/** @internal BridgeManager lookup used when an incoming packet is the first
* observation that a live PID changed UIN. */
packetClientForPid(pid: number): PacketSender | null {
- return this.packetClientsByPid_.get(pid) ?? null;
+ return this.connections.get(pid)?.client ?? null;
}
detachPid(pid: number): void {
- this.pids_.delete(pid);
- this.receiveHealthByPid_.delete(pid);
- this.packetClientsByPid_.delete(pid);
+ const wasActive = this.activePid === pid;
+ this.connections.delete(pid);
+ const active = this.activeConnection;
- if (this.packetClientPid_ !== pid) {
- // An unscoped legacy sender cannot be associated with a particular PID.
- // It is safe to retain while another PID exists, but never after the
- // Bridge becomes empty.
- if (this.pids_.size === 0) {
- this.packetClient_ = null;
- this.packetClientPid_ = null;
- }
-
- return;
+ if (wasActive && active) {
+ runtimeLog.trace(
+ 'bridge_sender_fact event=fallback uin=%j detachedPid=%d fallbackPid=%d',
+ this.identity.uin,
+ pid,
+ active.pid,
+ );
+ log.debug(
+ 'packet sender changed: UIN=%s PID=%d→%d',
+ this.identity.uin,
+ pid,
+ active.pid,
+ );
}
-
- this.selectFallbackPacketClient(pid);
}
hasPid(pid: number): boolean {
- return this.pids_.has(pid);
+ return this.connections.has(pid);
}
get empty(): boolean {
- return this.pids_.size === 0;
+ return this.connections.size === 0;
+ }
+ private get activeConnection(): ProcessConnection | undefined {
+ return [...this.connections.values()].at(-1);
}
get activePid(): number | null {
- if (this.packetClientPid_ !== null && this.pids_.has(this.packetClientPid_)) {
- return this.packetClientPid_;
- }
-
- const pids = [...this.pids_];
- return pids.length > 0 ? pids[pids.length - 1]! : null;
+ return this.activeConnection?.pid ?? null;
}
get receiveHealthy(): boolean {
- for (const pid of this.pids_) {
- const healthy = this.receiveHealthByPid_.get(pid);
-
- if (healthy === undefined) {
- const message = `Bridge receive-health invariant violated: PID=${pid} has no health state`;
- log.error(message);
- throw new Error(message);
- }
-
- if (healthy) {
- return true;
- }
- }
-
- return false;
+ return [...this.connections.values()].some((connection) => connection.receiveHealthy);
}
setPidReceiveHealthy(pid: number, healthy: boolean): void {
- if (!this.pids_.has(pid)) {
+ const connection = this.connections.get(pid);
+
+ if (!connection) {
throw new Error(`Bridge receive-health invariant violated: PID=${pid} is not attached`);
}
- this.receiveHealthByPid_.set(pid, healthy);
+ connection.receiveHealthy = healthy;
}
getOnlineClients(): readonly Readonly[] | null {
return this.onlineClients_;
}
whenRosterWarmupSettled(): Promise {
- if (this.rosterWarmupSettled_ && this.rosterWarmupResult_) {
- return Promise.resolve(this.rosterWarmupResult_);
- }
-
- this.maybeStartRosterWarmup();
- return new Promise((resolve) => {
- if (this.rosterWarmupSettled_ && this.rosterWarmupResult_) {
- resolve(this.rosterWarmupResult_);
- return;
- }
-
- this.rosterWarmupWaiters_.push(resolve);
- });
+ return this.rosterWarmup;
}
onPacket(pkt: PacketInfo): Promise {
@@ -358,7 +298,9 @@ export class Bridge implements BridgeInterface {
body: Uint8Array,
timeoutMs = packetTimeoutMs(),
): Promise {
- if (!this.packetClient_) {
+ const connection = this.activeConnection;
+
+ if (!connection) {
return runWithTraceRequest(() => {
const startedAt = Date.now();
runtimeLog.trace(() => [
@@ -391,11 +333,7 @@ export class Bridge implements BridgeInterface {
}
const startedAt = Date.now();
- const result = await this.packetClient_.sendPacket(
- serviceCmd,
- Buffer.from(body),
- timeoutMs,
- );
+ const result = await connection.client.sendPacket(serviceCmd, Buffer.from(body), timeoutMs);
const elapsed = Date.now() - startedAt;
const respLen = result.responseData ? result.responseData.length : 0;
@@ -424,52 +362,12 @@ export class Bridge implements BridgeInterface {
return result;
}
- private selectFallbackPacketClient(detachedPid: number): void {
- const pids = [...this.pids_];
-
- for (let index = pids.length - 1; index >= 0; index -= 1) {
- const fallbackPid = pids[index]!;
- const fallback = this.packetClientsByPid_.get(fallbackPid);
-
- if (!fallback) {
- continue;
- }
-
- this.packetClient_ = fallback;
- this.packetClientPid_ = fallbackPid;
- runtimeLog.trace(
- 'bridge_sender_fact event=fallback uin=%j detachedPid=%d fallbackPid=%d',
- this.identity.uin,
- detachedPid,
- fallbackPid,
- );
- log.debug(
- 'packet sender fallback: UIN=%s detached PID=%d fallback PID=%d',
- this.identity.uin,
- detachedPid,
- fallbackPid,
- );
- return;
- }
-
- this.packetClient_ = null;
- this.packetClientPid_ = null;
-
- if (this.pids_.size > 0) {
- log.warn(
- 'packet sender unavailable after PID detach: UIN=%s detached PID=%d remaining PIDs=%d',
- this.identity.uin,
- detachedPid,
- this.pids_.size,
- );
- }
- }
async resolveUserUid(uin: number, groupId?: number): Promise {
return this.identity.resolveUid(uin, groupId);
}
private maybeStartRosterWarmup(): void {
- if (this.disposed_ || this.rosterWarmupStarted_ || !this.packetClient_) {
+ if (this.disposed_ || this.rosterWarmupStarted_ || this.empty) {
return;
}
@@ -495,20 +393,6 @@ export class Bridge implements BridgeInterface {
);
}
- private settleRosterWarmup(result: RosterWarmupResult): void {
- if (this.rosterWarmupSettled_) {
- return;
- }
-
- this.rosterWarmupSettled_ = true;
- this.rosterWarmupResult_ = result;
- const waiters = this.rosterWarmupWaiters_.splice(0);
-
- for (const resolve of waiters) {
- resolve(result);
- }
- }
-
private stillOpen(): boolean {
return !this.disposed_;
}
diff --git a/packages/core/src/bridge/manager.ts b/packages/core/src/bridge/manager.ts
index a718acc5..d0be9b2d 100644
--- a/packages/core/src/bridge/manager.ts
+++ b/packages/core/src/bridge/manager.ts
@@ -6,7 +6,7 @@ import { IdentityService } from '@snowluma/protocol/identity-service';
import { Bridge } from './bridge';
export type SessionStartedCallback = (uin: string, bridge: Bridge) => void;
-export type SessionClosedCallback = (uin: string, bridge: Bridge) => void;
+export type SessionClosedCallback = (uin: string, bridge: Bridge, pid: number) => void;
interface QQSession {
bridge: Bridge;
@@ -64,8 +64,8 @@ export class BridgeManager {
/** Additive subscription: every observer (OneBotManager, NotificationManager,
* …) receives every session edge. (Was a single `set*Callback` setter —
* converted to N listeners so a second observer can't clobber the first.)
- * The close edge now carries the bridge too, since callers read the last
- * nickname before it is disposed. */
+ * The close edge carries the final detached PID and the bridge so observers
+ * can identify the process and read its nickname before disposal. */
addSessionStartedListener(cb: SessionStartedCallback): void {
this.sessionStartedListeners_.push(cb);
}
@@ -86,10 +86,10 @@ export class BridgeManager {
}
}
- private fireSessionClosed(uin: string, bridge: Bridge): void {
+ private fireSessionClosed(uin: string, bridge: Bridge, pid: number): void {
for (const cb of this.sessionClosedListeners_) {
try {
- cb(uin, bridge);
+ cb(uin, bridge, pid);
} catch (err) {
log.warn(
'session-closed listener threw: %s',
@@ -397,12 +397,6 @@ export class BridgeManager {
throw new Error(message);
}
- if (!session.bridge.packetClientForPid(pid)) {
- const message = `BridgeManager invariant violated: PID=${pid} is mapped to UIN=${uin}, but Bridge has no sender for the PID`;
- log.error(message);
- throw new Error(message);
- }
-
// Validation is complete. Mutate both sides only after the ownership
// invariant is known to hold, so a fail-fast error preserves the evidence.
this.pidToUin_.delete(pid);
@@ -415,7 +409,7 @@ export class BridgeManager {
this.sessions_.delete(uin);
log.debug('session closed: UIN=%s', uin);
// Fire before dispose() so listeners can still read bridge.identity.
- this.fireSessionClosed(uin, session.bridge);
+ this.fireSessionClosed(uin, session.bridge, pid);
this.closeSession(uin, session.bridge);
return true;
}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index be8b71c5..b4c5a6af 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -91,7 +91,14 @@ async function main() {
// Global notification subsystem (account up/down → webhook). Bound AFTER
// OneBotManager so the nickname fallback is already populated when it observes.
- const notificationManager = createNotificationManager();
+ // Lifecycle events identify their PID; an older process with the same UIN
+ // must not supply facts for a recovered account.
+ const notificationManager = createNotificationManager(async (uin, pid) => {
+ const found = (await hookManager.listProcesses()).find(
+ (p) => p.pid === pid && p.uin === uin,
+ );
+ return found ? { status: found.status, pid: found.pid, error: found.error } : undefined;
+ });
notificationManager.bind(bridgeManager);
let stopWebUI: (() => Promise) | undefined;
diff --git a/packages/core/src/notifications/config.ts b/packages/core/src/notifications/config.ts
index 9076cad5..dfb32fcc 100644
--- a/packages/core/src/notifications/config.ts
+++ b/packages/core/src/notifications/config.ts
@@ -1,14 +1,11 @@
-// Global notification-channel store + the pure template renderer.
-//
-// Mirrors the conventions of `webui/ui-config.ts` (the plan calls for this
-// explicitly): every `normalize*` is TOTAL — any unknown / corrupt input
-// collapses to a safe default, numbers clamp, unknown keys are dropped — and
-// persistence is an atomic write (tmp → rename) behind a module-level cache.
-//
-// Channels are GLOBAL (defined once here); each UIN opts into a subset via
-// `OneBotConfig.notifications.channelIds` (see packages/onebot/src/config.ts).
+// Global channels are selected per account by OneBotConfig.notifications.channelIds.
import { boolOr, clampInt, isObject } from '@snowluma/common/coerce';
import { createLogger } from '@snowluma/common/logger';
+import {
+ DEFAULT_WEBHOOK_BODY,
+ DEFAULT_EMAIL_BODY,
+ DEFAULT_EMAIL_SUBJECT,
+} from '@snowluma/common/notification-templates';
import fs from 'fs';
import path from 'path';
import { extractAddress, parseRecipients } from './smtp';
@@ -79,23 +76,6 @@ export interface NotificationsConfig {
channels: NotificationChannel[];
}
-/** Default body template — Server酱-style JSON ({title}/{desp}). The WebUI
- * ships additional per-vendor presets (钉钉/Discord/…) as frontend constants
- * the operator can drop in. */
-export const DEFAULT_BODY_TEMPLATE = `{
- "title": "账号状态通知:{event}",
- "desp": "您的账号状态发生了改变。\\n\\n**昵称**:{nickname}\\n**QQ号**:{uin}\\n**当前状态**:{event}\\n**时间**:{time}"
-}`;
-
-export const DEFAULT_SUBJECT_TEMPLATE = '账号{event}:{nickname} ({uin})';
-
-export const DEFAULT_EMAIL_BODY_TEMPLATE = `账号状态发生了改变。
-
-昵称:{nickname}
-QQ号:{uin}
-当前状态:{event}
-时间:{time}`;
-
const SMTP_HOST_MAX = 253;
const SMTP_USER_MAX = 256;
const SMTP_PASS_MAX = 256;
@@ -315,7 +295,7 @@ function normalizeEmailChannel(
name,
type: 'email',
url: '',
- bodyTemplate: strOr(raw.bodyTemplate, DEFAULT_EMAIL_BODY_TEMPLATE, BODY_TEMPLATE_MAX),
+ bodyTemplate: strOr(raw.bodyTemplate, DEFAULT_EMAIL_BODY, BODY_TEMPLATE_MAX),
enabled: boolOr(raw.enabled, true),
smtpHost,
smtpPort,
@@ -325,8 +305,8 @@ function normalizeEmailChannel(
from,
to,
subjectTemplate:
- strOr(raw.subjectTemplate, DEFAULT_SUBJECT_TEMPLATE, SUBJECT_TEMPLATE_MAX) ||
- DEFAULT_SUBJECT_TEMPLATE,
+ strOr(raw.subjectTemplate, DEFAULT_EMAIL_SUBJECT, SUBJECT_TEMPLATE_MAX) ||
+ DEFAULT_EMAIL_SUBJECT,
};
}
@@ -368,7 +348,7 @@ function normalizeChannel(raw: unknown): NotificationChannel | null {
name,
type: 'webhook',
url,
- bodyTemplate: strOr(raw.bodyTemplate, DEFAULT_BODY_TEMPLATE, BODY_TEMPLATE_MAX),
+ bodyTemplate: strOr(raw.bodyTemplate, DEFAULT_WEBHOOK_BODY, BODY_TEMPLATE_MAX),
enabled: boolOr(raw.enabled, true),
...(headers ? { headers } : {}),
};
diff --git a/packages/core/src/notifications/debounce.ts b/packages/core/src/notifications/debounce.ts
index ed70028f..ee6641dc 100644
--- a/packages/core/src/notifications/debounce.ts
+++ b/packages/core/src/notifications/debounce.ts
@@ -1,14 +1,5 @@
-// Per-UIN debounce state machine for online↔offline notifications.
-//
-// Uptime-Kuma semantics (grill-locked in the plan): an offline that SURVIVES
-// `debounceSeconds` fires an "offline" notification; its later recovery fires
-// the paired "online". An offline that self-heals within the window fires
-// NOTHING (the blip is suppressed). A cold online — one with no prior fired
-// offline — fires nothing (it is not a recovery).
-//
-// This module is PURE: no timers, no I/O, no clock. It only decides; the
-// manager owns the timer + the side effects. That keeps the debounce logic
-// fully unit-testable by driving a sequence of events.
+// Offline must survive the debounce window before it can emit a recovery pair.
+// The manager owns timers and delivery; this machine only decides transitions.
import type { NotificationEvent } from './config';
export type DebounceDecision =
@@ -17,80 +8,48 @@ export type DebounceDecision =
| { kind: 'cancel' }
| { kind: 'emit'; event: NotificationEvent };
-interface UinState {
- /** An offline debounce timer is armed but has not yet fired. */
- pending: boolean;
- /** An "offline" notification has fired and is awaiting its recovery. */
- firedOffline: boolean;
-}
-
export class DebounceMachine {
- private readonly states = new Map();
-
- private state(uin: string): UinState {
- let s = this.states.get(uin);
-
- if (!s) {
- s = { pending: false, firedOffline: false };
- this.states.set(uin, s);
- }
-
- return s;
- }
+ private readonly states = new Map();
/** Account went offline. `debounceSeconds` is read fresh from config so a
* reload takes effect on the next transition. */
onOffline(uin: string, debounceSeconds: number): DebounceDecision {
- const s = this.state(uin);
-
- if (s.firedOffline || s.pending) {
+ if (this.states.has(uin)) {
return { kind: 'none' };
- } // already down / already counting
+ }
- // Non-finite / non-positive → no debounce, fire immediately. Stays total:
- // never schedule a setTimeout(NaN|Infinity). Production config always
- // clamps to a finite [0,3600]; this only hardens direct callers.
if (!Number.isFinite(debounceSeconds) || debounceSeconds <= 0) {
- s.firedOffline = true;
+ this.states.set(uin, 'offline');
return { kind: 'emit', event: 'offline' };
}
- s.pending = true;
+ this.states.set(uin, 'pending');
return { kind: 'schedule', delayMs: debounceSeconds * 1000 };
}
/** Account came online. */
onOnline(uin: string): DebounceDecision {
- const s = this.state(uin);
+ const state = this.states.get(uin);
+ this.states.delete(uin);
- if (s.pending) {
- s.pending = false;
- return { kind: 'cancel' }; // self-heal within the debounce window — nothing fired
+ if (state === 'pending') {
+ return { kind: 'cancel' };
}
- if (s.firedOffline) {
- s.firedOffline = false;
- return { kind: 'emit', event: 'online' }; // recovery, paired with the fired offline
+ if (state === 'offline') {
+ return { kind: 'emit', event: 'online' };
}
- return { kind: 'none' }; // cold online / already up
+ return { kind: 'none' };
}
/** The offline debounce window elapsed (the armed timer fired). */
onTimerElapsed(uin: string): DebounceDecision {
- const s = this.state(uin);
-
- if (!s.pending) {
+ if (this.states.get(uin) !== 'pending') {
return { kind: 'none' };
- } // cancelled before firing
+ }
- s.pending = false;
- s.firedOffline = true;
+ this.states.set(uin, 'offline');
return { kind: 'emit', event: 'offline' };
}
-
- /** Drop a UIN's state (e.g. on dispose). */
- forget(uin: string): void {
- this.states.delete(uin);
- }
}
diff --git a/packages/core/src/notifications/manager.ts b/packages/core/src/notifications/manager.ts
index ceabc3f9..98ae26f4 100644
--- a/packages/core/src/notifications/manager.ts
+++ b/packages/core/src/notifications/manager.ts
@@ -9,6 +9,7 @@
// SMTP send, the clock) are injected so the class is fully unit-testable; the
// real wiring lives in `createNotificationManager()` at the bottom.
import { positiveIntEnv } from '@snowluma/common/env';
+import type { HookProcessInfo } from '@snowluma/bridge/types';
import { createLogger } from '@snowluma/common/logger';
import { loadOneBotConfig } from '@snowluma/onebot/config';
import type { BridgeManager } from '../bridge/manager';
@@ -27,9 +28,8 @@ const log = createLogger('Notifications');
const DEFAULT_HISTORY_LIMIT = 100;
const DEFAULT_POST_TIMEOUT_MS = 10_000;
-const FALLBACK_DEBOUNCE_SECONDS = 30;
-/** One delivery attempt; kept only in memory (the plan forbids persistence). */
+/** One delivery attempt, retained in bounded in-memory history. */
export interface DeliveryRecord {
time: number;
uin: string;
@@ -58,17 +58,39 @@ export interface MailPayload {
text: string;
}
+/**
+ * Optional hook process snapshot attached to a notification. Missing facts
+ * mean unknown, not proof that QQ exited. Hook status describes connectivity;
+ * it does not by itself identify the reason an account went offline.
+ * Undefined fields render empty in templates.
+ */
+export type NotificationProcessFacts = Partial>;
+
export interface NotificationManagerDeps {
/** Global channel store (channels + debounceSeconds). */
loadConfig: () => NotificationsConfig;
/** The channel ids a UIN has opted into. */
loadChannelIds: (uin: string) => string[];
- /** Webhook delivery — never throws; failures come back as `{ ok: false }`. */
+ /** Webhook delivery. Rejections are recorded as failed attempts. */
post: (url: string, body: string, headers?: Record) => Promise;
/** SMTP delivery — optional so webhook-only tests stay lean. */
sendMail?: (mail: MailPayload) => Promise;
now: () => number;
historyLimit?: number;
+ /**
+ * Optional: look up the lifecycle event's PID and UIN at dispatch time. Omitted
+ * (or resolving to `undefined`) means "process unknown" — the fact
+ * variables then render empty rather than leaving `{status}` in the body.
+ */
+ resolveProcess?: (
+ uin: string,
+ pid: number | null,
+ ) => Promise;
+}
+
+interface AccountNotificationContext {
+ nickname: string;
+ pid: number | null;
}
function errMsg(err: unknown): string {
@@ -91,8 +113,9 @@ export class NotificationManager {
private readonly deps: NotificationManagerDeps;
private readonly machine = new DebounceMachine();
private readonly timers = new Map>();
- private readonly nicknames = new Map();
+ private readonly accounts = new Map();
private readonly history: DeliveryRecord[] = [];
+ private readonly deliveries = new Map>();
private readonly historyLimit: number;
private disposed = false;
@@ -105,76 +128,65 @@ export class NotificationManager {
* OneBotManager so the nickname fallback is already populated. */
bind(bridgeManager: BridgeManager): void {
bridgeManager.addSessionStartedListener((uin, bridge) =>
- this.handleOnline(uin, bridge.identity.nickname),
+ this.handleOnline(uin, bridge.identity.nickname, bridge.activePid),
);
- bridgeManager.addSessionClosedListener((uin, bridge) =>
- this.handleOffline(uin, bridge.identity.nickname),
+ bridgeManager.addSessionClosedListener((uin, bridge, pid) =>
+ this.handleOffline(uin, bridge.identity.nickname, pid),
);
}
- handleOnline(uin: string, nickname?: string): void {
+ handleOnline(uin: string, nickname?: string, pid: number | null = null): void {
if (this.disposed) {
return;
}
- if (nickname) {
- this.nicknames.set(uin, nickname);
- }
+ this.accounts.set(uin, {
+ nickname: nickname || this.accounts.get(uin)?.nickname || uin,
+ pid,
+ });
this.apply(uin, this.machine.onOnline(uin));
}
- handleOffline(uin: string, nickname?: string): void {
+ handleOffline(uin: string, nickname?: string, pid: number | null = null): void {
if (this.disposed) {
return;
}
- if (nickname) {
- this.nicknames.set(uin, nickname);
- }
+ let debounceSeconds: number;
- this.apply(uin, this.machine.onOffline(uin, this.debounceSeconds()));
- }
-
- private debounceSeconds(): number {
try {
- return this.deps.loadConfig().debounceSeconds;
- } catch {
- return FALLBACK_DEBOUNCE_SECONDS;
+ debounceSeconds = this.deps.loadConfig().debounceSeconds;
+ } catch (err) {
+ log.warn('offline(%s) skipped — config load failed: %s', uin, errMsg(err));
+ return;
}
+
+ this.accounts.set(uin, {
+ nickname: nickname || this.accounts.get(uin)?.nickname || uin,
+ pid,
+ });
+
+ this.apply(uin, this.machine.onOffline(uin, debounceSeconds));
}
private apply(uin: string, decision: DebounceDecision): void {
switch (decision.kind) {
case 'schedule': {
- const existing = this.timers.get(uin);
-
- if (existing) {
- clearTimeout(existing);
- }
-
const timer = setTimeout(() => {
this.timers.delete(uin);
this.apply(uin, this.machine.onTimerElapsed(uin));
}, decision.delayMs);
// Don't let a pending notification timer keep the process alive.
- if (typeof (timer as { unref?: () => void }).unref === 'function') {
- (timer as { unref: () => void }).unref();
- }
-
+ timer.unref();
this.timers.set(uin, timer);
break;
}
case 'cancel': {
- const timer = this.timers.get(uin);
-
- if (timer) {
- clearTimeout(timer);
- this.timers.delete(uin);
- }
-
+ clearTimeout(this.timers.get(uin));
+ this.timers.delete(uin);
break;
}
@@ -186,9 +198,36 @@ export class NotificationManager {
}
}
- /** Render + deliver a transition to every opted-in, enabled channel and record
- * the outcome. Never throws (a bad channel can't break the others). */
- async notify(uin: string, event: NotificationEvent): Promise {
+ /** Queue one transition; channel failures are recorded independently. */
+ notify(uin: string, event: NotificationEvent): Promise {
+ if (this.disposed) {
+ return Promise.resolve();
+ }
+
+ const account = this.accounts.get(uin) ?? { nickname: uin, pid: null };
+ const previous = this.deliveries.get(uin) ?? Promise.resolve();
+ // Both enrichment and every channel delivery belong to this transition.
+ // A slow lookup/send must not let recovery overtake offline for one UIN.
+ const delivery = previous
+ .then(() => this.notifyNow(uin, event, account))
+ .finally(() => {
+ if (this.deliveries.get(uin) === delivery) {
+ this.deliveries.delete(uin);
+ }
+ });
+ this.deliveries.set(uin, delivery);
+ return delivery;
+ }
+
+ private async notifyNow(
+ uin: string,
+ event: NotificationEvent,
+ account: AccountNotificationContext,
+ ): Promise {
+ if (this.disposed) {
+ return;
+ }
+
let channels: NotificationChannel[];
try {
@@ -203,15 +242,29 @@ export class NotificationManager {
return;
}
- const nickname = this.nicknames.get(uin) || uin;
+ let facts: NotificationProcessFacts | undefined;
+
+ try {
+ facts = await this.deps.resolveProcess?.(uin, account.pid);
+ } catch (err) {
+ log.warn('resolveProcess(%s, %s) failed: %s', uin, account.pid, errMsg(err));
+ }
+
const vars: Record = {
uin,
- nickname,
+ nickname: account.nickname,
event,
time: new Date(this.deps.now()).toISOString(),
+ status: facts?.status ?? '',
+ pid: facts?.pid === undefined ? '' : String(facts.pid),
+ error: facts?.error ?? '',
};
for (const ch of channels) {
+ if (this.disposed) {
+ return;
+ }
+
const result = await this.deliver(ch, vars);
this.record({
time: this.deps.now(),
@@ -265,7 +318,6 @@ export class NotificationManager {
return await this.deps.post(ch.url, renderTemplate(ch.bodyTemplate, vars), ch.headers);
} catch (err) {
- // Injected collaborators are contracted not to throw, but guard anyway.
return { ok: false, error: errMsg(err) };
}
}
@@ -292,6 +344,9 @@ export class NotificationManager {
nickname: '测试账号',
event: 'offline' as const,
time: new Date(this.deps.now()).toISOString(),
+ status: 'disconnected',
+ pid: '1234',
+ error: '',
};
return { ...(await this.deliver(channel, vars)), found: true };
}
@@ -378,13 +433,17 @@ export function createDefaultSendMail(
};
}
-/** The real, fully-wired singleton. */
-export function createNotificationManager(): NotificationManager {
+/** The real, fully-wired singleton. `resolveProcess` is supplied by the
+ * runtime — this package deliberately knows nothing about HookManager. */
+export function createNotificationManager(
+ resolveProcess?: NotificationManagerDeps['resolveProcess'],
+): NotificationManager {
return new NotificationManager({
loadConfig: loadNotificationsConfig,
loadChannelIds: (uin) => loadOneBotConfig(uin).notifications?.channelIds ?? [],
post: createDefaultPost(),
sendMail: createDefaultSendMail(),
now: () => Date.now(),
+ resolveProcess,
});
}
diff --git a/packages/core/tests/bridge-manager-ownership.test.ts b/packages/core/tests/bridge-manager-ownership.test.ts
index 0b0f7e97..8d4e1632 100644
--- a/packages/core/tests/bridge-manager-ownership.test.ts
+++ b/packages/core/tests/bridge-manager-ownership.test.ts
@@ -339,6 +339,7 @@ describe('BridgeManager PID ownership', () => {
manager.onPidDisconnected(101);
expect(manager.getSession('10001')).toBeNull();
expect(closed).toHaveBeenCalledOnce();
+ expect(closed).toHaveBeenCalledWith('10001', bridge, 101);
await expect(
bridge.sendRawPacket('Test.NoSender', new Uint8Array([3])),
).resolves.toMatchObject({
@@ -512,7 +513,7 @@ describe('BridgeManager PID ownership', () => {
expect(started).toHaveBeenCalledTimes(2);
expect(closed).toHaveBeenCalledOnce();
- expect(closed).toHaveBeenCalledWith('10001', expect.anything());
+ expect(closed).toHaveBeenCalledWith('10001', expect.anything(), 101);
expect(manager.getSession('10001')).toBeNull();
expect(manager.getSession('20002')!.bridge).toBe(targetBridge);
expect(targetBridge.activePid).toBe(101);
@@ -561,9 +562,7 @@ describe('BridgeManager PID ownership', () => {
try {
manager.onHookLogin(101, '10001', sender.client);
- // Deliberately violate the private ownership invariant through Bridge's
- // compatibility surface: Manager still maps PID 101 to this UIN, while
- // Bridge no longer owns either the PID or its sender.
+ // Remove the connection without updating the manager's ownership index.
manager.getSession('10001')!.bridge.detachPid(101);
expect(() => manager.onPacket(packet(101, '10001'))).toThrowError(
diff --git a/packages/core/tests/bridge-roster-warmup.test.ts b/packages/core/tests/bridge-roster-warmup.test.ts
index 01de91e8..63b4fc87 100644
--- a/packages/core/tests/bridge-roster-warmup.test.ts
+++ b/packages/core/tests/bridge-roster-warmup.test.ts
@@ -68,6 +68,35 @@ function makeProfile(uin: number, uid: string, nickname: string): UserProfileInf
}
describe('Bridge roster warmup', () => {
+ it('settles all callers, including callers waiting before the first connection', async () => {
+ const bridge = new Bridge(IdentityService.memory('10001'));
+ const fetchFriends = vi
+ .spyOn(bridge.apis.contacts, 'fetchFriendList')
+ .mockResolvedValue([makeFriend(10001, 'u_self', 'me')]);
+ vi.spyOn(bridge.apis.contacts, 'fetchGroupList').mockResolvedValue([]);
+ const beforeLogin = bridge.whenRosterWarmupSettled();
+
+ bridge.bindPid(7, sender);
+ const afterLogin = bridge.whenRosterWarmupSettled();
+ const expected = { friendsLoaded: true, groupsLoaded: true };
+ await expect(Promise.all([beforeLogin, afterLogin])).resolves.toEqual([expected, expected]);
+ await expect(bridge.whenRosterWarmupSettled()).resolves.toEqual(expected);
+ expect(fetchFriends).toHaveBeenCalledOnce();
+ await bridge.dispose();
+ await expect(bridge.whenRosterWarmupSettled()).resolves.toEqual(expected);
+ });
+
+ it('releases warmup waiters when disposed before the first connection', async () => {
+ const bridge = new Bridge(IdentityService.memory('10001'));
+ const waiting = bridge.whenRosterWarmupSettled();
+ await bridge.dispose();
+ await expect(waiting).resolves.toEqual({ friendsLoaded: false, groupsLoaded: false });
+ await expect(bridge.whenRosterWarmupSettled()).resolves.toEqual({
+ friendsLoaded: false,
+ groupsLoaded: false,
+ });
+ });
+
it('fetches friends and groups after the first sender and writes Identity', async () => {
const identity = IdentityService.memory('10001');
const bridge = new Bridge(identity);
diff --git a/packages/core/tests/notifications-config.test.ts b/packages/core/tests/notifications-config.test.ts
index 9125f865..41593cde 100644
--- a/packages/core/tests/notifications-config.test.ts
+++ b/packages/core/tests/notifications-config.test.ts
@@ -3,10 +3,12 @@ import fs from 'fs';
import os from 'os';
import path from 'path';
import {
- DEFAULT_BODY_TEMPLATE,
+ DEFAULT_WEBHOOK_BODY,
+ DEFAULT_EMAIL_BODY,
+ DEFAULT_EMAIL_SUBJECT,
+} from '@snowluma/common/notification-templates';
+import {
DEFAULT_DEBOUNCE_SECONDS,
- DEFAULT_EMAIL_BODY_TEMPLATE,
- DEFAULT_SUBJECT_TEMPLATE,
defaultNotificationsConfig,
normalizeNotificationsConfig,
renderTemplate,
@@ -145,7 +147,7 @@ describe('normalizeNotificationsConfig — total normalize', () => {
expect(channels[0].enabled).toBe(true);
expect(channels[0].name).toBe('c1');
expect(channels[0].type).toBe('webhook');
- expect(channels[0].bodyTemplate).toBe(DEFAULT_BODY_TEMPLATE);
+ expect(channels[0].bodyTemplate).toBe(DEFAULT_WEBHOOK_BODY);
expect(channels[0].headers).toBeUndefined();
});
@@ -198,14 +200,14 @@ describe('normalizeNotificationsConfig — total normalize', () => {
name: 'ops-mail',
type: 'email',
url: '',
- bodyTemplate: DEFAULT_EMAIL_BODY_TEMPLATE,
+ bodyTemplate: DEFAULT_EMAIL_BODY,
enabled: true,
smtpHost: 'smtp.qq.com',
smtpPort: 465,
smtpSecure: true,
from: 'SnowLuma ',
to: 'a@example.com, b@example.com',
- subjectTemplate: DEFAULT_SUBJECT_TEMPLATE,
+ subjectTemplate: DEFAULT_EMAIL_SUBJECT,
},
]);
});
diff --git a/packages/core/tests/notifications-debounce.test.ts b/packages/core/tests/notifications-debounce.test.ts
index 30391996..a204c45d 100644
--- a/packages/core/tests/notifications-debounce.test.ts
+++ b/packages/core/tests/notifications-debounce.test.ts
@@ -62,10 +62,14 @@ describe('DebounceMachine — online↔offline debounce (Uptime-Kuma semantics)'
expect(m.onOnline('a')).toEqual({ kind: 'emit', event: 'online' });
});
- it('forget() resets a UIN to baseline', () => {
+ it('starts a new debounce cycle after recovery without retaining the old timer state', () => {
const m = new DebounceMachine();
- m.onOffline('u', 0); // fired offline
- m.forget('u');
- expect(m.onOnline('u')).toEqual({ kind: 'none' }); // state cleared → no recovery
+ m.onOffline('u', 30);
+ m.onTimerElapsed('u');
+ m.onOnline('u');
+ expect(m.onTimerElapsed('u')).toEqual({ kind: 'none' });
+ expect(m.onOffline('u', 60)).toEqual({ kind: 'schedule', delayMs: 60_000 });
+ expect(m.onOnline('u')).toEqual({ kind: 'cancel' });
+ expect(m.onOnline('u')).toEqual({ kind: 'none' });
});
});
diff --git a/packages/core/tests/notifications-lifecycle.test.ts b/packages/core/tests/notifications-lifecycle.test.ts
new file mode 100644
index 00000000..3a792b67
--- /dev/null
+++ b/packages/core/tests/notifications-lifecycle.test.ts
@@ -0,0 +1,97 @@
+import { IdentityService } from '@snowluma/protocol/identity-service';
+import type { PacketSender } from '@snowluma/common/packet-sender';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { BridgeManager } from '../src/bridge/manager';
+import { NotificationManager, type NotificationManagerDeps } from '../src/notifications/manager';
+
+const sender: PacketSender = {
+ sendPacket: async () => ({
+ success: false,
+ gotResponse: false,
+ errorCode: -1,
+ errorMessage: 'test: no QQ connection',
+ responseData: null,
+ }),
+};
+
+describe('notification lifecycle PID', () => {
+ let bridges: BridgeManager;
+ let notifications: NotificationManager;
+ const posts: string[] = [];
+ const resolveProcess = vi.fn>(
+ async (_uin, pid) => (pid === null ? undefined : { pid }),
+ );
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.spyOn(IdentityService, 'openForUin').mockImplementation((uin) =>
+ IdentityService.memory(uin),
+ );
+ posts.length = 0;
+ resolveProcess.mockClear();
+ bridges = new BridgeManager();
+ notifications = new NotificationManager({
+ loadConfig: () => ({
+ version: 1,
+ debounceSeconds: 30,
+ channels: [
+ {
+ id: 'c1',
+ name: 'C1',
+ type: 'webhook',
+ url: 'https://hook.example/c1',
+ enabled: true,
+ bodyTemplate: '{event}:{uin}:{pid}',
+ },
+ ],
+ }),
+ loadChannelIds: () => ['c1'],
+ post: async (_url, body) => {
+ posts.push(body);
+ return { ok: true };
+ },
+ now: () => Date.now(),
+ resolveProcess,
+ });
+ notifications.bind(bridges);
+ });
+
+ afterEach(async () => {
+ notifications.dispose();
+ await bridges.dispose();
+ vi.restoreAllMocks();
+ vi.useRealTimers();
+ });
+
+ it('retains the final detached PID through debounce and uses the new PID on recovery', async () => {
+ bridges.onHookLogin(1001, '12345', sender);
+ bridges.onHookLogin(2002, '12345', sender);
+ bridges.onPidDisconnected(1001);
+ await vi.advanceTimersByTimeAsync(30_000);
+ expect(posts).toEqual([]);
+
+ bridges.onPidDisconnected(2002);
+ expect(bridges.getSession('12345')).toBeNull();
+ await vi.advanceTimersByTimeAsync(30_000);
+ expect(resolveProcess).toHaveBeenNthCalledWith(1, '12345', 2002);
+
+ bridges.onHookLogin(3003, '12345', sender);
+ await vi.advanceTimersByTimeAsync(0);
+ expect(resolveProcess).toHaveBeenNthCalledWith(2, '12345', 3003);
+ expect(posts).toEqual(['offline:12345:2002', 'online:12345:3003']);
+ });
+
+ it('keeps queued event context when the same UIN recovers on another PID', async () => {
+ bridges.onHookLogin(1001, '12345', sender);
+ bridges.onPidDisconnected(1001);
+ const offline = notifications.notify('12345', 'offline');
+ bridges.onHookLogin(2002, '12345', sender);
+ const online = notifications.notify('12345', 'online');
+ await Promise.all([offline, online]);
+ expect(resolveProcess.mock.calls).toEqual([
+ ['12345', 1001],
+ ['12345', 2002],
+ ]);
+ expect(posts).toEqual(['offline:12345:1001', 'online:12345:2002']);
+ });
+});
diff --git a/packages/core/tests/notifications-manager.test.ts b/packages/core/tests/notifications-manager.test.ts
index 5a627621..b53598d1 100644
--- a/packages/core/tests/notifications-manager.test.ts
+++ b/packages/core/tests/notifications-manager.test.ts
@@ -1,10 +1,12 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { subscribeLogs, type LogEntry } from '@snowluma/common/logger';
import {
NotificationManager,
createDefaultPost,
selectChannels,
type MailPayload,
type NotificationManagerDeps,
+ type NotificationProcessFacts,
type PostResult,
} from '../src/notifications/manager';
import type { NotificationChannel, NotificationsConfig } from '../src/notifications/config';
@@ -105,6 +107,48 @@ describe('NotificationManager — dispatch + history', () => {
expect(posts[0].body).toBe('offline:123:Alice');
});
+ it('carries process facts into the template so a supervisor can act on them', async () => {
+ const { posts, mgr } = setup({
+ loadConfig: () => ({
+ version: 1,
+ debounceSeconds: 30,
+ channels: [ch({ bodyTemplate: '{event}:{uin}:{status}:{pid}:{error}' })],
+ }),
+ resolveProcess: async () => ({ status: 'disconnected', pid: 4242, error: '' }),
+ });
+ await mgr.notify('123', 'offline');
+ expect(posts[0].body).toBe('offline:123:disconnected:4242:');
+ });
+
+ it('renders fact variables empty when no resolver is configured', async () => {
+ const { posts, mgr } = setup({
+ loadConfig: () => ({
+ version: 1,
+ debounceSeconds: 30,
+ channels: [ch({ bodyTemplate: '{event}:{status}:{pid}' })],
+ }),
+ });
+ await mgr.notify('123', 'offline');
+ // No resolver → empty, not the literal placeholders.
+ expect(posts[0].body).toBe('offline::');
+ });
+
+ it('still notifies when the resolver throws', async () => {
+ const { posts, mgr } = setup({
+ loadConfig: () => ({
+ version: 1,
+ debounceSeconds: 30,
+ channels: [ch({ bodyTemplate: '{event}:{status}' })],
+ }),
+ resolveProcess: async () => {
+ throw new Error('hook manager unavailable');
+ },
+ });
+ await mgr.notify('123', 'offline');
+ expect(posts).toHaveLength(1);
+ expect(posts[0].body).toBe('offline:');
+ });
+
it('records ok and failed deliveries, most-recent-first', async () => {
let n = 0;
const { mgr } = setup({
@@ -119,6 +163,90 @@ describe('NotificationManager — dispatch + history', () => {
expect(recent[1]).toMatchObject({ event: 'offline', ok: true, status: 200 });
});
+ it('keeps offline before recovery when the offline process lookup is delayed', async () => {
+ let resolve!: (facts: NotificationProcessFacts) => void;
+ const delayed = new Promise((done) => {
+ resolve = done;
+ });
+ const resolveProcess = vi
+ .fn()
+ .mockReturnValueOnce(delayed)
+ .mockResolvedValue({ status: 'online', pid: 4242 });
+ const { posts, mgr } = setup({ resolveProcess });
+ const offline = mgr.notify('123', 'offline');
+ const online = mgr.notify('123', 'online');
+ await new Promise((done) => setImmediate(done));
+ const whileResolving = [...posts];
+ resolve({ status: 'disconnected', pid: 4242 });
+ await Promise.all([offline, online]);
+ expect(whileResolving).toEqual([]);
+ expect(posts.map((post) => post.body)).toEqual(['offline:123:123', 'online:123:123']);
+ });
+
+ it('finishes every channel before sending the recovery, even when a delivery fails', async () => {
+ let reject!: (error: Error) => void;
+ const delayed = new Promise((_resolve, fail) => {
+ reject = fail;
+ });
+ const deliveries: string[] = [];
+ const { mgr } = setup({
+ loadConfig: () => ({
+ version: 1,
+ debounceSeconds: 0,
+ channels: [ch(), ch({ id: 'c2' })],
+ }),
+ loadChannelIds: () => ['c1', 'c2'],
+ post: async (_url, body) => {
+ deliveries.push(body);
+ return deliveries.length === 1 ? delayed : { ok: true };
+ },
+ });
+ const offline = mgr.notify('123', 'offline');
+ const online = mgr.notify('123', 'online');
+ await new Promise((done) => setImmediate(done));
+ reject(new Error('delivery failed'));
+ await Promise.all([offline, online]);
+ expect(deliveries).toEqual([
+ 'offline:123:123',
+ 'offline:123:123',
+ 'online:123:123',
+ 'online:123:123',
+ ]);
+ expect(mgr.getRecent().filter((record) => !record.ok)).toHaveLength(1);
+ });
+
+ it('does not block another account behind a slow process lookup', async () => {
+ let resolve!: (facts: undefined) => void;
+ const delayed = new Promise((done) => {
+ resolve = done;
+ });
+ const { posts, mgr } = setup({
+ resolveProcess: (uin) => (uin === '123' ? delayed : Promise.resolve(undefined)),
+ });
+ const slow = mgr.notify('123', 'offline');
+ await mgr.notify('456', 'offline');
+ const whileResolving = [...posts];
+ resolve(undefined);
+ await slow;
+ expect(whileResolving.map((post) => post.body)).toEqual(['offline:456:456']);
+ expect(posts.map((post) => post.body)).toEqual(['offline:456:456', 'offline:123:123']);
+ });
+
+ it('drops queued notifications on disposal and does not deliver after a pending lookup', async () => {
+ let resolve!: (facts: undefined) => void;
+ const delayed = new Promise((done) => {
+ resolve = done;
+ });
+ const { posts, mgr } = setup({ resolveProcess: () => delayed });
+ const offline = mgr.notify('123', 'offline');
+ const online = mgr.notify('123', 'online');
+ await new Promise((done) => setImmediate(done));
+ mgr.dispose();
+ resolve(undefined);
+ await Promise.all([offline, online]);
+ expect(posts).toEqual([]);
+ });
+
it('skips channels the UIN did not opt into', async () => {
const { posts, mgr } = setup({ loadChannelIds: () => [] });
await mgr.notify('123', 'offline');
@@ -309,9 +437,7 @@ describe('NotificationManager — debounce integration (fake timers)', () => {
mgr.handleOffline('123', 'Bob'); // arm 30s timer
await vi.advanceTimersByTimeAsync(10_000);
mgr.handleOnline('123', 'Bob'); // self-heal → cancel timer
- // The machine's state guard alone would suppress the misfire; assert the
- // manager ALSO cleared the timer (defense-in-depth a pure test can't see).
- expect((mgr as unknown as { timers: Map }).timers.size).toBe(0);
+ expect(vi.getTimerCount()).toBe(0);
await vi.advanceTimersByTimeAsync(60_000);
expect(events).toEqual([]);
});
@@ -333,6 +459,50 @@ describe('NotificationManager — debounce integration (fake timers)', () => {
expect(events).toEqual(['offline']);
});
+ it('reports config failure without inventing a debounce window or a recovery event', async () => {
+ const loadConfig = vi.fn().mockImplementation(() => {
+ throw new Error('config unreadable');
+ });
+ const post = vi.fn().mockResolvedValue({ ok: true });
+ const mgr = new NotificationManager({
+ loadConfig,
+ loadChannelIds: () => ['c1'],
+ post,
+ now: () => 1000,
+ });
+ const logs: LogEntry[] = [];
+ const unsubscribe = subscribeLogs((entry) => logs.push(entry));
+
+ try {
+ mgr.handleOffline('123', 'Bob');
+ expect(vi.getTimerCount()).toBe(0);
+ expect(logs).toContainEqual(
+ expect.objectContaining({
+ scope: 'Notifications',
+ level: 'warn',
+ message: 'offline(123) skipped — config load failed: config unreadable',
+ }),
+ );
+
+ loadConfig.mockReturnValue({ version: 1, debounceSeconds: 5, channels: [ch()] });
+ await vi.advanceTimersByTimeAsync(30_000);
+ mgr.handleOnline('123', 'Bob');
+ await vi.advanceTimersByTimeAsync(0);
+ expect(post).not.toHaveBeenCalled();
+
+ mgr.handleOffline('123', 'Bob');
+ await vi.advanceTimersByTimeAsync(5_000);
+ expect(post).toHaveBeenCalledExactlyOnceWith(
+ 'https://hook.example/c1',
+ 'offline:123:Bob',
+ undefined,
+ );
+ } finally {
+ unsubscribe();
+ mgr.dispose();
+ }
+ });
+
it('ignores online/offline after dispose so process exit is not a runtime drop', async () => {
const { events, mgr } = setup(0);
mgr.dispose();
diff --git a/packages/webui/README.md b/packages/webui/README.md
index b4b83821..78bbf585 100644
--- a/packages/webui/README.md
+++ b/packages/webui/README.md
@@ -39,6 +39,21 @@ request headers. The backend still accepts `Authorization: Bearer ` for
existing clients when the dedicated header is absent. Both layers still require
their own valid credentials.
+## Account notification templates
+
+Webhook bodies and email subjects/bodies support `{uin}`, `{nickname}`, `{event}`
+(`offline` or `online`), `{time}`, `{status}` (Hook process state), `{pid}`, and
+`{error}` (Hook process error). New webhook and email channels include process
+status in their default body; existing saved templates are preserved.
+
+Process facts are resolved when the notification is dispatched, after any offline
+debounce. Each transition carries its process PID, including the final PID detached
+when an account goes offline. Facts are looked up for that PID and UIN without
+substituting another process. Missing facts render empty and mean unknown, not
+proof that QQ exited. Hook status alone does not identify the cause of a QQ login
+failure. Notifications for one account are delivered in transition order; a slow
+account does not delay other accounts.
+
## Local development
On Windows, the native API logs the process token and EXE integrity label once
diff --git a/packages/webui/src/components/settings/notification-channel-dialog.tsx b/packages/webui/src/components/settings/notification-channel-dialog.tsx
index 1fbc35c5..44f5df3e 100644
--- a/packages/webui/src/components/settings/notification-channel-dialog.tsx
+++ b/packages/webui/src/components/settings/notification-channel-dialog.tsx
@@ -3,6 +3,11 @@
// The channel id is the stable key per-account opt-ins reference, so it's
// editable only on create and locked on edit.
import { useState } from 'react';
+import {
+ DEFAULT_WEBHOOK_BODY,
+ DEFAULT_EMAIL_BODY,
+ DEFAULT_EMAIL_SUBJECT,
+} from '@snowluma/common/notification-templates';
import { Plus, Trash2 } from 'lucide-react';
import { Modal } from '@/components/interior/modal';
import { Button } from '@/components/ui/button';
@@ -65,20 +70,6 @@ function hasRecipient(value: string): boolean {
return value.split(/[,;\n]+/).some((part) => looksLikeEmail(part));
}
-export const DEFAULT_WEBHOOK_BODY = `{
- "title": "账号状态通知:{event}",
- "desp": "您的账号状态发生了改变。\\n\\n**昵称**:{nickname}\\n**QQ号**:{uin}\\n**当前状态**:{event}\\n**时间**:{time}"
-}`;
-
-export const DEFAULT_EMAIL_BODY = `账号状态发生了改变。
-
-昵称:{nickname}
-QQ号:{uin}
-当前状态:{event}
-时间:{time}`;
-
-export const DEFAULT_EMAIL_SUBJECT = '账号{event}:{nickname} ({uin})';
-
export function applyType(
draft: NotificationChannel,
type: NotificationChannelType,
@@ -227,11 +218,6 @@ export function NotificationChannelDialog(props: NotificationChannelDialogProps)
open={open}
onClose={() => onOpenChange(false)}
title={isEdit ? '编辑渠道' : '新建渠道'}
- description={
- type === 'email'
- ? '账号上线 / 下线时向该邮箱发送一封渲染后的通知。'
- : '账号上线 / 下线时向该 Webhook POST 一条渲染后的通知。'
- }
closeLabel="关闭渠道编辑弹窗"
maxWidth={576}
maxHeight="min(86dvh, 780px)"
@@ -365,7 +351,7 @@ export function NotificationChannelDialog(props: NotificationChannelDialogProps)
))}
- 可选。用于飞书等需要鉴权头的 Webhook;默认仍带 JSON Content-Type。
+ 可选,默认 Content-Type 为 application/json。
>
@@ -442,7 +428,7 @@ export function NotificationChannelDialog(props: NotificationChannelDialogProps)
- 465 通常开启;587 先明文再 STARTTLS,请关掉此项。
+ 465 开启,587 关闭(STARTTLS)。
{'{uin}'}{' '}
{'{nickname}'}{' '}
{'{event}'}(offline/online){' '}
- {'{time}'}
- {type === 'email' ? '。正文以 < 开头时按 HTML 发送。' : ''}
+ {'{time}'}{' '}
+ {'{status}'}(Hook 状态){' '}
+ {'{pid}'}(进程 ID){' '}
+ {'{error}'}(进程错误)
+ 。进程信息为空表示未知。
+ {type === 'email' ? '正文以 < 开头时按 HTML 发送。' : ''}
@@ -501,7 +491,7 @@ export function NotificationChannelDialog(props: NotificationChannelDialogProps)
- 关闭后保留配置但不推送;账号侧对应开关会被锁定并关闭。
+ 关闭后停止推送,保留配置。
(null);
const [loading, setLoading] = useState(true);
- const [dialog, setDialog] = useState({
- open: false,
- index: null,
- seed: blankChannel([]),
- });
+ const [dialog, setDialog] = useState(null);
const [testing, setTesting] = useState(null);
const { msg, flash, setMsg } = useFlashMessage();
const saveTimer = useRef(null);
@@ -166,18 +162,18 @@ export function NotificationsPanel() {
const otherIds = (index: number | null) =>
channels.filter((_, i) => i !== index).map((c) => c.id);
- const openCreate = () => setDialog({ open: true, index: null, seed: blankChannel(channels) });
- const openEdit = (i: number) => setDialog({ open: true, index: i, seed: channels[i] });
+ const openCreate = () => setDialog({ index: null, seed: blankChannel(channels) });
+ const openEdit = (i: number) => setDialog({ index: i, seed: channels[i] });
- const submitChannel = (ch: NotificationChannel) => {
- if (dialog.index == null) {
+ const submitChannel = (ch: NotificationChannel, index: number | null) => {
+ if (index === null) {
setChannels([...channels, ch], {
title: '正在新增通知渠道',
successTitle: '通知渠道已新增',
});
} else {
setChannels(
- channels.map((c, idx) => (idx === dialog.index ? ch : c)),
+ channels.map((c, idx) => (idx === index ? ch : c)),
{ title: '正在更新通知渠道', successTitle: '通知渠道已更新' },
);
}
@@ -234,10 +230,7 @@ export function NotificationsPanel() {
-
- 账号上线 / 下线时向启用的渠道发送通知(Webhook POST
- 或邮件,仅去抖防刷屏)。渠道在此全局定义,每个账号在其「配置」页勾选启用哪些。
-
+
在此管理通知渠道,再到账号「配置」页选择启用。
@@ -258,8 +251,7 @@ export function NotificationsPanel() {
}}
/>
- 下线后在该秒数内自愈则不发;超时才发「下线」,恢复时再发「上线」。
- 0 = 立即发、不去抖。
+ 下线持续超过此时长才通知,恢复时再通知。0 表示立即通知。
@@ -329,14 +321,14 @@ export function NotificationsPanel() {
)}
- {dialog.open && (
+ {dialog && (
!open && setDialog((d) => ({ ...d, open: false }))}
+ open
+ onOpenChange={(open) => !open && setDialog(null)}
isEdit={dialog.index != null}
initial={dialog.seed}
otherIds={otherIds(dialog.index)}
- onSubmit={submitChannel}
+ onSubmit={(channel) => submitChannel(channel, dialog.index)}
/>
)}
diff --git a/packages/webui/tests/notification-channel-dialog.test.tsx b/packages/webui/tests/notification-channel-dialog.test.tsx
index cc0ffb86..039eb893 100644
--- a/packages/webui/tests/notification-channel-dialog.test.tsx
+++ b/packages/webui/tests/notification-channel-dialog.test.tsx
@@ -1,9 +1,10 @@
import { renderToStaticMarkup } from 'react-dom/server';
import { describe, expect, it, vi } from 'vitest';
+import { DEFAULT_EMAIL_BODY, DEFAULT_WEBHOOK_BODY } from '@snowluma/common/notification-templates';
import {
- DEFAULT_EMAIL_BODY,
- DEFAULT_WEBHOOK_BODY,
NotificationChannelDialog,
+ applyType,
+ toChannel,
} from '../src/components/settings/notification-channel-dialog';
vi.mock('@/contexts/ThemeContext', () => ({
@@ -53,7 +54,9 @@ describe('NotificationChannelDialog', () => {
expect(markup).toContain('Webhook URL');
expect(markup).toContain('请求头');
expect(markup).not.toContain('SMTP 主机');
- expect(markup).toContain('向该 Webhook POST');
+ expect(markup).toContain('{status}');
+ expect(markup).toContain('{pid}');
+ expect(markup).toContain('{error}');
});
it('shows SMTP fields for an email channel', () => {
@@ -86,6 +89,34 @@ describe('NotificationChannelDialog', () => {
expect(markup).toContain('主题模板');
expect(markup).toContain('隐式 TLS');
expect(markup).not.toContain('Webhook URL');
- expect(markup).toContain('向该邮箱发送');
+ expect(markup).toContain('{status}');
+ expect(markup).toContain('{pid}');
+ expect(markup).toContain('{error}');
+ });
+
+ it('includes process status when saving a new webhook or switching it to email', () => {
+ const webhook = {
+ id: 'new-channel',
+ name: 'New',
+ type: 'webhook' as const,
+ url: 'https://example.com/webhook',
+ enabled: true,
+ bodyTemplate: DEFAULT_WEBHOOK_BODY,
+ };
+ expect(toChannel(webhook, []).bodyTemplate).toContain('{status}');
+ expect(toChannel(applyType(webhook, 'email'), []).bodyTemplate).toContain('{status}');
+ });
+
+ it('preserves an existing custom template', () => {
+ const existing = {
+ id: 'existing',
+ name: 'Existing',
+ type: 'webhook' as const,
+ url: 'https://example.com/webhook',
+ enabled: true,
+ bodyTemplate: '{event}:{uin}',
+ };
+ expect(toChannel(existing, []).bodyTemplate).toBe('{event}:{uin}');
+ expect(toChannel(applyType(existing, 'email'), []).bodyTemplate).toBe('{event}:{uin}');
});
});
diff --git a/packages/webui/tests/notification-channel.test.ts b/packages/webui/tests/notification-channel.test.ts
index 206f9a6a..3fd0fbc7 100644
--- a/packages/webui/tests/notification-channel.test.ts
+++ b/packages/webui/tests/notification-channel.test.ts
@@ -1,11 +1,10 @@
import { describe, expect, it } from 'vitest';
import {
- applyType,
DEFAULT_EMAIL_BODY,
DEFAULT_EMAIL_SUBJECT,
DEFAULT_WEBHOOK_BODY,
- toChannel,
-} from '../src/components/settings/notification-channel-dialog';
+} from '@snowluma/common/notification-templates';
+import { applyType, toChannel } from '../src/components/settings/notification-channel-dialog';
import { notificationChannelType, type NotificationChannel } from '../src/types';
function webhook(over: Partial = {}): NotificationChannel {