release: retunnel 3.1.2 — reach a local app bound to ::1 (#59)

An application the user could browse at http://localhost:PORT returned 502
through the tunnel whenever it was bound to ::1, because the client only ever
dialled 127.0.0.1. That is the common shape on macOS, where localhost resolves
to ::1 first and many dev servers bind IPv6 only.

Addressing the app as the NAME "localhost" is NOT a sufficient fix and was
rejected after testing: it depends on the host's /etc/hosts, and on a machine
whose localhost has no AAAA record getaddrinfo returns 127.0.0.1 alone, leaving
an IPv6-only app just as unreachable. Both loopback literals are now tried
explicitly (IPv4 first, as the common case) for HTTP, WebSocket and TCP
streams, and whichever answers is remembered for the rest of the session so
only the first request pays for probing.

Probe: audit/evaluations/probe_local_address_family.py asserts BOTH families,
since a fix that merely moved the failure would otherwise look identical.
Verified: red on published 3.1.1 (IPv6 502), green on this build; full harness
12/12 against production.

Refs #59

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: ourway

VERSION

@@ -1 +1 @@
-3.1.1
+3.1.2

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "retunnel"
-version = "3.1.1"
+version = "3.1.2"
 description = "ReTunnel - Securely expose local servers to the internet"
 authors = [{name = "ReTunnel Team", email = "support@retunnel.com"}]
 license = "MIT"

retunnel/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = "3.1.1"
+__version__ = "3.1.2"
 
 from .client.client import ReTunnelClient, TunnelConfig
 

retunnel/client/tcp_stream.py

@@ -5,6 +5,7 @@
 import asyncio
 import logging
 
+from retunnel.local_proxy import LOCAL_HOST, LOCAL_HOSTS
 from retunnel.msg.messages import StreamOpen
 
 from .streams import Sender, StreamState
@@ -15,11 +16,24 @@
 async def handle_tcp_stream(
     msg: StreamOpen, state: StreamState, sender: Sender, port: int
 ) -> None:
-    try:
-        reader, writer = await asyncio.open_connection("127.0.0.1", port)
-    except Exception as e:
-        logger.warning("TCP connect to 127.0.0.1:%d failed: %s", port, e)
-        await sender.reset(f"{type(e).__name__}: {e}")
+    reader = None
+    writer = None
+    last: Exception | None = None
+    for host in LOCAL_HOSTS:
+        try:
+            reader, writer = await asyncio.open_connection(host, port)
+            break
+        except OSError as e:  # nothing listening on this family
+            last = e
+    if reader is None or writer is None:
+        logger.warning(
+            "TCP connect to %s:%d failed on %s: %s",
+            LOCAL_HOST,
+            port,
+            "/".join(LOCAL_HOSTS),
+            last,
+        )
+        await sender.reset(f"{type(last).__name__}: {last}")
         return
 
     async def local_to_server() -> None:

retunnel/local_proxy.py

@@ -18,6 +18,27 @@
 # not send them; the local app must see the caller's request, not ours.
 _SKIP_AUTO = frozenset({"Accept", "Accept-Encoding", "User-Agent"})
 
+# Loopback addresses tried, in order, when reaching the local application.
+#
+# Hardcoding 127.0.0.1 meant an app the user could browse at
+# http://localhost:PORT answered 502 through the tunnel whenever it was bound
+# to ::1 -- the common case on macOS, where localhost resolves to ::1 first and
+# many dev servers bind IPv6 only (issuedb #59).
+#
+# Resolving the NAME "localhost" is NOT a fix: it depends on the host's
+# /etc/hosts, and where localhost has no AAAA record (this build machine)
+# getaddrinfo returns 127.0.0.1 alone and an IPv6-only app stays unreachable.
+# Both literals are therefore tried explicitly, IPv4 first as the common case;
+# whichever answers is remembered for the rest of the session.
+LOCAL_HOSTS = ("127.0.0.1", "::1")
+# The name used in logs and messages.
+LOCAL_HOST = "localhost"
+
+
+def _authority(host: str, port: int) -> str:
+    """host:port, bracketing an IPv6 literal as a URL requires."""
+    return f"[{host}]:{port}" if ":" in host else f"{host}:{port}"
+
 
 class LocalProxyResponse:
     def __init__(self, resp: aiohttp.ClientResponse) -> None:
@@ -41,11 +62,14 @@ async def close(self) -> None:
 
 
 class LocalProxy:
-    """Connections to the local application on 127.0.0.1:<port>."""
+    """Connections to the local application on localhost:<port>."""
 
     def __init__(self, port: int) -> None:
         self.port = port
         self._session: aiohttp.ClientSession | None = None
+        # The loopback address that last worked, so only the first request of
+        # a session pays for probing both families.
+        self._host: str | None = None
 
     def _get_session(self) -> aiohttp.ClientSession:
         if self._session is None or self._session.closed:
@@ -57,10 +81,17 @@ def _get_session(self) -> aiohttp.ClientSession:
             )
         return self._session
 
