---
slug: "danypops-pi-ipv4-fallback"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/DanyPops/pi-ipv4-fallback@main/README.md"
repo: "https://github.com/DanyPops/pi-ipv4-fallback"
source_file: "README.md"
branch: "main"
---
# @danypops/pi-ipv4-fallback

A [pi](https://pi.dev) extension that probes IPv6 reachability once at startup and prefers IPv4 for the rest of the process if it's broken.

## Why

Corporate VPNs commonly advertise a route to IPv6-only addresses and then silently blackhole traffic (no RST, no ICMP unreachable) instead of cleanly rejecting it. When that happens, any Node/Bun HTTP client that resolves a AAAA record first — including `google-auth-library`'s OAuth token requests for Vertex-routed Claude models — can hang until it times out, surfacing as an opaque error like:

```
request to https://oauth2.googleapis.com/token failed, reason:
```

`dns.setDefaultResultOrder("ipv4first")` is a process-wide, runtime-mutable Node API (also implemented by Bun) that `dns.lookup()` honors — and `dns.lookup()` is what `net.connect`/`http`/`https` use by default. Flipping it fixes every default HTTP client in the process at once (Anthropic direct, Vertex, Bedrock, Gemini, whatever), not just one provider, and needs no env var to remember.

This intentionally does **not** force IPv4 unconditionally — on networks where IPv6 actually works, forcing IPv4 would only add latency for no benefit. It's an adaptive, one-shot probe, not a blanket flag.

Ported from the equivalent boot-time probe in a sibling project (`~/Workspace/alef`'s `packages/cli/src/boot/network.ts`) — kept as a pi extension rather than upstreamed into `pi-ai`/`pi-coding-agent` core, since this is environment-specific mitigation behavior, not a universal correctness fix everyone needs.

## Install

```bash
pi install ~/Projects/pi-ipv4-fallback
```

Set `PI_SKIP_IPV4_FALLBACK=1` to disable the probe entirely.

## How it works

1. On extension load (the async factory function, awaited by pi before `session_start`, `resources_discover`, or any queued `pi.registerProvider()` calls are flushed — i.e. before any provider could have made a real network call yet), attempt a short-timeout (400ms) TCP connect to Google Public DNS's IPv6 literal (`2001:4860:4860::8888:443`). Connecting directly to an IP, not a hostname, isolates IPv6 *routing* health from DNS resolver health.
2. If it fails (refused, unreachable, or times out), call `dns.setDefaultResultOrder("ipv4first")`.
3. If it switched, notify once at the next `session_start` (TUI/RPC modes only).

## Testing

`test/network.test.ts` covers the probe logic directly (reachable / refused / timeout).

`test/blackhole-vpn-scenario.test.ts` simulates the actual failure mode this exists for — a true blackhole (silent drop, no RST/ICMP) — which can't be reproduced with plain loopback sockets, since any connection this machine can actually make completes or fails near-instantly. It mocks `dns.lookup` (honoring whatever `dns.setDefaultResultOrder()` currently reports, exactly like real DNS resolution does) and `net.connect` for a fake IPv6 candidate that never responds, then asserts:

- **Without** the extension: a client that connects to the first resolved address times out (IPv6-first, blackholed).
- **With** the extension: the same client succeeds immediately (IPv4-first, real local server).

A negative control (temporarily skip the real `preferIpv4IfUnreachable()` call) was run manually to confirm the "with extension" case genuinely fails without it — the test is causally tied to the shipped code, not vacuous.

```bash
npm install
npm run check   # tsc --noEmit
npm test        # vitest run
```

## License

MIT