feedparser_rs/

limits.rs

//! Parser limits to prevent `DoS` attacks and excessive memory usage

/// Parser limits for protecting against denial-of-service attacks
///
/// These limits prevent malicious or malformed feeds from causing excessive
/// memory allocation, deep recursion, or other resource exhaustion issues.
///
/// # Examples
///
/// ```
/// use feedparser_rs::ParserLimits;
///
/// let limits = ParserLimits::default();
/// assert_eq!(limits.max_entries, 10_000);
///
/// // Custom limits for restricted environments
/// let strict = ParserLimits {
///     max_entries: 1_000,
///     max_feed_size_bytes: 10 * 1024 * 1024, // 10MB
///     ..Default::default()
/// };
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ParserLimits {
    /// Maximum number of entries/items in a feed
    ///
    /// Prevents memory exhaustion from feeds with millions of items.
    /// Typical feeds have 10-100 entries, large feeds may have up to 1000.
    ///
    /// Default: 10,000 entries
    pub max_entries: usize,

    /// Maximum number of links per feed (channel-level)
    ///
    /// Prevents link bombing attacks.
    ///
    /// Default: 100 links
    pub max_links_per_feed: usize,

    /// Maximum number of links per entry
    ///
    /// Prevents link bombing in individual entries.
    ///
    /// Default: 50 links
    pub max_links_per_entry: usize,

    /// Maximum number of authors per feed or entry
    ///
    /// Default: 20 authors
    pub max_authors: usize,

    /// Maximum number of contributors per feed or entry
    ///
    /// Default: 20 contributors
    pub max_contributors: usize,

    /// Maximum number of tags/categories per feed or entry
    ///
    /// Default: 100 tags
    pub max_tags: usize,

    /// Maximum number of content blocks per entry
    ///
    /// Atom feeds can have multiple content elements.
    ///
    /// Default: 10 content blocks
    pub max_content_blocks: usize,

    /// Maximum number of enclosures per entry
    ///
    /// Podcast feeds typically have 1 enclosure per episode.
    ///
    /// Default: 20 enclosures
    pub max_enclosures: usize,

    /// Maximum number of XML namespaces
    ///
    /// Prevents namespace pollution attacks.
    ///
    /// Default: 100 namespaces
    pub max_namespaces: usize,

    /// Maximum XML nesting depth
    ///
    /// Prevents stack overflow from deeply nested XML.
    ///
    /// Default: 100 levels
    pub max_nesting_depth: usize,

    /// Maximum HTML tag nesting depth accepted by HTML sanitization
    ///
    /// `sanitize_html`'s underlying HTML5 tree builder exhibits quadratic-time
    /// behavior on pathologically deep tag nesting within a single text field
    /// (verified: multi-second slowdown from a single deeply nested `<div>`
    /// chain). Content nested deeper than this is escaped as plain text
    /// (`&lt;`/`&gt;`) instead of being run through the sanitizer, bounding
    /// worst-case CPU cost to linear regardless of input shape.
    ///
    /// This is a safety bound, not a compatibility ceiling to be tuned up to
    /// match "typical" content: exceeding it degrades gracefully (the field's
    /// HTML formatting is lost, but its text content is fully preserved and
    /// still safely escaped) rather than dropping data or erroring, so it is
    /// safe to keep conservative. Legitimate feed content — even unusually
    /// deep block-quoted reply chains or nested tables — rarely exceeds a few
    /// dozen levels; 100 (50 under [`ParserLimits::strict`]) leaves headroom
    /// above that without leaving much headroom for abuse.
    ///
    /// Default: 100 levels
    pub max_html_nesting_depth: usize,

    /// Maximum text field length in bytes
    ///
    /// Prevents excessive memory from huge title/description fields. Also bounds
    /// the per-value serialized size of a captured JSON Feed extension object
    /// (see `max_json_extensions`); an oversized extension value is dropped
    /// entirely rather than truncated.
    ///
    /// Default: 10 MB
    pub max_text_length: usize,

    /// Maximum total feed size in bytes
    ///
    /// The entire feed must fit within this limit.
    ///
    /// Default: 100 MB
    pub max_feed_size_bytes: usize,

    /// Maximum attribute value length in bytes
    ///
    /// XML attributes should be reasonably sized.
    ///
    /// Default: 64 KB
    pub max_attribute_length: usize,

    /// Maximum number of podcast soundbites per entry
    ///
    /// Podcast 2.0 soundbite elements for shareable clips.
    ///
    /// Default: 10 soundbites
    pub max_podcast_soundbites: usize,

    /// Maximum number of podcast transcripts per entry
    ///
    /// Podcast 2.0 transcript elements.
    ///
    /// Default: 20 transcripts
    pub max_podcast_transcripts: usize,

    /// Maximum number of podcast funding elements per feed
    ///
    /// Podcast 2.0 funding elements for donation links.
    ///
    /// Default: 20 funding elements
    pub max_podcast_funding: usize,

    /// Maximum number of podcast person elements per entry
    ///
    /// Podcast 2.0 person elements for hosts, guests, etc.
    ///
    /// Default: 50 persons
    pub max_podcast_persons: usize,

    /// Maximum number of podcast value recipients per feed
    ///
    /// Podcast 2.0 value recipients for payment splitting.
    /// Prevents `DoS` from feeds with excessive recipient lists.
    ///
    /// Default: 20 recipients
    pub max_value_recipients: usize,

    /// Maximum number of alternate enclosures per entry
    ///
    /// Default: 20
    pub max_podcast_alternate_enclosures: usize,

    /// Maximum number of sources per alternate enclosure
    ///
    /// Default: 10
    pub max_podcast_alternate_enclosure_sources: usize,

    /// Maximum number of podroll entries per feed
    ///
    /// Default: 50
    pub max_podcast_podroll: usize,

    /// Maximum number of socialInteract elements per entry
    ///
    /// Default: 20
    pub max_podcast_social_interact: usize,

    /// Maximum number of txt records per feed or entry
    ///
    /// Default: 20
    pub max_podcast_txt: usize,

    /// Maximum number of follow links per feed or entry
    ///
    /// Default: 20
    pub max_podcast_follow: usize,

    /// Maximum number of chat references per feed or entry
    ///
    /// Podcast 2.0 chat elements pointing to chat rooms/servers.
    ///
    /// Default: 20
    pub max_podcast_chat: usize,

    /// Maximum number of value time splits per `podcast:value` element
    ///
    /// Podcast 2.0 valueTimeSplit elements for routing payments over time
    /// ranges. Prevents `DoS` from feeds with excessive split lists.
    ///
    /// Default: 20
    pub max_podcast_value_time_splits: usize,

    /// Maximum number of JSON Feed extension objects captured per scope
    ///
    /// JSON Feed permits custom object keys (starting with `_` followed by a
    /// letter) anywhere in a feed; this bounds how many distinct keys are
    /// captured per feed-root or item-root scope, counted independently. When a
    /// scope has more extension keys than this limit, the surviving keys are the
    /// alphabetically-first ones, not the document-order-first ones: `serde_json`
    /// backs a JSON object with a `BTreeMap` by default (the `preserve_order`
    /// feature, which would switch it to an `IndexMap` and make truncation
    /// document-order-first, is not enabled).
    ///
    /// Default: 100
    pub max_json_extensions: usize,
}