-    def url(self, target: str, scheme: str = "http") -> URL:
+    def hosts(self) -> tuple[str, ...]:
+        """Loopback addresses to try, best-known first."""
+        if self._host is not None:
+            return (self._host,)
+        return LOCAL_HOSTS
+
+    def url(self, target: str, scheme: str = "http", host: str = "") -> URL:
         if not target.startswith("/"):
             target = "/" + target
-        return URL(f"{scheme}://127.0.0.1:{self.port}{target}", encoded=True)
+        authority = _authority(host or self.hosts()[0], self.port)
+        return URL(f"{scheme}://{authority}{target}", encoded=True)
 
     async def open_http(
         self,
@@ -69,15 +100,23 @@ async def open_http(
         headers: list[tuple[str, str]],
         body: bytes,
     ) -> LocalProxyResponse:
-        resp = await self._get_session().request(
-            method,
-            self.url(target),
-            headers=CIMultiDict(headers),
-            data=body if body else None,
-            allow_redirects=False,
-            skip_auto_headers=_SKIP_AUTO,
-        )
-        return LocalProxyResponse(resp)
+        last: Exception | None = None
+        for host in self.hosts():
+            try:
+                resp = await self._get_session().request(
+                    method,
+                    self.url(target, host=host),
+                    headers=CIMultiDict(headers),
+                    data=body if body else None,
+                    allow_redirects=False,
+                    skip_auto_headers=_SKIP_AUTO,
+                )
+            except aiohttp.ClientConnectorError as e:
+                last = e  # nothing listening on this family; try the other
+                continue
+            self._host = host
+            return LocalProxyResponse(resp)
+        raise last if last is not None else RuntimeError("no loopback address")
 
     async def open_ws(
         self,
@@ -87,14 +126,23 @@ async def open_ws(
     ) -> aiohttp.ClientWebSocketResponse:
         """Upgrade to the local app. Raises aiohttp.WSServerHandshakeError
         (with .status and .headers) when the app refuses the upgrade."""
-        return await self._get_session().ws_connect(
-            self.url(target, "ws"),
-            headers=CIMultiDict(headers),
-            protocols=subprotocols,
-            autoping=True,
-            max_msg_size=0,
-            compress=0,
-        )
+        last: Exception | None = None
+        for host in self.hosts():
+            try:
+                ws = await self._get_session().ws_connect(
+                    self.url(target, "ws", host=host),
+                    headers=CIMultiDict(headers),
+                    protocols=subprotocols,
+                    autoping=True,
+                    max_msg_size=0,
+                    compress=0,
+                )
+            except aiohttp.ClientConnectorError as e:
+                last = e
+                continue
+            self._host = host
+            return ws
+        raise last if last is not None else RuntimeError("no loopback address")
 
     async def close(self) -> None:
         if self._session is not None and not self._session.closed: