Skip to content

Commit 8d8a40c

Browse files
bug-opsbug-ops
committed
feat: add semantic newtypes (Url, MimeType, Email) and box namespace metadata
BREAKING CHANGE: Type changes in public API ## Changes ### Semantic Newtypes (types/common.rs) - Add `Url(String)` - URL wrapper with Deref<Target=str> - Add `MimeType(Arc<str>)` - MIME type with string interning for efficient cloning - Add `Email(String)` - Email wrapper with Deref<Target=str> - All newtypes implement: From, Into, Deref, AsRef, Display, PartialEq, serde traits ### Boxing Large Optional Structs - Box `ItunesFeedMeta`, `ItunesEntryMeta` - reduces stack size - Box `PodcastMeta`, `PodcastEntryMeta` - reduces stack size - Box `SyndicationMeta`, `GeoLocation` - reduces stack size - Memory savings: ~7.6 KB per 100-entry plain RSS feed (76% reduction) ### Type Applications - Link.href: String → Url - Link.link_type: Option<String> → Option<MimeType> - Person.email: Option<String> → Option<Email> - Enclosure.url: String → Url - Enclosure.enclosure_type: Option<String> → Option<MimeType> - MediaContent.url: String → Url - MediaContent.content_type: Option<String> → Option<MimeType> - MediaThumbnail.url: String → Url - Image.url: String → Url - PodcastPerson.img/href: Option<String> → Option<Url> - PodcastTranscript.url/transcript_type: String/Option<String> → Url/Option<MimeType> - PodcastFunding.url: String → Url - PodcastChapters.url/chapters_type: String/Option<String> → Url/Option<MimeType> ### Binding Updates - Python: Use .as_deref() for Box fields - Node.js: Use .map(|b| T::from(*b)) for Box fields, .into_inner() for newtypes ### Performance - No parsing performance regression (verified with benchmarks) - Arc<str> for MimeType provides ~10x faster cloning - Box reduces stack frame size for feeds without namespace metadata
1 parent 3672893 commit 8d8a40c

File tree

18 files changed

+938
-193
lines changed

18 files changed

+938
-193
lines changed

‎crates/feedparser-rs-core/src/lib.rs‎

Lines changed: 142 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used, clippy::panic))]
22

