dsh-proxy-routing 0.4.1

package/lib/proxy/stream.js

@@ -0,0 +1,179 @@
+// lib/proxy/stream.js — ByteStream：socket 单泵字节流 + 行/精确字节的 pull 解析
+//
+// 关键不变量：socket 上只挂一套 data/end/error 监听，数据进入内部队列，
+// 解析方用 `readLine()` / `readExactly(n)` 按需拉取；不足时挂起等待。
+// 超时语义：空闲超时（每次收到数据重置），而非一次性绝对生命周期——
+// 大下载只要持续有数据就不会被误杀。
+// 背压：内部缓冲超过高水位时 pause socket，消耗到低水位以下再 resume。
+import { proxyError } from "./errors.js";
+
+/** 单行头上限 64KB；超过视为畸形响应。 */
+export const MAX_LINE = 64 * 1024;
+/** 内部缓冲高水位（超过则 pause socket）。 */
+export const HIGH_WATER = 1024 * 1024;
+/** 低水位（缓冲降到该值以下 resume）。 */
+export const LOW_WATER = HIGH_WATER / 2;
+
+export class ByteStream {
+  /**
+   * @param {import("node:net").Socket} sock
+   * @param {{idleMs?:number, maxBuffered?:number}|number} [opts] number 兼容旧签名（视为 idleMs）
+   */
+  constructor(sock, opts = {}) {
+    const options = typeof opts === "number" ? { idleMs: opts } : opts;
+    this.sock = sock;
+    this.buf = Buffer.alloc(0);
+    this.waiters = []; // [{ type:'line'|'bytes'|'data', n?, resolve, reject }]
+    this.ended = false;
+    this.error = null;
+    this.detached = false;
+    this.idleMs = options.idleMs ?? 0;
+    this.maxBuffered = options.maxBuffered ?? HIGH_WATER;
+    this.paused = false;
+
+    sock.on("data", (d) => this._push(d));
+    sock.on("end", () => this._finish());
+    sock.on("error", (e) => this._fail(e));
+    this._armTimer();
+  }
+
+  _armTimer() {
+    this._clearTimer();
+    if (this.idleMs > 0 && !this.detached && !this.ended) {
+      this.timer = setTimeout(() => {
+        this.timer = null;
+        this._fail(proxyError("ETIMEOUT", "proxy read idle timeout"));
+      }, this.idleMs);
+      this.timer.unref?.();
+    }
+  }
+
+  _push(d) {
+    if (this.detached) return;
+    this.buf = this.buf.length === 0 ? d : Buffer.concat([this.buf, d]);
+    this._armTimer();
+    // 背压：超过高水位暂停 socket 输入
+    if (!this.paused && this.buf.length > this.maxBuffered) {
+      this.paused = true;
+      try { this.sock.pause(); } catch {}
+    }
+    this._drain();
+  }
+
+  _finish() {
+    if (this.detached) return;
+    this.ended = true;
+    this._clearTimer();
+    this._drain();
+  }
+
+  _fail(e) {
+    if (this.detached) return;
+    this.error = e;
+    this.ended = true;
+    this._clearTimer();
+    this._drain();
+  }
+
+  _clearTimer() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  _maybeResume() {
+    if (this.paused && this.buf.length <= LOW_WATER) {
+      this.paused = false;
+      try { this.sock.resume(); } catch {}
+    }
+  }
+
+  _drain() {
+    while (this.waiters.length > 0) {
+      const w = this.waiters[0];
+      if (w.type === "data") {
+        if (this.buf.length > 0) {
+          this.waiters.shift();
+          const out = this.buf;
+          this.buf = Buffer.alloc(0);
+          this._maybeResume();
+          w.resolve(out);
+        } else if (this.ended) {
+          this.waiters.shift();
+          if (this.error) w.reject(this.error);
+          else w.resolve(null);
+        } else return;
+      } else if (w.type === "line") {
+        const idx = this.buf.indexOf(0x0a); // '\n'
+        if (idx === -1) {
+          if (this.buf.length > MAX_LINE) {
+            this.waiters.shift();
+            w.reject(proxyError("ELINE", "response header line too long"));
+          } else if (this.ended) {
+            this.waiters.shift();
+            w.reject(this.error ?? proxyError("EEOF", "connection closed before line terminator"));
+          } else return;
+        } else {
+          this.waiters.shift();
+          let line = this.buf.subarray(0, idx);
+          this.buf = this.buf.subarray(idx + 1);
+          if (line.length > 0 && line[line.length - 1] === 0x0d) line = line.subarray(0, line.length - 1); // 剥 \r
+          this._maybeResume();
+          w.resolve(line.toString("latin1"));
+        }
+      } else {
+        if (this.buf.length >= w.n) {
+          this.waiters.shift();
+          const out = this.buf.subarray(0, w.n);
+          this.buf = this.buf.subarray(w.n);
+          this._maybeResume();
+          w.resolve(out);
+        } else if (this.ended) {
+          this.waiters.shift();
+          w.reject(this.error ?? proxyError("EEOF", `connection closed before ${w.n} bytes were available`));
+        } else return;
+      }
+    }
+  }
+
+  /** 读取一行（不含换行符；\r\n 与 \n 均可）。 */
+  readLine() {
+    return new Promise((resolve, reject) => {
+      this.waiters.push({ type: "line", resolve, reject });
+      this._drain();
+    });
+  }
+
+  /** 精确读取 n 字节。 */
+  readExactly(n) {
+    return new Promise((resolve, reject) => {
+      this.waiters.push({ type: "bytes", n, resolve, reject });
+      this._drain();
+    });
+  }
+
+  /** 取下一段可用数据（可能小于请求量）；流结束返回 null。 */
+  nextData() {
+    return new Promise((resolve, reject) => {
+      this.waiters.push({ type: "data", resolve, reject });
+      this._drain();
+    });
+  }
+
+  /** 取走内部剩余缓冲（供调用方回灌 socket，如 CONNECT 早字节）。 */
+  takeBuf() {
+    const out = this.buf;
+    this.buf = Buffer.alloc(0);
+    return out;
+  }
+
+  /** 停止接收后续数据（socket 仍归调用方管理）。 */
+  detach() {
+    this.detached = true;
+    this._clearTimer();
+    for (const w of this.waiters.splice(0)) {
+      w.reject(proxyError("EDETACHED", "stream detached"));
+    }
+  }
+}

