llm-session-proxy 0.1.0

package/src/config.js

@@ -0,0 +1,310 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 默认配置。
+ *
+ * 默认值刻意对齐 OpenCode Go / Zen 的要求（注入 x-opencode-* 会话头），
+ * 但每一项都可以被配置文件、环境变量或命令行参数覆盖，以适配任意上游。
+ */
+export const DEFAULT_CONFIG = {
+  listen: {
+    host: '127.0.0.1',
+    port: 9355,
+  },
+  upstream: {
+    protocol: 'https',
+    host: 'opencode.ai',
+    port: null,
+    basePath: '',
+    rewriteHost: true,
+  },
+  request: {
+    bufferBody: true,
+    maxBodyBytes: 64 * 1024 * 1024,
+    timeoutMs: 600000,
+    pathRewrite: [],
+    dropHeaders: [],
+    forwardClientSessionHeaders: true,
+  },
+  session: {
+    enabled: true,
+    headerNames: [
+      'x-opencode-session',
+      'x-session-id',
+      'x-conversation-id',
+      'x-thread-id',
+      'x-chat-id',
+    ],
+    bodyFields: [
+      'session_id',
+      'sessionId',
+      'conversation_id',
+      'conversationId',
+      'thread_id',
+      'threadId',
+      'chat_id',
+      'chatId',
+    ],
+    contentHash: {
+      enabled: true,
+      fields: ['system', 'system_instruction', 'instructions'],
+      includeFirstUserMessage: true,
+      includePromptField: true,
+    },
+    idPrefix: 'ses_',
+    idFormat: 'hex26',
+    requestIdFormat: 'msg_{{session.count}}',
+    maxSessions: 512,
+    ttlSeconds: 0,
+  },
+  inject: {
+    headers: {
+      'x-opencode-session': '{{session.id}}',
+      'x-opencode-request': '{{session.requestId}}',
+      'x-opencode-client': 'cli',
+      'x-opencode-project': 'global',
+    },
+    body: {},
+    removeBodyFields: [],
+    overwrite: true,
+  },
+  model: {
+    enabled: true,
+    field: 'model',
+    stripPrefixes: ['proxy-'],
+    map: {},
+    default: null,
+  },
+  userAgent: 'opencode/1.18.29 cli',
+  // keep：完全保留客户端 UA；replace：始终用上面的 UA；
+  // replace-generic：仅当客户端 UA 缺失或像个通用 HTTP 库时才替换（默认）
+  userAgentMode: 'replace-generic',
+  response: {
+    stream: true,
+    timeoutMs: 600000,
+  },
+  log: {
+    level: 'info',
+    file: null,
+    maxBytes: 5 * 1024 * 1024,
+    backups: 2,
+    requests: true,
+  },
+};
+
+const GENERIC_UA_RE = /^(node|undici|axios|node-fetch|python-requests|python-httpx|go-http-client|java|okhttp|curl|postmanruntime|got|superagent|request|apache-httpclient|libwww-perl|http\.client|wget)/i;
+
+const ENV_MAP = {
+  PROXY_HOST: ['listen', 'host'],
+  PROXY_PORT: ['listen', 'port'],
+  UPSTREAM_PROTO: ['upstream', 'protocol'],
+  UPSTREAM_HOST: ['upstream', 'host'],
+  UPSTREAM_PORT: ['upstream', 'port'],
+  UPSTREAM_BASE_PATH: ['upstream', 'basePath'],
+  OPENCODE_UA: ['userAgent'],
+  USER_AGENT: ['userAgent'],
+  USER_AGENT_MODE: ['userAgentMode'],
+  LOG_FILE: ['log', 'file'],
+  LOG_LEVEL: ['log', 'level'],
+  SESSION_ID_PREFIX: ['session', 'idPrefix'],
+  SESSION_ID_FORMAT: ['session', 'idFormat'],
+  REQUEST_ID_FORMAT: ['session', 'requestIdFormat'],
+  MAX_SESSIONS: ['session', 'maxSessions'],
+  SESSION_TTL: ['session', 'ttlSeconds'],
+  MODEL_ALIAS_PREFIX: ['model', 'stripPrefixes'],
+  INJECT_HEADERS: ['inject', 'headers'],
+  PATH_REWRITE: ['request', 'pathRewrite'],
+  TIMEOUT_MS: ['request', 'timeoutMs'],
+  MAX_BODY_BYTES: ['request', 'maxBodyBytes'],
+};
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** 递归合并：普通对象逐层合并，数组与其他类型整体覆盖。 */
+export function deepMerge(base, override) {
+  if (!isPlainObject(override)) return override === undefined ? base : override;
+  const out = Array.isArray(base) ? [...base] : { ...(isPlainObject(base) ? base : {}) };
+  for (const [key, value] of Object.entries(override)) {
+    if (value === undefined) continue;
+    out[key] = isPlainObject(value) && isPlainObject(out[key]) ? deepMerge(out[key], value) : value;
+  }
+  return out;
+}
+
+/** 宽松 JSON：允许 // 与 /* *​/ 注释、允许尾随逗号。方便写带说明的配置文件。 */
+export function parseJsonLoose(text, source = '<inline>') {
+  const stripped = text
+    .replace(/^\uFEFF/, '')
+    .replace(/"(?:\\.|[^"\\])*"|\/\/[^\n\r]*|\/\*[\s\S]*?\*\//g, (match) =>
+      match.startsWith('"') ? match : '',
+    )
+    .replace(/,(\s*[}\]])/g, '$1');
+  try {
+    return JSON.parse(stripped);
+  } catch (error) {
+    throw new Error(`配置文件解析失败（${source}）: ${error.message}`);
+  }
+}
+
+export function loadConfigFile(filePath) {
+  const resolved = path.resolve(filePath);
+  const text = fs.readFileSync(resolved, 'utf8');
+  const raw = parseJsonLoose(text, resolved);
+  if (!isPlainObject(raw)) throw new Error(`配置文件根节点必须是对象（${resolved}）`);
+  return { config: raw, path: resolved };
+}
+
+/** 把上游 URL / host:port 字符串解析成 upstream 片段。 */
+export function parseUpstream(input) {
+  if (!input) return {};
+  const text = String(input).trim();
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(text) ? text : `https://${text}`;
+  const url = new URL(withScheme);
+  const basePath = url.pathname && url.pathname !== '/' ? url.pathname.replace(/\/+$/, '') : '';
+  return {
+    protocol: url.protocol.replace(':', ''),
+    host: url.hostname,
+    port: url.port ? Number(url.port) : null,
+    basePath,
+  };
+}
+
+function setByPath(target, keyPath, value) {
+  let cursor = target;
+  for (let i = 0; i < keyPath.length - 1; i += 1) {
+    const key = keyPath[i];
+    if (!isPlainObject(cursor[key])) cursor[key] = {};
+    cursor = cursor[key];
+  }
+  cursor[keyPath[keyPath.length - 1]] = value;
+}
+
+function coerce(keyPath, raw) {
+  const key = keyPath.join('.');
+  if (/^(listen\.port|upstream\.port|request\.timeoutMs|request\.maxBodyBytes|session\.maxSessions|session\.ttlSeconds|response\.timeoutMs|log\.maxBytes|log\.backups)$/.test(key)) {
+    const num = Number(raw);
+    if (!Number.isFinite(num)) throw new Error(`环境变量 ${key} 需要是数字，收到 "${raw}"`);
+    return num;
+  }
+  if (/^(inject\.headers|request\.pathRewrite)$/.test(key)) {
+    const value = JSON.parse(raw);
+    return value;
+  }
+  if (key === 'model.stripPrefixes') {
+    return String(raw).split(',').map((s) => s.trim()).filter(Boolean);
+  }
+  return raw;
+}
+
+/** 从环境变量读取配置片段。 */
+export function configFromEnv(env = process.env) {
+  const out = {};
+  for (const [envName, keyPath] of Object.entries(ENV_MAP)) {
+    const raw = env[envName];
+    if (raw === undefined || raw === '') continue;
+    setByPath(out, keyPath, coerce(keyPath, raw));
+  }
+  if (env.CONFIG_FILE) out.__configFile = env.CONFIG_FILE;
+  return out;
+}
+
+function normalize(config) {
+  const next = { ...config };
+  if (typeof next.upstream?.host === 'string' && /:\/\//.test(next.upstream.host)) {
+    next.upstream = deepMerge(next.upstream, parseUpstream(next.upstream.host));
+  }
+  next.listen.port = Number(next.listen.port);
+  if (next.upstream.port !== null && next.upstream.port !== undefined) {
+    next.upstream.port = Number(next.upstream.port);
+  }
+  if (next.model && Array.isArray(next.model.stripPrefixes)) {
+    next.model.stripPrefixes = next.model.stripPrefixes.filter((p) => typeof p === 'string' && p.length > 0);
+  }
+  if (next.request && Array.isArray(next.request.pathRewrite)) {
+    next.request.pathRewrite = next.request.pathRewrite
+      .map((rule) => {
+        if (!rule || typeof rule !== 'object') return null;
+        const pattern = rule.pattern ?? rule.from;
+        const replacement = rule.replacement ?? rule.to ?? '';
+        if (typeof pattern !== 'string') return null;
+        try {
+          // 提前编译，配置错误在启动时就暴露
+          // eslint-disable-next-line no-new
+          new RegExp(pattern);
+        } catch (error) {
+          throw new Error(`pathRewrite 里的正则不合法 "${pattern}": ${error.message}`);
+        }
+        return { pattern, replacement, flags: rule.flags || undefined };
+      })
+      .filter(Boolean);
+  }
+  return next;
+}
+
+function validate(config) {
+  const errors = [];
+  if (!Number.isInteger(config.listen.port) || config.listen.port < 0 || config.listen.port > 65535) {
+    errors.push(`listen.port 不合法: ${config.listen.port}`);
+  }
+  if (!config.upstream?.host) errors.push('upstream.host 不能为空');
+  if (!['http', 'https'].includes(config.upstream?.protocol)) {
+    errors.push(`upstream.protocol 只支持 http / https，收到 ${config.upstream?.protocol}`);
+  }
+  if (config.session?.enabled && !['hex26', 'hex', 'uuid', 'base36', 'short'].includes(config.session.idFormat)) {
+    errors.push(`session.idFormat 不支持: ${config.session.idFormat}`);
+  }
+  if (config.inject?.headers && !isPlainObject(config.inject.headers)) {
+    errors.push('inject.headers 必须是对象（值为模板字符串）');
+  }
+  if (errors.length) throw new Error(`配置校验失败:\n  - ${errors.join('\n  - ')}`);
+  return config;
+}
+
+/**
+ * 组装最终配置：默认值 < 配置文件 < 环境变量 < 命令行参数。
+ * 三者都是同一套字段，优先级从低到高。
+ */
+export function buildConfig({ file = null, env = process.env, flags = {} } = {}) {
+  let merged = deepMerge(DEFAULT_CONFIG, {});
+  let configPath = file || env.CONFIG_FILE || null;
+
+  if (configPath) {
+    const loaded = loadConfigFile(configPath);
+    merged = deepMerge(merged, loaded.config);
+    configPath = loaded.path;
+  }
+
+  const fromEnv = configFromEnv(env);
+  delete fromEnv.__configFile;
+  merged = deepMerge(merged, fromEnv);
+  merged = deepMerge(merged, flags);
+
+  const normalized = normalize(merged);
+  validate(normalized);
+  normalized.__configPath = configPath;
+  return normalized;
+}
+
+/** 上游连接信息，供代理层使用。 */
+export function resolveUpstream(config) {
+  const { protocol, host, port, basePath } = config.upstream;
+  const defaultPort = protocol === 'https' ? 443 : 80;
+  return {
+    protocol,
+    host,
+    port: port ?? defaultPort,
+    hostHeader: (port ?? defaultPort) === defaultPort ? host : `${host}:${port ?? defaultPort}`,
+    basePath: basePath || '',
+  };
+}
+
+export function shouldReplaceUserAgent(incoming, config) {
+  const mode = config.userAgentMode || 'replace-generic';
+  if (mode === 'keep') return false;
+  if (mode === 'replace') return true;
+  if (!incoming) return true;
+  return GENERIC_UA_RE.test(String(incoming).trim()) || String(incoming).toLowerCase().includes('opencode');
+}