impl Default for ParserLimits {
    /// Creates default parser limits suitable for general use
    ///
    /// These defaults are conservative and should work for most feeds,
    /// including large podcast feeds and news aggregators.
    fn default() -> Self {
        Self {
            max_entries: 10_000,
            max_links_per_feed: 100,
            max_links_per_entry: 50,
            max_authors: 20,
            max_contributors: 20,
            max_tags: 100,
            max_content_blocks: 10,
            max_enclosures: 20,
            max_namespaces: 100,
            max_nesting_depth: 100,
            max_html_nesting_depth: 100,
            max_text_length: 10 * 1024 * 1024,      // 10 MB
            max_feed_size_bytes: 100 * 1024 * 1024, // 100 MB
            max_attribute_length: 64 * 1024,        // 64 KB
            max_podcast_soundbites: 10,
            max_podcast_transcripts: 20,
            max_podcast_funding: 20,
            max_podcast_persons: 50,
            max_value_recipients: 20,
            max_podcast_alternate_enclosures: 20,
            max_podcast_alternate_enclosure_sources: 10,
            max_podcast_podroll: 50,
            max_podcast_social_interact: 20,
            max_podcast_txt: 20,
            max_podcast_follow: 20,
            max_podcast_chat: 20,
            max_podcast_value_time_splits: 20,
            max_json_extensions: 100,
        }
    }
}

