dsh-flash-proxy 0.0.0-stage → 0.1.4

package/dist/index.js

@@ -0,0 +1,714 @@
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+// Default export only (export default Schema); there is no named Schema.
+import Schema from '@deepseek-ai/schemastery';
+export const name = 'dsh-flash-proxy';
+// No host-side hard dependencies; all services are injected lazily.
+export const inject = [];
+// ── Constants ─────────────────────────────────────────────────────────────
+const DEFAULT_MODE = 'all-proxy';
+const DEFAULT_CUSTOM = '';
+/**
+ * Default test target: the canonical "is there a working network path"
+ * endpoint. Returns an empty 204, so it measures the path and nothing else —
+ * and it is unreachable without a working proxy on networks that need one,
+ * which is exactly the signal the test is meant to produce.
+ */
+const DEFAULT_TEST_URL = 'https://www.google.com/generate_204';
+/** Hard ceiling on a single test; also reported in the diagnostics payload. */
+const TEST_TIMEOUT_MS = 10000;
+/** Redirect hops followed before giving up (the chain is reported either way). */
+const MAX_REDIRECTS = 5;
+/** Bytes of response body echoed back for inspection. */
+const BODY_SNIPPET_LIMIT = 200;
+/** Domains that bypass the proxy when proxyMode is 'api-bypass'. */
+const API_BYPASS_DOMAINS = 'api.deepseek.com,chat.deepseek.com';
+/**
+ * The ctx service DSH publishes with the launch-environment snapshot it
+ * resolved the boot-time proxy policy from. That snapshot merges three layers
+ * (process | project-env | user-env) and structurally satisfies the
+ * EnvLookup this plugin hands back to dsh-http-proxy.
+ */
+const LAUNCH_ENVIRONMENT_SERVICE = 'launchEnvironment';
+/**
+ * The plugin's Config schema — the host's composition defaults, exported so
+ * the Cordis loader publishes it as runtime.Config.
+ *
+ * This is not a cosmetic nicety. dsh-settings resolves a namespace's editable
+ * form from entry.fiber.runtime.Config (its schema(entry) reads exactly
+ * that), so a plugin without an exported Config is NOT configurable by the
+ * native configuration editor — and a client preference write through
+ * settings.update('dsh-flash-proxy', …) is refused with No configurable plugin
+ * entry "dsh-flash-proxy".
+ *
+ * Every field is marked .volatile(): live-editable without plugin restart.
+ * The settings configuration editor only shows volatile fields; ordinary
+ * (non-volatile) config requires a Cordis configuration file edit and a
+ * restart. Since all dsh-flash-proxy settings are user preferences the client
+ * writes through ctx.remote.settings, they must all be volatile.
+ */
+export const Config = Schema.object({
+    proxyEnabled: Schema.boolean().default(true).volatile(),
+    proxyMode: Schema.string().default(DEFAULT_MODE).volatile(),
+    customNoProxy: Schema.string().default(DEFAULT_CUSTOM).volatile(),
+    testUrl: Schema.string().default(DEFAULT_TEST_URL).volatile(),
+    // Keep the old field so legacy clients don't break; migrated on read.
+    useProxy: Schema.boolean().default(true).volatile(),
+});
+/** Map a proxyMode (+ optional customNoProxy) to the actual NO_PROXY value. */
+function resolveNoProxy(mode, custom) {
+    switch (mode) {
+        case 'all-proxy': return undefined; // no bypass → all traffic proxied
+        case 'api-bypass': return API_BYPASS_DOMAINS;
+        case 'all-bypass': return '*';
+        case 'custom': {
+            // The only user-supplied value here. A blank one means "no bypass
+            // entries", i.e. the same routing as all-proxy — so clear the variable
+            // rather than publishing NO_PROXY='', which would leave a set-but-empty
+            // variable in the environment for spawned children to read. (Routing is
+            // identical either way: dsh-http-proxy's parser drops empty entries.)
+            const value = (custom || '').trim();
+            return value === '' ? undefined : value;
+        }
+        default: return undefined;
+    }
+}
+/**
+ * Disposer for the dispatcher this plugin installed.
+ *
+ * installProxyFromEnvironment returns one and restores both the global
+ * dispatcher and the module's policy state. Dropping it — as this code used to
+ * — leaks one ProxyAgent and its whole socket pool per mode change.
+ */
+let _disposeProxyPolicy = null;
+/**
+ * The last (mode, custom) pair this plugin actually applied, joined by a NUL
+ * so ("a","b\0c") cannot collide with ("a\0b","c").
+ *
+ * Two paths can reach applyProxyEnv: the initial startup apply below and the
+ * loader/volatile-update handler after a settings edit. Both are async — each
+ * suspends on await loadProxyModule() *before* it touches
+ * _disposeProxyPolicy — so without a guard the later caller would overwrite
+ * the field and the earlier disposer would be dropped, leaking one ProxyAgent
+ * and its socket pool. The duplicate would also log the pair twice, so the
+ * proxy log could no longer distinguish a real mode switch from startup noise.
+ *
+ * The guard is assigned before the first await on purpose — that is what
+ * makes the second caller in the same tick a no-op — and cleared again on the
+ * paths that do not end in an install, so a transient failure still retries.
+ */
+let _appliedProxyKey = null;
+let _proxyModulePromise = null;
+/**
+ * Load @deepseek-ai/dsh-http-proxy, once, from the instance DSH itself uses.
+ *
+ * Two traps live here, and both previously made the entire proxy feature a
+ * silent no-op:
+ *
+ * 1. require does not exist. This half is ESM, so every require(...) threw
+ *    ReferenceError: require is not defined into a surrounding try/catch —
+ *    which is why the failure only ever surfaced as a stray string in the
+ *    client's diagnostics.
+ * 2. The package is not resolvable from here at all. It ships nested inside the
+ *    DSH installation (<dsh>/node_modules/@deepseek-ai/dsh-http-proxy) and is
+ *    not a dependency of this plugin.
+ *
+ * Resolving it is not merely convenience. The module keeps the resolved policy
+ * in *module-level* state (active/installed) that only
+ * installProxyFromEnvironment writes, and proxyRouteFor reads. A second
+ * copy of the module would therefore answer "direct" for every URL forever,
+ * while also installing a dispatcher that DSH's own proxyRouteFor cannot see.
+ * So: one cached handle, resolved through DSH's own entry point, which is the
+ * exact module instance DSH booted with.
+ */
+function loadProxyModule() {
+    if (_proxyModulePromise)
+        return _proxyModulePromise;
+    _proxyModulePromise = (async () => {
+        // Widened to string on purpose: a literal would make TypeScript try to
+        // resolve a package that is deliberately not a dependency of this plugin.
+        const specifier = '@deepseek-ai/dsh-http-proxy';
+        // Preferred: an ordinary resolution, for any setup that installs it for us.
+        try {
+            return (await import(specifier));
+        }
+        catch (_) { /* fall through to DSH's own copy */ }
+        const entry = process.argv[1];
+        if (!entry) {
+            console.warn('[dsh-flash-proxy] cannot locate the DSH entry point; proxy control unavailable');
+            return null;
+        }
+        try {
+            const resolved = createRequire(entry).resolve(specifier);
+            console.log('[dsh-flash-proxy] dsh-http-proxy resolved to ' + resolved);
+            return (await import(pathToFileURL(resolved).href));
+        }
+        catch (e) {
+            console.warn('[dsh-flash-proxy] could not load ' + specifier + ': ' + (e?.message || e));
+            return null;
+        }
+    })();
+    return _proxyModulePromise;
+}
+/** An EnvLookup over process.env — the fallback when no snapshot is provided. */
+function processEnvLookup() {
+    return {
+        get(name) {
+            const value = process.env[name];
+            return value !== undefined && value !== '' ? { value } : undefined;
+        },
+    };
+}
+/** Send a JSON response with no-store cache control. */
+function sendJson(res, status, payload) {
+    res.statusCode = status;
+    res.setHeader('content-type', 'application/json; charset=utf-8');
+    res.setHeader('cache-control', 'no-store');
+    res.end(JSON.stringify(payload));
+}
+/**
+ * Read an optional JSON request body, bounded so a client cannot feed the
+ * host an unbounded buffer. Returns null for an empty, oversized, or
+ * unparseable body — callers treat that as "no override supplied".
+ */
+async function readJsonBody(req, limit = 4096) {
+    try {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of req) {
+            size += chunk.length;
+            if (size > limit)
+                return null;
+            chunks.push(chunk);
+        }
+        if (chunks.length === 0)
+            return null;
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch (_) {
+        return null;
+    }
+}
+// ── Main plugin entry ─────────────────────────────────────────────────────
+export function apply(ctx, config) {
+    /** The launch-environment snapshot DSH resolved the boot-time policy from. */
+    function launchEnvironment() {
+        try {
+            const svc = ctx.get ? ctx.get(LAUNCH_ENVIRONMENT_SERVICE) : undefined;
+            return svc && typeof svc.get === 'function' ? svc : null;
+        }
+        catch (_) {
+            return null;
+        }
+    }
+    /**
+     * Read a launch-environment variable the way the policy resolved it: the
+     * launch snapshot first (it merges process / project-env / user-env),
+     * process.env as fallback. The proxy variables are the main caller.
+     */
+    function readLaunchEnv(names) {
+        const snapshot = launchEnvironment();
+        for (const name of names) {
+            const fromSnapshot = snapshot ? snapshot.get(name) : undefined;
+            if (fromSnapshot && fromSnapshot.value)
+                return fromSnapshot.value;
+            const raw = process.env[name];
+            if (raw)
+                return raw;
+        }
+        return null;
+    }
+    /**
+     * The per-class proxy variables currently in force, read the same way the
+     * policy does (launch snapshot first, process.env as fallback). Unlike the
+     * single httpProxy field — which reports the *first* value found, mirroring
+     * how undici falls back https→http — this keeps each family's value distinct,
+     * so a UI can list HTTP_PROXY / HTTPS_PROXY / ALL_PROXY verbatim. https
+     * checks HTTPS_PROXY first, then HTTP, matching dsh-http-proxy's fallback;
+     * http and all are reported exactly as found.
+     */
+    function proxyEnvSummary() {
+        return {
+            // HTTPS falls back to the HTTP proxy when no HTTPS_PROXY is set — that is
+            // an undici behaviour (https uses https_proxy, else http_proxy) and the
+            // display should mirror what routing actually does.
+            https: readLaunchEnv(['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy']),
+            http: readLaunchEnv(['HTTP_PROXY', 'http_proxy']),
+            all: readLaunchEnv(['ALL_PROXY', 'all_proxy']),
+        };
+    }
+    /**
+     * Resolve the effective proxy mode.
+     *
+     * The global master switch (proxyEnabled) takes precedence: when it is off,
+     * the proxy is disabled entirely and every request goes direct (all-bypass).
+     * Otherwise the legacy useProxy migration applies — if proxyMode sits at its
+     * default but useProxy was explicitly set, the old boolean takes over.
+     */
+    function resolveMode() {
+        // Global master off → proxy disabled entirely (all direct).
+        const enabled = config.proxyEnabled?.get() !== false;
+        if (!enabled)
+            return 'all-bypass';
+        let mode = config.proxyMode.get() || DEFAULT_MODE;
+        if (!config.proxyMode.get() && typeof config.useProxy?.get() === 'boolean') {
+            mode = config.useProxy.get() ? 'all-proxy' : 'all-bypass';
+        }
+        return mode;
+    }
+    /**
+     * Publish the chosen bypass list and re-install the process-wide dispatcher.
+     *
+     * Writing process.env.NO_PROXY is necessary but nowhere near sufficient:
+     * undici's global dispatcher routes by the ProxyPolicy object it was handed
+     * at install time and never re-reads the environment, so only a re-install
+     * changes actual routing. The environment write exists for the consumers that
+     * *do* read it — spawned children, and node:http's proxyEnv.
+     */
+    async function applyProxyEnv(mode, custom) {
+        // Idempotence guard — see _appliedProxyKey. Set before any await so the
+        // duplicate startup caller is a no-op rather than a racing second install.
+        const key = mode + '\u0000' + custom;
+        if (key === _appliedProxyKey)
+            return;
+        _appliedProxyKey = key;
+        const noProxy = resolveNoProxy(mode, custom);
+        if (noProxy === undefined) {
+            delete process.env.NO_PROXY;
+            delete process.env.no_proxy;
+        }
+        else {
+            process.env.NO_PROXY = noProxy;
+            process.env.no_proxy = noProxy;
+        }
+        console.log('[dsh-flash-proxy] proxy mode=' + mode + ' (NO_PROXY=' + (noProxy ?? '<removed>') + ')');
+        const mod = await loadProxyModule();
+        if (!mod) {
+            _appliedProxyKey = null;
+            console.warn('[dsh-flash-proxy] proxy module unavailable — routing is unchanged (the mode now affects child processes only)');
+            return;
+        }
+        // Base the policy on DSH's own snapshot so that nothing but the bypass list
+        // changes. Resolving from process.env would silently disagree with the
+        // policy DSH installed: its snapshot also merges the project-env and
+        // user-env layers, which process.env knows nothing about.
+        const snapshot = launchEnvironment();
+        const base = snapshot || processEnvLookup();
+        const envLookup = {
+            get(name) {
+                // undici reads the lowercase spelling first, so both are owned here.
+                if (name === 'NO_PROXY' || name === 'no_proxy') {
+                    return noProxy === undefined ? undefined : { value: noProxy };
+                }
+                return base.get(name);
+            },
+        };
+        try {
+            // Release the previous install before taking a new one, otherwise every
+            // mode change stacks another dispatcher on top of the last.
+            if (_disposeProxyPolicy) {
+                try {
+                    await _disposeProxyPolicy();
+                }
+                catch (_) { /* already released */ }
+                _disposeProxyPolicy = null;
+            }
+            _disposeProxyPolicy = await mod.installProxyFromEnvironment(envLookup, (message) => {
+                console.warn('[dsh-flash-proxy] proxy install warning: ' + message);
+            });
+            console.log('[dsh-flash-proxy] undici global dispatcher re-installed (env source=' +
+                (snapshot ? 'launchEnvironment' : 'process.env') + ')');
+        }
+        catch (e) {
+            // Let the next change retry: nothing was installed, so nothing is in force.
+            _appliedProxyKey = null;
+            console.warn('[dsh-flash-proxy] could not re-install proxy dispatcher:', e?.message || e);
+        }
+    }
+    /**
+     * Ask dsh-http-proxy how it would route url.
+     *
+     * proxyRouteFor takes a URL object. Handed a string it does not throw — it
+     * quietly answers "direct", which is how this plugin came to report 直连 for
+     * every request it ever tested.
+     */
+    async function proxyRouteForUrl(url) {
+        const mod = await loadProxyModule();
+        if (!mod)
+            return { proxied: false, error: 'dsh-http-proxy is not loadable from this plugin' };
+        try {
+            return { proxied: mod.proxyRouteFor(new URL(url))?.proxied === true, error: null };
+        }
+        catch (e) {
+            return { proxied: false, error: e?.message || String(e) };
+        }
+    }
+    /**
+     * Resolve the test target.
+     *
+     * An explicit override (from the request body) wins over the stored
+     * setting, so the URL the client is displaying is exactly the URL probed —
+     * no dependency on the settings write having landed first.
+     */
+    function resolveTestUrl(override) {
+        const fromOverride = typeof override === 'string' ? override.trim() : '';
+        const raw = fromOverride || String(config.testUrl.get() || '').trim();
+        return raw || DEFAULT_TEST_URL;
+    }
+    /**
+     * How dsh-http-proxy would route url, plus the env it decides from.
+     *
+     * probeRoute: false is for callers that already rejected the URL: routing is
+     * moot then, and reporting routeError: "Invalid URL" alongside the caller's
+     * own InvalidTestUrl only prints the same message twice.
+     */
+    async function describeProxyRoute(url, probeRoute = true) {
+        const mode = resolveMode();
+        const custom = config.customNoProxy.get() || '';
+        const route = probeRoute
+            ? await proxyRouteForUrl(url)
+            : { proxied: false, error: null };
+        return {
+            mode,
+            // What this plugin published for the current mode: the value that governs
+            // routing once the dispatcher has been re-installed.
+            noProxy: resolveNoProxy(mode, custom) ?? null,
+            httpProxy: readLaunchEnv(['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy']),
+            proxyEnv: proxyEnvSummary(),
+            proxied: route.proxied,
+            routeError: route.error,
+        };
+    }
+    /**
+     * Diagnose outbound connectivity to url.
+     *
+     * Two deliberate choices, both about *diagnosis* rather than connectivity:
+     *
+     * - redirect: 'manual' with a hand-rolled hop loop, so the redirect chain is
+     *   recorded instead of silently followed. "302 to somewhere unreachable" is
+     *   a different failure from "connection refused", and the old single-shot
+     *   redirect: 'follow' made them indistinguishable.
+     * - Never throws. Every failure is returned as data, because the caller has
+     *   to render it either way, and the interesting part (cause.code — e.g.
+     *   ENOTFOUND, UND_ERR_CONNECT_TIMEOUT, DEPTH_ZERO_SELF_SIGNED_CERT)
+     *   only exists on the nested cause of undici's TypeError: fetch failed.
+     */
+    async function runConnectionTest(url) {
+        const started = Date.now();
+        const proxy = await describeProxyRoute(url);
+        const redirects = [];
+        /** Assemble the payload so every exit path reports the same shape. */
+        const report = (extra) => ({
+            url,
+            proxy,
+            timeoutMs: TEST_TIMEOUT_MS,
+            redirects,
+            elapsedMs: Date.now() - started,
+            ...extra,
+        });
+        let current = url;
+        let resp = null;
+        let redirectLimitHit = false;
+        try {
+            for (let hop = 0;; hop++) {
+                resp = await fetch(current, {
+                    method: 'GET',
+                    redirect: 'manual',
+                    signal: AbortSignal.timeout(TEST_TIMEOUT_MS),
+                });
+                const location = resp.headers.get('location');
+                if (!(resp.status >= 300 && resp.status < 400 && location))
+                    break;
+                let next = String(location);
+                try {
+                    next = new URL(next, current).href;
+                }
+                catch (_) { /* keep raw value */ }
+                redirects.push({ hop: hop + 1, from: current, status: resp.status, to: next });
+                if (hop >= MAX_REDIRECTS) {
+                    redirectLimitHit = true;
+                    break;
+                }
+                current = next;
+            }
+        }
+        catch (e) {
+            const cause = e?.cause;
+            return report({
+                ok: false,
+                finalUrl: current,
+                headersMs: Date.now() - started,
+                status: 0,
+                statusText: '',
+                contentType: '',
+                contentLength: null,
+                bodyMs: 0,
+                bodyBytes: 0,
+                bodySnippet: null,
+                redirectLimitHit,
+                error: {
+                    name: e?.name || 'Error',
+                    message: e?.message || String(e),
+                    code: e?.code || null,
+                    causeName: cause?.name || null,
+                    causeMessage: cause?.message || null,
+                    causeCode: cause?.code || null,
+                    causeErrno: cause?.errno ?? null,
+                },
+            });
+        }
+        const headersMs = Date.now() - started;
+        const contentType = resp.headers.get('content-type') || '';
+        const contentLength = resp.headers.get('content-length') || null;
+        // Read the body too, so the timing covers the whole exchange and a proxy's
+        // own "blocked" page can be inspected rather than guessed at.
+        let bodyBytes = 0;
+        let bodySnippet = null;
+        const bodyStart = Date.now();
+        try {
+            const buf = Buffer.from(await resp.arrayBuffer());
+            bodyBytes = buf.byteLength;
+            const textual = !contentType || /text|json|xml|javascript|html/i.test(contentType);
+            if (buf.byteLength > 0 && textual) {
+                bodySnippet = buf.toString('utf8', 0, Math.min(buf.byteLength, BODY_SNIPPET_LIMIT));
+            }
+        }
+        catch (_) { /* body is optional — headers already prove the path */ }
+        const bodyMs = Date.now() - bodyStart;
+        // Any HTTP response means the network path works — 401/404 included. The
+        // status is reported verbatim so the caller can judge it.
+        return report({
+            ok: true,
+            finalUrl: current,
+            headersMs,
+            status: resp.status,
+            statusText: resp.statusText || '',
+            contentType,
+            contentLength,
+            bodyMs,
+            bodyBytes,
+            bodySnippet,
+            redirectLimitHit,
+            error: null,
+        });
+    }
+    // ── Settings registration ──────────────────────────────────────────────
+    // When the settings service is available, register the dsh-flash-proxy
+    // namespace's page policy. Volatile fields in the exported Config schema
+    // are what make this plugin's settings editable without restart —
+    // settings.configure tells the settings UI to show a form for this
+    // instance; it does not register a schema (that is Config's job).
+    ctx.inject(['settings'], (settingsCtx) => {
+        settingsCtx.effect(() => settingsCtx.settings.configure({ auto: false }, ctx.fiber));
+    });
+    // ── Volatile-update handler (proxy paths only) ─────────────────────────
+    // React to volatile config updates in-place. The loader's _commitVolatile()
+    // updates the Volatile<T> references in config and then emits
+    // loader/volatile-update with the paths that changed. This plugin
+    // subscribes to proxy paths only.
+    const relevant = (p) => p.length === 1;
+    ctx.on('loader/volatile-update', (paths) => {
+        const proxyPaths = ['proxyEnabled', 'proxyMode', 'customNoProxy', 'useProxy'];
+        if (!paths.some((p) => relevant(p) && proxyPaths.includes(p[0])))
+            return;
+        try {
+            const mode = resolveMode();
+            applyProxyEnv(mode, config.customNoProxy.get() || '');
+        }
+        catch (e) {
+            console.error('[dsh-flash-proxy] failed to update proxy setting:', e);
+        }
+    });
+    // ── Initial proxy state apply ──────────────────────────────────────────
+    // Apply the initial proxy state immediately
+    try {
+        const mode = resolveMode();
+        applyProxyEnv(mode, config.customNoProxy.get() || '');
+    }
+    catch (_) { }
+    // ── HTTP API routes ────────────────────────────────────────────────────
+    // The webServer type augmentation lives in @deepseek-ai/dsh-host-webserver
+    // which is not a direct dependency; cast through any for the register calls.
+    ctx.inject(['webServer'], (wsCtx) => {
+        // GET /plugins/dsh-flash-proxy/proxy-status
+        // Returns the current proxyMode, customNoProxy, the test target, and the
+        // actual NO_PROXY env var value so the client can show the real state.
+        wsCtx.effect(() => wsCtx.webServer.register({
+            kind: 'exact',
+            path: '/plugins/dsh-flash-proxy/proxy-status',
+            handler: async (req, res) => {
+                if (req.method !== 'GET') {
+                    res.statusCode = 405;
+                    res.setHeader('allow', 'GET');
+                    res.end();
+                    return;
+                }
+                const mode = resolveMode();
+                const custom = config.customNoProxy.get() || '';
+                const testUrl = resolveTestUrl();
+                const route = await proxyRouteForUrl(testUrl);
+                sendJson(res, 200, {
+                    // Global master state. When false, resolveMode() forces 'all-bypass'
+                    // regardless of proxyMode — the client uses this flag to render the
+                    // master toggle and to distinguish "proxy disabled" from "mode =
+                    // all-bypass" chosen explicitly.
+                    proxyEnabled: config.proxyEnabled?.get() !== false,
+                    proxyMode: mode,
+                    customNoProxy: custom,
+                    testUrl,
+                    // What this plugin published for the current mode (null = cleared).
+                    noProxy: resolveNoProxy(mode, custom) ?? null,
+                    testDefault: DEFAULT_TEST_URL,
+                    // Probed against the configured test target, not a hardcoded host —
+                    // "is a proxy active" and "did the test use one" must not disagree.
+                    proxyAvailable: route.proxied,
+                    // Whether any proxy variable exists at all. proxyAvailable alone
+                    // cannot distinguish "no proxy configured" from "configured, and this
+                    // URL is deliberately bypassed" — the client needs both to avoid
+                    // telling the user their proxy has no effect when they asked for a
+                    // bypass.
+                    httpProxy: readLaunchEnv(['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy']),
+                    // Per-class proxy variables, each verbatim — lets the client render a
+                    // complete read-only inventory (HTTP_PROXY / HTTPS_PROXY / ALL_PROXY).
+                    proxyEnv: proxyEnvSummary(),
+                    routeError: route.error,
+                });
+            },
+        }), 'dsh-flash-proxy: GET /proxy-status');
+        // POST /plugins/dsh-flash-proxy/test-connection
+        // Connection test with diagnostics — walks the redirect chain manually,
+        // measures headers vs body separately, and reports the proxy route decision
+        // plus the underlying socket error code.
+        wsCtx.effect(() => wsCtx.webServer.register({
+            kind: 'exact',
+            path: '/plugins/dsh-flash-proxy/test-connection',
+            handler: async (req, res) => {
+                if (req.method !== 'POST') {
+                    res.statusCode = 405;
+                    res.setHeader('allow', 'POST');
+                    res.end();
+                    return;
+                }
+                // Optional { url } override; falls back to the stored setting.
+                const body = await readJsonBody(req);
+                const testUrl = resolveTestUrl(body && body.url);
+                let target;
+                try {
+                    target = new URL(testUrl);
+                    if (target.protocol !== 'http:' && target.protocol !== 'https:') {
+                        throw new Error('unsupported protocol: ' + target.protocol);
+                    }
+                }
+                catch (e) {
+                    sendJson(res, 200, {
+                        ok: false,
+                        url: testUrl,
+                        finalUrl: testUrl,
+                        elapsedMs: 0,
+                        headersMs: 0,
+                        bodyMs: 0,
+                        bodyBytes: 0,
+                        bodySnippet: null,
+                        status: 0,
+                        statusText: '',
+                        contentType: '',
+                        contentLength: null,
+                        redirects: [],
+                        redirectLimitHit: false,
+                        timeoutMs: TEST_TIMEOUT_MS,
+                        proxy: await describeProxyRoute(testUrl, false),
+                        error: {
+                            name: 'InvalidTestUrl',
+                            message: e?.message || String(e),
+                            code: null,
+                            causeName: null,
+                            causeMessage: null,
+                            causeCode: null,
+                            causeErrno: null,
+                        },
+                    });
+                    return;
+                }
+                try {
+                    sendJson(res, 200, await runConnectionTest(testUrl));
+                }
+                catch (e) {
+                    // runConnectionTest already reports failures as data; this is a
+                    // belt-and-braces guard so the route can never 500.
+                    sendJson(res, 200, {
+                        ok: false,
+                        url: testUrl,
+                        finalUrl: testUrl,
+                        elapsedMs: 0,
+                        redirects: [],
+                        proxy: await describeProxyRoute(testUrl),
+                        error: { name: 'InternalError', message: e?.message || String(e) },
+                    });
+                }
+            },
+        }), 'dsh-flash-proxy: POST /test-connection');
+    });
+    // ── Migration: adopt proxy settings from dock-flash namespace ───────
+    ctx.inject(['settings'], (settingsCtx) => {
+        const settings = settingsCtx.settings;
+        if (!settings || typeof settings.describe !== 'function')
+            return;
+        // `settings` here is the HOST service — `SettingsForms` from
+        // @deepseek-ai/dsh-settings — and ITS `describe()` is SYNCHRONOUS: it returns
+        // the descriptor ARRAY directly, with no `{ok, value}` envelope. Writing
+        // `settings.describe().then(...)` therefore threw
+        // `TypeError: settings.describe(...).then is not a function` on the spot, and
+        // because the throw happens at the `.then` ACCESS it also escaped the
+        // `.catch(() => {})` at the end of the chain — so this migration has never run
+        // once. Normalize the result instead, and accept BOTH shapes: the host's bare
+        // array, and the remote namespace's `{ ok, value: { namespaces } }`.
+        const described = (() => {
+            try {
+                return Promise.resolve(settings.describe());
+            }
+            catch (e) {
+                return Promise.reject(e);
+            }
+        })();
+        described.then(async (desc) => {
+            if (!desc || desc.ok === false)
+                return;
+            const view = desc.value || desc;
+            const nsList = view && Array.isArray(view.namespaces)
+                ? view.namespaces
+                : (Array.isArray(view) ? view : []);
+            const oldNs = nsList.find((n) => (n && (n.ns || n.namespace)) === 'dock-flash');
+            if (!oldNs)
+                return;
+            const resolved = oldNs.value || oldNs.resolved;
+            if (!resolved)
+                return;
+            const currentMode = config.proxyMode.get();
+            const alreadyMigrated = currentMode && currentMode !== DEFAULT_MODE;
+            if (!alreadyMigrated) {
+                const patch = {};
+                if (resolved.proxyMode && resolved.proxyMode !== DEFAULT_MODE) {
+                    patch.proxyMode = resolved.proxyMode;
+                }
+                if (resolved.customNoProxy) {
+                    patch.customNoProxy = resolved.customNoProxy;
+                }
+                if (resolved.testUrl && resolved.testUrl !== DEFAULT_TEST_URL) {
+                    patch.testUrl = resolved.testUrl;
+                }
+                if (typeof resolved.useProxy === 'boolean' && !resolved.proxyMode) {
+                    patch.proxyMode = resolved.useProxy ? 'all-proxy' : 'all-bypass';
+                }
+                if (Object.keys(patch).length > 0) {
+                    console.log('[dsh-flash-proxy] migrating proxy settings from dock-flash namespace:', patch);
+                    try {
+                        await settings.update('dsh-flash-proxy', patch);
+                    }
+                    catch (e) {
+                        console.warn('[dsh-flash-proxy] migration write failed:', e?.message || e);
+                    }
+                }
+            }
+        }).catch(() => { });
+    });
+}