fbi-proxy 1.16.0 → 1.17.0

package/ts/routes.ts

@@ -27,6 +27,12 @@ export type RouteConfig = {
    * `{name:multi}` (one or more dot-segments — for DNS-passthrough).
    */
   match: string;
+  /**
+   * Optional path-prefix matcher. When set, the rule only matches
+   * requests whose path falls under this prefix; among host-matching
+   * rules the longest matching prefix wins. Forwarded upstream as-is.
+   */
+  path?: string;
   /**
    * Target template. Expanded with placeholder captures from `match`.
    * E.g. `"127.0.0.1:{port}"`.
@@ -46,6 +52,15 @@ export type RoutesFile = {
   routes: RouteConfig[];
 };
 
+/**
+ * Compose-style per-project config (`fbi-proxy.yaml`). The top-level
+ * `name` is the namespace (defaults to the directory name when omitted).
+ */
+export type ComposeFile = {
+  name?: string;
+  routes: RouteConfig[];
+};
+
 /** Result type for `validateRoute`. */
 export type ValidationResult =
   | { valid: true }
@@ -108,9 +123,19 @@ export function parseRoutesYaml(yaml: string): RoutesFile {
         headers[hk] = hv;
       }
     }
+    let path: string | undefined;
+    if (e.path != null) {
+      if (typeof e.path !== "string") {
+        throw new Error(
+          `routes.yaml: entry '${e.name}': \`path\` must be a string`,
+        );
+      }
+      path = e.path;
+    }
     routes.push({
       name: e.name,
       match: e.match,
+      ...(path != null ? { path } : {}),
       target: e.target,
       headers,
     });
@@ -118,6 +143,28 @@ export function parseRoutesYaml(yaml: string): RoutesFile {
   return { version: 1, routes };
 }
 
+/**
+ * Parse a compose-style `fbi-proxy.yaml`. Reuses the route validation in
+ * `parseRoutesYaml`. Returns the namespace (`name`, possibly undefined)
+ * and the parsed routes.
+ */
+export function parseComposeYaml(yaml: string): ComposeFile {
+  const raw = YAML.parse(yaml);
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("fbi-proxy.yaml must be a YAML mapping at the top level");
+  }
+  const obj = raw as Record<string, unknown>;
+  if (obj.name != null && typeof obj.name !== "string") {
+    throw new Error("fbi-proxy.yaml: `name` must be a string");
+  }
+  // parseRoutesYaml validates the `routes` list + each entry; version is
+  // optional in a compose file so default it in.
+  const { routes } = parseRoutesYaml(
+    YAML.stringify({ version: 1, routes: obj.routes ?? [] }),
+  );
+  return { name: obj.name as string | undefined, routes };
+}
+
 const PLACEHOLDER_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const VALID_KINDS = new Set(["", "int", "slug", "multi"]);
 
