Skip to content

Commit 83783d0

Browse files
t3dotggclaude
andcommitted
Reject a specific non-loopback --host in browser dev; restore vp run docs
Single-origin browser dev proxies backend traffic to localhost. A backend bound only to a specific interface (--host 192.168.1.10) leaves localhost unanswered, so every proxied request fails in a way that reads as a broken server rather than an unsupported flag combination. Reject it at startup with the two working alternatives (wildcard bind, --share). dev:server and dev:desktop don't proxy and keep specific-interface binds. Also returns the docs this PR touched to `vp run dev` — vp is this repo's task runner and forwards --share fine; the `bun run` wording was introduced by this PR itself responding to a bot nudge, matching neither main nor the surrounding lines. Co-Authored-By: Claude Fable 5 <[email protected]>
1 parent 9055f7c commit 83783d0

4 files changed

Lines changed: 133 additions & 3 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
## Dev Servers
1717

1818
- In a linked git worktree, dev state defaults to that worktree's gitignored `.t3`. This deliberately outranks an ambient `T3CODE_HOME`, which could otherwise select the installed app's live `~/.t3/userdata` database. An explicit `--home-dir` still wins.
19-
- Start the web stack with `bun run dev`. Use `bun run dev:share` when someone needs to open it from another device on the tailnet.
19+
- Start the web stack with `vp run dev`. Add `--share` when someone needs to open it from another device on the tailnet.
2020
- Browser dev is single-origin: Vite proxies `/api`, `/ws`, `/oauth`, and `/.well-known` to the backend. Do not set `VITE_HTTP_URL` or `VITE_WS_URL` for `dev`/`dev:web`.
2121
- Worktree paths supply stable preferred port offsets. Read the actual server and web ports from the `[dev-runner]` line because occupied ports can still shift them.
2222

‎docs/reference/scripts.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Scripts
22

3-
- `bun run dev` — Starts contracts, server, and web in watch mode.
4-
- `bun run dev --share` (or `bun run dev:share`) — Also publishes the web port over HTTPS on this machine's tailnet. The startup pairing URL is built against the shared origin, and the mapping is removed on exit.
3+
- `vp run dev` — Starts contracts, server, and web in watch mode.
4+
- `vp run dev --share` — Also publishes the web port over HTTPS on this machine's tailnet. The startup pairing URL is built against the shared origin, and the mapping is removed on exit.
55
- `vp run dev:server` — Starts just the WebSocket server. The server process runs on Bun (`@effect/platform-bun` + `BunPtyAdapter`), but task running uses `vp run`.
66
- `vp run dev:web` — Starts just the Vite dev server for the web app.
77
- Dev commands run from a linked **git worktree** default to that worktree's gitignored `.t3`, even when `T3CODE_HOME` is set, storing state in `<worktree>/.t3/userdata`. Pass `--home-dir <path>` to choose another isolated directory explicitly. Submodules are not worktrees and keep the normal precedence.

‎scripts/dev-runner.test.ts‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -853,6 +853,90 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
853853
});
854854
});
855855