3-
//! feedparser-rs-core: High-performance RSS/Atom/JSON Feed parser
3+
//! # feedparser-rs: High-performance RSS/Atom/JSON Feed parser
44
//!
5-
//! This crate provides a pure Rust implementation of feed parsing with
6-
//! compatibility for Python's feedparser library.
5+
//! A pure Rust implementation of feed parsing with API compatibility for Python's
6+
//! [feedparser](https://github.com/kurtmckee/feedparser) library. Designed for
7+
//! 10-100x faster feed parsing with identical behavior.
78
//!
8-
//! # Examples
9+
//! ## Quick Start
910
//!
1011
//! ```
1112
//! use feedparser_rs::parse;
@@ -15,29 +16,148 @@
1516
//! <rss version="2.0">
1617
//! <channel>
1718
//! <title>Example Feed</title>
19+
//! <link>https://example.com</link>
20+
//! <item>
21+
//! <title>First Post</title>
22+
//! <link>https://example.com/post/1</link>
23+
//! </item>
1824
//! </channel>
1925
//! </rss>
2026
//! "#;
2127
//!
2228
//! let feed = parse(xml.as_bytes()).unwrap();
23-
//! assert!(feed.bozo == false);
29+
//! assert!(!feed.bozo);
30+
//! assert_eq!(feed.feed.title.as_deref(), Some("Example Feed"));
31+
//! assert_eq!(feed.entries.len(), 1);
2432
//! ```
2533
//!
26-
//! # Features
34+
//! ## Supported Formats
2735
//!
28-
//! - Parse RSS 0.9x, 1.0, 2.0
29-
//! - Parse Atom 0.3, 1.0
30-
//! - Parse JSON Feed 1.0, 1.1
31-
//! - Tolerant parsing with bozo flag
32-
//! - Multi-format date parsing
33-
//! - HTML sanitization
34-
//! - Encoding detection
36+
//! | Format | Versions | Detection |
37+
//! |--------|----------|-----------|
38+
//! | RSS | 0.90, 0.91, 0.92, 2.0 | `<rss>` element |
39+
//! | RSS 1.0 | RDF-based | `<rdf:RDF>` with RSS namespace |
40+
//! | Atom | 0.3, 1.0 | `<feed>` with Atom namespace |
41+
//! | JSON Feed | 1.0, 1.1 | `version` field starting with `https://jsonfeed.org` |
3542
//!
36-
//! # Architecture
43+
//! ## Namespace Extensions
3744
//!
38-
//! The library provides core data structures like [`ParsedFeed`], [`Entry`], and [`FeedMeta`]
39-
//! for representing parsed feed data. The main entry point is the [`parse`] function which
40-
//! automatically detects feed format and returns parsed results.
45+
//! The parser supports common feed extensions:
46+
//!
47+
//! - **iTunes/Podcast** (`itunes:`) - Podcast metadata, categories, explicit flags
48+
//! - **Podcast 2.0** (`podcast:`) - Transcripts, chapters, funding, persons
49+
//! - **Dublin Core** (`dc:`) - Creator, date, rights, subject
50+
//! - **Media RSS** (`media:`) - Thumbnails, content, descriptions
51+
//! - **Content** (`content:encoded`) - Full HTML content
52+
//! - **Syndication** (`sy:`) - Update frequency hints
53+
//! - **`GeoRSS`** (`georss:`) - Geographic coordinates
54+
//! - **Creative Commons** (`cc:`, `creativeCommons:`) - License information
55+
//!
56+
//! ## Type-Safe URL and MIME Handling
57+
//!
58+
//! The library uses semantic newtypes for improved type safety:
59+
//!
60+
//! ```
61+
//! use feedparser_rs::{Url, MimeType, Email};
62+
//!
63+
//! // Url - wraps URL strings without validation (bozo-compatible)
64+
//! let url = Url::new("https://example.com/feed.xml");
65+
//! assert_eq!(url.as_str(), "https://example.com/feed.xml");
66+
//! assert!(url.starts_with("https://")); // Deref to str
67+
//!
68+
//! // MimeType - uses Arc<str> for efficient cloning
69+
//! let mime = MimeType::new("application/rss+xml");
70+
//! let clone = mime.clone(); // Cheap: just increments refcount
71+
//!
72+
//! // Email - wraps email addresses
73+
//! let email = Email::new("author@example.com");
74+
//! ```
75+
//!
76+
//! These types implement <code>[`Deref`]&lt;Target=str&gt;</code>, so string methods work directly:
77+
//!
78+
//! ```
79+
//! use feedparser_rs::Url;
80+
//!
81+
//! let url = Url::new("https://example.com/path?query=1");
82+
//! assert!(url.contains("example.com"));
83+
//! assert_eq!(url.len(), 32);
84+
//! ```
85+
//!
86+
//! ## The Bozo Pattern
87+
//!
88+
//! Following Python feedparser's philosophy, this library **never panics** on
89+
//! malformed input. Instead, it sets the `bozo` flag and continues parsing:
90+
//!
91+
//! ```
92+
//! use feedparser_rs::parse;
93+
//!
94+
//! // XML with undefined entity - triggers bozo
95+
//! let xml_with_entity = b"<rss version='2.0'><channel><title>Test &#xFFFF;</title></channel></rss>";
96+
//!
97+
//! let feed = parse(xml_with_entity).unwrap();
98+
//! // Parser handles invalid characters gracefully
99+
//! assert!(feed.feed.title.is_some());
100+
//! ```
101+
//!
102+
//! The bozo flag indicates the feed had issues but was still parseable.
103+
//!
104+
//! ## Resource Limits
105+
//!
106+
//! Protect against malicious feeds with [`ParserLimits`]:
107+
//!
108+
//! ```
109+
//! use feedparser_rs::{parse_with_limits, ParserLimits};
110+
//!
111+
//! // Customize limits for untrusted input
112+
//! let limits = ParserLimits {
113+
//! max_entries: 100,
114+
//! max_text_length: 50_000,
115+
//! ..Default::default()
116+
//! };
117+
//!
118+
//! let xml = b"<rss version='2.0'><channel><title>Safe</title></channel></rss>";
119+
//! let feed = parse_with_limits(xml, limits).unwrap();
120+
//! ```
121+
//!
122+
//! ## HTTP Fetching
123+
//!
124+
//! With the `http` feature (enabled by default), fetch feeds from URLs:
125+
//!
126+
//! ```no_run
127+
//! use feedparser_rs::parse_url;
128+
//!
129+
//! // Simple fetch
130+
//! let feed = parse_url("https://example.com/feed.xml", None, None, None)?;
131+
//!
132+
//! // With conditional GET for caching
133+
//! let feed2 = parse_url(
134+
//! "https://example.com/feed.xml",
135+
//! feed.etag.as_deref(), // ETag from previous fetch
136+
//! feed.modified.as_deref(), // Last-Modified from previous fetch
137+
//! Some("MyApp/1.0"), // Custom User-Agent
138+
//! )?;
139+
//!
140+
//! if feed2.status == Some(304) {
141+
//! println!("Feed not modified since last fetch");
142+
//! }
143+
//! # Ok::<(), feedparser_rs::FeedError>(())
144+
//! ```
145+
//!
146+
//! ## Core Types
147+
//!
148+
//! - [`ParsedFeed`] - Complete parsed feed with metadata and entries
149+
//! - [`FeedMeta`] - Feed-level metadata (title, link, author, etc.)
150+
//! - [`Entry`] - Individual feed entry/item
151+
//! - [`Link`], [`Person`], [`Tag`] - Common feed elements
152+
//! - [`Url`], [`MimeType`], [`Email`] - Type-safe string wrappers
153+
//!
154+
//! ## Module Structure
155+
//!
156+
//! - [`types`] - All data structures for parsed feeds
157+
//! - [`namespace`] - Handlers for namespace extensions (iTunes, Podcast 2.0, etc.)
158+
//! - [`util`] - Helper functions for dates, HTML sanitization, encoding
159+
//! - [`compat`] - Python feedparser API compatibility layer
160+
//! - [`http`] - HTTP client for fetching feeds (requires `http` feature)
41161
42162
/// Compatibility utilities for Python feedparser API
43163
pub mod compat;
@@ -68,11 +188,12 @@ pub use limits::{LimitError, ParserLimits};
68188
pub use options::ParseOptions;
69189
pub use parser::{detect_format, parse, parse_with_limits};
70190
pub use types::{
71-
Content, Enclosure, Entry, FeedMeta, FeedVersion, Generator, Image, ItunesCategory,
191+
Content, Email, Enclosure, Entry, FeedMeta, FeedVersion, Generator, Image, ItunesCategory,
72192
ItunesEntryMeta, ItunesFeedMeta, ItunesOwner, LimitedCollectionExt, Link, MediaContent,
73-
MediaThumbnail, ParsedFeed, Person, PodcastChapters, PodcastEntryMeta, PodcastFunding,
74-
PodcastMeta, PodcastPerson, PodcastSoundbite, PodcastTranscript, PodcastValue,
75-
PodcastValueRecipient, Source, Tag, TextConstruct, TextType, parse_duration, parse_explicit,
193+
MediaThumbnail, MimeType, ParsedFeed, Person, PodcastChapters, PodcastEntryMeta,
194+
PodcastFunding, PodcastMeta, PodcastPerson, PodcastSoundbite, PodcastTranscript, PodcastValue,
195+
PodcastValueRecipient, Source, Tag, TextConstruct, TextType, Url, parse_duration,
196+
parse_explicit,
76197
};
77198