@@ -164,6 +211,9 @@ export function validateRoute(r: RouteConfig): ValidationResult {
   if (!r.match) return { valid: false, reason: "route `match` is required" };
   if (!r.target) return { valid: false, reason: "route `target` is required" };
 
+  if (r.path != null && !r.path.startsWith("/"))
+    return { valid: false, reason: "route `path` must start with '/'" };
+
   if (!bracesBalanced(r.match))
     return { valid: false, reason: "unbalanced braces in `match`" };
   if (!bracesBalanced(r.target))

package/ts/rulesCli.ts

@@ -0,0 +1,166 @@
+/**
+ * `fbi-proxy up | down | ps | config` — compose-style management of
+ * runtime routing rules. Each project ships an `fbi-proxy.yaml` whose
+ * top-level `name` is the namespace; rules are stored as conf.d
+ * fragments and applied live via the loopback admin API.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import YAML from "yaml";
+import { parseComposeYaml, validateRoute, type RouteConfig } from "./routes";
+import {
+  applyRules,
+  deleteRules,
+  listRules,
+  type RuleInfo,
+} from "./adminClient";
+
+const DEFAULT_FILE = "fbi-proxy.yaml";
+
+export const RULES_SUBCOMMANDS = new Set(["up", "down", "ps", "config"]);
+
+/** Derive the namespace: explicit `-p` > compose `name` > directory name. */
+function resolveNamespace(
+  explicit: string | undefined,
+  composeName: string | undefined,
+  filePath: string,
+): string {
+  if (explicit) return explicit;
+  if (composeName) return composeName;
+  // directory of the compose file (or CWD for stdin) — like docker compose.
+  return path.basename(path.dirname(path.resolve(filePath)));
+}
+
+function loadCompose(file: string): { name?: string; routes: RouteConfig[] } {
+  if (!existsSync(file)) {
+    throw new Error(
+      `[fbi-proxy] ${file} not found. Create one (compose-style):\n` +
+        `  name: my-app\n  routes:\n    - name: web\n      match: fbi.com\n      path: /\n      target: localhost:3000`,
+    );
+  }
+  const compose = parseComposeYaml(readFileSync(file, "utf8"));
+  for (const r of compose.routes) {
+    const v = validateRoute(r);
+    if (!v.valid) {
+      throw new Error(`[fbi-proxy] ${file}: rule '${r.name}': ${v.reason}`);
+    }
+  }
+  return compose;
+}
+
+function printRulesTable(rules: RuleInfo[]): void {
+  if (rules.length === 0) {
+    console.log("(no rules)");
+    return;
+  }
+  const rows = rules.map((r) => ({
+    NAMESPACE: r.namespace,
+    NAME: r.name,
+    MATCH: r.match,
+    PATH: r.path ?? "*",
+    TARGET: r.target,
+  }));
+  const cols = ["NAMESPACE", "NAME", "MATCH", "PATH", "TARGET"] as const;
+  const widths = Object.fromEntries(
+    cols.map((c) => [
+      c,
+      Math.max(c.length, ...rows.map((row) => String(row[c]).length)),
+    ]),
+  ) as Record<(typeof cols)[number], number>;
+  const fmt = (row: Record<string, string>) =>
+    cols.map((c) => String(row[c]).padEnd(widths[c])).join("  ");
+  console.log(fmt(Object.fromEntries(cols.map((c) => [c, c]))));
+  for (const row of rows) console.log(fmt(row));
+}
+
+/**
+ * Entry point dispatched from cli.ts when the first positional arg is one
+ * of `up|down|ps|config`. Returns the process exit code.
+ */
+export async function runRulesCli(rawArgs: string[]): Promise<number> {
+  const argv = await yargs(rawArgs)
+    .scriptName("fbi-proxy")
+    .command("up", "Apply this project's fbi-proxy.yaml to the running proxy")
+    .command("down", "Remove this project's rules from the running proxy")
+    .command("ps", "List active rules across all namespaces")
+    .command("config", "Print the merged resolved routing table")
+    .option("file", {
+      alias: "f",
+      type: "string",
+      default: DEFAULT_FILE,
+      description: "Path to the compose file",
+    })
+    .option("project", {
+      alias: "p",
+      type: "string",
+      description:
+        "Override the namespace (defaults to compose `name` or dir name)",
+    })
+    .option("output", {
+      alias: "o",
+      type: "string",
+      choices: ["table", "json", "yaml"] as const,
+      default: "table",
+      description: "Output format for ps/config",
+    })
+    .help().argv;
+
+  const cmd = String(argv._[0]);
+
+  try {
+    switch (cmd) {
+      case "up": {
+        const compose = loadCompose(argv.file);
+        const ns = resolveNamespace(argv.project, compose.name, argv.file);
+        const body = YAML.stringify({ version: 1, routes: compose.routes });
+        const applied = await applyRules(ns, body);
+        console.log(
+          `[fbi-proxy] up: namespace '${ns}' (${compose.routes.length} rule(s))`,
+        );
+        printRulesTable(applied.filter((r) => r.namespace === ns));
+        return 0;
+      }
+      case "down": {
+        // Namespace can come from -p, or the compose file if present.
+        let ns = argv.project;
+        if (!ns) {
+          const compose = existsSync(argv.file) ? loadCompose(argv.file) : null;
+          ns = resolveNamespace(undefined, compose?.name, argv.file);
+        }
+        const res = await deleteRules(ns);
+        console.log(
+          res.removed
+            ? `[fbi-proxy] down: removed namespace '${ns}'`
+            : `[fbi-proxy] down: namespace '${ns}' was not present`,
+        );
+        return 0;
+      }
+      case "ps":
+      case "config": {
+        const rules = await listRules();
+        if (argv.output === "json") {
+          console.log(JSON.stringify(rules, null, 2));
+        } else if (argv.output === "yaml") {
+          console.log(YAML.stringify(rules));
+        } else {
+          printRulesTable(rules);
+        }
+        return 0;
+      }
+      default:
+        console.error(`[fbi-proxy] unknown command '${cmd}'`);
+        return 2;
+    }
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    return 1;
+  }
+}
+
+/** Convenience for standalone invocation/testing. */
+if (import.meta.main) {
+  runRulesCli(hideBin(process.argv)).then((code) => process.exit(code));
+}

package/ts/setup.ts

@@ -355,7 +355,11 @@ function runAsRoot(script: string): boolean {
     );
   }
   console.log("[setup] (opening macOS auth dialog — enter password)");
-  const wrapped = `do shell script ${appleScriptQuote(script)} with administrator privileges`;
+  const prompt =
+    "fbi-proxy setup needs administrator access to install its HTTPS " +
+    "certificate into the system trust store and add a pf rule forwarding " +
+    "port 443 to the local proxy.";
+  const wrapped = `do shell script ${appleScriptQuote(script)} with prompt ${appleScriptQuote(prompt)} with administrator privileges`;
   return (
     spawnSync("osascript", ["-e", wrapped], { stdio: "inherit" }).status === 0
   );