@axiom-lattice/gateway 3.0.2 → 3.0.4

package/src/router/middlewares/auditLogger.ts

@@ -1,34 +0,0 @@
-import type { MessageMiddleware } from "../MessageContext";
-import { Logger } from "../../logger/Logger";
-
-const logger = new Logger({ serviceName: "lattice/gateway/audit" });
-
-export function createAuditLoggerMiddleware(): MessageMiddleware {
-  return async (ctx, next) => {
-    const start = Date.now();
-    try {
-      await next();
-      logger.info("message routed", {
-        event: "message:routed",
-        channel: ctx.inboundMessage.channel,
-        senderId: ctx.inboundMessage.sender.id,
-        agentId: ctx.binding?.agentId,
-        threadId: ctx.binding?.threadId,
-        duration: Date.now() - start,
-        status: "success",
-      });
-    } catch (error) {
-      logger.error(
-        error instanceof Error ? error.message : String(error),
-        {
-          event: "message:error",
-          channel: ctx.inboundMessage.channel,
-          senderId: ctx.inboundMessage.sender.id,
-          duration: Date.now() - start,
-          status: "error",
-        },
-      );
-      throw error;
-    }
-  };
-}

package/src/router/middlewares/deduplication.ts

@@ -1,38 +0,0 @@
-import type { MessageMiddleware } from "../MessageContext";
-
-const processedMessages = new Map<string, number>();
-
-export function createDeduplicationMiddleware(
-  ttlMs: number = 5 * 60 * 1000,
-): MessageMiddleware {
-  return async (ctx, next) => {
-    const msg = ctx.inboundMessage;
-    const msgId = msg.content.metadata?.messageId as string | undefined;
-    const key = msgId
-      ? `${msg.channel}:${msg.channelInstallationId}:${msgId}`
-      : null;
-
-    if (key) {
-      const now = Date.now();
-      const lastProcessed = processedMessages.get(key);
-      if (lastProcessed && (now - lastProcessed) < ttlMs) {
-        console.warn({
-          event: "dedup:blocked",
-          channel: msg.channel,
-          senderId: msg.sender.id,
-          messageId: msgId,
-        }, "Duplicate message blocked by deduplication");
-        return;
-      }
-      processedMessages.set(key, now);
-    }
-
-    if (processedMessages.size > 10000) {
-      const oldest = Array.from(processedMessages.entries())
-        .sort((a, b) => a[1] - b[1])[0];
-      if (oldest) processedMessages.delete(oldest[0]);
-    }
-
-    await next();
-  };
-}

package/src/router/middlewares/index.ts

@@ -1,3 +0,0 @@
-export { createDeduplicationMiddleware } from "./deduplication";
-export { createRateLimitMiddleware } from "./rateLimit";
-export { createAuditLoggerMiddleware } from "./auditLogger";

package/src/router/middlewares/rateLimit.ts

@@ -1,46 +0,0 @@
-import type { MessageMiddleware } from "../MessageContext";
-
-export class RateLimitError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "RateLimitError";
-  }
-}
-
-interface Counter { count: number; resetAt: number; }
-const rateCounters = new Map<string, Counter>();
-
-export function createRateLimitMiddleware(
-  maxRequests: number = 10,
-  windowMs: number = 60 * 1000,
-  maxEntries: number = 10000,
-): MessageMiddleware {
-  return async (ctx, next) => {
-    const senderKey = `${ctx.inboundMessage.channel}:${ctx.inboundMessage.sender.id}`;
-    const now = Date.now();
-    let counter = rateCounters.get(senderKey);
-    if (!counter || now > counter.resetAt) {
-      counter = { count: 0, resetAt: now + windowMs };
-    }
-    counter.count++;
-    rateCounters.set(senderKey, counter);
-
-    if (rateCounters.size > maxEntries) {
-      const oldest = Array.from(rateCounters.entries())
-        .sort((a, b) => a[1].resetAt - b[1].resetAt)[0];
-      if (oldest) rateCounters.delete(oldest[0]);
-    }
-
-    if (counter.count > maxRequests) {
-      console.warn({
-        event: "ratelimit:blocked",
-        channel: ctx.inboundMessage.channel,
-        senderId: ctx.inboundMessage.sender.id,
-        count: counter.count,
-        maxRequests,
-      }, "Rate limit exceeded");
-      throw new RateLimitError(`Rate limit exceeded`);
-    }
-    await next();
-  };
-}

