@undefineds.co/xpod 0.1.0-local.202602081751

package/dist/edge/EdgeNodeHealthProbeService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EdgeNodeHealthProbeService.js","sourceRoot":"","sources":["../../src/edge/EdgeNodeHealthProbeService.ts"],"names":[],"mappings":"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","sourcesContent":["import { getLoggerFor } from 'global-logger-factory';\nimport { getIdentityDatabase } from '../identity/drizzle/db';\nimport { EdgeNodeRepository } from '../identity/drizzle/EdgeNodeRepository';\n\ninterface EdgeNodeHealthProbeServiceOptions {\n  repository?: EdgeNodeRepository;\n  identityDbUrl?: string;\n  enabled?: boolean | string;\n  timeoutMs?: number | string;\n  locations?: string | string[];\n}\n\ninterface ProbeResult {\n  location: string;\n  candidate: string;\n  success: boolean;\n  latencyMs?: number;\n  error?: string;\n  checkedAt: string;\n}\n\ninterface ProbeLocation {\n  name: string;\n  endpoint?: string;\n}\n\nexport class EdgeNodeHealthProbeService {\n  private readonly logger = getLoggerFor(this);\n  private readonly repository?: EdgeNodeRepository;\n  private readonly enabled: boolean;\n  private readonly timeoutMs: number;\n  private readonly locations: ProbeLocation[];\n\n  public constructor(options: EdgeNodeHealthProbeServiceOptions) {\n    this.repository = options.repository ?? this.createRepository(options.identityDbUrl);\n    this.enabled = this.normalizeBoolean(options.enabled) && Boolean(this.repository);\n    this.timeoutMs = this.normalizeTimeout(options.timeoutMs) ?? 3_000;\n    this.locations = this.normalizeLocations(options.locations);\n  }\n\n  public async probeNode(nodeId: string): Promise<void> {\n    if (!this.enabled) {\n      return;\n    }\n    const node = await this.repository!.getNodeMetadata(nodeId);\n    if (!node?.metadata) {\n      this.logger.debug(`节点 ${nodeId} 无 metadata，跳过探测。`);\n      return;\n    }\n    const metadata = node.metadata as Record<string, unknown>;\n    const candidates = this.collectCandidates(metadata);\n    if (candidates.length === 0) {\n      this.logger.debug(`节点 ${nodeId} 没有可探测的候选地址。`);\n      return;\n    }\n\n    const results: ProbeResult[] = [];\n    for (const candidate of candidates) {\n      for (const location of this.locations) {\n        const result = await this.ping(candidate, location);\n        results.push(result);\n      }\n    }\n\n    const successful = results.find((item) => item.success);\n    const clusterSuccess = results.some((item) => item.location === 'cluster' && item.success);\n    const status = clusterSuccess ? 'direct' : successful ? 'degraded' : 'unreachable';\n    const now = new Date();\n    const reachability = {\n      status,\n      lastProbeAt: now.toISOString(),\n      lastSuccessAt: successful ? successful.checkedAt : undefined,\n      samples: results,\n    };\n\n    await this.repository!.mergeNodeMetadata(nodeId, { reachability });\n  }\n\n  private collectCandidates(metadata: Record<string, unknown>): string[] {\n    const candidates = new Set<string>();\n    const direct = (metadata.directCandidates as string[] | undefined) ?? [];\n    for (const candidate of direct) {\n      if (typeof candidate === 'string' && candidate.trim().length > 0) {\n        candidates.add(candidate.trim());\n      }\n    }\n    if (typeof metadata.publicAddress === 'string') {\n      candidates.add(metadata.publicAddress.trim());\n    }\n    if (typeof metadata.baseUrl === 'string') {\n      candidates.add(metadata.baseUrl.trim());\n    }\n    return Array.from(candidates);\n  }\n\n  private async ping(candidate: string, location: ProbeLocation): Promise<ProbeResult> {\n    const url = this.toUrl(candidate);\n    if (!url) {\n      return { candidate, success: false, error: 'invalid-url', location: location.name, checkedAt: new Date().toISOString() };\n    }\n\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeoutMs);\n    const started = Date.now();\n    try {\n      if (location.endpoint) {\n        const probeUrl = new URL(location.endpoint);\n        probeUrl.searchParams.set('target', url.toString());\n        const response = await fetch(probeUrl.toString(), {\n          method: 'GET',\n          signal: controller.signal,\n          headers: { 'accept': 'application/json' },\n        });\n        clearTimeout(timer);\n        const latencyMs = Date.now() - started;\n        if (!response.ok) {\n          return {\n            candidate,\n            location: location.name,\n            success: false,\n            latencyMs,\n            error: `status:${response.status}`,\n            checkedAt: new Date().toISOString(),\n          };\n        }\n        try {\n          const data = await response.json() as Partial<ProbeResult>;\n          return {\n            candidate,\n            location: location.name,\n            success: Boolean(data.success),\n            latencyMs: typeof data.latencyMs === 'number' ? data.latencyMs : latencyMs,\n            error: data.error,\n            checkedAt: data.checkedAt ?? new Date().toISOString(),\n          };\n        } catch (error: unknown) {\n          return {\n            candidate,\n            location: location.name,\n            success: false,\n            latencyMs,\n            error: `invalid-json:${(error as Error).message}`,\n            checkedAt: new Date().toISOString(),\n          };\n        }\n      }\n      const response = await fetch(url.toString(), {\n        method: 'HEAD',\n        signal: controller.signal,\n      });\n      clearTimeout(timer);\n      const latencyMs = Date.now() - started;\n      return {\n        candidate,\n        location: location.name,\n        success: response.ok,\n        latencyMs,\n        error: response.ok ? undefined : `status:${response.status}`,\n        checkedAt: new Date().toISOString(),\n      };\n    } catch (error: unknown) {\n      clearTimeout(timer);\n      return {\n        candidate,\n        location: location.name,\n        success: false,\n        error: (error as Error).message,\n        checkedAt: new Date().toISOString(),\n      };\n    }\n  }\n\n  private toUrl(value: string): URL | undefined {\n    try {\n      return new URL(value);\n    } catch {\n      try {\n        return new URL(`https://${value}`);\n      } catch {\n        return undefined;\n      }\n    }\n  }\n\n  private createRepository(identityDbUrl?: string): EdgeNodeRepository | undefined {\n    if (!identityDbUrl) {\n      return undefined;\n    }\n    const db = getIdentityDatabase(identityDbUrl);\n    return new EdgeNodeRepository(db);\n  }\n\n  private normalizeBoolean(value?: boolean | string): boolean {\n    if (typeof value === 'boolean') {\n      return value;\n    }\n    if (typeof value === 'string') {\n      const normalized = value.trim().toLowerCase();\n      return normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on';\n    }\n    return false;\n  }\n\n  private normalizeTimeout(value?: number | string): number | undefined {\n    if (typeof value === 'number' && Number.isFinite(value) && value > 0) {\n      return Math.trunc(value);\n    }\n    if (typeof value === 'string') {\n      const parsed = Number(value.trim());\n      if (Number.isFinite(parsed) && parsed > 0) {\n        return Math.trunc(parsed);\n      }\n    }\n    return undefined;\n  }\n\n  private normalizeLocations(value?: string | string[]): ProbeLocation[] {\n    const defaultLocation: ProbeLocation = { name: 'cluster' };\n    if (value === undefined) {\n      return [ defaultLocation ];\n    }\n    const input = Array.isArray(value) ? value : value.split(/[,;\\n]+/u);\n    const result: ProbeLocation[] = [];\n    for (const entry of input) {\n      const trimmed = entry.trim();\n      if (trimmed.length === 0) {\n        continue;\n      }\n      const [ namePart, endpointPart ] = trimmed.split('@', 2);\n      const name = namePart.trim() || 'cluster';\n      const endpoint = endpointPart?.trim();\n      result.push({\n        name,\n        endpoint: endpoint?.length ? endpoint : undefined,\n      });\n    }\n    return result.length > 0 ? result : [ defaultLocation ];\n  }\n}\n"]}

package/dist/edge/EdgeNodeHealthProbeService.jsonld

@@ -0,0 +1,176 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService",
+      "@type": "Class",
+      "requireElement": "EdgeNodeHealthProbeService",
+      "parameters": [
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_repository",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "undefineds:dist/identity/drizzle/EdgeNodeRepository.jsonld#EdgeNodeRepository",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          }
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_identityDbUrl",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:string",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          }
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_enabled",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:boolean",
+              "xsd:string",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          }
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_timeoutMs",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:number",
+              "xsd:string",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          }
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_locations",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:string",
+              {
+                "@type": "ParameterRangeArray",
+                "parameterRangeValue": "xsd:string"
+              },
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          }
+        }
+      ],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_logger",
+          "memberFieldName": "logger"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_repository",
+          "memberFieldName": "repository"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_enabled",
+          "memberFieldName": "enabled"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_timeoutMs",
+          "memberFieldName": "timeoutMs"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_locations",
+          "memberFieldName": "locations"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_constructor",
+          "memberFieldName": "constructor"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_probeNode",
+          "memberFieldName": "probeNode"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_collectCandidates",
+          "memberFieldName": "collectCandidates"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_ping",
+          "memberFieldName": "ping"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_toUrl",
+          "memberFieldName": "toUrl"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_createRepository",
+          "memberFieldName": "createRepository"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_normalizeBoolean",
+          "memberFieldName": "normalizeBoolean"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_normalizeTimeout",
+          "memberFieldName": "normalizeTimeout"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_normalizeLocations",
+          "memberFieldName": "normalizeLocations"
+        }
+      ],
+      "constructorArguments": [
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options__constructorArgument",
+          "fields": [
+            {
+              "keyRaw": "repository",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_repository"
+              }
+            },
+            {
+              "keyRaw": "identityDbUrl",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_identityDbUrl"
+              }
+            },
+            {
+              "keyRaw": "enabled",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_enabled"
+              }
+            },
+            {
+              "keyRaw": "timeoutMs",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_timeoutMs"
+              }
+            },
+            {
+              "keyRaw": "locations",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_locations"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/dist/edge/EdgeNodeModeDetector.d.ts

@@ -0,0 +1,50 @@
+export interface NodeRegistrationInfo {
+    nodeId: string;
+    publicIp?: string;
+    publicIpv6?: string;
+    publicPort?: number;
+    capabilities: NodeCapabilities;
+}
+export interface NodeCapabilities {
+    solidProtocolVersion?: string;
+    storageBackends?: string[];
+    authMethods?: string[];
+    maxBandwidth?: number;
+    supportedModes?: ('direct' | 'proxy')[];
+    location?: {
+        country?: string;
+        region?: string;
+        coordinates?: {
+            lat: number;
+            lon: number;
+        };
+    };
+}
+export interface ModeDetectionResult {
+    accessMode: 'direct' | 'proxy';
+    reason: string;
+    subdomain: string;
+    connectivityTest?: {
+        success: boolean;
+        latency?: number;
+        error?: string;
+    };
+}
+export interface EdgeNodeModeDetectorOptions {
+    baseDomain: string;
+    connectivityTimeoutMs?: number;
+    maxDirectModeAttempts?: number;
+}
+export declare class EdgeNodeModeDetector {
+    private readonly logger;
+    private readonly baseDomain;
+    private readonly connectivityTimeoutMs;
+    private readonly maxDirectModeAttempts;
+    constructor(options: EdgeNodeModeDetectorOptions);
+    detectMode(nodeInfo: NodeRegistrationInfo): Promise<ModeDetectionResult>;
+    private generateSubdomain;
+    private testDirectConnectivity;
+    private singleConnectivityAttempt;
+    recheckMode(currentMode: string, nodeInfo: NodeRegistrationInfo): Promise<ModeDetectionResult | null>;
+    private extractSupportedModes;
+}

package/dist/edge/EdgeNodeModeDetector.js

@@ -0,0 +1,194 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EdgeNodeModeDetector = void 0;
+const global_logger_factory_1 = require("global-logger-factory");
+class EdgeNodeModeDetector {
+    constructor(options) {
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        this.baseDomain = options.baseDomain;
+        this.connectivityTimeoutMs = options.connectivityTimeoutMs ?? 3000;
+        this.maxDirectModeAttempts = Math.max(1, options.maxDirectModeAttempts ?? 1);
+    }
+    async detectMode(nodeInfo) {
+        const subdomain = this.generateSubdomain(nodeInfo.nodeId);
+        const supportedModes = this.extractSupportedModes(nodeInfo.capabilities);
+        const supportsDirect = supportedModes.has('direct');
+        const supportsProxy = supportedModes.has('proxy');
+        // Prefer direct if supported and has public IP (IPv6 or IPv4)
+        const hasPublicIp = Boolean(nodeInfo.publicIp || nodeInfo.publicIpv6);
+        let connectivityTest;
+        if (supportsDirect && hasPublicIp) {
+            // 优先测试 IPv6 连通性
+            const ipToTest = nodeInfo.publicIpv6 ?? nodeInfo.publicIp;
+            const port = nodeInfo.publicPort ?? 443;
+            connectivityTest = await this.testDirectConnectivity(ipToTest, port);
+            if (connectivityTest.success) {
+                this.logger.info(`Node ${nodeInfo.nodeId} is directly reachable at ${ipToTest}:${port}`);
+                return {
+                    accessMode: 'direct',
+                    reason: `Direct connectivity test passed (${nodeInfo.publicIpv6 ? 'IPv6' : 'IPv4'})`,
+                    subdomain,
+                    connectivityTest,
+                };
+            }
+            // 如果 IPv6 测试失败且有 IPv4，尝试 IPv4
+            if (nodeInfo.publicIpv6 && nodeInfo.publicIp) {
+                this.logger.debug(`IPv6 connectivity failed for ${nodeInfo.nodeId}, trying IPv4...`);
+                connectivityTest = await this.testDirectConnectivity(nodeInfo.publicIp, port);
+                if (connectivityTest.success) {
+                    this.logger.info(`Node ${nodeInfo.nodeId} is directly reachable via IPv4 at ${nodeInfo.publicIp}:${port}`);
+                    return {
+                        accessMode: 'direct',
+                        reason: 'Direct connectivity test passed (IPv4 fallback)',
+                        subdomain,
+                        connectivityTest,
+                    };
+                }
+            }
+            this.logger.info(`Node ${nodeInfo.nodeId} is not directly reachable, will fall back to proxy if available: ${connectivityTest.error}`);
+            if (!supportsProxy) {
+                return {
+                    accessMode: 'direct',
+                    reason: `Direct connectivity failed and proxy not supported: ${connectivityTest.error}`,
+                    subdomain,
+                    connectivityTest,
+                };
+            }
+        }
+        // Direct not available or failed; if proxy supported, use proxy mode
+        if (supportsProxy) {
+            return {
+                accessMode: 'proxy',
+                reason: supportsDirect && hasPublicIp ? 'Direct connectivity failed, using proxy' : 'Direct not available, using proxy',
+                subdomain,
+                connectivityTest,
+            };
+        }
+        // Neither direct nor proxy viable
+        return {
+            accessMode: supportsDirect ? 'direct' : 'proxy',
+            reason: supportsDirect ? 'Direct mode only; no proxy configured' : 'Proxy only; no direct available',
+            subdomain,
+        };
+    }
+    generateSubdomain(nodeId) {
+        // Generate a unique subdomain based on node ID
+        // For now, use a simple approach - in production you might want more sophisticated logic
+        const sanitized = nodeId.replace(/[^a-zA-Z0-9-]/g, '').toLowerCase();
+        return `${sanitized}.${this.baseDomain}`;
+    }
+    async testDirectConnectivity(ip, port) {
+        let lastResult = await this.singleConnectivityAttempt(ip, port);
+        if (lastResult.success || this.maxDirectModeAttempts === 1) {
+            return lastResult;
+        }
+        for (let attempt = 2; attempt <= this.maxDirectModeAttempts; attempt++) {
+            lastResult = await this.singleConnectivityAttempt(ip, port);
+            if (lastResult.success) {
+                return lastResult;
+            }
+        }
+        return lastResult;
+    }
+    async singleConnectivityAttempt(ip, port) {
+        const net = await Promise.resolve().then(() => __importStar(require('node:net')));
+        return new Promise((resolve) => {
+            const startTime = Date.now();
+            const socket = new net.Socket();
+            const cleanup = () => {
+                socket.destroy();
+            };
+            const timeout = setTimeout(() => {
+                cleanup();
+                resolve({
+                    success: false,
+                    error: `Connection timeout after ${this.connectivityTimeoutMs}ms`,
+                });
+            }, this.connectivityTimeoutMs);
+            socket.on('connect', () => {
+                clearTimeout(timeout);
+                const latency = Date.now() - startTime;
+                cleanup();
+                resolve({
+                    success: true,
+                    latency,
+                });
+            });
+            socket.on('error', (error) => {
+                clearTimeout(timeout);
+                cleanup();
+                resolve({
+                    success: false,
+                    error: error.message,
+                });
+            });
+            try {
+                socket.connect(port, ip);
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                cleanup();
+                resolve({
+                    success: false,
+                    error: error instanceof Error ? error.message : 'Unknown connection error',
+                });
+            }
+        });
+    }
+    async recheckMode(currentMode, nodeInfo) {
+        // Only recheck if currently in proxy mode and public IP is available
+        const supportedModes = this.extractSupportedModes(nodeInfo.capabilities);
+        if (currentMode !== 'proxy' || !nodeInfo.publicIp || !supportedModes.has('direct')) {
+            return null;
+        }
+        const connectivityTest = await this.testDirectConnectivity(nodeInfo.publicIp, nodeInfo.publicPort ?? 443);
+        if (connectivityTest.success) {
+            const subdomain = this.generateSubdomain(nodeInfo.nodeId);
+            this.logger.info(`Node ${nodeInfo.nodeId} connectivity restored, switching to direct mode`);
+            return {
+                accessMode: 'direct',
+                reason: 'Direct connectivity restored',
+                subdomain,
+                connectivityTest,
+            };
+        }
+        return null;
+    }
+    extractSupportedModes(capabilities) {
+        const modes = new Set();
+        const rawModes = capabilities.supportedModes ?? ['direct', 'proxy'];
+        for (const mode of rawModes) {
+            modes.add(mode);
+        }
+        if (modes.size === 0) {
+            modes.add('direct');
+            modes.add('proxy');
+        }
+        return modes;
+    }
+}
+exports.EdgeNodeModeDetector = EdgeNodeModeDetector;
+//# sourceMappingURL=EdgeNodeModeDetector.js.map

package/dist/edge/EdgeNodeModeDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EdgeNodeModeDetector.js","sourceRoot":"","sources":["../../src/edge/EdgeNodeModeDetector.ts"],"names":[],"mappings":"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","sourcesContent":["import { getLoggerFor } from 'global-logger-factory';\n\nexport interface NodeRegistrationInfo {\n  nodeId: string;\n  publicIp?: string;\n  publicIpv6?: string;\n  publicPort?: number;\n  capabilities: NodeCapabilities;\n}\n\nexport interface NodeCapabilities {\n  solidProtocolVersion?: string;\n  storageBackends?: string[];\n  authMethods?: string[];\n  maxBandwidth?: number;\n  supportedModes?: ('direct' | 'proxy')[];\n  location?: {\n    country?: string;\n    region?: string;\n    coordinates?: { lat: number; lon: number };\n  };\n}\n\nexport interface ModeDetectionResult {\n  accessMode: 'direct' | 'proxy';\n  reason: string;\n  subdomain: string;\n  connectivityTest?: {\n    success: boolean;\n    latency?: number;\n    error?: string;\n  };\n}\n\nexport interface EdgeNodeModeDetectorOptions {\n  baseDomain: string;\n  connectivityTimeoutMs?: number;\n  maxDirectModeAttempts?: number;\n}\n\nexport class EdgeNodeModeDetector {\n  private readonly logger = getLoggerFor(this);\n  private readonly baseDomain: string;\n  private readonly connectivityTimeoutMs: number;\n  private readonly maxDirectModeAttempts: number;\n\n  public constructor(options: EdgeNodeModeDetectorOptions) {\n    this.baseDomain = options.baseDomain;\n    this.connectivityTimeoutMs = options.connectivityTimeoutMs ?? 3000;\n    this.maxDirectModeAttempts = Math.max(1, options.maxDirectModeAttempts ?? 1);\n  }\n\n  public async detectMode(nodeInfo: NodeRegistrationInfo): Promise<ModeDetectionResult> {\n    const subdomain = this.generateSubdomain(nodeInfo.nodeId);\n    const supportedModes = this.extractSupportedModes(nodeInfo.capabilities);\n    const supportsDirect = supportedModes.has('direct');\n    const supportsProxy = supportedModes.has('proxy');\n\n    // Prefer direct if supported and has public IP (IPv6 or IPv4)\n    const hasPublicIp = Boolean(nodeInfo.publicIp || nodeInfo.publicIpv6);\n    let connectivityTest: { success: boolean; latencyMs?: number; error?: string } | undefined;\n\n    if (supportsDirect && hasPublicIp) {\n      // 优先测试 IPv6 连通性\n      const ipToTest = nodeInfo.publicIpv6 ?? nodeInfo.publicIp!;\n      const port = nodeInfo.publicPort ?? 443;\n      \n      connectivityTest = await this.testDirectConnectivity(ipToTest, port);\n\n      if (connectivityTest.success) {\n        this.logger.info(`Node ${nodeInfo.nodeId} is directly reachable at ${ipToTest}:${port}`);\n        return {\n          accessMode: 'direct',\n          reason: `Direct connectivity test passed (${nodeInfo.publicIpv6 ? 'IPv6' : 'IPv4'})`,\n          subdomain,\n          connectivityTest,\n        };\n      }\n      \n      // 如果 IPv6 测试失败且有 IPv4，尝试 IPv4\n      if (nodeInfo.publicIpv6 && nodeInfo.publicIp) {\n        this.logger.debug(`IPv6 connectivity failed for ${nodeInfo.nodeId}, trying IPv4...`);\n        connectivityTest = await this.testDirectConnectivity(nodeInfo.publicIp, port);\n        \n        if (connectivityTest.success) {\n          this.logger.info(`Node ${nodeInfo.nodeId} is directly reachable via IPv4 at ${nodeInfo.publicIp}:${port}`);\n          return {\n            accessMode: 'direct',\n            reason: 'Direct connectivity test passed (IPv4 fallback)',\n            subdomain,\n            connectivityTest,\n          };\n        }\n      }\n\n      this.logger.info(`Node ${nodeInfo.nodeId} is not directly reachable, will fall back to proxy if available: ${connectivityTest.error}`);\n      if (!supportsProxy) {\n        return {\n          accessMode: 'direct',\n          reason: `Direct connectivity failed and proxy not supported: ${connectivityTest.error}`,\n          subdomain,\n          connectivityTest,\n        };\n      }\n    }\n\n    // Direct not available or failed; if proxy supported, use proxy mode\n    if (supportsProxy) {\n      return {\n        accessMode: 'proxy',\n        reason: supportsDirect && hasPublicIp ? 'Direct connectivity failed, using proxy' : 'Direct not available, using proxy',\n        subdomain,\n        connectivityTest,\n      };\n    }\n\n    // Neither direct nor proxy viable\n    return {\n      accessMode: supportsDirect ? 'direct' : 'proxy',\n      reason: supportsDirect ? 'Direct mode only; no proxy configured' : 'Proxy only; no direct available',\n      subdomain,\n    };\n  }\n\n  private generateSubdomain(nodeId: string): string {\n    // Generate a unique subdomain based on node ID\n    // For now, use a simple approach - in production you might want more sophisticated logic\n    const sanitized = nodeId.replace(/[^a-zA-Z0-9-]/g, '').toLowerCase();\n    return `${sanitized}.${this.baseDomain}`;\n  }\n\n  private async testDirectConnectivity(ip: string, port: number): Promise<{\n    success: boolean;\n    latency?: number;\n    error?: string;\n  }> {\n    let lastResult = await this.singleConnectivityAttempt(ip, port);\n    if (lastResult.success || this.maxDirectModeAttempts === 1) {\n      return lastResult;\n    }\n\n    for (let attempt = 2; attempt <= this.maxDirectModeAttempts; attempt++) {\n      lastResult = await this.singleConnectivityAttempt(ip, port);\n      if (lastResult.success) {\n        return lastResult;\n      }\n    }\n    return lastResult;\n  }\n\n  private async singleConnectivityAttempt(ip: string, port: number): Promise<{\n    success: boolean;\n    latency?: number;\n    error?: string;\n  }> {\n    const net = await import('node:net');\n\n    return new Promise((resolve) => {\n      const startTime = Date.now();\n      const socket = new net.Socket();\n\n      const cleanup = (): void => {\n        socket.destroy();\n      };\n\n      const timeout = setTimeout(() => {\n        cleanup();\n        resolve({\n          success: false,\n          error: `Connection timeout after ${this.connectivityTimeoutMs}ms`,\n        });\n      }, this.connectivityTimeoutMs);\n\n      socket.on('connect', () => {\n        clearTimeout(timeout);\n        const latency = Date.now() - startTime;\n        cleanup();\n        resolve({\n          success: true,\n          latency,\n        });\n      });\n\n      socket.on('error', (error) => {\n        clearTimeout(timeout);\n        cleanup();\n        resolve({\n          success: false,\n          error: error.message,\n        });\n      });\n\n      try {\n        socket.connect(port, ip);\n      } catch (error) {\n        clearTimeout(timeout);\n        cleanup();\n        resolve({\n          success: false,\n          error: error instanceof Error ? error.message : 'Unknown connection error',\n        });\n      }\n    });\n  }\n\n  public async recheckMode(currentMode: string, nodeInfo: NodeRegistrationInfo): Promise<ModeDetectionResult | null> {\n    // Only recheck if currently in proxy mode and public IP is available\n    const supportedModes = this.extractSupportedModes(nodeInfo.capabilities);\n    if (currentMode !== 'proxy' || !nodeInfo.publicIp || !supportedModes.has('direct')) {\n      return null;\n    }\n\n    const connectivityTest = await this.testDirectConnectivity(\n      nodeInfo.publicIp,\n      nodeInfo.publicPort ?? 443\n    );\n\n    if (connectivityTest.success) {\n      const subdomain = this.generateSubdomain(nodeInfo.nodeId);\n      this.logger.info(`Node ${nodeInfo.nodeId} connectivity restored, switching to direct mode`);\n      return {\n        accessMode: 'direct',\n        reason: 'Direct connectivity restored',\n        subdomain,\n        connectivityTest,\n      };\n    }\n\n    return null;\n  }\n\n  private extractSupportedModes(capabilities: NodeCapabilities): Set<string> {\n    const modes = new Set<string>();\n    const rawModes = capabilities.supportedModes ?? ['direct', 'proxy'];\n    \n    for (const mode of rawModes) {\n      modes.add(mode);\n    }\n    \n    if (modes.size === 0) {\n      modes.add('direct');\n      modes.add('proxy');\n    }\n    return modes;\n  }\n}\n"]}

package/dist/edge/EdgeNodeModeDetector.jsonld

@@ -0,0 +1,114 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector",
+      "@type": "Class",
+      "requireElement": "EdgeNodeModeDetector",
+      "parameters": [
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector_options_baseDomain",
+          "range": "xsd:string"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector_options_connectivityTimeoutMs",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:number",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          }
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector_options_maxDirectModeAttempts",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:number",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          }
+        }
+      ],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector__member_logger",
+          "memberFieldName": "logger"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector__member_baseDomain",
+          "memberFieldName": "baseDomain"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector__member_connectivityTimeoutMs",
+          "memberFieldName": "connectivityTimeoutMs"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector__member_maxDirectModeAttempts",
+          "memberFieldName": "maxDirectModeAttempts"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector__member_constructor",
+          "memberFieldName": "constructor"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector__member_detectMode",
+          "memberFieldName": "detectMode"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector__member_generateSubdomain",
+          "memberFieldName": "generateSubdomain"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector__member_testDirectConnectivity",
+          "memberFieldName": "testDirectConnectivity"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector__member_singleConnectivityAttempt",
+          "memberFieldName": "singleConnectivityAttempt"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector__member_recheckMode",
+          "memberFieldName": "recheckMode"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector__member_extractSupportedModes",
+          "memberFieldName": "extractSupportedModes"
+        }
+      ],
+      "constructorArguments": [
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector_options__constructorArgument",
+          "fields": [
+            {
+              "keyRaw": "baseDomain",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector_options_baseDomain"
+              }
+            },
+            {
+              "keyRaw": "connectivityTimeoutMs",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector_options_connectivityTimeoutMs"
+              }
+            },
+            {
+              "keyRaw": "maxDirectModeAttempts",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeModeDetector.jsonld#EdgeNodeModeDetector_options_maxDirectModeAttempts"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/dist/edge/EdgeNodeTunnelManager.d.ts

@@ -0,0 +1,23 @@
+import type { EdgeNodeTunnelManager } from './interfaces/EdgeNodeTunnelManager';
+interface SimpleEdgeNodeTunnelManagerOptions {
+    /** 当直连失败时兜底的入口地址列表。 */
+    entrypoints?: string | string[] | null;
+    /** 是否默认启用隧道。 */
+    enabled?: boolean;
+}
+export declare class SimpleEdgeNodeTunnelManager implements EdgeNodeTunnelManager {
+    private readonly logger;
+    private readonly entrypoints;
+    private readonly enabled;
+    constructor(options: SimpleEdgeNodeTunnelManagerOptions);
+    ensureConnectivity(nodeId: string, metadata: Record<string, unknown>): Promise<Record<string, unknown> | undefined>;
+    private selectEntrypoint;
+    private hashString;
+    private extractRecord;
+    private isRedirectHealthy;
+    private normalizeEntrypoints;
+}
+export declare class NoopEdgeNodeTunnelManager implements EdgeNodeTunnelManager {
+    ensureConnectivity(): Promise<Record<string, unknown> | undefined>;
+}
+export {};