#19437: Gateway: respect custom bind host for local health/RPC target resolution
gateway
size: XS
Cluster:
Gateway Resilience and Configuration
## Summary
Fix local gateway target resolution for `bind=custom` so CLI health/RPC checks connect to `gateway.customBindHost` instead of hardcoded loopback.
## Problem
After configuring:
- `gateway.bind = "custom"`
- `gateway.customBindHost = "<ip>"`
the configure/health flow could still fail because local RPC checks were targeting:
- `ws://127.0.0.1:<port>`
This produced disconnects (often `1006`) when the gateway was actually bound to a custom host (for example `172.18.0.4`).
## Root Cause
`buildGatewayConnectionDetails()` in `src/gateway/call.ts` only handled local URL resolution for:
- `loopback` (default fallback)
- `lan`
- `tailnet`
`custom` bind mode was not included, so it fell through to loopback.
## Changes
- Added `custom` bind handling in local URL resolution:
- use `gateway.customBindHost` when it is a valid IPv4
- Updated connection metadata source label:
- now reports `local custom <ip>` for this mode
- Added regression tests in `src/gateway/call.test.ts` for:
- `callGateway()` URL selection with `bind=custom`
- `buildGatewayConnectionDetails()` source/URL reporting with `bind=custom`
## Result
When `gateway.bind=custom`, local health/RPC probes now target the configured custom IP, aligning probe behavior with runtime gateway bind settings.
## Validation
- `pnpm vitest run src/gateway/call.test.ts` passed.
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR fixes a real bug: when `gateway.bind = "custom"` is configured, the CLI health/RPC probes were still targeting `127.0.0.1` instead of the configured `customBindHost`. The fix correctly adds `custom` bind mode handling in `buildGatewayConnectionDetails()` and updates the `urlSource` label accordingly.
Key observations:
- The logic is correct and the fallback to loopback when `customBindHost` is absent or not a valid IPv4 works as expected
- `isIPv4` from `node:net` is imported for validation, while `isValidIPv4` from `./net.js` already exists and is used for the same `customBindHost` purpose elsewhere in the codebase (e.g. `onboard-helpers.ts:469`)
- The new tests cover the happy path but are missing a test for the fallback-to-loopback behavior when `bind=custom` but `customBindHost` is absent or invalid — an analogous fallback test exists for `bind=lan` at line 127
<h3>Confidence Score: 4/5</h3>
- This PR is safe to merge; the fix is narrowly scoped, logically correct, and tests pass
- The core bug fix is sound and the new code mirrors the existing patterns for `tailnet` and `lan` bind modes. The two style-level issues (using `isIPv4` from `node:net` instead of the codebase-consistent `isValidIPv4`, and missing a fallback test) are not blocking. No regressions to existing behavior are introduced.
- No files require special attention beyond the style suggestions noted
<sub>Last reviewed commit: 08db64e</sub>
<!-- greptile_other_comments_section -->
<sub>(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#19026: fix(gateway): use loopback for local CLI-to-gateway connections
by Phineas1500 · 2026-02-17
85.7%
#22056: fix(gateway): use loopback for self-connections regardless of bind ...
by usedhonda · 2026-02-20
85.0%
#19429: Fix/custom bind host validation
by frudas24 · 2026-02-17
84.7%
#22110: fix(tools): prefer loopback for internal tool-to-gateway RPC calls
by pierreeurope · 2026-02-20
82.8%
#16300: fix(tui): respect gateway bind mode in TUI connection
by cortexuvula · 2026-02-14
82.7%
#14564: fix(gateway): crashes on startup when tailscale meets non-loopback ...
by yinghaosang · 2026-02-12
82.6%
#22804: fix: prioritize loopback for internal gateway calls (issue #22706)
by ambicuity · 2026-02-21
81.0%
#11098: Support dual-stack custom and LAN gateway binds
by zUZWqEHF · 2026-02-07
80.9%
#11455: fix(gateway): default gateway.mode to local when unset
by AnonO6 · 2026-02-07
79.2%
#22682: fix(gateway): [P0] status probe ignores gateway.tls.enabled — hardc...
by mahsumaktas · 2026-02-21
78.2%