package/src/index.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  DEFAULT_CONFIG,
+  buildConfig,
+  deepMerge,
+  loadConfigFile,
+  parseJsonLoose,
+  parseUpstream,
+  resolveUpstream,
+} from './config.js';
+import { applyBodyInject, buildInjectHeaders, rewriteModel, rewritePath } from './inject.js';
+import { Logger } from './logger.js';
+import { createProxyServer } from './proxy.js';
+import {
+  SessionStore,
+  contentFingerprint,
+  findExplicitSession,
+  generateId,
+  normalizeSessionId,
+  resolveSession,
+} from './session.js';
+import { createContext, randomBase36, randomHex, renderDeep, renderTemplate } from './template.js';
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(fs.readFileSync(path.join(moduleDir, '..', 'package.json'), 'utf8'));
+
+export const VERSION = pkg.version;
+export const NAME = pkg.name;
+
+export {
+  DEFAULT_CONFIG,
+  Logger,
+  SessionStore,
+  applyBodyInject,
+  buildConfig,
+  buildInjectHeaders,
+  contentFingerprint,
+  createContext,
+  createProxyServer,
+  deepMerge,
+  findExplicitSession,
+  generateId,
+  loadConfigFile,
+  normalizeSessionId,
+  parseJsonLoose,
+  parseUpstream,
+  randomBase36,
+  randomHex,
+  renderDeep,
+  renderTemplate,
+  resolveSession,
+  resolveUpstream,
+  rewriteModel,
+  rewritePath,
+};
+
+/**
+ * 一步启动代理（适合在脚本里内嵌使用）。
+ *
+ * const proxy = await startProxy({ configFile: './my.json' });
+ * console.log(proxy.url);
+ */
+export async function startProxy(options = {}) {
+  const {
+    config: providedConfig,
+    configFile = null,
+    env = process.env,
+    flags = {},
+    logger: providedLogger = null,
+    silent = false,
+  } = options;
+
+  const config = providedConfig
+    ? deepMerge(DEFAULT_CONFIG, providedConfig)
+    : buildConfig({ file: configFile, env, flags });
+
+  const logger = providedLogger || new Logger({ ...config.log, console: !silent && config.log.level !== 'silent' });
+  const proxy = createProxyServer({ config, logger });
+  await proxy.listen();
+
+  const address = proxy.server.address();
+  const host = config.listen.host === '0.0.0.0' ? '127.0.0.1' : config.listen.host;
+  const url = `http://${host}:${address.port}`;
+
+  return {
+    ...proxy,
+    url,
+    logger,
+    async stop() {
+      await proxy.close();
+      logger.close();
+    },
+  };
+}
+
+export default {
+  NAME,
+  VERSION,
+  startProxy,
+  createProxyServer,
+  buildConfig,
+  SessionStore,
+  Logger,
+};

