portforward start --svc filter; unit tests + CI test gate

Author: ephor

.github/workflows/release.yml

@@ -8,7 +8,15 @@ permissions:
   contents: write
 
 jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun test
+
   build:
+    needs: test
     runs-on: ubuntu-latest
     strategy:
       matrix:

README.md

@@ -32,6 +32,7 @@ git clone https://github.com/edenlabllc/portforward port-forward
 cd port-forward
 ./install.sh              # compiles dist/portforward and installs it
 # or just: bun run build  # produces dist/portforward
+bun test                  # run the unit tests
 ```
 
 > No `bun install` is required — the project has no runtime dependencies.
@@ -63,6 +64,16 @@ portforward start
 - `.portforward.yml`
 - `.workspace.yaml`
 
+### Selecting services
+
+By default `start` runs every service in the config. Use `--svc` (repeatable) to run only some. The term is matched as a case-insensitive substring of the service name, so `postgres` matches `postgres-cluster-pooler` and `clickhouse` matches both `clickhouse-http` and `clickhouse-native`:
+
+```bash
+portforward start --svc minio --svc postgres
+```
+
+An unknown term fails fast and lists the available services.
+
 ## Config
 
 ```yaml

package.json

@@ -8,6 +8,7 @@
   },
   "scripts": {
     "build": "bun build --compile src/cli.ts --outfile dist/portforward",
+    "test": "bun test",
     "start": "bun src/cli.ts start",
     "init": "bun src/cli.ts init",
     "check": "bun src/cli.ts check"

src/cli.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test } from "bun:test";
+import {
+  finalizeConfig,
+  isBenignForwardError,
+  nextReconnectDelay,
+  parseConfig,
+  selectServices,
+  validateConfig,
+  type ServiceConfig,
+} from "./cli.ts";
+
+function service(overrides: Partial<ServiceConfig> = {}): ServiceConfig {
+  return { name: "api", namespace: "default", pod: "api", localPort: 8080, remotePort: 8080, ...overrides };
+}
+
+describe("parseConfig", () => {
+  test("parses the preferred services mapping", () => {
+    const config = parseConfig(`name: local-dev
+services:
+  api:
+    namespace: default
+    localPort: 8080
+    remotePort: 8080
+  postgres:
+    namespace: default
+    localPort: 5432
+    remotePort: 5432
+`);
+    finalizeConfig(config);
+
+    expect(config.name).toBe("local-dev");
+    expect(config.services).toHaveLength(2);
+    expect(config.services[0]).toMatchObject({ name: "api", namespace: "default", localPort: 8080, remotePort: 8080 });
+    // pod defaults to the service key when omitted
+    expect(config.services[0]!.pod).toBe("api");
+  });
+
+  test("normalizes `service:` to a service/ resource", () => {
+    const config = parseConfig(`services:
+  api:
+    namespace: default
+    service: api-svc
+    localPort: 80
+    remotePort: 80
+`);
+    expect(config.services[0]!.resource).toBe("service/api-svc");
+  });
+
+  test("supports legacy portforwards arrays", () => {
+    const config = parseConfig(`name: legacy
+portforwards:
+  - name: api
+    namespace: default
+    pod: api
+    localPort: 8080
+    remotePort: 8080
+`);
+    expect(config.services).toHaveLength(1);
+    expect(config.services[0]).toMatchObject({ name: "api", pod: "api", localPort: 8080 });
+  });
+
+  test("parses JSON config", () => {
+    const config = parseConfig(`{"name":"j","services":{"api":{"namespace":"default","pod":"api","localPort":1,"remotePort":2}}}`);
+    expect(config.name).toBe("j");
+    expect(config.services[0]).toMatchObject({ name: "api", localPort: 1, remotePort: 2 });
+  });
+
+  test("strips inline comments but keeps `#` inside quotes", () => {
+    const config = parseConfig(`services:
+  api:
+    namespace: default # forwarded api
+    pod: "a#b"
+    localPort: 80
+    remotePort: 80
+`);
+    expect(config.services[0]!.namespace).toBe("default");
+    expect(config.services[0]!.pod).toBe("a#b");
+  });
+});
+
+describe("selectServices", () => {
+  const services = [
+    service({ name: "minio" }),
+    service({ name: "postgres-cluster-pooler" }),
+    service({ name: "clickhouse-http" }),
+    service({ name: "clickhouse-native" }),
+  ];
+
+  test("returns all when no terms given", () => {
+    expect(selectServices(services, [])).toHaveLength(4);
+  });
+
+  test("matches by case-insensitive substring", () => {
+    const picked = selectServices(services, ["postgres", "MINIO"]).map((s) => s.name);
+    expect(picked).toEqual(["minio", "postgres-cluster-pooler"]);
+  });
+
+  test("a single term can select a group", () => {
+    const picked = selectServices(services, ["clickhouse"]).map((s) => s.name);
+    expect(picked).toEqual(["clickhouse-http", "clickhouse-native"]);
+  });
+
+  test("throws on a term that matches nothing", () => {
+    expect(() => selectServices(services, ["nope"])).toThrow(/no service matches: nope/);
+  });
+});
+
+describe("validateConfig", () => {
+  test("accepts a complete service", () => {
+    expect(() => validateConfig({ services: [service()] }, "cfg")).not.toThrow();
+  });
+
+  test("requires namespace", () => {
+    expect(() => validateConfig({ services: [service({ namespace: undefined as unknown as string })] }, "cfg"))
+      .toThrow(/namespace is required/);
+  });
+
+  test("requires a pod or resource", () => {
+    expect(() => validateConfig({ services: [service({ pod: undefined, resource: undefined })] }, "cfg"))
+      .toThrow(/pod or .*resource is required/);
+  });
+
+  test("requires integer ports", () => {
+    expect(() => validateConfig({ services: [service({ localPort: NaN })] }, "cfg"))
+      .toThrow(/localPort is required/);
+  });
+});
+
+describe("nextReconnectDelay", () => {
+  test("doubles up to a 30s ceiling", () => {
+    expect(nextReconnectDelay(2000)).toBe(4000);
+    expect(nextReconnectDelay(16000)).toBe(30000);
+    expect(nextReconnectDelay(30000)).toBe(30000);
+  });
+});
+
+describe("isBenignForwardError", () => {
+  test("flags per-connection copy resets", () => {
+    expect(isBenignForwardError("E0602 ... error copying from local connection to remote stream: ... reset by peer")).toBe(true);
+  });
+
+  test("keeps real errors visible", () => {
+    expect(isBenignForwardError("error: lost connection to pod")).toBe(false);
+  });
+});

