@undefineds.co/xpod 0.4.13 → 0.4.15

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;

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

@@ -0,0 +1,115 @@
+import { createSolidLocalRouteFetch } from './local-route-fetch.js';
+/**
+ * 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 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;
+}
+export 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));
+}
+/**
+ * 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 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) {
+            // The route went away (laptop moved networks, tunnel restarted). Ask for
+            // the current set once and retry against whatever is best now.
+            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://')) {
+        // Non-HTTP routes (p2p sockets) report their own readiness.
+        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/index.cjs

@@ -43,6 +43,7 @@ __export(exports_src, {
   useSolidSessionSnapshot: () => useSolidSessionSnapshot,
   useSolidRuntime: () => useSolidRuntime,
   useLoginStore: () => useLoginStore,
+  usableRoutes: () => usableRoutes,
   storageBindingMatches: () => storageBindingMatches,
   resolveSolidLocalRouteUrl: () => resolveSolidLocalRouteUrl,
   resolveSolidLocalRouteFromStatus: () => resolveSolidLocalRouteFromStatus,
@@ -57,8 +58,10 @@ __export(exports_src, {
   createStorageSelectionState: () => createStorageSelectionState,
   createSolidSessionRuntime: () => createSolidSessionRuntime,
   createSolidLocalRouteFetch: () => createSolidLocalRouteFetch,
+  createSolidAccessRouteFetch: () => createSolidAccessRouteFetch,
   createPodRuntime: () => createPodRuntime,
   createLoginStore: () => createLoginStore,
+  chooseAccessRoute: () => chooseAccessRoute,
   SolidRuntimeProvider: () => SolidRuntimeProvider,
   SOLID_LOCAL_ROUTE_LOCAL_URL_HEADER: () => SOLID_LOCAL_ROUTE_LOCAL_URL_HEADER,
   SOLID_LOCAL_ROUTE_CANONICAL_URL_HEADER: () => SOLID_LOCAL_ROUTE_CANONICAL_URL_HEADER,
@@ -1154,3 +1157,89 @@ function routedHeaders(input, init, canonicalUrl, localUrl) {
   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/index.d.ts

@@ -6,3 +6,4 @@ export * from './storage-selection';
 /** LinX four-phase store (`linx-login`). Xpod uses `xpod.remembered-login.v1` instead. */
 export * from './login-store';
 export * from './local-route-fetch';
+export * from './access-route';

package/node_modules/@undefineds.co/solid-sdk/dist/index.js

@@ -6,3 +6,4 @@ export * from './storage-selection.js';
 /** LinX four-phase store (`linx-login`). Xpod uses `xpod.remembered-login.v1` instead. */
 export * from './login-store.js';
 export * from './local-route-fetch.js';
+export * from './access-route.js';

package/node_modules/@undefineds.co/solid-sdk/package.json

@@ -42,10 +42,15 @@
       "types": "./dist/local-route-fetch.d.ts",
       "import": "./dist/local-route-fetch.js",
       "require": "./dist/local-route-fetch.cjs"
+    },
+    "./access-route": {
+      "types": "./dist/access-route.d.ts",
+      "import": "./dist/access-route.js",
+      "require": "./dist/access-route.cjs"
     }
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json && bun ../../scripts/fix-dist-js-imports.mjs dist && bun build src/index.ts --target=node --format=cjs --packages=external --outfile=dist/index.cjs && bun build src/local-route-fetch.ts --target=node --format=cjs --packages=external --outfile=dist/local-route-fetch.cjs",
+    "build": "rm -rf dist && tsc -p tsconfig.json && bun ../../scripts/fix-dist-js-imports.mjs dist && bun build src/index.ts --target=node --format=cjs --packages=external --outfile=dist/index.cjs && bun build src/local-route-fetch.ts --target=node --format=cjs --packages=external --outfile=dist/local-route-fetch.cjs && bun build src/access-route.ts --target=node --format=cjs --packages=external --outfile=dist/access-route.cjs",
     "test": "vitest run test --config ../../vitest.packages.config.mts"
   },
   "dependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@undefineds.co/xpod",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "description": "Xpod is an extended Community Solid Server, offering rich-feature, production-level Solid Pod and identity management.",
   "repository": "https://github.com/undefinedsco/xpod",
   "author": "developer@undefineds.co",
@@ -65,7 +65,7 @@
   },
   "scripts": {
     "build": "bun run build:packages && bun run build:ts && bun run build:components && bun run build:ui",
-    "build:packages": "bun run --filter '@undefineds.co/solid-sdk' build && bun run --filter '@undefineds.co/shared-ui' build && bun run --filter '@undefineds.co/pod-collections' build && bun run --filter '@undefineds.co/extension-sdk' build && bun run --filter '@undefineds.co/ai-connections-core' build && bun run --filter '@undefineds.co/ai-connections' build",
+    "build:packages": "bun run --filter '@undefineds.co/solid-sdk' build && bun run --filter '@undefineds.co/shared-ui' build && bun run --filter '@undefineds.co/pod-collections' build && bun run --filter '@undefineds.co/extension-sdk' build && bun run --filter '@undefineds.co/ai-connections' build",
     "test:packages": "bun run --filter './packages/*' test",
     "build:ts": "tsc",
     "build:components": "componentsjs-generator -s src -c dist/components -r undefineds -i config/components-ignore.json",
@@ -170,7 +170,8 @@
     "smoke:tunnel:ngrok:browser": "bun scripts/ngrok-browser-pod-smoke.ts",
     "smoke:tunnel:ngrok:inrupt": "bun scripts/ngrok-inrupt-oidc-smoke.ts",
     "dev:monitor": "bun --no-env-file scripts/dev-repair.ts",
-    "dev:monitor:desktop": "bun --no-env-file scripts/dev-repair.ts --desktop"
+    "dev:monitor:desktop": "bun --no-env-file scripts/dev-repair.ts --desktop",
+    "accept:network-tunnel": "bun scripts/accept-network-tunnel.ts"
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.39",
@@ -351,7 +352,6 @@
     "@undefineds.co/drizzle-solid": "file:./node_modules/@undefineds.co/drizzle-solid",
     "@undefineds.co/extensions": "file:./node_modules/@undefineds.co/extensions",
     "@undefineds.co/ai-connections": "file:./node_modules/@undefineds.co/ai-connections",
-    "@undefineds.co/ai-connections-core": "file:./node_modules/@undefineds.co/ai-connections-core",
     "@undefineds.co/extension-sdk": "file:./node_modules/@undefineds.co/extension-sdk",
     "@undefineds.co/pod-collections": "file:./node_modules/@undefineds.co/pod-collections",
     "@undefineds.co/shared-ui": "file:./node_modules/@undefineds.co/shared-ui",
@@ -384,7 +384,7 @@
     }
   },
   "optionalDependencies": {
-    "@undefineds.co/xpod-darwin-arm64": "0.4.13"
+    "@undefineds.co/xpod-darwin-arm64": "0.4.15"
   },
   "resolutions": {
     "@inrupt/solid-client-authn-browser": "^3.1.1",
@@ -409,7 +409,6 @@
     "@undefineds.co/drizzle-solid",
     "@undefineds.co/extensions",
     "@undefineds.co/ai-connections",
-    "@undefineds.co/ai-connections-core",
     "@undefineds.co/extension-sdk",
     "@undefineds.co/pod-collections",
     "@undefineds.co/shared-ui",