A stateless RSS 2.0 and Atom 1.0 reader. fetch gets and parses a feed, parse reads feed text with no network, and new-entries diffs entries against the ids a caller keeps. Nothing here remembers anything: storing ids, ETags and dates belongs to the caller.

Both formats come back in one shape: {title, link, updated, updated-at, entries}, each entry {id, title, link, published, updated, summary, author, content, published-at, updated-at}. A missing or blank value is null.

Dates. published and updated are the raw strings from the feed. published-at and updated-at are the same moments as UTC YYYY-MM-DDTHH:MM:SSZ, or null when the raw string isn't a well-formed RFC 822 or RFC 3339 date with a known offset.

Malformed feeds. ::hot::xml is strict. XML it can't read, and a document that isn't RSS or Atom, is an Err: nothing is repaired or guessed at.

Conditional GET. Pass the etag and last-modified from the last result in opts. A 304 comes back as {not-modified: true, etag, last-modified, entries: []}.

Context Vars

Optional
  • feed.user-agent

Values

MONTHS

MONTHS: Map {
  jan: "01",
  feb: "02",
  mar: "03",
  apr: "04",
  may: "05",
  jun: "06",
  jul: "07",
  aug: "08",
  sep: "09",
  oct: "10",
  nov: "11",
  dec: "12"
}

RFC_3339

RFC_3339: Str "^(\\d{4}-\\d{2}-\\d{2})[Tt ](\\d{2}:\\d{2}:\\d{2})(?:\\.\\d+)?([Zz]|[+-]\\d{2}:\\d{2})$"

RFC_822

RFC_822: Str "^(?:[A-Za-z]+,?\\s+)?(\\d{1,2})\\s+([A-Za-z]{3})[A-Za-z]*\\s+(\\d{4})\\s+(\\d{2}):(\\d{2})(?::(\\d{2}))?\\s+([A-Za-z]+|[+-]\\d{4})$"

ZONES

ZONES: Map {
  gmt: "+00:00",
  ut: "+00:00",
  utc: "+00:00",
  z: "+00:00",
  est: "-05:00",
  edt: "-04:00",
  cst: "-06:00",
  cdt: "-05:00",
  mst: "-07:00",
  mdt: "-06:00",
  pst: "-08:00",
  pdt: "-07:00"
}

Functions

atom-text

fn (node: Any, tags: Vec<Str>): Str?

The first of tags under node with text, as first-text, except that type="xhtml" content comes back as its <div> markup, since ::hot::xml/text skips child elements (pure).

Example

entry from-xml("<entry><title type='xhtml'><div><b>Rates held</b></div></title></entry>")
::feed/atom-text(entry, ["title"])  // "<div><b>Rates held</b></div>"

fetch

fn (url: Str): Map
fn (url: Str, opts: Map): Map

GET a feed and parse it. Returns the parse result plus not-modified, etag and last-modified.

opts: user-agent (sec.gov asks for a company name and contact email), and etag and last-modified from an earlier result, which make the request conditional. On a 304, not-modified is true and entries is empty. Not every publisher sends either validator. Non-2xx is an Err carrying HttpError.

Example

first-read ::feed/fetch("https://www.sec.gov/news/pressreleases.rss", {user-agent: "Acme Corp ops@acme.example"})
next-read ::feed/fetch("https://www.sec.gov/news/pressreleases.rss", {
  user-agent: "Acme Corp ops@acme.example",
  etag: first-read.etag,
  last-modified: first-read.last-modified
})
next-read.not-modified

first-text

fn (node: Any, tags: Vec<Str>): Str?

The first non-blank text among node's children named by tags, in the order given, or null. Namespaced children go by their prefix, such as dc:creator (pure).

Example

item from-xml("<item><summary> </summary><description>Rates held</description></item>")
::feed/first-text(item, ["summary", "description"])  // "Rates held"
::feed/first-text(item, ["author"])                  // null

new-entries

fn (entries: Vec<Map>, seen-ids: Vec): Vec<Map>

The entries whose id isn't in seen-ids, in feed order (pure). An entry with no id can't be matched, so it always counts as new.

Example

entries [{id: "a", title: "Old"}, {id: "b", title: "New"}]
map(::feed/new-entries(entries, ["a"]), %.title)  // ["New"]

// The ids to store for next time
map(entries, %.id)  // ["a", "b"]

normalize-date

fn (raw: Str?): Str?

An RFC 822 or RFC 3339 date as UTC YYYY-MM-DDTHH:MM:SSZ, dropping fractions of a second (pure). Null for anything else: other formats, a date-only value, a two-digit year, a time zone name with more than one meaning, or a date that doesn't exist.

Example

::feed/normalize-date("Fri, 30 Oct 2026 15:30:00 -0400")  // "2026-10-30T19:30:00Z"
::feed/normalize-date("2026-11-03T17:27:58-05:00")        // "2026-11-03T22:27:58Z"
::feed/normalize-date("yesterday")                        // null

parse

fn (text: Str | Bytes): Map
fn (text: Str | Bytes, opts: Map): Map

Parse RSS 2.0 or Atom 1.0 text, or Bytes in an encoding ::feed::api/decode reads (pure). opts.base-url is the URL relative links resolve against when the feed has no xml:base. An Err for malformed XML or for any other kind of document, RSS 1.0 (RDF) included.

Example

text "<rss version='2.0'><channel><title>News</title><item><title>Rates held</title><guid>a1</guid></item></channel></rss>"
feed ::feed/parse(text)
feed.title                 // "News"
first(feed.entries).title  // "Rates held"

read-response

fn (response: ::hot::http/HttpResponse, url: Str, opts: Map): Map

The result of fetch for one response (pure). A 304 keeps the caller's etag and last-modified when the server doesn't repeat them.

Example

response {status: 304, headers: {}, body: ""}
out ::feed/read-response(response, "https://example.com/feed.xml", {etag: "abc"})
out.not-modified  // true
out.etag          // "abc"
fn (base: Str?, href: Str?): Str?

href against base (pure), for the relative links Atom allows: EDGAR writes /cgi-bin/browse-edgar?action=getcurrent. An absolute href, or one with no base to go on, comes back unchanged. .. segments are left in the URL.

Example

::feed/resolve-link("https://www.sec.gov/a/b.xml", "/c?d=1")  // "https://www.sec.gov/c?d=1"
::feed/resolve-link("https://www.sec.gov/a/b.xml", "c.html")  // "https://www.sec.gov/a/c.html"