@openclaw/zalo 2026.3.13 → 2026.5.2-beta.1

package/src/monitor.types.ts

@@ -0,0 +1,4 @@
+export type ZaloRuntimeEnv = {
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+};

package/src/monitor.webhook.test.ts

@@ -1,34 +1,30 @@
-import { createServer, type RequestListener } from "node:http";
-import type { AddressInfo } from "node:net";
-import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/zalo";
+import type { RequestListener } from "node:http";
+import {
+  createEmptyPluginRegistry,
+  setActivePluginRegistry,
+} from "openclaw/plugin-sdk/plugin-test-runtime";
+import { withServer } from "openclaw/plugin-sdk/test-env";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { createEmptyPluginRegistry } from "../../../src/plugins/registry.js";
-import { setActivePluginRegistry } from "../../../src/plugins/runtime.js";
+import type { OpenClawConfig, PluginRuntime } from "../runtime-api.js";
+import { handleZaloWebhookRequest } from "./monitor.js";
+import type { ZaloRuntimeEnv } from "./monitor.types.js";
 import {
   clearZaloWebhookSecurityStateForTest,
   getZaloWebhookRateLimitStateSizeForTest,
   getZaloWebhookStatusCounterSizeForTest,
-  handleZaloWebhookRequest,
+  handleZaloWebhookRequest as handleZaloWebhookRequestInternal,
   registerZaloWebhookTarget,
-} from "./monitor.js";
+  type ZaloWebhookProcessUpdate,
+  ZaloRetryableWebhookError,
+} from "./monitor.webhook.js";
+import {
+  createImageLifecycleCore,
+  createImageUpdate,
+  createTextUpdate,
+  expectImageLifecycleDelivery,
+  postWebhookReplay,
+} from "./test-support/lifecycle-test-support.js";
 import type { ResolvedZaloAccount } from "./types.js";
