@undefineds.co/xpod 0.4.14 → 0.4.15

package/dist/tunnel/AutoTunnelProvider.d.ts

@@ -0,0 +1,56 @@
+import type { TunnelConfig, TunnelProvider, TunnelSetupOptions, TunnelStatus } from './TunnelProvider';
+/** One tunnel the auto provider may bring up, in the order it is worth trying. */
+export interface AutoTunnelCandidate {
+    /** Provider or profile id, used in status and in the failure detail. */
+    id: string;
+    provider: TunnelProvider;
+}
+export interface AutoTunnelProviderOptions {
+    candidates: readonly AutoTunnelCandidate[];
+    /**
+     * How long one candidate gets to reach `proxy-ready` before the next one is
+     * tried. A candidate that is blocked (network policy, rejected credential)
+     * usually fails faster than this; the timeout only bounds the silent ones.
+     */
+    readinessTimeoutMs?: number;
+    /** Poll interval while waiting for readiness. */
+    pollIntervalMs?: number;
+}
+/**
+ * Brings up whichever tunnel actually works.
+ *
+ * An operator configures the providers they have credentials for; which of them
+ * can reach its control plane is a property of the network, not of the list. So
+ * the candidates are tried in order and the first one that publishes a proxy
+ * wins, with the losers stopped and their reasons kept for the failure report.
+ * An explicit selection never goes through here: the runtime registers that
+ * provider directly, so a closed or pinned tunnel cannot come back on its own.
+ */
+export declare class AutoTunnelProvider implements TunnelProvider {
+    readonly name = "auto";
+    private readonly logger;
+    private readonly candidates;
+    private readonly readinessTimeoutMs;
+    private readonly pollIntervalMs;
+    private configs;
+    private active?;
+    private started;
+    private status;
+    /** Why each candidate that did not win was dropped. */
+    private readonly attempts;
+    constructor(options: AutoTunnelProviderOptions);
+    setup(options: TunnelSetupOptions): Promise<TunnelConfig>;
+    start(config?: TunnelConfig): Promise<void>;
+    stop(): Promise<void>;
+    getStatus(): TunnelStatus;
+    getEndpoint(): string | undefined;
+    cleanup(config: TunnelConfig): Promise<void>;
+    /** Id of the candidate currently serving, once one is ready. */
+    getActiveId(): string | undefined;
+    /** The candidates that were tried, and why the ones that lost did. */
+    getAttempts(): readonly string[];
+    private waitForReady;
+    /** Stop a candidate that lost and stop counting it as started. */
+    private dropCandidate;
+    private stopLosers;
+}

