Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: race address families on sync connects (RFC 8305 Happy Eyeballs) (#10803)

Wenrui LI954bf810bfa3
diff --git a/studio/backend/core/data_recipe/jobs/worker.py b/studio/backend/core/data_recipe/jobs/worker.py
index b4c5c4d5bdb..2d2d4e06ab6 100644
--- a/studio/backend/core/data_recipe/jobs/worker.py
+++ b/studio/backend/core/data_recipe/jobs/worker.py
@@ -21,11 +21,13 @@ from ..service import build_config_builder, create_data_designer, install_public
from utils.paths.lazy import LazyPath
from utils.paths import ensure_dir, recipe_datasets_root
-# Fresh spawned interpreter: re-apply main.py's OS-trust-store injection.
+# Fresh spawned interpreter: re-apply main.py's process-wide network injections.
from utils.native_tls import activate_native_tls
+from utils.happy_eyeballs import activate_happy_eyeballs
from utils.paths.path_utils import drop_appledouble_metadata
activate_native_tls()
+activate_happy_eyeballs()
_ARTIFACT_ROOT = LazyPath(recipe_datasets_root)
_RE_GITHUB_CURSOR = re.compile(r"\bcursor=[^\s,]+")
diff --git a/studio/backend/core/export/worker.py b/studio/backend/core/export/worker.py
index 3a814b3e1bb..9d5e6408860 100644
--- a/studio/backend/core/export/worker.py
+++ b/studio/backend/core/export/worker.py
@@ -28,10 +28,12 @@ from typing import Any
logger = get_logger(__name__)
-# Fresh spawned interpreter: re-apply the OS-trust-store injection.
+# Fresh spawned interpreter: re-apply the process-wide network injections.
from utils.native_tls import activate_native_tls
+from utils.happy_eyeballs import activate_happy_eyeballs
activate_native_tls()
+activate_happy_eyeballs()
from utils.hardware import apply_gpu_ids
diff --git a/studio/backend/core/inference/stt_download_worker.py b/studio/backend/core/inference/stt_download_worker.py
index 41756667b52..a1d93e84a93 100644
--- a/studio/backend/core/inference/stt_download_worker.py
+++ b/studio/backend/core/inference/stt_download_worker.py
@@ -21,11 +21,14 @@ import time
from pathlib import Path
from typing import Optional, Sequence
-# Fresh spawned interpreter: re-apply the OS-trust-store injection.
from hub.utils.hf_tokens import apply_token_to_child_env
+
+# Fresh spawned interpreter: re-apply the process-wide network injections.
from utils.native_tls import activate_native_tls
+from utils.happy_eyeballs import activate_happy_eyeballs
activate_native_tls()
+activate_happy_eyeballs()
# How long a cancelled worker gets to exit on SIGTERM before it is killed.
diff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.py
index 8c33a9c0520..8202456dfe7 100644
--- a/studio/backend/core/inference/worker.py
+++ b/studio/backend/core/inference/worker.py
@@ -36,8 +36,9 @@ from core.inference.audio_errors import (
from core.inference.context_refusal import ContextBudgetExceeded
from utils.hardware import apply_gpu_ids, is_apple_silicon
-# Fresh spawned interpreter: re-apply the OS-trust-store injection.
+# Fresh spawned interpreter: re-apply the process-wide network injections.
from utils.native_tls import activate_native_tls
+from utils.happy_eyeballs import activate_happy_eyeballs
_ID_BYTES = 36
@@ -144,6 +145,7 @@ def narrow_load_reason(cmd: dict) -> Optional[str]:
activate_native_tls()
+activate_happy_eyeballs()
_SHARE_OBJECT_MAX_BYTES = 1 << 20
_SHARE_OBJECT_ERROR_SIZE = -1
diff --git a/studio/backend/core/training/diffusion_training_service.py b/studio/backend/core/training/diffusion_training_service.py
index 2726b8b0a3d..d0c5cdf8a26 100644
--- a/studio/backend/core/training/diffusion_training_service.py
+++ b/studio/backend/core/training/diffusion_training_service.py
@@ -65,11 +65,13 @@ def _finite_or_none(value: Any) -> Optional[float]:
def _run_diffusion_child(*, event_queue: Any, stop_queue: Any, config: dict) -> None:
- # Fresh spawned interpreter: re-apply the OS-trust-store injection, inside the secret scrub and
- # before the trainer imports diffusers.
+ # Fresh spawned interpreter: re-apply the process-wide network injections, inside the secret
+ # scrub and before the trainer imports diffusers.
from utils.native_tls import activate_native_tls
+ from utils.happy_eyeballs import activate_happy_eyeballs
activate_native_tls()
+ activate_happy_eyeballs()
# Imported lazily so this module (and the route layer) stays torch-free at import.
from .diffusion_lora_trainer import run_diffusion_training_process
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index c242961f2f5..7fe970e72be 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -43,10 +43,12 @@ if sys.platform.startswith("linux") and "HSA_ENABLE_DXG_DETECTION" not in os.env
logger = get_logger(__name__)
from utils.child_stdio import utf8_child_env
-# Fresh spawned interpreter: re-apply the OS-trust-store injection.
+# Fresh spawned interpreter: re-apply the process-wide network injections.
from utils.native_tls import activate_native_tls
+from utils.happy_eyeballs import activate_happy_eyeballs
activate_native_tls()
+activate_happy_eyeballs()
from utils.hardware import apply_gpu_ids
from utils.hf_dataset_options import hf_dataset_split_instruction_names
diff --git a/studio/backend/hub/workers/hf_download.py b/studio/backend/hub/workers/hf_download.py
index f275d696098..f074e3e104f 100644
--- a/studio/backend/hub/workers/hf_download.py
+++ b/studio/backend/hub/workers/hf_download.py
@@ -24,10 +24,12 @@ _BACKEND = _HERE.parent.parent
if str(_BACKEND) not in sys.path:
sys.path.insert(0, str(_BACKEND))
-# Fresh interpreter: main.py's truststore injection does not survive the spawn.
+# Fresh interpreter: main.py's process-wide network injections do not survive the spawn.
from utils.native_tls import activate_native_tls
+from utils.happy_eyeballs import activate_happy_eyeballs
activate_native_tls()
+activate_happy_eyeballs()
from hub.utils.snapshot_filters import (
SNAPSHOT_IGNORE_PATTERNS,
diff --git a/studio/backend/main.py b/studio/backend/main.py
index a4480008d7a..328ba9d20a2 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -193,8 +193,10 @@ if _backend_dir not in sys.path:
# OS trust store for TLS before anything opens a connection: behind a
# TLS-inspecting proxy certifi alone rejects every Hub request.
from utils.native_tls import activate_native_tls
+from utils.happy_eyeballs import activate_happy_eyeballs
activate_native_tls()
+activate_happy_eyeballs()
# `uvicorn main:app` bypasses run.py; seed thread caps here too.
from utils.cpu_threads import configure_cpu_threads
diff --git a/studio/backend/tests/test_happy_eyeballs.py b/studio/backend/tests/test_happy_eyeballs.py
new file mode 100644
index 00000000000..6bf1754c6e2
--- /dev/null
+++ b/studio/backend/tests/test_happy_eyeballs.py
@@ -0,0 +1,448 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""A black-holed address family must cost one stagger, not one timeout per address.
+
+100::/64 is the RFC 6666 discard prefix; on a host with no IPv6 route it is refused
+outright, so ordering cases script the socket instead.
+"""
+
+from __future__ import annotations
+
+import ast
+import errno
+import selectors
+import socket
+import sys
+import threading
+import time
+from pathlib import Path
+
+import pytest
+
+from utils import happy_eyeballs as he
+
+_TESTS_DIR = str(Path(__file__).resolve().parent)
+if _TESTS_DIR not in sys.path:
+ sys.path.insert(0, _TESTS_DIR)
+
+from test_native_tls_entrypoints import _ENTRYPOINTS as _NATIVE_TLS_ENTRYPOINTS # noqa: E402
+
+# Activate inside a spawned child function or inline script, so the native TLS guard does not list them.
+_EXTRA_ENTRYPOINTS = (
+ "core/training/diffusion_training_service.py",
+ "utils/models/model_config.py",
+)
+
+
+DISCARD = [f"100::{i + 1}" for i in range(8)]
+
+
+def listener():
+ srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+ srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+ srv.bind(("127.0.0.1", 0))
+ srv.listen(32)
+ accepted = []
+
+ def _accept():
+ while True:
+ try:
+ accepted.append(srv.accept()[0])
+ except OSError:
+ return
+
+ threading.Thread(target = _accept, daemon = True).start()
+ yield srv.getsockname()[1]
+ srv.close()
+ for sock in accepted:
+ sock.close()
+
+
+def _resolver(
+ port,
+ *,
+ aaaa = 8,
+ with_a = True,
+):
+ def _getaddrinfo(
+ host,
+ _port,
+ family = 0,
+ type = 0,
+ proto = 0,
+ flags = 0,
+ ):
+ infos = [
+ (socket.AF_INET6, socket.SOCK_STREAM, 6, "", (addr, port, 0, 0))
+ for addr in DISCARD[:aaaa]
+ ]
+ if with_a:
+ infos.append((socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", port)))
+ return infos
+
+ return _getaddrinfo
+
+
+def test_families_are_interleaved_not_walked_in_resolver_order():
+ infos = [
+ (socket.AF_INET6, socket.SOCK_STREAM, 6, "", ("100::1", 443, 0, 0)),
+ (socket.AF_INET6, socket.SOCK_STREAM, 6, "", ("100::2", 443, 0, 0)),
+ (socket.AF_INET6, socket.SOCK_STREAM, 6, "", ("100::3", 443, 0, 0)),
+ (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("1.2.3.4", 443)),
+ (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("5.6.7.8", 443)),
+ ]
+ assert [i[4][0] for i in he._interleave(infos)] == [
+ "100::1",
+ "1.2.3.4",
+ "100::2",
+ "5.6.7.8",
+ "100::3",
+ ], "the second family must get a turn before the first family is exhausted"
+
+
+def test_eight_black_holed_aaaa_cost_one_stagger(listener, monkeypatch):
+ monkeypatch.setattr(socket, "getaddrinfo", _resolver(listener))
+
+ start = time.monotonic()
+ sock = he.happy_eyeballs_connection(("hub.invalid", listener), 10)
+ elapsed = time.monotonic() - start
+ try:
+ assert sock.getpeername()[0] == "127.0.0.1"
+ finally:
+ sock.close()
+
+ # The stdlib pays 8 x 10s.
+ assert elapsed < 3.0, f"took {elapsed:.1f}s; the AAAA records were walked in order"
+
+
+def test_the_whole_walk_costs_one_timeout_plus_staggers_not_one_timeout_each(monkeypatch):
+ monkeypatch.setattr(socket, "getaddrinfo", _resolver(443, aaaa = 6, with_a = False))
+
+ start = time.monotonic()
+ with pytest.raises(OSError):
+ he.happy_eyeballs_connection(("hub.invalid", 443), 3)
+ elapsed = time.monotonic() - start
+
+ # 3s + five staggers = 4.25s; the stdlib pays 18s.
+ assert (
+ elapsed < 6.0
+ ), f"took {elapsed:.1f}s for a 3s budget; the timeout is still applied per address"
+
+
+def test_a_reachable_address_late_in_the_list_is_still_dialled(monkeypatch):
+ """Every attempt keeps the whole timeout, so a live address opened past
+ ``timeout / delay`` staggers is still dialled, as the stdlib would."""
+ monkeypatch.setenv(he._DELAY_ENV, "0.05")
+ good = "127.0.0.1"
+ dialled = []
+
+ class _Stub:
+ def __init__(self, family, *_args, **_kwargs):
+ self.family = family
+ self.peer = None
+
+ def setblocking(self, _flag):
+ pass
+
+ def settimeout(self, _value):
+ pass
+
+ def connect_ex(self, sa):
+ dialled.append(sa[0])
+ self.peer = sa[0]
+ return 0 if sa[0] == good else errno.EINPROGRESS
+
+ def close(self):
+ pass
+
+ class _NeverReady:
+ def register(self, *_args, **_kwargs):
+ pass
+
+ def unregister(self, *_args, **_kwargs):
+ pass
+
+ def select(self, timeout):
+ if timeout:
+ time.sleep(timeout + 0.03) # a loaded runner oversleeps every stagger
+ return []
+
+ def close(self):
+ pass
+
+ # TEST-NET-1 black holes; the live address is ninth, due 0.4s in.
+ monkeypatch.setattr(
+ socket,
+ "getaddrinfo",
+ lambda *a, **k: [
+ (socket.AF_INET, socket.SOCK_STREAM, 6, "", (f"192.0.2.{i + 1}", 443)) for i in range(8)
+ ]
+ + [(socket.AF_INET, socket.SOCK_STREAM, 6, "", (good, 443))],
+ )
+ monkeypatch.setattr(socket, "socket", _Stub)
+ monkeypatch.setattr(selectors, "DefaultSelector", _NeverReady)
+
+ sock = he.happy_eyeballs_connection(("hub.invalid", 443), 0.2)
+
+ assert good in dialled, (
+ "the only live address was never dialled; the stdlib would have reached it with "
+ "a whole timeout of its own"
+ )
+ assert sock.peer == good, "the race returned a black hole instead of the winner"
+
+
+def test_a_single_address_resolves_once_and_keeps_the_callers_timeout(listener, monkeypatch):
+ lookups = []
+
+ def _one(*a, **k):
+ lookups.append(a[0])
+ return [(socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", listener))]
+
+ monkeypatch.setattr(socket, "getaddrinfo", _one)
+ sock = he.happy_eyeballs_connection(("one.invalid", listener), 5)
+ try:
+ assert sock.gettimeout() == 5
+ finally:
+ sock.close()
+ assert lookups == ["one.invalid"], "the host was resolved more than once"
+
+
+def test_a_refused_port_still_raises_immediately(monkeypatch):
+ """Racing must not turn a fast, definite failure into a wait for the deadline."""
+ monkeypatch.setattr(
+ socket,
+ "getaddrinfo",
+ lambda *a, **k: [
+ (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", 1)),
+ (socket.AF_INET6, socket.SOCK_STREAM, 6, "", ("::1", 1, 0, 0)),
+ ],
+ )
+
+ start = time.monotonic()
+ with pytest.raises(OSError) as excinfo:
+ he.happy_eyeballs_connection(("refused.invalid", 1), 30)
+ elapsed = time.monotonic() - start
+
+ # Windows retries a reset SYN for ~2s; the stdlib pays that per address too.
+ assert elapsed < 10.0, f"a refused connect waited {elapsed:.1f}s instead of failing"
+ assert excinfo.value.errno in (errno.ECONNREFUSED, errno.EADDRNOTAVAIL)
+
+
+def test_the_last_failure_is_raised_not_the_first(monkeypatch):
+ """hf_tcp_reachable reads ECONNREFUSED as "the Hub answered"."""
+ scripted = {"100::1": errno.ENETUNREACH, "127.0.0.1": errno.ECONNREFUSED}
+
+ class _Stub:
+ def __init__(self, family, *_args, **_kwargs):
+ self.family = family
+
+ def setblocking(self, _flag):
+ pass
+
+ def connect_ex(self, sa):
+ return scripted[sa[0]]
+
+ def close(self):
+ pass
+
+ monkeypatch.setattr(
+ socket,
+ "getaddrinfo",
+ lambda *a, **k: [
+ (socket.AF_INET6, socket.SOCK_STREAM, 6, "", ("100::1", 443, 0, 0)),
+ (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", 443)),
+ ],
+ )
+ monkeypatch.setattr(socket, "socket", _Stub)
+
+ with pytest.raises(OSError) as excinfo:
+ he.happy_eyeballs_connection(("hub.invalid", 443), 5)
+
+ assert excinfo.value.errno == errno.ECONNREFUSED, (
+ "raised the first family's failure instead of the last; hf_tcp_reachable reads "
+ "that as an unreachable Hub"
+ )
+
+
+def test_a_deadline_reached_with_attempts_in_flight_raises_a_timeout(monkeypatch):
+ class _Stub:
+ def __init__(self, family, *_args, **_kwargs):
+ self.family = family
+
+ def setblocking(self, _flag):
+ pass
+
+ def connect_ex(self, sa):
+ return errno.ECONNREFUSED if sa[0] == "127.0.0.1" else errno.EINPROGRESS
+
+ def close(self):
+ pass
+
+ class _NeverReady:
+ def register(self, *_args, **_kwargs):
+ pass
+
+ def unregister(self, *_args, **_kwargs):
+ pass
+
+ def select(self, timeout):
+ if timeout:
+ time.sleep(min(timeout, 0.05))
+ return []
+
+ def close(self):
+ pass
+
+ monkeypatch.setattr(
+ socket,
+ "getaddrinfo",
+ lambda *a, **k: [
+ (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", 443)),
+ (socket.AF_INET6, socket.SOCK_STREAM, 6, "", ("100::1", 443, 0, 0)),
+ ],
+ )
+ monkeypatch.setattr(socket, "socket", _Stub)
+ monkeypatch.setattr(selectors, "DefaultSelector", _NeverReady)
+
+ with pytest.raises(socket.timeout):
+ he.happy_eyeballs_connection(("hub.invalid", 443), 0.3)
+
+
+def _mixed_list_connector(monkeypatch, order):
+ """What the connector raises for "hole" (never answers) and "refused" in *order*."""
+ monkeypatch.setenv(he._DELAY_ENV, "0.05")
+ addr = {"hole": ("192.0.2.1", 443), "refused": ("127.0.0.1", 1)}
+
+ class _Stub:
+ def __init__(self, family, *_args, **_kwargs):
+ self.family = family
+
+ def setblocking(self, _flag):
+ pass
+
+ def connect_ex(self, sa):
+ return errno.ECONNREFUSED if sa == addr["refused"] else errno.EINPROGRESS
+
+ def close(self):
+ pass
+
+ class _NeverReady:
+ def register(self, *_args, **_kwargs):
+ pass
+
+ def unregister(self, *_args, **_kwargs):
+ pass
+
+ def select(self, timeout):
+ if timeout:
+ time.sleep(timeout)
+ return []
+
+ def close(self):
+ pass
+
+ monkeypatch.setattr(
+ socket,
+ "getaddrinfo",
+ lambda *a, **k: [(socket.AF_INET, socket.SOCK_STREAM, 6, "", addr[k]) for k in order],
+ )
+ monkeypatch.setattr(socket, "socket", _Stub)
+ monkeypatch.setattr(selectors, "DefaultSelector", _NeverReady)
+
+ with pytest.raises(OSError) as excinfo:
+ he.happy_eyeballs_connection(("hub.invalid", 443), 0.2)
+ return excinfo.value
+
+
+def test_a_black_hole_then_a_refused_address_raises_refused_as_the_stdlib_does(monkeypatch):
+ exc = _mixed_list_connector(monkeypatch, ("hole", "refused"))
+ assert isinstance(
+ exc, ConnectionRefusedError
+ ), f"raised {type(exc).__name__}; the stdlib raises the last address's refusal"
+
+
+def test_a_refused_address_then_a_black_hole_raises_a_timeout_as_the_stdlib_does(monkeypatch):
+ exc = _mixed_list_connector(monkeypatch, ("refused", "hole"))
+ assert isinstance(
+ exc, socket.timeout
+ ), f"raised {type(exc).__name__}; the stdlib raises the last address's timeout"
+
+
+def test_the_winning_socket_is_blocking_with_the_callers_timeout(listener, monkeypatch):
+ monkeypatch.setattr(socket, "getaddrinfo", _resolver(listener, aaaa = 2))
+
+ sock = he.happy_eyeballs_connection(("hub.invalid", listener), 7)
+ try:
+ assert sock.gettimeout() == 7
+ finally:
+ sock.close()
+
+
+def test_the_env_switch_turns_it_off(monkeypatch):
+ monkeypatch.setenv(he._ENV, "0")
+ assert he.happy_eyeballs_enabled() is False
+ monkeypatch.setenv(he._ENV, "1")
+ assert he.happy_eyeballs_enabled() is True
+ monkeypatch.delenv(he._ENV, raising = False)
+ assert he.happy_eyeballs_enabled() is True, "it must be on by default"
+
+
+def test_activation_installs_the_connector_and_is_idempotent(monkeypatch):
+ monkeypatch.setattr(he, "_activated", False)
+ monkeypatch.setattr(socket, "create_connection", he._original_create_connection)
+
+ assert he.activate_happy_eyeballs() is True
+ assert socket.create_connection is he.happy_eyeballs_connection
+ assert he.activate_happy_eyeballs() is True
+
+
+def test_every_network_entry_point_activates_it():
+ import pathlib
+ backend = pathlib.Path(he.__file__).resolve().parent.parent
+ for rel in tuple(_NATIVE_TLS_ENTRYPOINTS) + _EXTRA_ENTRYPOINTS:
+ src = (backend / rel).read_text(encoding = "utf-8")
+ assert "activate_native_tls()" in src, f"{rel} moved; update this guard"
+ assert (
+ "activate_happy_eyeballs()" in src
+ ), f"{rel} activates native TLS but not happy eyeballs"
+ ast.parse(src)
+
+
+def test_the_config_probe_child_activates_it(monkeypatch):
+ import subprocess
+
+ from utils.transformers_version import _PROBE_CONFIG_SCRIPT
+
+ monkeypatch.delenv(he._ENV, raising = False)
+ head = _PROBE_CONFIG_SCRIPT.partition("target_dir, model_name")[0]
+ out = subprocess.run(
+ [sys.executable, "-c", head + "import socket\nprint(socket.create_connection.__name__)\n"],
+ capture_output = True,
+ text = True,
+ timeout = 60,
+ )
+ assert out.stdout.strip() == "happy_eyeballs_connection", out.stderr
+
+
+def test_a_fixed_source_port_walks_like_the_stdlib(monkeypatch):
+ calls = []
+ monkeypatch.setattr(he, "_walk", lambda *a, **k: calls.append(a) or "sock")
+ monkeypatch.setattr(socket, "getaddrinfo", _resolver(443, aaaa = 2))
+
+ assert he.happy_eyeballs_connection(("hub.invalid", 443), 5, ("0.0.0.0", 40000)) == "sock"
+ assert calls, "a fixed source port was raced; the second bind would fail with EADDRINUSE"
+
+
+def test_the_sequential_walk_raises_what_the_stdlib_raises(monkeypatch):
+ monkeypatch.setattr(
+ socket,
+ "getaddrinfo",
+ lambda *a, **k: [(socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", 1))],
+ )
+ with pytest.raises(ConnectionRefusedError):
+ he.happy_eyeballs_connection(("refused.invalid", 1), 5)
+ if sys.version_info >= (3, 11):
+ with pytest.raises(ExceptionGroup): # noqa: F821
+ he.happy_eyeballs_connection(("refused.invalid", 1), 5, all_errors = True)
diff --git a/studio/backend/utils/happy_eyeballs.py b/studio/backend/utils/happy_eyeballs.py
new file mode 100644
index 00000000000..a68cd42dd57
--- /dev/null
+++ b/studio/backend/utils/happy_eyeballs.py
@@ -0,0 +1,238 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""RFC 8305 Happy Eyeballs for sync connects.
+
+``socket.create_connection`` applies ``timeout`` per resolved address, so a black-holed
+family (VPN without IPv6) costs one timeout per address (python/cpython#88810). httpx's
+sync backend and ``http.client`` call it; ``requests`` does not (urllib3 2.x has its own
+loop). Spawned children must re-activate, like :mod:`utils.native_tls`.
+"""
+
+from __future__ import annotations
+
+import errno
+import logging
+import os
+import selectors
+import socket
+import sys
+import time
+
+_ENV = "UNSLOTH_STUDIO_HAPPY_EYEBALLS"
+_DELAY_ENV = "UNSLOTH_STUDIO_HAPPY_EYEBALLS_DELAY"
+_FALSEY = ("0", "false", "no", "off")
+
+# Connection Attempt Delay, RFC 8305 section 5.
+_DEFAULT_DELAY = 0.25
+
+_IN_FLIGHT = frozenset({errno.EINPROGRESS, errno.EWOULDBLOCK, errno.EALREADY})
+_HAS_EXCEPTION_GROUP = sys.version_info >= (3, 11)
+
+_logger = logging.getLogger(__name__)
+_original_create_connection = socket.create_connection
+_activated = False
+
+
+def happy_eyeballs_enabled() -> bool:
+ return os.environ.get(_ENV, "").strip().lower() not in _FALSEY
+
+
+def attempt_delay() -> float:
+ try:
+ value = float(os.environ.get(_DELAY_ENV, "").strip() or _DEFAULT_DELAY)
+ except ValueError:
+ return _DEFAULT_DELAY
+ return max(0.0, value)
+
+
+def _interleave(infos: list) -> list:
+ """Round-robin across families, resolver order kept within each."""
+ by_family: dict = {}
+ for info in infos:
+ by_family.setdefault(info[0], []).append(info)
+ queues = list(by_family.values())
+ ordered = []
+ for i in range(max((len(q) for q in queues), default = 0)):
+ for q in queues:
+ if i < len(q):
+ ordered.append(q[i])
+ return ordered
+
+
+def _walk(infos, timeout, source_address, all_errors):
+ """The stdlib's sequential loop over already-resolved addresses: no second lookup."""
+ if not infos:
+ raise OSError("getaddrinfo returns an empty list")
+ exceptions = []
+ for af, socktype, proto, _canon, sa in infos:
+ sock = None
+ try:
+ sock = socket.socket(af, socktype, proto)
+ if timeout is not socket._GLOBAL_DEFAULT_TIMEOUT:
+ sock.settimeout(timeout)
+ if source_address:
+ sock.bind(source_address)
+ sock.connect(sa)
+ return sock
+ except OSError as exc:
+ if not all_errors:
+ exceptions.clear()
+ exceptions.append(exc)
+ if sock is not None:
+ sock.close()
+ if all_errors and _HAS_EXCEPTION_GROUP:
+ raise ExceptionGroup("create_connection failed", exceptions) # novermin
+ raise exceptions[0]
+
+
+def happy_eyeballs_connection(
+ address,
+ timeout = socket._GLOBAL_DEFAULT_TIMEOUT,
+ source_address = None,
+ *,
+ all_errors = False,
+):
+ """Drop-in ``socket.create_connection``: attempts overlap, each with the whole ``timeout``."""
+ host, port = address
+ if timeout is socket._GLOBAL_DEFAULT_TIMEOUT:
+ resolved_timeout = socket.getdefaulttimeout()
+ else:
+ resolved_timeout = timeout
+
+ infos = socket.getaddrinfo(host, port, 0, socket.SOCK_STREAM)
+ # A fixed source port can only be bound by one socket at a time, so it cannot race.
+ if len(infos) <= 1 or (source_address and source_address[1]):
+ return _walk(infos, timeout, source_address, all_errors)
+
+ ordered = _interleave(infos)
+ delay = attempt_delay()
+ exceptions: list = []
+ failed: dict = {} # sockaddr -> its failure
+ pending: dict = {} # socket -> (sockaddr, expiry); every attempt gets the whole timeout
+ winner = None
+
+ def _fail(sa, exc):
+ exceptions.append(exc)
+ failed[sa] = exc
+
+ sel = selectors.DefaultSelector()
+ try:
+ index = 0
+ next_due = 0.0
+ kick = True # a failed attempt lets the next one start at once (RFC 8305)
+ while True:
+ now = time.monotonic()
+ for sock, (sa, expiry) in list(pending.items()):
+ if expiry is not None and expiry <= now:
+ sel.unregister(sock)
+ del pending[sock]
+ sock.close()
+ _fail(sa, socket.timeout("timed out"))
+ kick = True
+ if index < len(ordered) and (kick or not pending or now >= next_due):
+ kick = False
+ af, socktype, proto, _canon, sa = ordered[index]
+ index += 1
+ next_due = now + delay
+ sock = None
+ try:
+ sock = socket.socket(af, socktype, proto)
+ sock.setblocking(False)
+ if source_address:
+ sock.bind(source_address)
+ err = sock.connect_ex(sa)
+ if err == 0:
+ winner = sock
+ break
+ if err not in _IN_FLIGHT:
+ raise OSError(err, os.strerror(err))
+ sel.register(sock, selectors.EVENT_WRITE)
+ pending[sock] = (
+ sa,
+ None if resolved_timeout is None else now + resolved_timeout,
+ )
+ except OSError as exc:
+ _fail(sa, exc)
+ kick = True
+ if sock is not None:
+ sock.close()
+ continue
+ if not pending:
+ if index >= len(ordered):
+ break
+ continue
+
+ wakes = [e for _sa, e in pending.values() if e is not None]
+ if index < len(ordered):
+ wakes.append(next_due)
+ wait = max(0.0, min(wakes) - time.monotonic()) if wakes else None
+ for key, _mask in sel.select(wait):
+ sock = key.fileobj
+ err = sock.getsockopt(socket.SOL_SOCKET, socket.SO_ERROR)
+ sel.unregister(sock)
+ sa, _expiry = pending.pop(sock)
+ if err == 0:
+ winner = sock
+ break
+ sock.close()
+ _fail(sa, OSError(err, os.strerror(err)))
+ kick = True
+ if winner is not None:
+ break
+ finally:
+ for sock in list(pending):
+ try:
+ sel.unregister(sock)
+ except Exception: # noqa: BLE001
+ pass
+ if sock is not winner:
+ sock.close()
+ sel.close()
+
+ if winner is not None:
+ winner.setblocking(True)
+ winner.settimeout(resolved_timeout)
+ return winner
+
+ if not exceptions:
+ exceptions.append(socket.timeout("timed out"))
+ if all_errors and _HAS_EXCEPTION_GROUP:
+ raise ExceptionGroup("create_connection failed", exceptions) # novermin
+ # Like the stdlib, the last address in resolver order decides the error:
+ # hf_tcp_reachable reads ECONNREFUSED as "the endpoint answered".
+ raise failed.get(infos[-1][4]) or socket.timeout("timed out")
+
+
+def activate_happy_eyeballs() -> bool:
+ """Idempotently install the connector process-wide; True when active."""
+ global _activated
+ if _activated:
+ return True
+ if not happy_eyeballs_enabled():
+ return False
+ try:
+ socket.create_connection = happy_eyeballs_connection
+ except Exception as exc: # noqa: BLE001
+ _logger.warning(
+ "happy eyeballs unavailable (%s); connects keep the stdlib's "
+ "one-timeout-per-address walk",
+ exc,
+ )
+ return False
+ _activated = True
+ return True
+
+
+def inline_activation_source() -> str:
+ """Activation as source, for a ``python -c`` child that cannot import backend modules."""
+ return (
+ "try:\n"
+ " import importlib.util as _he_util\n"
+ f" _he_spec = _he_util.spec_from_file_location('_studio_happy_eyeballs', {os.path.abspath(__file__)!r})\n"
+ " _he_mod = _he_util.module_from_spec(_he_spec)\n"
+ " _he_spec.loader.exec_module(_he_mod)\n"
+ " _he_mod.activate_happy_eyeballs()\n"
+ "except Exception:\n"
+ " pass\n"
+ )
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index 05091d54486..64bd73a9215 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -993,6 +993,11 @@ try:
activate_native_tls()
except Exception:
pass
+try:
+ from utils.happy_eyeballs import activate_happy_eyeballs
+ activate_happy_eyeballs()
+except Exception:
+ pass
try:
from transformers import AutoConfig
diff --git a/studio/backend/utils/transformers_version.py b/studio/backend/utils/transformers_version.py
index b3c39c063f0..b6e25bad238 100644
--- a/studio/backend/utils/transformers_version.py
+++ b/studio/backend/utils/transformers_version.py
@@ -58,6 +58,7 @@ from hub.utils.hf_tokens import (
from utils.native_path_leases import child_env_without_native_path_secret
from utils.prebuilt.update_flow import resolves_into_studio_app_tree
from utils.native_tls import inline_gate_source, vendor_dir
+from utils.happy_eyeballs import inline_activation_source
from utils.child_stdio import utf8_child_env
from utils.hf_cache_settings import get_hf_cache_paths
from utils.subprocess_compat import (
@@ -1528,6 +1529,7 @@ _TRUSTSTORE_VENDOR = """
+ repr(vendor_dir())
+ "\n"
+ inline_gate_source()
+ + inline_activation_source()
+ r"""
target_dir, model_name = sys.argv[1], sys.argv[2]
if target_dir: # empty = probe the ambient (default-tier) transformers, no sidecar prepend