Package-level declarations

Types

Link copied to clipboard
class Feed

A parsed feed: its channel fields and its entries in document order. Stable Core. Built with Feed { title = …; entries = … }, by RomeFeedParser and by a parser of your own.

Link copied to clipboard

An enclosure of a feed entry: a media file the entry points at. Stable Core. Built with FeedEnclosure(url) { mimeType = …; lengthBytes = … }.

Link copied to clipboard
class FeedEntry

One entry of a feed. Stable Core. Built with FeedEntry(id) { title = …; link = … }, by RomeFeedParser and by a parser of your own.

Link copied to clipboard
abstract class FeedFailure : HttpFailure

A failure of a feed document: the exchange and the policy were fine, the bytes were not a feed this module will read. Returned by a FeedParser and by FeedFetcher.fetch inside a Result.

Link copied to clipboard
sealed interface FeedFetch

The outcome of a successful fetch: Fetched or NotModified. Stable Core. The two are the whole contract, so a when over a FeedFetch needs no else. Whichever you got, store validators first, then adopt or ignore permanentlyMovedTo, then use the feed on Fetched.

Link copied to clipboard

Fetches feeds with a stateless conditional GET over a UrlFetcher. Stable Core.

Link copied to clipboard

The configuration of a FeedFetcher: the receiver of the factory's lambda. Stable Core. Not thread-safe; use it only inside the lambda.

Link copied to clipboard
class FeedInput(document: ByteArray, val contentType: String?, val baseUrl: Url?)

One document for a FeedParser. Stable Core. The bytes are copied in and read back as copies. toString() prints the document's size, whether a content type is present and the base URL as scheme, host and port; never the content, the content type's value or a path.

Link copied to clipboard
class FeedLimit

The FeedLimits bound a document exceeded; the limit of FeedFailure.LimitExceeded. Each constant is the FeedLimits member of that name.

Link copied to clipboard

The bounds a FeedParser applies to a document. Stable Core. Built with FeedLimits { maxEntries = 200 }, or derived with FeedLimits(from) { … }; every member can only be tightened: a value above its default or below its floor is refused when the limits are built, so the generous side stays the safe one and a default can be relied on as an upper bound.

Link copied to clipboard
interface FeedParser

Parses the bytes of one feed document into a Feed: the parser port of this module. RomeFeedParser is the supplied implementation on the JVM; a consumer supplies its own through FeedFetcherConfig.parser.

Link copied to clipboard

Why a document was refused before or while it was read; the reason of FeedFailure.Refused.

Link copied to clipboard
class FeedValidators(etag: String?, lastModified: String?)

The conditional-GET validators of a feed: the ETag and the Last-Modified of its last response, held verbatim. Stable Core. Store what FeedFetch.validators returns after every response and hand it back to FeedFetcher.fetch on the next poll. A value loaded from your storage is held to the same rules as one read from a response: SP and HTAB are trimmed at both ends; an empty value is null; the ETag has at most 256 and the Last-Modified at most 64 characters; every character is U+0020 to U+007E (the request type refuses anything else, so a stored non-ASCII tag would fail every later fetch); an ETag is never *. A value that breaks a rule becomes null, never truncated, and a Last-Modified is never parsed or reformatted. Equality is on both values; toString() prints whether each is present, never a value.

Link copied to clipboard

Why a document is not a feed; the reason of FeedFailure.NotAFeed.

Link copied to clipboard

The supplied FeedParser: RSS 0.90 to 2.0, RSS 1.0 and Atom 0.3 and 1.0 over Rome 2.1.0. Stable Core, usable without an opt-in; no Rome type is part of its API.

Functions

Link copied to clipboard
fun Feed(configure: Feed.Builder.() -> Unit = {}): Feed

Builds a Feed. Stable Core. The factory requires the invariants a value must hold and applies no limit and no fallback: a link, when set, is a canonical absolute link (lower-case http or https scheme, no white space, control character or backslash, no user-info, a host of letters, digits, -, ., _ or non-ASCII characters or a bracketed IPv6 literal, a port of at most 65535).

Link copied to clipboard
fun FeedEnclosure(url: String, configure: FeedEnclosure.Builder.() -> Unit = {}): FeedEnclosure

Builds a FeedEnclosure. Stable Core. The factory requires the invariants a value must hold and applies no limit and no fallback: the URL is a canonical absolute link (lower-case http or https scheme, no white space, control character or backslash, no user-info, a host of letters, digits, -, ., _ or non-ASCII characters or a bracketed IPv6 literal, a port of at most 65535).

Link copied to clipboard
fun FeedEntry(id: String, configure: FeedEntry.Builder.() -> Unit = {}): FeedEntry

Builds a FeedEntry. Stable Core. The factory requires the invariants a value must hold and applies no limit and no fallback: a link, when set, is a canonical absolute link (lower-case http or https scheme, no white space, control character or backslash, no user-info, a host of letters, digits, -, ., _ or non-ASCII characters or a bracketed IPv6 literal, a port of at most 65535).

Link copied to clipboard
fun FeedFetcher(urlFetcher: UrlFetcher, configure: FeedFetcherConfig.() -> Unit = {}): FeedFetcher

Builds a FeedFetcher over a UrlFetcher the caller owns. Stable Core. The fetcher never closes it. Share one budget by building the UrlFetcher with it.

Link copied to clipboard
fun FeedLimits(configure: FeedLimits.Builder.() -> Unit = {}): FeedLimits

Builds a FeedLimits from FeedLimits.Defaults. FeedLimits { maxEntries = 200 }; every member may only be tightened.

Builds a FeedLimits starting from from, which is never modified. A member may be raised back up to its default, never above it.

Link copied to clipboard

Builds a FeedFetcher for feed URLs an administrator supplies: an Untrusted policy (OutboundUrlPolicy.untrusted()), an owned UrlFetcher(userAgent, policy) and so an owned OkHttpTransport with a 2 MiB decoded-body cap, 3 redirects and no https-to-http hop. Stable Core. close() closes the UrlFetcher and so the transport, which cancels every request still on the network: each such fetch returns Closed("transport"). See the overload with a policy to add the deployment's own denied ranges or ports.

As the overload without a policy, for a policy of the caller's own: OutboundUrlPolicy.untrusted { extraDeniedRanges += … }. Stable Core. The transport is built with the policy's settings as they are; close() closes it as the overload without a policy does.