@openclaw/feishu 2026.2.25 → 2026.3.2

package/src/monitor.startup.test.ts

@@ -0,0 +1,203 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { monitorFeishuProvider, stopFeishuMonitor } from "./monitor.js";
+
+const probeFeishuMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./probe.js", () => ({
+  probeFeishu: probeFeishuMock,
+}));
+
+vi.mock("./client.js", () => ({
+  createFeishuWSClient: vi.fn(() => ({ start: vi.fn() })),
+  createEventDispatcher: vi.fn(() => ({ register: vi.fn() })),
+}));
+
+vi.mock("./runtime.js", () => ({
+  getFeishuRuntime: () => ({
+    channel: {
+      debounce: {
+        resolveInboundDebounceMs: () => 0,
+        createInboundDebouncer: () => ({
+          enqueue: async () => {},
+          flushKey: async () => {},
+        }),
+      },
+      text: {
+        hasControlCommand: () => false,
+      },
+    },
+  }),
+}));
+
+function buildMultiAccountWebsocketConfig(accountIds: string[]): ClawdbotConfig {
+  return {
+    channels: {
+      feishu: {
+        enabled: true,
+        accounts: Object.fromEntries(
+          accountIds.map((accountId) => [
+            accountId,
+            {
+              enabled: true,
+              appId: `cli_${accountId}`,
+              appSecret: `secret_${accountId}`,
+              connectionMode: "websocket",
+            },
+          ]),
+        ),
+      },
+    },
+  } as ClawdbotConfig;
+}
+
+afterEach(() => {
+  stopFeishuMonitor();
+});
+
+describe("Feishu monitor startup preflight", () => {
+  it("starts account probes sequentially to avoid startup bursts", async () => {
+    let inFlight = 0;
+    let maxInFlight = 0;
+    const started: string[] = [];
+    let releaseProbes!: () => void;
+    const probesReleased = new Promise<void>((resolve) => {
+      releaseProbes = () => resolve();
+    });
+    probeFeishuMock.mockImplementation(async (account: { accountId: string }) => {
+      started.push(account.accountId);
+      inFlight += 1;
+      maxInFlight = Math.max(maxInFlight, inFlight);
+      await probesReleased;
+      inFlight -= 1;
+      return { ok: true, botOpenId: `bot_${account.accountId}` };
+    });
+
+    const abortController = new AbortController();
+    const monitorPromise = monitorFeishuProvider({
+      config: buildMultiAccountWebsocketConfig(["alpha", "beta", "gamma"]),
+      abortSignal: abortController.signal,
+    });
+
+    try {
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(started).toEqual(["alpha"]);
+      expect(maxInFlight).toBe(1);
+    } finally {
+      releaseProbes();
+      abortController.abort();
+      await monitorPromise;
+    }
+  });
+
+  it("does not refetch bot info after a failed sequential preflight", async () => {
+    const started: string[] = [];
+    let releaseBetaProbe!: () => void;
+    const betaProbeReleased = new Promise<void>((resolve) => {
+      releaseBetaProbe = () => resolve();
+    });
+
+    probeFeishuMock.mockImplementation(async (account: { accountId: string }) => {
+      started.push(account.accountId);
+      if (account.accountId === "alpha") {
+        return { ok: false };
+      }
+      await betaProbeReleased;
+      return { ok: true, botOpenId: `bot_${account.accountId}` };
+    });
+
+    const abortController = new AbortController();
+    const monitorPromise = monitorFeishuProvider({
+      config: buildMultiAccountWebsocketConfig(["alpha", "beta"]),
+      abortSignal: abortController.signal,
+    });
+
+    try {
+      for (let i = 0; i < 10 && !started.includes("beta"); i += 1) {
+        await Promise.resolve();
+      }
+
+      expect(started).toEqual(["alpha", "beta"]);
+      expect(started.filter((accountId) => accountId === "alpha")).toHaveLength(1);
+    } finally {
+      releaseBetaProbe();
+      abortController.abort();
+      await monitorPromise;
+    }
+  });
+
+  it("continues startup when probe layer reports timeout", async () => {
+    const started: string[] = [];
+    let releaseBetaProbe!: () => void;
+    const betaProbeReleased = new Promise<void>((resolve) => {
+      releaseBetaProbe = () => resolve();
+    });
+
+    probeFeishuMock.mockImplementation((account: { accountId: string }) => {
+      started.push(account.accountId);
+      if (account.accountId === "alpha") {
+        return Promise.resolve({ ok: false, error: "probe timed out after 10000ms" });
+      }
+      return betaProbeReleased.then(() => ({ ok: true, botOpenId: `bot_${account.accountId}` }));
+    });
+
+    const abortController = new AbortController();
+    const runtime = { log: vi.fn(), error: vi.fn(), exit: vi.fn() };
+    const monitorPromise = monitorFeishuProvider({
+      config: buildMultiAccountWebsocketConfig(["alpha", "beta"]),
+      runtime,
+      abortSignal: abortController.signal,
+    });
+
+    try {
+      for (let i = 0; i < 10 && !started.includes("beta"); i += 1) {
+        await Promise.resolve();
+      }
+
+      expect(started).toEqual(["alpha", "beta"]);
+      expect(runtime.error).toHaveBeenCalledWith(
+        expect.stringContaining("bot info probe timed out"),
+      );
+    } finally {
+      releaseBetaProbe();
+      abortController.abort();
+      await monitorPromise;
+    }
+  });
+
+  it("stops sequential preflight when aborted during probe", async () => {
+    const started: string[] = [];
+    probeFeishuMock.mockImplementation(
+      (account: { accountId: string }, options: { abortSignal?: AbortSignal }) => {
+        started.push(account.accountId);
+        return new Promise((resolve) => {
+          options.abortSignal?.addEventListener(
+            "abort",
+            () => resolve({ ok: false, error: "probe aborted" }),
+            { once: true },
+          );
+        });
+      },
+    );
+
+    const abortController = new AbortController();
+    const monitorPromise = monitorFeishuProvider({
+      config: buildMultiAccountWebsocketConfig(["alpha", "beta"]),
+      abortSignal: abortController.signal,
+    });
+
+    try {
+      await Promise.resolve();
+      expect(started).toEqual(["alpha"]);
+
+      abortController.abort();
+      await monitorPromise;
+
+      expect(started).toEqual(["alpha"]);
+    } finally {
+      abortController.abort();
+    }
+  });
+});