package/lib/proxy-env.js

@@ -0,0 +1,173 @@
+// lib/proxy-env.js — standard proxy environment ownership for future child processes
+
+const PROXY_KEYS = [
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "ALL_PROXY",
+  "NO_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "all_proxy",
+  "no_proxy",
+];
+
+const URL_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy"];
+const NO_PROXY_KEYS = ["NO_PROXY", "no_proxy"];
+const LOCAL_BYPASS = ["127.0.0.1", "localhost", "::1"];
+
+export const PROXY_ENV_KEYS = Object.freeze([...PROXY_KEYS]);
+export const SUBPROCESS_INHERITANCE_NOTE = "仅后续新启动的普通 Bash/下载进程继承；已运行后台任务和 persistent bash 保留旧环境，需重启或重置后生效";
+
+function hasOwn(env, key) {
+  return Object.prototype.hasOwnProperty.call(env, key);
+}
+
+function capture(env) {
+  const values = {};
+  for (const key of PROXY_KEYS) {
+    values[key] = hasOwn(env, key)
+      ? { present: true, value: env[key] }
+      : { present: false, value: undefined };
+  }
+  return values;
+}
+
+function cloneSnapshot(snapshot) {
+  if (!snapshot) return null;
+  return Object.fromEntries(PROXY_KEYS.map((key) => [key, { ...snapshot[key] }]));
+}
+
+function restoreValues(env, values) {
+  for (const key of PROXY_KEYS) {
+    const entry = values[key];
+    if (entry.present) env[key] = entry.value;
+    else delete env[key];
+  }
+}
+
+function applyValues(env, values) {
+  const before = capture(env);
+  try {
+    restoreValues(env, values);
+  } catch {
+    try {
+      restoreValues(env, before);
+    } catch {
+      throw new Error("Failed to update subprocess proxy environment; rollback was incomplete");
+    }
+    throw new Error("Failed to update subprocess proxy environment; previous state was restored");
+  }
+}
+
+function bracketHost(host) {
+  const value = String(host || "127.0.0.1");
+  return value.includes(":") && !value.startsWith("[") ? `[${value}]` : value;
+}
+
+export function proxyUrl(cfg, { includeAuth = true } = {}) {
+  const scheme = cfg.protocol === "socks5" ? "socks5" : "http";
+  const url = new URL(`${scheme}://${bracketHost(cfg.host)}:${cfg.port || 7890}`);
+  if (includeAuth) {
+    if (cfg.username) url.username = cfg.username;
+    if (cfg.password) url.password = cfg.password;
+  }
+  return url.href;
+}
+
+export function mergeNoProxy(original, configured = []) {
+  const merged = [];
+  const seen = new Set();
+  const add = (raw) => {
+    for (const part of String(raw ?? "").split(",")) {
+      const value = part.trim();
+      const key = value.toLowerCase();
+      if (!value || seen.has(key)) continue;
+      seen.add(key);
+      merged.push(value);
+    }
+  };
+
+  for (const key of NO_PROXY_KEYS) {
+    const entry = original?.[key];
+    if (entry?.present) add(entry.value);
+  }
+  for (const value of configured) add(value);
+  for (const value of LOCAL_BYPASS) add(value);
+  return merged;
+}
+
+/** mergeNoProxy 的原始 env 形态便捷入口（key → string，非 snapshot 条目）。 */
+export function mergeNoProxyEnv(env = {}, configured = []) {
+  const entries = {};
+  for (const key of NO_PROXY_KEYS) {
+    entries[key] = { present: hasOwn(env, key), value: env[key] };
+  }
+  return mergeNoProxy(entries, configured);
+}
+
+function desiredValues(cfg, original) {
+  const url = proxyUrl(cfg);
+  const noProxy = mergeNoProxy(original, Array.isArray(cfg.noProxy) ? cfg.noProxy : []);
+  const values = {};
+  for (const key of URL_KEYS) values[key] = { present: true, value: url };
+  for (const key of NO_PROXY_KEYS) values[key] = { present: true, value: noProxy.join(",") };
+  return { values, noProxy };
+}
+
+export class ProxyEnvironmentController {
+  constructor(env = process.env) {
+    this.env = env;
+    this.original = null;
+    this.active = false;
+    this.currentProxyUrl = "";
+    this.currentNoProxy = [];
+  }
+
+  checkpoint() {
+    return {
+      values: capture(this.env),
+      original: cloneSnapshot(this.original),
+      active: this.active,
+      currentProxyUrl: this.currentProxyUrl,
+      currentNoProxy: [...this.currentNoProxy],
+    };
+  }
+
+  restoreCheckpoint(checkpoint) {
+    applyValues(this.env, checkpoint.values);
+    this.original = cloneSnapshot(checkpoint.original);
+    this.active = checkpoint.active;
+    this.currentProxyUrl = checkpoint.currentProxyUrl;
+    this.currentNoProxy = [...checkpoint.currentNoProxy];
+  }
+
+  enable(cfg) {
+    const original = this.active ? this.original : capture(this.env);
+    const desired = desiredValues(cfg, original);
+    applyValues(this.env, desired.values);
+    this.original = original;
+    this.active = true;
+    this.currentProxyUrl = proxyUrl(cfg, { includeAuth: false });
+    this.currentNoProxy = desired.noProxy;
+    return this.status();
+  }
+
+  disable() {
+    if (!this.active) return this.status();
+    applyValues(this.env, this.original);
+    this.original = null;
+    this.active = false;
+    this.currentProxyUrl = "";
+    this.currentNoProxy = [];
+    return this.status();
+  }
+
+  status() {
+    return {
+      enabled: this.active,
+      proxyUrl: this.currentProxyUrl,
+      noProxy: [...this.currentNoProxy],
+      inheritance: SUBPROCESS_INHERITANCE_NOTE,
+    };
+  }
+}

