lektor

Lektor: A Standard for Feed Readers

NOTE: The entirety of this file is tentative, and subject to change at any time.

There are two main tasks for a feed reader: fetching and viewing. These two tasks, in the lektor system, are split apart into different components, mediated by a lektordir system. There are two main parts to the lektor architecture: the lektor-dir format and the lektor-entry format.

lektor-feed

A given feed consists of at least a name (which is human-readable) and an id which unambiguously identifies the feed (which is a URI). Information about feeds is stored in the src directory inside a lektor-dir. Information about a given feed is stored inside src/$hash, where $hash is the SHA-1 hash of of the feed's id.

Obligatory elements include:

• id: The URI which identifies the feed. In the case of RSS/Atom/ActivityStream feeds, this will generally be the URL at which the feed is hosted. For other things—for example, for services which may not have a web equivalent—it might instead be a tag URI or some other opaque identifier.
• name: The human-readable name of the feed. This is produced by the fetcher and should not be changed by a viewer.

Optional elements include:

• description: A human-readable description describing the feed.
• language: The language the feed is written in.
• image: An image that can be optionally displayed with the channel.
• copyright: The copyright notice for the feed.
• author: Authorship information for the feed.

Feed example

A minimal feed might look like

cd $LEKTORDIR
HASH=$(printf 'http://example.com/rss.xml' | sha1sum)
mkdir -p $HASH

echo http://example.com/rss.xml  >$HASH/id
echo Example Feed                >$HASH/name

A feed with more entries might look like

cd $LEKTORDIR
HASH=$(printf 'http://example.com/rss.xml' | sha1sum)
mkdir -p $HASH

echo http://example.com/rss.xml           >$HASH/id
echo Example Feed                         >$HASH/name
echo 'An example feed.'                   >$HASH/description
echo en-us                                >$HASH/language
echo http://example.com/image.png         >$HASH/image
echo Copyright 2015, Getty Ritter         >$HASH/copyright
echo 'Getty Ritter <gdritter@gmail.com>'  >$HASH/author

lektor-entry

In contrast to maildir, entries in a lektor-dir are not files but directories adhering to a particular structure.

Obligatory elements include:

• title: The title of the entry.
• id: The URI which identifies the entry. This will often be a URL at which the resource corresponding to the entry is available, but may also be an opaque identifier.
• content: TBD
• feed: A directory that contains all the information about the source feed. This will generally be a symlink

Optional elements include:

• author: Names and email addressess of the authors of the entry.
• pubdate: When the entry was published.

lektor-dir

A lektordir is a directory with at least four subdirectories: tmp, new, cur, and src. A fetcher is responsible for examining a feed and adding new entries the lektordir according to the following process:

• The fetcher chdir()s to the lektordir directory.
• The fetcher stat()s the name tmp/$feed/$time.$pid.$host, where $feed is the hash of the feed's id value, $time is the number of seconds since the beginning of 1970 GMT, $pid is the program's process ID, and $host is its host name.
• If stat() returned anything other than ENOENT, the program sleeps for two seconds, updates $time, and tries the stat() again, a limited number of times.
• The fetcher creates the directory tmp/$feed/$time.$pid.$host.
• The fetcher writes the entry contents (according to the lektor-entry format) to the directory.
• The fetcher link()s the file to new/$feed/$time.$pid.$host. At that instant, the entry has been successfully created.

A viewer is responsible for displaying new feed entries to a user through some mechanism. A viewer looks through the new directory for new entries. If there is a new entry, new/$feed/$unique, the viewer may:

• Display the contents of new/$feed/$unique
• Delete new/$feed/$unique
• Rename new/$feed/$unique.

A lektordir can contain arbitrary other directories, but for the sake of compatibility, these should attempt to adhere to the following schema:

• If the extra directory contains configuration or other information for a given feed, it