feat: add plugin HTTP hooks + Zalo plugin

src/gateway/server-http.ts

@@ -190,6 +190,7 @@ export function createGatewayHttpServer(opts: {
   controlUiBasePath: string;
   openAiChatCompletionsEnabled: boolean;
   handleHooksRequest: HooksRequestHandler;
+  handlePluginRequest?: HooksRequestHandler;
   resolvedAuth: import("./auth.js").ResolvedGatewayAuth;
 }): HttpServer {
   const {
@@ -198,6 +199,7 @@ export function createGatewayHttpServer(opts: {
     controlUiBasePath,
     openAiChatCompletionsEnabled,
     handleHooksRequest,
+    handlePluginRequest,
     resolvedAuth,
   } = opts;
   const httpServer: HttpServer = createHttpServer((req, res) => {
@@ -206,6 +208,7 @@ export function createGatewayHttpServer(opts: {
 
     void (async () => {
       if (await handleHooksRequest(req, res)) return;
+      if (handlePluginRequest && (await handlePluginRequest(req, res))) return;
       if (openAiChatCompletionsEnabled) {
         if (await handleOpenAiHttpRequest(req, res, { auth: resolvedAuth })) return;
       }

src/gateway/server-runtime-state.ts

@@ -10,12 +10,14 @@ import type { ChatAbortControllerEntry } from "./chat-abort.js";
 import type { HooksConfigResolved } from "./hooks.js";
 import { createGatewayHooksRequestHandler } from "./server/hooks.js";
 import { listenGatewayHttpServer } from "./server/http-listen.js";
+import { createGatewayPluginRequestHandler } from "./server/plugins-http.js";
 import type { GatewayWsClient } from "./server/ws-types.js";
 import { createGatewayBroadcaster } from "./server-broadcast.js";
 import { type ChatRunEntry, createChatRunState } from "./server-chat.js";
 import { MAX_PAYLOAD_BYTES } from "./server-constants.js";
 import { attachGatewayUpgradeHandler, createGatewayHttpServer } from "./server-http.js";
 import type { DedupeEntry } from "./server-shared.js";
+import type { PluginRegistry } from "../plugins/registry.js";
 
 export async function createGatewayRuntimeState(params: {
   cfg: {
@@ -28,12 +30,14 @@ export async function createGatewayRuntimeState(params: {
   openAiChatCompletionsEnabled: boolean;
   resolvedAuth: ResolvedGatewayAuth;
   hooksConfig: () => HooksConfigResolved | null;
+  pluginRegistry: PluginRegistry;
   deps: CliDeps;
   canvasRuntime: RuntimeEnv;
   canvasHostEnabled: boolean;
   allowCanvasHostInTests?: boolean;
   logCanvas: { info: (msg: string) => void; warn: (msg: string) => void };
   logHooks: ReturnType<typeof createSubsystemLogger>;
+  logPlugins: ReturnType<typeof createSubsystemLogger>;
 }): Promise<{
   canvasHost: CanvasHostHandler | null;
   httpServer: HttpServer;
@@ -89,12 +93,18 @@ export async function createGatewayRuntimeState(params: {
     logHooks: params.logHooks,
   });
 
+  const handlePluginRequest = createGatewayPluginRequestHandler({
+    registry: params.pluginRegistry,
+    log: params.logPlugins,
+  });
+
   const httpServer = createGatewayHttpServer({
     canvasHost,
     controlUiEnabled: params.controlUiEnabled,
     controlUiBasePath: params.controlUiBasePath,
     openAiChatCompletionsEnabled: params.openAiChatCompletionsEnabled,
     handleHooksRequest,
+    handlePluginRequest,
     resolvedAuth: params.resolvedAuth,
   });
 

src/gateway/server.impl.ts

@@ -67,6 +67,7 @@ const logHealth = log.child("health");
 const logCron = log.child("cron");
 const logReload = log.child("reload");
 const logHooks = log.child("hooks");
+const logPlugins = log.child("plugins");
 const logWsControl = log.child("ws");
 const canvasRuntime = runtimeForLogger(logCanvas);
 
@@ -222,12 +223,14 @@ export async function startGatewayServer(
     openAiChatCompletionsEnabled,
     resolvedAuth,
     hooksConfig: () => hooksConfig,
+    pluginRegistry,
     deps,
     canvasRuntime,
     canvasHostEnabled,
     allowCanvasHostInTests: opts.allowCanvasHostInTests,
     logCanvas,
     logHooks,
+    logPlugins,
   });
   let bonjourStop: (() => Promise<void>) | null = null;
   let bridge: import("../infra/bridge/server.js").NodeBridgeServer | null = null;

src/gateway/server/__tests__/test-utils.ts

@@ -0,0 +1,22 @@
+import type { PluginRegistry } from "../../../plugins/registry.js";
+
+export const createTestRegistry = (
+  overrides: Partial<PluginRegistry> = {},
+): PluginRegistry => {
+  const base: PluginRegistry = {
+    plugins: [],
+    tools: [],
+    channels: [],
+    gatewayHandlers: {},
+    httpHandlers: [],
+    cliRegistrars: [],
+    services: [],
+    diagnostics: [],
+  };
+  const merged = { ...base, ...overrides };
+  return {
+    ...merged,
+    gatewayHandlers: merged.gatewayHandlers ?? {},
+    httpHandlers: merged.httpHandlers ?? [],
+  };
+};

src/gateway/server/plugins-http.test.ts

@@ -0,0 +1,77 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { describe, expect, it, vi } from "vitest";
+
+import { createGatewayPluginRequestHandler } from "./plugins-http.js";
+import { createTestRegistry } from "./__tests__/test-utils.js";
+
+const makeResponse = () =>
+  ({
+    headersSent: false,
+    statusCode: 200,
+    setHeader: vi.fn(),
+    end: vi.fn(),
+  }) as unknown as ServerResponse;
+
+describe("createGatewayPluginRequestHandler", () => {
+  it("returns false when no handlers are registered", async () => {
+    const log = { warn: vi.fn() } as unknown as Parameters<
+      typeof createGatewayPluginRequestHandler
+    >[0]["log"];
+    const handler = createGatewayPluginRequestHandler({
+      registry: createTestRegistry(),
+      log,
+    });
+    const handled = await handler({} as IncomingMessage, makeResponse());
+    expect(handled).toBe(false);
+  });
+
+  it("continues until a handler reports it handled the request", async () => {
+    const first = vi.fn(async () => false);
+    const second = vi.fn(async () => true);
+    const handler = createGatewayPluginRequestHandler({
+      registry: createTestRegistry({
+        httpHandlers: [
+          { pluginId: "first", handler: first, source: "first" },
+          { pluginId: "second", handler: second, source: "second" },
+        ],
+      }),
+      log: { warn: vi.fn() } as unknown as Parameters<typeof createGatewayPluginRequestHandler>[0]["log"],
+    });
+
+    const handled = await handler({} as IncomingMessage, makeResponse());
+    expect(handled).toBe(true);
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it("logs and responds with 500 when a handler throws", async () => {
+    const log = { warn: vi.fn() } as unknown as Parameters<
+      typeof createGatewayPluginRequestHandler
+    >[0]["log"];
+    const handler = createGatewayPluginRequestHandler({
+      registry: createTestRegistry({
+        httpHandlers: [
+          {
+            pluginId: "boom",
+            handler: async () => {
+              throw new Error("boom");
+            },
+            source: "boom",
+          },
+        ],
+      }),
+      log,
+    });
+
+    const res = makeResponse();
+    const handled = await handler({} as IncomingMessage, res);
+    expect(handled).toBe(true);
+    expect(log.warn).toHaveBeenCalledWith(expect.stringContaining("boom"));
+    expect(res.statusCode).toBe(500);
+    expect(res.setHeader).toHaveBeenCalledWith(
+      "Content-Type",
+      "text/plain; charset=utf-8",
+    );
+    expect(res.end).toHaveBeenCalledWith("Internal Server Error");
+  });
+});

src/gateway/server/plugins-http.ts

@@ -0,0 +1,36 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { createSubsystemLogger } from "../../logging.js";
+import type { PluginRegistry } from "../../plugins/registry.js";
+
+type SubsystemLogger = ReturnType<typeof createSubsystemLogger>;
+
+export type PluginHttpRequestHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+) => Promise<boolean>;
+
+export function createGatewayPluginRequestHandler(params: {
+  registry: PluginRegistry;
+  log: SubsystemLogger;
+}): PluginHttpRequestHandler {
+  const { registry, log } = params;
+  return async (req, res) => {
+    if (registry.httpHandlers.length === 0) return false;
+    for (const entry of registry.httpHandlers) {
+      try {
+        const handled = await entry.handler(req, res);
+        if (handled) return true;
+      } catch (err) {
+        log.warn(`plugin http handler failed (${entry.pluginId}): ${String(err)}`);
+        if (!res.headersSent) {
+          res.statusCode = 500;
+          res.setHeader("Content-Type", "text/plain; charset=utf-8");
+          res.end("Internal Server Error");
+        }
+        return true;
+      }
+    }
+    return false;
+  };
+}