Developer:Cap

On this page we propose an extension to the IRC protocol, activated at the request of a client, which allows IRC servers to communicate time to clients in a machine readable format.

Work in progress

Background

ZNC as a bouncer has the built-in ability to log messages to buffers, even while no client is connected. When a client reconnects, these buffers are sent back to the client to give the user some chat history from while he/she was away.

The IRC protocol does not communicate time, however, and a client would typically attribute these buffered messages to the time the client received them. This will always be the time at which the client connected, rather than the actual time the message was sent.

ZNC has solved this by reformatting the actual body of messages and appending or prepending a timestamp where possible. Currently this happens for the PRIVMSG, NOTICE, and WALLOPS commands. But there are several disadvantages to this:

• The ZNC timestamp duplicates any formatting the client may do, causing two timestamps to be displayed.
• Some clients can be extended to parse the ZNC timestamp and use it for their own display, but the ZNC timestamp is only meant to be human readable. Often, timezone information and second precision are lost.
• ZNC can be configured to present time in a machine readable format, but users who mix clients won't be able to get the best experience everywhere.
• Users rely on the ZNC timezone settings to be correct, and will get incorrect time display when travelling between timezones.

Protocol extension

Clients indicate support for the extension by requesting a capability znc.in/server-time as per the IRC Client Capabilities Extension.

CAP REQ znc.in/server-time

After requesting the capability, clients MUST be able to parse an optional timestamp at the start of each message. The message pseudo-BNF, as defined in RFC 1459, section 2.3.1 is extended to look as follows:

<message>    ::= [<line-props>] [':' <prefix> <SPACE> ] <command> <params> <crlf>
<line-props> ::= '@' <line-prop> [',' <line-prop>]*
<line-prop>  ::= <key> '=' <value>
<key>        ::= 't'
<value>      ::= 
       ::= <A sequence of digits representing a Unix timestamp>

The timestamp is a Unix timestamp specifying the seconds since the epoch (1970-01-01 00:00:00 +0000 UTC), as specified by POSIX.1. As explained there, this is NOT the actual number of seconds since that time since e.g. leap seconds are ignored and simplified rules for leap years are used. See POSIX.1 Annex B 2.2.2.

Clients and servers MUST conform with the IRC Client Capabilities Extension specification. Servers MAY include the timestamp in messages when they see fit, but MUST NOT do so before acknowledging the client capability using CAP ACK. Clients MAY choose to simplify parsing by accepting timestamps at any point in the connection.

Clients MUST NOT send timestamps, and a server receiving a message including a timestamp from a client SHOULD treat it as a protocol error.

Because the timestamp is optional, backwards compatibility with unsupporting servers is guaranteed. For example, the following message valid in RFC 1459 is still valid with the protocol extension:

:Angel PRIVMSG Wiz :Hello are you receiving this message ?

If the server were to add a timestamp to this message, it would look as follows:

@t=1319042451 :Angel PRIVMSG Wiz :Hello are you receiving this message ?

Feedback and concerns

Capability name

When the pull request was created, concerns were raised about the name of the capability in a znc.in private namespace. This was done in accordance with the IRC Client Capabilities Extension specification.

The counter argument is that very few capabilities in the wild follow the naming conventions in the specification. On top of that, it is supposed to be required to standardize extensions in the 'global' namespace, but the specification itself is still only a draft.

• Maybe we can approach other BNC teams with similar functionality and see if they're interested in implementing this? Given the counter argument, I think we're reasonably safe just dropping the znc.in namespace if we get one other bouncer or IRCd on board. -- Kosinus (talk)

Messages affected

In theory, all messages can be tagged with a timestamp. In fact, this makes perfect sense if the extension were implemented in an IRCd.

The original motivation was for ZNC to be able to communicate accurate time for messages received in the past, and stored in a buffer. The current ZNC implementation limits its scope to these buffer messages. Messages received by ZNC and immediately forwarded to its clients do not have a timestamp.

• What are the benefits of implementing this in an IRCd, when an IRCd is only concerned with 'now'? Are there other use-cases for adding timestamps? -- Kosinus (talk)
• I've disallowed clients from sending timestamps. However, I wonder if there'd be a use for that? Perhaps, if there is, it could be added as a separate capability client-time. -- Kosinus (talk)

Message truncating

The IRC line length limit is 510, excluding the CRLF. A server adding a timestamp to the message must truncate the message to fit this limit, or internally extend the limit.

ZNC extends the limit, and in practice truncating will be rare. For that matter, the same problem already existed with the existing timestamp implementation.

• How do IRCds deal with prefixing in general? This situation already occurs when prepending the :prefix part to a message before forwarding. -- Kosinus (talk)

Line properties

If the line has several properties, not only server-time, but also "x", how it should look like?

@t=1234,x=yyy :foo PRIVMSG bar :hi

or

@t=1234 @x=yyy :foo PRIVMSG bar :hi

ZNC implementation

This is supported in the latest git version of ZNC. When requested, ZNC disables the regular reformatting of text to prepend or append timestamps, and instead adds the Unix timestamps using the protocol extension explained above.

The normal timestamps ZNC has always added were already implemented for PRIVMSGs, including ACTIONs, NOTICEs and WALLOPS. Users of clients without the capability will see these timestamps in the same way they always have.

The capability-based timestamps cover all those cases and more, basically all messages that are stored in a buffer. In practice the additional messages covered are the MOTD, and certain raw replies from the server.

Other implementations

• LimeChat branch
• Textual 2.1 (kylef/future branch)