bluebox 0.1.4

A fast DNS interceptor and cache for local networks
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

//! Blocklist format parsers.
//!
//! This module provides parsers for common blocklist formats used by various
//! ad-blocking and privacy tools.
//!
//! # Supported Formats
//!
//! - **Domain List**: Simple format with one domain per line, supports wildcards
//! - **Hosts File**: Standard `/etc/hosts` format used by Steven Black, Dan Pollock, etc.
//! - **`AdBlock`**: Basic `AdBlock` Plus filter syntax (domain extraction only)
//!
//! # Example
//!
//! ```
//! use bluebox::blocklist::{BlocklistParser, DomainListParser};
//! use std::io::BufReader;
//!
//! let content = "# Comment\nexample.com\n*.ads.com";
//! let parser = DomainListParser;
//! let domains = parser.parse(&mut BufReader::new(content.as_bytes())).unwrap();
//! assert_eq!(domains, vec!["example.com", "*.ads.com"]);
//! ```

mod adblock;
mod domains;
mod hosts;
pub mod loader;
pub mod manager;
pub mod remote;

use std::io::BufRead;

pub use adblock::AdBlockParser;
pub use domains::DomainListParser;
pub use hosts::HostsFileParser;

use crate::config::BlocklistFormat;

/// Error type for blocklist parsing operations.
#[derive(Debug, thiserror::Error)]
pub enum ParseError {
    /// I/O error during reading.
    #[error("I/O error")]
    Io(#[from] std::io::Error),

    /// Invalid line encountered during parsing.
    #[error("invalid line {line}: {reason}")]
    InvalidLine {
        /// Line number (1-indexed).
        line: usize,
        /// Reason for the error.
        reason: String,
    },
}

/// Trait for blocklist parsers.
///
/// Each parser implementation handles a specific blocklist format and extracts
/// domain patterns that can be used by the [`Blocker`](crate::dns::Blocker).
pub trait BlocklistParser: Send + Sync {
    /// Parse blocklist content and return domain patterns.
    ///
    /// # Arguments
    ///
    /// * `reader` - A mutable reference to a buffered reader over the blocklist content
    ///
    /// # Returns
    ///
    /// A vector of domain patterns (e.g., `"example.com"`, `"*.ads.com"`).
    ///
    /// # Errors
    ///
    /// Returns a [`ParseError`] if reading fails.
    fn parse(&self, reader: &mut dyn BufRead) -> Result<Vec<String>, ParseError>;
}

/// Returns a boxed parser for the given blocklist format.
///
/// # Example
///
/// ```
/// use bluebox::blocklist::parser_for_format;
/// use bluebox::config::BlocklistFormat;
/// use std::io::BufReader;
///
/// let parser = parser_for_format(BlocklistFormat::Hosts);
/// let content = "0.0.0.0 ads.example.com";
/// let domains = parser.parse(&mut BufReader::new(content.as_bytes())).unwrap();
/// assert_eq!(domains, vec!["ads.example.com"]);
/// ```
#[must_use]
pub fn parser_for_format(format: BlocklistFormat) -> Box<dyn BlocklistParser> {
    match format {
        BlocklistFormat::Domains => Box::new(DomainListParser),
        BlocklistFormat::Hosts => Box::new(HostsFileParser),
        BlocklistFormat::Adblock => Box::new(AdBlockParser),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::io::BufReader;

    #[test]
    fn should_return_domain_parser_when_format_is_domains() {
        let parser = parser_for_format(BlocklistFormat::Domains);
        let content = "example.com\n*.test.com";
        let domains = parser
            .parse(&mut BufReader::new(content.as_bytes()))
            .unwrap();
        assert_eq!(domains, vec!["example.com", "*.test.com"]);
    }

    #[test]
    fn should_return_hosts_parser_when_format_is_hosts() {
        let parser = parser_for_format(BlocklistFormat::Hosts);
        let content = "0.0.0.0 ads.example.com";
        let domains = parser
            .parse(&mut BufReader::new(content.as_bytes()))
            .unwrap();
        assert_eq!(domains, vec!["ads.example.com"]);
    }

    #[test]
    fn should_return_adblock_parser_when_format_is_adblock() {
        let parser = parser_for_format(BlocklistFormat::Adblock);
        let content = "||ads.example.com^";
        let domains = parser
            .parse(&mut BufReader::new(content.as_bytes()))
            .unwrap();
        assert_eq!(domains, vec!["ads.example.com"]);
    }
}