inspector/clients/web/src/test/integration/server/resolve-bind-host.test.ts
cliffhall adde9ccf94 fix: bind loopback by address and pin the sandbox port so containers work
Two defaults that each break the Inspector inside a container.

#1951 — the web UI never loads in a VS Code dev container. `HOST` defaulted
to the NAME `localhost`, and `server.listen(port, host)` resolves a name
through `dns.lookup` and binds the SINGLE address it gets back. Since Node 17
the default result order is `verbatim`, so on a glibc Linux host — whose
/etc/hosts maps localhost to both 127.0.0.1 and ::1 — that is `::1`. The
server bound IPv6 loopback only and refused every IPv4 client, including the
dev container port forwarder. It presents as an endless spinner rather than a
connection error because the forwarder accepts on the host side before failing
to connect inward. Default to the ADDRESS 127.0.0.1 instead; an explicit
HOST=localhost is still honored as typed.

#2008 — the Apps tab is unreachable in any container. The MCP Apps sandbox
listened on an OS-assigned port, so it changed every run and could never be
named in a devcontainer `forwardPorts`, a `docker run -p`, or a tunnel. Default
it to a fixed 6275, mirroring CLIENT_PORT's fixed 6274, and retry once on an
OS-assigned port (loudly) if it is taken — the collision a dynamic default
never had.

Verified in the reporter's exact image
(mcr.microsoft.com/devcontainers/typescript-node:4-24-trixie): both listeners
come up on 127.0.0.1 and answer 200 on 6274 and 6275/sandbox.

Also EXPOSE 6275 and set MCP_SANDBOX_PORT in the image, and document both
defaults in the web README, the migration guide, and the root README's Docker
section.

Signed-off-by: cliffhall <cliff@futurescale.com>
2026-08-15 12:33:27 -04:00

103 lines
3.5 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

import { describe, it, expect } from "vitest";
import {
BIND_ALL_INTERFACES_ENV,
DEFAULT_BIND_HOST,
resolveBindHostname,
} from "../../../../server/resolve-bind-host.js";
describe("resolveBindHostname", () => {
// Regression guard for #1951. The default must be an *address*, never the
// name `localhost`: `listen()` resolves a name and binds the single address
// the resolver returns first, which on glibc Linux is `::1` — leaving every
// IPv4 client (a dev container's port forwarder, an `ssh -L` to 127.0.0.1, a
// container healthcheck) refused. See DEFAULT_BIND_HOST.
it("defaults to the IPv4 loopback address, not the name localhost", () => {
expect(resolveBindHostname({})).toBe("127.0.0.1");
expect(resolveBindHostname({})).toBe(DEFAULT_BIND_HOST);
expect(resolveBindHostname({})).not.toBe("localhost");
});
it("still honors an explicit HOST=localhost as typed", () => {
expect(resolveBindHostname({ HOST: "localhost" })).toBe("localhost");
});
it("returns a loopback HOST unchanged", () => {
expect(resolveBindHostname({ HOST: "127.0.0.1" })).toBe("127.0.0.1");
});
it("trims the returned host so detection and the bind value agree", () => {
expect(resolveBindHostname({ HOST: " 127.0.0.1 " })).toBe("127.0.0.1");
});
it("returns a bracketed IPv6 HOST bare so listen() can bind it", () => {
expect(resolveBindHostname({ HOST: "[::1]" })).toBe("::1");
});
it("keeps the zone index on a link-local HOST for listen()", () => {
// The guard must not throw on a zone-scoped host, and must return it with
// the zone intact (listen() needs the zone to pick the interface).
expect(resolveBindHostname({ HOST: "fe80::1%eth0" })).toBe("fe80::1%eth0");
});
it.each([
"0.0.0.0",
"::",
"",
"0",
"0x0.0.0.0",
"::ffff:0.0.0.0",
" 0 ",
"0", // fullwidth "0" — the resolver binds it as 0.0.0.0, so the guard must refuse it
])("refuses the all-interfaces host %j without the opt-in", (host) => {
expect(() => resolveBindHostname({ HOST: host })).toThrow(
new RegExp(BIND_ALL_INTERFACES_ENV),
);
});
it("names the resolved wildcard address when the spelling differs (fullwidth)", () => {
// `HOST="0"` renders like `0`, so the message shows it resolves to 0.0.0.0.
expect(() => resolveBindHostname({ HOST: "0" })).toThrow(
/resolves to 0\.0\.0\.0/,
);
});
it("does not add a resolved-address hint for an already-canonical bracketed HOST", () => {
// `HOST="[::]"` is accepted-then-refused as the wildcard; the message must
// not read "(resolves to [::])" — same value, just bracketed. Capture the
// message outside try/catch so a stopped-throwing regression reports clearly.
let message = "";
expect(() => {
try {
resolveBindHostname({ HOST: "[::]" });
} catch (err) {
message = (err as Error).message;
throw err;
}
}).toThrow(BIND_ALL_INTERFACES_ENV);
expect(message).not.toContain("resolves to");
});
it.each(["true", "TRUE", "1", " true "])(
"allows 0.0.0.0 when the opt-in is %j",
(flag) => {
expect(
resolveBindHostname({
HOST: "0.0.0.0",
[BIND_ALL_INTERFACES_ENV]: flag,
}),
).toBe("0.0.0.0");
},
);
it.each(["false", "0", "", "yes", "no"])(
"still refuses 0.0.0.0 when the opt-in reads %j",
(flag) => {
expect(() =>
resolveBindHostname({
HOST: "0.0.0.0",
[BIND_ALL_INTERFACES_ENV]: flag,
}),
).toThrow();
},
);
});