From 59e9dfdf84b6cf26225a2a633670bab5336f50d8 Mon Sep 17 00:00:00 2001 From: Simon Ser Date: Fri, 2 Jun 2023 11:23:21 +0200 Subject: [PATCH] chathistory: add cursors This improves reliability of timestamp-based queries by using an opaque cursor. A message at a page boundary can be missed by a client if one of its neighbours has the same timestamp. --- extensions/chathistory.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/extensions/chathistory.md b/extensions/chathistory.md index db65e7f6b..20f595312 100644 --- a/extensions/chathistory.md +++ b/extensions/chathistory.md @@ -59,12 +59,12 @@ If `MSGREFTYPES` is missing, clients SHOULD assume the server supports both and ### `CHATHISTORY` Command The client can request message history content by sending the `CHATHISTORY` command to the server. This command has the following general syntax: - CHATHISTORY [] + CHATHISTORY [] CHATHISTORY TARGETS The `target` parameter specifies a single buffer (channel or nickname) from which history is to be retrieved. If a nickname is given as the `target` then the server SHOULD include history sent between the current user and the target nickname, including outgoing messages ("self messages"). The server SHOULD attempt to include history involving other nicknames if either the current user or the target nickname has changed during the requested timeframe. -A `timestamp` parameter MUST have the format `timestamp=YYYY-MM-DDThh:mm:ss.sssZ`, as in the [server-time][server-time] extension. A `msgid` parameter MUST have the format `msgid=foobar`, as in the [message-ids][message-ids] extension. +A `timestamp` parameter MUST have the format `timestamp=YYYY-MM-DDThh:mm:ss.sssZ`, as in the [server-time][server-time] extension. A `msgid` parameter MUST have the format `msgid=foobar`, as in the [message-ids][message-ids] extension. A `cursor` parameter MUST have the format `cursor=foobar`. If the `batch` capability was negotiated, the server MUST reply to a successful `CHATHISTORY` command using a [`batch`][batch]. For subcommands that return message history (i.e. all subcommands other than `TARGETS`), the batch MUST have type `chathistory` and take a single additional parameter, the canonical name of the target being queried. For `TARGETS`, the batch MUST have type `draft/chathistory-targets`. If no content exists to return, the server SHOULD return an empty batch in order to avoid the client waiting for a reply. @@ -76,19 +76,19 @@ The following subcommands are used to return message history relative to `timest #### `BEFORE` - CHATHISTORY BEFORE + CHATHISTORY BEFORE Request up to `limit` number of messages before and excluding the given `timestamp` or `msgid`. Only one timestamp or msgid MUST be given, not both. #### `AFTER` - CHATHISTORY AFTER + CHATHISTORY AFTER Request up to `limit` number of messages after and excluding the given `timestamp` or `msgid`. Only one timestamp or msgid MUST be given, not both. #### `LATEST` - CHATHISTORY LATEST <* | timestamp=YYYY-MM-DDThh:mm:ss.sssZ | msgid=1234> + CHATHISTORY LATEST <* | timestamp=YYYY-MM-DDThh:mm:ss.sssZ | msgid=1234 | cursor=1234> Request up to `limit` number of the most recent messages that have been sent. If a `timestamp` or `msgid` is given, the returned messages are restricted to those sent after and excluding that timestamp or msgid; if a `*` is given, no such restriction applies. If a `*` is not given, only one timestamp or msgid MUST be given, not both. @@ -104,10 +104,18 @@ This is useful for retrieving conversation context around a single message. #### `BETWEEN` - CHATHISTORY BETWEEN + CHATHISTORY BETWEEN Request up to `limit` number of messages between the given `timestamp` or `msgid` values. With respect to the limit, the returned messages MUST be counted starting from and excluding the first message selector, while finishing on and excluding the second. This may be forwards or backwards in time. +#### `CURSORS` + +All commands above MAY return a `CHATHISTORY CURSORS` message. There MUST NOT be more than one message returned. If returned, that message MUST be the first one in the batch. + + CHATHISTORY CURSORS [prev] + +`next` is a a cursor which can be used to query the next page of messages. `prev` is a cursor which can be used to query the previous page of messages, it MUST only be returned in response to `CHATHISTORY AROUND`. + #### `TARGETS` Unlike the other subcommands, `TARGETS` does not return message history. Instead, it lists channels the user has visible history in, together with users with which the user has exchanged direct messages, ordered by the time of the latest message in the channel history or direct message conversation (i.e. sent from or to the other user). This allows the client to discover missed direct message conversations with users it is not currently aware of.