-
-async function withServer(handler: RequestListener, fn: (baseUrl: string) => Promise<void>) {
-  const server = createServer(handler);
-  await new Promise<void>((resolve) => {
-    server.listen(0, "127.0.0.1", () => resolve());
-  });
-  const address = server.address() as AddressInfo | null;
-  if (!address) {
-    throw new Error("missing server address");
-  }
-  try {
-    await fn(`http://127.0.0.1:${address.port}`);
-  } finally {
-    await new Promise<void>((resolve) => server.close(() => resolve()));
-  }
-}
-
 const DEFAULT_ACCOUNT: ResolvedZaloAccount = {
   accountId: "default",
   enabled: true,
@@ -37,13 +33,19 @@ const DEFAULT_ACCOUNT: ResolvedZaloAccount = {
   config: {},
 };
 
-const webhookRequestHandler: RequestListener = async (req, res) => {
-  const handled = await handleZaloWebhookRequest(req, res);
-  if (!handled) {
-    res.statusCode = 404;
-    res.end("not found");
-  }
-};
+function createWebhookRequestHandler(processUpdate?: ZaloWebhookProcessUpdate): RequestListener {
+  return async (req, res) => {
+    const handled = processUpdate
+      ? await handleZaloWebhookRequestInternal(req, res, processUpdate)
+      : await handleZaloWebhookRequest(req, res);
+    if (!handled) {
+      res.statusCode = 404;
+      res.end("not found");
+    }
+  };
+}
+
+const webhookRequestHandler = createWebhookRequestHandler();
 
 function registerTarget(params: {
   path: string;
@@ -52,16 +54,20 @@ function registerTarget(params: {
   account?: ResolvedZaloAccount;
   config?: OpenClawConfig;
   core?: PluginRuntime;
+  runtime?: Partial<ZaloRuntimeEnv>;
 }): () => void {
   return registerZaloWebhookTarget({
     token: "tok",
     account: params.account ?? DEFAULT_ACCOUNT,
     config: params.config ?? ({} as OpenClawConfig),
-    runtime: {},
+    runtime: (params.runtime ?? {}) as ZaloRuntimeEnv,
     core: params.core ?? ({} as PluginRuntime),
     secret: params.secret ?? "secret",
     path: params.path,
+    webhookUrl: `https://example.com${params.path}`,
+    webhookPath: params.path,
     mediaMaxMb: 5,
+    canHostMedia: true,
     statusSink: params.statusSink,
   });
 }
@@ -121,31 +127,48 @@ async function postUntilRateLimited(params: {
   return false;
 }
 
-describe("handleZaloWebhookRequest", () => {
-  afterEach(() => {
-    clearZaloWebhookSecurityStateForTest();
-    setActivePluginRegistry(createEmptyPluginRegistry());
+async function postWebhookJson(params: {
+  baseUrl: string;
+  path: string;
+  secret: string;
+  payload: unknown;
+}) {
+  return fetch(`${params.baseUrl}${params.path}`, {
+    method: "POST",
+    headers: {
+      "x-bot-api-secret-token": params.secret,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(params.payload),
   });
+}
 
-  it("registers and unregisters plugin HTTP route at path boundaries", () => {
-    const registry = createEmptyPluginRegistry();
-    setActivePluginRegistry(registry);
-    const unregisterA = registerTarget({ path: "/hook" });
-    const unregisterB = registerTarget({ path: "/hook" });
+async function expectTwoWebhookPostsOk(params: {
+  baseUrl: string;
+  first: { path: string; secret: string; payload: unknown };
+  second: { path: string; secret: string; payload: unknown };
+}) {
+  const first = await postWebhookJson({
+    baseUrl: params.baseUrl,
+    path: params.first.path,
+    secret: params.first.secret,
+    payload: params.first.payload,
+  });
+  const second = await postWebhookJson({
+    baseUrl: params.baseUrl,
+    path: params.second.path,
+    secret: params.second.secret,
+    payload: params.second.payload,
+  });
 
-    expect(registry.httpRoutes).toHaveLength(1);
-    expect(registry.httpRoutes[0]).toEqual(
-      expect.objectContaining({
-        pluginId: "zalo",
-        path: "/hook",
-        source: "zalo-webhook",
-      }),
-    );
+  expect(first.status).toBe(200);
+  expect(second.status).toBe(200);
+}
 
-    unregisterA();
-    expect(registry.httpRoutes).toHaveLength(1);
-    unregisterB();
-    expect(registry.httpRoutes).toHaveLength(0);
+describe("handleZaloWebhookRequest", () => {
+  afterEach(() => {
+    clearZaloWebhookSecurityStateForTest();
+    setActivePluginRegistry(createEmptyPluginRegistry());
   });
 
   it("returns 400 for non-object payloads", async () => {
@@ -218,16 +241,198 @@ describe("handleZaloWebhookRequest", () => {
     }
   });
 
-  it("deduplicates webhook replay by event_name + message_id", async () => {
+  it("deduplicates webhook replay for the same event origin", async () => {
     const sink = vi.fn();
     const unregister = registerTarget({ path: "/hook-replay", statusSink: sink });
+    const payload = createTextUpdate({
+      messageId: "msg-replay-1",
+      userId: "123",
+      userName: "",
+      chatId: "123",
+      text: "hello",
+    });
 
+    try {
+      await withServer(webhookRequestHandler, async (baseUrl) => {
+        const { first, replay } = await postWebhookReplay({
+          baseUrl,
+          path: "/hook-replay",
+          secret: "secret",
+          payload,
+        });
+
+        expect(first.status).toBe(200);
+        expect(replay.status).toBe(200);
+        expect(sink).toHaveBeenCalledTimes(1);
+      });
+    } finally {
+      unregister();
+    }
+  });
+
+  it("allows a retry after processUpdate throws a retryable replay error", async () => {
+    const error = vi.fn();
+    const unregister = registerTarget({
+      path: "/hook-retry-after-failure",
+      runtime: { error },
+    });
+    const payload = createTextUpdate({
+      messageId: "msg-retry-after-failure-1",
+      userId: "123",
+      userName: "",
+      chatId: "123",
+      text: "hello",
+    });
+    let attempts = 0;
+    const processUpdate = vi.fn<ZaloWebhookProcessUpdate>(async () => {
+      attempts += 1;
+      if (attempts === 1) {
+        throw new ZaloRetryableWebhookError("boom");
+      }
+    });
+
+    try {
+      await withServer(createWebhookRequestHandler(processUpdate), async (baseUrl) => {
+        const first = await postWebhookJson({
+          baseUrl,
+          path: "/hook-retry-after-failure",
+          secret: "secret",
+          payload,
+        });
+
+        expect(first.status).toBe(200);
+        await vi.waitFor(() => expect(error).toHaveBeenCalledTimes(1));
+
+        const second = await postWebhookJson({
+          baseUrl,
+          path: "/hook-retry-after-failure",
+          secret: "secret",
+          payload,
+        });
+
+        expect(second.status).toBe(200);
+        await vi.waitFor(() => expect(processUpdate).toHaveBeenCalledTimes(2));
+      });
+    } finally {
+      unregister();
+    }
+  });
+
+  it("keeps replay dedupe isolated per authenticated target", async () => {
+    const sinkA = vi.fn();
+    const sinkB = vi.fn();
+    const unregisterA = registerTarget({
+      path: "/hook-replay-scope",
+      secret: "secret-a",
+      statusSink: sinkA,
+    });
+    const unregisterB = registerTarget({
+      path: "/hook-replay-scope",
+      secret: "secret-b",
+      statusSink: sinkB,
+      account: {
+        ...DEFAULT_ACCOUNT,
+        accountId: "work",
+      },
+    });
+    const payload = createTextUpdate({
+      messageId: "msg-replay-scope-1",
+      userId: "123",
+      userName: "",
+      chatId: "123",
+      text: "hello",
+    });
+
+    try {
+      await withServer(webhookRequestHandler, async (baseUrl) => {
+        await expectTwoWebhookPostsOk({
+          baseUrl,
+          first: { path: "/hook-replay-scope", secret: "secret-a", payload },
+          second: { path: "/hook-replay-scope", secret: "secret-b", payload },
+        });
+      });
+
+      expect(sinkA).toHaveBeenCalledTimes(1);
+      expect(sinkB).toHaveBeenCalledTimes(1);
+    } finally {
+      unregisterA();
+      unregisterB();
+    }
+  });
+
+  it("does not collide replay dedupe across different chats", async () => {
+    const sink = vi.fn();
+    const unregister = registerTarget({ path: "/hook-replay-chat-scope", statusSink: sink });
+    const firstPayload = createTextUpdate({
+      messageId: "msg-replay-chat-1",
+      userId: "123",
+      userName: "",
+      chatId: "chat-a",
+      text: "hello from a",
+    });
+    const secondPayload = createTextUpdate({
+      messageId: "msg-replay-chat-1",
+      userId: "123",
+      userName: "",
+      chatId: "chat-b",
+      text: "hello from b",
+    });
+
+    try {
+      await withServer(webhookRequestHandler, async (baseUrl) => {
+        await expectTwoWebhookPostsOk({
+          baseUrl,
+          first: { path: "/hook-replay-chat-scope", secret: "secret", payload: firstPayload },
+          second: { path: "/hook-replay-chat-scope", secret: "secret", payload: secondPayload },
+        });
+      });
+
+      expect(sink).toHaveBeenCalledTimes(2);
+    } finally {
+      unregister();
+    }
+  });
+
+  it("does not collide replay dedupe across different senders in the same chat", async () => {
+    const sink = vi.fn();
+    const unregister = registerTarget({ path: "/hook-replay-sender-scope", statusSink: sink });
+    const firstPayload = createTextUpdate({
+      messageId: "msg-replay-sender-1",
+      userId: "user-a",
+      userName: "",
+      chatId: "chat-shared",
+      text: "hello from user a",
+    });
+    const secondPayload = createTextUpdate({
+      messageId: "msg-replay-sender-1",
+      userId: "user-b",
+      userName: "",
+      chatId: "chat-shared",
+      text: "hello from user b",
+    });
+
+    try {
+      await withServer(webhookRequestHandler, async (baseUrl) => {
+        await expectTwoWebhookPostsOk({
+          baseUrl,
+          first: { path: "/hook-replay-sender-scope", secret: "secret", payload: firstPayload },
+          second: { path: "/hook-replay-sender-scope", secret: "secret", payload: secondPayload },
+        });
+      });
+
+      expect(sink).toHaveBeenCalledTimes(2);
+    } finally {
+      unregister();
+    }
+  });
+
+  it("does not throw when replay metadata is partially missing", async () => {
+    const sink = vi.fn();
+    const unregister = registerTarget({ path: "/hook-replay-partial", statusSink: sink });
     const payload = {
       event_name: "message.text.received",
       message: {
-        from: { id: "123" },
-        chat: { id: "123", chat_type: "PRIVATE" },
-        message_id: "msg-replay-1",
+        message_id: "msg-replay-partial-1",
         date: Math.floor(Date.now() / 1000),
         text: "hello",
       },
@@ -235,7 +440,7 @@ describe("handleZaloWebhookRequest", () => {
 
     try {
       await withServer(webhookRequestHandler, async (baseUrl) => {
-        const first = await fetch(`${baseUrl}/hook-replay`, {
+        const response = await fetch(`${baseUrl}/hook-replay-partial`, {
           method: "POST",
           headers: {
             "x-bot-api-secret-token": "secret",
@@ -243,7 +448,126 @@ describe("handleZaloWebhookRequest", () => {
           },
           body: JSON.stringify(payload),
         });
-        const second = await fetch(`${baseUrl}/hook-replay`, {
+
+        expect(response.status).toBe(200);
+      });
+
+      expect(sink).toHaveBeenCalledTimes(1);
+    } finally {
+      unregister();
+    }
+  });
+
+  it("keeps replay dedupe isolated when path/account values collide under colon-joined keys", async () => {
+    const sinkA = vi.fn();
+    const sinkB = vi.fn();
+    // Old key format `${path}:${accountId}:${event_name}:${messageId}` would collide for these two targets.
+    const unregisterA = registerTarget({
+      path: "/hook-replay-collision:a",
+      secret: "secret-a",
+      statusSink: sinkA,
+      account: {
+        ...DEFAULT_ACCOUNT,
+        accountId: "team",
+      },
+    });
+    const unregisterB = registerTarget({
+      path: "/hook-replay-collision",
+      secret: "secret-b",
+      statusSink: sinkB,
+      account: {
+        ...DEFAULT_ACCOUNT,
+        accountId: "a:team",
+      },
+    });
+    const payload = createTextUpdate({
+      messageId: "msg-replay-collision-1",
+      userId: "123",
+      userName: "",
+      chatId: "123",
+      text: "hello",
+    });
+
+    try {
+      await withServer(webhookRequestHandler, async (baseUrl) => {
+        await expectTwoWebhookPostsOk({
+          baseUrl,
+          first: { path: "/hook-replay-collision:a", secret: "secret-a", payload },
+          second: { path: "/hook-replay-collision", secret: "secret-b", payload },
+        });
+      });
+
+      expect(sinkA).toHaveBeenCalledTimes(1);
+      expect(sinkB).toHaveBeenCalledTimes(1);
+    } finally {
+      unregisterA();
+      unregisterB();
+    }
+  });
+
+  it("keeps replay dedupe isolated across different webhook paths", async () => {
+    const sinkA = vi.fn();
+    const sinkB = vi.fn();
+    const sharedSecret = "secret";
+    const unregisterA = registerTarget({
+      path: "/hook-replay-scope-a",
+      secret: sharedSecret,
+      statusSink: sinkA,
+    });
+    const unregisterB = registerTarget({
+      path: "/hook-replay-scope-b",
+      secret: sharedSecret,
+      statusSink: sinkB,
+    });
+    const payload = createTextUpdate({
+      messageId: "msg-replay-cross-path-1",
+      userId: "123",
+      userName: "",
+      chatId: "123",
+      text: "hello",
+    });
+
+    try {
+      await withServer(webhookRequestHandler, async (baseUrl) => {
+        await expectTwoWebhookPostsOk({
+          baseUrl,
+          first: { path: "/hook-replay-scope-a", secret: sharedSecret, payload },
+          second: { path: "/hook-replay-scope-b", secret: sharedSecret, payload },
+        });
+      });
+
+      expect(sinkA).toHaveBeenCalledTimes(1);
+      expect(sinkB).toHaveBeenCalledTimes(1);
+    } finally {
+      unregisterA();
+      unregisterB();
+    }
+  });
+
+  it("downloads inbound image media from webhook photo_url and preserves display_name", async () => {
+    const {
+      core,
+      finalizeInboundContextMock,
+      recordInboundSessionMock,
+      fetchRemoteMediaMock,
+      saveMediaBufferMock,
+    } = createImageLifecycleCore();
+    const unregister = registerTarget({
+      path: "/hook-image",
+      core,
+      account: {
+        ...DEFAULT_ACCOUNT,
+        config: {
+          dmPolicy: "open",
+          allowFrom: ["*"],
+        },
+      },
+    });
+    const payload = createImageUpdate();
+
+    try {
+      await withServer(webhookRequestHandler, async (baseUrl) => {
+        const response = await fetch(`${baseUrl}/hook-image`, {
           method: "POST",
           headers: {
             "x-bot-api-secret-token": "secret",
@@ -252,13 +576,19 @@ describe("handleZaloWebhookRequest", () => {
           body: JSON.stringify(payload),
         });
 
-        expect(first.status).toBe(200);
-        expect(second.status).toBe(200);
-        expect(sink).toHaveBeenCalledTimes(1);
+        expect(response.status).toBe(200);
       });
     } finally {
       unregister();
     }
+
+    await vi.waitFor(() => expect(fetchRemoteMediaMock).toHaveBeenCalledTimes(1));
+    expectImageLifecycleDelivery({
+      fetchRemoteMediaMock,
+      saveMediaBufferMock,
+      finalizeInboundContextMock,
+      recordInboundSessionMock,
+    });
   });
 
   it("returns 429 when per-path request rate exceeds threshold", async () => {

package/src/monitor.webhook.ts

@@ -1,8 +1,10 @@
-import { timingSafeEqual } from "node:crypto";
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { OpenClawConfig } from "openclaw/plugin-sdk/zalo";
+import { createClaimableDedupe } from "openclaw/plugin-sdk/persistent-dedupe";
+import { safeEqualSecret } from "openclaw/plugin-sdk/security-runtime";
+import type { ResolvedZaloAccount } from "./accounts.js";
+import type { ZaloFetch, ZaloUpdate } from "./api.js";
+import type { ZaloRuntimeEnv } from "./monitor.types.js";
 import {
-  createDedupeCache,
   createFixedWindowRateLimiter,
   createWebhookAnomalyTracker,
   readJsonWebhookBodyOrReject,
@@ -15,11 +17,9 @@ import {
   withResolvedWebhookRequestPipeline,
   WEBHOOK_ANOMALY_COUNTER_DEFAULTS,
   WEBHOOK_RATE_LIMIT_DEFAULTS,
-} from "openclaw/plugin-sdk/zalo";
-import { resolveClientIp } from "../../../src/gateway/net.js";
-import type { ResolvedZaloAccount } from "./accounts.js";
-import type { ZaloFetch, ZaloUpdate } from "./api.js";
-import type { ZaloRuntimeEnv } from "./monitor.js";
+  resolveClientIp,
+  type OpenClawConfig,
+} from "./runtime-api.js";
 
 const ZALO_WEBHOOK_REPLAY_WINDOW_MS = 5 * 60_000;
 
@@ -31,7 +31,10 @@ export type ZaloWebhookTarget = {
   core: unknown;
   secret: string;
   path: string;
+  webhookUrl: string;
+  webhookPath: string;
   mediaMaxMb: number;
+  canHostMedia: boolean;
   statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
   fetcher?: ZaloFetch;
 };
@@ -47,9 +50,9 @@ const webhookRateLimiter = createFixedWindowRateLimiter({
   maxRequests: WEBHOOK_RATE_LIMIT_DEFAULTS.maxRequests,
   maxTrackedKeys: WEBHOOK_RATE_LIMIT_DEFAULTS.maxTrackedKeys,
 });
-const recentWebhookEvents = createDedupeCache({
+const recentWebhookEvents = createClaimableDedupe({
   ttlMs: ZALO_WEBHOOK_REPLAY_WINDOW_MS,
-  maxSize: 5000,
+  memoryMaxSize: 5000,
 });
 const webhookAnomalyTracker = createWebhookAnomalyTracker({
   maxTrackedKeys: WEBHOOK_ANOMALY_COUNTER_DEFAULTS.maxTrackedKeys,
@@ -59,6 +62,7 @@ const webhookAnomalyTracker = createWebhookAnomalyTracker({
 
 export function clearZaloWebhookSecurityStateForTest(): void {
   webhookRateLimiter.clear();
+  recentWebhookEvents.clearMemory();
   webhookAnomalyTracker.clear();
 }
 
@@ -71,29 +75,64 @@ export function getZaloWebhookStatusCounterSizeForTest(): number {
 }
 
 function timingSafeEquals(left: string, right: string): boolean {
-  const leftBuffer = Buffer.from(left);
-  const rightBuffer = Buffer.from(right);
-
-  if (leftBuffer.length !== rightBuffer.length) {
-    const length = Math.max(1, leftBuffer.length, rightBuffer.length);
-    const paddedLeft = Buffer.alloc(length);
-    const paddedRight = Buffer.alloc(length);
-    leftBuffer.copy(paddedLeft);
-    rightBuffer.copy(paddedRight);
-    timingSafeEqual(paddedLeft, paddedRight);
-    return false;
-  }
-
-  return timingSafeEqual(leftBuffer, rightBuffer);
+  return safeEqualSecret(left, right);
 }
 
-function isReplayEvent(update: ZaloUpdate, nowMs: number): boolean {
+function buildReplayEventCacheKey(target: ZaloWebhookTarget, update: ZaloUpdate): string | null {
   const messageId = update.message?.message_id;
   if (!messageId) {
-    return false;
+    return null;
+  }
+  const chatId = update.message?.chat?.id ?? "";
+  const senderId = update.message?.from?.id ?? "";
+  return JSON.stringify([
+    target.path,
+    target.account.accountId,
+    update.event_name,
+    chatId,
+    senderId,
+    messageId,
+  ]);
+}
+
+export class ZaloRetryableWebhookError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ZaloRetryableWebhookError";
+  }
+}
+
+export async function processZaloReplayGuardedUpdate(params: {
+  target: ZaloWebhookTarget;
+  update: ZaloUpdate;
+  processUpdate: ZaloWebhookProcessUpdate;
+  nowMs?: number;
+}): Promise<"processed" | "duplicate"> {
+  const replayEventKey = buildReplayEventCacheKey(params.target, params.update);
+  if (replayEventKey) {
+    const replayClaim = await recentWebhookEvents.claim(replayEventKey, { now: params.nowMs });
+    if (replayClaim.kind !== "claimed") {
+      return "duplicate";
+    }
+  }
+
+  params.target.statusSink?.({ lastInboundAt: Date.now() });
+  try {
+    await params.processUpdate({ update: params.update, target: params.target });
+    if (replayEventKey) {
+      await recentWebhookEvents.commit(replayEventKey);
+    }
+    return "processed";
+  } catch (error) {
+    if (replayEventKey) {
+      if (error instanceof ZaloRetryableWebhookError) {
+        recentWebhookEvents.release(replayEventKey, { error });
+      } else {
+        await recentWebhookEvents.commit(replayEventKey);
+      }
+    }
+    throw error;
   }
-  const key = `${update.event_name}:${messageId}`;
-  return recentWebhookEvents.check(key, nowMs);
 }
 
 function recordWebhookStatus(
@@ -222,14 +261,12 @@ export async function handleZaloWebhookRequest(
         return true;
       }
 
-      if (isReplayEvent(update, nowMs)) {
-        res.statusCode = 200;
-        res.end("ok");
-        return true;
-      }
-
-      target.statusSink?.({ lastInboundAt: Date.now() });
-      processUpdate({ update, target }).catch((err) => {
+      void processZaloReplayGuardedUpdate({
+        target,
+        update,
+        processUpdate,
+        nowMs,
+      }).catch((err) => {
         target.runtime.error?.(`[${target.account.accountId}] Zalo webhook failed: ${String(err)}`);
       });