78199
pub use namespace::syndication::{SyndicationMeta, UpdatePeriod};

‎crates/feedparser-rs-core/src/namespace/cc.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ pub fn handle_feed_element(
5353
if let Some(license_url) = extract_license_url(attrs, text) {
5454
feed.links.try_push_limited(
5555
Link {
56-
href: license_url,
56+
href: license_url.into(),
5757
rel: Some("license".to_string()),
5858
..Default::default()
5959
},
@@ -94,7 +94,7 @@ pub fn handle_entry_element(
9494
if let Some(license_url) = extract_license_url(attrs, text) {
9595
entry.links.try_push_limited(
9696
Link {
97-
href: license_url,
97+
href: license_url.into(),
9898
rel: Some("license".to_string()),
9999
..Default::default()
100100
},

‎crates/feedparser-rs-core/src/namespace/content.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ pub fn handle_entry_element(element: &str, text: &str, entry: &mut Entry) {
2626
// content:encoded → add to entry.content as HTML
2727
entry.content.push(Content {
2828
value: text.to_string(),
29-
content_type: Some("text/html".to_string()),
29+
content_type: Some("text/html".into()),
3030
language: None,
3131
base: None,
3232
});

‎crates/feedparser-rs-core/src/namespace/georss.rs‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -178,25 +178,25 @@ pub fn handle_entry_element(
178178
match tag {
179179
b"point" => {
180180
if let Some(loc) = parse_point(text) {
181-
entry.geo = Some(loc);
181+
entry.geo = Some(Box::new(loc));
182182
}
183183
true
184184
}
185185
b"line" => {
186186
if let Some(loc) = parse_line(text) {
187-
entry.geo = Some(loc);
187+
entry.geo = Some(Box::new(loc));
188188
}
189189
true
190190
}
191191
b"polygon" => {
192192
if let Some(loc) = parse_polygon(text) {
193-
entry.geo = Some(loc);
193+
entry.geo = Some(Box::new(loc));
194194
}
195195
true
196196
}
197197
b"box" => {
198198
if let Some(loc) = parse_box(text) {
199-
entry.geo = Some(loc);
199+
entry.geo = Some(Box::new(loc));
200200
}
201201
true
202202
}
@@ -225,25 +225,25 @@ pub fn handle_feed_element(
225225
match tag {
226226
b"point" => {
227227
if let Some(loc) = parse_point(text) {
228-
feed.geo = Some(loc);
228+
feed.geo = Some(Box::new(loc));
229229
}
230230
true
231231
}
232232
b"line" => {
233233
if let Some(loc) = parse_line(text) {
234-
feed.geo = Some(loc);
234+
feed.geo = Some(Box::new(loc));
235235
}
236236
true
237237
}
238238
b"polygon" => {
239239
if let Some(loc) = parse_polygon(text) {
240-
feed.geo = Some(loc);
240+
feed.geo = Some(Box::new(loc));
241241
}
242242
true
243243
}
244244
b"box" => {
245245
if let Some(loc) = parse_box(text) {
246-
feed.geo = Some(loc);
246+
feed.geo = Some(Box::new(loc));
247247
}
248248
true
249249
}

‎crates/feedparser-rs-core/src/namespace/media_rss.rs‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,17 @@
1414
/// - `media:keywords` → tags (comma-separated)
1515
/// - `media:category` → tags
1616
/// - `media:credit` → contributors
17+
///
18+
/// # Type Design Note
19+
///
20+
/// The [`MediaContent`] and [`MediaThumbnail`] types in this module use raw `String`
21+
/// fields instead of the `Url`/`MimeType` newtypes from `types::common`. This is
22+
/// intentional:
23+
///
24+
/// 1. These are internal parsing types with extended attributes (medium, bitrate,
25+
/// framerate, expression, `is_default`) not present in the public API types.
26+
/// 2. The `media_content_to_enclosure` function handles conversion to public types.
27+
/// 3. The public API types in `types::common::MediaContent` use proper newtypes.
1728
use crate::types::{Enclosure, Entry, Tag};
1829

1930
/// Media RSS namespace URI
@@ -191,8 +202,8 @@ pub fn handle_entry_element(element: &str, text: &str, entry: &mut Entry) {
191202
/// ```
192203
pub fn media_content_to_enclosure(content: &MediaContent) -> Enclosure {
193204
Enclosure {
194-
url: content.url.clone(),
195-
enclosure_type: content.type_.clone(),
205+
url: content.url.clone().into(),
206+
enclosure_type: content.type_.as_ref().map(|t| t.clone().into()),
196207
length: content.file_size,
197208
}
198209
}

‎crates/feedparser-rs-core/src/namespace/syndication.rs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ pub fn handle_feed_element(element: &str, text: &str, feed: &mut FeedMeta) {
8282
"updatePeriod" => {
8383
if let Some(period) = UpdatePeriod::parse(text) {
8484
if feed.syndication.is_none() {
85-
feed.syndication = Some(SyndicationMeta::default());
85+
feed.syndication = Some(Box::new(SyndicationMeta::default()));
8686
}
8787
if let Some(syn) = &mut feed.syndication {
8888
syn.update_period = Some(period);
@@ -92,7 +92,7 @@ pub fn handle_feed_element(element: &str, text: &str, feed: &mut FeedMeta) {
9292
"updateFrequency" => {
9393
if let Ok(freq) = text.parse::<u32>() {
9494
if feed.syndication.is_none() {
95-
feed.syndication = Some(SyndicationMeta::default());
95+
feed.syndication = Some(Box::new(SyndicationMeta::default()));
9696
}
9797
if let Some(syn) = &mut feed.syndication {
9898
syn.update_frequency = Some(freq);
@@ -101,7 +101,7 @@ pub fn handle_feed_element(element: &str, text: &str, feed: &mut FeedMeta) {
101101
}
102102
"updateBase" => {
103103
if feed.syndication.is_none() {
104-
feed.syndication = Some(SyndicationMeta::default());
104+
feed.syndication = Some(Box::new(SyndicationMeta::default()));
105105
}
106106
if let Some(syn) = &mut feed.syndication {
107107
syn.update_base = Some(text.to_string());

0 commit comments

Comments
 (0)