856+
// Single-origin browser dev proxies the backend at localhost, so a backend
857+
// bound only to a specific interface breaks every proxied request in a way
858+
// that looks like a broken server. Reject the combination up front.
859+
it.effect("rejects a specific non-loopback --host for browser dev modes", () => {
860+
const spawnerLayer = Layer.succeed(
861+
ChildProcessSpawner.ChildProcessSpawner,
862+
ChildProcessSpawner.make(() => Effect.succeed(mockProcess(0))),
863+
);
864+
865+
return Effect.gen(function* () {
866+
const error = yield* runDevRunnerWithInput({
867+
...devServerInput,
868+
mode: "dev",
869+
port: undefined,
870+
host: "192.168.1.10",
871+
}).pipe(
872+
Effect.provide(Layer.mergeAll(emptyConfigLayer, netServiceLayer, spawnerLayer)),
873+
Effect.provideService(HostProcessPlatform, "linux"),
874+
Effect.flip,
875+
);
876+
877+
if (error._tag !== "DevRunnerHostNotProxiableError") {
878+
assert.fail(`Unexpected error: ${error._tag}`);
879+
}
880+
assert.equal(error.mode, "dev");
881+
assert.equal(error.host, "192.168.1.10");
882+
assert.include(error.message, "0.0.0.0");
883+
assert.include(error.message, "--share");
884+
});
885+
});
886+
887+
// Wildcards keep loopback answering, so the proxy target stays valid and
888+
// the combination must keep working — it is the documented way to serve a
889+
// LAN interface and the browser proxy at once.
890+
it.effect("still spawns the stack for a wildcard --host in dev mode", () => {
891+
let spawnCount = 0;
892+
const spawnerLayer = Layer.succeed(
893+
ChildProcessSpawner.ChildProcessSpawner,
894+
ChildProcessSpawner.make(() => {
895+
spawnCount += 1;
896+
return Effect.succeed(mockProcess(0));
897+
}),
898+
);
899+
900+
return Effect.gen(function* () {
901+
yield* runDevRunnerWithInput({
902+
...devServerInput,
903+
mode: "dev",
904+
port: undefined,
905+
host: "0.0.0.0",
906+
}).pipe(
907+
Effect.provide(Layer.mergeAll(emptyConfigLayer, netServiceLayer, spawnerLayer)),
908+
Effect.provideService(HostProcessPlatform, "linux"),
909+
);
910+
911+
assert.equal(spawnCount, 1);
912+
});
913+
});
914+
915+
// dev:server does not proxy — the client talks to the backend directly —
916+
// so a specific interface bind stays legitimate there.
917+
it.effect("keeps a specific --host working for dev:server", () => {
918+
let spawnCount = 0;
919+
const spawnerLayer = Layer.succeed(
920+
ChildProcessSpawner.ChildProcessSpawner,
921+
ChildProcessSpawner.make(() => {
922+
spawnCount += 1;
923+
return Effect.succeed(mockProcess(0));
924+
}),
925+
);
926+
927+
return Effect.gen(function* () {
928+
yield* runDevRunnerWithInput({
929+
...devServerInput,
930+
host: "192.168.1.10",
931+
}).pipe(
932+
Effect.provide(Layer.mergeAll(emptyConfigLayer, netServiceLayer, spawnerLayer)),
933+
Effect.provideService(HostProcessPlatform, "linux"),
934+
);
935+
936+
assert.equal(spawnCount, 1);
937+
});
938+
});
939+
856940
it.effect("spawns nothing when --dry-run is combined with --share", () => {
857941
let spawnCount = 0;
858942
const spawnerLayer = Layer.succeed(

‎scripts/dev-runner.ts‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,26 @@ const DESKTOP_DEV_LOOPBACK_HOST = "127.0.0.1";
3636
// which silently moved the ports out from under a URL that had just been shared.
3737
const DEV_PORT_PROBE_HOSTS = ["127.0.0.1", "::1"] as const;
3838

39+
/**
40+
* Bind hosts on which a backend still answers `http://localhost:<port>`, which
41+
* is where single-origin browser dev proxies to. Loopback and the wildcards
42+
* qualify; a specific interface (e.g. a LAN IP) does not — the OS binds only
43+
* that address and the proxy target goes dark.
44+
*/
45+
export function isProxiableBindHost(host: string): boolean {
46+
const normalized = host.trim();
47+
return (
48+
normalized === "" ||
49+
normalized === "localhost" ||
50+
normalized === "127.0.0.1" ||
51+
normalized === "::1" ||
52+
normalized === "[::1]" ||
53+
normalized === "0.0.0.0" ||
54+
normalized === "::" ||
55+
normalized === "[::]"
56+
);
57+
}
58+
3959
export const DEFAULT_T3_HOME = Effect.map(Effect.service(Path.Path), (path) =>
4060
path.join(NodeOS.homedir(), ".t3"),
4161
);
@@ -143,8 +163,21 @@ export class DevRunnerProcessExitError extends Schema.TaggedErrorClass<DevRunner
143163
}
144164
}
145165

166+
export class DevRunnerHostNotProxiableError extends Schema.TaggedErrorClass<DevRunnerHostNotProxiableError>()(
167+
"DevRunnerHostNotProxiableError",
168+
{
169+
mode: Schema.Literals(["dev", "dev:web"]),
170+
host: Schema.String,
171+
},
172+
) {
173+
override get message(): string {
174+
return `--host ${this.host} cannot be combined with ${this.mode}: single-origin browser dev proxies the backend at localhost, and a backend bound only to ${this.host} leaves localhost unanswered, so every proxied request fails. Use a wildcard (0.0.0.0 or ::) to serve that interface and loopback together, or --share for remote access.`;
175+
}
176+
}
177+
146178
export const DevRunnerError = Schema.Union([
147179
DevRunnerConfigurationError,
180+
DevRunnerHostNotProxiableError,
148181
DevRunnerInvalidPortOffsetError,
149182
DevRunnerPortExhaustedError,
150183
DevRunnerProcessError,
@@ -582,6 +615,19 @@ export function runDevRunnerWithInput(input: DevRunnerCliInput) {
582615
),
583616
);
584617

618+
// Single-origin browser dev proxies the backend at localhost. A wildcard
619+
// bind still answers there; a specific non-loopback interface does not,
620+
// which breaks every proxied request in a way that reads as "server is
621+
// broken" rather than "flag combination is unsupported". Reject it up
622+
// front instead. (dev:server and dev:desktop don't proxy — untouched.)
623+
if (
624+
(input.mode === "dev" || input.mode === "dev:web") &&
625+
input.host !== undefined &&
626+
!isProxiableBindHost(input.host)
627+
) {
628+
return yield* new DevRunnerHostNotProxiableError({ mode: input.mode, host: input.host });
629+
}
630+
585631
const worktreePath = yield* resolveGitWorktreePath(yield* HostProcessWorkingDirectory);
586632

587633
const { offset, source } = yield* resolveOffset({

0 commit comments

Comments
 (0)