@timber-js/app 0.2.0-alpha.97 → 0.2.0-alpha.99

package/src/server/port-resolution.ts

@@ -0,0 +1,215 @@
+/**
+ * Port resolution for the dev server, Vite preview, and the Node
+ * production preview server.
+ *
+ * Behavior (see TIM-842):
+ *
+ *   1. Default port is **3000** for both dev and prod.
+ *   2. If the user did NOT set an explicit port, auto-bump from 3000
+ *      until a free port is found (3000 → 3001 → 3002 → …).
+ *   3. If the user DID set an explicit port (via `--port`, `PORT` env
+ *      var, or `vite.config.ts` `server.port`), use it as-is and let
+ *      the bind fail loudly on conflict (`strictPort: true`).
+ *
+ * The port-bump probe is performed by binding the **actual** server
+ * (e.g. the dev holding server) — not a throwaway probe — so there is
+ * no time-of-check / time-of-use race between probing and listening.
+ *
+ * Design doc: 21-dev-server.md §"Default Port and Auto-Bump".
+ */
+
+/** Default port used by `timber dev` and `timber preview`. */
+export const DEFAULT_PORT = 3000;
+
+/**
+ * A function that attempts to bind to a given port.
+ *
+ * Resolves with the bound port on success. Rejects with an error
+ * (typically with `code === 'EADDRINUSE'`) on failure.
+ */
+export type ListenFn = (port: number) => Promise<number>;
+
+// ── Pure resolution ────────────────────────────────────────────────────
+
+export interface ResolvePortInput {
+  /**
+   * Port read from `vite.config.ts` `server.port` or the `--port` CLI
+   * flag (Vite merges `--port` into `userConfig.server.port` before
+   * plugins see it).
+   */
+  configPort?: number | undefined;
+  /** Raw value of `process.env.PORT`. */
+  envPort?: string | undefined;
+  /** Default port to use when neither `configPort` nor `envPort` is set. */
+  defaultPort?: number;
+}
+
+export interface ResolvedPortInput {
+  /** Port to start binding from. */
+  port: number;
+  /**
+   * `true` if the port came from an explicit user override (config or
+   * env). When `true`, callers must NOT auto-bump and must surface
+   * `EADDRINUSE` to the user.
+   */
+  explicit: boolean;
+}
+
+/**
+ * Pure: compute the starting port from config / env / defaults.
+ *
+ * Performs no I/O — pair with {@link bindWithBump} to actually listen.
+ */
+export function resolveStartPort(input: ResolvePortInput): ResolvedPortInput {
+  const defaultPort = input.defaultPort ?? DEFAULT_PORT;
+
+  // `configPort` wins over `envPort`. This matches Vite's behavior:
+  // `vite --port 4000` overrides `PORT=5000` in the environment.
+  if (typeof input.configPort === 'number' && Number.isFinite(input.configPort)) {
+    return { port: input.configPort, explicit: true };
+  }
+
+  if (input.envPort != null && input.envPort !== '') {
+    const parsed = Number(input.envPort);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return { port: parsed, explicit: true };
+    }
+  }
+
+  return { port: defaultPort, explicit: false };
+}
+
+// ── Bind with auto-bump ────────────────────────────────────────────────
+
+export interface BindWithBumpOptions {
+  /** First port to attempt. */
+  startPort: number;
+  /**
+   * If `true`, increment the port and retry on `EADDRINUSE`. If
+   * `false`, attempt once and let the error propagate.
+   */
+  autoBump: boolean;
+  /** Maximum number of port attempts when `autoBump` is `true`. */
+  maxAttempts?: number;
+}
+
+export interface BindWithBumpResult {
+  /** Port that was actually bound. */
+  port: number;
+  /** `true` if the bound port differs from `startPort`. */
+  bumped: boolean;
+}
+
+/**
+ * Bind a server starting at `startPort`, optionally bumping the port
+ * on `EADDRINUSE` until a free one is found.
+ *
+ * Use this with the actual server you intend to keep listening (e.g.
+ * the dev holding server). Pairing the probe with the real listen
+ * eliminates the TOCTOU race that a throwaway probe would introduce.
+ */
+export async function bindWithBump(
+  listen: ListenFn,
+  options: BindWithBumpOptions
+): Promise<BindWithBumpResult> {
+  const maxAttempts = options.autoBump ? (options.maxAttempts ?? 100) : 1;
+  let lastErr: unknown = null;
+
+  for (let i = 0; i < maxAttempts; i++) {
+    const port = options.startPort + i;
+    try {
+      const bound = await listen(port);
+      return { port: bound, bumped: i > 0 };
+    } catch (err) {
+      lastErr = err;
+      // Only retry on EADDRINUSE — other errors (EACCES, etc.) are
+      // permanent and must surface immediately.
+      if (!isAddrInUse(err)) throw err;
+    }
+  }
+
+  throw lastErr ?? new Error(`Could not bind to a free port starting at ${options.startPort}`);
+}
+
+/** True if `err` is a Node `EADDRINUSE` error from `server.listen()`. */
+export function isAddrInUse(err: unknown): boolean {
+  return (
+    typeof err === 'object' && err !== null && (err as { code?: string }).code === 'EADDRINUSE'
+  );
+}
+
+// ── High-level helper used by the rootSync plugin ────────────────────
+
+export interface StartDevServerPortInput {
+  /** Resolved port from `userConfig.server?.port` (or `--port`), or undefined. */
+  configPort: number | undefined;
+  /** Raw `process.env.PORT` value. */
+  envPort: string | undefined;
+  /** ListenFn for the holding server (or any pre-bind probe target). */
+  listen: ListenFn;
+  /** Logger — defaults to `console`. Injected for tests. */
+  log?: (msg: string) => void;
+  warn?: (msg: string) => void;
+}
+
+export interface StartDevServerPortResult {
+  /** Port chosen for both the holding server and Vite's dev server. */
+  port: number;
+  /** True if the user explicitly set the port (=> Vite must `strictPort: true`). */
+  explicit: boolean;
+  /** True if the holding server actually bound the port. */
+  bound: boolean;
+}
+
+/**
+ * Run the full dev-server port resolution + holding-server bind sequence.
+ *
+ * Resolves the port from config / env / default, attempts to bind the
+ * holding server (auto-bumping when the port came from the default),
+ * and logs the chosen URL. On a clean failure for an explicit port, it
+ * warns and falls back to the requested port so Vite can surface the
+ * conflict via `strictPort: true`.
+ *
+ * Extracted from `index.ts` so the rootSync `config()` hook stays
+ * focused on plugin assembly.
+ */
+export async function startDevServerPort(
+  input: StartDevServerPortInput
+): Promise<StartDevServerPortResult> {
+  const log = input.log ?? ((msg: string) => console.log(msg));
+  const warn = input.warn ?? ((msg: string) => console.warn(msg));
+
+  const start = resolveStartPort({
+    configPort: input.configPort,
+    envPort: input.envPort,
+    defaultPort: DEFAULT_PORT,
+  });
+
+  try {
+    const result = await bindWithBump(input.listen, {
+      startPort: start.port,
+      autoBump: !start.explicit,
+    });
+    if (result.bumped) {
+      log(`\n  \x1b[33m[timber]\x1b[0m Port ${start.port} in use, using ${result.port}\n`);
+    }
+    log(
+      `\n  \x1b[2m\u{1FAB5} timber.js dev server starting at\x1b[0m ` +
+        `\x1b[36mhttp://localhost:${result.port}\x1b[0m\n`
+    );
+    return { port: result.port, explicit: start.explicit, bound: true };
+  } catch (err) {
+    // Holding server failed to bind. For explicit ports we leave the
+    // bound state false and let Vite fail loudly via strictPort: true.
+    // For implicit ports this is essentially unreachable (auto-bump
+    // tries 100 ports), but if we hit it we still want Vite to surface
+    // the error.
+    if (start.explicit && isAddrInUse(err)) {
+      warn(
+        `\n  \x1b[33m[timber]\x1b[0m Port ${start.port} is already in use. ` +
+          `Set PORT (or remove the override) to pick another port.\n`
+      );
+    }
+    return { port: start.port, explicit: start.explicit, bound: false };
+  }
+}