dsh-proxy-routing 0.4.1

package/lib/config.js

@@ -0,0 +1,194 @@
+// lib/config.js — v2 canonical proxy-routing state and pure validation helpers.
+// Persistence is owned by the official DSH settings seam (`proxy-routing` in
+// `$DSH_HOME/settings.yaml`); this module has no private file lifecycle.
+
+export const CONFIG_VERSION = 2;
+export const DEFAULT_PROFILE_ID = "default";
+
+/** 未配置代理端点时的固定指引文案（工具/校验/状态共用，避免散落）。 */
+export const UNCONFIGURED_GUIDANCE =
+  "代理端点未配置：请运行 net_proxy_discover（仅 Full Access）寻找已运行代理，或向用户询问 protocol/host/port 后运行 net_proxy_probe，再请求 net_proxy_enable。";
+
+/** 全新 canonical 默认：default profile 未配置端点，agent 直连，gateway 关闭。 */
+export function canonicalDefaults() {
+  return {
+    version: CONFIG_VERSION,
+    profiles: [
+      {
+        id: DEFAULT_PROFILE_ID,
+        noProxy: ["127.0.0.1", "localhost", "::1", "api.deepseek.com"],
+        timeout: 60000,
+      },
+    ],
+    bindings: {
+      agent: { kind: "direct" },
+      providers: [],
+      gateway: null,
+      gatewayPurposes: [],
+    },
+    gateway: {
+      enabled: false,
+      port: 17890,
+      dedicatedPurposePorts: false,
+      purposes: [],
+    },
+  };
+}
+
+/** 把 profile 投影为通道层使用的代理参数对象。 */
+export function toProxy(value) {
+  const profile = value && Array.isArray(value.profiles)
+    ? value.profiles.find((entry) => entry?.id === DEFAULT_PROFILE_ID) ?? value.profiles[0]
+    : value;
+  const c = profile && typeof profile === "object" ? profile : {};
+  return {
+    protocol: c.protocol,
+    host: c.host,
+    port: c.port,
+    username: c.username || undefined,
+    password: c.password || undefined,
+    noProxy: Array.isArray(c.noProxy) ? c.noProxy : [],
+    timeout: c.timeout ?? 60000,
+  };
+}
+
+
+/** profile 是否已配置端点（protocol/host/port 齐全，且 host 非空）。 */
+export function profileConfigured(profile) {
+  return Boolean(
+    profile &&
+      (profile.protocol === "http" || profile.protocol === "socks5") &&
+      typeof profile.host === "string" &&
+      profile.host.trim() !== "" &&
+      Number.isInteger(profile.port) &&
+      profile.port >= 1 &&
+      profile.port <= 65535,
+  );
+}
+
+function configError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function validProviderId(id) {
+  if (typeof id !== "string" || id.length === 0 || id.length > 64 || /[\s\u0000-\u001f]/.test(id)) {
+    throw configError("INVALID_PROVIDER_ID", `invalid provider id: ${JSON.stringify(id)}`);
+  }
+  return id;
+}
+
+/** 校验 + 规范化 canonical。无效 profile 引用、被 profile 路由引用但未配置端点的 profile 抛固定指引错误。 */
+export function validateCanonical(input) {
+  const c = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  if (c.version !== undefined && c.version !== CONFIG_VERSION) {
+    throw configError("UNSUPPORTED_CONFIG_VERSION", `unsupported proxy-routing config version: ${JSON.stringify(c.version)}`);
+  }
+  const canonical = canonicalDefaults();
+
+  const defaultProfile = canonical.profiles[0];
+  const rawProfiles = Array.isArray(c.profiles) && c.profiles.length > 0 ? c.profiles : canonical.profiles;
+  const ids = new Set();
+  canonical.profiles = rawProfiles.map((p, index) => {
+    const profile = {
+      id: p && typeof p.id === "string" && p.id !== "" ? p.id : index === 0 ? DEFAULT_PROFILE_ID : `profile-${index}`,
+      noProxy: [...defaultProfile.noProxy],
+      timeout: defaultProfile.timeout,
+    };
+    if (profile.id.length > 64 || /\s/.test(profile.id)) {
+      throw configError("INVALID_PROFILE_ID", `invalid profile id: ${JSON.stringify(profile.id)}`);
+    }
+    if (ids.has(profile.id)) throw configError("DUPLICATE_PROFILE_ID", `duplicate profile id: ${profile.id}`);
+    ids.add(profile.id);
+    if (!p || typeof p !== "object") return profile;
+    if (p.protocol === "http" || p.protocol === "socks5") profile.protocol = p.protocol;
+    if (typeof p.host === "string") profile.host = p.host;
+    if (p.port !== undefined) {
+      if (!Number.isInteger(p.port) || p.port < 1 || p.port > 65535) {
+        throw configError("INVALID_PORT", `profile ${profile.id}: invalid port`);
+      }
+      profile.port = p.port;
+    }
+    if (typeof p.username === "string") profile.username = p.username;
+    if (typeof p.password === "string") profile.password = p.password;
+    if (Array.isArray(p.noProxy)) profile.noProxy = p.noProxy.filter((x) => typeof x === "string");
+    if (Number.isInteger(p.timeout) && p.timeout > 0) profile.timeout = p.timeout;
+    return profile;
+  });
+
+  const normRoute = (route) => {
+    if (!route || typeof route !== "object") return { kind: "direct" };
+    if (route.kind === "direct") return { kind: "direct" };
+    if (route.kind === "profile") {
+      if (typeof route.profileId !== "string" || route.profileId === "") {
+        throw configError("INVALID_ROUTE", "profile route requires a profileId");
+      }
+      if (!ids.has(route.profileId)) {
+        throw configError("MISSING_PROFILE", `profile route references missing profile "${route.profileId}"`);
+      }
+      const profile = canonical.profiles.find((x) => x.id === route.profileId);
+      if (!profileConfigured(profile)) {
+        throw configError("UNCONFIGURED_PROFILE", UNCONFIGURED_GUIDANCE);
+      }
+      return { kind: "profile", profileId: route.profileId };
+    }
+    throw configError("INVALID_ROUTE", `unknown route kind: ${JSON.stringify(route.kind)}`);
+  };
+
+  const bindings = c.bindings && typeof c.bindings === "object" ? c.bindings : {};
+  canonical.bindings = {
+    agent: normRoute(bindings.agent),
+    providers: Array.isArray(bindings.providers)
+      ? bindings.providers
+          .filter((entry) => entry && typeof entry === "object" && typeof entry.provider === "string")
+          .map((entry) => ({ provider: validProviderId(entry.provider), route: normRoute(entry.route) }))
+      : [],
+    gateway: bindings.gateway == null ? null : normRoute(bindings.gateway),
+    gatewayPurposes: Array.isArray(bindings.gatewayPurposes)
+      ? bindings.gatewayPurposes
+          .filter((entry) => entry && typeof entry === "object" && typeof entry.purpose === "string")
+          .map((entry) => ({ purpose: entry.purpose, route: normRoute(entry.route) }))
+      : [],
+  };
+
+  const gw = c.gateway && typeof c.gateway === "object" ? c.gateway : {};
+  canonical.gateway = {
+    enabled: gw.enabled === true,
+    port: Number.isInteger(gw.port) && gw.port >= 1 && gw.port <= 65535 ? gw.port : 17890,
+    dedicatedPurposePorts: gw.dedicatedPurposePorts === true,
+    purposes: Array.isArray(gw.purposes) ? gw.purposes.filter((x) => typeof x === "string") : [],
+  };
+  return canonical;
+}
+
+/** canonical 序列化（JSON 美化）。 */
+export function serializeCanonical(canonical) {
+  return JSON.stringify(canonical, null, 2);
+}
+
+/** 公开快照：仅 profile ids 与脱敏端点；凭据值永不出现（hasUsername/hasPassword）。 */
+export function publicSnapshot(canonical) {
+  const c = canonical;
+  return {
+    version: c.version,
+    profiles: c.profiles.map((p) => ({
+      id: p.id,
+      configured: profileConfigured(p),
+      ...(p.protocol ? { protocol: p.protocol } : {}),
+      ...(p.host ? { host: p.host } : {}),
+      ...(p.port !== undefined ? { port: p.port } : {}),
+      hasUsername: Boolean(p.username),
+      hasPassword: Boolean(p.password),
+      noProxy: [...(p.noProxy || [])],
+      timeout: p.timeout,
+    })),
+    bindings: {
+      agent: { ...c.bindings.agent },
+      providers: c.bindings.providers.map((entry) => ({ provider: entry.provider, route: { ...entry.route } })),
+      gateway: c.bindings.gateway ? { ...c.bindings.gateway } : null,
+      gatewayPurposes: c.bindings.gatewayPurposes.map((entry) => ({ purpose: entry.purpose, route: { ...entry.route } })),
+    },
+    gateway: { ...c.gateway },
+  };
+}

