To create new wiki account, please join us on #znc at freenode and ask admins to create a wiki account for you. You can say thanks to spambots for this inconvenience.

Difference between revisions of "Developer:Cap"

From ZNC
Jump to navigation Jump to search
m (Its znc.in/server-time and the pull request was merged already)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
= This page is here only for historical reasons. Don't use it as a specs for the extension =
 +
Final version of the spec is here: [http://ircv3.atheme.org/specification/message-tags-3.2 Message Tags] and [http://ircv3.atheme.org/extensions/server-time-3.2 server-time]
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 
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.  
 
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 ==
 
==Background ==
Line 22: Line 42:
 
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 [http://tools.ietf.org/html/rfc1459#section-2.3.1 RFC 1459, section 2.3.1] is extended to look as follows:
 
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 [http://tools.ietf.org/html/rfc1459#section-2.3.1 RFC 1459, section 2.3.1] is extended to look as follows:
  
  <message> ::= ['@' <time> <SPACE> ] [':' <prefix> <SPACE> ] <command> <params> <crlf>
+
  <message>   ::= ['@' <line-props> <SPACE>] [':' <prefix> <SPACE> ] <command> <params> <crlf>
  <time>   ::= <A sequence of digits representing a Unix timestamp>
+
<line-props> ::= <line-prop> [',' <line-prop>]*
 +
<line-prop>  ::= <key> '=' <value>
 +
<key>        ::= 't'
 +
<value>      ::= <time>
 +
  <time>       ::= <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.  
 
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 [http://www.leeh.co.uk/draft-mitchell-irc-capabilities-02.html 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 and servers MUST conform with the [http://ircv3.atheme.org/specification/capability-negotiation-3.1 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.  
 
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 [http://tools.ietf.org/html/rfc1459 RFC 1459] is still valid with the protocol extension:  
 
Because the timestamp is optional, backwards compatibility with unsupporting servers is guaranteed. For example, the following message valid in [http://tools.ietf.org/html/rfc1459 RFC 1459] is still valid with the protocol extension:  
:Angel PRIVMSG Wiz :Hello are you receiving this message ?
+
: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:  
 
If the server were to add a timestamp to this message, it would look as follows:  
@1319042451 :Angel PRIVMSG Wiz :Hello are you receiving this message ?
+
@t=1319042451 :Angel PRIVMSG Wiz :Hello are you receiving this message ?
  
 
== Feedback and concerns ==
 
== Feedback and concerns ==
 
=== Capability name ===
 
=== 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 [http://www.leeh.co.uk/draft-mitchell-irc-capabilities-02.html IRC Client Capabilities Extension] specification.  
+
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 [http://ircv3.atheme.org/specification/capability-negotiation-3.1 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.  
 
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.  
Line 75: Line 99:
 
==Other implementations ==
 
==Other implementations ==
 
* [https://github.com/stephank/limechat/tree/server-time LimeChat branch]
 
* [https://github.com/stephank/limechat/tree/server-time LimeChat branch]
 +
* [https://github.com/kylef/Textual/compare/e9b5f548b1...1da35b99efa Textual 2.1 (kylef/future branch)]

Latest revision as of 10:09, 4 August 2012

This page is here only for historical reasons. Don't use it as a specs for the extension[edit]

Final version of the spec is here: Message Tags and server-time










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.


Background[edit]

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[edit]

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> <SPACE>] [':' <prefix> <SPACE> ] <command> <params> <crlf>
<line-props> ::= <line-prop> [',' <line-prop>]*
<line-prop>  ::= <key> '=' <value>
<key>        ::= 't'
<value>      ::= 

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[edit]

Capability name[edit]

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[edit]

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[edit]

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)

Security considerations[edit]

ZNC implementation[edit]

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[edit]