@monster-orange/den 0.2.7 → 0.3.0

package/src/shared/edge/config.ts

@@ -12,9 +12,17 @@
  *     publish: true          # false: another proxy fronts the edge
  *     http_port: 80
  *     https_port: 443
+ *     tls: none              # http only; or (see tls.ts):
+ *     #   tls: { strategy: mkcert }                   # own local CA, per machine
+ *     #   tls: { strategy: mkcert, ca: ~/path/to/ca } # an existing CA; never minted
+ *     #   tls: { strategy: files, include: edge/dynamic, mounts: {...} }
+ *     #        # included config holds the certs; optional ca: the CA that
+ *     #        # signed them, trusted by health checks
+ *     # legacy (still read, mapped to tls, deprecated):
+ *     #   caroot: <ca>       → tls: { strategy: mkcert, ca: <ca> }
+ *     #   issue_cert: false  → tls: { strategy: files }
+ *     #   neither, no tls    → mkcert with a local CA, and a warning
  *     # opt-ins (all off by default):
- *     caroot: ~/path/to/mkcert-ca   # use an existing CA; never mint one
- *     issue_cert: false             # included config holds the certs
  *     https_redirect: false         # included config redirects per name
  *     docker_labels: { network: apps-network }
  *     include: edge/dynamic         # dynamic-config files, repo-relative
@@ -35,7 +43,8 @@ import { cachedRead } from "../read-cache.js";
 import { readManifestStacks } from "../stacks/config.js";
 import { getActiveWorkspaces } from "../environment-manager/workspaces.js";
 import { assertDomain } from "./render.js";
-import type { EdgeConfig } from "./types.js";
+import { tlsStrategyIds } from "./tls.js";
+import type { EdgeConfig, EdgeTls } from "./types.js";
 
 import { product } from "../product.js";
 export const DEFAULT_TRAEFIK_IMAGE = "traefik:v3.7.17";
@@ -51,6 +60,7 @@ interface RawEdge {
   publish?: boolean;
   http_port?: number;
   https_port?: number;
+  tls?: unknown;
   caroot?: string;
   issue_cert?: boolean;
   https_redirect?: boolean;
@@ -120,6 +130,108 @@ function mounts(v: RawEdge["mounts"], root: string): Record<string, string> {
   return out;
 }
 
+const TLS_KEYS: Record<string, string[]> = {
+  none: ["strategy"],
+  mkcert: ["strategy", "ca"],
+  files: ["strategy", "ca", "include", "mounts"],
+};
+
+interface ResolvedTls {
+  tls: EdgeTls;
+  from: EdgeConfig["tlsFrom"];
+  /** `files`' own include and mounts (raw, resolved by the caller). */
+  include?: string;
+  mounts?: Record<string, string>;
+}
+
+/**
+ * `edge.tls` (user.yml's replaces the team's), or the legacy keys mapped to
+ * it (EXT-1 rule 6): `issue_cert: false` → files, `caroot` → mkcert with
+ * `ca`, neither → mkcert with a local CA (implicit, warned).
+ */
+function readTls(team: RawEdge, user: RawEdge, root: string): ResolvedTls {
+  const raw = user.tls ?? team.tls;
+  const caroot = user.caroot ?? team.caroot;
+  const issue = user.issue_cert ?? team.issue_cert;
+  const ids = tlsStrategyIds();
+  const builtIns = ids.join(", ");
+  if (raw === undefined) {
+    const ca = caroot ? resolvePath(caroot, root) : null;
+    return {
+      tls:
+        issue === false
+          ? { strategy: "files", ca }
+          : { strategy: "mkcert", ca },
+      from: caroot === undefined && issue === undefined ? "implicit" : "legacy",
+    };
+  }
+  const legacy = [
+    ...(caroot !== undefined ? ["caroot"] : []),
+    ...(issue !== undefined ? ["issue_cert"] : []),
+  ];
+  if (legacy.length)
+    throw new Error(
+      `edge.tls replaces edge.${legacy.join(" and edge.")}; remove ${legacy.length > 1 ? "them" : "it"} ` +
+        "(caroot is tls.ca, issue_cert: false is tls.strategy: files).",
+    );
+  const obj: Record<string, unknown> =
+    typeof raw === "string"
+      ? { strategy: raw }
+      : raw && typeof raw === "object" && !Array.isArray(raw)
+        ? (raw as Record<string, unknown>)
+        : {};
+  const id = obj.strategy;
+  if (typeof id !== "string" || !id)
+    throw new Error(
+      `edge.tls must be a strategy id or { strategy: <id>, ... }; the built-ins are ${builtIns}`,
+    );
+  if (!ids.includes(id))
+    throw new Error(
+      `edge.tls.strategy "${id}" is not a known TLS strategy; the built-ins are ${builtIns}`,
+    );
+  const allowed = TLS_KEYS[id] ?? ["strategy"];
+  for (const k of Object.keys(obj))
+    if (!allowed.includes(k))
+      throw new Error(
+        `edge.tls.${k} does not apply to strategy ${id} (it takes ${allowed.join(", ")})`,
+      );
+  let ca: string | null = null;
+  if (obj.ca !== undefined) {
+    if (typeof obj.ca !== "string" || !obj.ca.trim())
+      throw new Error(
+        "edge.tls.ca must be the path to an existing CA directory",
+      );
+    ca = resolvePath(obj.ca, root);
+  }
+  if (
+    obj.include !== undefined &&
+    (typeof obj.include !== "string" || !obj.include)
+  )
+    throw new Error(
+      "edge.tls.include must be a directory of dynamic-config files",
+    );
+  if (
+    obj.mounts !== undefined &&
+    (!obj.mounts || typeof obj.mounts !== "object" || Array.isArray(obj.mounts))
+  )
+    throw new Error("edge.tls.mounts must map host paths to container paths");
+  const tls: EdgeTls =
+    id === "none"
+      ? { strategy: "none" }
+      : { strategy: id as "mkcert" | "files", ca };
+  return {
+    tls,
+    from: "explicit",
+    include: obj.include as string | undefined,
+    mounts: obj.mounts as Record<string, string> | undefined,
+  };
+}
+
+/** True when the org config has an `edge:` block (an edge is configured). */
+export function hasEdgeBlock(root: string = getDistRoot()): boolean {
+  return layers(root).team.edge !== undefined;
+}
+
 /** The web UI's route name: the brand name as a slug ("Den" → "den"). */
 function webRouteName(team: Record<string, unknown>): string {
   const name = (team.brand as { name?: string } | undefined)?.name?.trim();
@@ -188,6 +300,22 @@ function computeEdgeConfig(root: string): EdgeConfig {
     throw new Error("edge.aliases must be a list of domains");
   aliases.forEach(assertDomain);
   const publish = user.publish ?? team.publish ?? true;
+  const tls = readTls(team, user, root);
+  if (tls.include !== undefined && team.include !== undefined)
+    throw new Error(
+      "edge.include and edge.tls.include are both set; keep one (tls.include for files' certs)",
+    );
+  const include = tls.include ?? team.include;
+  // The state dir the config names (or the XDG default), DEN_EDGE_DIR aside.
+  const configuredStateDir = expandHome(
+    user.state_dir ??
+      team.state_dir ??
+      path.join(
+        process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share"),
+        team.org,
+        "edge",
+      ),
+  );
   return {
     org: team.org,
     domain: team.domain,
@@ -214,26 +342,24 @@ function computeEdgeConfig(root: string): EdgeConfig {
           ),
         }
       : null,
-    stateDir: expandHome(
-      process.env.DEN_EDGE_DIR ??
-        user.state_dir ??
-        team.state_dir ??
-        path.join(
-          process.env.XDG_DATA_HOME ||
-            path.join(os.homedir(), ".local", "share"),
-          team.org,
-          "edge",
-        ),
-    ),
-    caroot:
-      (user.caroot ?? team.caroot)
-        ? resolvePath((user.caroot ?? team.caroot)!, root)
-        : null,
-    issueCert: (user.issue_cert ?? team.issue_cert) !== false,
+    stateDir:
+      process.env.DEN_EDGE_DIR !== undefined
+        ? expandHome(process.env.DEN_EDGE_DIR)
+        : configuredStateDir,
+    // Set only when DEN_EDGE_DIR overrides it: the dir the config names.
+    ...(process.env.DEN_EDGE_DIR !== undefined &&
+    expandHome(process.env.DEN_EDGE_DIR) !== configuredStateDir
+      ? { defaultStateDir: configuredStateDir }
+      : {}),
+    tls: tls.tls,
+    tlsFrom: tls.from,
     httpsRedirect: (user.https_redirect ?? team.https_redirect) !== false,
     dockerLabels: dockerLabels(user.docker_labels ?? team.docker_labels),
-    include: team.include ? resolvePath(team.include, root) : null,
-    mounts: mounts({ ...(team.mounts ?? {}), ...(user.mounts ?? {}) }, root),
+    include: include ? resolvePath(include, root) : null,
+    mounts: mounts(
+      { ...(team.mounts ?? {}), ...(user.mounts ?? {}), ...(tls.mounts ?? {}) },
+      root,
+    ),
     networks: [
       ...new Set([
         ...list(team.networks, "networks"),

package/src/shared/edge/exec.ts

@@ -0,0 +1,31 @@
+/** Running the edge's CLIs (docker, mkcert): one place, one error shape. */
+import { spawnSync } from "child_process";
+
+export function sh(
+  cmd: string,
+  args: string[],
+  opts: { env?: NodeJS.ProcessEnv; inherit?: boolean } = {},
+) {
+  const r = spawnSync(cmd, args, {
+    encoding: "utf-8",
+    env: { ...process.env, ...opts.env },
+    stdio: opts.inherit ? "inherit" : "pipe",
+  });
+  if (r.error) throw new Error(`${cmd} is not installed (${r.error.message})`);
+  return {
+    code: r.status ?? 1,
+    out: (r.stdout ?? "").trim(),
+    err: (r.stderr ?? "").trim(),
+  };
+}
+
+export function must(
+  cmd: string,
+  args: string[],
+  opts: { env?: NodeJS.ProcessEnv } = {},
+): string {
+  const r = sh(cmd, args, opts);
+  if (r.code !== 0)
+    throw new Error(`${cmd} ${args.join(" ")} failed:\n${r.err || r.out}`);
+  return r.out;
+}

package/src/shared/edge/included.ts

@@ -0,0 +1,169 @@
+/**
+ * The routers in the distribution's included dynamic-config files (`edge
+ * include`, e.g. `edge/dynamic/*.yml`): Traefik serves them beside the
+ * routes Den generates, so `edge routes`, /api/edge and the Edge page list
+ * them too, each marked by its source file (PL-SPEC §10, a consumer's review).
+ *
+ * Read-only: the files are parsed, never written, and only `http.routers`
+ * is read. The same files `edge up` copies in (top-level YAML, not the
+ * generated edge.yml, not a stack's own route file).
+ *
+ * Since 0.3.0-dev.32 (a consumer's finding) also the stacks' own route
+ * files: Den writes `stack-<project>.yml` into the edge's dynamic directory
+ * when a stack comes up, and those routers are neither Den's host routes
+ * nor included files, so nothing listed them.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { parse } from "yaml";
+import { includeFiles, isOwnedElsewhere, isStackRoutes } from "./runtime.js";
+import type { EdgeConfig } from "./types.js";
+
+export interface IncludedRouter {
+  /** The router's key under `http.routers`. */
+  name: string;
+  /** The included file it comes from (its name, as Traefik reads it). */
+  file: string;
+  rule: string;
+  service: string;
+  entryPoints: string[];
+  /** The hosts its rule names (`Host(...)`), for links. */
+  hosts: string[];
+  tls: boolean;
+  /**
+   * Served over https: the router has TLS or is on the websecure
+   * entrypoint (0.3.0-dev.33). Its URLs are https://, else http://.
+   */
+  secure: boolean;
+  /**
+   * Where it sends traffic: its service's loadBalancer server URL(s) when
+   * the same file defines that service, else the service's name
+   * (0.3.0-dev.33).
+   */
+  upstream: string;
+}
+
+/** A router's URLs: one per host, with its scheme; none without a Host(). */
+export function routerUrls(r: Pick<IncludedRouter, "hosts" | "secure">) {
+  const scheme = r.secure ? "https://" : "http://";
+  return r.hosts.map((h) => scheme + h);
+}
+
+export interface IncludedRouters {
+  routers: IncludedRouter[];
+  /** Files that could not be read or parsed: listed, never fatal. */
+  errors: { file: string; error: string }[];
+}
+
+/** The hosts a Traefik rule names: every quoted argument of Host(...). */
+export function ruleHosts(rule: string): string[] {
+  const out: string[] = [];
+  for (const m of rule.matchAll(/\bHost\(([^)]*)\)/g))
+    for (const q of m[1].matchAll(/[`"']([^`"']+)[`"']/g))
+      if (!out.includes(q[1])) out.push(q[1]);
+  return out;
+}
+
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+
+/** The routers in one dynamic-config document's `http.routers`. */
+export function routersOf(doc: unknown, file: string): IncludedRouter[] {
+  const http = (
+    doc as { http?: { routers?: unknown; services?: unknown } } | null
+  )?.http;
+  const routers = http?.routers;
+  if (!routers || typeof routers !== "object" || Array.isArray(routers))
+    return [];
+  const services = obj(http?.services);
+  return Object.entries(routers as Record<string, unknown>).map(([name, r]) => {
+    const o = obj(r);
+    const rule = str(o.rule);
+    const service = str(o.service);
+    const entryPoints = Array.isArray(o.entryPoints)
+      ? o.entryPoints.filter((e): e is string => typeof e === "string")
+      : [];
+    const tls = o.tls !== undefined && o.tls !== null && o.tls !== false;
+    return {
+      name,
+      file,
+      rule,
+      service,
+      entryPoints,
+      hosts: ruleHosts(rule),
+      tls,
+      secure: tls || entryPoints.includes("websecure"),
+      upstream: serverUrls(services[service]).join(", ") || service,
+    };
+  });
+}
+
+const obj = (v: unknown): Record<string, unknown> =>
+  v && typeof v === "object" && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : {};
+
+/** A Traefik service's loadBalancer server URLs (none: not a load balancer). */
+function serverUrls(svc: unknown): string[] {
+  const servers = obj(obj(svc).loadBalancer).servers;
+  return Array.isArray(servers)
+    ? servers.map((x) => str(obj(x).url)).filter(Boolean)
+    : [];
+}
+
+/** Every router in the edge's included files, in file then key order. */
+export function includedRouters(cfg: EdgeConfig): IncludedRouters {
+  const out: IncludedRouters = { routers: [], errors: [] };
+  if (!cfg.include) return out;
+  let files: string[];
+  try {
+    files = includeFiles(cfg.include).filter((f) => !isOwnedElsewhere(f));
+  } catch (e) {
+    out.errors.push({
+      file: path.basename(cfg.include),
+      error: (e as Error).message,
+    });
+    return out;
+  }
+  for (const file of files) {
+    try {
+      const doc: unknown = parse(
+        fs.readFileSync(path.join(cfg.include, file), "utf-8"),
+      );
+      out.routers.push(...routersOf(doc, file));
+    } catch (e) {
+      out.errors.push({ file, error: (e as Error).message.split("\n")[0] });
+    }
+  }
+  return out;
+}
+
+/**
+ * Every router in the stacks' route files (`stack-*.yml` in the edge's
+ * dynamic directory, which `stack up` writes and `stack down` removes), in
+ * file then key order. No directory yet: none.
+ */
+export function stackRouters(cfg: EdgeConfig): IncludedRouters {
+  const out: IncludedRouters = { routers: [], errors: [] };
+  const dyn = path.join(cfg.stateDir, "dynamic");
+  let files: string[];
+  try {
+    files = fs
+      .readdirSync(dyn, { withFileTypes: true })
+      .filter((e) => e.isFile() && isStackRoutes(e.name))
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return out;
+  }
+  for (const file of files) {
+    try {
+      const doc: unknown = parse(
+        fs.readFileSync(path.join(dyn, file), "utf-8"),
+      );
+      out.routers.push(...routersOf(doc, file));
+    } catch (e) {
+      out.errors.push({ file, error: (e as Error).message.split("\n")[0] });
+    }
+  }
+  return out;
+}

package/src/shared/edge/render.ts

@@ -38,12 +38,34 @@ function hostRule(name: string, cfg: EdgeConfig): string {
     .join(" || ");
 }
 
-/** Public URL for a route, including the port when it isn't 443. */
+/** True when the edge serves https: every edge.tls strategy but `none`. */
+export function edgeHttps(cfg: EdgeConfig): boolean {
+  return cfg.tls.strategy !== "none";
+}
+
+/** The entrypoint routes listen on: websecure, or web for `tls: none`. */
+export function routeEntryPoint(cfg: EdgeConfig): "web" | "websecure" {
+  return edgeHttps(cfg) ? "websecure" : "web";
+}
+
+/** A router's TLS block: `{ tls: {} }`, or nothing for `tls: none`. */
+export function routerTls(cfg: EdgeConfig): { tls?: Record<string, never> } {
+  return edgeHttps(cfg) ? { tls: {} } : {};
+}
+
+/**
+ * Public URL for a route, including the port when it isn't the default
+ * (443, or 80 for an http-only edge).
+ */
 export function routeUrl(
   name: string,
   cfg: EdgeConfig,
   domain = cfg.domain,
 ): string {
+  if (!edgeHttps(cfg)) {
+    const h = cfg.ports?.http ?? 80;
+    return `http://${routeHost(name, domain)}${h === 80 ? "" : `:${h}`}`;
+  }
   const p = cfg.ports?.https ?? 443;
   return `https://${routeHost(name, domain)}${p === 443 ? "" : `:${p}`}`;
 }
@@ -64,12 +86,20 @@ export function certNames(cfg: EdgeConfig): string[] {
   ]);
 }
 
-/** Dynamic config: TLS cert, HTTP→HTTPS redirect, dashboard, routes. */
+/**
+ * Dynamic config: TLS cert, HTTP→HTTPS redirect, dashboard, routes. With
+ * `tls: none` every router is on the http entrypoint, with no TLS and no
+ * redirect.
+ */
 export function renderEdgeDynamic(cfg: EdgeConfig): string {
   const httpsPort = cfg.ports?.https ?? 443;
   const redirectPort = httpsPort !== 443 ? { port: String(httpsPort) } : {};
+  const https = edgeHttps(cfg);
+  const redirect = https && cfg.httpsRedirect;
+  // Fresh objects per router: a shared one would render as a YAML anchor.
+  const entryPoints = () => [routeEntryPoint(cfg)];
   const routers: Record<string, unknown> = {
-    ...(cfg.httpsRedirect
+    ...(redirect
       ? {
           "to-https": {
             entryPoints: ["web"],
@@ -81,10 +111,10 @@ export function renderEdgeDynamic(cfg: EdgeConfig): string {
         }
       : {}),
     dashboard: {
-      entryPoints: ["websecure"],
+      entryPoints: entryPoints(),
       rule: hostRule("edge", cfg),
       service: "api@internal",
-      tls: {},
+      ...routerTls(cfg),
     },
   };
   const services: Record<string, unknown> = {};
@@ -97,10 +127,10 @@ export function renderEdgeDynamic(cfg: EdgeConfig): string {
       );
     const key = `route-${slug(name)}`;
     routers[key] = {
-      entryPoints: ["websecure"],
+      entryPoints: entryPoints(),
       rule: hostRule(name, cfg),
       service: key,
-      tls: {},
+      ...routerTls(cfg),
     };
     services[key] = { loadBalancer: { servers: [{ url }] } };
   }
@@ -113,7 +143,7 @@ export function renderEdgeDynamic(cfg: EdgeConfig): string {
     yaml.stringify({
       http: {
         routers,
-        ...(cfg.httpsRedirect
+        ...(redirect
           ? {
               middlewares: {
                 "to-https": {
@@ -128,7 +158,7 @@ export function renderEdgeDynamic(cfg: EdgeConfig): string {
           : {}),
         ...(Object.keys(services).length ? { services } : {}),
       },
-      ...(cfg.issueCert
+      ...(cfg.tls.strategy === "mkcert"
         ? {
             tls: {
               stores: { default: { defaultCertificate: cert } },
@@ -145,8 +175,25 @@ export function dockerProxyName(org: string): string {
   return `${edgeNames(org).container}-docker`;
 }
 
-/** Compose file for the edge; publishes host ports only when configured. */
-export function renderEdgeCompose(cfg: EdgeConfig): string {
+/**
+ * Compose file for the edge; publishes host ports only when configured.
+ * With `tls: none` there is no https entrypoint, port or cert volume.
+ */
+/** The labels that say which state dir and org own the edge container. */
+export const EDGE_ROOT_LABEL = "den.edge.root";
+export const EDGE_ORG_LABEL = "den.edge.org";
+
+/**
+ * The edge's compose.yml. Its container carries `den.edge.root` (the state
+ * dir that owns it, `ownerRoot`: edgeUp passes its realpath) and
+ * `den.edge.org` (0.3.0-dev.40): edgeUp and `edge down` touch an existing
+ * edge only when its root is theirs.
+ */
+export function renderEdgeCompose(
+  cfg: EdgeConfig,
+  ownerRoot: string = cfg.stateDir,
+): string {
+  const https = edgeHttps(cfg);
   const n = edgeNames(cfg.org);
   const proxy = dockerProxyName(cfg.org);
   const labels = cfg.dockerLabels;
@@ -159,10 +206,11 @@ export function renderEdgeCompose(cfg: EdgeConfig): string {
       image: cfg.image,
       container_name: n.container,
       restart: "unless-stopped",
+      labels: { [EDGE_ROOT_LABEL]: ownerRoot, [EDGE_ORG_LABEL]: cfg.org },
       ...(labels ? { depends_on: ["docker-proxy"] } : {}),
       command: [
         "--entrypoints.web.address=:80",
-        "--entrypoints.websecure.address=:443",
+        ...(https ? ["--entrypoints.websecure.address=:443"] : []),
         "--providers.file.directory=/etc/edge/dynamic",
         "--providers.file.watch=true",
         ...(labels
@@ -179,12 +227,19 @@ export function renderEdgeCompose(cfg: EdgeConfig): string {
         ...cfg.args,
       ],
       ...(cfg.ports
-        ? { ports: [`${cfg.ports.http}:80`, `${cfg.ports.https}:443`] }
+        ? {
+            ports: [
+              `${cfg.ports.http}:80`,
+              ...(https ? [`${cfg.ports.https}:443`] : []),
+            ],
+          }
         : {}),
       extra_hosts: ["host.docker.internal:host-gateway"],
       volumes: [
         "./dynamic:/etc/edge/dynamic:ro",
-        ...(cfg.issueCert ? ["./certs:/etc/edge/certs:ro"] : []),
+        ...(cfg.tls.strategy === "mkcert"
+          ? ["./certs:/etc/edge/certs:ro"]
+          : []),
         ...Object.entries(cfg.mounts)
           .sort(([a], [b]) => a.localeCompare(b))
           .map(([host, target]) => `${host}:${target}:ro`),