package/src/inject.js

@@ -0,0 +1,141 @@
+import { renderDeep, renderTemplate } from './template.js';
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeInto(target, patch) {
+  for (const [key, value] of Object.entries(patch)) {
+    if (isPlainObject(value) && isPlainObject(target[key])) mergeInto(target[key], value);
+    else target[key] = value;
+  }
+  return target;
+}
+
+function deleteByPath(target, keyPath) {
+  const segments = keyPath.split('.');
+  let cursor = target;
+  for (let i = 0; i < segments.length - 1; i += 1) {
+    cursor = cursor?.[segments[i]];
+    if (!isPlainObject(cursor) && !Array.isArray(cursor)) return;
+  }
+  if (cursor && typeof cursor === 'object') delete cursor[segments[segments.length - 1]];
+}
+
+/** 按规则重写请求路径（例如把客户端用的 /v1/ 映射到上游的 /zen/go/v1/）。 */
+export function rewritePath(originalPath, rules = []) {
+  let result = originalPath;
+  for (const rule of rules) {
+    const re = new RegExp(rule.pattern, rule.flags);
+    result = result.replace(re, rule.replacement);
+  }
+  return result;
+}
+
+/**
+ * 模型名重写：
+ *   1. map 精确映射优先（别名 -> 真实模型名）
+ *   2. stripPrefixes 逐条剥离（Trae 等客户端必须用 proxy- 前缀避开内置通道时使用）
+ *   3. default 兜底
+ * 返回 { changed, from, to }，未变化时 changed=false。
+ */
+export function rewriteModel(body, modelConfig, { logger } = {}) {
+  if (!modelConfig?.enabled || !isPlainObject(body)) return { changed: false };
+  const field = modelConfig.field || 'model';
+  const original = body[field];
+  if (typeof original !== 'string' || !original) return { changed: false };
+
+  const map = modelConfig.map || {};
+  const hasOwn = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+
+  let next = original;
+  if (hasOwn(map, original)) {
+    // 1. 原始名直接命中映射，优先级最高
+    next = map[original];
+  } else {
+    for (const prefix of modelConfig.stripPrefixes || []) {
+      if (prefix && next.startsWith(prefix)) {
+        next = next.slice(prefix.length);
+        break;
+      }
+    }
+    // 2. 剥掉前缀后再查一次 map，让客户端可以"加 proxy- 前缀 + 用短别名"同时成立
+    if (next !== original && hasOwn(map, next)) next = map[next];
+  }
+  if ((!next || next === original) && modelConfig.default) next = modelConfig.default;
+  if (!next || next === original) return { changed: false, from: original, to: original };
+
+  body[field] = next;
+  logger?.debug(`[model] ${original} -> ${next}`);
+  return { changed: true, from: original, to: next };
+}
+
+/** 按配置往请求体里补字段 / 删字段。 */
+/**
+ * 允许用 "metadata.trace" 这样的点路径书写注入字段，展开成嵌套对象再合并，
+ * 与 removeBodyFields 的写法保持一致。
+ */
+function expandDottedKeys(source) {
+  const out = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (!key.includes('.')) {
+      out[key] = value;
+      continue;
+    }
+    const segments = key.split('.');
+    let cursor = out;
+    for (let i = 0; i < segments.length - 1; i += 1) {
+      if (!isPlainObject(cursor[segments[i]])) cursor[segments[i]] = {};
+      cursor = cursor[segments[i]];
+    }
+    cursor[segments[segments.length - 1]] = value;
+  }
+  return out;
+}
+
+export function applyBodyInject(body, injectConfig, ctx) {
+  if (!isPlainObject(body) || !injectConfig) return { changed: false };
+  const changes = [];
+
+  if (injectConfig.body && Object.keys(injectConfig.body).length) {
+    const rendered = renderDeep(expandDottedKeys(injectConfig.body), ctx);
+    const before = JSON.stringify(body);
+    if (injectConfig.overwrite === false) {
+      const patch = {};
+      for (const [key, value] of Object.entries(rendered)) {
+        if (!(key in body)) patch[key] = value;
+      }
+      mergeInto(body, patch);
+    } else {
+      mergeInto(body, rendered);
+    }
+    if (JSON.stringify(body) !== before) changes.push(`body:${Object.keys(injectConfig.body).join(',')}`);
+  }
+
+  for (const keyPath of injectConfig.removeBodyFields || []) {
+    if (typeof keyPath === 'string' && keyPath) {
+      deleteByPath(body, keyPath);
+      changes.push(`body-${keyPath}`);
+    }
+  }
+
+  return { changed: changes.length > 0, changes };
+}
+
+/**
+ * 生成需要注入/覆盖的请求头。
+ * inject.overwrite === false 时，已存在的请求头不会被覆盖。
+ */
+export function buildInjectHeaders(injectConfig, ctx, existingLower = new Map()) {
+  const out = {};
+  const headers = injectConfig?.headers || {};
+  for (const [name, template] of Object.entries(headers)) {
+    if (template === null || template === undefined) continue;
+    const lower = name.toLowerCase();
+    if (injectConfig.overwrite === false && existingLower.has(lower)) continue;
+    const value = renderTemplate(String(template), ctx);
+    if (value === '') continue;
+    out[lower] = value;
+  }
+  return out;
+}