package/lib/routes.js

@@ -0,0 +1,75 @@
+// lib/routes.js — 路由解析：把 canonical bindings 解析为深冻结的
+// `direct` / `profile` 路由快照。provider 覆盖缺失时继承 Agent 路由；
+// 显式 direct 永不随 Agent 路由变化而继承。快照不可变，供 fetch/shell 路由使用。
+import { DEFAULT_PROFILE_ID, profileConfigured, UNCONFIGURED_GUIDANCE } from "./config.js";
+
+export function deepFreeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    for (const key of Object.keys(value)) deepFreeze(value[key]);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+function routeError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/** 把一条 binding route 物化为不可变快照；profile 快照内嵌脱敏前完整 profile（含凭据，仅内部使用）。 */
+export function routeSnapshot(canonical, route) {
+  if (!route || route.kind === "direct") return Object.freeze({ kind: "direct" });
+  if (route.kind !== "profile") throw routeError("INVALID_ROUTE", `unknown route kind: ${JSON.stringify(route.kind)}`);
+  const profile = canonical.profiles.find((p) => p.id === route.profileId);
+  if (!profile) throw routeError("MISSING_PROFILE", `profile route references missing profile "${route.profileId}"`);
+  if (!profileConfigured(profile)) throw routeError("UNCONFIGURED_PROFILE", UNCONFIGURED_GUIDANCE);
+  return deepFreeze({
+    kind: "profile",
+    profileId: profile.id,
+    profile: {
+      protocol: profile.protocol,
+      host: profile.host,
+      port: profile.port,
+      username: profile.username || undefined,
+      password: profile.password || undefined,
+      noProxy: [...(profile.noProxy || [])],
+      timeout: profile.timeout,
+    },
+  });
+}
+
+/** Agent 路由快照。 */
+export function resolveAgentRoute(canonical) {
+  return routeSnapshot(canonical, canonical.bindings.agent);
+}
+
+/** Provider 路由快照：有显式覆盖用覆盖（多条取最后一条），否则继承 Agent。 */
+export function resolveProviderRoute(canonical, providerId) {
+  if (typeof providerId !== "string") return resolveAgentRoute(canonical);
+  let override = null;
+  for (const entry of canonical.bindings.providers) {
+    if (entry.provider === providerId) override = entry.route;
+  }
+  if (override) return routeSnapshot(canonical, override);
+  return resolveAgentRoute(canonical);
+}
+
+/** Gateway 路由快照：null 绑定继承 Agent。 */
+export function resolveGatewayRoute(canonical) {
+  if (canonical.bindings.gateway == null) return resolveAgentRoute(canonical);
+  return routeSnapshot(canonical, canonical.bindings.gateway);
+}
+
+/** Purpose 路由快照：缺失 purpose 绑定继承 gateway（gateway 又继承 Agent）。 */
+export function resolvePurposeRoute(canonical, purposeId) {
+  if (typeof purposeId === "string") {
+    for (const entry of canonical.bindings.gatewayPurposes) {
+      if (entry.purpose === purposeId) return routeSnapshot(canonical, entry.route);
+    }
+  }
+  return resolveGatewayRoute(canonical);
+}
+
+/** 便捷：默认 profile id（契约锚点）。 */
+export { DEFAULT_PROFILE_ID };

