danypops-pi-ipv4-fallback

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# @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

@danypops/pi-ipv4-fallback

A pi 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

pi install ~/Projects/pi-ipv4-fallback

Set PI_SKIP_IPV4_FALLBACK=1 to disable the probe entirely.

How it works

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.
If it fails (refused, unreachable, or times out), call dns.setDefaultResultOrder("ipv4first").
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.

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

License

MIT