package/src/monitor.startup.ts

@@ -0,0 +1,51 @@
+import type { RuntimeEnv } from "openclaw/plugin-sdk";
+import { probeFeishu } from "./probe.js";
+import type { ResolvedFeishuAccount } from "./types.js";
+
+export const FEISHU_STARTUP_BOT_INFO_TIMEOUT_MS = 10_000;
+
+type FetchBotOpenIdOptions = {
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  timeoutMs?: number;
+};
+
+function isTimeoutErrorMessage(message: string | undefined): boolean {
+  return message?.toLowerCase().includes("timeout") || message?.toLowerCase().includes("timed out")
+    ? true
+    : false;
+}
+
+function isAbortErrorMessage(message: string | undefined): boolean {
+  return message?.toLowerCase().includes("aborted") ?? false;
+}
+
+export async function fetchBotOpenIdForMonitor(
+  account: ResolvedFeishuAccount,
+  options: FetchBotOpenIdOptions = {},
+): Promise<string | undefined> {
+  if (options.abortSignal?.aborted) {
+    return undefined;
+  }
+
+  const timeoutMs = options.timeoutMs ?? FEISHU_STARTUP_BOT_INFO_TIMEOUT_MS;
+  const result = await probeFeishu(account, {
+    timeoutMs,
+    abortSignal: options.abortSignal,
+  });
+  if (result.ok) {
+    return result.botOpenId;
+  }
+
+  if (options.abortSignal?.aborted || isAbortErrorMessage(result.error)) {
+    return undefined;
+  }
+
+  if (isTimeoutErrorMessage(result.error)) {
+    const error = options.runtime?.error ?? console.error;
+    error(
+      `feishu[${account.accountId}]: bot info probe timed out after ${timeoutMs}ms; continuing startup`,
+    );
+  }
+  return undefined;
+}

