fix(hf-cache): keep Offline ahead of a missing cache dir, scope the hub_api docs

Review follow-ups to the hub_api guard move:

- HfTokenizer::from_pretrained resolved the cache directory before
  hub_api's guard, so HEADROOM_OFFLINE with no cache directory came back
  as HfTokenizerError::Hub, not Offline. The missing-directory branch now
  runs guard_egress first.
- hub_api's doc claimed every Rust Hub download; Kompress::from_pretrained
  (test-only) still builds its own guarded Api::new() client. Say so.
- The offline-egress test checks the guard order inside hub_api's body,
  not the first occurrences in hf_cache.rs.
- Stale comments in kompress.rs and hf_impl.rs; `use thiserror::Error`
  like the rest of the crate.
This commit is contained in:
Kenneth Wong
2026-10-23 13:45:23 +08:00
parent 7e17a2d3e6
commit 14dbac2940
4 changed files with 30 additions and 16 deletions
+11 -6
View File
@@ -17,6 +17,8 @@
use std::path::{Path, PathBuf};
use thiserror::Error;
/// True when `HEADROOM_HF_PIN` turns revision pinning off, so pinned repos
/// float on `main` (same values as Python's `onnx_runtime._resolve_revision`).
#[cfg_attr(not(feature = "ml"), allow(dead_code))] // the pinned loaders are `ml`-only
@@ -140,7 +142,7 @@ pub(crate) fn hf_endpoint() -> String {
}
/// Why [`hub_api`] returned no client.
#[derive(Debug, thiserror::Error)]
#[derive(Debug, Error)]
pub(crate) enum HubApiError {
/// `HEADROOM_OFFLINE` is set; refused before the client existed.
#[error(transparent)]
@@ -154,11 +156,14 @@ pub(crate) enum HubApiError {
/// with [`hf_token`], as Python's `huggingface_hub` would, for fetching
/// `destination` (a repo id) for `purpose`.
///
/// This is the air-gap chokepoint for every Rust Hub download: under
/// `HEADROOM_OFFLINE` it returns [`HubApiError::Offline`] before building the
/// client, because building it resolves the endpoint and the `ureq` agent,
/// and `hf-hub` downloads on a cache miss even with `HF_HUB_OFFLINE` set.
/// Guarding here rather than in each caller means no caller can skip it.
/// This is the air-gap chokepoint for the tokenizer and embedder downloads:
/// under `HEADROOM_OFFLINE` it returns [`HubApiError::Offline`] before
/// building the client, because building it resolves the endpoint and the
/// `ureq` agent, and `hf-hub` downloads on a cache miss even with
/// `HF_HUB_OFFLINE` set. Guarding here rather than in each caller means no
/// caller of this function can skip it. (`Kompress::from_pretrained` still
/// builds its own `Api::new()` client behind its own guard; production loads
/// Kompress cache-only through `Kompress::from_cache`.)
///
/// The token is not sent over plain `http://` to a host other than loopback:
/// it would cross the network in clear text on every request, so the client
+11 -5
View File
@@ -175,15 +175,21 @@ impl HfTokenizer {
/// Refuses with [`HfTokenizerError::Offline`] under `HEADROOM_OFFLINE`.
fn hub_api(repo: &str) -> Result<hf_hub::api::sync::Api, HfTokenizerError> {
use crate::hf_cache::HubApiError;
const PURPOSE: &str = "HuggingFace tokenizer download";
let hub_error = |source: Box<dyn std::error::Error + Send + Sync>| HfTokenizerError::Hub {
repo: repo.to_string(),
source,
};
let cache = crate::hf_cache::hub_cache_dir().ok_or_else(|| {
hub_error("no HuggingFace cache directory (set HF_HUB_CACHE or HF_HOME)".into())
})?;
crate::hf_cache::hub_api(&cache, "HuggingFace tokenizer download", repo).map_err(|e| match e {
let Some(cache) = crate::hf_cache::hub_cache_dir() else {
// Offline still wins: the caller treats `Offline` as final, and a
// missing cache directory is no reason to report a Hub failure.
crate::offline::guard_egress(PURPOSE, repo)?;
return Err(hub_error(
"no HuggingFace cache directory (set HF_HUB_CACHE or HF_HOME)".into(),
));
};
crate::hf_cache::hub_api(&cache, PURPOSE, repo).map_err(|e| match e {
HubApiError::Offline(blocked) => HfTokenizerError::Offline(blocked),
HubApiError::Build(source) => hub_error(Box::new(source)),
})
@@ -317,7 +323,7 @@ mod tests {
/// this a real assertion rather than a tautology: without the guard the call
/// reaches `hf-hub`, dials `huggingface.co`, gets a 401/404 and returns
/// `HfTokenizerError::Hub`. Only the guard can produce `Offline`, and only
/// by returning before `Api::new` — so `Offline` *is* the "no socket was
/// by returning before `hf_cache::hub_api` builds the client — so `Offline` *is* the "no socket was
/// opened" assertion for this path. (A packet-level assertion is not
/// available to a `cargo test` unit test the way `socket.socket` patching is
/// in Python; this typed-error distinction is the equivalent signal.)
@@ -267,8 +267,8 @@ impl Kompress {
/// downloading on miss). Blocking — call off the hot path. Tries the
/// [`ONNX_CANDIDATES`] in order.
pub fn from_pretrained(config: KompressConfig) -> Result<Self, KompressError> {
// Air-gap chokepoint — the same one `hf_impl.rs` uses for the
// tokenizer, for the same reason. `HF_HUB_OFFLINE` only shortcuts the
// Air-gap chokepoint — the same guard `hf_cache::hub_api` runs for
// the tokenizer and embedder, for the same reason. `HF_HUB_OFFLINE` only shortcuts the
// cache *lookup*; on a cache miss `hf-hub` still dials huggingface.co,
// so the Kompress model download is a live egress path under
// `HEADROOM_OFFLINE=1` and was not covered.
+6 -3
View File
@@ -598,9 +598,12 @@ class TestRustOfflineParity:
def test_hf_fetch_guards_before_it_builds_a_client(self) -> None:
source = _RUST_HF.read_text(encoding="utf-8")
assert "guard_egress(" in source, "hf_cache.rs does not consult the offline guard"
guard_at = source.index("guard_egress(")
api_at = source.index("hf_hub::api::sync::ApiBuilder::from_cache(")
# Within hub_api itself: a guard elsewhere in the file does not count.
fn_at = source.index("pub(crate) fn hub_api(")
body = source[fn_at : source.index("\n}\n", fn_at)]
assert "guard_egress(" in body, "hf_cache::hub_api does not consult the offline guard"
guard_at = body.index("guard_egress(")
api_at = body.index("hf_hub::api::sync::ApiBuilder::from_cache(")
assert guard_at < api_at, (
"the offline guard runs after ApiBuilder::build(), which already resolves the "
"Hub endpoint and builds the ureq agent — guard before the client "