@downcity/city 1.1.4 → 1.1.5

package/src/cli/shared/PublicAccess.ts

@@ -0,0 +1,106 @@
+/**
+ * control plane 公网访问提示解析。
+ *
+ * 关键点（中文）
+ * - 优先使用用户显式声明的公网地址，避免 NAT / 反向代理场景误判。
+ * - 仅在显式公网模式或 host 本身就是可直连地址时，才生成 Public URL。
+ * - 自动探测只做“最佳努力”，不会为了猜公网 IP 访问外部网络。
+ */
+
+import os from "node:os";
+
+/**
+ * 从网卡列表中提取首个公网 IPv4。
+ */
+export function detectPublicIpv4FromInterfaces(
+  interfaces: NodeJS.Dict<os.NetworkInterfaceInfo[]> = os.networkInterfaces(),
+): string | null {
+  for (const entries of Object.values(interfaces)) {
+    for (const rawItem of (entries || []) as Array<{
+      address?: string;
+      family?: string | number;
+      internal?: boolean;
+    }>) {
+      const item = rawItem;
+      const family =
+        typeof item.family === "string"
+          ? item.family
+          : item.family === 4
+            ? "IPv4"
+            : "unknown";
+      if (family !== "IPv4") continue;
+      if (item.internal) continue;
+      const address = String(item.address || "").trim();
+      if (!address) continue;
+      if (isPrivateIpv4(address)) continue;
+      return address;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 解析 control plane 对外可访问地址。
+ */
+export function resolveControlPlanePublicUrl(params: {
+  bindHost: string;
+  port: number;
+  publicMode?: boolean;
+  env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+  detectedPublicIp?: string | null;
+}): string | null {
+  const env = params.env || process.env;
+  const explicitUrl = String(env.DOWNCITY_PUBLIC_URL || "").trim();
+  if (explicitUrl) return normalizeUrl(explicitUrl, params.port);
+
+  const explicitHost = String(env.DOWNCITY_PUBLIC_HOST || "").trim();
+  if (explicitHost) return formatUrl(explicitHost, params.port);
+
+  const bindHost = String(params.bindHost || "").trim();
+  if (isDirectReachableHost(bindHost)) {
+    return formatUrl(bindHost, params.port);
+  }
+
+  if (params.publicMode !== true) return null;
+  const detectedPublicIp =
+    String(params.detectedPublicIp || "").trim() || detectPublicIpv4FromInterfaces();
+  if (!detectedPublicIp) return null;
+
+  return formatUrl(detectedPublicIp, params.port);
+}
+
+function normalizeUrl(value: string, port: number): string {
+  if (/^https?:\/\//i.test(value)) return value;
+  return formatUrl(value, port);
+}
+
+function formatUrl(host: string, port: number): string {
+  const normalizedHost = String(host || "").trim();
+  if (!normalizedHost) return `http://127.0.0.1:${String(port)}`;
+  if (normalizedHost.startsWith("[")) return `http://${normalizedHost}:${String(port)}`;
+  if (normalizedHost.includes(":") && !normalizedHost.includes(".")) {
+    return `http://[${normalizedHost}]:${String(port)}`;
+  }
+  return `http://${normalizedHost}:${String(port)}`;
+}
+
+function isDirectReachableHost(host: string): boolean {
+  const value = String(host || "").trim().toLowerCase();
+  if (!value) return false;
+  if (value === "0.0.0.0" || value === "::") return false;
+  if (value === "127.0.0.1" || value === "::1" || value === "localhost") return false;
+  return true;
+}
+
+function isPrivateIpv4(address: string): boolean {
+  if (address.startsWith("10.")) return true;
+  if (address.startsWith("127.")) return true;
+  if (address.startsWith("169.254.")) return true;
+  if (address.startsWith("192.168.")) return true;
+
+  const parts = address.split(".").map((item) => Number.parseInt(item, 10));
+  if (parts.length !== 4 || parts.some((item) => Number.isNaN(item))) return true;
+  if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
+  return false;
+}

package/src/cli/shared/PublicHostEnv.ts

@@ -0,0 +1,116 @@
+/**
+ * city 公网 host 自动环境配置。
+ *
+ * 关键点（中文）
+ * - `city start` 时自动探测公网 IPv4，并写入平台 Env 的 `DOWNCITY_PUBLIC_HOST`。
+ * - 若部署环境已经注入 `DOWNCITY_PUBLIC_URL/HOST`，绝不覆盖。
+ * - 写入平台 Env 后，后续 agent daemon 启动会通过 `context.globalEnv` 读取到该值。
+ */
+
+import { PlatformStore } from "@downcity/agent";
+import type {
+  CityPublicHostEnvEntry,
+  CityPublicHostEnvResult,
+  EnsureCityPublicHostEnvInput,
+} from "./PublicHostEnvTypes.js";
+
+const PUBLIC_HOST_DESCRIPTION = "Auto-detected public host for agent contact links.";
+
+function isIpv4Address(value: string): boolean {
+  const parts = String(value || "").trim().split(".");
+  if (parts.length !== 4) return false;
+  return parts.every((part) => {
+    if (!/^\d+$/.test(part)) return false;
+    const num = Number.parseInt(part, 10);
+    return num >= 0 && num <= 255;
+  });
+}
+
+async function resolvePublicIpv4FromNetwork(): Promise<string | null> {
+  if (typeof fetch !== "function") return null;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 800);
+  try {
+    const response = await fetch("https://api.ipify.org?format=json", {
+      signal: controller.signal,
+    });
+    if (!response.ok) return null;
+    const data = (await response.json().catch(() => null)) as {
+      ip?: unknown;
+    } | null;
+    const ip = String(data?.ip || "").trim();
+    return isIpv4Address(ip) ? ip : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function readGlobalEnvFromStore(): Record<string, string> {
+  const store = new PlatformStore();
+  try {
+    return store.getGlobalEnvMapSync();
+  } catch {
+    return {};
+  } finally {
+    store.close();
+  }
+}
+
+async function upsertGlobalEnvToStore(entry: CityPublicHostEnvEntry): Promise<void> {
+  const store = new PlatformStore();
+  try {
+    await store.upsertEnvEntry({
+      scope: "global",
+      key: entry.key,
+      value: entry.value,
+      description: entry.description,
+    });
+  } finally {
+    store.close();
+  }
+}
+
+/**
+ * 确保 city 全局环境中存在自动探测的公网 host。
+ */
+export async function ensureCityPublicHostEnv(
+  input: EnsureCityPublicHostEnvInput = {},
+): Promise<CityPublicHostEnvResult> {
+  const env = input.env || process.env;
+  const globalEnv = input.readGlobalEnv ? input.readGlobalEnv() : readGlobalEnvFromStore();
+  const hasRuntimePublicAddress = Boolean(
+    String(env.DOWNCITY_PUBLIC_URL || globalEnv.DOWNCITY_PUBLIC_URL || "").trim() ||
+      String(env.DOWNCITY_PUBLIC_HOST || globalEnv.DOWNCITY_PUBLIC_HOST || "").trim(),
+  );
+  if (hasRuntimePublicAddress) {
+    return {
+      changed: false,
+      reason: "configured",
+    };
+  }
+
+  const resolved = String(
+    (await (input.resolvePublicIpv4 || resolvePublicIpv4FromNetwork)()) || "",
+  ).trim();
+  if (!isIpv4Address(resolved)) {
+    return {
+      changed: false,
+      reason: "unavailable",
+    };
+  }
+
+  const entry: CityPublicHostEnvEntry = {
+    key: "DOWNCITY_PUBLIC_HOST",
+    value: resolved,
+    description: PUBLIC_HOST_DESCRIPTION,
+  };
+  await (input.upsertGlobalEnv || upsertGlobalEnvToStore)(entry);
+  env.DOWNCITY_PUBLIC_HOST = resolved;
+  return {
+    changed: true,
+    key: "DOWNCITY_PUBLIC_HOST",
+    value: resolved,
+  };
+}

package/src/cli/shared/PublicHostEnvTypes.ts

@@ -0,0 +1,27 @@
+/**
+ * city 公网 host 环境变量类型。
+ */
+
+export type CityPublicHostEnvResult =
+  | {
+      changed: true;
+      key: "DOWNCITY_PUBLIC_HOST";
+      value: string;
+    }
+  | {
+      changed: false;
+      reason: "configured" | "unavailable";
+    };
+
+export interface CityPublicHostEnvEntry {
+  key: "DOWNCITY_PUBLIC_HOST";
+  value: string;
+  description: string;
+}
+
+export interface EnsureCityPublicHostEnvInput {
+  env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+  readGlobalEnv?: () => Record<string, string>;
+  resolvePublicIpv4?: () => Promise<string | null> | string | null;
+  upsertGlobalEnv?: (entry: CityPublicHostEnvEntry) => Promise<void>;
+}