package/lib/control.js

@@ -0,0 +1,199 @@
+// lib/control.js — serialized runtime transactions backed by official settings.
+// Participant lifecycle remains prepare -> persist/compensate -> publish -> commit.
+import { validateCanonical, serializeCanonical } from "./config.js";
+
+function safe(fn, ...args) {
+  try {
+    const result = fn?.(...args);
+    return result && typeof result.then === "function" ? result.catch(() => {}) : result;
+  } catch {
+    return undefined;
+  }
+}
+
+export class ControlPlane {
+  /**
+   * @param {object} options
+   * @param {object} options.canonical 已校验的初始 canonical
+   * @param {(next:object, previous:object, capture:(snapshot:object, revision?:number)=>void, expectedSettingsRevision?:number)=>Promise<object|void>} [options.persist] settings-backed write
+   * @param {(previousSection:object, previous:object, failed:object, expectedRevision?:number)=>Promise<void>} [options.compensate] settings-backed rollback
+   * @param {Array<object>} [options.participants] 运行时参与者
+   * @param {{info?:Function, warn?:Function}} [options.logger]
+   */
+  constructor({ canonical, persist, compensate, participants = [], logger = console }) {
+    this.canonical = canonical;
+    this.persist = persist;
+    this.compensate = compensate;
+    this.revision = 0;
+    this.active = true;
+    this.participants = [...participants];
+    this.logger = logger;
+    this.tail = Promise.resolve();
+  }
+
+  addParticipant(participant) {
+    this.participants.push(participant);
+  }
+
+  /** 串行化：任何任务都排在上一任务之后（失败不影响后续入队）。 */
+  enqueue(task) {
+    const run = this.tail.then(task, task);
+    this.tail = run.then(() => undefined, () => undefined);
+    return run;
+  }
+
+  /**
+   * Run one validated runtime transaction. Settings writes happen after all
+   * participants prepare; a later failure is compensated through the same
+   * official settings scope before the error is returned.
+   * @param {object} options
+   * @param {object} options.candidate
+   * @param {boolean} [options.persist=true] write candidate through settings
+   * @param {boolean} [options.compensateOnFailure=false] restore persisted external edit
+   * @param {object} [options.compensation] raw settings user section to restore
+   * @param {number} [options.compensationRevision] raw settings revision expected for compensation
+   * @param {number} [options.expectedSettingsRevision] raw settings revision expected for this transition
+   * @param {(next:object, previous:object, capture:(snapshot:object, revision?:number)=>void, expectedSettingsRevision?:number)=>Promise<object|void>} options.persist
+   */
+  async transition({ candidate, persist = true, compensateOnFailure = false, compensation, compensationRevision, expectedSettingsRevision }) {
+    if (!this.active) throw new Error("proxy control plane has been disposed");
+    const prev = this.canonical;
+    const prevRevision = this.revision;
+    let validated;
+    let persistenceSnapshot = compensation;
+    let persistenceRevision = compensationRevision;
+    const capturePersistenceSnapshot = (snapshot, revision) => {
+      if (snapshot !== undefined) persistenceSnapshot = structuredClone(snapshot);
+      if (Number.isInteger(revision)) persistenceRevision = revision;
+    };
+    const staged = [];
+    let persisted = false;
+    try {
+      validated = validateCanonical(candidate);
+      if (serializeCanonical(validated) === serializeCanonical(prev)) {
+        return { canonical: prev, revision: this.revision, unchanged: true };
+      }
+      for (const p of this.participants) {
+        const s = await p.prepare({ next: validated, prev, kind: "transition" });
+        staged.push({ p, s });
+      }
+      if (persist) {
+        if (typeof this.persist !== "function") {
+          const error = new Error("proxy-routing settings persistence is unavailable");
+          error.code = "SETTINGS_UNAVAILABLE";
+          throw error;
+        }
+        persisted = true;
+        let returnedSnapshot;
+        try {
+          returnedSnapshot = await this.persist(validated, prev, capturePersistenceSnapshot, expectedSettingsRevision);
+        } catch (error) {
+          if (error?.settingsPersisted === false) persisted = false;
+          if (Number.isInteger(error?.settingsRevision)) persistenceRevision = error.settingsRevision;
+          throw error;
+        }
+        if (returnedSnapshot && typeof returnedSnapshot === "object"
+          && Object.prototype.hasOwnProperty.call(returnedSnapshot, "compensation")) {
+          persistenceSnapshot = structuredClone(returnedSnapshot.compensation);
+          if (Number.isInteger(returnedSnapshot.revision)) persistenceRevision = returnedSnapshot.revision;
+        } else if (returnedSnapshot !== undefined) {
+          persistenceSnapshot = returnedSnapshot;
+        }
+      }
+      this.canonical = validated;
+      this.revision += 1;
+      for (const { p, s } of staged) await p.commit(s); // 设计上不得抛错
+      for (const { p, s } of staged) await safe(p.finalize, s, { superseded: false });
+      return { canonical: validated, revision: this.revision };
+    } catch (error) {
+      for (const { p, s } of staged) await safe(p.rollback, s);
+      let compensationFailure;
+      if (persisted || compensateOnFailure) {
+        if (typeof this.compensate !== "function") {
+          this.logger.warn?.("[proxy-routing] settings compensation is unavailable");
+          compensationFailure = new Error("Failed to switch proxy configuration; persisted rollback was incomplete");
+          compensationFailure.code = "PROXY_SETTINGS_COMPENSATION_FAILED";
+        } else {
+          try {
+            await this.compensate(persistenceSnapshot ?? prev, prev, validated, persistenceRevision);
+          } catch (compensationError) {
+            this.logger.warn?.("[proxy-routing] 配置回滚不完整：未能恢复 settings namespace");
+            compensationFailure = new Error("Failed to switch proxy configuration; persisted rollback was incomplete");
+            compensationFailure.code = "PROXY_SETTINGS_COMPENSATION_FAILED";
+            compensationFailure.cause = compensationError;
+          }
+        }
+      }
+      this.canonical = prev;
+      this.revision = prevRevision;
+      if (compensationFailure) throw compensationFailure;
+      throw error;
+    }
+  }
+
+  /**
+   * 工具/Web 写路径：CAS + 可持久化。
+   * @param {object} options
+   * @param {number} [options.expectedRevision] runtime revision for the current control plane
+   * @param {number} [options.expectedSettingsRevision] raw settings revision for the persistence CAS
+   * @param {(canonical:object)=>object} options.apply returns a candidate canonical (or throws validation error)
+   * @param {boolean} [options.persist=true] 是否写文件
+   */
+  mutate({ expectedRevision, expectedSettingsRevision, apply, persist = true }) {
+    if (this.disposing || !this.active) {
+      return Promise.reject(new Error("proxy control plane has been disposed"));
+    }
+    return this.enqueue(async () => {
+      if (!this.active) throw new Error("proxy control plane has been disposed");
+      if (expectedRevision !== undefined && expectedRevision !== this.revision) {
+        throw new Error(`stale revision: expected ${expectedRevision}, current ${this.revision}`);
+      }
+      const candidate = validateCanonical(apply(this.canonical));
+      return this.transition({ candidate, persist, expectedSettingsRevision });
+    });
+  }
+
+  /** External settings update: the provider already persisted it; apply once. */
+  reloadSettings({ next, previous, previousRaw, previousRawRevision }) {
+    if (this.disposing || !this.active) {
+      return Promise.reject(new Error("proxy control plane has been disposed"));
+    }
+    return this.enqueue(async () => {
+      if (!this.active) throw new Error("proxy control plane has been disposed");
+      try {
+        return await this.transition({
+          candidate: next,
+          persist: false,
+          compensateOnFailure: true,
+          compensation: previousRaw,
+          compensationRevision: previousRawRevision,
+        });
+      } catch (error) {
+        // The raw previous section is used for compensation; the resolved
+        // previous value remains a diagnostic fallback for lightweight callers.
+        if (previous && serializeCanonical(previous) !== serializeCanonical(this.canonical)) {
+          this.logger.warn?.("[proxy-routing] settings watcher previous value differs from runtime snapshot");
+        }
+        throw error;
+      }
+    });
+  }
+
+  /** 异步销毁：拒绝新变更 → 排空队列 → 参与者 dispose（幂等）。 */
+  async dispose() {
+    if (this.disposing || !this.active) return;
+    this.disposing = true;
+    await this.tail.catch(() => {});
+    this.active = false;
+    for (const p of this.participants) await safe(p.dispose);
+    this.participants = [];
+  }
+
+  status() {
+    return {
+      active: this.active,
+      revision: this.revision,
+      participants: this.participants.map((p) => p.name).filter(Boolean),
+    };
+  }
+}