impl ParserLimits {
    /// Creates strict limits for resource-constrained environments
    ///
    /// Use this for embedded systems or when parsing untrusted feeds
    /// with minimal resources.
    ///
    /// # Examples
    ///
    /// ```
    /// use feedparser_rs::ParserLimits;
    ///
    /// let limits = ParserLimits::strict();
    /// assert_eq!(limits.max_entries, 1_000);
    /// ```
    #[must_use]
    pub const fn strict() -> Self {
        Self {
            max_entries: 1_000,
            max_links_per_feed: 20,
            max_links_per_entry: 10,
            max_authors: 5,
            max_contributors: 5,
            max_tags: 20,
            max_content_blocks: 3,
            max_enclosures: 5,
            max_namespaces: 20,
            max_nesting_depth: 50,
            max_html_nesting_depth: 50,
            max_text_length: 1024 * 1024,          // 1 MB
            max_feed_size_bytes: 10 * 1024 * 1024, // 10 MB
            max_attribute_length: 8 * 1024,        // 8 KB
            max_podcast_soundbites: 5,
            max_podcast_transcripts: 5,
            max_podcast_funding: 5,
            max_podcast_persons: 10,
            max_value_recipients: 5,
            max_podcast_alternate_enclosures: 5,
            max_podcast_alternate_enclosure_sources: 3,
            max_podcast_podroll: 10,
            max_podcast_social_interact: 5,
            max_podcast_txt: 5,
            max_podcast_follow: 5,
            max_podcast_chat: 5,
            max_podcast_value_time_splits: 5,
            max_json_extensions: 20,
        }
    }

    /// Creates permissive limits for trusted feeds
    ///
    /// Use this only for feeds from trusted sources where you expect
    /// large data volumes (e.g., feed archives).
    ///
    /// # Examples
    ///
    /// ```
    /// use feedparser_rs::ParserLimits;
    ///
    /// let limits = ParserLimits::permissive();
    /// assert_eq!(limits.max_entries, 100_000);
    /// ```
    #[must_use]
    pub const fn permissive() -> Self {
        Self {
            max_entries: 100_000,
            max_links_per_feed: 500,
            max_links_per_entry: 200,
            max_authors: 100,
            max_contributors: 100,
            max_tags: 500,
            max_content_blocks: 50,
            max_enclosures: 100,
            max_namespaces: 500,
            max_nesting_depth: 200,
            max_html_nesting_depth: 200,
            max_text_length: 50 * 1024 * 1024,      // 50 MB
            max_feed_size_bytes: 500 * 1024 * 1024, // 500 MB
            max_attribute_length: 256 * 1024,       // 256 KB
            max_podcast_soundbites: 50,
            max_podcast_transcripts: 100,
            max_podcast_funding: 50,
            max_podcast_persons: 200,
            max_value_recipients: 50,
            max_podcast_alternate_enclosures: 100,
            max_podcast_alternate_enclosure_sources: 50,
            max_podcast_podroll: 200,
            max_podcast_social_interact: 100,
            max_podcast_txt: 100,
            max_podcast_follow: 100,
            max_podcast_chat: 100,
            max_podcast_value_time_splits: 50,
            max_json_extensions: 500,
        }
    }

    /// Validates that a feed size is within limits
    ///
    /// Call this before starting to parse a feed.
    ///
    /// # Errors
    ///
    /// Returns an error if the feed exceeds `max_feed_size_bytes`.
    pub const fn check_feed_size(&self, size: usize) -> Result<(), LimitError> {
        if size > self.max_feed_size_bytes {
            Err(LimitError::FeedTooLarge {
                size,
                max: self.max_feed_size_bytes,
            })
        } else {
            Ok(())
        }
    }

    /// Validates that a collection size is within limits
    ///
    /// Use this during parsing to check collection sizes.
    ///
    /// # Errors
    ///
    /// Returns an error if the collection size exceeds the specified limit.
    pub const fn check_collection_size(
        &self,
        current: usize,
        limit: usize,
        name: &'static str,
    ) -> Result<(), LimitError> {
        if current >= limit {
            Err(LimitError::CollectionTooLarge {
                name,
                size: current,
                max: limit,
            })
        } else {
            Ok(())
        }
    }