package/src/monitor.state.defaults.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveFeishuWebhookAnomalyDefaultsForTest,
+  resolveFeishuWebhookRateLimitDefaultsForTest,
+} from "./monitor.state.js";
+
+describe("feishu monitor state defaults", () => {
+  it("falls back to hard defaults when sdk defaults are missing", () => {
+    expect(resolveFeishuWebhookRateLimitDefaultsForTest(undefined)).toEqual({
+      windowMs: 60_000,
+      maxRequests: 120,
+      maxTrackedKeys: 4_096,
+    });
+    expect(resolveFeishuWebhookAnomalyDefaultsForTest(undefined)).toEqual({
+      maxTrackedKeys: 4_096,
+      ttlMs: 21_600_000,
+      logEvery: 25,
+    });
+  });
+
+  it("keeps valid sdk values and repairs invalid fields", () => {
+    expect(
+      resolveFeishuWebhookRateLimitDefaultsForTest({
+        windowMs: 45_000,
+        maxRequests: 0,
+        maxTrackedKeys: -1,
+      }),
+    ).toEqual({
+      windowMs: 45_000,
+      maxRequests: 120,
+      maxTrackedKeys: 4_096,
+    });
+
+    expect(
+      resolveFeishuWebhookAnomalyDefaultsForTest({
+        maxTrackedKeys: 2048,
+        ttlMs: Number.NaN,
+        logEvery: 10,
+      }),
+    ).toEqual({
+      maxTrackedKeys: 2048,
+      ttlMs: 21_600_000,
+      logEvery: 10,
+    });
+  });
+});

package/src/monitor.state.ts

