mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
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:
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 "
|
||||
|
||||
Reference in New Issue
Block a user