package/lib/rpc.js

@@ -0,0 +1,110 @@
+// lib/rpc.js — loopback Connection RPC for the browser Settings diagnostics.
+import { discoverProxies } from "./discovery.js";
+
+const CHANNEL = "/proxy-agent";
+const DEFAULT_TIMEOUT = 1500;
+const MAX_HOST_LENGTH = 255;
+
+function failure(code, message, details = {}) {
+  return { ok: false, error: { code, message, details } };
+}
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function endpointOf(value) {
+  if (!isObject(value)) throw new Error("proxy endpoint must be an object");
+  if (value.protocol !== "http" && value.protocol !== "socks5") throw new Error("protocol must be http or socks5");
+  if (typeof value.host !== "string" || value.host.trim() === "" || value.host.length > MAX_HOST_LENGTH) throw new Error("host must be a non-empty string");
+  if (!Number.isInteger(value.port) || value.port < 1 || value.port > 65535) throw new Error("port must be an integer between 1 and 65535");
+  return { protocol: value.protocol, host: value.host.trim(), port: value.port };
+}
+
+function publicProbe(result) {
+  return {
+    ok: result.ok,
+    connectMs: result.connectMs,
+    totalMs: result.totalMs,
+    httpStatus: result.httpStatus,
+    ...(result.error ? { error: String(result.error).replace(/https?:\/\/[^\s]+/gi, "target") } : {}),
+  };
+}
+
+function mutationOf(value) {
+  if (!isObject(value)) throw new Error("proxy mutation must be an object")
+  const hasEndpoint = Object.prototype.hasOwnProperty.call(value, "endpoint")
+  const hasAgent = Object.prototype.hasOwnProperty.call(value, "agent")
+  if (!hasEndpoint && !hasAgent) throw new Error("proxy mutation must include endpoint or agent")
+  const result = {}
+  if (hasEndpoint) result.endpoint = endpointOf(value.endpoint)
+  if (hasAgent) {
+    if (!isObject(value.agent)) throw new Error("agent route must be an object")
+    if (value.agent.kind === "direct") result.agent = { kind: "direct" }
+    else if (value.agent.kind === "profile" && value.agent.profileId === "default") result.agent = { kind: "profile", profileId: "default" }
+    else throw new Error("agent route must be direct or the default profile")
+  }
+  if (value.expectedRevision !== undefined
+    && (!Number.isInteger(value.expectedRevision) || value.expectedRevision < 0)) {
+    throw new Error("expectedRevision must be a non-negative integer")
+  }
+  result.expectedRevision = value.expectedRevision
+  return result
+}
+
+function applyMutation(canonical, mutation) {
+  const next = structuredClone(canonical)
+  if (mutation.endpoint !== undefined) {
+    const index = next.profiles.findIndex((profile) => profile.id === "default")
+    if (index < 0) throw new Error("default proxy profile is unavailable")
+    next.profiles[index] = { ...next.profiles[index], ...mutation.endpoint }
+  }
+  if (mutation.agent !== undefined) next.bindings = { ...next.bindings, agent: mutation.agent }
+  return next
+}
+
+async function dispatch(control, endpoint, payload, signal) {
+  if (endpoint === "discover") {
+    if (payload !== undefined && (!isObject(payload) || Object.keys(payload).length !== 0)) throw new Error("discover accepts an empty payload");
+    const found = await discoverProxies({ timeout: DEFAULT_TIMEOUT, signal });
+    return {
+      scanned: found.scanned,
+      candidates: found.candidates,
+    };
+  }
+  if (endpoint === "probe") {
+    const proxy = endpointOf(payload);
+    return publicProbe(await control.probe(proxy, { signal }));
+  }
+  if (endpoint === "mutate") {
+    const mutation = mutationOf(payload)
+    const result = await control.mutate({
+      expectedSettingsRevision: mutation.expectedRevision,
+      apply: (canonical) => applyMutation(canonical, mutation),
+    })
+    const settingsRevision = control.getSettingsRevision?.()
+    return {
+      runtimeRevision: result.revision,
+      ...(Number.isInteger(settingsRevision) ? { settingsRevision } : {}),
+    }
+  }
+  throw Object.assign(new Error(`unknown proxy endpoint: ${endpoint}`), { code: "UNKNOWN_ENDPOINT" });
+}
+
+/** Register the browser diagnostics channel only when Web Connection exists. */
+export function installProxyRpc(ctx, control) {
+  if (typeof ctx.inject !== "function") return;
+  ctx.inject(["connection"], (connectionCtx) => {
+    connectionCtx.connection.rpc.handle(CHANNEL, async (endpoint, payload, signal) => {
+      try {
+        return { ok: true, value: await dispatch(control, endpoint, payload, signal) };
+      } catch (error) {
+        if (error?.name === "AbortError" || error?.code === "ABORT_ERR") return failure("cancelled", "proxy diagnostic was cancelled");
+        if (error?.code === "UNKNOWN_ENDPOINT") return failure("not-found", "proxy diagnostic endpoint was not found");
+        return failure("bad-request", error instanceof Error ? error.message : String(error));
+      }
+    }, { authority: "loopback" });
+  });
+}
+
+export const PROXY_RPC_CHANNEL = CHANNEL;

