@undefineds.co/xpod 0.1.0-local.202602081751

package/dist/subdomain/SubdomainService.d.ts

@@ -0,0 +1,114 @@
+import type { TunnelProvider, TunnelConfig } from '../tunnel/TunnelProvider';
+import type { DnsProvider } from '../dns/DnsProvider';
+/**
+ * 子域名注册信息
+ */
+export interface SubdomainRegistration {
+    /** 子域名 (如 mynode) */
+    subdomain: string;
+    /** 完整域名 (如 mynode.pods.undefieds.co) */
+    fullDomain: string;
+    /** 访问模式 */
+    mode: 'direct' | 'tunnel';
+    /** 公网 IP (直连模式) */
+    publicIp?: string;
+    /** 隧道配置 (隧道模式) */
+    tunnelConfig?: TunnelConfig;
+    /** 注册时间 */
+    registeredAt: Date;
+    /** 所有者 ID */
+    ownerId?: string;
+}
+/**
+ * 连通性检测结果
+ */
+export interface ConnectivityResult {
+    /** 是否可达 */
+    reachable: boolean;
+    /** 公网 IP */
+    publicIp?: string;
+    /** 延迟 (ms) */
+    latency?: number;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * SubdomainService 配置
+ */
+export interface SubdomainServiceOptions {
+    /** 基础域名 (如 pods.undefieds.co) */
+    baseDomain: string;
+    /** DNS Provider */
+    dnsProvider: DnsProvider;
+    /** Tunnel Provider */
+    tunnelProvider: TunnelProvider;
+    /** 连通性检测端点 (可选，用于回调检测) */
+    connectivityCheckEndpoint?: string;
+    /** 保留的子域名列表 */
+    reservedSubdomains?: string[];
+}
+/**
+ * 子域名管理服务
+ *
+ * 负责：
+ * 1. 子域名可用性检查
+ * 2. 连通性检测
+ * 3. 直连/隧道模式选择
+ * 4. DNS 记录管理
+ * 5. 隧道创建
+ */
+export declare class SubdomainService {
+    private readonly baseDomain;
+    private readonly dnsProvider;
+    private readonly tunnelProvider;
+    private readonly connectivityCheckEndpoint?;
+    private readonly reservedSubdomains;
+    /** 已注册的子域名 (内存缓存，后续可改为数据库) */
+    private registrations;
+    constructor(options: SubdomainServiceOptions);
+    /**
+     * 检查子域名是否可用
+     */
+    checkAvailability(subdomain: string): Promise<{
+        available: boolean;
+        reason?: string;
+    }>;
+    /**
+     * 注册子域名
+     */
+    register(options: {
+        subdomain: string;
+        localPort: number;
+        publicIp?: string;
+        ownerId?: string;
+    }): Promise<SubdomainRegistration>;
+    /**
+     * 释放子域名
+     */
+    release(subdomain: string): Promise<void>;
+    /**
+     * 获取注册信息
+     */
+    getRegistration(subdomain: string): SubdomainRegistration | undefined;
+    /**
+     * 获取所有注册
+     */
+    getAllRegistrations(): SubdomainRegistration[];
+    /**
+     * 启动隧道
+     */
+    startTunnel(subdomain: string): Promise<void>;
+    /**
+     * 停止隧道
+     */
+    stopTunnel(): Promise<void>;
+    /**
+     * 校验子域名格式
+     */
+    private isValidSubdomain;
+    /**
+     * 连通性检测
+     */
+    private checkConnectivity;
+    private isIpv6;
+}

package/dist/subdomain/SubdomainService.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubdomainService = void 0;
+/**
+ * 子域名管理服务
+ *
+ * 负责：
+ * 1. 子域名可用性检查
+ * 2. 连通性检测
+ * 3. 直连/隧道模式选择
+ * 4. DNS 记录管理
+ * 5. 隧道创建
+ */
+class SubdomainService {
+    constructor(options) {
+        /** 已注册的子域名 (内存缓存，后续可改为数据库) */
+        this.registrations = new Map();
+        this.baseDomain = options.baseDomain;
+        this.dnsProvider = options.dnsProvider;
+        this.tunnelProvider = options.tunnelProvider;
+        this.connectivityCheckEndpoint = options.connectivityCheckEndpoint;
+        this.reservedSubdomains = new Set(options.reservedSubdomains ?? [
+            'www', 'api', 'app', 'admin', 'mail', 'ftp', 'ssh',
+            'pods', 'center', 'edge', 'node', 'test', 'dev', 'staging',
+        ]);
+    }
+    /**
+     * 检查子域名是否可用
+     */
+    async checkAvailability(subdomain) {
+        // 1. 格式校验
+        if (!this.isValidSubdomain(subdomain)) {
+            return {
+                available: false,
+                reason: 'Invalid subdomain format. Use 3-63 lowercase letters, numbers, or hyphens.',
+            };
+        }
+        // 2. 保留名检查
+        if (this.reservedSubdomains.has(subdomain.toLowerCase())) {
+            return {
+                available: false,
+                reason: 'This subdomain is reserved.',
+            };
+        }
+        // 3. 已注册检查
+        if (this.registrations.has(subdomain.toLowerCase())) {
+            return {
+                available: false,
+                reason: 'This subdomain is already registered.',
+            };
+        }
+        return { available: true };
+    }
+    /**
+     * 注册子域名
+     */
+    async register(options) {
+        const { subdomain, localPort, publicIp, ownerId } = options;
+        const normalizedSubdomain = subdomain.toLowerCase();
+        // 1. 检查可用性
+        const availability = await this.checkAvailability(normalizedSubdomain);
+        if (!availability.available) {
+            throw new Error(availability.reason);
+        }
+        const fullDomain = `${normalizedSubdomain}.${this.baseDomain}`;
+        // 2. 连通性检测 (如果提供了公网 IP)
+        let mode = 'tunnel';
+        let verifiedIp;
+        if (publicIp) {
+            const connectivity = await this.checkConnectivity(publicIp, localPort);
+            // 如果可达，或者虽然不可达但我们是在 Local 模式且用户显式指定了 IP
+            // 这里可以放宽一点限制，因为有些网络环境可能单向不通但 DNS 应该先挂上去
+            if (connectivity.reachable) {
+                mode = 'direct';
+                verifiedIp = publicIp;
+            }
+        }
+        // 3. 根据模式设置 DNS 和隧道
+        let tunnelConfig;
+        if (mode === 'direct') {
+            const type = this.isIpv6(verifiedIp) ? 'AAAA' : 'A';
+            // 直连模式：创建 A 或 AAAA 记录
+            await this.dnsProvider.upsertRecord({
+                subdomain: normalizedSubdomain,
+                domain: this.baseDomain,
+                type,
+                value: verifiedIp,
+                ttl: 60,
+            });
+        }
+        else {
+            // 隧道模式：创建隧道 + CNAME
+            tunnelConfig = await this.tunnelProvider.setup({
+                subdomain: normalizedSubdomain,
+                localPort,
+            });
+        }
+        // 4. 保存注册信息
+        const registration = {
+            subdomain: normalizedSubdomain,
+            fullDomain,
+            mode,
+            publicIp: verifiedIp,
+            tunnelConfig,
+            registeredAt: new Date(),
+            ownerId,
+        };
+        this.registrations.set(normalizedSubdomain, registration);
+        return registration;
+    }
+    /**
+     * 释放子域名
+     */
+    async release(subdomain) {
+        const normalizedSubdomain = subdomain.toLowerCase();
+        const registration = this.registrations.get(normalizedSubdomain);
+        if (!registration) {
+            throw new Error('Subdomain not found');
+        }
+        // 1. 清理隧道
+        if (registration.tunnelConfig) {
+            await this.tunnelProvider.cleanup(registration.tunnelConfig);
+        }
+        // 2. 删除 DNS 记录 (尝试删除 A 和 CNAME 类型)
+        try {
+            await this.dnsProvider.deleteRecord({
+                subdomain: normalizedSubdomain,
+                domain: this.baseDomain,
+                type: registration.mode === 'direct' ? 'A' : 'CNAME',
+            });
+        }
+        catch (error) {
+            console.warn(`Failed to delete DNS record for ${normalizedSubdomain}:`, error);
+        }
+        // 3. 移除注册信息
+        this.registrations.delete(normalizedSubdomain);
+    }
+    /**
+     * 获取注册信息
+     */
+    getRegistration(subdomain) {
+        return this.registrations.get(subdomain.toLowerCase());
+    }
+    /**
+     * 获取所有注册
+     */
+    getAllRegistrations() {
+        return Array.from(this.registrations.values());
+    }
+    /**
+     * 启动隧道
+     */
+    async startTunnel(subdomain) {
+        const registration = this.registrations.get(subdomain.toLowerCase());
+        if (!registration) {
+            throw new Error('Subdomain not found');
+        }
+        if (registration.mode !== 'tunnel' || !registration.tunnelConfig) {
+            throw new Error('Subdomain is not in tunnel mode');
+        }
+        await this.tunnelProvider.start(registration.tunnelConfig);
+    }
+    /**
+     * 停止隧道
+     */
+    async stopTunnel() {
+        await this.tunnelProvider.stop();
+    }
+    // ============ 私有方法 ============
+    /**
+     * 校验子域名格式
+     */
+    isValidSubdomain(subdomain) {
+        // 3-63 字符，小写字母、数字、连字符，不能以连字符开头或结尾
+        const regex = /^[a-z0-9]([a-z0-9-]{1,61}[a-z0-9])?$/;
+        return regex.test(subdomain) && subdomain.length >= 3 && subdomain.length <= 63;
+    }
+    /**
+     * 连通性检测
+     */
+    async checkConnectivity(ip, port) {
+        try {
+            const start = Date.now();
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5000);
+            // IPv6 需要加中括号
+            const host = this.isIpv6(ip) ? `[${ip}]` : ip;
+            const response = await fetch(`http://${host}:${port}/.well-known/solid`, {
+                method: 'HEAD',
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            const latency = Date.now() - start;
+            return {
+                reachable: response.ok || response.status === 401,
+                publicIp: ip,
+                latency,
+            };
+        }
+        catch (error) {
+            return {
+                reachable: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+    isIpv6(ip) {
+        return ip.includes(':');
+    }
+}
+exports.SubdomainService = SubdomainService;
+//# sourceMappingURL=SubdomainService.js.map

package/dist/subdomain/SubdomainService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubdomainService.js","sourceRoot":"","sources":["../../src/subdomain/SubdomainService.ts"],"names":[],"mappings":"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","sourcesContent":["import type { TunnelProvider, TunnelConfig } from '../tunnel/TunnelProvider';\nimport type { DnsProvider } from '../dns/DnsProvider';\n\n/**\n * 子域名注册信息\n */\nexport interface SubdomainRegistration {\n  /** 子域名 (如 mynode) */\n  subdomain: string;\n\n  /** 完整域名 (如 mynode.pods.undefieds.co) */\n  fullDomain: string;\n\n  /** 访问模式 */\n  mode: 'direct' | 'tunnel';\n\n  /** 公网 IP (直连模式) */\n  publicIp?: string;\n\n  /** 隧道配置 (隧道模式) */\n  tunnelConfig?: TunnelConfig;\n\n  /** 注册时间 */\n  registeredAt: Date;\n\n  /** 所有者 ID */\n  ownerId?: string;\n}\n\n/**\n * 连通性检测结果\n */\nexport interface ConnectivityResult {\n  /** 是否可达 */\n  reachable: boolean;\n\n  /** 公网 IP */\n  publicIp?: string;\n\n  /** 延迟 (ms) */\n  latency?: number;\n\n  /** 错误信息 */\n  error?: string;\n}\n\n/**\n * SubdomainService 配置\n */\nexport interface SubdomainServiceOptions {\n  /** 基础域名 (如 pods.undefieds.co) */\n  baseDomain: string;\n\n  /** DNS Provider */\n  dnsProvider: DnsProvider;\n\n  /** Tunnel Provider */\n  tunnelProvider: TunnelProvider;\n\n  /** 连通性检测端点 (可选，用于回调检测) */\n  connectivityCheckEndpoint?: string;\n\n  /** 保留的子域名列表 */\n  reservedSubdomains?: string[];\n}\n\n/**\n * 子域名管理服务\n * \n * 负责：\n * 1. 子域名可用性检查\n * 2. 连通性检测\n * 3. 直连/隧道模式选择\n * 4. DNS 记录管理\n * 5. 隧道创建\n */\nexport class SubdomainService {\n  private readonly baseDomain: string;\n  private readonly dnsProvider: DnsProvider;\n  private readonly tunnelProvider: TunnelProvider;\n  private readonly connectivityCheckEndpoint?: string;\n  private readonly reservedSubdomains: Set<string>;\n\n  /** 已注册的子域名 (内存缓存，后续可改为数据库) */\n  private registrations: Map<string, SubdomainRegistration> = new Map();\n\n  constructor(options: SubdomainServiceOptions) {\n    this.baseDomain = options.baseDomain;\n    this.dnsProvider = options.dnsProvider;\n    this.tunnelProvider = options.tunnelProvider;\n    this.connectivityCheckEndpoint = options.connectivityCheckEndpoint;\n    this.reservedSubdomains = new Set(options.reservedSubdomains ?? [\n      'www', 'api', 'app', 'admin', 'mail', 'ftp', 'ssh',\n      'pods', 'center', 'edge', 'node', 'test', 'dev', 'staging',\n    ]);\n  }\n\n  /**\n   * 检查子域名是否可用\n   */\n  async checkAvailability(subdomain: string): Promise<{\n    available: boolean;\n    reason?: string;\n  }> {\n    // 1. 格式校验\n    if (!this.isValidSubdomain(subdomain)) {\n      return {\n        available: false,\n        reason: 'Invalid subdomain format. Use 3-63 lowercase letters, numbers, or hyphens.',\n      };\n    }\n\n    // 2. 保留名检查\n    if (this.reservedSubdomains.has(subdomain.toLowerCase())) {\n      return {\n        available: false,\n        reason: 'This subdomain is reserved.',\n      };\n    }\n\n    // 3. 已注册检查\n    if (this.registrations.has(subdomain.toLowerCase())) {\n      return {\n        available: false,\n        reason: 'This subdomain is already registered.',\n      };\n    }\n\n    return { available: true };\n  }\n\n  /**\n   * 注册子域名\n   */\n  async register(options: {\n    subdomain: string;\n    localPort: number;\n    publicIp?: string;\n    ownerId?: string;\n  }): Promise<SubdomainRegistration> {\n    const { subdomain, localPort, publicIp, ownerId } = options;\n    const normalizedSubdomain = subdomain.toLowerCase();\n\n    // 1. 检查可用性\n    const availability = await this.checkAvailability(normalizedSubdomain);\n    if (!availability.available) {\n      throw new Error(availability.reason);\n    }\n\n    const fullDomain = `${normalizedSubdomain}.${this.baseDomain}`;\n\n    // 2. 连通性检测 (如果提供了公网 IP)\n    let mode: 'direct' | 'tunnel' = 'tunnel';\n    let verifiedIp: string | undefined;\n\n    if (publicIp) {\n      const connectivity = await this.checkConnectivity(publicIp, localPort);\n      // 如果可达，或者虽然不可达但我们是在 Local 模式且用户显式指定了 IP\n      // 这里可以放宽一点限制，因为有些网络环境可能单向不通但 DNS 应该先挂上去\n      if (connectivity.reachable) {\n        mode = 'direct';\n        verifiedIp = publicIp;\n      }\n    }\n\n    // 3. 根据模式设置 DNS 和隧道\n    let tunnelConfig: TunnelConfig | undefined;\n\n    if (mode === 'direct') {\n      const type = this.isIpv6(verifiedIp!) ? 'AAAA' : 'A';\n      // 直连模式：创建 A 或 AAAA 记录\n      await this.dnsProvider.upsertRecord({\n        subdomain: normalizedSubdomain,\n        domain: this.baseDomain,\n        type,\n        value: verifiedIp!,\n        ttl: 60,\n      });\n    } else {\n      // 隧道模式：创建隧道 + CNAME\n      tunnelConfig = await this.tunnelProvider.setup({\n        subdomain: normalizedSubdomain,\n        localPort,\n      });\n    }\n\n    // 4. 保存注册信息\n    const registration: SubdomainRegistration = {\n      subdomain: normalizedSubdomain,\n      fullDomain,\n      mode,\n      publicIp: verifiedIp,\n      tunnelConfig,\n      registeredAt: new Date(),\n      ownerId,\n    };\n\n    this.registrations.set(normalizedSubdomain, registration);\n\n    return registration;\n  }\n\n  /**\n   * 释放子域名\n   */\n  async release(subdomain: string): Promise<void> {\n    const normalizedSubdomain = subdomain.toLowerCase();\n    const registration = this.registrations.get(normalizedSubdomain);\n\n    if (!registration) {\n      throw new Error('Subdomain not found');\n    }\n\n    // 1. 清理隧道\n    if (registration.tunnelConfig) {\n      await this.tunnelProvider.cleanup(registration.tunnelConfig);\n    }\n\n    // 2. 删除 DNS 记录 (尝试删除 A 和 CNAME 类型)\n    try {\n      await this.dnsProvider.deleteRecord({\n        subdomain: normalizedSubdomain,\n        domain: this.baseDomain,\n        type: registration.mode === 'direct' ? 'A' : 'CNAME',\n      });\n    } catch (error) {\n      console.warn(`Failed to delete DNS record for ${normalizedSubdomain}:`, error);\n    }\n\n    // 3. 移除注册信息\n    this.registrations.delete(normalizedSubdomain);\n  }\n\n  /**\n   * 获取注册信息\n   */\n  getRegistration(subdomain: string): SubdomainRegistration | undefined {\n    return this.registrations.get(subdomain.toLowerCase());\n  }\n\n  /**\n   * 获取所有注册\n   */\n  getAllRegistrations(): SubdomainRegistration[] {\n    return Array.from(this.registrations.values());\n  }\n\n  /**\n   * 启动隧道\n   */\n  async startTunnel(subdomain: string): Promise<void> {\n    const registration = this.registrations.get(subdomain.toLowerCase());\n\n    if (!registration) {\n      throw new Error('Subdomain not found');\n    }\n\n    if (registration.mode !== 'tunnel' || !registration.tunnelConfig) {\n      throw new Error('Subdomain is not in tunnel mode');\n    }\n\n    await this.tunnelProvider.start(registration.tunnelConfig);\n  }\n\n  /**\n   * 停止隧道\n   */\n  async stopTunnel(): Promise<void> {\n    await this.tunnelProvider.stop();\n  }\n\n  // ============ 私有方法 ============\n\n  /**\n   * 校验子域名格式\n   */\n  private isValidSubdomain(subdomain: string): boolean {\n    // 3-63 字符，小写字母、数字、连字符，不能以连字符开头或结尾\n    const regex = /^[a-z0-9]([a-z0-9-]{1,61}[a-z0-9])?$/;\n    return regex.test(subdomain) && subdomain.length >= 3 && subdomain.length <= 63;\n  }\n\n  /**\n   * 连通性检测\n   */\n  private async checkConnectivity(\n    ip: string,\n    port: number\n  ): Promise<ConnectivityResult> {\n    try {\n      const start = Date.now();\n      const controller = new AbortController();\n      const timeout = setTimeout(() => controller.abort(), 5000);\n\n      // IPv6 需要加中括号\n      const host = this.isIpv6(ip) ? `[${ip}]` : ip;\n      const response = await fetch(`http://${host}:${port}/.well-known/solid`, {\n        method: 'HEAD',\n        signal: controller.signal,\n      });\n\n      clearTimeout(timeout);\n\n      const latency = Date.now() - start;\n\n      return {\n        reachable: response.ok || response.status === 401,\n        publicIp: ip,\n        latency,\n      };\n    } catch (error) {\n      return {\n        reachable: false,\n        error: error instanceof Error ? error.message : 'Unknown error',\n      };\n    }\n  }\n\n  private isIpv6(ip: string): boolean {\n    return ip.includes(':');\n  }\n}\n"]}

package/dist/subdomain/SubdomainService.jsonld

@@ -0,0 +1,261 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainRegistration",
+      "@type": "AbstractClass",
+      "requireElement": "SubdomainRegistration",
+      "comment": "子域名注册信息",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainRegistration__member_subdomain",
+          "memberFieldName": "subdomain"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainRegistration__member_fullDomain",
+          "memberFieldName": "fullDomain"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainRegistration__member_mode",
+          "memberFieldName": "mode"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainRegistration__member_publicIp",
+          "memberFieldName": "publicIp"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainRegistration__member_tunnelConfig",
+          "memberFieldName": "tunnelConfig"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainRegistration__member_registeredAt",
+          "memberFieldName": "registeredAt"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainRegistration__member_ownerId",
+          "memberFieldName": "ownerId"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#ConnectivityResult",
+      "@type": "AbstractClass",
+      "requireElement": "ConnectivityResult",
+      "comment": "连通性检测结果",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#ConnectivityResult__member_reachable",
+          "memberFieldName": "reachable"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#ConnectivityResult__member_publicIp",
+          "memberFieldName": "publicIp"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#ConnectivityResult__member_latency",
+          "memberFieldName": "latency"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#ConnectivityResult__member_error",
+          "memberFieldName": "error"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainServiceOptions",
+      "@type": "AbstractClass",
+      "requireElement": "SubdomainServiceOptions",
+      "comment": "SubdomainService 配置",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainServiceOptions__member_baseDomain",
+          "memberFieldName": "baseDomain"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainServiceOptions__member_dnsProvider",
+          "memberFieldName": "dnsProvider"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainServiceOptions__member_tunnelProvider",
+          "memberFieldName": "tunnelProvider"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainServiceOptions__member_connectivityCheckEndpoint",
+          "memberFieldName": "connectivityCheckEndpoint"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainServiceOptions__member_reservedSubdomains",
+          "memberFieldName": "reservedSubdomains"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService",
+      "@type": "Class",
+      "requireElement": "SubdomainService",
+      "comment": "子域名管理服务  负责： 1. 子域名可用性检查 2. 连通性检测 3. 直连/隧道模式选择 4. DNS 记录管理 5. 隧道创建",
+      "parameters": [
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService_options_baseDomain",
+          "range": "xsd:string",
+          "comment": "基础域名 (如 pods.undefieds.co)"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService_options_dnsProvider",
+          "range": "undefineds:dist/dns/DnsProvider.jsonld#DnsProvider",
+          "comment": "DNS Provider"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService_options_tunnelProvider",
+          "range": "undefineds:dist/tunnel/TunnelProvider.jsonld#TunnelProvider",
+          "comment": "Tunnel Provider"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService_options_connectivityCheckEndpoint",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:string",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "连通性检测端点 (可选，用于回调检测)"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService_options_reservedSubdomains",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              {
+                "@type": "ParameterRangeArray",
+                "parameterRangeValue": "xsd:string"
+              },
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "保留的子域名列表"
+        }
+      ],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_baseDomain",
+          "memberFieldName": "baseDomain"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_dnsProvider",
+          "memberFieldName": "dnsProvider"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_tunnelProvider",
+          "memberFieldName": "tunnelProvider"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_connectivityCheckEndpoint",
+          "memberFieldName": "connectivityCheckEndpoint"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_reservedSubdomains",
+          "memberFieldName": "reservedSubdomains"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_registrations",
+          "memberFieldName": "registrations"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_constructor",
+          "memberFieldName": "constructor"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_checkAvailability",
+          "memberFieldName": "checkAvailability"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_register",
+          "memberFieldName": "register"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_release",
+          "memberFieldName": "release"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_getRegistration",
+          "memberFieldName": "getRegistration"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_getAllRegistrations",
+          "memberFieldName": "getAllRegistrations"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_startTunnel",
+          "memberFieldName": "startTunnel"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_stopTunnel",
+          "memberFieldName": "stopTunnel"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_isValidSubdomain",
+          "memberFieldName": "isValidSubdomain"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_checkConnectivity",
+          "memberFieldName": "checkConnectivity"
+        },
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService__member_isIpv6",
+          "memberFieldName": "isIpv6"
+        }
+      ],
+      "constructorArguments": [
+        {
+          "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService_options__constructorArgument",
+          "fields": [
+            {
+              "keyRaw": "baseDomain",
+              "value": {
+                "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService_options_baseDomain"
+              }
+            },
+            {
+              "keyRaw": "dnsProvider",
+              "value": {
+                "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService_options_dnsProvider"
+              }
+            },
+            {
+              "keyRaw": "tunnelProvider",
+              "value": {
+                "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService_options_tunnelProvider"
+              }
+            },
+            {
+              "keyRaw": "connectivityCheckEndpoint",
+              "value": {
+                "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService_options_connectivityCheckEndpoint"
+              }
+            },
+            {
+              "keyRaw": "reservedSubdomains",
+              "value": {
+                "@id": "undefineds:dist/subdomain/SubdomainService.jsonld#SubdomainService_options_reservedSubdomains"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/dist/subdomain/index.d.ts

@@ -0,0 +1,2 @@
+export { SubdomainService, type SubdomainServiceOptions, type SubdomainRegistration, type ConnectivityResult, } from './SubdomainService';
+export { SubdomainClient, SubdomainClientError, type SubdomainClientOptions, type SubdomainCheckResult, type SubdomainRegistrationResult, type SubdomainInfo, } from './SubdomainClient';

package/dist/subdomain/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubdomainClientError = exports.SubdomainClient = exports.SubdomainService = void 0;
+var SubdomainService_1 = require("./SubdomainService");
+Object.defineProperty(exports, "SubdomainService", { enumerable: true, get: function () { return SubdomainService_1.SubdomainService; } });
+var SubdomainClient_1 = require("./SubdomainClient");
+Object.defineProperty(exports, "SubdomainClient", { enumerable: true, get: function () { return SubdomainClient_1.SubdomainClient; } });
+Object.defineProperty(exports, "SubdomainClientError", { enumerable: true, get: function () { return SubdomainClient_1.SubdomainClientError; } });
+//# sourceMappingURL=index.js.map

package/dist/subdomain/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/subdomain/index.ts"],"names":[],"mappings":";;;AAAA,uDAK4B;AAJ1B,oHAAA,gBAAgB,OAAA;AAMlB,qDAO2B;AANzB,kHAAA,eAAe,OAAA;AACf,uHAAA,oBAAoB,OAAA","sourcesContent":["export {\n  SubdomainService,\n  type SubdomainServiceOptions,\n  type SubdomainRegistration,\n  type ConnectivityResult,\n} from './SubdomainService';\n\nexport {\n  SubdomainClient,\n  SubdomainClientError,\n  type SubdomainClientOptions,\n  type SubdomainCheckResult,\n  type SubdomainRegistrationResult,\n  type SubdomainInfo,\n} from './SubdomainClient';\n"]}

package/dist/supervisor/Supervisor.d.ts

@@ -0,0 +1,20 @@
+import type { ServiceConfig, ServiceState, StatusChangeHandler } from './types';
+export declare class Supervisor {
+    private processes;
+    private states;
+    private configs;
+    private onStatusChange?;
+    private isShuttingDown;
+    constructor();
+    private shutdown;
+    private killAll;
+    setStatusChangeHandler(handler: StatusChangeHandler): void;
+    register(config: ServiceConfig): void;
+    startAll(): Promise<void>;
+    stopAll(): Promise<void>;
+    start(name: string): void;
+    stop(name: string): Promise<void>;
+    getStatus(name: string): ServiceState | undefined;
+    getAllStatus(): ServiceState[];
+    private updateState;
+}