From d572c78f3fc29affda8e7b608a6a7eb2d94334ff Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Mon, 2 Jan 2017 17:41:48 -0500 Subject: [PATCH 01/27] Add scrollback batch type --- extensions/batch/scrollback-3.3.md | 84 ++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 extensions/batch/scrollback-3.3.md diff --git a/extensions/batch/scrollback-3.3.md b/extensions/batch/scrollback-3.3.md new file mode 100644 index 000000000..eb30d0da9 --- /dev/null +++ b/extensions/batch/scrollback-3.3.md @@ -0,0 +1,84 @@ +--- +title: IRCv3 scrollback Batch Type +layout: spec +work-in-progress: true +copyrights: + - + name: "Evan Magaliff" + period: "2016" + email: "evan@muffinmedic.net" +--- +## Description +### `scrollback` Batch Type +This document describes the format of the `scrollback` batch type. The `scrollback` batch type is an extension of the `chathistory` batch type, adding additional IRC events to it's output and implementing a client-side command for requesting scrollback content from the server. + +The `scrollback` batch type takes a single target parameter, which must be either a channel or query name. + +Client side support for the [`batch`][batch], [`server-time`][server-time], and [`draft/msgid`](https://github.com/ircv3/ircv3-specifications/pull/285) capabilities is required. + +When a client with the above mentioned capabilities requests scrollback content from the server (using the `scrollback` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, beginning with the first message previous to the last-known timestamp. The raw IRC lines are to be formatted and returned to the client as they would be originally, with the addition of the above capability tags. + +The `server-time` should be the time at which the message was originally sent, the `batch id` a randomly generated string unique to the entire batch, and the `draft/msgid` a unique identifier for each message. + +### `scrollback` Command +Scrollback content can be requested by the client to the server by sending the `SCROLLBACK` command to the server. No acknowledgement by the server of the command is required other then returning the requested content. + +#### Format + SCROLLBACK target YYYY-MM-DDThh:mm:ss.sssZ message_count + SCROLLBACK #channel 2016-11-19T18:02:01.000Z 50 + +If no message_count is known, `*` can be used as default + +## Examples + +### Begin + :irc.host BATCH +ID muffinmedic.net/scrollback target + :irc.host BATCH +XNyDSitp9MvcX scrollback #channel +### PRIVMSG + @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PRIVMSG target :message + @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:01.001Z :foo!bar@example.com PRIVMSG #channel :The ZNC SCROLLBACK command is going to be fantastic! +### NOTICE + @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host NTOICE target :message + @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:02.002Z :foo!bar@example.com NOTICE #channel :Announcing the new ZNC SCROLLBACK command! +### JOIN + @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host JOIN :#channel + @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:03.003Z :foo!bar@example.com JOIN :#channel +### PART + @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PART #channel :reason + @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:04.004Z :foo!bar@example.com PART #channel :This place is too addicting +### QUIT + @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host QUIT #channel :reason + @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:05.005Z :foo!bar@example.com QUIT #channel :Restarting in debug mode +### KICK + @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :op_nick!ident@host KICK #channel kicked_nick :message + @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:06.006Z :foo!bar@example.com KICK #channel CupcakeMedic :Muffins > cupcakes +### NICK + @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :old_nick!ident@host NICK :new_nick + @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:07.007Z :foo!bar@example.com NICK :Evan +### TOPIC + @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host TOPIC #channel :topic + @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:08.008Z :foo!bar@example.com TOPIC #channel :Check out the new ZNC SCROLLBACK command +### MODE + @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :op_nick!ident@host MODE #channel mode(s) parameter(s) + @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:09.009Z :foo!bar@example.com MODE #channel +b *!*@example.com +### End + :irc.host BATCH -ID + :irc.host BATCH -XNyDSitp9MvcX + +## Use cases +The batch type and supporting command are useful for allowing an "infinite scroll" type capability within the client itself. A client will, upon scrolling to the top of the active window, request scrollback from the server and, upon receiving such content, append it to the top of the window. Users can repeat this historic scrolling to retrieve prior history until limitations are met (see below). + +## Limitations +Logging of messages and other actions must be enabled server-side and can be stored in any format desired, given appropriate software exists to retrieve and format such stored contnet. Scrollback can only be retrieved as far back as logs exist for the requesting user in the specified channel or query. + +A method for securely identifying the requesting user must exist to ensure content is sent only to the appropriate users and clients. See below for more information. + +## Security considerations +Secure identification of users and clients must exist in order to ensure that users cannot obtain history that does not belong to them. Use of account names, internal account identifiers, or certificate fingerprints should be strongly considered when matching content to users. The server must verify the current user's identity matches that of the desired content. This information is not sent as part of the `SCROLLBACK` command and must be validated via other means, such as those stated above. + +## Current Implementations +A ZNC-module implementation exists as [znc-scrollback](https://github.com/MuffinMedic/znc-scrollback). Client-side support for the ZNC module is in progress. Interest in supporting the batch type and command without ZNC has also been obtained, although specifics are not available at this time. + +[batch]: ../batch-3.2.html +[chathistory]: chathistory-3.3.html +[server-time]: ../server-time-3.2.html From ff83973ae01c649bc3896ab7fe1c1c357424dfff Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Mon, 2 Jan 2017 17:45:15 -0500 Subject: [PATCH 02/27] Update copyright year --- extensions/batch/scrollback-3.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/batch/scrollback-3.3.md b/extensions/batch/scrollback-3.3.md index eb30d0da9..652c17253 100644 --- a/extensions/batch/scrollback-3.3.md +++ b/extensions/batch/scrollback-3.3.md @@ -5,7 +5,7 @@ work-in-progress: true copyrights: - name: "Evan Magaliff" - period: "2016" + period: "2017" email: "evan@muffinmedic.net" --- ## Description From 25c7e8dc4b0b19cc40fdbc351c7349ae61e58e9a Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Mon, 2 Jan 2017 17:53:09 -0500 Subject: [PATCH 03/27] Add RPL_ISUPPORT 005 to command specification --- extensions/batch/scrollback-3.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/batch/scrollback-3.3.md b/extensions/batch/scrollback-3.3.md index 652c17253..15f8e0583 100644 --- a/extensions/batch/scrollback-3.3.md +++ b/extensions/batch/scrollback-3.3.md @@ -21,7 +21,7 @@ When a client with the above mentioned capabilities requests scrollback content The `server-time` should be the time at which the message was originally sent, the `batch id` a randomly generated string unique to the entire batch, and the `draft/msgid` a unique identifier for each message. ### `scrollback` Command -Scrollback content can be requested by the client to the server by sending the `SCROLLBACK` command to the server. No acknowledgement by the server of the command is required other then returning the requested content. +Scrollback content can be requested by the client to the server by sending the `SCROLLBACK` command to the server. No acknowledgement by the server of the command is required other then returning the requested content. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick SCROLLBACK :are supported by this server` #### Format SCROLLBACK target YYYY-MM-DDThh:mm:ss.sssZ message_count From 577d9c5ef582f5ac6cdf9ff315067bb950fc9a86 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Mon, 2 Jan 2017 19:56:36 -0500 Subject: [PATCH 04/27] Add draft/msgid support to scrollback command --- extensions/batch/scrollback-3.3.md | 43 ++++++++++++++++-------------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/extensions/batch/scrollback-3.3.md b/extensions/batch/scrollback-3.3.md index 15f8e0583..65a94b041 100644 --- a/extensions/batch/scrollback-3.3.md +++ b/extensions/batch/scrollback-3.3.md @@ -16,16 +16,19 @@ The `scrollback` batch type takes a single target parameter, which must be eithe Client side support for the [`batch`][batch], [`server-time`][server-time], and [`draft/msgid`](https://github.com/ircv3/ircv3-specifications/pull/285) capabilities is required. -When a client with the above mentioned capabilities requests scrollback content from the server (using the `scrollback` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, beginning with the first message previous to the last-known timestamp. The raw IRC lines are to be formatted and returned to the client as they would be originally, with the addition of the above capability tags. +When a client with the above mentioned capabilities requests scrollback content from the server (using the `scrollback` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines are to be formatted and returned to the client as they would be originally, with the addition of the above capability tags. The `server-time` should be the time at which the message was originally sent, the `batch id` a randomly generated string unique to the entire batch, and the `draft/msgid` a unique identifier for each message. ### `scrollback` Command -Scrollback content can be requested by the client to the server by sending the `SCROLLBACK` command to the server. No acknowledgement by the server of the command is required other then returning the requested content. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick SCROLLBACK :are supported by this server` +Scrollback content can be requested by the client to the server by sending the `SCROLLBACK` command to the server. No acknowledgement by the server of the command is required other then returning the requested content. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick SCROLLBACK :are supported by this server` #### Format - SCROLLBACK target YYYY-MM-DDThh:mm:ss.sssZ message_count - SCROLLBACK #channel 2016-11-19T18:02:01.000Z 50 + SCROLLBACK target timestamp=YYYY-MM-DDThh:mm:ss.sssZ message_count + SCROLLBACK #channel timestamp=2016-11-19T18:02:01.000Z 50 + + SCROLLBACK target draft/msgid=ID message_count + SCROLLBACK #channel draft/msgid=774ba1b6-202b-448c-b23a-6150ce5681fd 50 If no message_count is known, `*` can be used as default @@ -36,31 +39,31 @@ If no message_count is known, `*` can be used as default :irc.host BATCH +XNyDSitp9MvcX scrollback #channel ### PRIVMSG @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PRIVMSG target :message - @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:01.001Z :foo!bar@example.com PRIVMSG #channel :The ZNC SCROLLBACK command is going to be fantastic! + @batch=XNyDSitp9MvcX;draft/msgid=eb703092-0782-4c28-bf7c-f9e5c45963ca;time=2016-11-19T18:02:01.001Z :foo!bar@example.com PRIVMSG #channel :The ZNC SCROLLBACK command is going to be fantastic! ### NOTICE @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host NTOICE target :message - @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:02.002Z :foo!bar@example.com NOTICE #channel :Announcing the new ZNC SCROLLBACK command! + @batch=XNyDSitp9MvcX;draft/msgid=cb302078-ce4e-4866-82b8-480ec58094b3;time=2016-11-19T18:02:02.002Z :foo!bar@example.com NOTICE #channel :Announcing the new ZNC SCROLLBACK command! ### JOIN - @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host JOIN :#channel - @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:03.003Z :foo!bar@example.com JOIN :#channel + @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host JOIN :#channel + @batch=XNyDSitp9MvcX;draft/msgid=8c878e54-465c-41ec-b9d7-764efdce21cb;time=2016-11-19T18:02:03.003Z :foo!bar@example.com JOIN :#channel ### PART - @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PART #channel :reason - @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:04.004Z :foo!bar@example.com PART #channel :This place is too addicting + @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PART #channel :reason + @batch=XNyDSitp9MvcX;draft/msgid=03b89bc0-ad61-464e-9ab7-9b09fc2c20c3;time=2016-11-19T18:02:04.004Z :foo!bar@example.com PART #channel :This place is too addicting ### QUIT - @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host QUIT #channel :reason - @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:05.005Z :foo!bar@example.com QUIT #channel :Restarting in debug mode + @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host QUIT #channel :reason + @batch=XNyDSitp9MvcX;draft/msgid=fd705235-2de7-4b5b-9346-dbedfcd317ee;time=2016-11-19T18:02:05.005Z :foo!bar@example.com QUIT #channel :Restarting in debug mode ### KICK - @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :op_nick!ident@host KICK #channel kicked_nick :message - @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:06.006Z :foo!bar@example.com KICK #channel CupcakeMedic :Muffins > cupcakes + @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :op_nick!ident@host KICK #channel kicked_nick :message + @batch=XNyDSitp9MvcX;draft/msgid=4fb49dea-1138-4522-b17a-19b084a2efb9;time=2016-11-19T18:02:06.006Z :foo!bar@example.com KICK #channel CupcakeMedic :Muffins > cupcakes ### NICK - @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :old_nick!ident@host NICK :new_nick - @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:07.007Z :foo!bar@example.com NICK :Evan + @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :old_nick!ident@host NICK :new_nick + @batch=XNyDSitp9MvcX;draft/msgid=d7315ace-fcac-4f79-bcfe-476b63bf8b4d;time=2016-11-19T18:02:07.007Z :foo!bar@example.com NICK :Evan ### TOPIC - @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host TOPIC #channel :topic - @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:08.008Z :foo!bar@example.com TOPIC #channel :Check out the new ZNC SCROLLBACK command + @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host TOPIC #channel :topic + @batch=XNyDSitp9MvcX;draft/msgid=f9187528-c7ec-4233-b8ce-4d02f4ba9c12;time=2016-11-19T18:02:08.008Z :foo!bar@example.com TOPIC #channel :Check out the new ZNC SCROLLBACK command ### MODE - @batch=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :op_nick!ident@host MODE #channel mode(s) parameter(s) - @batch=XNyDSitp9MvcX;draft/msgid=;time=2016-11-19T18:02:09.009Z :foo!bar@example.com MODE #channel +b *!*@example.com + @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :op_nick!ident@host MODE #channel mode(s) parameter(s) + @batch=XNyDSitp9MvcX;draft/msgid=8460bc16-bfab-452a-8343-274222a09a0c;time=2016-11-19T18:02:09.009Z :foo!bar@example.com MODE #channel +b *!*@example.com ### End :irc.host BATCH -ID :irc.host BATCH -XNyDSitp9MvcX From e2d46f5126aa2a1e63508347c1ab26d87d204f52 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Mon, 2 Jan 2017 20:02:43 -0500 Subject: [PATCH 05/27] Require batch reply --- extensions/batch/scrollback-3.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/batch/scrollback-3.3.md b/extensions/batch/scrollback-3.3.md index 65a94b041..5ba037849 100644 --- a/extensions/batch/scrollback-3.3.md +++ b/extensions/batch/scrollback-3.3.md @@ -21,7 +21,7 @@ When a client with the above mentioned capabilities requests scrollback content The `server-time` should be the time at which the message was originally sent, the `batch id` a randomly generated string unique to the entire batch, and the `draft/msgid` a unique identifier for each message. ### `scrollback` Command -Scrollback content can be requested by the client to the server by sending the `SCROLLBACK` command to the server. No acknowledgement by the server of the command is required other then returning the requested content. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick SCROLLBACK :are supported by this server` +Scrollback content can be requested by the client to the server by sending the `SCROLLBACK` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be set to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick SCROLLBACK :are supported by this server` #### Format SCROLLBACK target timestamp=YYYY-MM-DDThh:mm:ss.sssZ message_count From 3871fa590d55fff522d819655dcdf488a321a801 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Mon, 2 Jan 2017 20:32:28 -0500 Subject: [PATCH 06/27] Make draft/msgid optional --- extensions/batch/scrollback-3.3.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/extensions/batch/scrollback-3.3.md b/extensions/batch/scrollback-3.3.md index 5ba037849..e7fe91fa6 100644 --- a/extensions/batch/scrollback-3.3.md +++ b/extensions/batch/scrollback-3.3.md @@ -14,11 +14,11 @@ This document describes the format of the `scrollback` batch type. The `scrollba The `scrollback` batch type takes a single target parameter, which must be either a channel or query name. -Client side support for the [`batch`][batch], [`server-time`][server-time], and [`draft/msgid`](https://github.com/ircv3/ircv3-specifications/pull/285) capabilities is required. +Client side support for the [`batch`][batch] and [`server-time`][server-time] capabilities is required. Support for the [`draft/msgid`](https://github.com/ircv3/ircv3-specifications/pull/285) capability is optional but recommended. When a client with the above mentioned capabilities requests scrollback content from the server (using the `scrollback` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines are to be formatted and returned to the client as they would be originally, with the addition of the above capability tags. -The `server-time` should be the time at which the message was originally sent, the `batch id` a randomly generated string unique to the entire batch, and the `draft/msgid` a unique identifier for each message. +The `server-time` should be the time at which the message was originally sent, the `batch id` a randomly generated string unique to the entire batch, and the optional `draft/msgid`, if included, the `draft/msgid` originally sent with the message. ### `scrollback` Command Scrollback content can be requested by the client to the server by sending the `SCROLLBACK` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be set to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick SCROLLBACK :are supported by this server` @@ -33,6 +33,7 @@ Scrollback content can be requested by the client to the server by sending the ` If no message_count is known, `*` can be used as default ## Examples +The examples below are written with `draft/msgid` tags included. This tag is optional and can be excluded if desired. ### Begin :irc.host BATCH +ID muffinmedic.net/scrollback target From ff2ef808f72c6203444dc5c4d16c9059349d0c3c Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Mon, 2 Jan 2017 21:27:30 -0500 Subject: [PATCH 07/27] Reimplement extension using chathistory batch type --- extensions/{batch => }/scrollback-3.3.md | 54 ++++++++---------------- 1 file changed, 18 insertions(+), 36 deletions(-) rename extensions/{batch => }/scrollback-3.3.md (54%) diff --git a/extensions/batch/scrollback-3.3.md b/extensions/scrollback-3.3.md similarity index 54% rename from extensions/batch/scrollback-3.3.md rename to extensions/scrollback-3.3.md index e7fe91fa6..a78e1c3b5 100644 --- a/extensions/batch/scrollback-3.3.md +++ b/extensions/scrollback-3.3.md @@ -1,5 +1,5 @@ --- -title: IRCv3 scrollback Batch Type +title: IRCv3 scrollback extension layout: spec work-in-progress: true copyrights: @@ -9,62 +9,44 @@ copyrights: email: "evan@muffinmedic.net" --- ## Description -### `scrollback` Batch Type -This document describes the format of the `scrollback` batch type. The `scrollback` batch type is an extension of the `chathistory` batch type, adding additional IRC events to it's output and implementing a client-side command for requesting scrollback content from the server. +This document describes the format of the `scrollback` extension. The `scrollback` extension uses the `chathistory` batch type, adding a client-side command for requesting scrollback content from the server. -The `scrollback` batch type takes a single target parameter, which must be either a channel or query name. +The `scrollback` extensions adds an optional `draft/msgid` to the `chathistory` batch reply. Client side support for the [`batch`][batch] and [`server-time`][server-time] capabilities is required. Support for the [`draft/msgid`](https://github.com/ircv3/ircv3-specifications/pull/285) capability is optional but recommended. -When a client with the above mentioned capabilities requests scrollback content from the server (using the `scrollback` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines are to be formatted and returned to the client as they would be originally, with the addition of the above capability tags. +When a client with the above mentioned capabilities requests scrollback content from the server (using the `SCROLLBACK` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. The `server-time` should be the time at which the message was originally sent, the `batch id` a randomly generated string unique to the entire batch, and the optional `draft/msgid`, if included, the `draft/msgid` originally sent with the message. -### `scrollback` Command -Scrollback content can be requested by the client to the server by sending the `SCROLLBACK` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be set to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick SCROLLBACK :are supported by this server` +### `SCROLLBACK` Command +Scrollback content can be requested by the client to the server by sending the `SCROLLBACK` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick SCROLLBACK :are supported by this server` #### Format +The `scrollback` content can requested using timestamps: + SCROLLBACK target timestamp=YYYY-MM-DDThh:mm:ss.sssZ message_count SCROLLBACK #channel timestamp=2016-11-19T18:02:01.000Z 50 +Alternatively, content can be requested using a `draft/msgid`: + SCROLLBACK target draft/msgid=ID message_count SCROLLBACK #channel draft/msgid=774ba1b6-202b-448c-b23a-6150ce5681fd 50 -If no message_count is known, `*` can be used as default +If no message_count is known, `*` should be used to specify the default value. ## Examples -The examples below are written with `draft/msgid` tags included. This tag is optional and can be excluded if desired. +The examples below are written with `draft/msgid` tags included. This tag is optional but recommended. ### Begin - :irc.host BATCH +ID muffinmedic.net/scrollback target + :irc.host BATCH +ID chathistory target :irc.host BATCH +XNyDSitp9MvcX scrollback #channel ### PRIVMSG @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PRIVMSG target :message - @batch=XNyDSitp9MvcX;draft/msgid=eb703092-0782-4c28-bf7c-f9e5c45963ca;time=2016-11-19T18:02:01.001Z :foo!bar@example.com PRIVMSG #channel :The ZNC SCROLLBACK command is going to be fantastic! + @batch=XNyDSitp9MvcX;draft/msgid=eb703092-0782-4c28-bf7c-f9e5c45963ca;time=2016-11-19T18:02:01.001Z :foo!bar@example.com PRIVMSG #channel :The SCROLLBACK specification is going to be fantastic! ### NOTICE @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host NTOICE target :message - @batch=XNyDSitp9MvcX;draft/msgid=cb302078-ce4e-4866-82b8-480ec58094b3;time=2016-11-19T18:02:02.002Z :foo!bar@example.com NOTICE #channel :Announcing the new ZNC SCROLLBACK command! -### JOIN - @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host JOIN :#channel - @batch=XNyDSitp9MvcX;draft/msgid=8c878e54-465c-41ec-b9d7-764efdce21cb;time=2016-11-19T18:02:03.003Z :foo!bar@example.com JOIN :#channel -### PART - @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PART #channel :reason - @batch=XNyDSitp9MvcX;draft/msgid=03b89bc0-ad61-464e-9ab7-9b09fc2c20c3;time=2016-11-19T18:02:04.004Z :foo!bar@example.com PART #channel :This place is too addicting -### QUIT - @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host QUIT #channel :reason - @batch=XNyDSitp9MvcX;draft/msgid=fd705235-2de7-4b5b-9346-dbedfcd317ee;time=2016-11-19T18:02:05.005Z :foo!bar@example.com QUIT #channel :Restarting in debug mode -### KICK - @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :op_nick!ident@host KICK #channel kicked_nick :message - @batch=XNyDSitp9MvcX;draft/msgid=4fb49dea-1138-4522-b17a-19b084a2efb9;time=2016-11-19T18:02:06.006Z :foo!bar@example.com KICK #channel CupcakeMedic :Muffins > cupcakes -### NICK - @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :old_nick!ident@host NICK :new_nick - @batch=XNyDSitp9MvcX;draft/msgid=d7315ace-fcac-4f79-bcfe-476b63bf8b4d;time=2016-11-19T18:02:07.007Z :foo!bar@example.com NICK :Evan -### TOPIC - @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host TOPIC #channel :topic - @batch=XNyDSitp9MvcX;draft/msgid=f9187528-c7ec-4233-b8ce-4d02f4ba9c12;time=2016-11-19T18:02:08.008Z :foo!bar@example.com TOPIC #channel :Check out the new ZNC SCROLLBACK command -### MODE - @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :op_nick!ident@host MODE #channel mode(s) parameter(s) - @batch=XNyDSitp9MvcX;draft/msgid=8460bc16-bfab-452a-8343-274222a09a0c;time=2016-11-19T18:02:09.009Z :foo!bar@example.com MODE #channel +b *!*@example.com + @batch=XNyDSitp9MvcX;draft/msgid=cb302078-ce4e-4866-82b8-480ec58094b3;time=2016-11-19T18:02:02.002Z :foo!bar@example.com NOTICE #channel :Announcing the new IRCv3 SCROLLBACK extension draft! ### End :irc.host BATCH -ID :irc.host BATCH -XNyDSitp9MvcX @@ -83,6 +65,6 @@ Secure identification of users and clients must exist in order to ensure that us ## Current Implementations A ZNC-module implementation exists as [znc-scrollback](https://github.com/MuffinMedic/znc-scrollback). Client-side support for the ZNC module is in progress. Interest in supporting the batch type and command without ZNC has also been obtained, although specifics are not available at this time. -[batch]: ../batch-3.2.html -[chathistory]: chathistory-3.3.html -[server-time]: ../server-time-3.2.html +[batch]: batch-3.2.html +[chathistory]: batch/chathistory-3.3.html +[server-time]: server-time-3.2.html From 8ae7bf9a4ac611ec1b2bfcea92d535ac683ec198 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Mon, 2 Jan 2017 21:29:52 -0500 Subject: [PATCH 08/27] Update URLs --- extensions/scrollback-3.3.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/extensions/scrollback-3.3.md b/extensions/scrollback-3.3.md index a78e1c3b5..3b4acb78c 100644 --- a/extensions/scrollback-3.3.md +++ b/extensions/scrollback-3.3.md @@ -65,6 +65,6 @@ Secure identification of users and clients must exist in order to ensure that us ## Current Implementations A ZNC-module implementation exists as [znc-scrollback](https://github.com/MuffinMedic/znc-scrollback). Client-side support for the ZNC module is in progress. Interest in supporting the batch type and command without ZNC has also been obtained, although specifics are not available at this time. -[batch]: batch-3.2.html -[chathistory]: batch/chathistory-3.3.html -[server-time]: server-time-3.2.html +[batch]: batch-3.2.md +[chathistory]: batch/chathistory-3.3.md +[server-time]: server-time-3.2.md From d26104693229f3272c037bf0e88f5b9dd2c7b504 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Tue, 3 Jan 2017 01:22:11 -0500 Subject: [PATCH 09/27] Rename scrollback to chathistory for consistency --- .../{scrollback-3.3.md => chathistory-3.3.md} | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) rename extensions/{scrollback-3.3.md => chathistory-3.3.md} (50%) diff --git a/extensions/scrollback-3.3.md b/extensions/chathistory-3.3.md similarity index 50% rename from extensions/scrollback-3.3.md rename to extensions/chathistory-3.3.md index 3b4acb78c..d38ebdf4b 100644 --- a/extensions/scrollback-3.3.md +++ b/extensions/chathistory-3.3.md @@ -1,5 +1,5 @@ --- -title: IRCv3 scrollback extension +title: IRCv3 chathistory extension layout: spec work-in-progress: true copyrights: @@ -9,29 +9,29 @@ copyrights: email: "evan@muffinmedic.net" --- ## Description -This document describes the format of the `scrollback` extension. The `scrollback` extension uses the `chathistory` batch type, adding a client-side command for requesting scrollback content from the server. +This document describes the format of the `chathistory` extension. The `chathistory` extension uses the `chathistory` batch type, adding a client-side command for requesting chathistory content from the server. -The `scrollback` extensions adds an optional `draft/msgid` to the `chathistory` batch reply. +The `chathistory` extension adds an optional `draft/msgid` to the `chathistory` batch reply. Client side support for the [`batch`][batch] and [`server-time`][server-time] capabilities is required. Support for the [`draft/msgid`](https://github.com/ircv3/ircv3-specifications/pull/285) capability is optional but recommended. -When a client with the above mentioned capabilities requests scrollback content from the server (using the `SCROLLBACK` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. +When a client with the above mentioned capabilities requests chathistory content from the server (using the `CHATHISTORY` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. The `server-time` should be the time at which the message was originally sent, the `batch id` a randomly generated string unique to the entire batch, and the optional `draft/msgid`, if included, the `draft/msgid` originally sent with the message. -### `SCROLLBACK` Command -Scrollback content can be requested by the client to the server by sending the `SCROLLBACK` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick SCROLLBACK :are supported by this server` +### `CHATHISTORY` Command +Scrollback content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY :are supported by this server` #### Format -The `scrollback` content can requested using timestamps: +The `chathistory` content can requested using timestamps: - SCROLLBACK target timestamp=YYYY-MM-DDThh:mm:ss.sssZ message_count - SCROLLBACK #channel timestamp=2016-11-19T18:02:01.000Z 50 + CHATHISTORY target timestamp=YYYY-MM-DDThh:mm:ss.sssZ message_count + CHATHISTORY #channel timestamp=2016-11-19T18:02:01.000Z 50 Alternatively, content can be requested using a `draft/msgid`: - SCROLLBACK target draft/msgid=ID message_count - SCROLLBACK #channel draft/msgid=774ba1b6-202b-448c-b23a-6150ce5681fd 50 + CHATHISTORY target draft/msgid=ID message_count + CHATHISTORY #channel draft/msgid=774ba1b6-202b-448c-b23a-6150ce5681fd 50 If no message_count is known, `*` should be used to specify the default value. @@ -40,19 +40,19 @@ The examples below are written with `draft/msgid` tags included. This tag is opt ### Begin :irc.host BATCH +ID chathistory target - :irc.host BATCH +XNyDSitp9MvcX scrollback #channel + :irc.host BATCH +XNyDSitp9MvcX chathistory #channel ### PRIVMSG @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PRIVMSG target :message - @batch=XNyDSitp9MvcX;draft/msgid=eb703092-0782-4c28-bf7c-f9e5c45963ca;time=2016-11-19T18:02:01.001Z :foo!bar@example.com PRIVMSG #channel :The SCROLLBACK specification is going to be fantastic! + @batch=XNyDSitp9MvcX;draft/msgid=eb703092-0782-4c28-bf7c-f9e5c45963ca;time=2016-11-19T18:02:01.001Z :foo!bar@example.com PRIVMSG #channel :The CHATHISTORY specification is going to be fantastic! ### NOTICE - @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host NTOICE target :message - @batch=XNyDSitp9MvcX;draft/msgid=cb302078-ce4e-4866-82b8-480ec58094b3;time=2016-11-19T18:02:02.002Z :foo!bar@example.com NOTICE #channel :Announcing the new IRCv3 SCROLLBACK extension draft! + @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host NOTICE target :message + @batch=XNyDSitp9MvcX;draft/msgid=cb302078-ce4e-4866-82b8-480ec58094b3;time=2016-11-19T18:02:02.002Z :foo!bar@example.com NOTICE #channel :Announcing the new IRCv3 CHATHISTORY extension draft! ### End :irc.host BATCH -ID :irc.host BATCH -XNyDSitp9MvcX ## Use cases -The batch type and supporting command are useful for allowing an "infinite scroll" type capability within the client itself. A client will, upon scrolling to the top of the active window, request scrollback from the server and, upon receiving such content, append it to the top of the window. Users can repeat this historic scrolling to retrieve prior history until limitations are met (see below). +The batch type and supporting command are useful for allowing an "infinite scroll" type capability within the client itself. A client will, upon scrolling to the top of the active window, request chathistory from the server and, upon receiving such content, append it to the top of the window. Users can repeat this historic scrolling to retrieve prior history until limitations are met (see below). ## Limitations Logging of messages and other actions must be enabled server-side and can be stored in any format desired, given appropriate software exists to retrieve and format such stored contnet. Scrollback can only be retrieved as far back as logs exist for the requesting user in the specified channel or query. @@ -60,11 +60,11 @@ Logging of messages and other actions must be enabled server-side and can be sto A method for securely identifying the requesting user must exist to ensure content is sent only to the appropriate users and clients. See below for more information. ## Security considerations -Secure identification of users and clients must exist in order to ensure that users cannot obtain history that does not belong to them. Use of account names, internal account identifiers, or certificate fingerprints should be strongly considered when matching content to users. The server must verify the current user's identity matches that of the desired content. This information is not sent as part of the `SCROLLBACK` command and must be validated via other means, such as those stated above. +Secure identification of users and clients must exist in order to ensure that users cannot obtain history that does not belong to them. Use of account names, internal account identifiers, or certificate fingerprints should be strongly considered when matching content to users. The server must verify the current user's identity matches that of the desired content. This information is not sent as part of the `CHATHISTORY` command and must be validated via other means, such as those stated above. ## Current Implementations -A ZNC-module implementation exists as [znc-scrollback](https://github.com/MuffinMedic/znc-scrollback). Client-side support for the ZNC module is in progress. Interest in supporting the batch type and command without ZNC has also been obtained, although specifics are not available at this time. +A ZNC-module implementation exists as [znc-chathistory](https://github.com/MuffinMedic/znc-chathistory). Client-side support for the ZNC module is in progress. Interest in supporting the batch type and command without ZNC has also been obtained, although specifics are not available at this time. -[batch]: batch-3.2.md -[chathistory]: batch/chathistory-3.3.md -[server-time]: server-time-3.2.md +[batch]: http://ircv3.net/specs/extensions/batch-3.2.html +[chathistory]: http://ircv3.net/specs/extensions/batch/chathistory-3.3.html +[server-time]: http://ircv3.net/specs/extensions/server-time-3.2.html From c4883c0cfb72f4a317e35bd0f9caf2a7a3765186 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Tue, 3 Jan 2017 18:18:27 -0500 Subject: [PATCH 10/27] Add max_message_count parameter to ISUPPORT --- extensions/chathistory-3.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/chathistory-3.3.md b/extensions/chathistory-3.3.md index d38ebdf4b..527802a01 100644 --- a/extensions/chathistory-3.3.md +++ b/extensions/chathistory-3.3.md @@ -20,7 +20,7 @@ When a client with the above mentioned capabilities requests chathistory content The `server-time` should be the time at which the message was originally sent, the `batch id` a randomly generated string unique to the entire batch, and the optional `draft/msgid`, if included, the `draft/msgid` originally sent with the message. ### `CHATHISTORY` Command -Scrollback content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY :are supported by this server` +Chathistory content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY=max_message_count :are supported by this server` #### Format The `chathistory` content can requested using timestamps: From 382968a32078b5d770a2a46ad4717436f204d434 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Wed, 4 Jan 2017 00:55:17 -0500 Subject: [PATCH 11/27] Add error replies and draft/label --- extensions/chathistory-3.3.md | 59 ++++++++++++++++++++--------------- 1 file changed, 34 insertions(+), 25 deletions(-) diff --git a/extensions/chathistory-3.3.md b/extensions/chathistory-3.3.md index 527802a01..e6fca2d5b 100644 --- a/extensions/chathistory-3.3.md +++ b/extensions/chathistory-3.3.md @@ -9,15 +9,19 @@ copyrights: email: "evan@muffinmedic.net" --- ## Description -This document describes the format of the `chathistory` extension. The `chathistory` extension uses the `chathistory` batch type, adding a client-side command for requesting chathistory content from the server. +This document describes the format of the `chathistory` extension. The `chathistory` extension uses the [chathistory][batch/chathistory] batch type, adding a client-side command for requesting `chathistory` content from the server. The `chathistory` extension adds an optional `draft/msgid` to the `chathistory` batch reply. -Client side support for the [`batch`][batch] and [`server-time`][server-time] capabilities is required. Support for the [`draft/msgid`](https://github.com/ircv3/ircv3-specifications/pull/285) capability is optional but recommended. +Client side support for the [`batch`][batch], [`server-time`][server-time], and [`draft/labeled-response`][draft/labeled-response] capabilities is required. Support for the [`draft/msgid`][draft/msgid] capability is optional but recommended. -When a client with the above mentioned capabilities requests chathistory content from the server (using the `CHATHISTORY` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. +When a client with the above mentioned capabilities requests `chathistory` content from the server (using the `CHATHISTORY` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. -The `server-time` should be the time at which the message was originally sent, the `batch id` a randomly generated string unique to the entire batch, and the optional `draft/msgid`, if included, the `draft/msgid` originally sent with the message. +The returned `batch` must not be blank. If no content exists to return, the appopriate error message should be sent instead. + +Both the `message_count` and `max_message_count` must be integers greater than 0. The client should not request a `message_count` greater than the `max_message_count` parameter sent in the command. If the `message_count` exceeds the `max_message_count`, server should return a number of lines equal to the `max_message_count`. + +The `server-time` should be the time at which the message was originally sent and the `batch id` a unique ID to the entire batch. The `draft/label` should be a unique ID used to identify the `chathistory` request and any replies. The optional `draft/msgid`, if included, should be the `draft/msgid` originally sent with the message. ### `CHATHISTORY` Command Chathistory content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY=max_message_count :are supported by this server` @@ -25,46 +29,51 @@ Chathistory content can be requested by the client to the server by sending the #### Format The `chathistory` content can requested using timestamps: - CHATHISTORY target timestamp=YYYY-MM-DDThh:mm:ss.sssZ message_count - CHATHISTORY #channel timestamp=2016-11-19T18:02:01.000Z 50 + @label=ID CHATHISTORY target timestamp=YYYY-MM-DDThh:mm:ss.sssZ message_count Alternatively, content can be requested using a `draft/msgid`: - CHATHISTORY target draft/msgid=ID message_count - CHATHISTORY #channel draft/msgid=774ba1b6-202b-448c-b23a-6150ce5681fd 50 + @label=ID CHATHISTORY target draft/msgid=ID message_count If no message_count is known, `*` should be used to specify the default value. -## Examples +#### Errors +If the server receives an improperly formatted `CHATHISTORY` command, the `CMD_INVALID` error code should be returned. + +If no `chathistory` exists to return, the server should return the appropriate error code. `ACCESS_DENIED` should be sent if the user requests content they do not have permission to view. `NOT_FOUND` should be sent if no content matching the request is found and no `ACCESS_DENIED` error exists. + +### Examples The examples below are written with `draft/msgid` tags included. This tag is optional but recommended. -### Begin - :irc.host BATCH +ID chathistory target - :irc.host BATCH +XNyDSitp9MvcX chathistory #channel -### PRIVMSG - @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PRIVMSG target :message - @batch=XNyDSitp9MvcX;draft/msgid=eb703092-0782-4c28-bf7c-f9e5c45963ca;time=2016-11-19T18:02:01.001Z :foo!bar@example.com PRIVMSG #channel :The CHATHISTORY specification is going to be fantastic! -### NOTICE - @batch=ID;draft/msgid=UUID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host NOTICE target :message - @batch=XNyDSitp9MvcX;draft/msgid=cb302078-ce4e-4866-82b8-480ec58094b3;time=2016-11-19T18:02:02.002Z :foo!bar@example.com NOTICE #channel :Announcing the new IRCv3 CHATHISTORY extension draft! -### End +#### Begin + @label=ID :irc.host BATCH +ID chathistory target +#### PRIVMSG + @batch=ID;draft/msgid=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PRIVMSG target :message +#### NOTICE + @batch=ID;draft/msgid=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host NOTICE target :message +#### End :irc.host BATCH -ID - :irc.host BATCH -XNyDSitp9MvcX +#### Error + @label=ID :nick!ident@host CHATHISTORY ERR :ERROR_CODE -## Use cases -The batch type and supporting command are useful for allowing an "infinite scroll" type capability within the client itself. A client will, upon scrolling to the top of the active window, request chathistory from the server and, upon receiving such content, append it to the top of the window. Users can repeat this historic scrolling to retrieve prior history until limitations are met (see below). +## Use Cases +The batch type and supporting command are useful for allowing an "infinite scroll" type capability within the client. A client will, upon scrolling to the top of the active window or a manual trigger, may request `chathistory` from the server and, after receiving returned content, append it to the top of the window. Users can repeat this historic scrolling to retrieve prior history until limitations are met (see below). ## Limitations Logging of messages and other actions must be enabled server-side and can be stored in any format desired, given appropriate software exists to retrieve and format such stored contnet. Scrollback can only be retrieved as far back as logs exist for the requesting user in the specified channel or query. A method for securely identifying the requesting user must exist to ensure content is sent only to the appropriate users and clients. See below for more information. -## Security considerations -Secure identification of users and clients must exist in order to ensure that users cannot obtain history that does not belong to them. Use of account names, internal account identifiers, or certificate fingerprints should be strongly considered when matching content to users. The server must verify the current user's identity matches that of the desired content. This information is not sent as part of the `CHATHISTORY` command and must be validated via other means, such as those stated above. +## Security Considerations +Secure identification of users and clients must exist in order to ensure that users cannot obtain history that does not belong to them. Use of account names, internal account identifiers, or certificate fingerprints should be strongly considered when matching content to users. The server must verify the current user's identity matches that of the desired content. This information is not sent as part of the `CHATHISTORY` command and must be validated via other means, such as those stated above. Access must be checked first and return an `ACCESS_DENIED` error as appropriate. If no `ACCESS_DENIED` error exists, the server can check for returnable content. ## Current Implementations A ZNC-module implementation exists as [znc-chathistory](https://github.com/MuffinMedic/znc-chathistory). Client-side support for the ZNC module is in progress. Interest in supporting the batch type and command without ZNC has also been obtained, although specifics are not available at this time. +Note: This module may be out of date while the specification is reviewed and modified. + [batch]: http://ircv3.net/specs/extensions/batch-3.2.html -[chathistory]: http://ircv3.net/specs/extensions/batch/chathistory-3.3.html +[batch/chathistory]: http://ircv3.net/specs/extensions/batch/chathistory-3.3.html [server-time]: http://ircv3.net/specs/extensions/server-time-3.2.html +[draft/msgid]: https://github.com/ircv3/ircv3-specifications/pull/285 +[draft/labeled-response]: https://github.com/ircv3/ircv3-specifications/pull/162 From ed14f4c892f607a24f0bae983fdc9bbff27d04ab Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Wed, 4 Jan 2017 01:05:52 -0500 Subject: [PATCH 12/27] Specify label as draft --- extensions/chathistory-3.3.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/extensions/chathistory-3.3.md b/extensions/chathistory-3.3.md index e6fca2d5b..88ed575e5 100644 --- a/extensions/chathistory-3.3.md +++ b/extensions/chathistory-3.3.md @@ -29,11 +29,11 @@ Chathistory content can be requested by the client to the server by sending the #### Format The `chathistory` content can requested using timestamps: - @label=ID CHATHISTORY target timestamp=YYYY-MM-DDThh:mm:ss.sssZ message_count + @draft/label=ID CHATHISTORY target timestamp=YYYY-MM-DDThh:mm:ss.sssZ message_count Alternatively, content can be requested using a `draft/msgid`: - @label=ID CHATHISTORY target draft/msgid=ID message_count + @draft/label=ID CHATHISTORY target draft/msgid=ID message_count If no message_count is known, `*` should be used to specify the default value. @@ -46,7 +46,7 @@ If no `chathistory` exists to return, the server should return the appropriate e The examples below are written with `draft/msgid` tags included. This tag is optional but recommended. #### Begin - @label=ID :irc.host BATCH +ID chathistory target + @draft/label=ID :irc.host BATCH +ID chathistory target #### PRIVMSG @batch=ID;draft/msgid=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PRIVMSG target :message #### NOTICE @@ -54,7 +54,7 @@ The examples below are written with `draft/msgid` tags included. This tag is opt #### End :irc.host BATCH -ID #### Error - @label=ID :nick!ident@host CHATHISTORY ERR :ERROR_CODE + @draft/label=ID :nick!ident@host CHATHISTORY ERR :ERROR_CODE ## Use Cases The batch type and supporting command are useful for allowing an "infinite scroll" type capability within the client. A client will, upon scrolling to the top of the active window or a manual trigger, may request `chathistory` from the server and, after receiving returned content, append it to the top of the window. Users can repeat this historic scrolling to retrieve prior history until limitations are met (see below). From 78b39f13b0710a4d249656e343ff327571a728b5 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Tue, 10 Jan 2017 12:51:39 -0500 Subject: [PATCH 13/27] Improve error reporting and remove default size --- extensions/chathistory-3.3.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/extensions/chathistory-3.3.md b/extensions/chathistory-3.3.md index 88ed575e5..68a9bd38d 100644 --- a/extensions/chathistory-3.3.md +++ b/extensions/chathistory-3.3.md @@ -17,14 +17,12 @@ Client side support for the [`batch`][batch], [`server-time`][server-time], and When a client with the above mentioned capabilities requests `chathistory` content from the server (using the `CHATHISTORY` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. -The returned `batch` must not be blank. If no content exists to return, the appopriate error message should be sent instead. - -Both the `message_count` and `max_message_count` must be integers greater than 0. The client should not request a `message_count` greater than the `max_message_count` parameter sent in the command. If the `message_count` exceeds the `max_message_count`, server should return a number of lines equal to the `max_message_count`. - The `server-time` should be the time at which the message was originally sent and the `batch id` a unique ID to the entire batch. The `draft/label` should be a unique ID used to identify the `chathistory` request and any replies. The optional `draft/msgid`, if included, should be the `draft/msgid` originally sent with the message. ### `CHATHISTORY` Command -Chathistory content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY=max_message_count :are supported by this server` +Chathistory content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. The returned `batch` must not be blank. If no content exists to return, the appopriate error message should be sent instead. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY=max_message_count :are supported by this server` + +Both the `message_count` and `max_message_count` must be integers greater than 0. The client should not request a `message_count` greater than the `max_message_count` parameter sent in the command. If the `message_count` exceeds the `max_message_count`, server should return a number of lines equal to the `max_message_count` and the appropriate warning as described below. #### Format The `chathistory` content can requested using timestamps: @@ -35,11 +33,11 @@ Alternatively, content can be requested using a `draft/msgid`: @draft/label=ID CHATHISTORY target draft/msgid=ID message_count -If no message_count is known, `*` should be used to specify the default value. - -#### Errors +#### Errors and Warnings If the server receives an improperly formatted `CHATHISTORY` command, the `CMD_INVALID` error code should be returned. +If the `message_count` exceeds the `max_message_count`, warn code `MAX_MSG_COUNT_EXCEEDED` should be returned. The command should continue to be processed as described above. + If no `chathistory` exists to return, the server should return the appropriate error code. `ACCESS_DENIED` should be sent if the user requests content they do not have permission to view. `NOT_FOUND` should be sent if no content matching the request is found and no `ACCESS_DENIED` error exists. ### Examples @@ -54,7 +52,9 @@ The examples below are written with `draft/msgid` tags included. This tag is opt #### End :irc.host BATCH -ID #### Error - @draft/label=ID :nick!ident@host CHATHISTORY ERR :ERROR_CODE + @draft/label=ID :nick!ident@host CHATHISTORY ERR ERROR_CODE +#### Warning + @draft/label=ID :nick!ident@host CHATHISTORY WARN WARN_CODE ## Use Cases The batch type and supporting command are useful for allowing an "infinite scroll" type capability within the client. A client will, upon scrolling to the top of the active window or a manual trigger, may request `chathistory` from the server and, after receiving returned content, append it to the top of the window. Users can repeat this historic scrolling to retrieve prior history until limitations are met (see below). From 78208a69d03158a3e8ad3968f227ee201286543c Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Tue, 10 Jan 2017 13:31:54 -0500 Subject: [PATCH 14/27] Make draft/label recommended --- extensions/chathistory-3.3.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/extensions/chathistory-3.3.md b/extensions/chathistory-3.3.md index 68a9bd38d..2394b6bb7 100644 --- a/extensions/chathistory-3.3.md +++ b/extensions/chathistory-3.3.md @@ -17,10 +17,10 @@ Client side support for the [`batch`][batch], [`server-time`][server-time], and When a client with the above mentioned capabilities requests `chathistory` content from the server (using the `CHATHISTORY` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. -The `server-time` should be the time at which the message was originally sent and the `batch id` a unique ID to the entire batch. The `draft/label` should be a unique ID used to identify the `chathistory` request and any replies. The optional `draft/msgid`, if included, should be the `draft/msgid` originally sent with the message. +The `server-time` should be the time at which the message was originally sent and the `batch id` a unique ID to the entire batch. `draft/label` is recommended and should be a unique ID used to identify the `chathistory` request and any replies. Also recommended, `draft/msgid` should be the `draft/msgid` originally sent with the message. ### `CHATHISTORY` Command -Chathistory content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. The returned `batch` must not be blank. If no content exists to return, the appopriate error message should be sent instead. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY=max_message_count :are supported by this server` +Chathistory content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY=max_message_count :are supported by this server` Both the `message_count` and `max_message_count` must be integers greater than 0. The client should not request a `message_count` greater than the `max_message_count` parameter sent in the command. If the `message_count` exceeds the `max_message_count`, server should return a number of lines equal to the `max_message_count` and the appropriate warning as described below. @@ -34,14 +34,16 @@ Alternatively, content can be requested using a `draft/msgid`: @draft/label=ID CHATHISTORY target draft/msgid=ID message_count #### Errors and Warnings +Errors indicate that there was nothing possible to return for the specified reason. Warnings are used when the command was successful but the client should be aware of specific handling requirements for the returned content or adjustments to sending the command. + If the server receives an improperly formatted `CHATHISTORY` command, the `CMD_INVALID` error code should be returned. If the `message_count` exceeds the `max_message_count`, warn code `MAX_MSG_COUNT_EXCEEDED` should be returned. The command should continue to be processed as described above. -If no `chathistory` exists to return, the server should return the appropriate error code. `ACCESS_DENIED` should be sent if the user requests content they do not have permission to view. `NOT_FOUND` should be sent if no content matching the request is found and no `ACCESS_DENIED` error exists. +If no `chathistory` exists to return, the server should return the appropriate error code. `ACCESS_DENIED` should be sent if the user requests content they do not have permission to view. ### Examples -The examples below are written with `draft/msgid` tags included. This tag is optional but recommended. +The examples below are written with `draft/msgid` tags included. This tag is recommended. #### Begin @draft/label=ID :irc.host BATCH +ID chathistory target From f923267f5c73e6a64975cc3ccd0145125aafed6b Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Tue, 10 Jan 2017 13:33:27 -0500 Subject: [PATCH 15/27] Specify optional draft/label --- extensions/chathistory-3.3.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/extensions/chathistory-3.3.md b/extensions/chathistory-3.3.md index 2394b6bb7..a107e4573 100644 --- a/extensions/chathistory-3.3.md +++ b/extensions/chathistory-3.3.md @@ -34,8 +34,6 @@ Alternatively, content can be requested using a `draft/msgid`: @draft/label=ID CHATHISTORY target draft/msgid=ID message_count #### Errors and Warnings -Errors indicate that there was nothing possible to return for the specified reason. Warnings are used when the command was successful but the client should be aware of specific handling requirements for the returned content or adjustments to sending the command. - If the server receives an improperly formatted `CHATHISTORY` command, the `CMD_INVALID` error code should be returned. If the `message_count` exceeds the `max_message_count`, warn code `MAX_MSG_COUNT_EXCEEDED` should be returned. The command should continue to be processed as described above. @@ -43,7 +41,7 @@ If the `message_count` exceeds the `max_message_count`, warn code `MAX_MSG_COUNT If no `chathistory` exists to return, the server should return the appropriate error code. `ACCESS_DENIED` should be sent if the user requests content they do not have permission to view. ### Examples -The examples below are written with `draft/msgid` tags included. This tag is recommended. +The examples below are written with `draft/msgid` and `draft/label` tags included. These tags are recommended. #### Begin @draft/label=ID :irc.host BATCH +ID chathistory target From 3ae73317e4b07a16be2f8dc849254f1247458f7f Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Sun, 12 Feb 2017 19:38:58 -0500 Subject: [PATCH 16/27] Specify work-in-progress draft implementation --- extensions/chathistory-3.3.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/extensions/chathistory-3.3.md b/extensions/chathistory-3.3.md index a107e4573..50065a452 100644 --- a/extensions/chathistory-3.3.md +++ b/extensions/chathistory-3.3.md @@ -8,6 +8,13 @@ copyrights: period: "2017" email: "evan@muffinmedic.net" --- +## Notes for implementing work-in-progress version +This is a work-in-progress specification. + +Software implementing this work-in-progress specification MUST NOT use the unprefixed `CHATHISTORY` command. Instead, implementations SHOULD use the `draft/CHATHISTORY` command to be interoperable with other software implementing a compatible work-in-progress version. + +The final version of the specification will use an unprefixed command. + ## Description This document describes the format of the `chathistory` extension. The `chathistory` extension uses the [chathistory][batch/chathistory] batch type, adding a client-side command for requesting `chathistory` content from the server. From 0af74500351c9a1c851e5c88705d25c5ed836fa8 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Tue, 7 Mar 2017 17:35:22 -0500 Subject: [PATCH 17/27] Allow for positive and negative directional message counts --- extensions/{chathistory-3.3.md => chathistory.md} | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) rename extensions/{chathistory-3.3.md => chathistory.md} (77%) diff --git a/extensions/chathistory-3.3.md b/extensions/chathistory.md similarity index 77% rename from extensions/chathistory-3.3.md rename to extensions/chathistory.md index 50065a452..7b4505dad 100644 --- a/extensions/chathistory-3.3.md +++ b/extensions/chathistory.md @@ -20,16 +20,16 @@ This document describes the format of the `chathistory` extension. The `chathist The `chathistory` extension adds an optional `draft/msgid` to the `chathistory` batch reply. -Client side support for the [`batch`][batch], [`server-time`][server-time], and [`draft/labeled-response`][draft/labeled-response] capabilities is required. Support for the [`draft/msgid`][draft/msgid] capability is optional but recommended. +Clients MUST support the [`batch`][batch], [`server-time`][server-time], and [`draft/labeled-response`][draft/labeled-response] capabilities. Clients SHOULD support the [`draft/msgid`][draft/msgid] capability. -When a client with the above mentioned capabilities requests `chathistory` content from the server (using the `CHATHISTORY` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. +When a client with the above mentioned capabilities requests `chathistory` content from the server (using the `CHATHISTORY` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp for a negative `message_count`, after the number of messages specified for a positive `message_count`, or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. -The `server-time` should be the time at which the message was originally sent and the `batch id` a unique ID to the entire batch. `draft/label` is recommended and should be a unique ID used to identify the `chathistory` request and any replies. Also recommended, `draft/msgid` should be the `draft/msgid` originally sent with the message. +The `server-time` should be the time at which the message was originally sent and the `batch id` a unique ID to the entire batch. `draft/label` SHOULD be inclued and MUST be a unique ID used to identify the `chathistory` request and any replies. `draft/msgid` SHOULD be the `draft/msgid` originally sent with the message. ### `CHATHISTORY` Command Chathistory content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY=max_message_count :are supported by this server` -Both the `message_count` and `max_message_count` must be integers greater than 0. The client should not request a `message_count` greater than the `max_message_count` parameter sent in the command. If the `message_count` exceeds the `max_message_count`, server should return a number of lines equal to the `max_message_count` and the appropriate warning as described below. +Both the `message_count` and `max_message_count` MUST be non-zero integers and `max_message_count` MUST be positive. The client should not request a `message_count` with an absolute value greater than the `max_message_count` parameter sent in the command. If the `message_count` absolute value exceeds the `max_message_count`, server should return a number of lines equal to the `max_message_count` and the appropriate warning as described below. #### Format The `chathistory` content can requested using timestamps: @@ -40,10 +40,12 @@ Alternatively, content can be requested using a `draft/msgid`: @draft/label=ID CHATHISTORY target draft/msgid=ID message_count +If `message_count` is positive, content MUST be retrieved from after the specifie timestamp or `draft/msgid`. If the `message_count` is negative, content MUST be retrieved from before the specified timestamp or `draft/msgid`. + #### Errors and Warnings If the server receives an improperly formatted `CHATHISTORY` command, the `CMD_INVALID` error code should be returned. -If the `message_count` exceeds the `max_message_count`, warn code `MAX_MSG_COUNT_EXCEEDED` should be returned. The command should continue to be processed as described above. +If the absolute value of `message_count` exceeds the `max_message_count`, warn code `MAX_MSG_COUNT_EXCEEDED` should be returned. The command should continue to be processed as described above. If no `chathistory` exists to return, the server should return the appropriate error code. `ACCESS_DENIED` should be sent if the user requests content they do not have permission to view. From 77b4a6a7776391b3033f30f6421b83bba78db594 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Tue, 7 Mar 2017 17:44:00 -0500 Subject: [PATCH 18/27] Typo fix --- extensions/chathistory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/chathistory.md b/extensions/chathistory.md index 7b4505dad..659b657d8 100644 --- a/extensions/chathistory.md +++ b/extensions/chathistory.md @@ -24,7 +24,7 @@ Clients MUST support the [`batch`][batch], [`server-time`][server-time], and [`d When a client with the above mentioned capabilities requests `chathistory` content from the server (using the `CHATHISTORY` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp for a negative `message_count`, after the number of messages specified for a positive `message_count`, or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. -The `server-time` should be the time at which the message was originally sent and the `batch id` a unique ID to the entire batch. `draft/label` SHOULD be inclued and MUST be a unique ID used to identify the `chathistory` request and any replies. `draft/msgid` SHOULD be the `draft/msgid` originally sent with the message. +The `server-time` should be the time at which the message was originally sent and the `batch id` a unique ID to the entire batch. `draft/label` SHOULD be included and MUST be a unique ID used to identify the `chathistory` request and any replies. `draft/msgid` SHOULD be the `draft/msgid` originally sent with the message. ### `CHATHISTORY` Command Chathistory content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY=max_message_count :are supported by this server` From 45b3e0a16551871d1f5cafa776c05cc048e31abd Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Wed, 8 Mar 2017 00:07:27 -0500 Subject: [PATCH 19/27] Make draft/labeled-response recommended --- extensions/chathistory.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/chathistory.md b/extensions/chathistory.md index 659b657d8..24732db97 100644 --- a/extensions/chathistory.md +++ b/extensions/chathistory.md @@ -20,11 +20,11 @@ This document describes the format of the `chathistory` extension. The `chathist The `chathistory` extension adds an optional `draft/msgid` to the `chathistory` batch reply. -Clients MUST support the [`batch`][batch], [`server-time`][server-time], and [`draft/labeled-response`][draft/labeled-response] capabilities. Clients SHOULD support the [`draft/msgid`][draft/msgid] capability. +Clients MUST support the [`batch`][batch] and [`server-time`][server-time] capabilities. Clients SHOULD support the [`draft/labeled-response`][draft/labeled-response] and [`draft/msgid`][draft/msgid] capabilities. When a client with the above mentioned capabilities requests `chathistory` content from the server (using the `CHATHISTORY` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp for a negative `message_count`, after the number of messages specified for a positive `message_count`, or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. -The `server-time` should be the time at which the message was originally sent and the `batch id` a unique ID to the entire batch. `draft/label` SHOULD be included and MUST be a unique ID used to identify the `chathistory` request and any replies. `draft/msgid` SHOULD be the `draft/msgid` originally sent with the message. +The `server-time` should be the time at which the message was originally sent and the `batch id` a unique ID to the entire batch. `draft/label` SHOULD be included and MUST be a unique ID used to identify the `chathistory` request and any replies. `draft/msgid` MUST be the `draft/msgid` originally sent with the message. ### `CHATHISTORY` Command Chathistory content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY=max_message_count :are supported by this server` From e5f366b8e2224db00f3475ffa1e5381da629d5fb Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Wed, 8 Mar 2017 10:26:16 -0500 Subject: [PATCH 20/27] Specificy draft/label and draft/msgid purposes --- extensions/chathistory.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/chathistory.md b/extensions/chathistory.md index 24732db97..906f49487 100644 --- a/extensions/chathistory.md +++ b/extensions/chathistory.md @@ -24,7 +24,7 @@ Clients MUST support the [`batch`][batch] and [`server-time`][server-time] capab When a client with the above mentioned capabilities requests `chathistory` content from the server (using the `CHATHISTORY` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp for a negative `message_count`, after the number of messages specified for a positive `message_count`, or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. -The `server-time` should be the time at which the message was originally sent and the `batch id` a unique ID to the entire batch. `draft/label` SHOULD be included and MUST be a unique ID used to identify the `chathistory` request and any replies. `draft/msgid` MUST be the `draft/msgid` originally sent with the message. +The `server-time` should be the time at which the message was received from the IRC server and the `batch id` a unique ID for the entire batch. `draft/label` SHOULD be included and MUST be a unique ID used to identify the `chathistory` request and any replies. A `draft/msgid` to identify each individual message MUST be the `draft/msgid` included when each message was first received from the IRC server. ### `CHATHISTORY` Command Chathistory content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY=max_message_count :are supported by this server` @@ -40,7 +40,7 @@ Alternatively, content can be requested using a `draft/msgid`: @draft/label=ID CHATHISTORY target draft/msgid=ID message_count -If `message_count` is positive, content MUST be retrieved from after the specifie timestamp or `draft/msgid`. If the `message_count` is negative, content MUST be retrieved from before the specified timestamp or `draft/msgid`. +If `message_count` is positive, content MUST be retrieved from after and not including the specified timestamp or `draft/msgid`. If the `message_count` is negative, content MUST be retrieved from before the specified timestamp or `draft/msgid`. #### Errors and Warnings If the server receives an improperly formatted `CHATHISTORY` command, the `CMD_INVALID` error code should be returned. From 545f645731a44e6895505c397b0a8cc0b166eeba Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Wed, 8 Mar 2017 10:26:16 -0500 Subject: [PATCH 21/27] Specify draft/label and draft/msgid purposes --- extensions/chathistory.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/chathistory.md b/extensions/chathistory.md index 24732db97..906f49487 100644 --- a/extensions/chathistory.md +++ b/extensions/chathistory.md @@ -24,7 +24,7 @@ Clients MUST support the [`batch`][batch] and [`server-time`][server-time] capab When a client with the above mentioned capabilities requests `chathistory` content from the server (using the `CHATHISTORY` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp for a negative `message_count`, after the number of messages specified for a positive `message_count`, or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. -The `server-time` should be the time at which the message was originally sent and the `batch id` a unique ID to the entire batch. `draft/label` SHOULD be included and MUST be a unique ID used to identify the `chathistory` request and any replies. `draft/msgid` MUST be the `draft/msgid` originally sent with the message. +The `server-time` should be the time at which the message was received from the IRC server and the `batch id` a unique ID for the entire batch. `draft/label` SHOULD be included and MUST be a unique ID used to identify the `chathistory` request and any replies. A `draft/msgid` to identify each individual message MUST be the `draft/msgid` included when each message was first received from the IRC server. ### `CHATHISTORY` Command Chathistory content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY=max_message_count :are supported by this server` @@ -40,7 +40,7 @@ Alternatively, content can be requested using a `draft/msgid`: @draft/label=ID CHATHISTORY target draft/msgid=ID message_count -If `message_count` is positive, content MUST be retrieved from after the specifie timestamp or `draft/msgid`. If the `message_count` is negative, content MUST be retrieved from before the specified timestamp or `draft/msgid`. +If `message_count` is positive, content MUST be retrieved from after and not including the specified timestamp or `draft/msgid`. If the `message_count` is negative, content MUST be retrieved from before the specified timestamp or `draft/msgid`. #### Errors and Warnings If the server receives an improperly formatted `CHATHISTORY` command, the `CMD_INVALID` error code should be returned. From 9cc586ae0aeffe78d7b3259fe3fe2d12881854d4 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Wed, 23 Aug 2017 10:56:45 -0400 Subject: [PATCH 22/27] Standardize errors --- extensions/chathistory.md | 52 +++++++++++++++++++++++++-------------- 1 file changed, 34 insertions(+), 18 deletions(-) diff --git a/extensions/chathistory.md b/extensions/chathistory.md index 906f49487..323706708 100644 --- a/extensions/chathistory.md +++ b/extensions/chathistory.md @@ -20,34 +20,46 @@ This document describes the format of the `chathistory` extension. The `chathist The `chathistory` extension adds an optional `draft/msgid` to the `chathistory` batch reply. -Clients MUST support the [`batch`][batch] and [`server-time`][server-time] capabilities. Clients SHOULD support the [`draft/labeled-response`][draft/labeled-response] and [`draft/msgid`][draft/msgid] capabilities. +Clients MUST support the [`batch`][batch] and [`server-time`][server-time] capabilities. Clients SHOULD support the [`draft/labeled-response`][draft/labeled-response] and [`draft/message-tags`][draft/message-tags] capabilities. -When a client with the above mentioned capabilities requests `chathistory` content from the server (using the `CHATHISTORY` command outlined below), the server should return to the client a single batch containing a number of desired raw IRC lines equal to the `message_count` parameter specified, ending directly before the given timestamp for a negative `message_count`, after the number of messages specified for a positive `message_count`, or with the message directly proceeding the one with the specified `draft/msgid`. The raw IRC lines should be formatted and returned to the client as they were originally, with the addition of the above capability tags. +When a client with the above mentioned capabilities requests `chathistory` content from the server (using the `draft/CHATHISTORY` command outlined below), the server SHOULD return to the client a single batch containing raw IRC lines starting with and exluduing the `start` parameter and up to and including the message at the `end` parameter. The raw IRC lines SHOULD be formatted and returned to the client as they were originally, with the addition of the above capability tags. -The `server-time` should be the time at which the message was received from the IRC server and the `batch id` a unique ID for the entire batch. `draft/label` SHOULD be included and MUST be a unique ID used to identify the `chathistory` request and any replies. A `draft/msgid` to identify each individual message MUST be the `draft/msgid` included when each message was first received from the IRC server. +The `server-time` SHOULD be the time at which the message was received from the IRC server and the `batch id` a unique ID for the entire batch. `draft/label` SHOULD be included and MUST be a unique ID used to identify the `chathistory` request and any replies. A `draft/msgid` to identify each individual message MUST be the `draft/msgid` included when each message was first received from the IRC server. ### `CHATHISTORY` Command -Chathistory content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. A `batch` must be returned by the server. If no content exists to return, an empty batch should be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY=max_message_count :are supported by this server` +`CHATHISTORY` content can be requested by the client to the server by sending the `draft/CHATHISTORY` command to the server. A `batch` MUST be returned by the server. If no content exists to return, an empty batch SHOULD be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick draft/CHATHISTORY=max_message_count :are supported by this server` -Both the `message_count` and `max_message_count` MUST be non-zero integers and `max_message_count` MUST be positive. The client should not request a `message_count` with an absolute value greater than the `max_message_count` parameter sent in the command. If the `message_count` absolute value exceeds the `max_message_count`, server should return a number of lines equal to the `max_message_count` and the appropriate warning as described below. +Both the `message_count` and `max_message_count` MUST be integers. `message_count` MUST be a non-zero and `max_message_count` MUST be greater than or equal to zero. The client SHOULD not request a `message_count` with an absolute value greater than the `max_message_count` parameter sent in the command. + +Both the `start` and `end` parameters support `draft/msgid` and `timestamp`. The `end` parameter also accepts a `message_count`. If the number of lines between the `start` and `end` parameters exceeds the `max_message_count`, the server SHOULD return a number of lines equal to the `max_message_count` and the appropriate warning as described below. A `max_message_count` of 0 indicates that no maximum exists. + +A positive `message_count` or tag `draft/msgid` prepended with a `+` indicates the client is requesting content after the `start`. A negative `message_count` or `draft/msgid` tag prepended with a `-` indicates the client is requested content before the specified `start`. + +The `target` parameter specifies a single channel or query from which history SHOULD be retrieved. Wildcards or multiple targets are not supported. #### Format +`chathistory` uses the following generic format: + + @draft/label=ID draft/CHATHISTORY + The `chathistory` content can requested using timestamps: - @draft/label=ID CHATHISTORY target timestamp=YYYY-MM-DDThh:mm:ss.sssZ message_count + @draft/label=ID draft/CHATHISTORY timestamp=YYYY-MM-DDThh:mm:ss.sssZ message_count= Alternatively, content can be requested using a `draft/msgid`: - @draft/label=ID CHATHISTORY target draft/msgid=ID message_count + @draft/label=ID draftCHATHISTORY draft/msgid= timestamp= + +Content can also be requested up to a specified timestamp or `draft/msgid` in place of the `message_count`. The start and end parameter types do not have to match: -If `message_count` is positive, content MUST be retrieved from after and not including the specified timestamp or `draft/msgid`. If the `message_count` is negative, content MUST be retrieved from before the specified timestamp or `draft/msgid`. + @draft/label=ID draftCHATHISTORY timestamp= +draft/msgid= #### Errors and Warnings -If the server receives an improperly formatted `CHATHISTORY` command, the `CMD_INVALID` error code should be returned. +If the server receives a`draft/CHATHISTORY` command with missing parameters, the `ERR_NEEDMOREPARAMS` error code SHOULD be returned. -If the absolute value of `message_count` exceeds the `max_message_count`, warn code `MAX_MSG_COUNT_EXCEEDED` should be returned. The command should continue to be processed as described above. +If the number of lines between the `start` and `end` parameters exceeds the `max_message_count`, warn code `MAX_MSG_COUNT_EXCEEDED` SHOULD be returned. The command SHOULD continue to be processed as described above. -If no `chathistory` exists to return, the server should return the appropriate error code. `ACCESS_DENIED` should be sent if the user requests content they do not have permission to view. +If the target has no `chathistory` content to return or the user does not have permission to view the requested content, `ERR_NOSUCHNICK` or `ERR_NOSUCHCHANNEL` SHOULD be returned accordingly. ### Examples The examples below are written with `draft/msgid` and `draft/label` tags included. These tags are recommended. @@ -58,23 +70,27 @@ The examples below are written with `draft/msgid` and `draft/label` tags include @batch=ID;draft/msgid=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PRIVMSG target :message #### NOTICE @batch=ID;draft/msgid=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host NOTICE target :message +#### ACTION + @batch=ID;draft/msgid=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PRIVMSG target :ACTION message #### End :irc.host BATCH -ID #### Error - @draft/label=ID :nick!ident@host CHATHISTORY ERR ERROR_CODE + @draft/label=ID :nick!ident@host draft/CHATHISTORY ERR ERROR_CODE #### Warning - @draft/label=ID :nick!ident@host CHATHISTORY WARN WARN_CODE + @draft/label=ID :nick!ident@host draft/CHATHISTORY WARN WARN_CODE ## Use Cases The batch type and supporting command are useful for allowing an "infinite scroll" type capability within the client. A client will, upon scrolling to the top of the active window or a manual trigger, may request `chathistory` from the server and, after receiving returned content, append it to the top of the window. Users can repeat this historic scrolling to retrieve prior history until limitations are met (see below). ## Limitations -Logging of messages and other actions must be enabled server-side and can be stored in any format desired, given appropriate software exists to retrieve and format such stored contnet. Scrollback can only be retrieved as far back as logs exist for the requesting user in the specified channel or query. +Logging of messages and other actions MUST be enabled server-side and can be stored in any format desired, given appropriate software exists to retrieve and format such stored contnet. Scrollback can only be retrieved as far back as logs exist for the requesting user in the specified channel or query. -A method for securely identifying the requesting user must exist to ensure content is sent only to the appropriate users and clients. See below for more information. +A method for securely identifying the requesting user MUST exist to ensure content is sent only to the appropriate users and clients. See below for more information. ## Security Considerations -Secure identification of users and clients must exist in order to ensure that users cannot obtain history that does not belong to them. Use of account names, internal account identifiers, or certificate fingerprints should be strongly considered when matching content to users. The server must verify the current user's identity matches that of the desired content. This information is not sent as part of the `CHATHISTORY` command and must be validated via other means, such as those stated above. Access must be checked first and return an `ACCESS_DENIED` error as appropriate. If no `ACCESS_DENIED` error exists, the server can check for returnable content. +Secure identification of users and clients MUST exist in order to ensure that users cannot obtain history they are not authorized to view. Use of account names, internal account identifiers, or certificate fingerprints SHOULD be strongly considered when matching content to users. The server MUST verify the current user's identity matches that of the desired content. This information is not sent as part of the `draft/CHATHISTORY` command and MUST be validated via other means, such as those stated above. Access MUST be checked first and return an `ERR_NOSUCHNICK` or `ERR_NOSUCHCHANNEL` error as appropriate. If no authorization error exists, the server can check for returnable content. If no returntable content is found, the server MUST send an `ERR_NOTEXTTOSEND` error. The server MUST NOT expose the existence of valid targets to unauthorized users. + +While a `max_message_count` of 0 MAY be used to indicate no limit exists, servers SHOULD set and enforce a reasonable `max_message_count` and properly throttle `draft/CHATHISTORY` commands to prevent abuse. ## Current Implementations A ZNC-module implementation exists as [znc-chathistory](https://github.com/MuffinMedic/znc-chathistory). Client-side support for the ZNC module is in progress. Interest in supporting the batch type and command without ZNC has also been obtained, although specifics are not available at this time. @@ -84,5 +100,5 @@ Note: This module may be out of date while the specification is reviewed and mod [batch]: http://ircv3.net/specs/extensions/batch-3.2.html [batch/chathistory]: http://ircv3.net/specs/extensions/batch/chathistory-3.3.html [server-time]: http://ircv3.net/specs/extensions/server-time-3.2.html -[draft/msgid]: https://github.com/ircv3/ircv3-specifications/pull/285 -[draft/labeled-response]: https://github.com/ircv3/ircv3-specifications/pull/162 +[draft/message-tags]: http://ircv3.net/specs/extensions/message-ids.html +[draft/labeled-response]: http://ircv3.net/specs/extensions/labeled-response.html From d054b8b36da813675d6756267f87ba09df45792f Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Wed, 23 Aug 2017 12:16:57 -0400 Subject: [PATCH 23/27] Remove `draft/` from `CHATHISTORY` command --- extensions/chathistory.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/extensions/chathistory.md b/extensions/chathistory.md index 323706708..b8046a54c 100644 --- a/extensions/chathistory.md +++ b/extensions/chathistory.md @@ -11,7 +11,7 @@ copyrights: ## Notes for implementing work-in-progress version This is a work-in-progress specification. -Software implementing this work-in-progress specification MUST NOT use the unprefixed `CHATHISTORY` command. Instead, implementations SHOULD use the `draft/CHATHISTORY` command to be interoperable with other software implementing a compatible work-in-progress version. +Software implementing this work-in-progress specification MUST NOT use the unprefixed `CHATHISTORY` command. Instead, implementations SHOULD use the `CHATHISTORY` command to be interoperable with other software implementing a compatible work-in-progress version. The final version of the specification will use an unprefixed command. @@ -22,12 +22,12 @@ The `chathistory` extension adds an optional `draft/msgid` to the `chathistory` Clients MUST support the [`batch`][batch] and [`server-time`][server-time] capabilities. Clients SHOULD support the [`draft/labeled-response`][draft/labeled-response] and [`draft/message-tags`][draft/message-tags] capabilities. -When a client with the above mentioned capabilities requests `chathistory` content from the server (using the `draft/CHATHISTORY` command outlined below), the server SHOULD return to the client a single batch containing raw IRC lines starting with and exluduing the `start` parameter and up to and including the message at the `end` parameter. The raw IRC lines SHOULD be formatted and returned to the client as they were originally, with the addition of the above capability tags. +When a client with the above mentioned capabilities requests `chathistory` content from the server (using the `CHATHISTORY` command outlined below), the server SHOULD return to the client a single batch containing raw IRC lines starting with and exluduing the `start` parameter and up to and including the message at the `end` parameter. The raw IRC lines SHOULD be formatted and returned to the client as they were originally, with the addition of the above capability tags. The `server-time` SHOULD be the time at which the message was received from the IRC server and the `batch id` a unique ID for the entire batch. `draft/label` SHOULD be included and MUST be a unique ID used to identify the `chathistory` request and any replies. A `draft/msgid` to identify each individual message MUST be the `draft/msgid` included when each message was first received from the IRC server. ### `CHATHISTORY` Command -`CHATHISTORY` content can be requested by the client to the server by sending the `draft/CHATHISTORY` command to the server. A `batch` MUST be returned by the server. If no content exists to return, an empty batch SHOULD be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick draft/CHATHISTORY=max_message_count :are supported by this server` +`CHATHISTORY` content can be requested by the client to the server by sending the `CHATHISTORY` command to the server. A `batch` MUST be returned by the server. If no content exists to return, an empty batch SHOULD be returned to avoid the client waiting for a reply. Command support is sent to the client as the RPL_ISUPPORT 005 numeric `:irc.host 005 nick CHATHISTORY=max_message_count :are supported by this server` Both the `message_count` and `max_message_count` MUST be integers. `message_count` MUST be a non-zero and `max_message_count` MUST be greater than or equal to zero. The client SHOULD not request a `message_count` with an absolute value greater than the `max_message_count` parameter sent in the command. @@ -40,11 +40,11 @@ The `target` parameter specifies a single channel or query from which history SH #### Format `chathistory` uses the following generic format: - @draft/label=ID draft/CHATHISTORY + @draft/label=ID CHATHISTORY The `chathistory` content can requested using timestamps: - @draft/label=ID draft/CHATHISTORY timestamp=YYYY-MM-DDThh:mm:ss.sssZ message_count= + @draft/label=ID CHATHISTORY timestamp=YYYY-MM-DDThh:mm:ss.sssZ message_count= Alternatively, content can be requested using a `draft/msgid`: @@ -55,7 +55,7 @@ Content can also be requested up to a specified timestamp or `draft/msgid` in pl @draft/label=ID draftCHATHISTORY timestamp= +draft/msgid= #### Errors and Warnings -If the server receives a`draft/CHATHISTORY` command with missing parameters, the `ERR_NEEDMOREPARAMS` error code SHOULD be returned. +If the server receives a`CHATHISTORY` command with missing parameters, the `ERR_NEEDMOREPARAMS` error code SHOULD be returned. If the number of lines between the `start` and `end` parameters exceeds the `max_message_count`, warn code `MAX_MSG_COUNT_EXCEEDED` SHOULD be returned. The command SHOULD continue to be processed as described above. @@ -75,9 +75,9 @@ The examples below are written with `draft/msgid` and `draft/label` tags include #### End :irc.host BATCH -ID #### Error - @draft/label=ID :nick!ident@host draft/CHATHISTORY ERR ERROR_CODE + @draft/label=ID :nick!ident@host CHATHISTORY ERR ERROR_CODE #### Warning - @draft/label=ID :nick!ident@host draft/CHATHISTORY WARN WARN_CODE + @draft/label=ID :nick!ident@host CHATHISTORY WARN WARN_CODE ## Use Cases The batch type and supporting command are useful for allowing an "infinite scroll" type capability within the client. A client will, upon scrolling to the top of the active window or a manual trigger, may request `chathistory` from the server and, after receiving returned content, append it to the top of the window. Users can repeat this historic scrolling to retrieve prior history until limitations are met (see below). @@ -88,9 +88,9 @@ Logging of messages and other actions MUST be enabled server-side and can be sto A method for securely identifying the requesting user MUST exist to ensure content is sent only to the appropriate users and clients. See below for more information. ## Security Considerations -Secure identification of users and clients MUST exist in order to ensure that users cannot obtain history they are not authorized to view. Use of account names, internal account identifiers, or certificate fingerprints SHOULD be strongly considered when matching content to users. The server MUST verify the current user's identity matches that of the desired content. This information is not sent as part of the `draft/CHATHISTORY` command and MUST be validated via other means, such as those stated above. Access MUST be checked first and return an `ERR_NOSUCHNICK` or `ERR_NOSUCHCHANNEL` error as appropriate. If no authorization error exists, the server can check for returnable content. If no returntable content is found, the server MUST send an `ERR_NOTEXTTOSEND` error. The server MUST NOT expose the existence of valid targets to unauthorized users. +Secure identification of users and clients MUST exist in order to ensure that users cannot obtain history they are not authorized to view. Use of account names, internal account identifiers, or certificate fingerprints SHOULD be strongly considered when matching content to users. The server MUST verify the current user's identity matches that of the desired content. This information is not sent as part of the `CHATHISTORY` command and MUST be validated via other means, such as those stated above. Access MUST be checked first and return an `ERR_NOSUCHNICK` or `ERR_NOSUCHCHANNEL` error as appropriate. If no authorization error exists, the server can check for returnable content. If no returntable content is found, the server MUST send an `ERR_NOTEXTTOSEND` error. The server MUST NOT expose the existence of valid targets to unauthorized users. -While a `max_message_count` of 0 MAY be used to indicate no limit exists, servers SHOULD set and enforce a reasonable `max_message_count` and properly throttle `draft/CHATHISTORY` commands to prevent abuse. +While a `max_message_count` of 0 MAY be used to indicate no limit exists, servers SHOULD set and enforce a reasonable `max_message_count` and properly throttle `CHATHISTORY` commands to prevent abuse. ## Current Implementations A ZNC-module implementation exists as [znc-chathistory](https://github.com/MuffinMedic/znc-chathistory). Client-side support for the ZNC module is in progress. Interest in supporting the batch type and command without ZNC has also been obtained, although specifics are not available at this time. From a210bfc0830abca23e3427fc0dafb173e8834bf3 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Wed, 23 Aug 2017 12:56:17 -0400 Subject: [PATCH 24/27] Remove WIP draft prefix requirement --- extensions/chathistory.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/extensions/chathistory.md b/extensions/chathistory.md index b8046a54c..5b480d398 100644 --- a/extensions/chathistory.md +++ b/extensions/chathistory.md @@ -8,13 +8,6 @@ copyrights: period: "2017" email: "evan@muffinmedic.net" --- -## Notes for implementing work-in-progress version -This is a work-in-progress specification. - -Software implementing this work-in-progress specification MUST NOT use the unprefixed `CHATHISTORY` command. Instead, implementations SHOULD use the `CHATHISTORY` command to be interoperable with other software implementing a compatible work-in-progress version. - -The final version of the specification will use an unprefixed command. - ## Description This document describes the format of the `chathistory` extension. The `chathistory` extension uses the [chathistory][batch/chathistory] batch type, adding a client-side command for requesting `chathistory` content from the server. From 4042cec8b02d40a6ab313ce3218a9cbb8e181e70 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Fri, 25 Aug 2017 12:31:32 -0400 Subject: [PATCH 25/27] Change error codes to less-resemble existing numerics --- extensions/chathistory.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/extensions/chathistory.md b/extensions/chathistory.md index 5b480d398..57dd1e925 100644 --- a/extensions/chathistory.md +++ b/extensions/chathistory.md @@ -41,35 +41,34 @@ The `chathistory` content can requested using timestamps: Alternatively, content can be requested using a `draft/msgid`: - @draft/label=ID draftCHATHISTORY draft/msgid= timestamp= + @draft/label=ID CHATHISTORY draft/msgid= timestamp= Content can also be requested up to a specified timestamp or `draft/msgid` in place of the `message_count`. The start and end parameter types do not have to match: - @draft/label=ID draftCHATHISTORY timestamp= +draft/msgid= + @draft/label=ID CHATHISTORY timestamp= +draft/msgid= #### Errors and Warnings -If the server receives a`CHATHISTORY` command with missing parameters, the `ERR_NEEDMOREPARAMS` error code SHOULD be returned. +If the server receives a `CHATHISTORY` command with missing parameters, the `NEED_MORE_PARAMS` error code SHOULD be returned. If the number of lines between the `start` and `end` parameters exceeds the `max_message_count`, warn code `MAX_MSG_COUNT_EXCEEDED` SHOULD be returned. The command SHOULD continue to be processed as described above. -If the target has no `chathistory` content to return or the user does not have permission to view the requested content, `ERR_NOSUCHNICK` or `ERR_NOSUCHCHANNEL` SHOULD be returned accordingly. +If the target has no `chathistory` content to return or the user does not have permission to view the requested content, `ENO_SUCH_NICK` or `NO_SUCH_CHANNEL` SHOULD be returned accordingly. ### Examples The examples below are written with `draft/msgid` and `draft/label` tags included. These tags are recommended. -#### Begin @draft/label=ID :irc.host BATCH +ID chathistory target -#### PRIVMSG + @batch=ID;draft/msgid=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PRIVMSG target :message -#### NOTICE + @batch=ID;draft/msgid=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host NOTICE target :message -#### ACTION + @batch=ID;draft/msgid=ID;time=YYYY-MM-DDThh:mm:ss.sssZ :nick!ident@host PRIVMSG target :ACTION message -#### End + :irc.host BATCH -ID -#### Error - @draft/label=ID :nick!ident@host CHATHISTORY ERR ERROR_CODE -#### Warning + + z + @draft/label=ID :nick!ident@host CHATHISTORY WARN WARN_CODE ## Use Cases @@ -81,7 +80,7 @@ Logging of messages and other actions MUST be enabled server-side and can be sto A method for securely identifying the requesting user MUST exist to ensure content is sent only to the appropriate users and clients. See below for more information. ## Security Considerations -Secure identification of users and clients MUST exist in order to ensure that users cannot obtain history they are not authorized to view. Use of account names, internal account identifiers, or certificate fingerprints SHOULD be strongly considered when matching content to users. The server MUST verify the current user's identity matches that of the desired content. This information is not sent as part of the `CHATHISTORY` command and MUST be validated via other means, such as those stated above. Access MUST be checked first and return an `ERR_NOSUCHNICK` or `ERR_NOSUCHCHANNEL` error as appropriate. If no authorization error exists, the server can check for returnable content. If no returntable content is found, the server MUST send an `ERR_NOTEXTTOSEND` error. The server MUST NOT expose the existence of valid targets to unauthorized users. +Secure identification of users and clients MUST exist in order to ensure that users cannot obtain history they are not authorized to view. Use of account names, internal account identifiers, or certificate fingerprints SHOULD be strongly considered when matching content to users. The server MUST verify the current user's identity matches that of the desired content. This information is not sent as part of the `CHATHISTORY` command and MUST be validated via other means, such as those stated above. Access MUST be checked first and return an `NO_SUCH_NICK` or `NO_SUCH_CHANNEL` error as appropriate. If no authorization error exists, the server can check for returnable content. If no returntable content is found, the server MUST send an `NO_TEXT_TO_SEND` error. The server MUST NOT expose the existence of valid targets to unauthorized users. While a `max_message_count` of 0 MAY be used to indicate no limit exists, servers SHOULD set and enforce a reasonable `max_message_count` and properly throttle `CHATHISTORY` commands to prevent abuse. From 8759f8690b4e51e9f5383780d2ec44b36883314a Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Fri, 25 Aug 2017 12:53:13 -0400 Subject: [PATCH 26/27] e and z --- extensions/chathistory.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/chathistory.md b/extensions/chathistory.md index 57dd1e925..9845bc0e8 100644 --- a/extensions/chathistory.md +++ b/extensions/chathistory.md @@ -52,7 +52,7 @@ If the server receives a `CHATHISTORY` command with missing parameters, the `NEE If the number of lines between the `start` and `end` parameters exceeds the `max_message_count`, warn code `MAX_MSG_COUNT_EXCEEDED` SHOULD be returned. The command SHOULD continue to be processed as described above. -If the target has no `chathistory` content to return or the user does not have permission to view the requested content, `ENO_SUCH_NICK` or `NO_SUCH_CHANNEL` SHOULD be returned accordingly. +If the target has no `chathistory` content to return or the user does not have permission to view the requested content, `NO_SUCH_NICK` or `NO_SUCH_CHANNEL` SHOULD be returned accordingly. ### Examples The examples below are written with `draft/msgid` and `draft/label` tags included. These tags are recommended. @@ -67,7 +67,7 @@ The examples below are written with `draft/msgid` and `draft/label` tags include :irc.host BATCH -ID - z + @draft/label=ID :nick!ident@host CHATHISTORY ERR ERR_CODE @draft/label=ID :nick!ident@host CHATHISTORY WARN WARN_CODE From 02aba740ec6aa877aa14a05b293feb40a75c1138 Mon Sep 17 00:00:00 2001 From: MuffinMedic Date: Fri, 25 Aug 2017 12:55:08 -0400 Subject: [PATCH 27/27] n --- extensions/chathistory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/chathistory.md b/extensions/chathistory.md index 9845bc0e8..19c3857a4 100644 --- a/extensions/chathistory.md +++ b/extensions/chathistory.md @@ -80,7 +80,7 @@ Logging of messages and other actions MUST be enabled server-side and can be sto A method for securely identifying the requesting user MUST exist to ensure content is sent only to the appropriate users and clients. See below for more information. ## Security Considerations -Secure identification of users and clients MUST exist in order to ensure that users cannot obtain history they are not authorized to view. Use of account names, internal account identifiers, or certificate fingerprints SHOULD be strongly considered when matching content to users. The server MUST verify the current user's identity matches that of the desired content. This information is not sent as part of the `CHATHISTORY` command and MUST be validated via other means, such as those stated above. Access MUST be checked first and return an `NO_SUCH_NICK` or `NO_SUCH_CHANNEL` error as appropriate. If no authorization error exists, the server can check for returnable content. If no returntable content is found, the server MUST send an `NO_TEXT_TO_SEND` error. The server MUST NOT expose the existence of valid targets to unauthorized users. +Secure identification of users and clients MUST exist in order to ensure that users cannot obtain history they are not authorized to view. Use of account names, internal account identifiers, or certificate fingerprints SHOULD be strongly considered when matching content to users. The server MUST verify the current user's identity matches that of the desired content. This information is not sent as part of the `CHATHISTORY` command and MUST be validated via other means, such as those stated above. Access MUST be checked first and return a `NO_SUCH_NICK` or `NO_SUCH_CHANNEL` error as appropriate. If no authorization error exists, the server can check for returnable content. If no returntable content is found, the server MUST send a `NO_TEXT_TO_SEND` error. The server MUST NOT expose the existence of valid targets to unauthorized users. While a `max_message_count` of 0 MAY be used to indicate no limit exists, servers SHOULD set and enforce a reasonable `max_message_count` and properly throttle `CHATHISTORY` commands to prevent abuse.