Skip to main content

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}