fix(websocket): handle IPv6 4-tuple in listener getsockname()

[yashksaini-coder]

Summary

Fixes #1316 — WebsocketListener.listen() could not bind any IPv6 address because it unpacked socket.getsockname() directly into a 2-tuple, which fails for IPv6 (which returns a 4-tuple (host, port, flowinfo, scopeid)).

Context

The ValueError from the bad unpack was caught by the outer except Exception in listen() and re-raised as OpenConnectionError("Failed to listen on ..."), so IPv6 WebSocket listeners failed silently-but-hard rather than exposing the real cause. Flagged as a follow-up from the PR #1308 review (inline comment on libp2p/transport/websocket/listener.py:289).

Approach

Extract the socket-name parsing into _extract_host_port_from_sockname(), a small helper that accepts any tuple of length ≥ 2 where the first two elements are a (host: str, port: int) pair. Any other shape returns None, and the listener logs a warning and falls back to the originally requested host/port. Because the helper is a pure function, it can be unit-tested without binding an actual IPv6 socket (which is not portable across all CI environments).

sock_name = sock.getsockname()
host_port = _extract_host_port_from_sockname(sock_name)
if host_port is not None:
    actual_host, actual_port = host_port
else:
    logger.warning("Unexpected getsockname() result %r; falling back to requested host/port", sock_name)

Files changed

• libp2p/transport/websocket/listener.py — add _extract_host_port_from_sockname, use it in listen()
• tests/core/transport/websocket/test_extract_host_port.py — new unit tests (IPv4 2-tuple, IPv6 4-tuple with zero and nonzero scopeid, unrecognised shapes)
• newsfragments/1316.bugfix.rst — changelog entry

Testing

• pytest tests/core/transport/websocket/test_extract_host_port.py tests/core/transport/websocket/test_websocket.py — 52 passed (including 4 new cases)
• make lint clean (ruff, ruff-format, mypy, pyrefly, path audit)

References

• Issue: fix(websocket): listener fails to bind IPv6 due to getsockname() unpack #1316
• Flagged during review of: fix(transport): remove nursery param from IListener.listen (adopts #1055) #1308

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Fixes IPv6 WebSocket listener binding by correctly handling the 4-tuple shape returned from socket.getsockname() and preventing the listener from failing with a masked ValueError.

Changes:

• Added _extract_host_port_from_sockname() to safely parse (host, port) from IPv4/IPv6 getsockname() results.
• Updated WebsocketListener.listen() to use the helper and warn+fallback on unexpected shapes.
• Added focused unit tests and a changelog entry for the IPv6 binding fix.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
libp2p/transport/websocket/listener.py	Adds a helper to parse IPv4/IPv6 getsockname() return values and uses it during listener setup.
tests/core/transport/websocket/test_extract_host_port.py	Introduces unit tests covering IPv4/IPv6 tuple shapes and unknown inputs.
newsfragments/1316.bugfix.rst	Documents the IPv6 listener binding fix and the new fallback behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The warning says the listener is 'falling back to requested host/port', but the code doesn’t explicitly apply a fallback here. This makes the behavior dependent on actual_host/actual_port being pre-initialized elsewhere and is harder to reason about. Consider explicitly setting actual_host/actual_port to the requested values in the else branch to match the log message and keep the control flow self-contained.

[Copilot]

Using Any in a runtime-evaluated annotation can introduce an unnecessary runtime dependency on typing.Any being in scope (depending on whether postponed evaluation of annotations is enabled in this module). Prefer sock_name: object here (since you’re doing runtime type checks anyway), or ensure Any is imported and annotations are postponed consistently across the module.

[yashksaini-coder]

Addressed Copilot feedback in cc5813b:

• _extract_host_port_from_sockname parameter is now sock_name: object rather than Any — matches the runtime isinstance checks and drops the unnecessary typing.Any dependency in the annotation.
• The "unexpected getsockname() result" branch now explicitly re-assigns actual_host, actual_port = host, port before logging the warning, so the "falling back to requested host/port" message is self-contained in the code flow rather than relying on pre-initialised values.