rss-gen 0.0.6

Contents

• Install — Cargo, MSRV, source
• Quick Start — generate an RSS 2.0 feed in ten lines
• Library Usage
  • RSS generation
  • Atom 1.0 generation
  • Parsing existing feeds
  • Format auto-detection
  • Validation diagnostics
  • quick_rss helper
  • Constants and limits
• Modules
• Features
• Development
• Security
• Documentation
• License

Install

As a Rust library

cargo add rss-gen

Or pin explicitly in Cargo.toml:

[dependencies]
rss-gen = "0.0.6"

MSRV

CI runs stable on every push, plus a dedicated MSRV lane that pins the 1.88.0 floor. Cross-platform matrix: Ubuntu + macOS + Windows.

Build from source

git clone https://github.com/sebastienrousseau/rssgen.git
cd rssgen
cargo test --workspace --all-features    # full suite, ~200 tests

Quick Start

use rss_gen::{generate_rss, RssData, RssItem, RssVersion};

fn main() -> Result<(), rss_gen::RssError> {
    // Construct an RSS 2.0 channel via the builder API.
    let mut feed = RssData::new(Some(RssVersion::RSS2_0))
        .title("My Rust Blog")
        .link("https://example.com")
        .description("A blog about Rust");

    // Items are appended in the order they should appear.
    feed.add_item(
        RssItem::new()
            .title("Hello, world")
            .link("https://example.com/hello")
            .description("First post")
            .guid("https://example.com/hello"),
    );

    let xml = generate_rss(&feed)?;
    assert!(xml.contains("<rss version=\"2.0\""));
    assert!(xml.contains("<title>My Rust Blog</title>"));
    Ok(())
}

Library Usage

RSS generation

rss-gen covers every shipping RSS version. Pick the wire format via RssVersion; the builder is the same for all of them.

use rss_gen::{generate_rss, RssData, RssItem, RssVersion};