package/lib/settings.js

@@ -0,0 +1,60 @@
+// lib/settings.js — official DSH settings seam for the proxy-routing namespace.
+import z from "@deepseek-ai/schemastery";
+import { settingsNamespace } from "@deepseek-ai/dsh-settings";
+import { canonicalDefaults } from "./config.js";
+
+export const PROXY_ROUTING_NAMESPACE = settingsNamespace("proxy-routing");
+
+const RouteSchema = z.object({
+  kind: z.union(["direct", "profile"]).default("direct"),
+  profileId: z.string(),
+});
+
+const ProfileSchema = z.object({
+  id: z.string().default("default"),
+  protocol: z.union(["http", "socks5"]),
+  host: z.string(),
+  port: z.natural().min(1).max(65535),
+  username: z.string().role("secret"),
+  password: z.string().role("secret"),
+  noProxy: z.array(z.string()).default(["127.0.0.1", "localhost", "::1", "api.deepseek.com"]),
+  timeout: z.natural().min(1000).max(600000).default(60000),
+});
+
+const ProviderRouteSchema = z.object({
+  provider: z.string(),
+  route: RouteSchema.default({ kind: "direct" }),
+});
+
+const GatewaySchema = z.object({
+  enabled: z.boolean().default(false),
+  port: z.natural().min(1).max(65535).default(17890),
+  dedicatedPurposePorts: z.boolean().default(false),
+  purposes: z.array(z.string()).default([]),
+});
+
+/** Canonical v2 schema registered under the DSH settings namespace. */
+export const ProxyRoutingSettingsSchema = z.object({
+  version: z.natural().default(2),
+  profiles: z.array(ProfileSchema).default(canonicalDefaults().profiles),
+  bindings: z.object({
+    agent: RouteSchema.default({ kind: "direct" }),
+    providers: z.array(ProviderRouteSchema).default([]),
+    gateway: z.union([RouteSchema, z.const(null)]).default(null),
+    gatewayPurposes: z.array(z.object({
+      purpose: z.string(),
+      route: RouteSchema.default({ kind: "direct" }),
+    })).default([]),
+  }).default(canonicalDefaults().bindings),
+  gateway: GatewaySchema.default(canonicalDefaults().gateway),
+}).default(canonicalDefaults());
+
+/** Stable error for compositions that omit the official settings provider. */
+export function settingsUnavailableError() {
+  const error = new Error(
+    "dsh-proxy-routing requires the DSH settings service; "
+    + "enable @deepseek-ai/dsh-settings-file in the profile first",
+  );
+  error.code = "SETTINGS_UNAVAILABLE";
+  return error;
+}