package/src/routes/__tests__/a2a-test-connection.test.ts

@@ -1,177 +0,0 @@
-import fastify, { FastifyInstance } from "fastify";
-import type { LocalRuntimeConfig } from "@axiom-lattice/protocols";
-import { registerA2ATestConnectionRoute } from "../a2a-test-connection";
-
-const mockStartProvider = jest.fn();
-const mockRemoveState = jest.fn();
-
-jest.mock("../../services/local-a2a", () => ({
-  localA2AService: {
-    startProvider: (...args: unknown[]) => mockStartProvider(...args),
-    removeState: (...args: unknown[]) => mockRemoveState(...args),
-  },
-}));
-
-describe("A2A test connection route", () => {
-  let app: FastifyInstance;
-  const originalFetch = global.fetch;
-  const mockFetch = jest.fn<(...args: Parameters<typeof fetch>) => ReturnType<typeof fetch>>();
-
-  const localRuntime: LocalRuntimeConfig = {
-    label: "Local Test",
-    agentCardUrl: "http://old-host/.well-known/agent-card.json",
-    command: {
-      executable: "local-a2a",
-      args: ["--port", "4301"],
-    },
-  };
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-    global.fetch = mockFetch as unknown as typeof fetch;
-    app = fastify();
-    registerA2ATestConnectionRoute(app);
-  });
-
-  afterEach(async () => {
-    await app.close();
-    global.fetch = originalFetch;
-  });
-
-  it("starts a temporary local runtime before fetching the local agent card", async () => {
-    mockStartProvider.mockResolvedValueOnce({
-      runtimeId: "test-runtime",
-      label: "Local Test",
-      status: "running",
-      enabled: true,
-    });
-    mockFetch.mockResolvedValueOnce(
-      new Response(JSON.stringify({ name: "Local Agent" }), { status: 200 }),
-    );
-
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/a2a/test-connection",
-      payload: {
-        agentCardUrl: "localhost:4301",
-        localRuntime,
-      },
-    });
-
-    expect(response.statusCode).toBe(200);
-    const body = JSON.parse(response.body);
-    expect(body.data.reachable).toBe(true);
-    expect(body.data.agentName).toBe("Local Agent");
-
-    expect(mockStartProvider).toHaveBeenCalledTimes(1);
-    const [runtimeId, startedRuntime] = mockStartProvider.mock.calls[0] as [
-      string,
-      LocalRuntimeConfig,
-    ];
-    expect(runtimeId).toMatch(/^test-/);
-    expect(startedRuntime.agentCardUrl).toBe(
-      "http://localhost:4301/.well-known/agent-card.json",
-    );
-
-    expect(mockFetch).toHaveBeenCalledWith(
-      "http://localhost:4301/.well-known/agent-card.json",
-      expect.objectContaining({ headers: {} }),
-    );
-    expect(mockRemoveState).toHaveBeenCalledWith("test-runtime");
-  });
-
-  it("uses https by default for remote URL tests and does not start a local runtime", async () => {
-    mockFetch.mockResolvedValueOnce(
-      new Response(JSON.stringify({ name: "Remote Agent" }), { status: 200 }),
-    );
-
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/a2a/test-connection",
-      payload: {
-        agentCardUrl: "example.com/a2a",
-        apiKey: "secret",
-      },
-    });
-
-    expect(response.statusCode).toBe(200);
-    const body = JSON.parse(response.body);
-    expect(body.data.reachable).toBe(true);
-    expect(body.data.agentName).toBe("Remote Agent");
-    expect(mockStartProvider).not.toHaveBeenCalled();
-    expect(mockRemoveState).not.toHaveBeenCalled();
-    expect(mockFetch).toHaveBeenCalledWith(
-      "https://example.com/a2a/.well-known/agent-card.json",
-      expect.objectContaining({
-        headers: { Authorization: "Bearer secret" },
-      }),
-    );
-  });
-
-  it("does not fetch the agent card when the local runtime fails to start", async () => {
-    mockStartProvider.mockResolvedValueOnce({
-      runtimeId: "test-failed",
-      label: "Local Test",
-      status: "failed",
-      enabled: true,
-      message: "Server did not become ready",
-    });
-
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/a2a/test-connection",
-      payload: {
-        agentCardUrl: "localhost:4301",
-        localRuntime,
-      },
-    });
-
-    expect(response.statusCode).toBe(200);
-    const body = JSON.parse(response.body);
-    expect(body.data.reachable).toBe(false);
-    expect(body.data.error).toContain("Server did not become ready");
-    expect(mockFetch).not.toHaveBeenCalled();
-    expect(mockRemoveState).toHaveBeenCalledWith("test-failed");
-  });
-
-  it.each([
-    ["--port with next arg", ["--port", "4302"]],
-    ["--port inline", ["--port=4302"]],
-    ["-p with next arg", ["-p", "4302"]],
-    ["-p inline", ["-p=4302"]],
-  ])("does not start local runtime when %s mismatches the agent card URL port", async (_label, args) => {
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/a2a/test-connection",
-      payload: {
-        agentCardUrl: "http://localhost:4301/.well-known/agent-card.json",
-        localRuntime: {
-          ...localRuntime,
-          command: {
-            executable: "local-a2a",
-            args,
-          },
-        },
-      },
-    });
-
-    expect(response.statusCode).toBe(200);
-    const body = JSON.parse(response.body);
-    expect(body.data.reachable).toBe(false);
-    expect(body.data.error).toContain("command port (4302) does not match agentCardUrl port (4301)");
-    expect(mockStartProvider).not.toHaveBeenCalled();
-    expect(mockFetch).not.toHaveBeenCalled();
-  });
-
-  it("returns 400 when agentCardUrl is missing", async () => {
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/a2a/test-connection",
-      payload: {},
-    });
-
-    expect(response.statusCode).toBe(400);
-    expect(JSON.parse(response.body).error).toBe("agentCardUrl is required");
-    expect(mockFetch).not.toHaveBeenCalled();
-  });
-});

