@mandujs/core 0.36.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/config/mandu.ts

@@ -126,6 +126,29 @@ export interface ManduConfig {
   spa?: boolean;
   server?: {
     port?: number;
+    /**
+     * Bind hostname for the HTTP server.
+     *
+     * Default: `"::"` (IPv6 wildcard, dual-stack). Bun leaves
+     * `IPV6_V6ONLY` off, so this one socket accepts both IPv6 clients
+     * (e.g. Node 17+ `fetch("localhost:PORT")` on Windows resolves to
+     * `::1`) and IPv4 clients (as IPv4-mapped IPv6) — you effectively
+     * get `0.0.0.0` + `::` for free.
+     *
+     * Set `"0.0.0.0"` to bind IPv4 only (container/firewall setups that
+     * need it). Note: on Windows, an IPv4-only bind makes Node's
+     * `fetch("localhost:PORT")` fail with `ECONNREFUSED ::1:PORT`
+     * because Node prefers the IPv6 address for `localhost`. `curl`
+     * and browsers silently fall back to IPv4, hiding the bug — Mandu
+     * emits a one-line warning on Windows when you pick this value
+     * explicitly so the trap is discoverable.
+     *
+     * Set `"127.0.0.1"` or `"::1"` to bind loopback-only (no LAN
+     * visibility). Set any other value (e.g. `"10.0.0.2"`,
+     * `"myhost.example.com"`) to bind that specific interface.
+     *
+     * @see issues #190 #223 #225
+     */
     hostname?: string;
     cors?:
       | boolean

package/src/config/validate.ts

@@ -44,9 +44,12 @@ function strictWithWarnings<T extends z.ZodRawShape>(
 const ServerConfigSchema = z
   .object({
     port: z.number().min(1).max(65535).default(3000),
-    // Default 0.0.0.0 so IPv4 `localhost` resolution (Windows default) succeeds.
-    // Users may pin "::1" or "127.0.0.1" explicitly. See issue #190.
-    hostname: z.string().default("0.0.0.0"),
+    // Default `"::"` (IPv6 wildcard, dual-stack): accepts both IPv4 and
+    // IPv6 clients on one socket. Fixes Windows Node 17+ fetch failing
+    // with `ECONNREFUSED ::1:PORT` because `localhost` resolves to `::1`
+    // first there. Explicit `"0.0.0.0"` (IPv4-only) and `"::1"` /
+    // `"127.0.0.1"` (loopback-only) are still honored. See #190 #223.
+    hostname: z.string().default("::"),
     cors: z
       .union([
         z.boolean(),

package/src/runtime/adapter-bun.ts

@@ -48,9 +48,11 @@ export function adapterBun(): ManduAdapter {
 
           return {
             port: manduServer.server.port ?? port,
-            // Report the effective bind address. startServer() defaults to
-            // 0.0.0.0 when no hostname is supplied. See #190.
-            hostname: hostname ?? "0.0.0.0",
+            // Report the effective bind address. startServer() defaults
+            // to `"::"` (dual-stack IPv6 wildcard) when no hostname is
+            // supplied — accepts both IPv4 and IPv6 clients on one
+            // socket. See #190 #223.
+            hostname: hostname ?? "::",
           };
         },
 

package/src/runtime/server.ts

@@ -4255,42 +4255,98 @@ function startBunServerWithFallback(options: {
 // ========== Server Startup ==========
 
 /**
- * Format a base URL for startup logging based on the bound hostname.
+ * Derive the list of loopback-style hosts actually reachable for a given
+ * bind address, without issuing any network probes. Used by the startup
+ * banner (`formatServerAddresses`) and by tooling that needs to know
+ * which loopback URLs will succeed for a given server.
+ *
+ * Matrix:
+ *   - `"0.0.0.0"` (IPv4 wildcard) → `["127.0.0.1"]` only. A server bound
+ *     to `0.0.0.0` does NOT answer on `[::1]` — the IPv6 loopback is a
+ *     different socket. This was the root cause of #225.
+ *   - `"::"` / `"::0"` / `"[::]"` / `"0:0:0:0:0:0:0:0"` (IPv6 wildcard,
+ *     dual-stack) → `["127.0.0.1", "[::1]"]`. IPV6_V6ONLY is off by
+ *     default on Bun, so the dual-stack socket accepts IPv4-mapped
+ *     connections too.
+ *   - `undefined` / `""` → same as the current default (`"::"`).
+ *   - `"127.0.0.1"` / `"::1"` / a specific IP → just that address.
+ *   - DNS name → just that name.
  *
- * When binding to wildcard addresses (`0.0.0.0`, `::`, or empty string),
- * the server listens on all interfaces — browsers must use `localhost`
- * or a specific loopback address to connect. We surface both IPv4 and IPv6
- * loopback URLs so the user can pick whichever their OS prefers.
+ * @see issues #223 #225
+ */
+export function reachableHosts(hostname: string | undefined): string[] {
+  const h = (hostname ?? "").trim();
+
+  // IPv4 wildcard — IPv4 loopback only.
+  if (h === "0.0.0.0") {
+    return ["127.0.0.1"];
+  }
+
+  // IPv6 wildcard (dual-stack). Empty / undefined is treated as the
+  // default, which is now `"::"` (dual-stack) — see `startServer()`.
+  if (h === "" || h === "::" || h === "::0" || h === "[::]" || h === "0:0:0:0:0:0:0:0") {
+    return ["127.0.0.1", "[::1]"];
+  }
+
+  // Bare IPv6 literal → bracket for URL syntax.
+  if (h.includes(":") && !h.startsWith("[")) {
+    return [`[${h}]`];
+  }
+
+  return [h];
+}
+
+/**
+ * Format a base URL for startup logging based on the bound hostname.
  *
  * Returns `{ primary, additional }` where `primary` is the canonical URL
- * for UX (open-in-browser, runtime control) and `additional` are supplementary
- * URLs shown in the startup log.
+ * for UX (open-in-browser, runtime control) and `additional` are
+ * supplementary URLs shown in the startup log. Every URL in `additional`
+ * is guaranteed to actually resolve to the running server — no more
+ * "(also reachable at [::1])" when the socket only answers on IPv4.
+ *
+ * @see issue #225
  */
 export function formatServerAddresses(
   hostname: string | undefined,
   port: number
 ): { primary: string; additional: string[] } {
-  const isWildcardV4 = hostname === "0.0.0.0" || hostname === undefined || hostname === "";
-  const isWildcardV6 = hostname === "::" || hostname === "[::]";
+  const h = (hostname ?? "").trim();
+  const isWildcardV4 = h === "0.0.0.0";
+  const isWildcardV6 =
+    h === "" || h === "::" || h === "::0" || h === "[::]" || h === "0:0:0:0:0:0:0:0";
+  const hosts = reachableHosts(hostname);
+
   if (isWildcardV4 || isWildcardV6) {
     return {
       primary: `http://localhost:${port}`,
-      additional: [`http://127.0.0.1:${port}`, `http://[::1]:${port}`],
+      additional: hosts.map((x) => `http://${x}:${port}`),
     };
   }
-  // Bracket IPv6 literals for URL syntax.
-  const host = hostname.includes(":") && !hostname.startsWith("[") ? `[${hostname}]` : hostname;
-  return { primary: `http://${host}:${port}`, additional: [] };
+
+  // Specific host — `primary` is that host, no additional entries.
+  return { primary: `http://${hosts[0]}:${port}`, additional: [] };
 }
 
 export function startServer(manifest: RoutesManifest, options: ServerOptions = {}): ManduServer {
   const {
     port = 3000,
-    // Default to 0.0.0.0 (dual-stack wildcard on IPv4) so `localhost` resolves
-    // to 127.0.0.1 via OS-level IPv4-preferred lookups (e.g., Windows). Users
-    // can still pin `hostname: "::1"` or `hostname: "127.0.0.1"` explicitly.
-    // See issue #190.
-    hostname = "0.0.0.0",
+    // Default to `"::"` (IPv6 wildcard, dual-stack). Bun leaves IPV6_V6ONLY
+    // off, so this single socket accepts both IPv4 (as IPv4-mapped IPv6)
+    // and IPv6 clients — covering `127.0.0.1`, `[::1]`, and LAN addresses
+    // of either family with one bind.
+    //
+    // Why not `"0.0.0.0"`? On Windows with Node 17+, `fetch("localhost:...")`
+    // resolves to `::1` first. A server bound to `0.0.0.0` accepts IPv4
+    // only, so Node clients (Playwright test runner, ATE-generated specs)
+    // fail with `ECONNREFUSED ::1:PORT`. Browsers and `curl` silently
+    // fall back to IPv4, hiding the bug. See issues #190 #223.
+    //
+    // Explicit `"0.0.0.0"` is still honored — users who need IPv4-only
+    // binds (certain container networks, firewall policies) keep that
+    // option; a one-line warning is emitted on Windows so the trap is
+    // discoverable.
+    hostname = "::",
     rootDir = process.cwd(),
     isDev = false,
     hmrPort,
@@ -4611,6 +4667,25 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     registry.settings = { ...registry.settings, hmrPort: actualPort };
   }
 
+  // ─── #223 — Windows hostname="0.0.0.0" discoverability warning ────────
+  // We cannot silently rewrite an explicit `"0.0.0.0"` (user may need
+  // IPv4-only binds for container/firewall reasons), but we CAN warn
+  // the one platform where the gotcha actually bites: Windows, where
+  // Node 17+ fetch prefers `::1` for `localhost` and will therefore
+  // fail to reach an IPv4-only bind. Silent on non-Windows, silent
+  // when `silent: true`.
+  // ──────────────────────────────────────────────────────────────────────
+  if (
+    !silent &&
+    options.hostname === "0.0.0.0" &&
+    process.platform === "win32"
+  ) {
+    console.warn(
+      `⚠️  hostname="0.0.0.0" binds IPv4 only; Node fetch('localhost:${actualPort}') ` +
+        `may fail on Windows (prefers ::1). Consider hostname="::" for dual-stack.`
+    );
+  }
+
   const addresses = formatServerAddresses(hostname, actualPort);
 
   // ─── #217 — gate the boot banner on `!silent` ─────────────────────────