1use 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#[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#[derive(Debug, Clone)]
25pub struct ImageReference {
26 pub host: String,
28 pub repository: String,
30 pub reference: String,
32 pub is_digest: bool,
34}
35
36impl ImageReference {
37 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 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 let before_colon = &image[..idx];
58 if before_colon.contains('/') || !before_colon.contains('.') {
59 let (img, tag) = image.split_at(idx);
61 (img.to_owned(), tag[1..].to_string(), false)
62 } else {
63 (image.to_owned(), "latest".to_owned(), false)
65 }
66 } else {
67 (image.to_owned(), "latest".to_owned(), false)
68 };
69
70 let (host, repository) = if let Some(first_slash) = image_part.find('/') {
72 let potential_host = &image_part[..first_slash];
73
74 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 ("docker.io".to_owned(), image_part)
85 }
86 } else {
87 ("docker.io".to_owned(), format!("library/{image_part}"))
89 };
90
91 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 pub fn manifest_url(&self) -> String {
108 format!(
109 "https://{}/v2/{}/manifests/{}",
110 self.host, self.repository, self.reference
111 )
112 }
113
114 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#[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#[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#[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#[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#[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#[derive(Debug, Clone)]
189pub enum ManifestResult {
190 Manifest(OciManifest),
192 Index(OciIndex),
194}
195
196#[derive(Debug, Clone, Default)]
198pub struct AuthConfig {
199 pub username: Option<String>,
200 pub password: Option<String>,
201 pub token: Option<String>,
202}
203
204pub struct ManifestFetcher {
206 client: Client,
207 tokens: parking_lot::RwLock<HashMap<String, String>>,
209}
210
211impl ManifestFetcher {
212 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 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 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 self.tokens.write().remove(&image_ref.host);
241 }
242 }
243 }
244
245 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 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 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 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 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 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 async fn authenticate(
376 &self,
377 image_ref: &ImageReference,
378 auth: Option<&AuthConfig>,
379 ) -> Result<String> {
380 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 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 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 query.append_pair(
414 "scope",
415 &format!("repository:{}:pull", image_ref.repository),
416 );
417 }
418 }
419
420 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 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#[derive(Debug, Deserialize)]
457struct TokenResponse {
458 token: Option<String>,
459 access_token: Option<String>,
460}
461
462fn 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
472fn parse_www_authenticate(header: &str) -> Result<HashMap<String, String>> {
474 let mut params = HashMap::new();
475
476 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!(¶ms["realm"], "https://auth.docker.io/token");
556 assert_eq!(¶ms["service"], "registry.docker.io");
557 assert_eq!(¶ms["scope"], "repository:library/alpine:pull");
558 Ok(())
559 }
560}