Skip to content

Commit 21cad4c

Browse files
fix(models): race-free lazy encoder load; timeout and length check for model downloads
OnnxEncoder._load (#340): the unlocked fast path only checked _session, and _session was assigned before Tokenizer.from_file ran. A concurrent encode_texts on the shared encoder could skip loading and call encode_batch on a None tokenizer. The session and tokenizer are now built into locals and published tokenizer-first, session-last. Both the fast path and the in-lock re-check require both attributes to be set. A failed tokenizer load leaves the encoder unloaded so a retry works. fd.models.pull (#341): _fetch called urlopen with no timeout and copied the body without checking its length. A stalled mirror blocked forever, and a connection closed early installed a truncated file. _fetch now passes timeout=FRESHDATA_MODEL_TIMEOUT (default 60 seconds; a non-numeric, non-finite or non-positive value raises ValueError). It counts the bytes written and raises OSError when the count differs from Content-Length. pull()'s existing cleanup removes the .part file, so nothing is installed. FRESHDATA_MODEL_TIMEOUT is documented in docs/semantic-models.md. Closes #340 Closes #341
1 parent 28072bf commit 21cad4c

4 files changed

Lines changed: 339 additions & 10 deletions

File tree

‎docs/semantic-models.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,11 @@ Models live in `~/.freshdata/models/<model-id>/`; override the directory with
5454
> checksums as artifacts are published; a pinned checksum that does not match
5555
> is refused at download *and* at load time.
5656
57+
Downloads use a network timeout of 60 seconds per connection attempt and
58+
socket read; override it with `FRESHDATA_MODEL_TIMEOUT` (a positive number of
59+
seconds). A transfer that ends before the server's advertised `Content-Length`
60+
raises `OSError` and nothing is installed; the partial `.part` file is removed.
61+
5762
### Air-gapped installs
5863

5964
Copy the model files into the model directory by hand:

‎src/freshdata/models/download.py‎

Lines changed: 43 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@
88

99
from __future__ import annotations
1010

11+
import math
1112
import os
12-
import shutil
1313
import tempfile
1414
import urllib.request
1515
from pathlib import Path
@@ -20,16 +20,55 @@
2020
_URL_BASE_ENV = "FRESHDATA_MODEL_URL_BASE"
2121
#: Empty until official artifacts are hosted; see docs/semantic-models.md.
2222
_DEFAULT_URL_BASE = ""
23+
_TIMEOUT_ENV = "FRESHDATA_MODEL_TIMEOUT"
24+
_DEFAULT_TIMEOUT = "60"
25+
_CHUNK_SIZE = 1024 * 1024
2326

2427

2528
def _url_base() -> str:
2629
return os.environ.get(_URL_BASE_ENV, _DEFAULT_URL_BASE)
2730

2831

32+
def _timeout() -> float:
33+
"""Network timeout in seconds (``FRESHDATA_MODEL_TIMEOUT``, default 60)."""
34+
raw = os.environ.get(_TIMEOUT_ENV, _DEFAULT_TIMEOUT)
35+
try:
36+
value = float(raw)
37+
except ValueError:
38+
value = math.nan
39+
if not (math.isfinite(value) and value > 0):
40+
raise ValueError(f"{_TIMEOUT_ENV} must be a positive number of seconds, got {raw!r}")
41+
return value
42+
43+
44+
def _content_length(response: object) -> int | None:
45+
headers = getattr(response, "headers", None)
46+
raw = headers.get("Content-Length") if headers is not None else None
47+
try:
48+
return int(raw) if raw is not None else None
49+
except ValueError:
50+
return None
51+
52+
2953
def _fetch(url: str, dest: Path) -> None:
30-
"""Download ``url`` to ``dest``. The single network seam (mocked in tests)."""
31-
with urllib.request.urlopen(url) as response, dest.open("wb") as fh: # noqa: S310
32-
shutil.copyfileobj(response, fh)
54+
"""Download ``url`` to ``dest``. The single network seam (mocked in tests).
55+
56+
Raises :class:`OSError` when the transfer ends before the advertised
57+
``Content-Length`` (the caller discards the partial file).
58+
"""
59+
timeout = _timeout()
60+
with urllib.request.urlopen(url, timeout=timeout) as response: # noqa: S310
61+
expected = _content_length(response)
62+
written = 0
63+
with dest.open("wb") as fh:
64+
while True:
65+
chunk = response.read(_CHUNK_SIZE)
66+
if not chunk:
67+
break
68+
fh.write(chunk)
69+
written += len(chunk)
70+
if expected is not None and written != expected:
71+
raise OSError(f"incomplete download of {url}: got {written} of {expected} bytes")
3372

3473

3574
def pull(model_id: str, *, force: bool = False) -> Path:

‎src/freshdata/models/runtime.py‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -53,26 +53,34 @@ def __init__(self, model_id: str) -> None:
5353
self._tokenizer: Any = None
5454
self._lock = threading.Lock()
5555

56-
def _load(self) -> None: # pragma: no cover - requires real model files
57-
if self._session is not None:
56+
def _loaded(self) -> bool:
57+
return self._session is not None and self._tokenizer is not None
58+
59+
def _load(self) -> None:
60+
# Double-checked locking. Both objects are built into locals and
61+
# published tokenizer-first, session-last, so a concurrent caller on
62+
# the unlocked fast path never observes a half-loaded encoder.
63+
if self._loaded():
5864
return
5965
with self._lock:
60-
if self._session is not None:
66+
if self._loaded():
6167
return
6268
ort = require_onnxruntime()
6369
tokenizers = require_tokenizers()
6470
verify(self.model_id) # refuses on pinned-checksum mismatch
6571
base = model_dir() / self.model_id
6672
options = ort.SessionOptions()
6773
options.intra_op_num_threads = min(4, os.cpu_count() or 1)
68-
self._session = ort.InferenceSession(
74+
session = ort.InferenceSession(
6975
str(base / "model.onnx"),
7076
sess_options=options,
7177
providers=["CPUExecutionProvider"],
7278
)
73-
self._tokenizer = tokenizers.Tokenizer.from_file(str(base / "tokenizer.json"))
79+
tokenizer = tokenizers.Tokenizer.from_file(str(base / "tokenizer.json"))
80+
self._tokenizer = tokenizer
81+
self._session = session
7482

75-
def encode_texts(self, texts: Sequence[str]) -> np.ndarray: # pragma: no cover
83+
def encode_texts(self, texts: Sequence[str]) -> np.ndarray:
7684
self._load()
7785
chunks: list[np.ndarray] = []
7886
for start in range(0, len(texts), _BATCH_SIZE):
Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
"""Model download robustness and race-free lazy encoder loading.
2+
3+
Covers #340 (``OnnxEncoder._load`` must never expose a half-loaded encoder to
4+
a concurrent caller) and #341 (``fd.models.pull`` must pass a network timeout
5+
and refuse truncated transfers). Everything is offline: ``onnxruntime`` and
6+
``tokenizers`` are replaced with fakes, and ``urllib.request.urlopen`` with an
7+
in-memory response.
8+
"""
9+
10+
from __future__ import annotations
11+
12+
import io
13+
import sys
14+
import threading
15+
import types
16+
import urllib.request
17+
from email.message import Message
18+
19+
import numpy as np
20+
import pytest
21+
22+
import freshdata as fd
23+
from freshdata.models import download as dl
24+
from freshdata.models import runtime
25+
26+
# --------------------------------------------------------------------------
27+
# #340: lazy encoder load race
28+
# --------------------------------------------------------------------------
29+
30+
31+
class _Encoding:
32+
ids = [1, 2]
33+
attention_mask = [1, 1]
34+
35+
36+
class _FakeTokenizer:
37+
def encode_batch(self, batch):
38+
return [_Encoding() for _ in batch]
39+
40+
41+
class _FakeSession:
42+
def run(self, _outputs, feeds):
43+
return [np.ones(feeds["input_ids"].shape + (4,), dtype=np.float32)]
44+
45+
46+
@pytest.fixture
47+
def fake_runtime(monkeypatch, tmp_path):
48+
"""Install fake onnxruntime/tokenizers; ``hooks`` controls from_file."""
49+
monkeypatch.setenv("FRESHDATA_MODEL_DIR", str(tmp_path))
50+
hooks: dict = {"from_file": lambda: None, "from_file_calls": 0, "session_calls": 0}
51+
52+
ort = types.ModuleType("onnxruntime")
53+
tok = types.ModuleType("tokenizers")
54+
55+
class SessionOptions:
56+
intra_op_num_threads = 1
57+
58+
def inference_session(*_args, **_kwargs):
59+
hooks["session_calls"] += 1
60+
return _FakeSession()
61+
62+
class Tokenizer:
63+
@staticmethod
64+
def from_file(_path):
65+
hooks["from_file_calls"] += 1
66+
hooks["from_file"]()
67+
return _FakeTokenizer()
68+
69+
ort.SessionOptions = SessionOptions
70+
ort.InferenceSession = inference_session
71+
tok.Tokenizer = Tokenizer
72+
monkeypatch.setitem(sys.modules, "onnxruntime", ort)
73+
monkeypatch.setitem(sys.modules, "tokenizers", tok)
74+
monkeypatch.setattr(runtime, "verify", lambda model_id: False)
75+
return hooks
76+
77+
78+
def test_concurrent_first_use_waits_for_complete_load(fake_runtime):
79+
started = threading.Event()
80+
release = threading.Event()
81+
82+
def slow_from_file():
83+
started.set()
84+
assert release.wait(10), "test did not release the tokenizer load"
85+
86+
fake_runtime["from_file"] = slow_from_file
87+
enc = runtime.OnnxEncoder("fd-col-encoder-v1")
88+
errors: list[str] = []
89+
results: list[np.ndarray] = []
90+
91+
def work():
92+
try:
93+
results.append(enc.encode_texts(["a"]))
94+
except Exception as exc: # noqa: BLE001 - surfaced via assertion
95+
errors.append(repr(exc))
96+
97+
first = threading.Thread(target=work)
98+
first.start()
99+
assert started.wait(10)
100+
# The first thread is now inside Tokenizer.from_file holding the lock.
101+
second = threading.Thread(target=work)
102+
second.start()
103+
second.join(0.3)
104+
# Before the fix the second thread saw ``_session`` set and crashed on a
105+
# None tokenizer; now it must still be waiting for the load to finish.
106+
assert second.is_alive(), errors
107+
assert errors == []
108+
release.set()
109+
first.join(10)
110+
second.join(10)
111+
assert not first.is_alive() and not second.is_alive()
112+
assert errors == []
113+
assert len(results) == 2
114+
assert all(r.shape == (1, 4) for r in results)
115+
assert fake_runtime["from_file_calls"] == 1
116+
assert fake_runtime["session_calls"] == 1
117+
118+
119+
def test_many_threads_first_use_load_once(fake_runtime):
120+
n = 8
121+
barrier = threading.Barrier(n)
122+
enc = runtime.OnnxEncoder("fd-col-encoder-v1")
123+
errors: list[str] = []
124+
125+
def work():
126+
try:
127+
barrier.wait(10)
128+
enc.encode_texts(["a", "b"])
129+
except Exception as exc: # noqa: BLE001 - surfaced via assertion
130+
errors.append(repr(exc))
131+
132+
threads = [threading.Thread(target=work) for _ in range(n)]
133+
for t in threads:
134+
t.start()
135+
for t in threads:
136+
t.join(10)
137+
assert errors == []
138+
assert fake_runtime["from_file_calls"] == 1
139+
assert fake_runtime["session_calls"] == 1
140+
141+
142+
def test_fast_path_requires_both_session_and_tokenizer(fake_runtime):
143+
enc = runtime.OnnxEncoder("fd-col-encoder-v1")
144+
enc._session = _FakeSession() # half-loaded: session without tokenizer
145+
enc._load()
146+
assert enc._tokenizer is not None
147+
assert fake_runtime["from_file_calls"] == 1
148+
149+
enc._load() # fully loaded: fast path, no reload
150+
assert fake_runtime["from_file_calls"] == 1
151+
152+
153+
def test_failed_tokenizer_load_leaves_encoder_unloaded(fake_runtime):
154+
def boom():
155+
raise RuntimeError("tokenizer.json unreadable")
156+
157+
fake_runtime["from_file"] = boom
158+
enc = runtime.OnnxEncoder("fd-col-encoder-v1")
159+
with pytest.raises(RuntimeError, match="unreadable"):
160+
enc.encode_texts(["a"])
161+
assert enc._session is None
162+
assert enc._tokenizer is None
163+
164+
fake_runtime["from_file"] = lambda: None
165+
assert enc.encode_texts(["a"]).shape == (1, 4)
166+
167+
168+
# --------------------------------------------------------------------------
169+
# #341: download timeout and truncation detection
170+
# --------------------------------------------------------------------------
171+
172+
173+
class _FakeResponse:
174+
def __init__(self, body: bytes, content_length: int | None) -> None:
175+
self._stream = io.BytesIO(body)
176+
self.headers = Message()
177+
if content_length is not None:
178+
self.headers["Content-Length"] = str(content_length)
179+
180+
def read(self, amt: int = -1) -> bytes:
181+
return self._stream.read(amt)
182+
183+
def __enter__(self):
184+
return self
185+
186+
def __exit__(self, *_exc):
187+
return False
188+
189+
190+
@pytest.fixture
191+
def model_home(tmp_path, monkeypatch):
192+
monkeypatch.setenv("FRESHDATA_MODEL_DIR", str(tmp_path))
193+
monkeypatch.setenv("FRESHDATA_MODEL_URL_BASE", "https://example.test/models")
194+
monkeypatch.delenv("FRESHDATA_MODEL_TIMEOUT", raising=False)
195+
return tmp_path
196+
197+
198+
def _install_urlopen(monkeypatch, body: bytes, content_length: int | None):
199+
calls: list[dict] = []
200+
201+
def fake_urlopen(url, *args, **kwargs):
202+
calls.append({"url": url, "args": args, "kwargs": kwargs})
203+
return _FakeResponse(body, content_length)
204+
205+
monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
206+
return calls
207+
208+
209+
def test_truncated_download_raises_and_installs_nothing(model_home, monkeypatch):
210+
_install_urlopen(monkeypatch, b"X" * 1000, content_length=1_000_000)
211+
with pytest.raises(OSError, match=r"incomplete download of .*got 1000 of 1000000 bytes"):
212+
fd.models.pull("fd-intent-v1")
213+
target = model_home / "fd-intent-v1"
214+
assert not (target / "model.onnx").exists()
215+
assert not list(target.glob("*.part"))
216+
assert fd.models.status()["fd-intent-v1"]["installed"] is False
217+
218+
219+
def test_fetch_truncated_leaves_partial_for_caller_cleanup(tmp_path, monkeypatch):
220+
monkeypatch.delenv("FRESHDATA_MODEL_TIMEOUT", raising=False)
221+
_install_urlopen(monkeypatch, b"abc", content_length=10)
222+
dest = tmp_path / "x.part"
223+
with pytest.raises(OSError, match="got 3 of 10 bytes"):
224+
dl._fetch("https://example.test/m/x", dest)
225+
assert dest.read_bytes() == b"abc" # pull()'s finally removes it
226+
227+
228+
def test_complete_download_installs(model_home, monkeypatch):
229+
payload = b"model-bytes" * 500_000 # larger than one read chunk
230+
calls = _install_urlopen(monkeypatch, payload, content_length=len(payload))
231+
primary = fd.models.pull("fd-intent-v1")
232+
assert primary.read_bytes() == payload
233+
assert not list(primary.parent.glob("*.part"))
234+
assert [c["url"] for c in calls] == ["https://example.test/models/fd-intent-v1/model.onnx"]
235+
236+
237+
def test_download_without_content_length_is_accepted(model_home, monkeypatch):
238+
_install_urlopen(monkeypatch, b"payload", content_length=None)
239+
primary = fd.models.pull("fd-intent-v1")
240+
assert primary.read_bytes() == b"payload"
241+
242+
243+
def test_default_timeout_is_passed(model_home, monkeypatch):
244+
calls = _install_urlopen(monkeypatch, b"ok", content_length=2)
245+
fd.models.pull("fd-intent-v1")
246+
assert calls[0]["kwargs"]["timeout"] == 60.0
247+
248+
249+
def test_timeout_env_override_is_passed(model_home, monkeypatch):
250+
monkeypatch.setenv("FRESHDATA_MODEL_TIMEOUT", "2.5")
251+
calls = _install_urlopen(monkeypatch, b"ok", content_length=2)
252+
fd.models.pull("fd-intent-v1")
253+
assert calls[0]["kwargs"]["timeout"] == 2.5
254+
255+
256+
@pytest.mark.parametrize("raw", ["abc", "", "0", "-1", "nan", "inf"])
257+
def test_invalid_timeout_env_raises_value_error(model_home, monkeypatch, raw):
258+
monkeypatch.setenv("FRESHDATA_MODEL_TIMEOUT", raw)
259+
calls = _install_urlopen(monkeypatch, b"ok", content_length=2)
260+
with pytest.raises(ValueError, match="FRESHDATA_MODEL_TIMEOUT must be a positive number"):
261+
fd.models.pull("fd-intent-v1")
262+
assert calls == []
263+
target = model_home / "fd-intent-v1"
264+
assert not (target / "model.onnx").exists()
265+
assert not list(target.glob("*.part"))
266+
267+
268+
def test_timeout_error_discards_partial(model_home, monkeypatch):
269+
def stalled(url, *args, **kwargs):
270+
raise TimeoutError("timed out")
271+
272+
monkeypatch.setattr(urllib.request, "urlopen", stalled)
273+
with pytest.raises(TimeoutError):
274+
fd.models.pull("fd-intent-v1")
275+
target = model_home / "fd-intent-v1"
276+
assert not (target / "model.onnx").exists()
277+
assert not list(target.glob("*.part"))

0 commit comments

Comments
 (0)