From 94465fe93b7195f67ff90908dcf4a2757b136f4a Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 21 Dec 2022 14:05:28 -0500 Subject: [PATCH] Add spec for getting events by timestamp (#1366) --- .../client_server/newsfragments/1366.feature | 1 + .../server_server/newsfragments/1366.feature | 1 + content/client-server-api/_index.md | 2 + .../room_event_by_timestamp.yaml | 123 ++++++++++++++++++ data/api/server-server/events.yaml | 88 ++++++++++++- 5 files changed, 214 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1366.feature create mode 100644 changelogs/server_server/newsfragments/1366.feature create mode 100644 data/api/client-server/room_event_by_timestamp.yaml diff --git a/changelogs/client_server/newsfragments/1366.feature b/changelogs/client_server/newsfragments/1366.feature new file mode 100644 index 00000000..42d035f5 --- /dev/null +++ b/changelogs/client_server/newsfragments/1366.feature @@ -0,0 +1 @@ +Add `/rooms//timestamp_to_event` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030). diff --git a/changelogs/server_server/newsfragments/1366.feature b/changelogs/server_server/newsfragments/1366.feature new file mode 100644 index 00000000..22834501 --- /dev/null +++ b/changelogs/server_server/newsfragments/1366.feature @@ -0,0 +1 @@ +Add `/timestamp_to_event/` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index fe111f18..06318ae3 100644 --- a/content/client-server-api/_index.md +++ b/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 diff --git a/data/api/client-server/room_event_by_timestamp.yaml b/data/api/client-server/room_event_by_timestamp.yaml new file mode 100644 index 00000000..7b360921 --- /dev/null +++ b/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 diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml index 4eef23b6..427978fb 100644 --- a/data/api/server-server/events.yaml +++ b/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"