    /// Validates XML nesting depth
    ///
    /// # Errors
    ///
    /// Returns an error if nesting depth exceeds `max_nesting_depth`.
    pub const fn check_nesting_depth(&self, depth: usize) -> Result<(), LimitError> {
        if depth > self.max_nesting_depth {
            Err(LimitError::NestingTooDeep {
                depth,
                max: self.max_nesting_depth,
            })
        } else {
            Ok(())
        }
    }

    /// Validates text field length
    ///
    /// # Errors
    ///
    /// Returns an error if text length exceeds `max_text_length`.
    pub const fn check_text_length(&self, length: usize) -> Result<(), LimitError> {
        if length > self.max_text_length {
            Err(LimitError::TextTooLong {
                length,
                max: self.max_text_length,
            })
        } else {
            Ok(())
        }
    }
}

/// Errors that occur when parser limits are exceeded
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[allow(missing_docs)] // Fields are self-explanatory from error messages
pub enum LimitError {
    /// Feed size exceeds maximum allowed
    #[error("Feed size ({size} bytes) exceeds maximum ({max} bytes)")]
    FeedTooLarge { size: usize, max: usize },

    /// Collection (entries, links, etc.) has too many items
    #[error("Collection '{name}' has {size} items, exceeds maximum ({max})")]
    CollectionTooLarge {
        name: &'static str,
        size: usize,
        max: usize,
    },

    /// XML nesting is too deep
    #[error("XML nesting depth ({depth}) exceeds maximum ({max})")]
    NestingTooDeep { depth: usize, max: usize },

