shaul_core/parser.rs
1use std::sync::Arc;
2
3use async_trait::async_trait;
4
5use crate::checksum::Checksum;
6use crate::error::{Error, Result};
7use crate::header::RequestOptions;
8use crate::link::Link;
9use crate::resource::Resource;
10
11/// Inputs a parser may use while turning a [`Link`] into a [`Resource`].
12#[derive(Clone, Debug, Default)]
13pub struct ParseOptions {
14 /// Request headers and authentication to use for metadata requests and to
15 /// carry into the produced files.
16 pub request: RequestOptions,
17 /// User-supplied checksum, applied to a single-file resource.
18 pub checksum: Option<Checksum>,
19 /// Provider revision (branch, tag or commit) requested by the user.
20 pub revision: Option<String>,
21 /// Glob patterns selecting files from a multi-file resource.
22 pub include: Vec<String>,
23 /// Glob patterns excluding files from a multi-file resource.
24 pub exclude: Vec<String>,
25}
26
27/// Turns a raw `Link` into a `Resource`. Parsers may perform network I/O to
28/// discover file lists (Hub) but must not transfer file contents.
29#[async_trait]
30pub trait LinkParser: Send + Sync {
31 /// Short, stable identifier such as `http` or `huggingface`, used in
32 /// diagnostics and reported by [`Router`](crate::router::Router).
33 fn name(&self) -> &'static str;
34 /// Returns `true` when this parser claims `link`. The check must be cheap
35 /// and free of side effects, because registration order decides which
36 /// parser is asked first.
37 fn supports(&self, link: &Link) -> bool;
38 /// Builds the protocol-agnostic resource for a claimed link.
39 async fn parse(&self, link: &Link, options: &ParseOptions) -> Result<Resource>;
40}
41
42/// Ordered collection of [`LinkParser`]s. Lookups always follow registration
43/// order.
44#[derive(Clone, Default)]
45pub struct ParserRegistry {
46 parsers: Vec<Arc<dyn LinkParser>>,
47}
48
49impl ParserRegistry {
50 /// Creates an empty registry.
51 pub fn new() -> Self {
52 Self::default()
53 }
54
55 /// Appends a parser; later registrations are consulted after earlier ones.
56 pub fn register(&mut self, parser: Arc<dyn LinkParser>) {
57 self.parsers.push(parser);
58 }
59
60 /// Builder-style variant of [`ParserRegistry::register`].
61 pub fn with(mut self, parser: Arc<dyn LinkParser>) -> Self {
62 self.register(parser);
63 self
64 }
65
66 /// Iterates over registered parsers in registration order.
67 pub fn iter(&self) -> impl Iterator<Item = &Arc<dyn LinkParser>> {
68 self.parsers.iter()
69 }
70
71 /// Returns `true` when no parser has been registered.
72 pub fn is_empty(&self) -> bool {
73 self.parsers.is_empty()
74 }
75
76 /// Try parsers in registration order. A parser that claims a link but
77 /// fails does not prevent a later parser from being tried.
78 pub async fn parse(&self, link: &Link, options: &ParseOptions) -> Result<Resource> {
79 let mut last_error = None;
80 let mut claimed = false;
81 for parser in &self.parsers {
82 if !parser.supports(link) {
83 continue;
84 }
85 claimed = true;
86 match parser.parse(link, options).await {
87 Ok(resource) => return Ok(resource),
88 Err(error) => last_error = Some(error),
89 }
90 }
91 Err(last_error.unwrap_or_else(|| {
92 if claimed {
93 Error::InvalidLink(link.to_string())
94 } else {
95 Error::NoParser(link.to_string())
96 }
97 }))
98 }
99}