package/src/logger.js

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const LEVELS = { silent: 0, error: 1, warn: 2, info: 3, debug: 4 };
+const COLORS = { error: 31, warn: 33, info: 36, debug: 90 };
+
+function stringify(value) {
+  if (typeof value === 'string') return value;
+  if (value instanceof Error) return value.stack || value.message;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * 极简日志器：同时写控制台（TTY 带色）与可选文件（按大小轮转）。
+ * 不依赖任何第三方库。
+ *
+ * 文件写入刻意采用同步 API：日志量小（每请求两三行），换来的是
+ * "进程退出/轮转时不会丢最后几行"这一确定性——排错时最需要的正是尾部日志。
+ */
+export class Logger {
+  constructor(options = {}) {
+    const {
+      level = 'info',
+      file = null,
+      maxBytes = 5 * 1024 * 1024,
+      backups = 2,
+      console: toConsole = true,
+    } = options;
+
+    this.level = LEVELS[level] ?? LEVELS.info;
+    this.toConsole = toConsole;
+    this.maxBytes = maxBytes;
+    this.backups = Math.max(0, backups);
+    this.file = file ? path.resolve(file) : null;
+    this.written = 0;
+
+    if (this.file) {
+      try {
+        fs.mkdirSync(path.dirname(this.file), { recursive: true });
+      } catch {
+        /* 目录创建失败时退化为仅控制台输出 */
+      }
+      try {
+        this.written = fs.statSync(this.file).size;
+      } catch {
+        this.written = 0;
+      }
+    }
+  }
+
+  get filePath() {
+    return this.file;
+  }
+
+  #rotate() {
+    try {
+      for (let i = this.backups - 1; i >= 1; i -= 1) {
+        const src = `${this.file}.${i}`;
+        if (fs.existsSync(src)) fs.renameSync(src, `${this.file}.${i + 1}`);
+      }
+      if (fs.existsSync(this.file)) fs.renameSync(this.file, `${this.file}.1`);
+    } catch {
+      /* 轮转失败不影响主流程 */
+    }
+    this.written = 0;
+  }
+
+  #writeFile(line) {
+    if (!this.file) return;
+    const buf = Buffer.from(`${line}\n`, 'utf8');
+    if (this.maxBytes > 0 && this.written + buf.length > this.maxBytes) this.#rotate();
+    try {
+      fs.appendFileSync(this.file, buf);
+      this.written += buf.length;
+    } catch {
+      /* 写盘失败（磁盘满、权限）时静默降级，不能因为日志挂掉代理 */
+    }
+  }
+
+  #emit(level, args) {
+    if (LEVELS[level] > this.level) return;
+    const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    const text = args.map(stringify).join(' ');
+    const line = `${ts} [${level.toUpperCase()}] ${text}`;
+    if (this.toConsole) {
+      const color = COLORS[level] || 0;
+      const out = process.stderr.isTTY ? `\u001b[${color}m${line}\u001b[0m` : line;
+      process.stderr.write(`${out}\n`);
+    }
+    this.#writeFile(line);
+  }
+
+  error(...args) {
+    this.#emit('error', args);
+  }
+
+  warn(...args) {
+    this.#emit('warn', args);
+  }
+
+  info(...args) {
+    this.#emit('info', args);
+  }
+
+  debug(...args) {
+    this.#emit('debug', args);
+  }
+
+  child(prefix) {
+    return {
+      error: (...a) => this.error(prefix, ...a),
+      warn: (...a) => this.warn(prefix, ...a),
+      info: (...a) => this.info(prefix, ...a),
+      debug: (...a) => this.debug(prefix, ...a),
+    };
+  }
+
+  /** 保留接口：同步写入无需 flush，调用它只是为了语义清晰。 */
+  close() {
+    /* 无缓冲需要排空 */
+  }
+}
+
+export { LEVELS };