Last modified Information Relaying Specification (LIRS) 2.1

Creation date: 1999-10-13 18:00
Update date: 2001-12-16 22:48

This document is an unofficial English translation of the original Japanese specification made by someone who has no knowledge of Japanese. Implement at your own risk.

About LIRS

LIRS is designed to include the minimal necessary information for update time acquisition agents (antennas). It assumes that a site that provides update times should not be burdened with anything other than reporting update times. It also assumes that the sites all run on UNIX environments.

The person exclusively responsible for changes to this specification is Hiya (hiya@haun.org).

Format

An LIRS file is a text file compressed using gzip.
The text is encoded using EUC-JP and consists in a series of records.
A record starts with LIRS,, followed by a data part, and ends with a comma and LF or CRLF.
LF is recommended, and CR alone is prohibited.
Lines that begin with # are comments and should be ignored.
The data part of a record consists in a series of fields separated by commas (,).
Field values must not include the CR or LF characters, or unescaped commas.
All dates are expressed as Unix timestamps: seconds from 1970-01-01T00:00:00Z.
With the exception of the extension field, blank fields should be represented as a zero (0).

Escaping

The backslash character (\) is the escape character. Commas in fields should be escaped (\,). A literal backslash can be inserted using two backslashes (\\).

Fields

The following fields should appear in all records, in this order:

Last-Modified
Last-Detected
Time difference
Content-Length
URL
Title
Author name
Source URL
Extension

Last-Modified

Timestamp of when the target site was last updated.

Should the last update detection fail, the LIRS provider should set this field to zero, and antenna agents should assume this record is unusable.

Last-Detected

Timestamp of when the LIRS provider last checked for the last update time for this site. This defines a notion of “freshness” that antenna agents can use to sort records by priority, or discard old records.

Should the last update detection fail, the LIRS provider should set this field to zero, and antenna agents should assume this record is unusable.

Time difference

Signed integer. Difference, in seconds, between GMT and the timezone of the target site; 32400 or +32400 in Japan. Since update times are reported in GMT, this allows sharing the timezone of the target site.

Content-Length

Size of the content served at the target URL, in bytes. LIRS providers that check the target site, and do not have more internal ways to detect an update, should consider a change in the Content-Length to be an update.

URL

URL of the target site. This field must be unique; a single URL must not be repeated twice in the same LIRS file. This field can be used as a unique identifier by antenna implementations.

Title

Title of the content served at the target site; usually the contents of the HTML <title> tag.

Author name

Name of the author of the content served at this URL.

Source URL

URL that was used by the LIRS provider to acquire update information. This is usually the same as the URL; in case of an implementation that aggregates update information from other LIRS providers, this could be the URL of each LIRS file. How to use this field is left to the implementor.

Extension

Arbitrary string for agent-specific information. Instead of 0 as the default for a blank field, this should be left empty.

Best practices

LIRS files should be cached, not generated dynamically.
LIRS implementations should automatically discard records that were last detected more than 28800 seconds (8 hours) ago.

Example

This is a single LIRS record, uncompressed:

LIRS,938779260,938781002,32400,49383,http://hiya.ouchi.to/n/,Tadayo Memories,Hiya,http://amano.hauN.org/,blah blah,\r\n

This translates to the following fields:

Title: Tadayo Memories
Author: Hiya
Site URL: http://hiya.ouchi.to/n/
Last modified: 1999-10-01T14:01:00Z
Last detected: 1999-10-01T14:30:02Z
Server timezone: UTC+9 (32400 seconds)
Source: http://amano.hauN.org/
Custom data: blah blah

Changelog

2001-12-16 22:48: Added a link to the Meta::LIRS Perl module
2000-10-25 14:36: Fixed an error in the description of the URL field.
2000-10-13 15:20: Fixed an error in the usage of gzip in LIRS.pm.
2000-06-23 13:52: Added details about handling line feeds (\015, \012).
2000-06-16 13:47: Added a link to lirs.rb.
2000-05-31 20:00: Backslashes should now be escaped too (\\).; Minor corrections due to changes in LIRS.pm.
1999-11-11 19:41: Document converted to HTML, and minor corrections.
1999-11-03 03:25: Minor corrections after a discussion about DI.; Added the About LIRS section.
1999-10-13 18:00: Initial version.

Generated on 2024-04-02T12:19:24+02:00 using pandoc 2.9.2.1