@@ -0,0 +1,152 @@
+import * as http from "http";
+import * as Lark from "@larksuiteoapi/node-sdk";
+import {
+  createFixedWindowRateLimiter,
+  createWebhookAnomalyTracker,
+  type RuntimeEnv,
+  WEBHOOK_ANOMALY_COUNTER_DEFAULTS as WEBHOOK_ANOMALY_COUNTER_DEFAULTS_FROM_SDK,
+  WEBHOOK_RATE_LIMIT_DEFAULTS as WEBHOOK_RATE_LIMIT_DEFAULTS_FROM_SDK,
+} from "openclaw/plugin-sdk";
+
+export const wsClients = new Map<string, Lark.WSClient>();
+export const httpServers = new Map<string, http.Server>();
+export const botOpenIds = new Map<string, string>();
+
+export const FEISHU_WEBHOOK_MAX_BODY_BYTES = 1024 * 1024;
+export const FEISHU_WEBHOOK_BODY_TIMEOUT_MS = 30_000;
+
+type WebhookRateLimitDefaults = {
+  windowMs: number;
+  maxRequests: number;
+  maxTrackedKeys: number;
+};
+
+type WebhookAnomalyDefaults = {
+  maxTrackedKeys: number;
+  ttlMs: number;
+  logEvery: number;
+};
+
+const FEISHU_WEBHOOK_RATE_LIMIT_FALLBACK_DEFAULTS: WebhookRateLimitDefaults = {
+  windowMs: 60_000,
+  maxRequests: 120,
+  maxTrackedKeys: 4_096,
+};
+
+const FEISHU_WEBHOOK_ANOMALY_FALLBACK_DEFAULTS: WebhookAnomalyDefaults = {
+  maxTrackedKeys: 4_096,
+  ttlMs: 6 * 60 * 60_000,
+  logEvery: 25,
+};
+
+function coercePositiveInt(value: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+  const normalized = Math.floor(value);
+  return normalized > 0 ? normalized : fallback;
+}
+
+export function resolveFeishuWebhookRateLimitDefaultsForTest(
+  defaults: unknown,
+): WebhookRateLimitDefaults {
+  const resolved = defaults as Partial<WebhookRateLimitDefaults> | null | undefined;
+  return {
+    windowMs: coercePositiveInt(
+      resolved?.windowMs,
+      FEISHU_WEBHOOK_RATE_LIMIT_FALLBACK_DEFAULTS.windowMs,
+    ),
+    maxRequests: coercePositiveInt(
+      resolved?.maxRequests,
+      FEISHU_WEBHOOK_RATE_LIMIT_FALLBACK_DEFAULTS.maxRequests,
+    ),
+    maxTrackedKeys: coercePositiveInt(
+      resolved?.maxTrackedKeys,
+      FEISHU_WEBHOOK_RATE_LIMIT_FALLBACK_DEFAULTS.maxTrackedKeys,
+    ),
+  };
+}
+
+export function resolveFeishuWebhookAnomalyDefaultsForTest(
+  defaults: unknown,
+): WebhookAnomalyDefaults {
+  const resolved = defaults as Partial<WebhookAnomalyDefaults> | null | undefined;
+  return {
+    maxTrackedKeys: coercePositiveInt(
+      resolved?.maxTrackedKeys,
+      FEISHU_WEBHOOK_ANOMALY_FALLBACK_DEFAULTS.maxTrackedKeys,
+    ),
+    ttlMs: coercePositiveInt(resolved?.ttlMs, FEISHU_WEBHOOK_ANOMALY_FALLBACK_DEFAULTS.ttlMs),
+    logEvery: coercePositiveInt(
+      resolved?.logEvery,
+      FEISHU_WEBHOOK_ANOMALY_FALLBACK_DEFAULTS.logEvery,
+    ),
+  };
+}
+
+const feishuWebhookRateLimitDefaults = resolveFeishuWebhookRateLimitDefaultsForTest(
+  WEBHOOK_RATE_LIMIT_DEFAULTS_FROM_SDK,
+);
+const feishuWebhookAnomalyDefaults = resolveFeishuWebhookAnomalyDefaultsForTest(
+  WEBHOOK_ANOMALY_COUNTER_DEFAULTS_FROM_SDK,
+);
+
+export const feishuWebhookRateLimiter = createFixedWindowRateLimiter({
+  windowMs: feishuWebhookRateLimitDefaults.windowMs,
+  maxRequests: feishuWebhookRateLimitDefaults.maxRequests,
+  maxTrackedKeys: feishuWebhookRateLimitDefaults.maxTrackedKeys,
+});
+
+const feishuWebhookAnomalyTracker = createWebhookAnomalyTracker({
+  maxTrackedKeys: feishuWebhookAnomalyDefaults.maxTrackedKeys,
+  ttlMs: feishuWebhookAnomalyDefaults.ttlMs,
+  logEvery: feishuWebhookAnomalyDefaults.logEvery,
+});
+
+export function clearFeishuWebhookRateLimitStateForTest(): void {
+  feishuWebhookRateLimiter.clear();
+  feishuWebhookAnomalyTracker.clear();
+}
+
+export function getFeishuWebhookRateLimitStateSizeForTest(): number {
+  return feishuWebhookRateLimiter.size();
+}
+
+export function isWebhookRateLimitedForTest(key: string, nowMs: number): boolean {
+  return feishuWebhookRateLimiter.isRateLimited(key, nowMs);
+}
+
+export function recordWebhookStatus(
+  runtime: RuntimeEnv | undefined,
+  accountId: string,
+  path: string,
+  statusCode: number,
+): void {
+  feishuWebhookAnomalyTracker.record({
+    key: `${accountId}:${path}:${statusCode}`,
+    statusCode,
+    log: runtime?.log ?? console.log,
+    message: (count) =>
+      `feishu[${accountId}]: webhook anomaly path=${path} status=${statusCode} count=${count}`,
+  });
+}
+
+export function stopFeishuMonitorState(accountId?: string): void {
+  if (accountId) {
+    wsClients.delete(accountId);
+    const server = httpServers.get(accountId);
+    if (server) {
+      server.close();
+      httpServers.delete(accountId);
+    }
+    botOpenIds.delete(accountId);
+    return;
+  }
+
+  wsClients.clear();
+  for (const server of httpServers.values()) {
+    server.close();
+  }
+  httpServers.clear();
+  botOpenIds.clear();
+}

package/src/monitor.test-mocks.ts

@@ -0,0 +1,12 @@
+import { vi } from "vitest";
+
+export const probeFeishuMock: ReturnType<typeof vi.fn> = vi.fn();
+
+vi.mock("./probe.js", () => ({
+  probeFeishu: probeFeishuMock,
+}));
+
+vi.mock("./client.js", () => ({
+  createFeishuWSClient: vi.fn(() => ({ start: vi.fn() })),
+  createEventDispatcher: vi.fn(() => ({ register: vi.fn() })),
+}));

package/src/monitor.transport.ts

