openclaw-openagent 1.0.13 → 1.0.14

package/src/transport/oasn/oasn-http.ts

@@ -1,529 +0,0 @@
-/**
- * OASN HTTP 客户端
- *
- * 设计依据：
- *   - docs/specs/2026-06-16-oasn-transport-abstraction-design.md §11.5（401 撤销）
- *   - docs/specs/2026-06-16-oasn-api-module-mapping.md §五（统一错误格式）
- *
- * 职责：
- *   1. 提供 GET/POST/PATCH/multipart 上传/二进制下载 等基础方法
- *   2. 注入 `Authorization: Bearer <api_key>` 头
- *   3. 解析 OASN 统一错误响应（`{ error: { code, message, retryable, request_id } }`）
- *      → 抛出 TransportError（保留 retryable / requestId 字段，便于上层判断）
- *   4. 401/UNAUTHENTICATED 时触发 `onCredentialRevoked` 回调（§11.5 撤销路径）
- *   5. 支持自动重试（仅当 `retryable: true` 时，最多 3 次指数退避）
- *
- * 不在此层处理：
- *   - SSE 升级（详见 oasn-invocation.ts 的 subscribeToInvocation）
- *   - 业务幂等持久化（详见 oasn-invocation.ts + state/store.ts）
- *   - file_ref LRU（详见 oasn-files.ts）
- */
-
-import { request as httpRequest, type RequestOptions } from 'node:http';
-import { request as httpsRequest } from 'node:https';
-import { URL } from 'node:url';
-
-import { logger } from '../../util/logger.js';
-import { makeTransportError, type TransportError } from '../types.js';
-import type { OasnErrorBody } from './oasn-types.js';
-
-/** OASN HTTP 客户端配置 */
-export interface OasnHttpConfig {
-  /** API base URL，如 `https://api.oasn.ai` */
-  apiBase: string;
-  /** Bearer token（api_key 或 access_token） */
-  token?: string;
-  /** 单次请求默认超时（ms） */
-  defaultTimeoutMs?: number;
-  /** 自动重试最大次数（仅当响应 retryable=true 时） */
-  maxRetries?: number;
-  /**
-   * 401/UNAUTHENTICATED 触发回调。
-   * 由 OasnTransport 接入，进一步触发 `credential_expired` 事件 + 清本地凭证（§11.5）。
-   */
-  onCredentialRevoked?: () => void;
-}
-
-/** 请求选项 */
-export interface OasnRequestOptions {
-  /** 自定义超时（覆盖 defaultTimeoutMs） */
-  timeoutMs?: number;
-  /** 自定义额外头（Authorization 由 client 自动注入，无需传入） */
-  headers?: Record<string, string>;
-  /** 跳过自动重试（如轮询接口自己控制节奏） */
-  skipRetry?: boolean;
-  /** Abort 信号 */
-  signal?: AbortSignal;
-}
-
-const DEFAULT_TIMEOUT_MS = 30_000;
-const DEFAULT_MAX_RETRIES = 3;
-
-type GlobalAgentState = {
-  NO_PROXY?: string | null;
-};
-
-type GlobalWithAgent = typeof globalThis & {
-  GLOBAL_AGENT?: GlobalAgentState;
-};
-
-/**
- * OpenClaw gateway may install global-agent for model/provider traffic. OASN
- * REL endpoints should keep their original TLS hostname; otherwise a local
- * proxy can turn `https://oasn-test...` into a certificate check against
- * `localhost`.
- */
-export function ensureOasnHostBypassesGlobalAgentProxy(hostname: string): void {
-  const normalized = hostname.trim().toLowerCase();
-  if (!normalized || normalized === 'localhost' || normalized === '127.0.0.1' || normalized === '::1') return;
-
-  const globalAgent = (globalThis as GlobalWithAgent).GLOBAL_AGENT;
-  if (!globalAgent || typeof globalAgent !== 'object') return;
-
-  const existing = String(globalAgent.NO_PROXY || '');
-  const entries = existing.split(/[\s,]+/).filter(Boolean);
-  if (entries.some((entry) => entry.toLowerCase() === normalized)) return;
-
-  globalAgent.NO_PROXY = entries.length > 0 ? `${entries.join(',')},${normalized}` : normalized;
-}
-
-function hasHeader(headers: Record<string, string>, name: string): boolean {
-  const lower = name.toLowerCase();
-  return Object.keys(headers).some((key) => key.toLowerCase() === lower);
-}
-
-export function buildNodeRequestOptions(
-  url: URL,
-  method: string,
-  headers: Record<string, string>,
-): RequestOptions & { servername?: string } {
-  const isHttps = url.protocol === 'https:';
-  const requestHeaders = { ...headers };
-  if (!hasHeader(requestHeaders, 'Host')) {
-    requestHeaders.Host = url.host;
-  }
-  const options: RequestOptions & { servername?: string } = {
-    method,
-    headers: requestHeaders,
-    hostname: url.hostname,
-    port: url.port || (isHttps ? 443 : 80),
-    path: `${url.pathname}${url.search}`,
-  };
-  if (isHttps) {
-    options.servername = url.hostname;
-  }
-  return options;
-}
-
-// ───────────────────────────────────────────────────────────────
-// 错误转换
-// ───────────────────────────────────────────────────────────────
-
-/**
- * 把 HTTP 响应（含可能的 OASN 统一错误体）转换为 TransportError。
- * 如果响应非 OASN 统一格式，使用 HTTP 状态码做兜底。
- */
-function toTransportError(
-  statusCode: number,
-  rawBody: string,
-): TransportError {
-  let code = `HTTP_${statusCode}`;
-  let message = rawBody.slice(0, 500);
-  let retryable = statusCode >= 500 || statusCode === 429 || statusCode === 408;
-  let requestId: string | undefined;
-
-  try {
-    const parsed = JSON.parse(rawBody) as Partial<OasnErrorBody>;
-    if (parsed?.error?.code) {
-      code = parsed.error.code;
-      message = parsed.error.message ?? message;
-      retryable = parsed.error.retryable ?? retryable;
-      requestId = parsed.error.request_id;
-    }
-  } catch {
-    // 非 JSON 响应，保留兜底值
-  }
-
-  return makeTransportError(code, `[${statusCode}] ${message}`, { retryable, requestId });
-}
-
-// ───────────────────────────────────────────────────────────────
-// OasnHttpClient
-// ───────────────────────────────────────────────────────────────
-
-export class OasnHttpClient {
-  private _config: OasnHttpConfig;
-
-  constructor(config: OasnHttpConfig) {
-    if (!config.apiBase) {
-      throw new Error('OasnHttpClient: apiBase is required');
-    }
-    this._config = {
-      apiBase: config.apiBase,
-      token: config.token,
-      defaultTimeoutMs: config.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS,
-      maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
-      onCredentialRevoked: config.onCredentialRevoked,
-    };
-  }
-
-  /** 动态更新 token —— 注册成功后由 OasnTransport 调用 */
-  setToken(token: string | undefined): void {
-    this._config.token = token;
-  }
-
-  // ─────────────────────────────────────────────────────────────
-  // 公共方法
-  // ─────────────────────────────────────────────────────────────
-
-  async get<T>(path: string, options?: OasnRequestOptions): Promise<T> {
-    return this._jsonRequest<T>('GET', path, undefined, options);
-  }
-
-  async post<T>(path: string, body: unknown, options?: OasnRequestOptions): Promise<T> {
-    return this._jsonRequest<T>('POST', path, body, options);
-  }
-
-  async patch<T>(path: string, body: unknown, options?: OasnRequestOptions): Promise<T> {
-    return this._jsonRequest<T>('PATCH', path, body, options);
-  }
-
-  /**
-   * multipart/form-data 上传。
-   * 仅支持 file + metadata 字段，不做通用 multipart 支持（OASN 上传场景固定）。
-   */
-  async postMultipart<T>(
-    path: string,
-    parts: {
-      file: { content: Buffer; filename: string; mimeType?: string };
-      fields?: Record<string, string>;
-    },
-    options?: OasnRequestOptions,
-  ): Promise<T> {
-    const boundary = `------oasn-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
-    const chunks: Buffer[] = [];
-
-    // 普通字段
-    if (parts.fields) {
-      for (const [key, value] of Object.entries(parts.fields)) {
-        chunks.push(Buffer.from(
-          `--${boundary}\r\n`
-          + `Content-Disposition: form-data; name="${key}"\r\n\r\n`
-          + `${value}\r\n`,
-        ));
-      }
-    }
-
-    // 文件字段
-    const mime = parts.file.mimeType ?? 'application/octet-stream';
-    chunks.push(Buffer.from(
-      `--${boundary}\r\n`
-      + `Content-Disposition: form-data; name="file"; filename="${parts.file.filename}"\r\n`
-      + `Content-Type: ${mime}\r\n\r\n`,
-    ));
-    chunks.push(parts.file.content);
-    chunks.push(Buffer.from(`\r\n--${boundary}--\r\n`));
-
-    const body = Buffer.concat(chunks);
-
-    return this._rawRequest<T>('POST', path, body, {
-      ...options,
-      headers: {
-        'Content-Type': `multipart/form-data; boundary=${boundary}`,
-        ...options?.headers,
-      },
-      isJsonBody: false,
-      expectJsonResponse: true,
-    });
-  }
-
-  /**
-   * 下载二进制内容（用于 Artifact 下载）。
-   * 不解析响应，直接返回 ArrayBuffer + 头信息。
-   */
-  async getBinary(
-    path: string,
-    options?: OasnRequestOptions,
-  ): Promise<{ content: ArrayBuffer; mimeType: string; displayName: string }> {
-    const url = this._resolveUrl(path);
-    const headers = this._buildHeaders({});
-    const timeoutMs = options?.timeoutMs ?? this._config.defaultTimeoutMs!;
-    return this._doBinaryRequest(url, headers, timeoutMs, options?.signal);
-  }
-
-  /**
-   * 暴露底层 raw 请求，用于 SSE 等流式场景（如 oasn-invocation 的 SSE 升级）。
-   * 调用方自行处理流式响应。
-   */
-  rawHttpRequest(
-    method: string,
-    path: string,
-    headers: Record<string, string>,
-    body?: Buffer | string,
-    options?: OasnRequestOptions,
-  ): Promise<{ statusCode: number; headers: Record<string, string>; body: string }> {
-    const url = this._resolveUrl(path);
-    const fullHeaders = this._buildHeaders(headers);
-    const timeoutMs = options?.timeoutMs ?? this._config.defaultTimeoutMs!;
-    return this._doRawRequest(url, method, fullHeaders, body, timeoutMs, options?.signal);
-  }
-
-  // ─────────────────────────────────────────────────────────────
-  // 内部实现
-  // ─────────────────────────────────────────────────────────────
-
-  private _resolveUrl(path: string): URL {
-    if (/^https?:\/\//i.test(path)) {
-      return new URL(path);
-    }
-    // path 必须以 / 开头
-    const base = this._config.apiBase.replace(/\/$/, '');
-    return new URL(`${base}${path}`);
-  }
-
-  private _buildHeaders(extra: Record<string, string>): Record<string, string> {
-    const headers: Record<string, string> = {
-      Accept: 'application/json',
-      ...extra,
-    };
-    if (this._config.token) {
-      headers['Authorization'] = `Bearer ${this._config.token}`;
-    }
-    return headers;
-  }
-
-  /**
-   * JSON 请求 —— body 自动 JSON.stringify，响应 JSON.parse。
-   * 含重试逻辑（仅当 retryable=true 时）。
-   */
-  private async _jsonRequest<T>(
-    method: string,
-    path: string,
-    body: unknown,
-    options?: OasnRequestOptions,
-  ): Promise<T> {
-    return this._rawRequest<T>(method, path, body, {
-      ...options,
-      isJsonBody: true,
-      expectJsonResponse: true,
-    });
-  }
-
-  private async _rawRequest<T>(
-    method: string,
-    path: string,
-    body: unknown,
-    options: OasnRequestOptions & { isJsonBody: boolean; expectJsonResponse: boolean },
-  ): Promise<T> {
-    const url = this._resolveUrl(path);
-    const headers = this._buildHeaders(options?.headers ?? {});
-
-    let bodyBuffer: Buffer | undefined;
-    if (body !== undefined) {
-      if (options.isJsonBody) {
-        const json = typeof body === 'string' ? body : JSON.stringify(body);
-        bodyBuffer = Buffer.from(json);
-        headers['Content-Type'] = 'application/json';
-        headers['Content-Length'] = String(bodyBuffer.length);
-      } else {
-        bodyBuffer = body as Buffer;
-        if (!headers['Content-Length']) {
-          headers['Content-Length'] = String(bodyBuffer.length);
-        }
-      }
-    }
-
-    const maxAttempts = options.skipRetry ? 1 : (this._config.maxRetries! + 1);
-    let lastErr: unknown;
-
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-      try {
-        if (attempt > 0) {
-          // 指数退避：200ms / 400ms / 800ms（含少量随机抖动）
-          const delay = 200 * Math.pow(2, attempt - 1) + Math.floor(Math.random() * 50);
-          await new Promise((r) => setTimeout(r, delay));
-          logger.info(`[transport/oasn/http] retry ${attempt}/${maxAttempts - 1} ${method} ${path}`);
-        }
-
-        const { statusCode, body: respBody } = await this._doRawRequest(
-          url,
-          method,
-          headers,
-          bodyBuffer,
-          options?.timeoutMs ?? this._config.defaultTimeoutMs!,
-          options?.signal,
-        );
-
-        if (statusCode >= 200 && statusCode < 300) {
-          if (!options.expectJsonResponse) return undefined as T;
-          if (statusCode === 204 || !respBody) return undefined as T;
-          try {
-            return JSON.parse(respBody) as T;
-          } catch (parseErr) {
-            throw makeTransportError(
-              'INVALID_JSON_RESPONSE',
-              `Failed to parse OASN response: ${(parseErr as Error).message}`,
-            );
-          }
-        }
-
-        // 错误响应
-        const err = toTransportError(statusCode, respBody);
-
-        // §11.5 401/UNAUTHENTICATED 撤销路径
-        if (statusCode === 401 || err.code === 'UNAUTHENTICATED') {
-          logger.warn(`[transport/oasn/http] 401 UNAUTHENTICATED on ${method} ${path}`);
-          this._config.onCredentialRevoked?.();
-          throw err; // 401 不重试
-        }
-
-        if (!err.retryable || attempt === maxAttempts - 1) throw err;
-        lastErr = err;
-        logger.warn(`[transport/oasn/http] retryable error code=${err.code} on ${method} ${path}, will retry`);
-      } catch (err) {
-        // 网络层错误（DNS / 连接 / 超时） —— 视为可重试
-        const isTransport = (err as TransportError).code !== undefined;
-        if (isTransport) throw err;
-        lastErr = err;
-        if (attempt === maxAttempts - 1) {
-          throw makeTransportError(
-            'NETWORK_ERROR',
-            `${method} ${path} failed: ${(err as Error).message}`,
-            { retryable: true },
-          );
-        }
-      }
-    }
-
-    // 不可达，但 TS 需要
-    throw lastErr ?? new Error('Unknown HTTP error');
-  }
-
-  /** 执行单次 HTTP 请求（不解析响应体格式） */
-  private _doRawRequest(
-    url: URL,
-    method: string,
-    headers: Record<string, string>,
-    body: Buffer | string | undefined,
-    timeoutMs: number,
-    signal?: AbortSignal,
-  ): Promise<{ statusCode: number; headers: Record<string, string>; body: string }> {
-    const isHttps = url.protocol === 'https:';
-    const requestFn = isHttps ? httpsRequest : httpRequest;
-    ensureOasnHostBypassesGlobalAgentProxy(url.hostname);
-
-    return new Promise((resolve, reject) => {
-      const reqOptions = buildNodeRequestOptions(url, method, headers);
-
-      let settled = false;
-      let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
-      const finish = (fn: () => void) => {
-        if (settled) return;
-        settled = true;
-        if (timeoutHandle) clearTimeout(timeoutHandle);
-        fn();
-      };
-
-      const req = requestFn(reqOptions, (res) => {
-        const chunks: Buffer[] = [];
-        res.on('data', (chunk: Buffer) => chunks.push(chunk));
-        res.on('end', () => {
-          const respBody = Buffer.concat(chunks).toString('utf-8');
-          const respHeaders: Record<string, string> = {};
-          for (const [k, v] of Object.entries(res.headers)) {
-            if (typeof v === 'string') respHeaders[k] = v;
-            else if (Array.isArray(v)) respHeaders[k] = v.join(', ');
-          }
-          finish(() => resolve({
-            statusCode: res.statusCode ?? 0,
-            headers: respHeaders,
-            body: respBody,
-          }));
-        });
-        res.on('error', (err) => finish(() => reject(err)));
-      });
-
-      req.on('error', (err) => finish(() => reject(err)));
-
-      timeoutHandle = setTimeout(() => {
-        req.destroy(new Error(`OASN HTTP timeout after ${timeoutMs}ms`));
-      }, timeoutMs);
-
-      // Abort 支持
-      if (signal) {
-        const onAbort = () => {
-          req.destroy(new Error('Request aborted'));
-        };
-        if (signal.aborted) onAbort();
-        else signal.addEventListener('abort', onAbort, { once: true });
-      }
-
-      if (body) req.write(body);
-      req.end();
-    });
-  }
-
-  /** 二进制下载 */
-  private _doBinaryRequest(
-    url: URL,
-    headers: Record<string, string>,
-    timeoutMs: number,
-    signal?: AbortSignal,
-  ): Promise<{ content: ArrayBuffer; mimeType: string; displayName: string }> {
-    const isHttps = url.protocol === 'https:';
-    const requestFn = isHttps ? httpsRequest : httpRequest;
-    ensureOasnHostBypassesGlobalAgentProxy(url.hostname);
-
-    return new Promise((resolve, reject) => {
-      const reqOptions = buildNodeRequestOptions(url, 'GET', headers);
-
-      let settled = false;
-      let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
-      const finish = (fn: () => void) => {
-        if (settled) return;
-        settled = true;
-        if (timeoutHandle) clearTimeout(timeoutHandle);
-        fn();
-      };
-
-      const req = requestFn(reqOptions, (res) => {
-        const status = res.statusCode ?? 0;
-        const chunks: Buffer[] = [];
-        res.on('data', (chunk: Buffer) => chunks.push(chunk));
-        res.on('end', () => {
-          const buf = Buffer.concat(chunks);
-          if (status >= 200 && status < 300) {
-            const mime = String(res.headers['content-type'] ?? 'application/octet-stream');
-            const disposition = String(res.headers['content-disposition'] ?? '');
-            const nameMatch = disposition.match(/filename\*?=([^;]+)/i);
-            const displayName = nameMatch
-              ? decodeURIComponent(nameMatch[1].replace(/^UTF-8''/i, '').replace(/^"|"$/g, ''))
-              : 'artifact';
-            finish(() => resolve({
-              content: buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer,
-              mimeType: mime,
-              displayName,
-            }));
-          } else {
-            finish(() => reject(toTransportError(status, buf.toString('utf-8'))));
-          }
-        });
-        res.on('error', (err) => finish(() => reject(err)));
-      });
-
-      req.on('error', (err) => finish(() => reject(err)));
-
-      timeoutHandle = setTimeout(() => {
-        req.destroy(new Error(`OASN binary download timeout after ${timeoutMs}ms`));
-      }, timeoutMs);
-
-      if (signal) {
-        const onAbort = () => req.destroy(new Error('Request aborted'));
-        if (signal.aborted) onAbort();
-        else signal.addEventListener('abort', onAbort, { once: true });
-      }
-
-      req.end();
-    });
-  }
-}