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
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"
resolve-link
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"