From 00e0eafa0c5e5f5e8facc2009dea2bec5081131f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 29 Nov 2022 19:13:25 -0500 Subject: [PATCH 1/6] add spec for getting events by timestamp --- content/client-server-api/_index.md | 2 + .../room_event_by_timestamp.yaml | 108 ++++++++++++++++++ data/api/server-server/events.yaml | 76 ++++++++++++ 3 files changed, 186 insertions(+) create mode 100644 data/api/client-server/room_event_by_timestamp.yaml diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 6ab6f46a4..e41d3a783 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1816,6 +1816,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 000000000..f09850f6f --- /dev/null +++ b/data/api/client-server/room_event_by_timestamp.yaml @@ -0,0 +1,108 @@ +# 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 Rooms 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. + 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 for, 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 + required: true + origin_server_ts: + type: integer + description: |- + The event's timestamp, in milliseconds since the Unix epoch. + 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 4eef23b65..1068f635c 100644 --- a/data/api/server-server/events.yaml +++ b/data/api/server-server/events.yaml @@ -157,3 +157,79 @@ 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 for, 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 + required: true + origin_server_ts: + type: integer + description: |- + The event's timestamp, in milliseconds since the Unix epoch. + examples: + application/json: { + "event_id": "$143273582443PhrSn:example.org", + "origin_server_ts": 1432735824653 + } From d20eebe2bb37203881807dc9f9fac437d3412e54 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 29 Nov 2022 19:19:24 -0500 Subject: [PATCH 2/6] add error code to federation endpoint --- data/api/server-server/events.yaml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml index 1068f635c..80b454a96 100644 --- a/data/api/server-server/events.yaml +++ b/data/api/server-server/events.yaml @@ -233,3 +233,13 @@ paths: "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" From b12e027fc0b75d01b95d607cf2da466fc2e29b11 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 29 Nov 2022 19:21:49 -0500 Subject: [PATCH 3/6] add changelogs --- changelogs/client_server/newsfragments/1366.feature | 1 + changelogs/server_server/newsfragments/1366.feature | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1366.feature create mode 100644 changelogs/server_server/newsfragments/1366.feature diff --git a/changelogs/client_server/newsfragments/1366.feature b/changelogs/client_server/newsfragments/1366.feature new file mode 100644 index 000000000..42d035f50 --- /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 000000000..228345017 --- /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). From 600330d3be5023ff8c4998c50c8405a6234c8cb7 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 29 Nov 2022 19:31:15 -0500 Subject: [PATCH 4/6] fix schema --- data/api/client-server/room_event_by_timestamp.yaml | 2 +- data/api/server-server/events.yaml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/data/api/client-server/room_event_by_timestamp.yaml b/data/api/client-server/room_event_by_timestamp.yaml index f09850f6f..fb3b9c833 100644 --- a/data/api/client-server/room_event_by_timestamp.yaml +++ b/data/api/client-server/room_event_by_timestamp.yaml @@ -80,11 +80,11 @@ paths: type: string description: |- The ID of the event found - required: true 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", diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml index 80b454a96..975b3dab4 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. @@ -223,11 +223,11 @@ paths: type: string description: |- The ID of the event found - required: true 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", From 1639b642858944eaad3de7647e17a2e5594af27e Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 30 Nov 2022 09:27:52 -0500 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Eric Eastwood --- data/api/client-server/room_event_by_timestamp.yaml | 7 +++++-- data/api/server-server/events.yaml | 2 +- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/data/api/client-server/room_event_by_timestamp.yaml b/data/api/client-server/room_event_by_timestamp.yaml index fb3b9c833..cfb12c456 100644 --- a/data/api/client-server/room_event_by_timestamp.yaml +++ b/data/api/client-server/room_event_by_timestamp.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Client-Server Rooms by date API" + title: "Matrix Client-Server events in room by date API" version: "1.0.0" host: localhost:8008 schemes: @@ -57,7 +57,7 @@ paths: type: integer name: ts description: |- - The timestamp to search for, as given in milliseconds + The timestamp to search from, as given in milliseconds since the Unix epoch. required: true x-example: 1432684800000 @@ -84,6 +84,9 @@ paths: 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: { diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml index 975b3dab4..427978fbb 100644 --- a/data/api/server-server/events.yaml +++ b/data/api/server-server/events.yaml @@ -200,7 +200,7 @@ paths: type: integer name: ts description: |- - The timestamp to search for, as given in milliseconds + The timestamp to search from, as given in milliseconds since the Unix epoch. required: true x-example: 1432684800000 From a29b5204e0c6249410e177a2baebebc4b0c0549f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 15 Dec 2022 20:43:36 -0500 Subject: [PATCH 6/6] add hint about receiving unrenderable events --- data/api/client-server/room_event_by_timestamp.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/data/api/client-server/room_event_by_timestamp.yaml b/data/api/client-server/room_event_by_timestamp.yaml index cfb12c456..7b3609215 100644 --- a/data/api/client-server/room_event_by_timestamp.yaml +++ b/data/api/client-server/room_event_by_timestamp.yaml @@ -43,6 +43,18 @@ paths: 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: []