Add spec for getting events by timestamp (matrix-org#1366)

changelogs/client_server/newsfragments/1366.feature

@@ -0,0 +1 @@
+Add `/rooms/<roomID>/timestamp_to_event` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030).

changelogs/server_server/newsfragments/1366.feature

@@ -0,0 +1 @@
+Add `/timestamp_to_event/<roomID>` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030).

content/client-server-api/_index.md

@@ -1818,6 +1818,8 @@ There are several APIs provided to `GET` events for a room:
 
 {{% http-api spec="client-server" api="message_pagination" %}}
 
+{{% http-api spec="client-server" api="room_event_by_timestamp" %}}
+
 {{% http-api spec="client-server" api="room_initial_sync" %}}
 
 ### Sending events to a room

data/api/client-server/room_event_by_timestamp.yaml

@@ -0,0 +1,123 @@
+# Copyright 2022 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server events in room by date API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/rooms/{roomId}/timestamp_to_event":
+    get:
+      x-addedInMatrixVersion: "1.6"
+      summary: Get the closest event ID to the given timestamp
+      description: |-
+        Get the ID of the event closest to the given timestamp, in the
+        direction specified by the `dir` parameter.
+
+        If the server does not have all of the room history and does not have
+        an event suitably close to the requested timestamp, it can use the
+        corresponding [federation endpoint](/server-server-api/#get_matrixfederationv1timestamp_to_eventroomid)
+        to ask other servers for a suitable event.
+
+        After calling this endpoint, clients can call
+        [`/rooms/{roomId}/context/{eventId}`](#get_matrixclientv3roomsroomidcontexteventid)
+        to obtain a pagination token to retrieve the events around the returned event.
+
+        The event returned by this endpoint could be an event that the client
+        cannot render, and so may need to paginate in order to locate an event
+        that it can display, which may end up being outside of the client's
+        suitable range.  Clients can employ different strategies to display
+        something reasonable to the user.  For example, the client could try
+        paginating in one direction for a while, while looking at the
+        timestamps of the events that it is paginating through, and if it
+        exceeds a certain difference from the target timestamp, it can try
+        paginating in the opposite direction.  The client could also simply
+        paginate in one direction and inform the user that the closest event
+        found in that direction is outside of the expected range.
+      operationId: getEventByTimestamp
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The ID of the room to search
+          required: true
+          x-example: "!636q39766251:matrix.org"
+        - in: query
+          type: integer
+          name: ts
+          description: |-
+            The timestamp to search from, as given in milliseconds
+            since the Unix epoch.
+          required: true
+          x-example: 1432684800000
+        - in: query
+          type: string
+          enum: [f, b]
+          name: dir
+          description: |-
+            The direction in which to search.  `f` for forwards, `b` for backwards.
+          required: true
+          x-example: f
+      responses:
+        200:
+          description: |-
+            An event was found matching the search parameters.
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  The ID of the event found
+              origin_server_ts:
+                type: integer
+                description: |-
+                  The event's timestamp, in milliseconds since the Unix epoch.
+                  This makes it easy to do a quick comparison to see if the
+                  `event_id` fetched is too far out of range to be useful for your
+                  use case.
+            required: ['event_id', 'origin_server_ts']
+          examples:
+            application/json: {
+                "event_id": "$143273582443PhrSn:example.org",
+                "origin_server_ts": 1432735824653
+              }
+        404:
+          description: |-
+            No event was found.
+          examples:
+            application/json: {
+                "errcode": "M_NOT_FOUND",
+                "error": "Unable to find event from 1432684800000 in forward direction"
+              }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Room participation

data/api/server-server/events.yaml

@@ -1,4 +1,4 @@
-# Copyright 2018 New Vector Ltd
+# Copyright 2018-2020 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -157,3 +157,89 @@ paths:
           description: A transaction containing a single PDU which is the event requested.
           schema:
             $ref: "definitions/single_pdu_transaction.yaml"
+  "/timestamp_to_event/{roomId}":
+    get:
+      summary: Get the closest event ID to the given timestamp
+      x-addedInMatrixVersion: "1.6"
+      description: |-
+        Get the ID of the event closest to the given timestamp, in the
+        direction specified by the `dir` parameter.
+
+        This is primarily used when handling the corresponding
+        [client-server endpoint](/client-server-api/#get_matrixclientv1roomsroomidtimestamp_to_event)
+        when the server does not have all of the room history, and does not
+        have an event suitably close to the requested timestamp.
+
+        The heuristics for deciding when to ask another homeserver for a closer
+        event if your homeserver doesn't have something close, are left up to
+        the homeserver implementation, although the heuristics will probably be
+        based on whether the closest event is a forward/backward extremity
+        indicating it's next to a gap of events which are potentially closer.
+
+        A good heuristic for which servers to try first is to sort by servers
+        that have been in the room the longest because they're most likely to
+        have anything we ask about.
+
+        After the local homeserver receives the response, it should determine,
+        using the `origin_server_ts` property, whether the returned event is
+        closer to the requested timestamp than the closest event that it could
+        find locally.  If so, it should try to backfill this event via the
+        [`/event/{event_id}`](#get_matrixfederationv1eventeventid) endpoint so
+        that it is available to for a client to query.
+      operationId: getEventByTimestamp
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The ID of the room to search
+          required: true
+          x-example: "!636q39766251:matrix.org"
+        - in: query
+          type: integer
+          name: ts
+          description: |-
+            The timestamp to search from, as given in milliseconds
+            since the Unix epoch.
+          required: true
+          x-example: 1432684800000
+        - in: query
+          type: string
+          enum: [f, b]
+          name: dir
+          description: |-
+            The direction in which to search.  `f` for forwards, `b` for backwards.
+          required: true
+          x-example: f
+      responses:
+        200:
+          description: |-
+            An event was found matching the search parameters.
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  The ID of the event found
+              origin_server_ts:
+                type: integer
+                description: |-
+                  The event's timestamp, in milliseconds since the Unix epoch.
+            required: ['event_id', 'origin_server_ts']
+          examples:
+            application/json: {
+                "event_id": "$143273582443PhrSn:example.org",
+                "origin_server_ts": 1432735824653
+              }
+        404:
+          description: |-
+            No event was found.
+          examples:
+            application/json: {
+                "errcode": "M_NOT_FOUND",
+                "error": "Unable to find event from 1432684800000 in forward direction"
+              }
+          schema:
+            "$ref": "../client-server/definitions/errors/error.yaml"