1use 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 fn fetch(&self, uri: &str) -> Result<Vec<u8>, AssetError>;
39
40 fn resolve_id(&self, _id: &str) -> Option<String> {
47 None
48 }
49}
50
51#[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
63pub struct FsAssetResolver {
67 pub root: PathBuf,
68 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 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
112fn 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
151pub struct HttpAssetResolver {
158 agent: ureq::Agent,
159 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
225pub struct AssetServiceResolver {
234 pub scheme: String,
236 pub base_url: String,
238 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 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
312pub 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
358pub struct CachingAssetResolver {
372 inner: Box<dyn AssetResolver>,
373 state: Mutex<CacheState>,
374 max_bytes: Option<usize>,
375}
376
377struct CacheState {
378 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 pub fn with_max_bytes(mut self, n: usize) -> Self {
402 self.max_bytes = Some(n);
403 self
404 }
405
406 pub fn cache_len(&self) -> usize {
408 self.state.lock().map(|s| s.entries.len()).unwrap_or(0)
409 }
410
411 pub fn cache_bytes(&self) -> usize {
413 self.state.lock().map(|s| s.current_bytes).unwrap_or(0)
414 }
415
416 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 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 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 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; }
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 }
481 Ok(bytes)
482 }
483
484 fn resolve_id(&self, id: &str) -> Option<String> {
485 self.inner.resolve_id(id)
486 }
487}
488
489#[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 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 let resolved = r.resolve_id(id).expect("id resolved from a sub-folder");
558 assert!(resolved.ends_with(&format!("{id}.png")), "got {resolved}");
559 assert_eq!(r.fetch(&resolved).unwrap(), b"\x89PNG-bytes");
561 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 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 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 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 Ok(format!("body-of-{uri}").into_bytes())
678 }
679 }
680
681 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 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 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()); assert_eq!(cache.fetch("x").unwrap(), b"ok"); assert_eq!(cache.fetch("x").unwrap(), b"ok"); }
734
735 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 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 cache.fetch("a").unwrap();
760
761 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 let counter = Arc::new(CountingResolver::new());
771 struct Big(Arc<CountingResolver>);
773 impl AssetResolver for Big {
774 fn fetch(&self, uri: &str) -> Result<Vec<u8>, AssetError> {
775 self.0.fetch(uri)?; 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 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 assert_eq!(counter.count(), 2);
799 }
800
801 #[test]
802 fn composite_skips_resolvers_that_dont_support_scheme() {
803 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}