package/lib/discovery.js

@@ -0,0 +1,89 @@
+// Local proxy discovery for first-use onboarding.
+// Discovery is deliberately bounded: environment proxy URLs plus a small set
+// of loopback ports. It reports candidates only; it never persists or enables.
+import { URL } from "node:url";
+import { probeProxy } from "./probe.js";
+
+export const DEFAULT_DISCOVERY_PORTS = [7890, 7897, 1080, 10808, 10809];
+const PROXY_ENV_KEYS = [
+  "HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy",
+];
+
+function endpointKey(endpoint) {
+  return `${endpoint.protocol}://${endpoint.host}:${endpoint.port}`;
+}
+
+function parseProxyUrl(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") return undefined;
+  try {
+    const url = new URL(raw.trim());
+    const protocol = url.protocol.replace(":", "").toLowerCase();
+    if (protocol !== "http" && protocol !== "socks5") return undefined;
+    const port = Number(url.port || (protocol === "http" ? 80 : 1080));
+    if (!Number.isInteger(port) || port < 1 || port > 65535 || url.hostname === "") return undefined;
+    return {
+      protocol,
+      host: url.hostname,
+      port,
+      ...(url.username ? { username: decodeURIComponent(url.username) } : {}),
+      ...(url.password ? { password: decodeURIComponent(url.password) } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function envCandidates(env) {
+  const candidates = [];
+  for (const key of PROXY_ENV_KEYS) {
+    const endpoint = parseProxyUrl(env?.[key]);
+    if (endpoint) candidates.push({ endpoint, source: `env:${key}` });
+  }
+  return candidates;
+}
+
+/**
+ * Probe bounded candidates in parallel. Credentials stay inside the probe call
+ * and are never returned to callers.
+ * @param {{target?: string, timeout?: number, ports?: number[], env?: object, signal?: AbortSignal}} options
+ */
+export async function discoverProxies({
+  target,
+  timeout = 1500,
+  ports = DEFAULT_DISCOVERY_PORTS,
+  env = process.env,
+  signal,
+} = {}) {
+  const candidates = envCandidates(env);
+  const seen = new Set(candidates.map(({ endpoint }) => endpointKey(endpoint)));
+  for (const rawPort of ports) {
+    if (!Number.isInteger(rawPort) || rawPort < 1 || rawPort > 65535) continue;
+    for (const protocol of ["http", "socks5"]) {
+      const endpoint = { protocol, host: "127.0.0.1", port: rawPort };
+      const key = endpointKey(endpoint);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      candidates.push({ endpoint, source: "loopback-common-port" });
+    }
+  }
+
+  const results = await Promise.all(candidates.map(async ({ endpoint, source }) => {
+    const result = await probeProxy(endpoint, { target, timeout, signal });
+    return {
+      source,
+      protocol: endpoint.protocol,
+      host: endpoint.host,
+      port: endpoint.port,
+      ok: result.ok,
+      connectMs: result.connectMs,
+      totalMs: result.totalMs,
+      ...(result.httpStatus >= 0 ? { httpStatus: result.httpStatus } : {}),
+      ...(result.error ? { error: result.error } : {}),
+    };
+  }));
+  return {
+    scanned: results.length,
+    candidates: results.filter((result) => result.ok),
+    results,
+  };
+}

package/lib/fetch-router.js

@@ -0,0 +1,77 @@
+// lib/fetch-router.js — 唯一稳定的全局 fetch 路由器。
+// 进程级 symbol registry 保证跨重载不递归包装；owner 注册路由解析器，
+// 卸载只移除本 owner；最后一个 owner 仅在 globalThis.fetch 仍是本 wrapper
+// 时恢复先前 fetch（不覆盖后来者安装的外部 wrapper）。
+import { proxiedFetch } from "./proxy/request.js";
+import { providerStore } from "./als.js";
+
+const FETCH_REGISTRY = Symbol.for("dsh-proxy-routing.fetch-registry");
+
+function registry() {
+  let reg = globalThis[FETCH_REGISTRY];
+  if (!reg) {
+    reg = { owners: new Map(), wrapped: false, previousFetch: undefined, wrapper: undefined };
+    Object.defineProperty(globalThis, FETCH_REGISTRY, { value: reg, configurable: true, writable: true });
+  }
+  return reg;
+}
+
+function dispatch(reg, input, init) {
+  const ctx = providerStore.getStore();
+  let route;
+  if (ctx && ctx.route) {
+    route = ctx.route; // provider 上下文：不可变快照
+  } else {
+    const last = [...reg.owners.values()].at(-1);
+    route = last ? last.getAgentRoute() : Object.freeze({ kind: "direct" });
+  }
+  if (route.kind === "direct") return reg.previousFetch(input, init);
+  return proxiedFetch(input, init, route.profile, reg.previousFetch);
+}
+
+export class FetchRouter {
+  /** @param {{getAgentRoute:()=>object}} deps 返回当前 Agent 路由快照（读取时原子） */
+  constructor({ getAgentRoute }) {
+    this.name = "fetch-router";
+    this.token = Symbol("fetch-router-owner");
+    this.getAgentRoute = getAgentRoute;
+  }
+
+  install() {
+    const reg = registry();
+    if (reg.owners.has(this.token)) return;
+    reg.owners.set(this.token, { getAgentRoute: this.getAgentRoute });
+    if (!reg.wrapped) {
+      reg.wrapped = true;
+      reg.previousFetch = globalThis.fetch;
+      reg.wrapper = (input, init) => dispatch(reg, input, init);
+      globalThis.fetch = reg.wrapper;
+    }
+  }
+
+  uninstall() {
+    const reg = registry();
+    reg.owners.delete(this.token);
+    if (reg.owners.size === 0 && reg.wrapped && globalThis.fetch === reg.wrapper) {
+      globalThis.fetch = reg.previousFetch;
+      reg.wrapped = false;
+      reg.previousFetch = undefined;
+      reg.wrapper = undefined;
+    }
+  }
+
+  ownerCount() {
+    return registry().owners.size;
+  }
+
+  owned() {
+    return registry().wrapped;
+  }
+
+  // ControlPlane 参与者协议：路由在派发时读取，无需预取资源。
+  prepare() { return {}; }
+  commit() {}
+  finalize() {}
+  rollback() {}
+  dispose() { this.uninstall(); }
+}