    /// Text field is too long
    #[error("Text field length ({length} bytes) exceeds maximum ({max} bytes)")]
    TextTooLong { length: usize, max: usize },
}

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

    #[test]
    fn test_default_limits() {
        let limits = ParserLimits::default();
        assert_eq!(limits.max_entries, 10_000);
        assert_eq!(limits.max_feed_size_bytes, 100 * 1024 * 1024);
    }

    #[test]
    fn test_strict_limits() {
        let limits = ParserLimits::strict();
        assert_eq!(limits.max_entries, 1_000);
        assert!(limits.max_entries < ParserLimits::default().max_entries);
    }

    #[test]
    fn test_permissive_limits() {
        let limits = ParserLimits::permissive();
        assert_eq!(limits.max_entries, 100_000);
        assert!(limits.max_entries > ParserLimits::default().max_entries);
    }

    #[test]
    fn test_check_feed_size_ok() {
        let limits = ParserLimits::default();
        assert!(limits.check_feed_size(1024).is_ok());
    }

    #[test]
    fn test_check_feed_size_too_large() {
        let limits = ParserLimits::default();
        let result = limits.check_feed_size(200 * 1024 * 1024);
        assert!(result.is_err());
        assert!(matches!(result, Err(LimitError::FeedTooLarge { .. })));
    }

    #[test]
    fn test_check_collection_size_ok() {
        let limits = ParserLimits::default();
        assert!(
            limits
                .check_collection_size(50, limits.max_entries, "entries")
                .is_ok()
        );
    }

    #[test]
    fn test_check_collection_size_too_large() {
        let limits = ParserLimits::default();
        let result = limits.check_collection_size(10_001, limits.max_entries, "entries");
        assert!(result.is_err());
        assert!(matches!(result, Err(LimitError::CollectionTooLarge { .. })));
    }

    #[test]
    fn test_check_nesting_depth_ok() {
        let limits = ParserLimits::default();
        assert!(limits.check_nesting_depth(50).is_ok());
    }

    #[test]
    fn test_check_nesting_depth_too_deep() {
        let limits = ParserLimits::default();
        let result = limits.check_nesting_depth(101);
        assert!(result.is_err());
        assert!(matches!(result, Err(LimitError::NestingTooDeep { .. })));
    }

    #[test]
    fn test_check_text_length_ok() {
        let limits = ParserLimits::default();
        assert!(limits.check_text_length(1024).is_ok());
    }

    #[test]
    fn test_check_text_length_too_long() {
        let limits = ParserLimits::default();
        let result = limits.check_text_length(20 * 1024 * 1024);
        assert!(result.is_err());
        assert!(matches!(result, Err(LimitError::TextTooLong { .. })));
    }

    #[test]
    fn test_limit_error_display() {
        let err = LimitError::FeedTooLarge {
            size: 200_000_000,
            max: 100_000_000,
        };
        let msg = err.to_string();
        assert!(msg.contains("200000000"));
        assert!(msg.contains("100000000"));
    }

    #[test]
    fn test_max_value_recipients_default() {
        let limits = ParserLimits::default();
        assert_eq!(limits.max_value_recipients, 20);
    }

    #[test]
    fn test_max_value_recipients_strict() {
        let limits = ParserLimits::strict();
        assert_eq!(limits.max_value_recipients, 5);
        assert!(limits.max_value_recipients < ParserLimits::default().max_value_recipients);
    }

    #[test]
    fn test_max_value_recipients_permissive() {
        let limits = ParserLimits::permissive();
        assert_eq!(limits.max_value_recipients, 50);
        assert!(limits.max_value_recipients > ParserLimits::default().max_value_recipients);
    }

    #[test]
    fn test_value_recipients_limit_enforcement() {
        let limits = ParserLimits::default();

        // Within limit
        assert!(
            limits
                .check_collection_size(19, limits.max_value_recipients, "value_recipients")
                .is_ok()
        );

        // At limit
        assert!(
            limits
                .check_collection_size(20, limits.max_value_recipients, "value_recipients")
                .is_err()
        );

        // Exceeds limit
        let result =
            limits.check_collection_size(21, limits.max_value_recipients, "value_recipients");
        assert!(result.is_err());
        assert!(matches!(result, Err(LimitError::CollectionTooLarge { .. })));
    }

    #[test]
    fn test_max_podcast_chat_tiers() {
        assert_eq!(ParserLimits::default().max_podcast_chat, 20);
        assert_eq!(ParserLimits::strict().max_podcast_chat, 5);
        assert_eq!(ParserLimits::permissive().max_podcast_chat, 100);
        assert!(ParserLimits::strict().max_podcast_chat < ParserLimits::default().max_podcast_chat);
        assert!(
            ParserLimits::permissive().max_podcast_chat > ParserLimits::default().max_podcast_chat
        );
    }

    #[test]
    fn test_podcast_chat_limit_enforcement() {
        let limits = ParserLimits::default();
        assert!(
            limits
                .check_collection_size(19, limits.max_podcast_chat, "chat")
                .is_ok()
        );
        let result = limits.check_collection_size(20, limits.max_podcast_chat, "chat");
        assert!(result.is_err());
        assert!(matches!(result, Err(LimitError::CollectionTooLarge { .. })));
    }

    #[test]
    fn test_max_podcast_value_time_splits_tiers() {
        assert_eq!(ParserLimits::default().max_podcast_value_time_splits, 20);
        assert_eq!(ParserLimits::strict().max_podcast_value_time_splits, 5);
        assert_eq!(ParserLimits::permissive().max_podcast_value_time_splits, 50);
        assert!(
            ParserLimits::strict().max_podcast_value_time_splits
                < ParserLimits::default().max_podcast_value_time_splits
        );
        assert!(
            ParserLimits::permissive().max_podcast_value_time_splits
                > ParserLimits::default().max_podcast_value_time_splits
        );
    }

    #[test]
    fn test_podcast_value_time_splits_limit_enforcement() {
        let limits = ParserLimits::default();
        assert!(
            limits
                .check_collection_size(19, limits.max_podcast_value_time_splits, "time_splits")
                .is_ok()
        );
        let result =
            limits.check_collection_size(20, limits.max_podcast_value_time_splits, "time_splits");
        assert!(result.is_err());
        assert!(matches!(result, Err(LimitError::CollectionTooLarge { .. })));
    }

    #[test]
    fn test_max_json_extensions_tiers() {
        assert_eq!(ParserLimits::default().max_json_extensions, 100);
        assert_eq!(ParserLimits::strict().max_json_extensions, 20);
        assert_eq!(ParserLimits::permissive().max_json_extensions, 500);
        assert!(
            ParserLimits::strict().max_json_extensions
                < ParserLimits::default().max_json_extensions
        );
        assert!(
            ParserLimits::permissive().max_json_extensions
                > ParserLimits::default().max_json_extensions
        );
    }
}