@nubemclaw/channel-telegram 1.2.2

package/src/transport.ts

@@ -0,0 +1,351 @@
+import type { ChannelLogger } from "@nubemclaw/channel-sdk";
+import { Agent, ProxyAgent, fetch as undiciFetch } from "undici";
+
+/**
+ * Telegram operational transport (Phase 13, task #144 v2).
+ *
+ * Port of the operational hardening from OpenClaw
+ * `extensions/telegram/src/fetch.ts:862`. Telegram long-polling keeps
+ * connections to `api.telegram.org` hot for hours; the default global
+ * `fetch`/undici behavior is wrong for this access pattern in three
+ * concrete ways the OpenClaw codebase documented through real
+ * production incidents (openclaw#68128 is cited verbatim in
+ * fetch.ts:37-39):
+ *
+ *   1. **HTTP/2 ALPN stalls long-polling.** Undici 8 enables HTTP/2
+ *      negotiation by default. The Telegram Bot API serves both /1.1
+ *      and /2, but the /2 stream behavior interacts badly with the
+ *      long-poll on Windows/IPv6 networks — connections hang past the
+ *      `getUpdates(timeout=N)` budget. `allowH2: false` pins HTTP/1.1.
+ *
+ *   2. **Unbounded connection pool leaks sockets.** The default Agent
+ *      has no per-origin connection limit and an effectively
+ *      unbounded `keepAliveTimeout`. Long polling rotates dispatchers
+ *      slowly; the leak grows monotonically until file descriptors
+ *      exhaust. Pinning `connections: 10`, `keepAliveTimeout: 30s` and
+ *      `keepAliveMaxTimeout: 600s` keeps the pool bounded.
+ *
+ *   3. **No way to release sockets on shutdown.** A polling session
+ *      that stops without destroying its dispatcher leaves keep-alive
+ *      sockets open. The exported `close()` calls `destroy()` on
+ *      every owned dispatcher so the runner can swap or drop the
+ *      transport cleanly.
+ *
+ * Two additional concerns the transport handles:
+ *
+ *   - **IPv4 fallback with sticky attempts**: some operator networks
+ *     (notably IPv6-only with broken NAT64) cannot reach
+ *     `api.telegram.org` over IPv6. OpenClaw observed enough of this
+ *     to ship sticky fallback to `family: 4`. We port the same
+ *     behavior with a simpler health model: after N consecutive
+ *     failures the transport flips to the IPv4-pinned dispatcher.
+ *
+ *   - **Proxy support**: `NUBEMCLAW_PROXY_URL` env var or constructor
+ *     param mounts an undici `ProxyAgent`. Corporate networks behind
+ *     egress proxies need this — there is no built-in env support in
+ *     grammy's default `globalThis.fetch`.
+ *
+ * What this implementation deliberately omits vs OpenClaw fetch.ts:
+ *
+ *   - **DNS pinning to hardcoded Telegram IPs** (the `149.154.167.220`
+ *     fallback list). Telegram rotates IPs on its own schedule; a
+ *     hardcoded list is a hostile maintenance burden and we have no
+ *     evidence it solved an incident outside OpenClaw's specific
+ *     deployment. If we see DNS failures in v3 we revisit.
+ *   - **HTTP exchange capture** (the `captureHttpExchange` calls).
+ *     That is a debug-only feature wired to OpenClaw's internal
+ *     observability; not portable to v3 today.
+ *
+ * The transport returns a `fetch` callable that grammy's `Bot`
+ * constructor accepts via `new Bot(token, { client: { fetcher } })`.
+ */
+
+const TELEGRAM_API_HOSTNAME = "api.telegram.org";
+const POOL_KEEP_ALIVE_TIMEOUT_MS = 30_000;
+const POOL_KEEP_ALIVE_MAX_TIMEOUT_MS = 600_000;
+const POOL_CONNECTIONS_PER_ORIGIN = 10;
+const POOL_PIPELINING = 1;
+const FALLBACK_FAILURE_THRESHOLD = 5;
+const FALLBACK_COOLDOWN_INITIAL_MS = 10_000;
+const FALLBACK_COOLDOWN_MAX_MS = 60_000;
+
+const FALLBACK_NETWORK_ERROR_CODES = new Set([
+  "ETIMEDOUT",
+  "ENETUNREACH",
+  "EHOSTUNREACH",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_SOCKET",
+]);
+
+const poolOptions = (): {
+  allowH2: false;
+  keepAliveTimeout: number;
+  keepAliveMaxTimeout: number;
+  connections: number;
+  pipelining: number;
+} => ({
+  allowH2: false,
+  keepAliveTimeout: POOL_KEEP_ALIVE_TIMEOUT_MS,
+  keepAliveMaxTimeout: POOL_KEEP_ALIVE_MAX_TIMEOUT_MS,
+  connections: POOL_CONNECTIONS_PER_ORIGIN,
+  pipelining: POOL_PIPELINING,
+});
+
+const collectErrorCodes = (err: unknown): Set<string> => {
+  const codes = new Set<string>();
+  const queue: unknown[] = [err];
+  const seen = new Set<unknown>();
+  let i = 0;
+  while (i < queue.length) {
+    const current = queue[i++];
+    if (current === null || current === undefined || seen.has(current)) continue;
+    seen.add(current);
+    if (typeof current !== "object") continue;
+    const code = (current as { code?: unknown }).code;
+    if (typeof code === "string" && code.trim() !== "") {
+      codes.add(code.trim().toUpperCase());
+    }
+    const cause = (current as { cause?: unknown }).cause;
+    if (cause !== undefined) queue.push(cause);
+    const nested = (current as { errors?: unknown }).errors;
+    if (Array.isArray(nested)) for (const n of nested) queue.push(n);
+  }
+  return codes;
+};
+
+const shouldFallback = (err: unknown): boolean => {
+  if (err === null || err === undefined) return false;
+  const codes = collectErrorCodes(err);
+  for (const c of FALLBACK_NETWORK_ERROR_CODES) {
+    if (codes.has(c)) return true;
+  }
+  const message =
+    err !== null && typeof err === "object" && "message" in err
+      ? String((err as { message: unknown }).message).toLowerCase()
+      : "";
+  return message.includes("fetch failed") && codes.size === 0;
+};
+
+type Dispatcher = Agent | ProxyAgent;
+
+type AttemptKind = "primary" | "fallback-ipv4";
+
+interface Attempt {
+  readonly kind: AttemptKind;
+  readonly create: () => Dispatcher;
+}
+
+interface AttemptHealth {
+  consecutiveFailures: number;
+  cooldownMs: number;
+  unhealthyUntilMs: number;
+}
+
+export interface TelegramTransportOptions {
+  /**
+   * Explicit proxy URL (`http://...` / `https://...`). Defaults to
+   * `NUBEMCLAW_PROXY_URL` env var. When set, every dispatcher routes
+   * through this proxy via `undici.ProxyAgent`.
+   */
+  readonly proxyUrl?: string;
+  /** Custom logger; defaults to a silent one (transport doesn't own loggers). */
+  readonly logger?: ChannelLogger;
+  /** Test seam: override the env var for proxy resolution. */
+  readonly envVars?: NodeJS.ProcessEnv;
+}
+
+export interface TelegramTransport {
+  /**
+   * `fetch`-shaped callable usable directly as `new Bot(token,
+   * { client: { fetcher } }).` Routes through the primary dispatcher
+   * with automatic IPv4 fallback on persistent network failures.
+   */
+  fetch: typeof globalThis.fetch;
+  /**
+   * Destroys every dispatcher this transport owns. Safe to call
+   * multiple times; subsequent calls resolve immediately. The runner
+   * MUST call this when stopping the channel — otherwise undici keeps
+   * keep-alive sockets open indefinitely.
+   */
+  close(): Promise<void>;
+}
+
+const silentLogger: ChannelLogger = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+};
+
+const resolveProxyUrl = (opts: TelegramTransportOptions): string | undefined => {
+  const explicit = opts.proxyUrl?.trim();
+  if (explicit !== undefined && explicit !== "") return explicit;
+  const envVars = opts.envVars ?? process.env;
+  const env = envVars["NUBEMCLAW_PROXY_URL"]?.trim();
+  return env !== undefined && env !== "" ? env : undefined;
+};
+
+export const createTelegramTransport = (opts: TelegramTransportOptions = {}): TelegramTransport => {
+  const logger = opts.logger ?? silentLogger;
+  const proxyUrl = resolveProxyUrl(opts);
+  const owned = new Set<Dispatcher>();
+
+  const buildPrimary = (): Dispatcher => {
+    if (proxyUrl !== undefined) {
+      return new ProxyAgent({ uri: proxyUrl, ...poolOptions() });
+    }
+    return new Agent({ ...poolOptions() });
+  };
+  const buildFallbackIpv4 = (): Dispatcher => {
+    // Force IPv4. ProxyAgent doesn't take a connect.family override
+    // directly via construction — when a proxy is in play we keep the
+    // dispatcher identical to primary because the IPv4 vs IPv6 decision
+    // is made by the proxy itself. Without a proxy we pin family: 4.
+    if (proxyUrl !== undefined) {
+      return new ProxyAgent({ uri: proxyUrl, ...poolOptions() });
+    }
+    return new Agent({
+      ...poolOptions(),
+      connect: { family: 4 },
+    });
+  };
+
+  // Lazy dispatcher instantiation per attempt so we only pay the cost
+  // when the attempt is actually exercised.
+  let primaryDispatcher: Dispatcher | null = null;
+  let fallbackDispatcher: Dispatcher | null = null;
+  const getPrimary = (): Dispatcher => {
+    if (primaryDispatcher === null) {
+      primaryDispatcher = buildPrimary();
+      owned.add(primaryDispatcher);
+    }
+    return primaryDispatcher;
+  };
+  const getFallback = (): Dispatcher => {
+    if (fallbackDispatcher === null) {
+      fallbackDispatcher = buildFallbackIpv4();
+      owned.add(fallbackDispatcher);
+    }
+    return fallbackDispatcher;
+  };
+
+  const attempts: Attempt[] = [
+    { kind: "primary", create: getPrimary },
+    { kind: "fallback-ipv4", create: getFallback },
+  ];
+  const health: AttemptHealth[] = attempts.map(() => ({
+    consecutiveFailures: 0,
+    cooldownMs: FALLBACK_COOLDOWN_INITIAL_MS,
+    unhealthyUntilMs: 0,
+  }));
+  let stickyIndex = 0;
+
+  const recordSuccess = (attemptIndex: number): void => {
+    const h = health[attemptIndex];
+    if (h === undefined) return;
+    h.consecutiveFailures = 0;
+    h.cooldownMs = FALLBACK_COOLDOWN_INITIAL_MS;
+    h.unhealthyUntilMs = 0;
+    if (attemptIndex < stickyIndex) {
+      logger.debug(
+        { from: stickyIndex, to: attemptIndex },
+        "telegram transport: recovered to lower-cost attempt",
+      );
+      stickyIndex = attemptIndex;
+    }
+  };
+
+  const recordFailure = (attemptIndex: number, err: unknown): void => {
+    if (!shouldFallback(err)) return;
+    const h = health[attemptIndex];
+    if (h === undefined) return;
+    h.consecutiveFailures += 1;
+    if (h.consecutiveFailures < FALLBACK_FAILURE_THRESHOLD) return;
+    const cooldownMs = Math.min(FALLBACK_COOLDOWN_MAX_MS, h.cooldownMs);
+    h.consecutiveFailures = 0;
+    h.cooldownMs = Math.min(FALLBACK_COOLDOWN_MAX_MS, cooldownMs * 2);
+    h.unhealthyUntilMs = Date.now() + cooldownMs;
+    logger.warn(
+      { attempt: attempts[attemptIndex]?.kind, cooldownMs },
+      "telegram transport: attempt marked temporarily unhealthy",
+    );
+  };
+
+  const promoteSticky = (): void => {
+    if (stickyIndex < attempts.length - 1) {
+      stickyIndex += 1;
+      logger.warn(
+        { newAttempt: attempts[stickyIndex]?.kind },
+        "telegram transport: promoting to fallback attempt",
+      );
+    }
+  };
+
+  const wrappedFetch: typeof globalThis.fetch = async (input, init) => {
+    let lastErr: unknown;
+    for (let attemptIndex = stickyIndex; attemptIndex < attempts.length; attemptIndex += 1) {
+      const attempt = attempts[attemptIndex];
+      if (attempt === undefined) break;
+      const h = health[attemptIndex];
+      if (h !== undefined && h.unhealthyUntilMs > Date.now()) {
+        // Skip this attempt while it cools down.
+        lastErr = new Error(`telegram transport: attempt '${attempt.kind}' cooling down`);
+        continue;
+      }
+      try {
+        const dispatcher = attempt.create();
+        // Cast to RequestInit + dispatcher property — undici's RequestInit
+        // extends the global with `dispatcher`, but the global `fetch`
+        // type doesn't know that.
+        const initWithDispatcher = {
+          ...init,
+          dispatcher,
+        } as unknown as Parameters<typeof undiciFetch>[1];
+        const res = await undiciFetch(
+          input as Parameters<typeof undiciFetch>[0],
+          initWithDispatcher,
+        );
+        recordSuccess(attemptIndex);
+        return res as unknown as Response;
+      } catch (cause) {
+        lastErr = cause;
+        if (!shouldFallback(cause)) throw cause;
+        recordFailure(attemptIndex, cause);
+        if (attemptIndex === stickyIndex && attemptIndex < attempts.length - 1) {
+          promoteSticky();
+        }
+      }
+    }
+    throw lastErr;
+  };
+
+  let closed = false;
+  const close = async (): Promise<void> => {
+    if (closed) return;
+    closed = true;
+    const toDestroy = [...owned];
+    owned.clear();
+    await Promise.all(
+      toDestroy.map(async (d) => {
+        try {
+          await d.destroy();
+        } catch {
+          // Already destroyed — ignore.
+        }
+      }),
+    );
+  };
+
+  return {
+    fetch: wrappedFetch,
+    close,
+  };
+};
+
+/**
+ * Sentinel constant identifying the Telegram API host. Exported for
+ * tests that want to assert the transport is being aimed at the right
+ * origin (the wrapped fetch does not enforce this — `globalThis.fetch`
+ * resolves the URL the caller supplies).
+ */
+export const TELEGRAM_HOST = TELEGRAM_API_HOSTNAME;