@undefineds.co/xpod 0.4.19 → 0.4.25

package/dist/edge/frp/FrpcProcessManager.js

@@ -5,12 +5,26 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const global_logger_factory_1 = require("global-logger-factory");
+/**
+ * frpc 崩溃后的重启退避（审计 N18）。
+ *
+ * 旧实现固定 1 秒重试：frpc 配置错误时会以每秒一次的节奏永远重启，日志与进程资源都被
+ * 刷满，而且 `stop()` 不会取消已排定的那次重启——停掉的隧道会被自己排的重启复活。
+ */
+const RESTART_BASE_DELAY_MS = 1_000;
+const RESTART_MAX_DELAY_MS = 60_000;
+/** 一次运行活过这个时长就算“健康”，重启计数清零。 */
+const HEALTHY_UPTIME_MS = 60_000;
+/** 隧道是兜底路径，退避到上限后继续重试，不放弃。 */
+const CONFIG_FILE_MODE = 0o600;
 class FrpcProcessManager {
     constructor(options) {
         this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
         this.restarting = false;
         this.status = { state: 'inactive' };
         this.desiredRunning = false;
+        this.consecutiveFailures = 0;
+        this.startedAt = 0;
         this.binaryPath = options.binaryPath;
         this.configPath = options.configPath;
         this.workingDirectory = options.workingDirectory;
@@ -38,16 +52,28 @@ class FrpcProcessManager {
         await this.restart(entrypoint ?? config.entrypoint);
     }
     async stop() {
-        if (!this.process) {
+        // 取消已排定的自动重启：否则一次显式停止会被自己排的重启撤销（与 supervisor 同类缺陷）。
+        this.cancelPendingRestart();
+        // 显式停止才算“重新开始”，自动重启之间的失败计数必须保留，否则退避永远回到 1 秒。
+        this.consecutiveFailures = 0;
+        await this.stopProcess();
+        if (this.status.state !== 'inactive') {
+            this.setStatus({ state: 'inactive', lastUpdated: new Date().toISOString() });
+        }
+    }
+    /**
+     * 结束当前进程，但不碰重启计数与待重启定时器。
+     *
+     * 先把 `this.process` 置空：退出回调据此判断“这个进程已被替换”，不会为它再排一次重启，
+     * 也不会把它的退出写成当前状态。
+     */
+    async stopProcess() {
+        const proc = this.process;
+        if (!proc) {
             return;
         }
-        return new Promise((resolve) => {
-            const proc = this.process;
-            this.process = undefined;
-            if (!proc) {
-                resolve();
-                return;
-            }
+        this.process = undefined;
+        await new Promise((resolve) => {
             proc.once('exit', () => resolve());
             proc.once('error', () => resolve());
             proc.kill();
@@ -60,7 +86,7 @@ class FrpcProcessManager {
         }
         this.restarting = true;
         try {
-            await this.stop();
+            await this.stopProcess();
             await this.ensureDirectory((0, node_path_1.dirname)(this.configPath));
             this.logger.info(`${this.logPrefix} 启动 frpc 进程`);
             const args = ['-c', this.configPath];
@@ -69,11 +95,13 @@ class FrpcProcessManager {
                 stdio: 'pipe',
             });
             this.process = proc;
+            this.startedAt = Date.now();
             this.setStatus({
                 state: 'running',
                 entrypoint,
                 lastUpdated: new Date().toISOString(),
                 pid: proc.pid ?? undefined,
+                restartCount: this.consecutiveFailures,
             });
             proc.stdout.on('data', (data) => {
                 this.logger.debug(`${this.logPrefix} ${data.toString().trim()}`);
@@ -83,13 +111,24 @@ class FrpcProcessManager {
             });
             proc.once('exit', (code, signal) => {
                 this.logger.info(`${this.logPrefix} 退出，code=${code ?? ''} signal=${signal ?? ''}`);
+                if (this.process !== proc) {
+                    // 已被显式停止或替换：这次退出既不代表当前状态，也不该排重启。
+                    return;
+                }
                 this.process = undefined;
+                // 一次活够久的运行说明配置没问题，重启计数清零；否则累加并指数退避。
+                const uptimeMs = this.startedAt > 0 ? Date.now() - this.startedAt : 0;
+                this.consecutiveFailures = uptimeMs >= HEALTHY_UPTIME_MS ? 0 : this.consecutiveFailures + 1;
+                const shouldRestart = this.autoRestart && Boolean(this.currentSignature) && this.desiredRunning;
+                const delayMs = shouldRestart ? this.nextRestartDelayMs() : undefined;
                 if (this.desiredRunning) {
                     this.setStatus({
                         state: 'error',
                         error: `exit:${code ?? 'unknown'}`,
                         lastUpdated: new Date().toISOString(),
                         entrypoint,
+                        restartCount: this.consecutiveFailures,
+                        ...(delayMs === undefined ? {} : { nextRestartInMs: delayMs }),
                     });
                 }
                 else {
@@ -98,12 +137,14 @@ class FrpcProcessManager {
                         lastUpdated: new Date().toISOString(),
                     });
                 }
-                if (this.autoRestart && this.currentSignature && this.desiredRunning) {
-                    setTimeout(() => {
+                if (shouldRestart && delayMs !== undefined) {
+                    this.logger.warn(`${this.logPrefix} ${delayMs}ms 后重启（连续失败 ${this.consecutiveFailures} 次，上限 ${RESTART_MAX_DELAY_MS}ms）`);
+                    this.restartTimer = setTimeout(() => {
+                        this.restartTimer = undefined;
                         void this.restart(entrypoint).catch((error) => {
                             this.logger.error(`${this.logPrefix} 重启失败: ${error instanceof Error ? error.message : String(error)}`);
                         });
-                    }, 1_000);
+                    }, delayMs);
                 }
             });
             proc.once('error', (error) => {
@@ -121,6 +162,16 @@ class FrpcProcessManager {
             this.restarting = false;
         }
     }
+    nextRestartDelayMs() {
+        const exponent = Math.max(0, this.consecutiveFailures - 1);
+        return Math.min(RESTART_BASE_DELAY_MS * 2 ** exponent, RESTART_MAX_DELAY_MS);
+    }
+    cancelPendingRestart() {
+        if (this.restartTimer) {
+            clearTimeout(this.restartTimer);
+            this.restartTimer = undefined;
+        }
+    }
     async ensureDirectory(path) {
         if (!path || path === '.') {
             return;
@@ -155,7 +206,14 @@ class FrpcProcessManager {
             lines.push(`# public_url = ${config.entrypoint}`);
         }
         await this.ensureDirectory((0, node_path_1.dirname)(this.configPath));
-        await node_fs_1.promises.writeFile(this.configPath, `${lines.join('\n')}\n`, 'utf8');
+        // frpc 配置里有隧道 token：写 0600，并对已存在的旧文件再 chmod 一次（审计 N18）。
+        await node_fs_1.promises.writeFile(this.configPath, `${lines.join('\n')}\n`, { encoding: 'utf8', mode: CONFIG_FILE_MODE });
+        try {
+            await node_fs_1.promises.chmod(this.configPath, CONFIG_FILE_MODE);
+        }
+        catch (error) {
+            this.logger.warn(`${this.logPrefix} 无法收紧配置文件权限: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
     getStatus() {
         return { ...this.status };
@@ -167,6 +225,8 @@ class FrpcProcessManager {
             error: update.error,
             entrypoint: update.entrypoint,
             pid: update.pid,
+            ...(update.restartCount === undefined ? {} : { restartCount: update.restartCount }),
+            ...(update.nextRestartInMs === undefined ? {} : { nextRestartInMs: update.nextRestartInMs }),
         };
     }
 }

package/dist/edge/reachability/ManagedClientFetch.d.ts

@@ -9,6 +9,8 @@ export interface ManagedClientFetchOptions {
     probe?: (route: AccessRoute, signal: AbortSignal) => Promise<boolean> | boolean;
     probeTimeoutMs?: number;
     p2p?: ManagedClientP2POptions;
+    /** Injectable clock: route validity must be decided against a known time in tests. */
+    now?: () => Date;
 }
 export interface ManagedClientFetch {
     route: AccessRoute;

package/dist/edge/reachability/ManagedClientFetch.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createSignaledManagedClientFetch = createSignaledManagedClientFetch;
 exports.createManagedClientFetch = createManagedClientFetch;
 const CanonicalFetch_1 = require("./CanonicalFetch");
+const RouteValidation_1 = require("./RouteValidation");
 const P2PDataPlane_1 = require("./P2PDataPlane");
 const P2PSignalingClient_1 = require("./P2PSignalingClient");
 const TcpP2PSignalingSession_1 = require("./TcpP2PSignalingSession");
@@ -34,8 +35,10 @@ async function createSignaledManagedClientFetch(options) {
 }
 async function createManagedClientFetch(options) {
     const errors = [];
-    for (const route of candidateRoutes(options.routeSet)) {
+    const now = (options.now ?? (() => new Date()))();
+    for (const route of candidateRoutes(options.routeSet, now, errors)) {
         if (!await routeProbeSucceeds(route, options)) {
+            errors.push(`Route ${route.id} failed its reachability probe`);
             continue;
         }
         if (route.kind === 'p2p') {
@@ -60,11 +63,24 @@ async function createManagedClientFetch(options) {
     }
     throw new Error(`No managed client route could be opened${errors.length > 0 ? `: ${errors.join('; ')}` : ''}`);
 }
-function candidateRoutes(routeSet) {
-    return routeSet.routes
-        .filter((route) => route.health !== 'unreachable')
-        .slice()
-        .sort((left, right) => left.priority - right.priority || left.id.localeCompare(right.id));
+/**
+ * Routes worth dialling, decided locally before any probe. Skipped routes are named in
+ * `skipped` so a failed selection says why instead of just failing.
+ */
+function candidateRoutes(routeSet, now, skipped) {
+    const candidates = [];
+    for (const route of routeSet.routes) {
+        if (route.health === 'unreachable') {
+            continue;
+        }
+        const reason = (0, RouteValidation_1.routeUnusableReason)(route, { now, remoteClient: true });
+        if (reason) {
+            skipped.push(`Route ${route.id} skipped: ${reason}`);
+            continue;
+        }
+        candidates.push(route);
+    }
+    return candidates.sort((left, right) => left.priority - right.priority || left.id.localeCompare(right.id));
 }
 async function routeProbeSucceeds(route, options) {
     const controller = new AbortController();
@@ -85,14 +101,10 @@ async function defaultManagedProbe(route, signal, fetchImpl) {
     if (route.kind === 'p2p') {
         return route.health !== 'unreachable';
     }
-    if (!route.targetUrl.startsWith('http://') && !route.targetUrl.startsWith('https://')) {
+    if (!(0, RouteValidation_1.isHttpTarget)(route.targetUrl)) {
         return route.health === 'healthy';
     }
-    const response = await (fetchImpl ?? fetch)(new URL('/.well-known/solid', route.targetUrl), {
-        method: 'HEAD',
-        signal,
-    });
-    return response.status < 500;
+    return await (0, RouteValidation_1.probeSolidWellKnown)(route.targetUrl, signal, fetchImpl);
 }
 function managedResult(route, fetch, transport) {
     return {

package/dist/edge/reachability/ManagedClientFetch.jsonld

@@ -29,6 +29,10 @@
         {
           "@id": "undefineds:dist/edge/reachability/ManagedClientFetch.jsonld#ManagedClientFetchOptions__member_p2p",
           "memberFieldName": "p2p"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/ManagedClientFetch.jsonld#ManagedClientFetchOptions__member_now",
+          "memberFieldName": "now"
         }
       ],
       "constructorArguments": []

package/dist/edge/reachability/ManagedRouteSelector.d.ts

@@ -3,5 +3,7 @@ export interface ChooseAccessRouteOptions {
     managedClient: boolean;
     timeoutMs?: number;
     probe?: (route: AccessRoute, signal: AbortSignal) => Promise<boolean> | boolean;
+    /** Injectable clock: expired access points must be rejected against a known time in tests. */
+    now?: () => Date;
 }
 export declare function chooseAccessRoute(routeSet: RouteSet, options: ChooseAccessRouteOptions): Promise<AccessRoute | null>;

package/dist/edge/reachability/ManagedRouteSelector.js

@@ -1,10 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.chooseAccessRoute = chooseAccessRoute;
+const RouteValidation_1 = require("./RouteValidation");
 async function chooseAccessRoute(routeSet, options) {
+    const now = (options.now ?? (() => new Date()))();
     const candidates = routeSet.routes
         .filter((route) => route.health !== 'unreachable')
         .filter((route) => options.managedClient || !route.requiresManagedClient)
+        // Expired and loopback-only access points are dropped before any probe: the node
+        // advertises its own list, so validating it is the client's job (N06).
+        .filter((route) => (0, RouteValidation_1.routeUnusableReason)(route, { now, remoteClient: options.managedClient }) === undefined)
         .slice()
         .sort((left, right) => left.priority - right.priority || left.id.localeCompare(right.id));
     if (candidates.length === 0) {
@@ -30,21 +35,11 @@ async function probeWithTimeout(route, probe, timeoutMs) {
         clearTimeout(timeout);
     }
 }
-/**
- * Same rule as the client transport's probe (`@undefineds.co/solid-sdk/access-route`):
- * a route answers when its host completed the HTTP exchange without failing. A
- * host that returns 404/405/501 for `/.well-known/solid` does not implement that
- * optional discovery path and is still serving the route; only a failing host
- * (5xx, closed socket) reports no route.
- */
+/** Require the shared Solid identity probe even when discovery returns an unsupported-method status. */
 async function defaultProbe(route, signal) {
-    if (!route.targetUrl.startsWith('http://') && !route.targetUrl.startsWith('https://')) {
+    if (!(0, RouteValidation_1.isHttpTarget)(route.targetUrl)) {
         return route.health === 'healthy';
     }
-    const response = await fetch(new URL('/.well-known/solid', route.targetUrl), {
-        method: 'HEAD',
-        signal,
-    });
-    return response.status < 500;
+    return await (0, RouteValidation_1.probeSolidWellKnown)(route.targetUrl, signal);
 }
 //# sourceMappingURL=ManagedRouteSelector.js.map

package/dist/edge/reachability/ManagedRouteSelector.jsonld

@@ -21,6 +21,10 @@
         {
           "@id": "undefineds:dist/edge/reachability/ManagedRouteSelector.jsonld#ChooseAccessRouteOptions__member_probe",
           "memberFieldName": "probe"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/ManagedRouteSelector.jsonld#ChooseAccessRouteOptions__member_now",
+          "memberFieldName": "now"
         }
       ],
       "constructorArguments": []

package/dist/edge/reachability/P2PDataPlane.d.ts

@@ -1,5 +1,36 @@
 import type { AccessRoute } from './types';
 export declare const XPOD_P2P_HTTP_PROTOCOL: "xpod-p2p-http/1";
+/**
+ * Resource ceilings for the P2P data plane (audit N17).
+ *
+ * The data plane is a byte pipe between two processes, so every unbounded quantity on it is a
+ * denial-of-service waiting to happen: a single line that never ends, a body that never stops,
+ * or a peer that opens more requests than the other side can serve. The numbers are deliberately
+ * generous for Pod traffic and small enough to fail fast.
+ */
+export declare const P2P_DATA_PLANE_LIMITS: {
+    /** Largest single wire line (one JSON envelope, base64 included). */
+    readonly maxFrameBytes: number;
+    /** Largest request or response body carried inside frames. */
+    readonly maxBodyBytes: number;
+    /** In-flight requests allowed per transport and per socket. */
+    readonly maxConcurrentRequests: 16;
+    /** Chunk size used when a response body is streamed. */
+    readonly chunkBytes: number;
+};
+export type P2PDataPlaneLimit = keyof typeof P2P_DATA_PLANE_LIMITS;
+/** Exceeding a ceiling is its own error so callers can answer 413/429 instead of a generic 502. */
+export declare class P2PDataPlaneLimitError extends Error {
+    readonly limit: P2PDataPlaneLimit;
+    constructor(message: string, limit: P2PDataPlaneLimit);
+}
+/** The caller aborted: the request may still be running on the peer until the cancel lands. */
+export declare class P2PDataPlaneAbortError extends Error {
+    constructor(message?: string);
+}
+/** Header a client sets to say it can consume chunked (streamed) response bodies. */
+export declare const XPOD_P2P_ACCEPT_HEADER: "x-xpod-p2p-accept";
+export declare const XPOD_P2P_ACCEPT_CHUNKED: "chunked";
 export type P2PHttpProtocol = typeof XPOD_P2P_HTTP_PROTOCOL;
 export type P2PHttpHeaderList = [string, string][];
 export interface P2PHttpRequestFrame {
@@ -17,21 +48,53 @@ export interface P2PHttpResponseFrame {
     statusText?: string;
     headers?: P2PHttpHeaderList;
     bodyBase64?: string;
+    /**
+     * Set when the head (status/headers) was delivered before the body finished: `bodyBase64` is
+     * then absent, every chunk follows through the transport's chunk callback, and the end of the
+     * body arrives with the transport's end callback.
+     */
+    streamed?: boolean;
+    /** Present instead of `bodyBase64` when the requester accepts a streamed body. */
+    bodyStream?: ReadableStream<Uint8Array>;
+}
+export interface P2PDataPlaneRequestOptions {
+    /** Aborting removes the pending request and tells the peer to stop working on it. */
+    signal?: AbortSignal;
+    /** Receives every body chunk of a streamed response, in order. */
+    onChunk?: (chunk: Uint8Array) => void;
+    /** Called once the body of a streamed response is complete. */
+    onEnd?: () => void;
+    /** Called when a streamed body fails after its head was already delivered. */
+    onError?: (error: Error) => void;
 }
 export interface P2PDataPlaneTransport {
-    request(frame: P2PHttpRequestFrame): Promise<P2PHttpResponseFrame>;
+    /**
+     * True when the transport understands chunk/end envelopes. A transport that does not must
+     * never be sent a streaming request: it would drop the body and answer an empty 200.
+     */
+    readonly supportsStreaming?: boolean;
+    request(frame: P2PHttpRequestFrame, options?: P2PDataPlaneRequestOptions): Promise<P2PHttpResponseFrame>;
+}
+export interface P2PDataPlaneLimitsOptions {
+    maxFrameBytes?: number;
+    maxBodyBytes?: number;
+    maxConcurrentRequests?: number;
 }
-export interface P2PDataPlaneFetchOptions {
+export interface P2PDataPlaneFetchOptions extends P2PDataPlaneLimitsOptions {
     route: AccessRoute;
     transport: P2PDataPlaneTransport;
 }
-export interface P2PDataPlaneHandlerOptions {
+export interface P2PDataPlaneHandlerOptions extends P2PDataPlaneLimitsOptions {
     targetBaseUrl: string | URL;
     fetchImpl?: typeof fetch;
 }
 export interface P2PDataPlaneHandler {
-    handleRequest(frame: P2PHttpRequestFrame): Promise<P2PHttpResponseFrame>;
+    handleRequest(frame: P2PHttpRequestFrame, options?: {
+        signal?: AbortSignal;
+    }): Promise<P2PHttpResponseFrame>;
 }
 export type P2PDataPlaneFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 export declare function createP2PDataPlaneFetch(options: P2PDataPlaneFetchOptions): P2PDataPlaneFetch;
 export declare function createP2PDataPlaneHandler(options: P2PDataPlaneHandlerOptions): P2PDataPlaneHandler;
+/** Decoded size of a base64 payload without allocating the buffer. */
+export declare function base64ByteLength(value: string): number;