package/dist/tunnel/AutoTunnelProvider.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutoTunnelProvider = void 0;
+const global_logger_factory_1 = require("global-logger-factory");
+const TunnelLifecycle_1 = require("./TunnelLifecycle");
+const DEFAULT_READINESS_TIMEOUT_MS = 30_000;
+const DEFAULT_POLL_INTERVAL_MS = 250;
+/**
+ * Brings up whichever tunnel actually works.
+ *
+ * An operator configures the providers they have credentials for; which of them
+ * can reach its control plane is a property of the network, not of the list. So
+ * the candidates are tried in order and the first one that publishes a proxy
+ * wins, with the losers stopped and their reasons kept for the failure report.
+ * An explicit selection never goes through here: the runtime registers that
+ * provider directly, so a closed or pinned tunnel cannot come back on its own.
+ */
+class AutoTunnelProvider {
+    constructor(options) {
+        this.name = 'auto';
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        this.configs = new Map();
+        this.started = [];
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('stopped');
+        /** Why each candidate that did not win was dropped. */
+        this.attempts = [];
+        this.candidates = options.candidates;
+        this.readinessTimeoutMs = options.readinessTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    }
+    async setup(options) {
+        this.configs = new Map();
+        for (const candidate of this.candidates) {
+            try {
+                this.configs.set(candidate.id, await candidate.provider.setup(options));
+            }
+            catch (error) {
+                this.attempts.push(`${candidate.id}: ${describeError(error)}`);
+                this.logger.warn(`Tunnel candidate ${candidate.id} could not be prepared: ${describeError(error)}`);
+            }
+        }
+        // The driver round-trips this config back into `start`, which drives the
+        // candidates itself, so it only has to describe the requested origin.
+        const first = this.candidates[0];
+        const config = first ? this.configs.get(first.id) : undefined;
+        return config ?? {
+            subdomain: options.subdomain,
+            provider: 'cloudflare',
+            endpoint: '',
+            originUrl: `${options.localProtocol ?? 'http'}://127.0.0.1:${options.localPort}`,
+        };
+    }
+    async start(config) {
+        void config;
+        for (const candidate of this.candidates) {
+            const candidateConfig = this.configs.get(candidate.id);
+            if (!candidateConfig) {
+                continue;
+            }
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('process-started', { endpoint: candidate.provider.getEndpoint() });
+            try {
+                this.started.push(candidate);
+                await candidate.provider.start(candidateConfig);
+                const ready = await this.waitForReady(candidate.provider);
+                if (ready) {
+                    this.active = candidate;
+                    this.status = withCandidate(candidate, candidate.provider.getStatus());
+                    this.logger.info(`Tunnel ready through ${candidate.id}`);
+                    await this.stopLosers(candidate);
+                    return;
+                }
+                this.attempts.push(`${candidate.id}: ${describeStatus(candidate.provider.getStatus())}`);
+                this.logger.warn(`Tunnel candidate ${candidate.id} did not become ready; trying the next one`);
+                await this.dropCandidate(candidate);
+            }
+            catch (error) {
+                this.attempts.push(`${candidate.id}: ${describeError(error)}`);
+                this.logger.warn(`Tunnel candidate ${candidate.id} failed: ${describeError(error)}`);
+                await this.dropCandidate(candidate);
+            }
+        }
+        // Nothing worked: report which candidates were tried and why, so a caller
+        // never has to guess whether the tunnel is off or merely unreachable.
+        const detail = this.attempts.length > 0
+            ? this.attempts.join('; ')
+            : 'no tunnel provider is configured';
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', { error: `no-tunnel-candidate-ready: ${detail}` });
+    }
+    async stop() {
+        const targets = this.started;
+        this.started = [];
+        this.active = undefined;
+        await Promise.all(targets.map(async (candidate) => {
+            await candidate.provider.stop().catch((error) => {
+                this.logger.warn(`Stopping tunnel candidate ${candidate.id} failed: ${describeError(error)}`);
+            });
+        }));
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('stopped');
+    }
+    getStatus() {
+        if (!this.active) {
+            return this.status;
+        }
+        const current = this.active.provider.getStatus();
+        // A tunnel that was ready and then died is still the active one, so its
+        // failure is what callers must see - never a stale "connected".
+        return withCandidate(this.active, current);
+    }
+    getEndpoint() {
+        return this.active?.provider.getEndpoint();
+    }
+    async cleanup(config) {
+        await Promise.all(this.candidates.map(async (candidate) => {
+            await candidate.provider.cleanup(config).catch((error) => {
+                this.logger.warn(`Cleaning up tunnel candidate ${candidate.id} failed: ${describeError(error)}`);
+            });
+        }));
+    }
+    /** Id of the candidate currently serving, once one is ready. */
+    getActiveId() {
+        return this.active?.id;
+    }
+    /** The candidates that were tried, and why the ones that lost did. */
+    getAttempts() {
+        return this.attempts;
+    }
+    async waitForReady(provider) {
+        const deadline = Date.now() + this.readinessTimeoutMs;
+        while (Date.now() < deadline) {
+            const status = provider.getStatus();
+            if (status.stage === 'proxy-ready' || status.connected) {
+                return true;
+            }
+            if (status.stage === 'failed') {
+                return false;
+            }
+            await delay(this.pollIntervalMs);
+        }
+        return false;
+    }
+    /** Stop a candidate that lost and stop counting it as started. */
+    async dropCandidate(candidate) {
+        await candidate.provider.stop().catch((error) => {
+            this.logger.warn(`Stopping tunnel candidate ${candidate.id} failed: ${describeError(error)}`);
+        });
+        this.started = this.started.filter((started) => started.id !== candidate.id);
+    }
+    async stopLosers(winner) {
+        await Promise.all(this.started
+            .filter((candidate) => candidate.id !== winner.id)
+            .map(async (candidate) => {
+            await candidate.provider.stop().catch(() => undefined);
+        }));
+        this.started = [winner];
+    }
+}
+exports.AutoTunnelProvider = AutoTunnelProvider;
+/**
+ * The winning candidate's own status, with its error text attributed to the
+ * profile id the operator configured rather than to the provider class name.
+ */
+function withCandidate(candidate, status) {
+    const stage = status.stage ?? (status.connected ? 'proxy-ready' : 'process-started');
+    const error = status.error ? `${candidate.id}: ${status.error}` : undefined;
+    return (0, TunnelLifecycle_1.createTunnelStatus)(stage, {
+        ...status,
+        ...(error ? { error } : {}),
+    });
+}
+function describeStatus(status) {
+    return status.error ?? status.stage ?? (status.connected ? 'connected' : 'unknown');
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+//# sourceMappingURL=AutoTunnelProvider.js.map

package/dist/tunnel/index.d.ts

@@ -2,5 +2,6 @@ export type { TunnelProvider, TunnelConfig, TunnelSetupOptions, TunnelStatus, }
 export { CloudflareTunnelProvider, type CloudflareTunnelProviderOptions, } from './CloudflareTunnelProvider';
 export { LocalTunnelProvider, type LocalTunnelProviderOptions, } from './LocalTunnelProvider';
 export { NgrokTunnelProvider, type NgrokTunnelProviderOptions, } from './NgrokTunnelProvider';
+export { AutoTunnelProvider, type AutoTunnelCandidate, type AutoTunnelProviderOptions, } from './AutoTunnelProvider';
 export type { ActiveTunnelProvider, TunnelProfile, TunnelProfileProvider, TunnelProfileState, } from './TunnelProfiles';
 export { resolveTunnelProfileState, selectActiveTunnelProfile, } from './TunnelProfiles';

package/dist/tunnel/index.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.selectActiveTunnelProfile = exports.resolveTunnelProfileState = exports.NgrokTunnelProvider = exports.LocalTunnelProvider = exports.CloudflareTunnelProvider = void 0;
+exports.selectActiveTunnelProfile = exports.resolveTunnelProfileState = exports.AutoTunnelProvider = exports.NgrokTunnelProvider = exports.LocalTunnelProvider = exports.CloudflareTunnelProvider = void 0;
 var CloudflareTunnelProvider_1 = require("./CloudflareTunnelProvider");
 Object.defineProperty(exports, "CloudflareTunnelProvider", { enumerable: true, get: function () { return CloudflareTunnelProvider_1.CloudflareTunnelProvider; } });
 var LocalTunnelProvider_1 = require("./LocalTunnelProvider");
 Object.defineProperty(exports, "LocalTunnelProvider", { enumerable: true, get: function () { return LocalTunnelProvider_1.LocalTunnelProvider; } });
 var NgrokTunnelProvider_1 = require("./NgrokTunnelProvider");
 Object.defineProperty(exports, "NgrokTunnelProvider", { enumerable: true, get: function () { return NgrokTunnelProvider_1.NgrokTunnelProvider; } });
+var AutoTunnelProvider_1 = require("./AutoTunnelProvider");
+Object.defineProperty(exports, "AutoTunnelProvider", { enumerable: true, get: function () { return AutoTunnelProvider_1.AutoTunnelProvider; } });
 var TunnelProfiles_1 = require("./TunnelProfiles");
 Object.defineProperty(exports, "resolveTunnelProfileState", { enumerable: true, get: function () { return TunnelProfiles_1.resolveTunnelProfileState; } });
 Object.defineProperty(exports, "selectActiveTunnelProfile", { enumerable: true, get: function () { return TunnelProfiles_1.selectActiveTunnelProfile; } });

package/node_modules/@undefineds.co/ai-connections/dist/error-wording.js

@@ -134,8 +134,13 @@ function messageForSafeErrorCode(code, provider) {
             return provider
                 ? `${providerLabel(provider)} does not support this operation.`
                 : 'This AI Connection operation is not supported.';
-        case 'service_identity_unavailable':
-            return 'AI Connection service identity is unavailable';
+        case 'service_access_missing':
+        case 'pod_interface_key_missing':
+        case 'pod_interface_key_rejected':
+        case 'caller_dpop_replay_unsupported':
+            // Xpod reaches the Pod with the owner's own interface key, never with a
+            // deployment identity, so the fix is always on the user's side.
+            return 'Xpod 尚未获得这个 Pod 的接口访问密钥。请在「客户端访问」中创建 API Key 并应用到客户端后重试。';
         case 'unauthorized':
             return 'Please sign in again to continue.';
         case 'forbidden':

package/node_modules/@undefineds.co/solid-sdk/dist/access-route.cjs

@@ -0,0 +1,230 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/access-route.ts
+var exports_access_route = {};
+__export(exports_access_route, {
+  usableRoutes: () => usableRoutes,
+  createSolidAccessRouteFetch: () => createSolidAccessRouteFetch,
+  chooseAccessRoute: () => chooseAccessRoute
+});
+module.exports = __toCommonJS(exports_access_route);
+
+// src/local-route-fetch.ts
+var SOLID_LOCAL_ROUTE_CANONICAL_URL_HEADER = "x-xpod-canonical-url";
+var SOLID_LOCAL_ROUTE_CANONICAL_ORIGIN_HEADER = "x-xpod-canonical-origin";
+var SOLID_LOCAL_ROUTE_CANONICAL_HOST_HEADER = "x-xpod-canonical-host";
+var SOLID_LOCAL_ROUTE_LOCAL_URL_HEADER = "x-xpod-local-route-url";
+function resolveSolidLocalRouteUrl(input, routes) {
+  let sourceUrl;
+  try {
+    sourceUrl = input instanceof URL ? new URL(input.href) : new URL(input);
+  } catch {
+    return;
+  }
+  const route = routes.map(normalizeRoute).filter((candidate) => isInsideBase(sourceUrl, candidate.canonicalBaseUrl)).sort((left, right) => right.canonicalBaseUrl.length - left.canonicalBaseUrl.length)[0];
+  return route ? replaceBase(sourceUrl, route) : undefined;
+}
+function createSolidLocalRouteFetch(options) {
+  return async (input, init) => {
+    const sourceUrl = requestUrl(input);
+    if (!sourceUrl) {
+      return init === undefined ? options.fetch.call(globalThis, input) : options.fetch.call(globalThis, input, init);
+    }
+    const routes = options.routes();
+    const targetUrl = resolveSolidLocalRouteUrl(sourceUrl, routes);
+    if (!targetUrl) {
+      return init === undefined ? options.fetch.call(globalThis, input) : options.fetch.call(globalThis, input, init);
+    }
+    const headers = routedHeaders(input, init, sourceUrl, targetUrl);
+    let response;
+    if (input instanceof Request) {
+      const request = new Request(new Request(targetUrl, input), { headers });
+      response = init === undefined ? await options.fetch.call(globalThis, request) : await options.fetch.call(globalThis, request, { ...init, headers });
+    } else {
+      response = await options.fetch.call(globalThis, targetUrl, { ...init, headers });
+    }
+    const canonicalResponseUrl = resolveSolidLocalRouteUrl(response.url, routes.map((route) => ({
+      canonicalBaseUrl: route.localBaseUrl,
+      localBaseUrl: route.canonicalBaseUrl
+    })));
+    return canonicalResponseUrl ? withResponseUrl(response, canonicalResponseUrl.href) : response;
+  };
+}
+function withResponseUrl(response, url) {
+  const clone = response.clone.bind(response);
+  Object.defineProperties(response, {
+    url: { value: url, configurable: true },
+    clone: { value: () => withResponseUrl(clone(), url), configurable: true }
+  });
+  return response;
+}
+function requestUrl(input) {
+  if (input instanceof Request)
+    return new URL(input.url);
+  try {
+    return new URL(String(input));
+  } catch {
+    return;
+  }
+}
+function normalizeRoute(route) {
+  return {
+    canonicalBaseUrl: normalizeBaseUrl(route.canonicalBaseUrl),
+    localBaseUrl: normalizeBaseUrl(route.localBaseUrl)
+  };
+}
+function normalizeBaseUrl(value) {
+  const url = new URL(value);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new TypeError("Solid local routes must use http or https");
+  }
+  url.search = "";
+  url.hash = "";
+  return url.href.endsWith("/") ? url.href : `${url.href}/`;
+}
+function isInsideBase(url, base) {
+  const canonical = new URL(base);
+  return url.origin === canonical.origin && url.pathname.startsWith(canonical.pathname);
+}
+function replaceBase(url, route) {
+  const canonical = new URL(route.canonicalBaseUrl);
+  const local = new URL(route.localBaseUrl);
+  const relativePath = url.pathname.slice(canonical.pathname.length);
+  const target = new URL(relativePath, local);
+  target.search = url.search;
+  target.hash = url.hash;
+  return target;
+}
+function routedHeaders(input, init, canonicalUrl, localUrl) {
+  const request = input instanceof Request ? input : undefined;
+  const headers = new Headers(request?.headers ?? undefined);
+  new Headers(init?.headers ?? undefined).forEach((value, key) => headers.set(key, value));
+  headers.set(SOLID_LOCAL_ROUTE_CANONICAL_URL_HEADER, canonicalUrl.toString());
+  headers.set(SOLID_LOCAL_ROUTE_CANONICAL_ORIGIN_HEADER, canonicalUrl.origin);
+  headers.set(SOLID_LOCAL_ROUTE_CANONICAL_HOST_HEADER, canonicalUrl.host);
+  headers.set(SOLID_LOCAL_ROUTE_LOCAL_URL_HEADER, localUrl.toString());
+  return headers;
+}
+
+// src/access-route.ts
+async function chooseAccessRoute(routeSet, options = {}) {
+  const candidates = usableRoutes(routeSet, options.managedClient ?? true, options.allowLocalOnlyRoutes ?? false);
+  if (candidates.length === 0) {
+    return null;
+  }
+  const probe = options.probe ?? defaultProbe;
+  const timeoutMs = options.probeTimeoutMs ?? 1000;
+  const results = await Promise.all(candidates.map(async (route) => ({
+    route,
+    ok: await probeWithTimeout(route, probe, timeoutMs)
+  })));
+  return results.find((result) => result.ok)?.route ?? null;
+}
+function usableRoutes(routeSet, managedClient, allowLocalOnlyRoutes) {
+  return routeSet.routes.filter((route) => route.health !== "unreachable").filter((route) => managedClient || !route.requiresManagedClient).filter((route) => allowLocalOnlyRoutes || route.visibility !== "local-only").slice().sort((left, right) => left.priority - right.priority || left.id.localeCompare(right.id));
+}
+function createSolidAccessRouteFetch(options) {
+  const managedClient = options.managedClient ?? true;
+  let selected;
+  const selectRoute = async () => {
+    const routeSet = {
+      canonicalUrl: options.routes()[0]?.canonicalUrl ?? "",
+      routes: options.routes()
+    };
+    const candidate = await chooseAccessRoute(routeSet, {
+      managedClient,
+      ...options.allowLocalOnlyRoutes === undefined ? {} : { allowLocalOnlyRoutes: options.allowLocalOnlyRoutes },
+      ...options.probeTimeoutMs === undefined ? {} : { probeTimeoutMs: options.probeTimeoutMs },
+      ...options.probe === undefined ? {} : { probe: options.probe }
+    });
+    selected = candidate ?? undefined;
+    return candidate;
+  };
+  const routeFor = async () => {
+    if (selected && options.routes().some((route) => route.id === selected?.id && route.targetUrl === selected?.targetUrl)) {
+      return selected;
+    }
+    return await selectRoute() ?? undefined;
+  };
+  const routedFetchFor = (route) => createSolidLocalRouteFetch({
+    fetch: options.fetch,
+    routes: () => [{
+      canonicalBaseUrl: route.canonicalUrl,
+      localBaseUrl: route.targetUrl
+    }]
+  });
+  return async (input, init) => {
+    const route = await routeFor();
+    if (!route) {
+      return init === undefined ? options.fetch.call(globalThis, input) : options.fetch.call(globalThis, input, init);
+    }
+    try {
+      return await routedFetchFor(route)(input, init);
+    } catch (error) {
+      selected = undefined;
+      await options.refreshRoutes?.();
+      const retryRoute = await selectRoute();
+      if (!retryRoute || retryRoute.id === route.id) {
+        throw error;
+      }
+      return routedFetchFor(retryRoute)(input, init);
+    }
+  };
+}
+async function probeWithTimeout(route, probe, timeoutMs) {
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await Promise.resolve(probe(route, controller.signal));
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function defaultProbe(route, signal) {
+  if (!route.targetUrl.startsWith("http://") && !route.targetUrl.startsWith("https://")) {
+    return route.health === "healthy";
+  }
+  const response = await fetch(new URL("/.well-known/solid", route.targetUrl), {
+    method: "HEAD",
+    signal
+  });
+  return response.ok || response.status === 401 || response.status === 403;
+}

package/node_modules/@undefineds.co/solid-sdk/dist/access-route.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Access routes for a node whose canonical URL never changes.
+ *
+ * A Pod's canonical URL is its RDF identity (`docs/multi-channel-access.md`), and
+ * the same identity can be reached over several physical paths: the node's own
+ * loopback listener, a LAN address, a public address, a hole-punched p2p socket
+ * or the user's tunnel. Callers pick by *where they are*, so the routes carry the
+ * priority that encodes it and the health that says whether it currently works.
+ */
+export type AccessRouteKind = 'loopback' | 'lan' | 'public-direct' | 'p2p' | 'user-tunnel' | 'xpod-relay';
+export type AccessRouteVisibility = 'local-only' | 'same-account' | 'authorized-client' | 'public';
+export type AccessRouteHealth = 'unknown' | 'healthy' | 'degraded' | 'unreachable';
+export interface AccessRoute {
+    id: string;
+    nodeId?: string;
+    /** The canonical origin this route serves. Requests keep this identity. */
+    canonicalUrl: string;
+    kind: AccessRouteKind;
+    /** Where the request is actually sent. */
+    targetUrl: string;
+    /** Lower wins. Loopback is 10, lan 20, public-direct 30, p2p 40, tunnel 50. */
+    priority: number;
+    requiresManagedClient?: boolean;
+    visibility?: AccessRouteVisibility;
+    health?: AccessRouteHealth;
+    metadata?: Record<string, unknown>;
+}
+export interface AccessRouteSet {
+    nodeId?: string;
+    canonicalUrl: string;
+    generatedAt?: string;
+    routes: readonly AccessRoute[];
+}
+export interface ChooseAccessRouteOptions {
+    /** A client that may use private routes (LAN, p2p, tunnel). */
+    managedClient?: boolean;
+    /**
+     * A client running on the node's own host may use `local-only` routes. It has
+     * to say so: a loopback target is meaningless anywhere else.
+     */
+    allowLocalOnlyRoutes?: boolean;
+    probeTimeoutMs?: number;
+    probe?: (route: AccessRoute, signal: AbortSignal) => Promise<boolean> | boolean;
+}
+/**
+ * Pick the best route that actually answers: candidates are ordered by priority
+ * and probed in parallel, so a same-machine client lands on loopback while a
+ * remote one skips it without waiting for it to time out.
+ */
+export declare function chooseAccessRoute(routeSet: AccessRouteSet, options?: ChooseAccessRouteOptions): Promise<AccessRoute | null>;
+export declare function usableRoutes(routeSet: AccessRouteSet, managedClient: boolean, allowLocalOnlyRoutes: boolean): AccessRoute[];
+export interface CreateSolidAccessRouteFetchOptions {
+    fetch: typeof globalThis.fetch;
+    /** Current route set. Re-read on every request so a caller can refresh it. */
+    routes: () => readonly AccessRoute[];
+    /**
+     * Re-discover the routes after the selected one stops working, which is how a
+     * client keeps using the newest path it knows about.
+     */
+    refreshRoutes?: () => Promise<readonly AccessRoute[] | void> | readonly AccessRoute[] | void;
+    managedClient?: boolean;
+    /** Set by clients that run on the node's own host (`local-only` routes). */
+    allowLocalOnlyRoutes?: boolean;
+    probeTimeoutMs?: number;
+    probe?: (route: AccessRoute, signal: AbortSignal) => Promise<boolean> | boolean;
+}
+/**
+ * A fetch that keeps canonical URLs canonical while sending the request over the
+ * best route this client can use.
+ *
+ * Canonical identity is preserved end to end: the target URL is rewritten, the
+ * canonical host travels in the `x-xpod-canonical-*` headers, and the response
+ * reports its canonical URL again. When the chosen route stops answering, the
+ * routes are refreshed and the request is retried once against the new best one.
+ */
+export declare function createSolidAccessRouteFetch(options: CreateSolidAccessRouteFetchOptions): typeof globalThis.fetch;