Skip to main content

hyprstream_workers/image/
manifest.rs

1//! Minimal OCI manifest fetcher for image metadata.
2//!
3//! This module only handles manifest fetching via HTTP. All blob operations
4//! go through nydus-storage's backend-registry for Dragonfly P2P compatibility.
5
6use anyhow::{anyhow, Context, Result};
7use reqwest::header::{HeaderValue, ACCEPT, AUTHORIZATION, WWW_AUTHENTICATE};
8use reqwest::Client;
9use serde::{Deserialize, Serialize};
10use std::collections::HashMap;
11use std::time::Duration;
12
13/// OCI media types for manifest negotiation.
14#[allow(dead_code)]
15pub mod media_types {
16    pub const OCI_MANIFEST: &str = "application/vnd.oci.image.manifest.v1+json";
17    pub const OCI_INDEX: &str = "application/vnd.oci.image.index.v1+json";
18    pub const DOCKER_MANIFEST: &str = "application/vnd.docker.distribution.manifest.v2+json";
19    pub const DOCKER_MANIFEST_LIST: &str =
20        "application/vnd.docker.distribution.manifest.list.v2+json";
21}
22
23/// Parsed OCI image reference.
24#[derive(Debug, Clone)]
25pub struct ImageReference {
26    /// Registry host (e.g., "registry-1.docker.io")
27    pub host: String,
28    /// Repository path (e.g., "library/alpine")
29    pub repository: String,
30    /// Tag or digest reference (e.g., "latest" or "sha256:...")
31    pub reference: String,
32    /// Whether reference is a digest
33    pub is_digest: bool,
34}
35
36impl ImageReference {
37    /// Parse an image reference string.
38    ///
39    /// Handles formats like:
40    /// - `alpine` -> docker.io/library/alpine:latest
41    /// - `alpine:3.18` -> docker.io/library/alpine:3.18
42    /// - `myrepo/myimage:tag` -> docker.io/myrepo/myimage:tag
43    /// - `ghcr.io/owner/repo:tag` -> ghcr.io/owner/repo:tag
44    /// - `registry.example.com/foo/bar@sha256:...` -> registry.example.com/foo/bar@sha256:...
45    pub fn parse(image: &str) -> Result<Self> {
46        let image = image.trim();
47        if image.is_empty() {
48            return Err(anyhow!("empty image reference"));
49        }
50
51        // Check for digest reference
52        let (image_part, reference, is_digest) = if let Some(idx) = image.rfind('@') {
53            let (img, digest) = image.split_at(idx);
54            (img.to_owned(), digest[1..].to_string(), true)
55        } else if let Some(idx) = image.rfind(':') {
56            // Check if this colon is part of a port number (host:port/repo)
57            let before_colon = &image[..idx];
58            if before_colon.contains('/') || !before_colon.contains('.') {
59                // It's a tag separator
60                let (img, tag) = image.split_at(idx);
61                (img.to_owned(), tag[1..].to_string(), false)
62            } else {
63                // It's a port separator, use default tag
64                (image.to_owned(), "latest".to_owned(), false)
65            }
66        } else {
67            (image.to_owned(), "latest".to_owned(), false)
68        };
69
70        // Parse host and repository
71        let (host, repository) = if let Some(first_slash) = image_part.find('/') {
72            let potential_host = &image_part[..first_slash];
73
74            // Check if this is a hostname (contains . or : or is "localhost")
75            if potential_host.contains('.')
76                || potential_host.contains(':')
77                || potential_host == "localhost"
78            {
79                let host = potential_host.to_owned();
80                let repo = image_part[first_slash + 1..].to_string();
81                (host, repo)
82            } else {
83                // No explicit host, use Docker Hub
84                ("docker.io".to_owned(), image_part)
85            }
86        } else {
87            // Simple name like "alpine" -> docker.io/library/alpine
88            ("docker.io".to_owned(), format!("library/{image_part}"))
89        };
90
91        // Docker Hub's actual registry host
92        let host = if host == "docker.io" {
93            "registry-1.docker.io".to_owned()
94        } else {
95            host
96        };
97
98        Ok(Self {
99            host,
100            repository,
101            reference,
102            is_digest,
103        })
104    }
105
106    /// Get the manifest URL for this image.
107    pub fn manifest_url(&self) -> String {
108        format!(
109            "https://{}/v2/{}/manifests/{}",
110            self.host, self.repository, self.reference
111        )
112    }
113
114    /// Get the blob URL for a given digest.
115    pub fn blob_url(&self, digest: &str) -> String {
116        format!(
117            "https://{}/v2/{}/blobs/{}",
118            self.host, self.repository, digest
119        )
120    }
121}
122
123/// OCI Image Manifest (single-platform).
124#[derive(Debug, Clone, Serialize, Deserialize)]
125#[serde(rename_all = "camelCase")]
126pub struct OciManifest {
127    pub schema_version: u32,
128    #[serde(default)]
129    pub media_type: Option<String>,
130    pub config: Descriptor,
131    pub layers: Vec<Descriptor>,
132    #[serde(default)]
133    pub annotations: HashMap<String, String>,
134}
135
136/// OCI Image Index (multi-platform manifest list).
137#[derive(Debug, Clone, Serialize, Deserialize)]
138#[serde(rename_all = "camelCase")]
139pub struct OciIndex {
140    pub schema_version: u32,
141    #[serde(default)]
142    pub media_type: Option<String>,
143    pub manifests: Vec<ManifestDescriptor>,
144    #[serde(default)]
145    pub annotations: HashMap<String, String>,
146}
147
148/// Content descriptor.
149#[derive(Debug, Clone, Serialize, Deserialize)]
150#[serde(rename_all = "camelCase")]
151pub struct Descriptor {
152    pub media_type: String,
153    pub digest: String,
154    pub size: u64,
155    #[serde(default)]
156    pub annotations: HashMap<String, String>,
157}
158
159/// Manifest descriptor with platform info.
160#[derive(Debug, Clone, Serialize, Deserialize)]
161#[serde(rename_all = "camelCase")]
162pub struct ManifestDescriptor {
163    pub media_type: String,
164    pub digest: String,
165    pub size: u64,
166    #[serde(default)]
167    pub platform: Option<Platform>,
168    #[serde(default)]
169    pub annotations: HashMap<String, String>,
170}
171
172/// Platform specification.
173#[derive(Debug, Clone, Serialize, Deserialize)]
174pub struct Platform {
175    pub architecture: String,
176    pub os: String,
177    #[serde(default, rename = "os.version")]
178    pub os_version: Option<String>,
179    #[serde(default, rename = "os.features")]
180    pub os_features: Option<Vec<String>>,
181    #[serde(default)]
182    pub variant: Option<String>,
183    #[serde(default)]
184    pub features: Option<Vec<String>>,
185}
186
187/// Result of fetching a manifest - could be single or multi-platform.
188#[derive(Debug, Clone)]
189pub enum ManifestResult {
190    /// Single-platform manifest
191    Manifest(OciManifest),
192    /// Multi-platform index
193    Index(OciIndex),
194}
195
196/// Authentication configuration.
197#[derive(Debug, Clone, Default)]
198pub struct AuthConfig {
199    pub username: Option<String>,
200    pub password: Option<String>,
201    pub token: Option<String>,
202}
203
204/// Minimal manifest fetcher using reqwest.
205pub struct ManifestFetcher {
206    client: Client,
207    /// Cached bearer tokens per realm
208    tokens: parking_lot::RwLock<HashMap<String, String>>,
209}
210
211impl ManifestFetcher {
212    /// Create a new manifest fetcher.
213    pub fn new() -> Result<Self> {
214        let client = Client::builder()
215            .timeout(Duration::from_secs(30))
216            .connect_timeout(Duration::from_secs(10))
217            .build()
218            .context("failed to create HTTP client")?;
219
220        Ok(Self {
221            client,
222            tokens: parking_lot::RwLock::new(HashMap::new()),
223        })
224    }
225
226    /// Fetch manifest for an image reference.
227    pub async fn fetch(
228        &self,
229        image_ref: &ImageReference,
230        auth: Option<&AuthConfig>,
231    ) -> Result<ManifestResult> {
232        let url = image_ref.manifest_url();
233
234        // Try with cached token first
235        if let Some(token) = self.get_cached_token(&image_ref.host) {
236            match self.fetch_with_token(&url, &token).await {
237                Ok(result) => return Ok(result),
238                Err(_) => {
239                    // Token might be expired, clear it
240                    self.tokens.write().remove(&image_ref.host);
241                }
242            }
243        }
244
245        // Try anonymous first
246        match self.fetch_anonymous(&url).await {
247            Ok(result) => return Ok(result),
248            Err(e) => {
249                tracing::debug!("anonymous fetch failed: {}, trying auth", e);
250            }
251        }
252
253        // Need to authenticate
254        let token = self.authenticate(image_ref, auth).await?;
255        self.tokens
256            .write()
257            .insert(image_ref.host.clone(), token.clone());
258        self.fetch_with_token(&url, &token).await
259    }
260
261    /// Fetch a specific platform manifest from an index.
262    pub async fn fetch_platform_manifest(
263        &self,
264        image_ref: &ImageReference,
265        digest: &str,
266        auth: Option<&AuthConfig>,
267    ) -> Result<OciManifest> {
268        let url = format!(
269            "https://{}/v2/{}/manifests/{}",
270            image_ref.host, image_ref.repository, digest
271        );
272
273        // Try with cached token
274        if let Some(token) = self.get_cached_token(&image_ref.host) {
275            if let Ok(result) = self.fetch_manifest_with_token(&url, &token).await {
276                return Ok(result);
277            }
278        }
279
280        // Need to authenticate
281        let token = self.authenticate(image_ref, auth).await?;
282        self.fetch_manifest_with_token(&url, &token).await
283    }
284
285    fn get_cached_token(&self, host: &str) -> Option<String> {
286        self.tokens.read().get(host).cloned()
287    }
288
289    async fn fetch_anonymous(&self, url: &str) -> Result<ManifestResult> {
290        let resp = self
291            .client
292            .get(url)
293            .header(ACCEPT, accept_header())
294            .send()
295            .await?;
296
297        if resp.status().is_success() {
298            self.parse_manifest_response(resp).await
299        } else {
300            Err(anyhow!(
301                "anonymous fetch failed with status {}",
302                resp.status()
303            ))
304        }
305    }
306
307    async fn fetch_with_token(&self, url: &str, token: &str) -> Result<ManifestResult> {
308        let resp = self
309            .client
310            .get(url)
311            .header(ACCEPT, accept_header())
312            .header(AUTHORIZATION, format!("Bearer {token}"))
313            .send()
314            .await?;
315
316        if resp.status().is_success() {
317            self.parse_manifest_response(resp).await
318        } else {
319            Err(anyhow!("fetch failed with status {}", resp.status()))
320        }
321    }
322
323    async fn fetch_manifest_with_token(&self, url: &str, token: &str) -> Result<OciManifest> {
324        let resp = self
325            .client
326            .get(url)
327            .header(
328                ACCEPT,
329                format!(
330                    "{}, {}",
331                    media_types::OCI_MANIFEST,
332                    media_types::DOCKER_MANIFEST
333                ),
334            )
335            .header(AUTHORIZATION, format!("Bearer {token}"))
336            .send()
337            .await?;
338
339        if resp.status().is_success() {
340            resp.json().await.context("failed to parse manifest JSON")
341        } else {
342            Err(anyhow!(
343                "fetch manifest failed with status {}",
344                resp.status()
345            ))
346        }
347    }
348
349    async fn parse_manifest_response(&self, resp: reqwest::Response) -> Result<ManifestResult> {
350        let content_type = resp
351            .headers()
352            .get("content-type")
353            .and_then(|v| v.to_str().ok())
354            .map(std::borrow::ToOwned::to_owned)
355            .unwrap_or_default();
356
357        let body = resp.text().await.context("failed to read response body")?;
358
359        // Determine if it's an index or manifest based on content type or structure
360        if content_type.contains("index")
361            || content_type.contains("manifest.list")
362            || body.contains("\"manifests\"")
363        {
364            let index: OciIndex =
365                serde_json::from_str(&body).context("failed to parse index JSON")?;
366            Ok(ManifestResult::Index(index))
367        } else {
368            let manifest: OciManifest =
369                serde_json::from_str(&body).context("failed to parse manifest JSON")?;
370            Ok(ManifestResult::Manifest(manifest))
371        }
372    }
373
374    /// Authenticate with the registry and get a bearer token.
375    async fn authenticate(
376        &self,
377        image_ref: &ImageReference,
378        auth: Option<&AuthConfig>,
379    ) -> Result<String> {
380        // First, make an unauthenticated request to get the WWW-Authenticate header
381        let url = image_ref.manifest_url();
382        let resp = self
383            .client
384            .get(&url)
385            .header(ACCEPT, accept_header())
386            .send()
387            .await?;
388
389        if resp.status() == 401 {
390            // Parse WWW-Authenticate header
391            let www_auth = resp
392                .headers()
393                .get(WWW_AUTHENTICATE)
394                .and_then(|v| v.to_str().ok())
395                .ok_or_else(|| anyhow!("missing WWW-Authenticate header"))?;
396
397            let auth_params = parse_www_authenticate(www_auth)?;
398            let realm = auth_params
399                .get("realm")
400                .ok_or_else(|| anyhow!("missing realm in WWW-Authenticate"))?;
401
402            // Build token request URL
403            let mut token_url = reqwest::Url::parse(realm).context("invalid realm URL")?;
404            {
405                let mut query = token_url.query_pairs_mut();
406                if let Some(service) = auth_params.get("service") {
407                    query.append_pair("service", service);
408                }
409                if let Some(scope) = auth_params.get("scope") {
410                    query.append_pair("scope", scope);
411                } else {
412                    // Default scope for pulling
413                    query.append_pair(
414                        "scope",
415                        &format!("repository:{}:pull", image_ref.repository),
416                    );
417                }
418            }
419
420            // Make token request
421            let mut token_req = self.client.get(token_url);
422            if let Some(auth_config) = auth {
423                if let (Some(user), Some(pass)) = (&auth_config.username, &auth_config.password) {
424                    token_req = token_req.basic_auth(user, Some(pass));
425                } else if let Some(token) = &auth_config.token {
426                    token_req = token_req.bearer_auth(token);
427                }
428            }
429
430            let token_resp = token_req.send().await?;
431            if !token_resp.status().is_success() {
432                return Err(anyhow!(
433                    "token request failed with status {}",
434                    token_resp.status()
435                ));
436            }
437
438            let token_data: TokenResponse = token_resp.json().await?;
439            Ok(token_data
440                .token
441                .or(token_data.access_token)
442                .ok_or_else(|| anyhow!("no token in response"))?)
443        } else if resp.status().is_success() {
444            // No auth needed
445            Err(anyhow!("no authentication required"))
446        } else {
447            Err(anyhow!(
448                "unexpected status {} during auth check",
449                resp.status()
450            ))
451        }
452    }
453}
454
455/// Token response from registry auth server.
456#[derive(Debug, Deserialize)]
457struct TokenResponse {
458    token: Option<String>,
459    access_token: Option<String>,
460}
461
462/// Build the Accept header for manifest requests.
463fn accept_header() -> HeaderValue {
464    HeaderValue::from_static(
465        "application/vnd.oci.image.manifest.v1+json, \
466         application/vnd.oci.image.index.v1+json, \
467         application/vnd.docker.distribution.manifest.v2+json, \
468         application/vnd.docker.distribution.manifest.list.v2+json",
469    )
470}
471
472/// Parse WWW-Authenticate header.
473fn parse_www_authenticate(header: &str) -> Result<HashMap<String, String>> {
474    let mut params = HashMap::new();
475
476    // Format: Bearer realm="...",service="...",scope="..."
477    let header = header.trim_start_matches("Bearer ");
478    for part in header.split(',') {
479        let part = part.trim();
480        if let Some(eq_idx) = part.find('=') {
481            let key = part[..eq_idx].trim().to_owned();
482            let value = part[eq_idx + 1..].trim().trim_matches('"').to_owned();
483            params.insert(key, value);
484        }
485    }
486
487    Ok(params)
488}
489
490#[cfg(test)]
491mod tests {
492    use super::*;
493
494    #[test]
495    fn test_parse_simple_image() -> Result<()> {
496        let ref_ = ImageReference::parse("alpine")?;
497        assert_eq!(ref_.host, "registry-1.docker.io");
498        assert_eq!(ref_.repository, "library/alpine");
499        assert_eq!(ref_.reference, "latest");
500        assert!(!ref_.is_digest);
501        Ok(())
502    }
503
504    #[test]
505    fn test_parse_tagged_image() -> Result<()> {
506        let ref_ = ImageReference::parse("alpine:3.18")?;
507        assert_eq!(ref_.host, "registry-1.docker.io");
508        assert_eq!(ref_.repository, "library/alpine");
509        assert_eq!(ref_.reference, "3.18");
510        Ok(())
511    }
512
513    #[test]
514    fn test_parse_user_repo() -> Result<()> {
515        let ref_ = ImageReference::parse("myuser/myimage:v1")?;
516        assert_eq!(ref_.host, "registry-1.docker.io");
517        assert_eq!(ref_.repository, "myuser/myimage");
518        assert_eq!(ref_.reference, "v1");
519        Ok(())
520    }
521
522    #[test]
523    fn test_parse_custom_registry() -> Result<()> {
524        let ref_ = ImageReference::parse("ghcr.io/owner/repo:tag")?;
525        assert_eq!(ref_.host, "ghcr.io");
526        assert_eq!(ref_.repository, "owner/repo");
527        assert_eq!(ref_.reference, "tag");
528        Ok(())
529    }
530
531    #[test]
532    fn test_parse_digest() -> Result<()> {
533        let ref_ = ImageReference::parse("alpine@sha256:abc123")?;
534        assert_eq!(ref_.host, "registry-1.docker.io");
535        assert_eq!(ref_.repository, "library/alpine");
536        assert_eq!(ref_.reference, "sha256:abc123");
537        assert!(ref_.is_digest);
538        Ok(())
539    }
540
541    #[test]
542    fn test_manifest_url() -> Result<()> {
543        let ref_ = ImageReference::parse("alpine:latest")?;
544        assert_eq!(
545            ref_.manifest_url(),
546            "https://registry-1.docker.io/v2/library/alpine/manifests/latest"
547        );
548        Ok(())
549    }
550
551    #[test]
552    fn test_parse_www_authenticate() -> Result<()> {
553        let header = r#"Bearer realm="https://auth.docker.io/token",service="registry.docker.io",scope="repository:library/alpine:pull""#;
554        let params = parse_www_authenticate(header)?;
555        assert_eq!(&params["realm"], "https://auth.docker.io/token");
556        assert_eq!(&params["service"], "registry.docker.io");
557        assert_eq!(&params["scope"], "repository:library/alpine:pull");
558        Ok(())
559    }
560}