aiohappyeyeballs

This package implements Happy Eyeballs (RFC 8305) for asyncio, providing dual-stack IPv4/IPv6 connection racing to ensure fast connection establishment. The API is refreshingly simple - essentially a drop-in replacement for asyncio's create_connection that handles the complexity of parallel connection attempts transparently. The main entry point `start_connection()` accepts standard host/port parameters and returns working streams without ceremony.

In production, it reliably handles edge cases like IPv6-only networks, slow DNS responses, and mixed connectivity scenarios. The type hints are solid and work well with mypy/pylance, giving proper autocompletion for the returned reader/writer tuple. Error handling propagates asyncio exceptions naturally, making it behave predictably in failure scenarios.

The main weakness is documentation - while the API is intuitive enough that you can figure it out from type hints alone, there's minimal explanation of configuration options, timeout behavior, or best practices. The package does one thing well but assumes you understand Happy Eyeballs concepts already. For most users integrating aiohttp or other libraries that use this under the hood, you won't interact with it directly.

This library implements RFC 8305 Happy Eyeballs for asyncio, solving the dual-stack IPv4/IPv6 connection problem transparently. It's a low-level utility that most developers won't use directly—it's typically a dependency of aiohttp and other async HTTP clients. When you do need it directly for custom socket connections, it works exactly as advertised.

The API is minimal and focused: `start_connection()` returns a coroutine that yields connected sockets, trying IPv6 and IPv4 in parallel with proper fallback delays. There's virtually no learning curve if you understand asyncio sockets. Type hints are complete and accurate, making IDE integration seamless. Error handling is straightforward—exceptions bubble up from the underlying socket operations without wrapping.

Documentation is sparse but the API surface is small enough that it doesn't matter much. The README has a basic usage example that's sufficient for most cases. Since this is infrastructure-level code, you'll rarely need to debug it—it just works quietly in the background handling network connection race conditions.

This library provides Happy Eyeballs (RFC 8305) connection racing for asyncio, letting you connect to dual-stack hosts faster by trying IPv6 and IPv4 in parallel with smart fallback. It's a focused implementation that does one thing well - you pass in addresses and get back the first successful connection. The API is straightforward: `start_connection()` returns an awaitable that handles the complexity internally.

From a security perspective, this is refreshingly minimal - it's essentially plumbing between your DNS resolution and socket connection. There's no TLS handling (happens upstream in your stack), no credential management, and no complex configuration to misconfigure. The library doesn't introduce dependency bloat and error handling is clean, raising connection errors appropriately without leaking internal state.

The main gotcha is understanding where it fits: it sits between `getaddrinfo()` and socket connection, so you still need to handle TLS context setup yourself. Documentation could better explain the stagger delay tuning, but defaults follow RFC recommendations sensibly. It's maintained actively with quick CVE response when issues arise in the ecosystem.