feat(external-gateway): add gateway client domain and DNS record support for dcrouter integration

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/onebox',
-  version: '1.24.2',
+  version: '1.25.0',
   description: 'Self-hosted container platform with automatic SSL and DNS - a mini Heroku for single servers'
 }

ts/classes/external-gateway.ts

@@ -9,13 +9,22 @@ type TWorkHosterType = 'onebox';
 interface IExternalGatewayConfig {
   url: string;
   apiToken: string;
+  gatewayClientId: string;
+  /** @deprecated Use gatewayClientId. */
   workHosterId: string;
   targetHost?: string;
   targetPort?: number;
 }
 
 interface IWorkHosterDomain {
+  id?: string;
   name: string;
+  source?: 'dcrouter' | 'provider';
+  authoritative?: boolean;
+  providerId?: string;
+  serviceCount?: number;
+  managePath?: string;
+  manageUrl?: string;
   capabilities?: {
     canCreateSubdomains: boolean;
     canManageDnsRecords: boolean;
@@ -24,6 +33,26 @@ interface IWorkHosterDomain {
   };
 }
 
+interface IGatewayDnsRecord {
+  id: string;
+  domainId: string;
+  domainName?: string;
+  name: string;
+  type: string;
+  value: string;
+  ttl: number;
+  source: string;
+  status: 'active' | 'missing';
+  gatewayClientType: 'onebox' | 'cloudly' | 'custom';
+  gatewayClientId: string;
+  appId: string;
+  hostname: string;
+  routeId?: string;
+  serviceName?: string;
+  managePath?: string;
+  manageUrl?: string;
+}
+
 interface IWorkAppRouteOwnership {
   workHosterType: TWorkHosterType;
   workHosterId: string;
@@ -31,6 +60,13 @@ interface IWorkAppRouteOwnership {
   hostname: string;
 }
 
+interface IGatewayClientOwnership {
+  gatewayClientType: TWorkHosterType;
+  gatewayClientId: string;
+  appId: string;
+  hostname: string;
+}
+
 interface IWorkAppRouteSyncResult {
   success: boolean;
   action?: 'created' | 'updated' | 'deleted' | 'unchanged';
@@ -93,12 +129,10 @@ export class ExternalGatewayManager {
   }
 
   public async syncDomains(): Promise<IDomain[]> {
-    const config = await this.requireConfig({ requireTarget: false });
-    const response = await this.fireDcRouterRequest<{ domains: IWorkHosterDomain[] }>(
-      'getWorkHosterDomains',
-      {},
-      config,
-    );
+    if (!(await this.isConfigured())) {
+      return this.database.getDomainsByProvider('dcrouter');
+    }
+    const response = { domains: await this.getGatewayDomains() };
 
     const activeDomainNames = new Set<string>();
     const now = Date.now();
@@ -143,6 +177,55 @@ export class ExternalGatewayManager {
     return this.database.getDomainsByProvider('dcrouter');
   }
 
+  public async getGatewayDomains(): Promise<IWorkHosterDomain[]> {
+    const config = await this.getConfig({ requireTarget: false });
+    if (!config) return [];
+
+    try {
+      const response = await this.fireDcRouterRequest<{ domains: IWorkHosterDomain[] }>(
+        'getGatewayClientDomains',
+        { gatewayClientId: config.gatewayClientId },
+        config,
+      );
+      return response.domains.map((domain) => ({
+        ...domain,
+        manageUrl: this.buildManageUrl(config, domain.managePath),
+      }));
+    } catch (error) {
+      logger.debug(`Falling back to legacy gateway domain API: ${getErrorMessage(error)}`);
+      const response = await this.fireDcRouterRequest<{ domains: IWorkHosterDomain[] }>(
+        'getWorkHosterDomains',
+        {},
+        config,
+      );
+      return response.domains.map((domain) => ({
+        ...domain,
+        manageUrl: this.buildManageUrl(config, domain.managePath),
+      }));
+    }
+  }
+
+  public async getGatewayDnsRecords(): Promise<IGatewayDnsRecord[]> {
+    const config = await this.getConfig({ requireTarget: false });
+    if (!config) return [];
+
+    try {
+      const response = await this.fireDcRouterRequest<{ records: IGatewayDnsRecord[] }>(
+        'getGatewayClientDnsRecords',
+        { gatewayClientId: config.gatewayClientId },
+        config,
+      );
+      return response.records.map((record) => ({
+        ...record,
+        serviceName: record.serviceName || record.appId,
+        manageUrl: this.buildManageUrl(config, record.managePath),
+      }));
+    } catch (error) {
+      logger.warn(`Failed to fetch gateway DNS records: ${getErrorMessage(error)}`);
+      return [];
+    }
+  }
+
   public async syncServiceRoute(service: IService): Promise<void> {
     if (!service.domain) return;
 
@@ -150,14 +233,24 @@ export class ExternalGatewayManager {
     if (!config) return;
 
     const result = await this.fireDcRouterRequest<IWorkAppRouteSyncResult>(
-      'syncWorkAppRoute',
+      'syncGatewayClientRoute',
       {
-        ownership: this.buildOwnership(service, service.domain, config),
+        ownership: this.buildGatewayClientOwnership(service, service.domain, config),
         route: this.buildRoute(service, config),
         enabled: service.status === 'running',
       },
       config,
-    );
+    ).catch(async () => {
+      return await this.fireDcRouterRequest<IWorkAppRouteSyncResult>(
+        'syncWorkAppRoute',
+        {
+          ownership: this.buildOwnership(service, service.domain!, config),
+          route: this.buildRoute(service, config),
+          enabled: service.status === 'running',
+        },
+        config,
+      );
+    });
 
     if (!result.success) {
       throw new Error(result.message || `dcrouter route sync failed for ${service.domain}`);
@@ -176,13 +269,22 @@ export class ExternalGatewayManager {
     if (!config) return;
 
     const result = await this.fireDcRouterRequest<IWorkAppRouteSyncResult>(
-      'syncWorkAppRoute',
+      'syncGatewayClientRoute',
       {
-        ownership: this.buildOwnership(service, service.domain, config),
+        ownership: this.buildGatewayClientOwnership(service, service.domain, config),
         delete: true,
       },
       config,
-    );
+    ).catch(async () => {
+      return await this.fireDcRouterRequest<IWorkAppRouteSyncResult>(
+        'syncWorkAppRoute',
+        {
+          ownership: this.buildOwnership(service, service.domain!, config),
+          delete: true,
+        },
+        config,
+      );
+    });
 
     if (!result.success) {
       throw new Error(result.message || `dcrouter route delete failed for ${service.domain}`);
@@ -240,10 +342,12 @@ export class ExternalGatewayManager {
       return null;
     }
 
+    const gatewayClientId = this.ensureGatewayClientId();
     const config: IExternalGatewayConfig = {
       url,
       apiToken,
-      workHosterId: this.ensureWorkHosterId(),
+      gatewayClientId,
+      workHosterId: gatewayClientId,
     };
 
     if (options.requireTarget !== false) {
@@ -288,13 +392,13 @@ export class ExternalGatewayManager {
     return port;
   }
 
-  private ensureWorkHosterId(): string {
-    let workHosterId = this.database.getSetting('dcrouterWorkHosterId');
-    if (!workHosterId) {
-      workHosterId = crypto.randomUUID();
-      this.database.setSetting('dcrouterWorkHosterId', workHosterId);
+  private ensureGatewayClientId(): string {
+    let gatewayClientId = this.database.getSetting('dcrouterGatewayClientId') || this.database.getSetting('dcrouterWorkHosterId');
+    if (!gatewayClientId) {
+      gatewayClientId = crypto.randomUUID();
+      this.database.setSetting('dcrouterGatewayClientId', gatewayClientId);
     }
-    return workHosterId;
+    return gatewayClientId;
   }
 
   private buildOwnership(
@@ -304,12 +408,25 @@ export class ExternalGatewayManager {
   ): IWorkAppRouteOwnership {
     return {
       workHosterType: 'onebox',
-      workHosterId: config.workHosterId,
+      workHosterId: config.gatewayClientId,
       workAppId: service.name || `service-${service.id}`,
       hostname,
     };
   }
 
+  private buildGatewayClientOwnership(
+    service: Pick<IService, 'id' | 'name'>,
+    hostname: string,
+    config: IExternalGatewayConfig,
+  ): IGatewayClientOwnership {
+    return {
+      gatewayClientType: 'onebox',
+      gatewayClientId: config.gatewayClientId,
+      appId: service.name || `service-${service.id}`,
+      hostname,
+    };
+  }
+
   private buildRoute(service: IService, config: IExternalGatewayConfig): IDcRouterRouteConfig {
     return {
       name: this.routeName(service.domain!),
@@ -335,6 +452,11 @@ export class ExternalGatewayManager {
     return `onebox-${domain.replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '')}`;
   }
 
+  private buildManageUrl(config: IExternalGatewayConfig, managePath?: string): string {
+    const normalizedPath = managePath?.startsWith('/') ? managePath : managePath ? `/${managePath}` : '';
+    return `${config.url}${normalizedPath}`;
+  }
+
   private async fireDcRouterRequest<TResponse>(
     method: string,
     requestData: Record<string, unknown>,

ts/opsserver/handlers/dns.handler.ts

@@ -61,5 +61,16 @@ export class DnsHandler {
         },
       ),
     );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetGatewayDnsRecords>(
+        'getGatewayDnsRecords',
+        async (dataArg) => {
+          await requireAdminIdentity(this.opsServerRef.adminHandler, dataArg);
+          const records = await this.opsServerRef.oneboxRef.externalGateway.getGatewayDnsRecords();
+          return { records };
+        },
+      ),
+    );
   }
 }

ts/opsserver/handlers/domains.handler.ts

@@ -97,5 +97,16 @@ export class DomainsHandler {
         },
       ),
     );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetGatewayDomains>(
+        'getGatewayDomains',
+        async (dataArg) => {
+          await requireAdminIdentity(this.opsServerRef.adminHandler, dataArg);
+          const domains = await this.opsServerRef.oneboxRef.externalGateway.getGatewayDomains();
+          return { domains };
+        },
+      ),
+    );
   }
 }

ts/opsserver/handlers/settings.handler.ts

@@ -24,7 +24,8 @@ export class SettingsHandler {
       cloudflareZoneId: settingsMap['cloudflareZoneId'] || '',
       dcrouterGatewayUrl: settingsMap['dcrouterGatewayUrl'] || '',
       dcrouterGatewayApiToken: dcrouterGatewayApiToken || '',
-      dcrouterWorkHosterId: settingsMap['dcrouterWorkHosterId'] || '',
+      dcrouterGatewayClientId: settingsMap['dcrouterGatewayClientId'] || settingsMap['dcrouterWorkHosterId'] || '',
+      dcrouterWorkHosterId: settingsMap['dcrouterWorkHosterId'] || settingsMap['dcrouterGatewayClientId'] || '',
       dcrouterTargetHost: settingsMap['dcrouterTargetHost'] || '',
       dcrouterTargetPort: parseInt(settingsMap['dcrouterTargetPort'] || '0', 10),
       autoRenewCerts: settingsMap['autoRenewCerts'] === 'true',
@@ -106,6 +107,7 @@ export class SettingsHandler {
     return [
       'dcrouterGatewayUrl',
       'dcrouterGatewayApiToken',
+      'dcrouterGatewayClientId',
       'dcrouterWorkHosterId',
       'dcrouterTargetHost',
       'dcrouterTargetPort',

ts/types.ts

@@ -261,6 +261,8 @@ export interface IAppSettings {
   cloudflareZoneId?: string;
   dcrouterGatewayUrl?: string;
   dcrouterGatewayApiToken?: string;
+  dcrouterGatewayClientId?: string;
+  /** @deprecated Use dcrouterGatewayClientId. */
   dcrouterWorkHosterId?: string;
   dcrouterTargetHost?: string;
   dcrouterTargetPort?: number;