src/cli.ts

@@ -9,7 +9,7 @@ const VERSION = typeof PORTFORWARD_VERSION !== "undefined" ? PORTFORWARD_VERSION
 const REPO = process.env.PORTFORWARD_REPO
   ?? (typeof PORTFORWARD_REPO !== "undefined" ? PORTFORWARD_REPO : "edenlabllc/portforward");
 
-type ServiceConfig = {
+export type ServiceConfig = {
   name: string;
   namespace: string;
   pod?: string;
@@ -19,7 +19,7 @@ type ServiceConfig = {
   remotePort: number;
 };
 
-type AppConfig = {
+export type AppConfig = {
   name?: string;
   services: ServiceConfig[];
 };
@@ -48,13 +48,15 @@ async function main() {
     const config = await loadConfig(configPath);
     if (config.services.length === 0) fail(`No services configured in ${configPath}`);
 
+    const selected = selectServices(config.services, getOptions(args, "--svc"));
+
     console.log(`portforward: ${config.name ?? configPath}`);
     console.log(`config: ${configPath}`);
-    console.log(`services: ${config.services.map((service) => service.name).join(", ")}`);
+    console.log(`services: ${selected.map((service) => service.name).join(", ")}`);
     console.log("Press Ctrl+C to stop.");
 
     installSignalHandlers();
-    await Promise.all(config.services.map((service) => keepAlive(service)));
+    await Promise.all(selected.map((service) => keepAlive(service)));
     return;
   }
 
@@ -97,15 +99,42 @@ function printHelp() {
 Usage:
   portforward init [--config portforward.yaml] [--force]
   portforward check [--config portforward.yaml]
-  portforward start [--config portforward.yaml]
+  portforward start [--config portforward.yaml] [--svc NAME]...
   portforward upgrade            download and install the latest release
   portforward version
 
+  --svc NAME   run only matching services (substring match, repeatable);
+               omit to start all. e.g. --svc minio --svc postgres
+
 Config files are searched in this order:
   ${CONFIG_FILES.join("\n  ")}
 `);
 }
 
+function getOptions(args: string[], name: string) {
+  const values: string[] = [];
+  for (let index = 0; index < args.length; index++) {
+    if (args[index] === name && args[index + 1] !== undefined) values.push(args[index + 1]!);
+  }
+  return values;
+}
+
+export function selectServices(services: ServiceConfig[], terms: string[]) {
+  if (terms.length === 0) return services;
+
+  const needles = terms.map((term) => term.toLowerCase());
+  const matches = (service: ServiceConfig) =>
+    needles.some((needle) => service.name.toLowerCase().includes(needle));
+  const unmatched = needles.filter((needle) =>
+    !services.some((service) => service.name.toLowerCase().includes(needle)));
+
+  if (unmatched.length) {
+    fail(`no service matches: ${unmatched.join(", ")}. available: ${services.map((service) => service.name).join(", ")}`);
+  }
+
+  return services.filter(matches);
+}
+
 function getOption(args: string[], name: string) {
   const index = args.indexOf(name);
   if (index === -1) return undefined;
@@ -179,13 +208,13 @@ async function loadConfig(path: string): Promise<AppConfig> {
   return parsed;
 }
 
-function finalizeConfig(config: AppConfig) {
+export function finalizeConfig(config: AppConfig) {
   for (const service of config.services) {
     service.pod ??= service.name;
   }
 }
 
-function parseConfig(text: string): AppConfig {
+export function parseConfig(text: string): AppConfig {
   const trimmed = text.trimStart();
   if (trimmed.startsWith("{")) return parseJsonConfig(trimmed);
   return parseYamlConfig(text);
@@ -337,7 +366,7 @@ function stripInlineComment(line: string) {
   return line.trimEnd();
 }
 
-function validateConfig(config: AppConfig, path: string) {
+export function validateConfig(config: AppConfig, path: string) {
   for (const service of config.services) {
     if (!service.name) fail(`Invalid config ${path}: service without name.`);
     if (!service.namespace) fail(`Invalid config ${path}: ${service.name}.namespace is required.`);
@@ -522,12 +551,12 @@ async function streamLines(stream: ReadableStream | null, onLine: (line: string)
   }
 }
 
-function isBenignForwardError(line: string) {
+export function isBenignForwardError(line: string) {
   return line.includes("error copying from local connection to remote stream")
     || line.includes("error copying from remote stream to local connection");
 }
 
-function nextReconnectDelay(current: number) {
+export function nextReconnectDelay(current: number) {
   return Math.min(current * 2, 30000);
 }
 
@@ -554,8 +583,12 @@ function sleep(ms: number) {
 }
 
 function fail(message: string): never {
-  console.error(`portforward: ${message}`);
-  process.exit(1);
+  throw new Error(message);
 }
 
-main().catch((error) => fail(error instanceof Error ? error.message : String(error)));
+if (import.meta.main) {
+  main().catch((error) => {
+    console.error(`portforward: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  });
+}