Skip to main content

markdoc_pdf/
assets.rs

1//! Pluggable asset fetching for media references.
2//!
3//! `markdoc-pdf` doesn't speak to any asset service directly; it goes through
4//! this trait so that any fetch backend (filesystem, HTTP, an asset-service
5//! client, pre-bundled in-memory cache) can be plugged in. Default deployments
6//! use [`FsAssetResolver`] for local-path references; [`AssetServiceResolver`]
7//! fetches `{scheme}://{asset_id}` references from an asset service over HTTP.
8//!
9//! The renderer treats fetch failures as soft errors — the image is
10//! replaced by a placeholder rather than aborting the PDF generation.
11
12use std::collections::HashMap;
13use std::io::Read;
14use std::path::{Path, PathBuf};
15use std::sync::{Arc, Mutex, OnceLock};
16use thiserror::Error;
17
18#[derive(Debug, Error)]
19pub enum AssetError {
20    #[error("asset not found: {0}")]
21    NotFound(String),
22    #[error("asset fetch failed for {uri}: {source}")]
23    Io {
24        uri: String,
25        #[source]
26        source: std::io::Error,
27    },
28    #[error("scheme {scheme} not supported by this resolver")]
29    UnsupportedScheme { scheme: String },
30    #[error("{0}")]
31    Other(String),
32}
33
34pub trait AssetResolver: Send + Sync {
35    /// Fetch the bytes referenced by `uri`. The URI can be a relative or
36    /// absolute path, an `http://` / `https://` URL, an asset-service
37    /// reference, or anything else a caller-supplied resolver knows how to handle.
38    fn fetch(&self, uri: &str) -> Result<Vec<u8>, AssetError>;
39
40    /// Resolve a bare asset `id` (no path, no extension — e.g. an asset
41    /// service's UUID) to a URI that [`fetch`](Self::fetch) can load. A filesystem
42    /// resolver searches its root recursively for a file whose stem matches;
43    /// resolvers that can't map an id return `None` (the default). Used as a
44    /// fallback for `{% media id="…" /%}` when the id isn't a file sitting
45    /// directly in the asset root.
46    fn resolve_id(&self, _id: &str) -> Option<String> {
47        None
48    }
49}
50
51/// Resolver that returns `NotFound` for every URI. The default when the
52/// caller hasn't wired anything else; lets media-bearing documents render
53/// as placeholders without configuration.
54#[derive(Debug, Default)]
55pub struct NullAssetResolver;
56
57impl AssetResolver for NullAssetResolver {
58    fn fetch(&self, uri: &str) -> Result<Vec<u8>, AssetError> {
59        Err(AssetError::NotFound(uri.to_string()))
60    }
61}
62
63/// Resolver that loads files from a filesystem root. URIs are joined to
64/// `root` as relative paths; absolute paths and `file://` URIs are also
65/// honored. Other schemes (`http`, `https`, …) error.
66pub struct FsAssetResolver {
67    pub root: PathBuf,
68    /// Lazily-built index of `<stem>` → path (relative to `root`) for every
69    /// image file anywhere under `root`, so `{% media id="…" /%}` resolves
70    /// even when the asset sits in a sub-folder. Built on first `resolve_id`.
71    id_index: OnceLock<HashMap<String, PathBuf>>,
72}
73
74impl FsAssetResolver {
75    pub fn new(root: impl Into<PathBuf>) -> Self {
76        Self {
77            root: root.into(),
78            id_index: OnceLock::new(),
79        }
80    }
81}
82
83impl AssetResolver for FsAssetResolver {
84    fn fetch(&self, uri: &str) -> Result<Vec<u8>, AssetError> {
85        let path = if let Some(rest) = uri.strip_prefix("file://") {
86            PathBuf::from(rest)
87        } else if uri.contains("://") {
88            // Reject other schemes explicitly so the caller knows to
89            // wrap us in a composite resolver.
90            let scheme = uri.split("://").next().unwrap_or("?").to_string();
91            return Err(AssetError::UnsupportedScheme { scheme });
92        } else {
93            let p = PathBuf::from(uri);
94            if p.is_absolute() {
95                p
96            } else {
97                self.root.join(p)
98            }
99        };
100        std::fs::read(&path).map_err(|e| AssetError::Io {
101            uri: uri.to_string(),
102            source: e,
103        })
104    }
105
106    fn resolve_id(&self, id: &str) -> Option<String> {
107        let index = self.id_index.get_or_init(|| build_id_index(&self.root));
108        index.get(id).map(|rel| rel.to_string_lossy().into_owned())
109    }
110}
111
112/// Walk `root` recursively and index image files by their stem (the file
113/// name without extension), keyed to the path relative to `root` — so the
114/// result feeds straight back into [`FsAssetResolver::fetch`]. First match
115/// wins on a stem collision (rare for UUID-named assets). Symlinked
116/// directories are not followed, so the walk cannot loop.
117fn build_id_index(root: &Path) -> HashMap<String, PathBuf> {
118    const IMAGE_EXTS: &[&str] = &["webp", "png", "jpg", "jpeg", "gif", "svg"];
119    let mut map: HashMap<String, PathBuf> = HashMap::new();
120    let mut stack: Vec<PathBuf> = vec![root.to_path_buf()];
121    while let Some(dir) = stack.pop() {
122        let Ok(entries) = std::fs::read_dir(&dir) else {
123            continue;
124        };
125        for entry in entries.flatten() {
126            let Ok(ft) = entry.file_type() else {
127                continue;
128            };
129            let path = entry.path();
130            if ft.is_dir() {
131                stack.push(path);
132            } else if ft.is_file() {
133                let is_image = path
134                    .extension()
135                    .and_then(|e| e.to_str())
136                    .map(|e| IMAGE_EXTS.contains(&e.to_ascii_lowercase().as_str()))
137                    .unwrap_or(false);
138                if is_image
139                    && let Some(stem) = path.file_stem().and_then(|s| s.to_str())
140                    && let Ok(rel) = path.strip_prefix(root)
141                {
142                    map.entry(stem.to_string())
143                        .or_insert_with(|| rel.to_path_buf());
144                }
145            }
146        }
147    }
148    map
149}
150
151/// HTTP/HTTPS asset resolver. Performs a synchronous GET and returns
152/// the response body. Other schemes return `UnsupportedScheme` so this
153/// can sit in a `CompositeAssetResolver` alongside FS / asset-service resolvers.
154///
155/// Defaults: 10-second timeout, 64 MiB max body, no per-request retry.
156/// Use [`HttpAssetResolver::with_agent`] to customise.
157pub struct HttpAssetResolver {
158    agent: ureq::Agent,
159    /// Cap on response body size to avoid loading hostile servers'
160    /// runaway responses.
161    pub max_body_bytes: usize,
162}
163
164impl HttpAssetResolver {
165    pub fn new() -> Self {
166        let agent: ureq::Agent = ureq::Agent::config_builder()
167            .timeout_global(Some(std::time::Duration::from_secs(10)))
168            .build()
169            .into();
170        Self {
171            agent,
172            max_body_bytes: 64 * 1024 * 1024,
173        }
174    }
175
176    pub fn with_agent(agent: ureq::Agent) -> Self {
177        Self {
178            agent,
179            max_body_bytes: 64 * 1024 * 1024,
180        }
181    }
182
183    pub fn with_max_body_bytes(mut self, n: usize) -> Self {
184        self.max_body_bytes = n;
185        self
186    }
187}
188
189impl Default for HttpAssetResolver {
190    fn default() -> Self {
191        Self::new()
192    }
193}
194
195impl AssetResolver for HttpAssetResolver {
196    fn fetch(&self, uri: &str) -> Result<Vec<u8>, AssetError> {
197        if !(uri.starts_with("http://") || uri.starts_with("https://")) {
198            let scheme = uri.split("://").next().unwrap_or("?").to_string();
199            return Err(AssetError::UnsupportedScheme { scheme });
200        }
201        let mut resp = self
202            .agent
203            .get(uri)
204            .call()
205            .map_err(|e| AssetError::Other(format!("HTTP fetch {uri}: {e}")))?;
206        let mut buf: Vec<u8> = Vec::new();
207        let mut reader = resp
208            .body_mut()
209            .as_reader()
210            .take(self.max_body_bytes as u64 + 1);
211        std::io::copy(&mut reader, &mut buf).map_err(|e| AssetError::Io {
212            uri: uri.to_string(),
213            source: e,
214        })?;
215        if buf.len() > self.max_body_bytes {
216            return Err(AssetError::Other(format!(
217                "Response body exceeds max_body_bytes ({})",
218                self.max_body_bytes
219            )));
220        }
221        Ok(buf)
222    }
223}
224
225/// Resolver for an asset service's own URI scheme, named by the caller:
226///   - `{scheme}://{asset_id}`              → `GET {base}/download/{asset_id}`
227///   - `{scheme}://{asset_id}/{derivative}` → `GET {base}/download/{asset_id}/{derivative}`
228///
229/// Authenticates by sending `X-Subject-Id` (a subject identifier as injected
230/// by an identity proxy such as Ory Oathkeeper). The id is the caller's
231/// choice — typically the PDF generator's service account or the
232/// requesting user.
233pub struct AssetServiceResolver {
234    /// URI scheme this resolver answers, without `://`. Example: `asset`.
235    pub scheme: String,
236    /// Base URL, no trailing slash. Example: `http://assets:3002`.
237    pub base_url: String,
238    /// Sent as `X-Subject-Id`. Required for non-public assets.
239    pub subject_id: Option<String>,
240    agent: ureq::Agent,
241    pub max_body_bytes: usize,
242}
243
244impl AssetServiceResolver {
245    pub fn new(
246        scheme: impl Into<String>,
247        base_url: impl Into<String>,
248        subject_id: Option<String>,
249    ) -> Self {
250        Self {
251            scheme: scheme.into(),
252            base_url: base_url.into().trim_end_matches('/').to_string(),
253            subject_id,
254            agent: ureq::Agent::config_builder()
255                .timeout_global(Some(std::time::Duration::from_secs(10)))
256                .build()
257                .into(),
258            max_body_bytes: 64 * 1024 * 1024,
259        }
260    }
261
262    fn build_url(&self, uri: &str) -> Option<String> {
263        let rest = uri
264            .strip_prefix(self.scheme.as_str())
265            .and_then(|r| r.strip_prefix("://"))?;
266        if rest.is_empty() {
267            return None;
268        }
269        // Pass through path verbatim — single id (`abc`) or id/derivative
270        // (`abc/web-large`). Strip any query string; the download contract
271        // doesn't use query params, derivatives are URL-path-encoded.
272        let path = rest.split('?').next().unwrap_or(rest);
273        Some(format!("{}/download/{}", self.base_url, path))
274    }
275}
276
277impl AssetResolver for AssetServiceResolver {
278    fn fetch(&self, uri: &str) -> Result<Vec<u8>, AssetError> {
279        if uri.split_once("://").map(|(scheme, _)| scheme) != Some(self.scheme.as_str()) {
280            let scheme = uri.split("://").next().unwrap_or("?").to_string();
281            return Err(AssetError::UnsupportedScheme { scheme });
282        }
283        let url = self
284            .build_url(uri)
285            .ok_or_else(|| AssetError::NotFound(uri.to_string()))?;
286        let mut req = self.agent.get(&url);
287        if let Some(sid) = &self.subject_id {
288            req = req.header("X-Subject-Id", sid);
289        }
290        let mut resp = req
291            .call()
292            .map_err(|e| AssetError::Other(format!("{} fetch {url}: {e}", self.scheme)))?;
293        let mut buf: Vec<u8> = Vec::new();
294        let mut reader = resp
295            .body_mut()
296            .as_reader()
297            .take(self.max_body_bytes as u64 + 1);
298        std::io::copy(&mut reader, &mut buf).map_err(|e| AssetError::Io {
299            uri: uri.to_string(),
300            source: e,
301        })?;
302        if buf.len() > self.max_body_bytes {
303            return Err(AssetError::Other(format!(
304                "{} response exceeds max_body_bytes ({})",
305                self.scheme, self.max_body_bytes
306            )));
307        }
308        Ok(buf)
309    }
310}
311
312/// Composes multiple resolvers; the first one whose `fetch` doesn't
313/// return `UnsupportedScheme` wins.
314pub struct CompositeAssetResolver {
315    resolvers: Vec<Box<dyn AssetResolver>>,
316}
317
318impl CompositeAssetResolver {
319    pub fn new() -> Self {
320        Self {
321            resolvers: Vec::new(),
322        }
323    }
324
325    pub fn push(mut self, resolver: Box<dyn AssetResolver>) -> Self {
326        self.resolvers.push(resolver);
327        self
328    }
329}
330
331impl Default for CompositeAssetResolver {
332    fn default() -> Self {
333        Self::new()
334    }
335}
336
337impl AssetResolver for CompositeAssetResolver {
338    fn fetch(&self, uri: &str) -> Result<Vec<u8>, AssetError> {
339        let mut last_err: Option<AssetError> = None;
340        for r in &self.resolvers {
341            match r.fetch(uri) {
342                Ok(b) => return Ok(b),
343                Err(e @ AssetError::UnsupportedScheme { .. }) => {
344                    last_err = Some(e);
345                    continue;
346                }
347                Err(e) => return Err(e),
348            }
349        }
350        Err(last_err.unwrap_or_else(|| AssetError::NotFound(uri.to_string())))
351    }
352
353    fn resolve_id(&self, id: &str) -> Option<String> {
354        self.resolvers.iter().find_map(|r| r.resolve_id(id))
355    }
356}
357
358/// Caches successful fetches by URI so repeated references to the same
359/// asset hit the inner resolver only once.
360///
361/// **Optional byte cap**: when set via [`Self::with_max_bytes`], the
362/// cache evicts least-recently-used entries to keep total cached body
363/// size under the cap. A single entry larger than the cap is fetched
364/// but not cached. Without a cap, the cache grows unbounded — fine for
365/// short-lived single-doc renders, dangerous for long-running services.
366///
367/// **Errors are not cached** — transient failures retry on the next
368/// call, and `AssetError::Io` isn't `Clone`-able anyway.
369///
370/// Thread-safe (`Send + Sync`); the cache is behind a `Mutex`.
371pub struct CachingAssetResolver {
372    inner: Box<dyn AssetResolver>,
373    state: Mutex<CacheState>,
374    max_bytes: Option<usize>,
375}
376
377struct CacheState {
378    /// `(bytes, last_access_seq)`.
379    entries: HashMap<String, (Arc<Vec<u8>>, u64)>,
380    seq: u64,
381    current_bytes: usize,
382}
383
384impl CachingAssetResolver {
385    pub fn new(inner: Box<dyn AssetResolver>) -> Self {
386        Self {
387            inner,
388            state: Mutex::new(CacheState {
389                entries: HashMap::new(),
390                seq: 0,
391                current_bytes: 0,
392            }),
393            max_bytes: None,
394        }
395    }
396
397    /// Limit total cached body size (in bytes). When inserting would
398    /// exceed this, the least-recently-used entries are evicted until
399    /// the new entry fits. Single entries larger than the cap are not
400    /// cached but still served from the inner resolver.
401    pub fn with_max_bytes(mut self, n: usize) -> Self {
402        self.max_bytes = Some(n);
403        self
404    }
405
406    /// Number of entries currently cached. Useful for instrumentation.
407    pub fn cache_len(&self) -> usize {
408        self.state.lock().map(|s| s.entries.len()).unwrap_or(0)
409    }
410
411    /// Total bytes currently held in the cache.
412    pub fn cache_bytes(&self) -> usize {
413        self.state.lock().map(|s| s.current_bytes).unwrap_or(0)
414    }
415
416    /// Drop all cached entries.
417    pub fn clear(&self) {
418        if let Ok(mut s) = self.state.lock() {
419            s.entries.clear();
420            s.current_bytes = 0;
421        }
422    }
423}
424
425impl CacheState {
426    fn next_seq(&mut self) -> u64 {
427        self.seq = self.seq.wrapping_add(1);
428        self.seq
429    }
430
431    /// Drop the LRU entry. Returns true if something was evicted.
432    fn evict_one(&mut self) -> bool {
433        let lru_key = self
434            .entries
435            .iter()
436            .min_by_key(|(_, (_, ts))| *ts)
437            .map(|(k, _)| k.clone());
438        if let Some(key) = lru_key
439            && let Some((bytes, _)) = self.entries.remove(&key)
440        {
441            self.current_bytes = self.current_bytes.saturating_sub(bytes.len());
442            return true;
443        }
444        false
445    }
446}
447
448impl AssetResolver for CachingAssetResolver {
449    fn fetch(&self, uri: &str) -> Result<Vec<u8>, AssetError> {
450        // Hot path: cache hit. Bump last-access while holding the lock.
451        if let Ok(mut state) = self.state.lock()
452            && let Some((bytes, _)) = state.entries.get(uri)
453        {
454            let copy = Vec::from(bytes.as_slice());
455            let seq = state.next_seq();
456            if let Some((_, ts)) = state.entries.get_mut(uri) {
457                *ts = seq;
458            }
459            return Ok(copy);
460        }
461        // Miss: delegate, then store on success (subject to cap).
462        let bytes = self.inner.fetch(uri)?;
463        if let Ok(mut state) = self.state.lock() {
464            let len = bytes.len();
465            let fits_alone = self.max_bytes.is_none_or(|cap| len <= cap);
466            if fits_alone {
467                if let Some(cap) = self.max_bytes {
468                    while state.current_bytes + len > cap {
469                        if !state.evict_one() {
470                            break; // empty cache; continue without cap
471                        }
472                    }
473                }
474                let arc = Arc::new(bytes.clone());
475                let seq = state.next_seq();
476                state.current_bytes += len;
477                state.entries.insert(uri.to_string(), (arc, seq));
478            }
479            // else: response too big to cache; skip.
480        }
481        Ok(bytes)
482    }
483
484    fn resolve_id(&self, id: &str) -> Option<String> {
485        self.inner.resolve_id(id)
486    }
487}
488
489/// Sniff a binary blob's media format from magic bytes.
490#[derive(Debug, Clone, Copy, PartialEq, Eq)]
491pub enum MediaFormat {
492    Png,
493    Jpeg,
494    Gif,
495    Webp,
496    Svg,
497    Unknown,
498}
499
500pub fn sniff_format(data: &[u8]) -> MediaFormat {
501    if data.starts_with(&[0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a]) {
502        return MediaFormat::Png;
503    }
504    if data.starts_with(&[0xff, 0xd8, 0xff]) {
505        return MediaFormat::Jpeg;
506    }
507    if data.starts_with(b"GIF87a") || data.starts_with(b"GIF89a") {
508        return MediaFormat::Gif;
509    }
510    if data.len() >= 12 && &data[0..4] == b"RIFF" && &data[8..12] == b"WEBP" {
511        return MediaFormat::Webp;
512    }
513    // SVG sniff: look for `<svg` near the start, allowing for XML decl
514    // or BOM. Cap at first 512 bytes to keep this cheap.
515    let head = &data[..data.len().min(512)];
516    if let Ok(text) = std::str::from_utf8(head)
517        && text.contains("<svg")
518    {
519        return MediaFormat::Svg;
520    }
521    MediaFormat::Unknown
522}
523
524#[cfg(test)]
525mod tests {
526    use super::*;
527
528    #[test]
529    fn null_resolver_always_errors() {
530        let r = NullAssetResolver;
531        assert!(matches!(
532            r.fetch("anything").unwrap_err(),
533            AssetError::NotFound(_)
534        ));
535    }
536
537    #[test]
538    fn fs_resolver_rejects_unsupported_scheme() {
539        let r = FsAssetResolver::new("/tmp");
540        let err = r.fetch("https://example.com/x.png").unwrap_err();
541        assert!(matches!(err, AssetError::UnsupportedScheme { .. }));
542    }
543
544    #[test]
545    fn fs_resolver_resolves_id_in_subdirectory() {
546        use std::fs;
547        let base = std::env::temp_dir().join("mdpdf-id-resolve-test");
548        let _ = fs::remove_dir_all(&base);
549        let nested = base.join("a/b");
550        fs::create_dir_all(&nested).unwrap();
551        let id = "0a02bb82-1a68-4c5c-883f-406361e1235e";
552        fs::write(nested.join(format!("{id}.png")), b"\x89PNG-bytes").unwrap();
553
554        let r = FsAssetResolver::new(&base);
555        // The id resolves to a path (relative to the root) even though the
556        // file is two levels down...
557        let resolved = r.resolve_id(id).expect("id resolved from a sub-folder");
558        assert!(resolved.ends_with(&format!("{id}.png")), "got {resolved}");
559        // ...and that path fetches back through the same resolver.
560        assert_eq!(r.fetch(&resolved).unwrap(), b"\x89PNG-bytes");
561        // An unknown id yields None.
562        assert!(r.resolve_id("no-such-id").is_none());
563
564        let _ = fs::remove_dir_all(&base);
565    }
566
567    #[test]
568    fn sniff_png() {
569        assert_eq!(
570            sniff_format(&[0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a, 0]),
571            MediaFormat::Png
572        );
573    }
574
575    #[test]
576    fn sniff_jpeg() {
577        assert_eq!(sniff_format(&[0xff, 0xd8, 0xff, 0xe0]), MediaFormat::Jpeg);
578    }
579
580    #[test]
581    fn sniff_svg() {
582        assert_eq!(
583            sniff_format(b"<?xml version=\"1.0\"?><svg xmlns=\"...\"/>"),
584            MediaFormat::Svg
585        );
586        assert_eq!(sniff_format(b"<svg/>"), MediaFormat::Svg);
587    }
588
589    #[test]
590    fn sniff_unknown() {
591        assert_eq!(sniff_format(b"random bytes"), MediaFormat::Unknown);
592    }
593
594    #[test]
595    fn http_resolver_rejects_non_http_scheme() {
596        let r = HttpAssetResolver::new();
597        let err = r.fetch("asset://abc").unwrap_err();
598        assert!(matches!(err, AssetError::UnsupportedScheme { .. }));
599        let err = r.fetch("file:///x").unwrap_err();
600        assert!(matches!(err, AssetError::UnsupportedScheme { .. }));
601    }
602
603    #[test]
604    fn asset_service_resolver_builds_download_url_for_bare_id() {
605        let r = AssetServiceResolver::new("asset", "http://assets:3002", None);
606        assert_eq!(
607            r.build_url("asset://abc-123").unwrap(),
608            "http://assets:3002/download/abc-123"
609        );
610    }
611
612    #[test]
613    fn asset_service_resolver_builds_url_for_derivative() {
614        let r = AssetServiceResolver::new("asset", "http://assets:3002/", None);
615        assert_eq!(
616            r.build_url("asset://abc-123/web-large").unwrap(),
617            "http://assets:3002/download/abc-123/web-large"
618        );
619    }
620
621    #[test]
622    fn asset_service_resolver_strips_trailing_slash_on_base() {
623        let r = AssetServiceResolver::new("asset", "http://assets:3002/", None);
624        assert_eq!(
625            r.build_url("asset://x").unwrap(),
626            "http://assets:3002/download/x"
627        );
628    }
629
630    #[test]
631    fn asset_service_resolver_drops_query_params() {
632        // The download contract uses path segments (derivative names), not
633        // query strings — strip any `?...` suffix the markdoc author
634        // may have added by mistake.
635        let r = AssetServiceResolver::new("asset", "http://assets:3002", None);
636        assert_eq!(
637            r.build_url("asset://abc?w=400").unwrap(),
638            "http://assets:3002/download/abc"
639        );
640    }
641
642    #[test]
643    fn asset_service_resolver_rejects_other_schemes() {
644        let r = AssetServiceResolver::new("asset", "http://assets:3002", None);
645        let err = r.fetch("https://example.com/x.png").unwrap_err();
646        assert!(matches!(err, AssetError::UnsupportedScheme { .. }));
647        // A scheme that merely starts with the resolver's is not its own.
648        let err = r.fetch("assets://abc").unwrap_err();
649        assert!(matches!(err, AssetError::UnsupportedScheme { .. }));
650        assert_eq!(r.build_url("assets://abc"), None);
651        let err = r.fetch("abc").unwrap_err();
652        assert!(matches!(err, AssetError::UnsupportedScheme { .. }));
653    }
654
655    /// Counts every fetch — used by the caching tests to verify the
656    /// inner resolver only sees one call per unique URI.
657    struct CountingResolver {
658        calls: Mutex<Vec<String>>,
659    }
660
661    impl CountingResolver {
662        fn new() -> Self {
663            Self {
664                calls: Mutex::new(Vec::new()),
665            }
666        }
667        fn count(&self) -> usize {
668            self.calls.lock().unwrap().len()
669        }
670    }
671
672    impl AssetResolver for CountingResolver {
673        fn fetch(&self, uri: &str) -> Result<Vec<u8>, AssetError> {
674            self.calls.lock().unwrap().push(uri.to_string());
675            // Distinct payload per URI so we can verify cache returns
676            // the right one.
677            Ok(format!("body-of-{uri}").into_bytes())
678        }
679    }
680
681    /// Newtype that delegates to a shared inner so the test can keep a
682    /// reference to the inner counter.
683    struct DelegateResolver(Arc<CountingResolver>);
684    impl AssetResolver for DelegateResolver {
685        fn fetch(&self, uri: &str) -> Result<Vec<u8>, AssetError> {
686            self.0.fetch(uri)
687        }
688    }
689
690    #[test]
691    fn caching_resolver_serves_repeated_uris_from_cache() {
692        let counter = Arc::new(CountingResolver::new());
693        let cache = CachingAssetResolver::new(Box::new(DelegateResolver(counter.clone())));
694
695        let a1 = cache.fetch("asset://abc").unwrap();
696        let a2 = cache.fetch("asset://abc").unwrap();
697        let b = cache.fetch("asset://other").unwrap();
698        let a3 = cache.fetch("asset://abc").unwrap();
699
700        assert_eq!(a1, b"body-of-asset://abc");
701        assert_eq!(a2, a1);
702        assert_eq!(a3, a1);
703        assert_eq!(b, b"body-of-asset://other");
704
705        // Inner saw exactly two unique URIs, regardless of repeats.
706        assert_eq!(counter.count(), 2);
707        assert_eq!(cache.cache_len(), 2);
708    }
709
710    #[test]
711    fn caching_resolver_does_not_cache_errors() {
712        // Inner that errors then succeeds on second call for the same URI.
713        struct FlakyResolver {
714            calls: Mutex<usize>,
715        }
716        impl AssetResolver for FlakyResolver {
717            fn fetch(&self, _uri: &str) -> Result<Vec<u8>, AssetError> {
718                let mut c = self.calls.lock().unwrap();
719                *c += 1;
720                if *c == 1 {
721                    Err(AssetError::Other("first call fails".into()))
722                } else {
723                    Ok(b"ok".to_vec())
724                }
725            }
726        }
727        let cache = CachingAssetResolver::new(Box::new(FlakyResolver {
728            calls: Mutex::new(0),
729        }));
730        assert!(cache.fetch("x").is_err()); // first fails
731        assert_eq!(cache.fetch("x").unwrap(), b"ok"); // retries → succeeds
732        assert_eq!(cache.fetch("x").unwrap(), b"ok"); // now cached
733    }
734
735    /// Resolver returning a fixed-size payload per URI so we can
736    /// reason about the cache's byte accounting precisely.
737    struct FixedSizeResolver {
738        payload_bytes: usize,
739    }
740    impl AssetResolver for FixedSizeResolver {
741        fn fetch(&self, _uri: &str) -> Result<Vec<u8>, AssetError> {
742            Ok(vec![0u8; self.payload_bytes])
743        }
744    }
745
746    #[test]
747    fn caching_resolver_evicts_when_over_max_bytes() {
748        // Cap = 100 bytes; each fetch returns 40 bytes. Caching three
749        // distinct URIs (3 × 40 = 120 > 100) should evict the LRU.
750        let inner = FixedSizeResolver { payload_bytes: 40 };
751        let cache = CachingAssetResolver::new(Box::new(inner)).with_max_bytes(100);
752
753        cache.fetch("a").unwrap();
754        cache.fetch("b").unwrap();
755        assert_eq!(cache.cache_len(), 2);
756        assert_eq!(cache.cache_bytes(), 80);
757
758        // Touch "a" so it's most-recent; "b" becomes LRU.
759        cache.fetch("a").unwrap();
760
761        // Insert "c" → must evict "b" (LRU) to fit.
762        cache.fetch("c").unwrap();
763        assert_eq!(cache.cache_len(), 2);
764        assert_eq!(cache.cache_bytes(), 80);
765    }
766
767    #[test]
768    fn caching_resolver_skips_caching_oversized_entries() {
769        // Cap = 50 bytes; payload = 100 bytes per fetch — too big to cache.
770        let counter = Arc::new(CountingResolver::new());
771        // Wrap in a small resolver that returns bigger bodies.
772        struct Big(Arc<CountingResolver>);
773        impl AssetResolver for Big {
774            fn fetch(&self, uri: &str) -> Result<Vec<u8>, AssetError> {
775                self.0.fetch(uri)?; // bump counter
776                Ok(vec![0u8; 100])
777            }
778        }
779        let cache = CachingAssetResolver::new(Box::new(Big(counter.clone()))).with_max_bytes(50);
780
781        cache.fetch("x").unwrap();
782        cache.fetch("x").unwrap();
783        // Both fetches went to the inner — the body was too big to cache.
784        assert_eq!(counter.count(), 2);
785        assert_eq!(cache.cache_len(), 0);
786    }
787
788    #[test]
789    fn caching_resolver_clear_drops_entries() {
790        let counter = Arc::new(CountingResolver::new());
791        let cache = CachingAssetResolver::new(Box::new(DelegateResolver(counter.clone())));
792        cache.fetch("x").unwrap();
793        assert_eq!(cache.cache_len(), 1);
794        cache.clear();
795        assert_eq!(cache.cache_len(), 0);
796        cache.fetch("x").unwrap();
797        // Inner saw two calls because we cleared between.
798        assert_eq!(counter.count(), 2);
799    }
800
801    #[test]
802    fn composite_skips_resolvers_that_dont_support_scheme() {
803        // FS handles only fs paths (and `file://`); Composite should
804        // try it, see UnsupportedScheme for `asset://`, then move on.
805        // With nothing else able to handle it, the final error is the
806        // last UnsupportedScheme observed.
807        let r = CompositeAssetResolver::new().push(Box::new(FsAssetResolver::new("/tmp")));
808        let err = r.fetch("asset://x").unwrap_err();
809        assert!(matches!(err, AssetError::UnsupportedScheme { .. }));
810    }
811}