chathistory: Add MSGREFTYPES ISUPPORT token (#510)

Author: progval

extensions/chathistory.md

@@ -14,6 +14,10 @@ copyrights:
     name: "Shivaram Lingamneni"
     period: "2020"
     email: "[email protected]"
+  -
+    name: "Val Lorentz"
+    period: "2022"
+    email: "[email protected]"
 ---
 
 ## Notes for implementing work-in-progress version
@@ -36,10 +40,22 @@ Full support for this extension requires support for the [`batch`][batch], [`ser
 
 The `draft/chathistory` capability MUST be negotiated. This allows the server and client to behave differently when history is available and can be queried. In particular, if a client requests this capability, the server (or bouncer) SHOULD NOT play back any history that would otherwise be sent automatically.
 
-An ISUPPORT token MUST be sent to the client to state the maximum number of messages a client can request in a single command, e.g., `CHATHISTORY=50`. If `0`, the client SHOULD assume that there is no maximum number of messages.
-
 The `draft/event-playback` capability MAY be negotiated. This allows the client to signal that it is capable of receiving and correctly processing lines that would normally produce a local state change (such as `JOIN` or `MODE`) in its history batches.
 
+### ISUPPORT tokens
+
+This specification defines two ISUPPORT tokens.
+
+`CHATHISTORY` MUST be sent to the client to state the maximum number of messages a client can request in a single command, e.g., `CHATHISTORY=50`. If `0`, the client SHOULD assume that there is no maximum number of messages.
+
+`MSGREFTYPES` SHOULD be sent, with a comma-separated list of types of message references they support as parameter to `CHATHISTORY` commands, in order of decreasing preference. Clients MUST ignore any type they do not support. The currently defined list of types is:
+
+* `timestamp`, to reference messages by their timestamp
+* `msgid`, to reference them by their `msgid`
+
+If `MSGREFTYPES` is missing, clients SHOULD assume the server supports both and has no preference.
+
+
 ### `CHATHISTORY` Command
 The client can request message history content by sending the `CHATHISTORY` command to the server. This command has the following general syntax:
 
@@ -129,6 +145,10 @@ If no message history can be returned due to an error, the `MESSAGE_ERROR` error
 
     FAIL CHATHISTORY MESSAGE_ERROR the_given_command the_given_target [extra_context] :Messages could not be retrieved
 
+If a client used a reference type (`timestamp=` or `msgid=`) the server does not support, the `INVALID_MSGREFTYPE` error code SHOULD be returned:
+
+    FAIL CHATHISTORY INVALID_MSGREFTYPE the_given_command the_given_target [extra_context] :msgid-based history requests are not supported
+
 ### Examples
 
 Requesting the latest conversation upon joining a channel