@@ -0,0 +1,163 @@
+import * as http from "http";
+import * as Lark from "@larksuiteoapi/node-sdk";
+import {
+  applyBasicWebhookRequestGuards,
+  type RuntimeEnv,
+  installRequestBodyLimitGuard,
+} from "openclaw/plugin-sdk";
+import { createFeishuWSClient } from "./client.js";
+import {
+  botOpenIds,
+  FEISHU_WEBHOOK_BODY_TIMEOUT_MS,
+  FEISHU_WEBHOOK_MAX_BODY_BYTES,
+  feishuWebhookRateLimiter,
+  httpServers,
+  recordWebhookStatus,
+  wsClients,
+} from "./monitor.state.js";
+import type { ResolvedFeishuAccount } from "./types.js";
+
+export type MonitorTransportParams = {
+  account: ResolvedFeishuAccount;
+  accountId: string;
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  eventDispatcher: Lark.EventDispatcher;
+};
+
+export async function monitorWebSocket({
+  account,
+  accountId,
+  runtime,
+  abortSignal,
+  eventDispatcher,
+}: MonitorTransportParams): Promise<void> {
+  const log = runtime?.log ?? console.log;
+  log(`feishu[${accountId}]: starting WebSocket connection...`);
+
+  const wsClient = createFeishuWSClient(account);
+  wsClients.set(accountId, wsClient);
+
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      wsClients.delete(accountId);
+      botOpenIds.delete(accountId);
+    };
+
+    const handleAbort = () => {
+      log(`feishu[${accountId}]: abort signal received, stopping`);
+      cleanup();
+      resolve();
+    };
+
+    if (abortSignal?.aborted) {
+      cleanup();
+      resolve();
+      return;
+    }
+
+    abortSignal?.addEventListener("abort", handleAbort, { once: true });
+
+    try {
+      wsClient.start({ eventDispatcher });
+      log(`feishu[${accountId}]: WebSocket client started`);
+    } catch (err) {
+      cleanup();
+      abortSignal?.removeEventListener("abort", handleAbort);
+      reject(err);
+    }
+  });
+}
+
+export async function monitorWebhook({
+  account,
+  accountId,
+  runtime,
+  abortSignal,
+  eventDispatcher,
+}: MonitorTransportParams): Promise<void> {
+  const log = runtime?.log ?? console.log;
+  const error = runtime?.error ?? console.error;
+
+  const port = account.config.webhookPort ?? 3000;
+  const path = account.config.webhookPath ?? "/feishu/events";
+  const host = account.config.webhookHost ?? "127.0.0.1";
+
+  log(`feishu[${accountId}]: starting Webhook server on ${host}:${port}, path ${path}...`);
+
+  const server = http.createServer();
+  const webhookHandler = Lark.adaptDefault(path, eventDispatcher, { autoChallenge: true });
+
+  server.on("request", (req, res) => {
+    res.on("finish", () => {
+      recordWebhookStatus(runtime, accountId, path, res.statusCode);
+    });
+
+    const rateLimitKey = `${accountId}:${path}:${req.socket.remoteAddress ?? "unknown"}`;
+    if (
+      !applyBasicWebhookRequestGuards({
+        req,
+        res,
+        rateLimiter: feishuWebhookRateLimiter,
+        rateLimitKey,
+        nowMs: Date.now(),
+        requireJsonContentType: true,
+      })
+    ) {
+      return;
+    }
+
+    const guard = installRequestBodyLimitGuard(req, res, {
+      maxBytes: FEISHU_WEBHOOK_MAX_BODY_BYTES,
+      timeoutMs: FEISHU_WEBHOOK_BODY_TIMEOUT_MS,
+      responseFormat: "text",
+    });
+    if (guard.isTripped()) {
+      return;
+    }
+
+    void Promise.resolve(webhookHandler(req, res))
+      .catch((err) => {
+        if (!guard.isTripped()) {
+          error(`feishu[${accountId}]: webhook handler error: ${String(err)}`);
+        }
+      })
+      .finally(() => {
+        guard.dispose();
+      });
+  });
+
+  httpServers.set(accountId, server);
+
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      server.close();
+      httpServers.delete(accountId);
+      botOpenIds.delete(accountId);
+    };
+
+    const handleAbort = () => {
+      log(`feishu[${accountId}]: abort signal received, stopping Webhook server`);
+      cleanup();
+      resolve();
+    };
+
+    if (abortSignal?.aborted) {
+      cleanup();
+      resolve();
+      return;
+    }
+
+    abortSignal?.addEventListener("abort", handleAbort, { once: true });
+
+    server.listen(port, host, () => {
+      log(`feishu[${accountId}]: Webhook server listening on ${host}:${port}`);
+    });
+
+    server.on("error", (err) => {
+      error(`feishu[${accountId}]: Webhook server error: ${err}`);
+      abortSignal?.removeEventListener("abort", handleAbort);
+      reject(err);
+    });
+  });
+}