package/src/routes/a2a-bridge.ts

@@ -1,266 +0,0 @@
-/**
- * A2A Bridge — WebSocket-based reverse proxy for agents behind NAT.
- *
- * Agents open an outbound WebSocket to the gateway. The gateway stores
- * the connection and exposes an HTTP proxy endpoint per agent. When the
- * orchestrator calls the agent, the gateway proxies the HTTP request
- * over the persistent WebSocket instead of trying to reach a private IP.
- *
- * Agent flow:
- *   1. Connect ws://gateway/api/a2a/bridge
- *   2. Send { type: "agent:register", agentId: "...", agentCard: {...} }
- *   3. Wait for { type: "http:request", requestId, method, path, headers, body }
- *   4. Process locally, respond with { type: "http:response", requestId, status, headers, body }
- *
- * Gateway flow:
- *   1. Accept WebSocket, store connection by agentId
- *   2. Expose GET/POST /api/a2a/bridge/proxy/{agentId}/*
- *   3. When HTTP request arrives, push over WebSocket, await response, relay
- */
-
-import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
-import type { WebSocket } from 'ws';
-import { v4 } from 'uuid';
-
-// ─── Logging ────────────────────────────────────────────────────────────────
-
-const log = {
-  info(msg: string, ctx?: Record<string, unknown>) {
-    console.log(JSON.stringify({ level: 'info', msg, ...ctx }));
-  },
-  warn(msg: string, ctx?: Record<string, unknown>) {
-    console.warn(JSON.stringify({ level: 'warn', msg, ...ctx }));
-  },
-  error(msg: string, ctx?: Record<string, unknown>) {
-    console.error(JSON.stringify({ level: 'error', msg, ...ctx }));
-  },
-};
-
-// ─── Types ──────────────────────────────────────────────────────────────────
-
-interface PendingRequest {
-  resolve: (response: BridgeHttpResponse) => void;
-  reject: (error: Error) => void;
-  timer: ReturnType<typeof setTimeout>;
-  /** The agent owning this pending request — used for cleanup on disconnect */
-  agentId: string;
-}
-
-interface BridgeHttpResponse {
-  status: number;
-  headers: Record<string, string>;
-  body: string;
-}
-
-interface AgentConnection {
-  ws: WebSocket;
-  agentId: string;
-  agentCard: Record<string, unknown>;
-  connectedAt: number;
-}
-
-// ─── Connection Registry ────────────────────────────────────────────────────
-
-const connections = new Map<string, AgentConnection>();
-const pending = new Map<string, PendingRequest>();
-
-function getAgentIdFromPath(path: string): string | null {
-  // Path: /api/a2a/bridge/proxy/{agentId}/...
-  const match = path.match(/^\/api\/a2a\/bridge\/proxy\/([^/]+)/);
-  return match ? match[1] : null;
-}
-
-// ─── WebSocket Handler ──────────────────────────────────────────────────────
-
-function handleBridgeConnection(socket: WebSocket, _request: FastifyRequest): void {
-  let agentId: string | null = null;
-
-  log.info('Bridge WebSocket connected');
-
-  socket.on('message', (raw) => {
-    let msg: Record<string, unknown>;
-    try {
-      msg = JSON.parse(raw.toString());
-    } catch {
-      log.warn('Bridge invalid message');
-      return;
-    }
-
-    switch (msg.type) {
-      case 'agent:register': {
-        agentId = msg.agentId as string;
-        if (!agentId) {
-          socket.send(JSON.stringify({ type: 'error', message: 'agentId required' }));
-          socket.close();
-          return;
-        }
-        connections.set(agentId, {
-          ws: socket,
-          agentId,
-          agentCard: msg.agentCard as Record<string, unknown> ?? {},
-          connectedAt: Date.now(),
-        });
-        log.info('Agent registered via bridge', { agentId });
-        socket.send(JSON.stringify({ type: 'agent:registered', agentId }));
-        break;
-      }
-
-      case 'http:response': {
-        const requestId = msg.requestId as string;
-        const p = pending.get(requestId);
-        if (p) {
-          clearTimeout(p.timer);
-          pending.delete(requestId);
-          p.resolve({
-            status: (msg.status as number) ?? 200,
-            headers: (msg.headers as Record<string, string>) ?? {},
-            body: (msg.body as string) ?? '',
-          });
-        }
-        break;
-      }
-
-      case 'http:error': {
-        const requestId = msg.requestId as string;
-        const p = pending.get(requestId);
-        if (p) {
-          clearTimeout(p.timer);
-          pending.delete(requestId);
-          p.reject(new Error((msg.message as string) ?? 'Agent error'));
-        }
-        break;
-      }
-    }
-  });
-
-  socket.on('close', () => {
-    if (agentId) {
-      connections.delete(agentId);
-      log.info('Bridge WebSocket disconnected', { agentId });
-      // Reject only this agent's pending requests
-      for (const [reqId, p] of pending) {
-        if (p.agentId === agentId) {
-          clearTimeout(p.timer);
-          p.reject(new Error('Agent disconnected'));
-          pending.delete(reqId);
-        }
-      }
-    }
-  });
-
-  socket.on('error', (err) => {
-    log.error('Bridge WebSocket error', { agentId, error: err.message });
-  });
-}
-
-// ─── HTTP Proxy Handler ─────────────────────────────────────────────────────
-
-async function handleBridgeProxy(
-  request: FastifyRequest,
-  reply: FastifyReply,
-): Promise<void> {
-  const agentId = getAgentIdFromPath(request.url);
-  if (!agentId) {
-    reply.status(400).send({ error: 'Agent ID not found in path' });
-    return;
-  }
-
-  const conn = connections.get(agentId);
-  if (!conn) {
-    reply.status(503).send({
-      error: 'Agent not connected',
-      message: `Agent "${agentId}" is not connected via WebSocket bridge`,
-    });
-    return;
-  }
-
-  const requestId = v4();
-
-  // Build sub-path (strip the proxy prefix)
-  const subPath = request.url.replace(`/api/a2a/bridge/proxy/${agentId}`, '') || '/';
-
-  // Read body
-  let body: string | undefined;
-  if (request.method === 'POST' || request.method === 'PUT') {
-    body = typeof request.body === 'string'
-      ? request.body
-      : JSON.stringify(request.body ?? {});
-  }
-
-  const bridgeRequest = {
-    type: 'http:request',
-    requestId,
-    method: request.method,
-    path: subPath,
-    headers: {
-      'content-type': request.headers['content-type'] ?? 'application/json',
-      'accept': request.headers['accept'] ?? '*/*',
-    },
-    body: body ?? '',
-  };
-
-  const timeout = 300_000; // 5 min
-
-  try {
-    const response = await new Promise<BridgeHttpResponse>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        pending.delete(requestId);
-        reject(new Error(`Bridge request timeout after ${timeout}ms`));
-      }, timeout);
-
-      pending.set(requestId, { resolve, reject, timer, agentId });
-
-      try {
-        if (conn.ws.readyState !== conn.ws.OPEN) {
-          pending.delete(requestId);
-          reject(new Error('WebSocket not open'));
-          return;
-        }
-        conn.ws.send(JSON.stringify(bridgeRequest));
-      } catch (err) {
-        clearTimeout(timer);
-        pending.delete(requestId);
-        reject(err as Error);
-      }
-    });
-
-    // Relay response headers
-    for (const [key, value] of Object.entries(response.headers)) {
-      if (!['content-length', 'transfer-encoding', 'connection'].includes(key.toLowerCase())) {
-        reply.header(key, value);
-      }
-    }
-
-    reply.status(response.status);
-
-    // Try to send as JSON if possible
-    try {
-      const parsed = JSON.parse(response.body);
-      reply.send(parsed);
-    } catch {
-      reply.send(response.body);
-    }
-  } catch (err) {
-    log.error('Bridge proxy error', { agentId, error: (err as Error).message });
-    reply.status(502).send({
-      error: 'Bridge proxy error',
-      message: (err as Error).message,
-    });
-  }
-}
-
-// ─── Route Registration ─────────────────────────────────────────────────────
-
-export function registerA2ABridgeRoutes(app: FastifyInstance): void {
-  // WebSocket endpoint for agents to connect
-  app.get('/api/a2a/bridge', { websocket: true }, (socket, req) => {
-    handleBridgeConnection(socket, req);
-  });
-
-  // HTTP proxy endpoint — all paths under /api/a2a/bridge/proxy/{agentId}/
-  app.route({
-    method: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
-    url: '/api/a2a/bridge/proxy/*',
-    handler: handleBridgeProxy,
-  });
-}

