Skip to main content

hyprstream_core/services/
image_substrate.rs

1//! HTTP image substrate for stock nydus-snapshotter consumers (#789).
2//!
3//! This is a thin read-only data plane over [`RafsStore`]. Ingest and dedup
4//! remain owned by the worker image store; this module only projects already
5//! pulled RAFS bootstraps and blob CAS objects over HTTP so cluster nodes can
6//! fetch them without learning the host-local store layout.
7
8use std::sync::Arc;
9
10use axum::{
11    extract::{Extension, Path, State},
12    http::{header, HeaderMap, HeaderValue, Method, StatusCode},
13    response::{IntoResponse, Response},
14    routing::get,
15    Router,
16};
17use hyprstream_workers::image::RafsStore;
18
19use crate::server::AuthenticatedUser;
20
21/// Serving policy for the nydus image substrate.
22#[derive(Clone, Debug, Default)]
23pub struct ImageSubstratePolicy {
24    /// Permit unauthenticated read-only blob/bootstrap fetches.
25    ///
26    /// This exists for nydus/containerd deployments where the snapshotter cannot
27    /// yet forward WIT/ticket credentials. Keep it false for protected clusters.
28    pub allow_anonymous_read: bool,
29}
30
31/// Shared axum state for image substrate routes.
32#[derive(Clone)]
33pub struct ImageSubstrateState {
34    store: Arc<RafsStore>,
35    policy: ImageSubstratePolicy,
36}
37
38impl ImageSubstrateState {
39    pub fn new(store: Arc<RafsStore>, policy: ImageSubstratePolicy) -> Self {
40        Self { store, policy }
41    }
42}
43
44/// Build a read-only router exposing RAFS bootstraps and layer/config blobs.
45///
46/// Routes:
47/// - `GET|HEAD /nydus/v1/bootstraps/:image_id`
48/// - `GET|HEAD /nydus/v1/blobs/:algorithm/:hex`
49/// - `GET|HEAD /v2/*path` for registry-compatible blob paths ending in
50///   `/blobs/<algorithm>:<hex>`
51pub fn create_image_substrate_router(
52    store: Arc<RafsStore>,
53    policy: ImageSubstratePolicy,
54) -> Router {
55    let state = ImageSubstrateState::new(store, policy);
56    Router::new()
57        .route(
58            "/nydus/v1/bootstraps/:image_id",
59            get(get_bootstrap).head(head_bootstrap),
60        )
61        .route(
62            "/nydus/v1/blobs/:algorithm/:hex",
63            get(get_blob_by_parts).head(head_blob_by_parts),
64        )
65        .route("/v2/*path", get(get_registry_blob).head(head_registry_blob))
66        .with_state(state)
67}
68
69async fn get_bootstrap(
70    State(state): State<ImageSubstrateState>,
71    Path(image_id): Path<String>,
72    user: Option<Extension<AuthenticatedUser>>,
73    headers: HeaderMap,
74) -> Response {
75    serve_bootstrap(state, image_id, user, headers, Method::GET).await
76}
77
78async fn head_bootstrap(
79    State(state): State<ImageSubstrateState>,
80    Path(image_id): Path<String>,
81    user: Option<Extension<AuthenticatedUser>>,
82    headers: HeaderMap,
83) -> Response {
84    serve_bootstrap(state, image_id, user, headers, Method::HEAD).await
85}
86
87async fn get_blob_by_parts(
88    State(state): State<ImageSubstrateState>,
89    Path((algorithm, hex)): Path<(String, String)>,
90    user: Option<Extension<AuthenticatedUser>>,
91    headers: HeaderMap,
92) -> Response {
93    serve_blob(
94        state,
95        format!("{algorithm}:{hex}"),
96        user,
97        headers,
98        Method::GET,
99    )
100    .await
101}
102
103async fn head_blob_by_parts(
104    State(state): State<ImageSubstrateState>,
105    Path((algorithm, hex)): Path<(String, String)>,
106    user: Option<Extension<AuthenticatedUser>>,
107    headers: HeaderMap,
108) -> Response {
109    serve_blob(
110        state,
111        format!("{algorithm}:{hex}"),
112        user,
113        headers,
114        Method::HEAD,
115    )
116    .await
117}
118
119async fn get_registry_blob(
120    State(state): State<ImageSubstrateState>,
121    Path(path): Path<String>,
122    user: Option<Extension<AuthenticatedUser>>,
123    headers: HeaderMap,
124) -> Response {
125    match digest_from_registry_path(&path) {
126        Some(digest) => serve_blob(state, digest, user, headers, Method::GET).await,
127        None => (StatusCode::NOT_FOUND, "registry path is not a blob").into_response(),
128    }
129}
130
131async fn head_registry_blob(
132    State(state): State<ImageSubstrateState>,
133    Path(path): Path<String>,
134    user: Option<Extension<AuthenticatedUser>>,
135    headers: HeaderMap,
136) -> Response {
137    match digest_from_registry_path(&path) {
138        Some(digest) => serve_blob(state, digest, user, headers, Method::HEAD).await,
139        None => StatusCode::NOT_FOUND.into_response(),
140    }
141}
142
143async fn serve_bootstrap(
144    state: ImageSubstrateState,
145    image_id: String,
146    user: Option<Extension<AuthenticatedUser>>,
147    headers: HeaderMap,
148    method: Method,
149) -> Response {
150    if let Some(resp) = authorize(&state, user.as_ref()) {
151        return resp;
152    }
153    if !is_sha256_digest(&image_id) {
154        return (StatusCode::BAD_REQUEST, "image_id must be sha256:<hex>").into_response();
155    }
156    serve_file(
157        state.store.bootstrap_path(&image_id),
158        "application/vnd.nydus.rafs.bootstrap.v1",
159        headers,
160        method,
161    )
162    .await
163}
164
165async fn serve_blob(
166    state: ImageSubstrateState,
167    digest: String,
168    user: Option<Extension<AuthenticatedUser>>,
169    headers: HeaderMap,
170    method: Method,
171) -> Response {
172    if let Some(resp) = authorize(&state, user.as_ref()) {
173        return resp;
174    }
175    if !is_sha256_digest(&digest) {
176        return (StatusCode::BAD_REQUEST, "digest must be sha256:<hex>").into_response();
177    }
178    serve_file(
179        state.store.blob_path(&digest),
180        "application/octet-stream",
181        headers,
182        method,
183    )
184    .await
185}
186
187fn authorize(
188    state: &ImageSubstrateState,
189    user: Option<&Extension<AuthenticatedUser>>,
190) -> Option<Response> {
191    if state.policy.allow_anonymous_read || user.is_some() {
192        None
193    } else {
194        let mut resp = (StatusCode::UNAUTHORIZED, "authentication required").into_response();
195        resp.headers_mut()
196            .insert(header::WWW_AUTHENTICATE, HeaderValue::from_static("Bearer"));
197        Some(resp)
198    }
199}
200
201async fn serve_file(
202    path: std::path::PathBuf,
203    content_type: &'static str,
204    headers: HeaderMap,
205    method: Method,
206) -> Response {
207    let bytes = match tokio::fs::read(&path).await {
208        Ok(bytes) => bytes,
209        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
210            return StatusCode::NOT_FOUND.into_response();
211        }
212        Err(_) => return StatusCode::INTERNAL_SERVER_ERROR.into_response(),
213    };
214
215    let len = bytes.len() as u64;
216    let range = parse_single_range(headers.get(header::RANGE), len);
217    let mut status = StatusCode::OK;
218    let mut start = 0usize;
219    let mut end = bytes.len();
220    if let Some(Ok((range_start, range_end))) = range {
221        status = StatusCode::PARTIAL_CONTENT;
222        start = range_start as usize;
223        end = range_end as usize + 1;
224    } else if matches!(range, Some(Err(()))) {
225        let mut resp = StatusCode::RANGE_NOT_SATISFIABLE.into_response();
226        resp.headers_mut().insert(
227            header::CONTENT_RANGE,
228            HeaderValue::from_str(&format!("bytes */{len}"))
229                .unwrap_or_else(|_| HeaderValue::from_static("bytes */0")),
230        );
231        return resp;
232    }
233
234    let mut resp = if method == Method::HEAD {
235        status.into_response()
236    } else {
237        (status, bytes[start..end].to_vec()).into_response()
238    };
239    let headers = resp.headers_mut();
240    headers.insert(header::ACCEPT_RANGES, HeaderValue::from_static("bytes"));
241    headers.insert(header::CONTENT_TYPE, HeaderValue::from_static(content_type));
242    headers.insert(
243        header::CONTENT_LENGTH,
244        HeaderValue::from_str(&(end - start).to_string())
245            .unwrap_or_else(|_| HeaderValue::from_static("0")),
246    );
247    if status == StatusCode::PARTIAL_CONTENT {
248        headers.insert(
249            header::CONTENT_RANGE,
250            HeaderValue::from_str(&format!("bytes {start}-{}/{len}", end - 1))
251                .unwrap_or_else(|_| HeaderValue::from_static("bytes */0")),
252        );
253    }
254    resp
255}
256
257fn digest_from_registry_path(path: &str) -> Option<String> {
258    let (_repo, digest) = path.rsplit_once("/blobs/")?;
259    Some(digest.to_owned())
260}
261
262fn is_sha256_digest(digest: &str) -> bool {
263    let Some(hex) = digest.strip_prefix("sha256:") else {
264        return false;
265    };
266    hex.len() == 64 && hex.bytes().all(|b| b.is_ascii_hexdigit())
267}
268
269fn parse_single_range(value: Option<&HeaderValue>, len: u64) -> Option<Result<(u64, u64), ()>> {
270    let value = value?.to_str().ok()?;
271    let spec = value.strip_prefix("bytes=")?;
272    let (start, end) = spec.split_once('-')?;
273    if len == 0 {
274        return Some(Err(()));
275    }
276    if start.is_empty() {
277        let suffix = end.parse::<u64>().ok()?;
278        if suffix == 0 {
279            return Some(Err(()));
280        }
281        let start = len.saturating_sub(suffix);
282        return Some(Ok((start, len - 1)));
283    }
284    let start = start.parse::<u64>().ok()?;
285    let end = if end.is_empty() {
286        len - 1
287    } else {
288        end.parse::<u64>().ok()?
289    };
290    if start >= len || start > end {
291        return Some(Err(()));
292    }
293    Some(Ok((start, end.min(len - 1))))
294}
295
296#[cfg(test)]
297#[allow(clippy::unwrap_used, clippy::expect_used)]
298mod tests {
299    use super::*;
300
301    use axum::body::Body;
302    use axum::http::Request;
303    use hyprstream_workers::config::ImageConfig;
304    use tower::ServiceExt;
305
306    const DIGEST: &str = "sha256:00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff";
307
308    fn test_store(dir: &std::path::Path) -> Arc<RafsStore> {
309        let config = ImageConfig {
310            blobs_dir: dir.join("blobs"),
311            bootstrap_dir: dir.join("bootstrap"),
312            refs_dir: dir.join("refs"),
313            cache_dir: dir.join("cache"),
314            ..ImageConfig::default()
315        };
316        std::fs::create_dir_all(&config.blobs_dir).unwrap();
317        std::fs::create_dir_all(&config.bootstrap_dir).unwrap();
318        std::fs::create_dir_all(&config.refs_dir).unwrap();
319        std::fs::create_dir_all(&config.cache_dir).unwrap();
320        Arc::new(RafsStore::new(config).unwrap())
321    }
322
323    #[tokio::test]
324    async fn serves_bootstrap_by_image_id() {
325        let dir = tempfile::tempdir().unwrap();
326        let store = test_store(dir.path());
327        std::fs::write(store.bootstrap_path(DIGEST), b"bootstrap").unwrap();
328
329        let app = create_image_substrate_router(
330            store,
331            ImageSubstratePolicy {
332                allow_anonymous_read: true,
333            },
334        );
335        let resp = app
336            .oneshot(
337                Request::builder()
338                    .uri(format!("/nydus/v1/bootstraps/{DIGEST}"))
339                    .body(Body::empty())
340                    .unwrap(),
341            )
342            .await
343            .unwrap();
344
345        assert_eq!(resp.status(), StatusCode::OK);
346        let body = axum::body::to_bytes(resp.into_body(), usize::MAX)
347            .await
348            .unwrap();
349        assert_eq!(&body[..], b"bootstrap");
350    }
351
352    #[tokio::test]
353    async fn serves_registry_compatible_blob_path_with_ranges() {
354        let dir = tempfile::tempdir().unwrap();
355        let store = test_store(dir.path());
356        std::fs::write(store.blob_path(DIGEST), b"0123456789").unwrap();
357
358        let app = create_image_substrate_router(
359            store,
360            ImageSubstratePolicy {
361                allow_anonymous_read: true,
362            },
363        );
364        let resp = app
365            .oneshot(
366                Request::builder()
367                    .uri(format!("/v2/example/repo/blobs/{DIGEST}"))
368                    .header(header::RANGE, "bytes=2-5")
369                    .body(Body::empty())
370                    .unwrap(),
371            )
372            .await
373            .unwrap();
374
375        assert_eq!(resp.status(), StatusCode::PARTIAL_CONTENT);
376        assert_eq!(
377            resp.headers().get(header::CONTENT_RANGE).unwrap(),
378            "bytes 2-5/10"
379        );
380        let body = axum::body::to_bytes(resp.into_body(), usize::MAX)
381            .await
382            .unwrap();
383        assert_eq!(&body[..], b"2345");
384    }
385
386    #[tokio::test]
387    async fn anonymous_reads_are_opt_in() {
388        let dir = tempfile::tempdir().unwrap();
389        let store = test_store(dir.path());
390        let app = create_image_substrate_router(store, ImageSubstratePolicy::default());
391
392        let resp = app
393            .oneshot(
394                Request::builder()
395                    .uri(format!(
396                        "/nydus/v1/blobs/sha256/{}",
397                        &DIGEST["sha256:".len()..]
398                    ))
399                    .body(Body::empty())
400                    .unwrap(),
401            )
402            .await
403            .unwrap();
404
405        assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
406    }
407}