fn main() -> Result<(), rss_gen::RssError> {
    let mut feed = RssData::new(Some(RssVersion::RSS2_0))
        .title("Engineering")
        .link("https://example.com")
        .description("Posts from the engineering team")
        .language("en-GB")
        .pub_date("Sat, 27 Jun 2026 00:00:00 GMT")
        .generator("rss-gen")
        // `atom_link` advertises the canonical feed URL via the
        // `<atom:link rel="self">` element on the channel.
        .atom_link("https://example.com/feed.xml");

    feed.add_item(
        RssItem::new()
            .title("Release notes")
            .link("https://example.com/release")
            .description("What shipped this week")
            .guid("https://example.com/release")
            .pub_date("Sat, 27 Jun 2026 00:00:00 GMT")
            .author("editor@example.com"),
    );

    let xml = generate_rss(&feed)?;
    // The emitted document is well-formed XML and includes the
    // standard atom:self link required by most feed readers.
    assert!(xml.contains(r#"<atom:link href="https://example.com/feed.xml""#));
    Ok(())
}

RssVersion::{RSS0_90, RSS0_91, RSS0_92, RSS1_0, RSS2_0} are all supported. RSS 1.0 emits the RDF wrapper (<rdf:RDF>); the others emit a <rss> root.

Atom 1.0 generation

Atom is a sibling code path — independent types, the same ergonomics. RFC 4287 required elements (id, title, updated) are checked at serialise time; entries inherit feed-level authors when none are declared per-entry, per §4.1.1.

use rss_gen::{generate_atom, AtomEntry, AtomFeed};

fn main() -> Result<(), rss_gen::RssError> {
    let feed = AtomFeed::new()
        .id("https://example.com/feed")
        .title("My Atom Feed")
        .updated("2026-06-27T00:00:00Z")
        .author_name("Jane Doe")
        // Convenience: emit `<link rel="self" href="...">`.
        .self_link("https://example.com/atom.xml")
        .add_entry(
            AtomEntry::new()
                .id("https://example.com/post-1")
                .title("First Post")
                .updated("2026-06-27T00:00:00Z")
                // Plain-text summary; use `summary_html` for an
                // explicit `type="html"` payload.
                .summary("Hello, Atom"),
        );

    let xml = generate_atom(&feed)?;
    assert!(xml.contains(r#"<feed xmlns="http://www.w3.org/2005/Atom">"#));
    Ok(())
}

Media enclosures (podcasts, attached video) follow Atom's typed-link model:

use rss_gen::{generate_atom, AtomEntry, AtomFeed};

fn main() -> Result<(), rss_gen::RssError> {
    let feed = AtomFeed::new()
        .id("https://example.com/podcast")
        .title("Pilot")
        .updated("2026-06-27T00:00:00Z")
        .author_name("Producer")
        .add_entry(
            AtomEntry::new()
                .id("https://example.com/ep-1")
                .title("Episode 1")
                .updated("2026-06-27T00:00:00Z")
                .summary("Pilot episode")
                // Emits <link rel="enclosure" type="audio/mpeg" length="12345678" .../>
                .add_enclosure(
                    "https://example.com/ep-1.mp3",
                    "audio/mpeg",
                    12_345_678,
                ),
        );

    let xml = generate_atom(&feed)?;
    assert!(xml.contains(r#"rel="enclosure""#));
    assert!(xml.contains(r#"type="audio/mpeg""#));
    Ok(())
}

Parsing existing feeds

parse_rss reads any supported RSS version into the same RssData struct used by the generator — round-tripping is symmetric.

use rss_gen::parse_rss;

fn main() -> Result<(), rss_gen::RssError> {
    let xml = r#"<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <title>Example</title>
    <link>https://example.com</link>
    <description>Sample feed</description>
    <item>
      <title>Post</title>
      <link>https://example.com/post</link>
      <description>Body</description>
    </item>
  </channel>
</rss>"#;

    let feed = parse_rss(xml, None)?;
    assert_eq!(feed.title, "Example");
    assert_eq!(feed.items.len(), 1);
    assert_eq!(feed.items[0].title, "Post");
    Ok(())
}

Format auto-detection

When the caller does not know upfront whether the document is RSS or Atom, detect_feed_format peeks the root element and returns a classifier value. It does not parse the rest of the document.

use rss_gen::{detect_feed_format, FeedFormat};

let rss_xml  = r#"<?xml version="1.0"?><rss version="2.0"><channel/></rss>"#;
let atom_xml = r#"<?xml version="1.0"?><feed xmlns="http://www.w3.org/2005/Atom"><id/></feed>"#;

assert_eq!(detect_feed_format(rss_xml),  FeedFormat::Rss);
assert_eq!(detect_feed_format(atom_xml), FeedFormat::Atom);

The classifier returns FeedFormat::RssRdf for RSS 1.0 (<rdf:RDF>) and FeedFormat::Unknown for documents that match neither root element — including hand-rolled <feed> documents that omit the Atom namespace declaration, so a misclassified payload does not silently flow into the Atom code path.

Validation diagnostics

Every validation error is prefixed with the element that produced it, so downstream tools (static site generators, CI gates, IDE integrations) can point at the offending field rather than a bare "missing field" message.

use rss_gen::{generate_rss, RssData, RssError};

fn main() {
    // Channel without a title, link, or description.
    let feed = RssData::new(None);

    match generate_rss(&feed) {
        Err(RssError::ValidationErrors(errors)) => {
            // Each entry is a `ValidationError { field, message }` —
            // dispatch programmatically on `field` rather than parsing
            // strings; `Display` (`e.to_string()`) still gives the
            // bare message for human-readable output.
            assert!(errors.iter().any(|e| e.field == "channel.title"));
            assert!(errors.iter().any(|e| e.field == "channel.link"));
            assert!(errors.iter().any(|e| e.field == "channel.description"));
        }
        other => panic!("expected ValidationErrors, got {other:?}"),
    }
}

Item-level link follows RSS 2.0 §5.7 — absolute URLs, root-relative paths (/tags/), and bare paths (articles/foo.html) are all accepted; whitespace, control characters, and empty strings are rejected. Channel-level link retains absolute-URL strictness because the spec requires it.

quick_rss helper

For one-shot generation of a minimal feed, quick_rss validates input bounds (length caps, URL scheme) and returns the serialised XML directly. Useful inside build.rs, snippet generators, and tests.

use rss_gen::quick_rss;

fn main() -> Result<(), rss_gen::RssError> {
    let xml = quick_rss(
        "My Rust Blog",
        "https://example.com",
        "A blog about Rust",
    )?;
    assert!(xml.contains("<title>My Rust Blog</title>"));
    assert!(xml.contains("<item>")); // an example item is included
    Ok(())
}

Constants and limits

rss-gen exposes its hard input bounds as pub const so callers can validate ahead of time rather than discover the limit at serialise time.

The VERSION constant resolves to the crate's CARGO_PKG_VERSION at compile time.

use rss_gen::{MAX_FEED_SIZE, VERSION};

assert!(VERSION.starts_with(char::is_numeric));
assert_eq!(MAX_FEED_SIZE, 1_048_576);

Modules

Features

Development

cargo build                                  # build the library
cargo test --workspace --all-features        # full test suite
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo fmt --all -- --check
cargo bench --bench benchmark                # Criterion harness
cargo +nightly fuzz run fuzz_rss_parsing     # structure-aware fuzzing

CI runs through a reusable workflow that gates Clippy, formatting, tests, cargo audit, cargo deny, dependency review, and CodeQL on every push and pull request. See CONTRIBUTING.md for signed-commit policy and PR guidelines.

Security

• No unsafe blocks. #![forbid(unsafe_code)] is enforced at the crate root — no FFI to a C XML parser, no raw-pointer dereferences, no unsafe blocks in the generator, parser, validator, or sanitiser.
• Input bounds. MAX_TITLE_LENGTH, MAX_LINK_LENGTH, MAX_DESCRIPTION_LENGTH, MAX_GENERAL_LENGTH, and MAX_FEED_SIZE cap every text dimension; quick_rss and RssData::validate / RssData::validate_size enforce them. Set these before exposing feed generation to untrusted input.
• Content sanitisation. sanitize_content removes invalid XML control characters (everything below 0x20 except \n, \r, \t) and escapes &, <, >, ", and ' so user-supplied content cannot break feed well-formedness or smuggle injected markup.
• URL hygiene. Channel-level link requires an absolute http / https URL. Item-level link follows RSS 2.0 §5.7 and permits relative paths, but rejects whitespace and control characters that would otherwise break feed-reader parsers.
• Supply chain. cargo audit and cargo deny run on every push via the shared security workflow. Dependabot is wired for the minor-and-patch group on Cargo.toml. CodeQL static analysis runs on every push and pull request.

Coordinated-disclosure contact and policy live in CONTRIBUTING.md.

Documentation

THE ARCHITECT — Sebastien Rousseau

THE ENGINE — EUXIS — Enterprise Unified Execution Intelligence System

License

Dual-licensed under Apache 2.0 or MIT, at your option.