package/src/routes/a2a-test-connection.ts

@@ -1,126 +0,0 @@
-import { FastifyInstance } from "fastify";
-import { randomUUID } from "node:crypto";
-import type { AgentCard, LocalRuntimeConfig } from "@axiom-lattice/protocols";
-import { localA2AService } from "../services/local-a2a";
-import { normalizeA2AAgentCardUrl } from "../utils/a2a-url";
-import {
-  validateLocalRuntimeCommand,
-  validateLocalRuntimePort,
-} from "../utils/local-a2a-runtime";
-
-type TestConnectionError = Error & {
-  code?: string;
-  cause?: unknown;
-};
-
-function describeTestConnectionError(error: unknown, agentCardUrl: string): string {
-  if (!(error instanceof Error)) {
-    return `Failed to fetch agent card from ${agentCardUrl}: ${String(error)}`;
-  }
-
-  const cause = (error as TestConnectionError).cause;
-  const causeParts: string[] = [];
-  if (cause instanceof Error) {
-    causeParts.push(cause.message);
-    const causeCode = (cause as TestConnectionError).code;
-    if (causeCode && !causeParts.some((part) => part.includes(causeCode))) {
-      causeParts.push(causeCode);
-    }
-  } else if (typeof cause === "object" && cause !== null) {
-    const code = "code" in cause ? String(cause.code) : "";
-    const message = "message" in cause ? String(cause.message) : "";
-    if (message) causeParts.push(message);
-    if (code && !message.includes(code)) causeParts.push(code);
-  }
-
-  const detail = causeParts.length > 0 ? ` (${causeParts.join(", ")})` : "";
-  return `Failed to fetch agent card from ${agentCardUrl}: ${error.message}${detail}`;
-}
-
-async function ensureLocalRuntimeForConnectionTest(
-  localRuntime: LocalRuntimeConfig,
-  agentCardUrl: string,
-): Promise<{ runtimeId: string } | { error: string }> {
-  const commandValidation = validateLocalRuntimeCommand(localRuntime);
-  if (!commandValidation.ok) {
-    return { error: commandValidation.error };
-  }
-  const testRuntime = {
-    ...localRuntime,
-    agentCardUrl,
-    command: {
-      ...localRuntime.command,
-      executable: localRuntime.command.executable.trim(),
-    },
-  };
-  const portValidation = validateLocalRuntimePort(testRuntime, agentCardUrl);
-  if (!portValidation.ok) {
-    return { error: portValidation.error };
-  }
-
-  const state = await localA2AService.startProvider(
-    `test-${randomUUID()}`,
-    testRuntime,
-  );
-  if (state.status === "running") return { runtimeId: state.runtimeId };
-  const detail = state.message ? ` ${state.message}` : "";
-  localA2AService.removeState(state.runtimeId);
-  return { error: `Local managed A2A server could not start for connection test.${detail}` };
-}
-
-async function readShortResponseBody(resp: Response): Promise<string> {
-  const body = await resp.text().catch(() => "");
-  return body.length > 500 ? `${body.slice(0, 500)}...` : body;
-}
-
-export function registerA2ATestConnectionRoute(app: FastifyInstance): void {
-  app.post("/api/a2a/test-connection", async (request, reply) => {
-    const { agentCardUrl, apiKey, localRuntime } = (request.body ?? {}) as {
-      agentCardUrl?: string;
-      apiKey?: string;
-      localRuntime?: LocalRuntimeConfig;
-    };
-    const normalizedAgentCardUrl = normalizeA2AAgentCardUrl(
-      agentCardUrl,
-      localRuntime ? "http://" : "https://",
-    );
-    if (!normalizedAgentCardUrl) {
-      return reply.status(400).send({ success: false, error: "agentCardUrl is required" });
-    }
-
-    let testRuntimeId: string | null = null;
-    try {
-      const headers: Record<string, string> = {};
-      if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
-
-      if (localRuntime) {
-        const localStartResult = await ensureLocalRuntimeForConnectionTest(localRuntime, normalizedAgentCardUrl);
-        if ("error" in localStartResult) {
-          return reply.send({ success: true, data: { reachable: false, error: localStartResult.error } });
-        }
-        testRuntimeId = localStartResult.runtimeId;
-      }
-
-      const resp = await fetch(normalizedAgentCardUrl, { headers, signal: AbortSignal.timeout(8000) });
-      if (!resp.ok) {
-        const body = await readShortResponseBody(resp);
-        const suffix = body ? `: ${body}` : "";
-        return reply.send({ success: true, data: { reachable: false, error: `HTTP ${resp.status} ${resp.statusText}${suffix}` } });
-      }
-      const card = await resp.json() as AgentCard;
-      return reply.send({ success: true, data: { reachable: true, agentName: card.name, agentCard: card } });
-    } catch (error: unknown) {
-      return reply.send({
-        success: true,
-        data: {
-          reachable: false,
-          error: describeTestConnectionError(error, normalizedAgentCardUrl),
-        },
-      });
-    } finally {
-      if (testRuntimeId) {
-        localA2AService.removeState(testRuntimeId);
-      }
-    }
-  });
-}