From d494e642db0950b8fa5d0a7a65ba1b70735a82b4 Mon Sep 17 00:00:00 2001 From: Eric Eastwood Date: Thu, 13 Apr 2023 15:45:21 -0500 Subject: [PATCH 1/4] Skeleton MSC --- ...-timestamp-to-event-causality-parameter.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 proposals/0000-timestamp-to-event-causality-parameter.md diff --git a/proposals/0000-timestamp-to-event-causality-parameter.md b/proposals/0000-timestamp-to-event-causality-parameter.md new file mode 100644 index 00000000000..71bee7f9dcb --- /dev/null +++ b/proposals/0000-timestamp-to-event-causality-parameter.md @@ -0,0 +1,24 @@ +# MSC0000: Template for new MSCs + + + + +## Proposal + + +## Potential issues + + + + +## Alternatives + + + + +## Security considerations + + + +## Unstable prefix + From 14ade12110c3b521caba37bafaf4d218ad1415a5 Mon Sep 17 00:00:00 2001 From: Eric Eastwood Date: Fri, 14 Apr 2023 06:02:06 -0500 Subject: [PATCH 2/4] Add iniitial proposal for /timestamp_to_event?event_id=$123 causal parameter --- ...-timestamp-to-event-causality-parameter.md | 109 +++++++++++++++++- 1 file changed, 107 insertions(+), 2 deletions(-) diff --git a/proposals/0000-timestamp-to-event-causality-parameter.md b/proposals/0000-timestamp-to-event-causality-parameter.md index 71bee7f9dcb..b374a69dae0 100644 --- a/proposals/0000-timestamp-to-event-causality-parameter.md +++ b/proposals/0000-timestamp-to-event-causality-parameter.md @@ -1,24 +1,129 @@ -# MSC0000: Template for new MSCs +# MSCXXXX: Add causal parameter to `/timestamp_to_event` +Causality just means being able to know "A happened before B" or vice versa. +Because `origin_server_ts` on an event is untrusted and can be set to whatever value, +using `/timestamp_to_event` can give you rogue results or even make you paginate in +loops. `/timestamp_to_event` was originally introduced in +[MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030/) where this +rogue result problem was first mentioned. + +For example even in a simple good intentioned case, you create a new room which puts all +of the primordial creation events at time X. You then send some messages using timestamp +massaging (`/send?ts=123`) at a time before X (this is exactly what we did with the +Gitter historical import). The problem occurs when you use +`/timestamp_to_event?dir=f&ts=123` because you will end up looping back to the +`m.room.create` that comes after. + +In less scrupulous scenarios or with bad intentioned actors, these timestamp loops can +occur throughout the room timeline. + +These loops make it hard properly navigate from page to page in the [Matrix Public +Archive](https://github.com/matrix-org/matrix-public-archive) where you view a given +date in the room and use `/timestamp_to_event` to jump to the next page. ## Proposal +Instead of only defining a timestamp, we add an optional `event_id` query parameter +which represents a topological spot in the DAG that we can easily determine what comes +before or after from (a casual relationship). -## Potential issues + - `/timestamp_to_event?dir=f&ts=123&event_id=$abc` means we find the closest event from + `ts` looking forwards after `event_id` + - `/timestamp_to_event?dir=B&ts=123&event_id=$abc` means we find the closest event from + `ts` looking backwards before `event_id` + +It essentially acts as a signal to keep progressing from this event regardless of what +timestamp shenagins are going on. + + +### Further explanation/example + +To explain how this new `event_id` causuality parameter helps, using the following +example DAG: + +```mermaid +flowchart LR + A["A (ts=100)"] ---> B["B (ts=50)"] ---> C["C (ts=999)"] ---> D["D (ts=200)"] ---> E["E (ts=300)"] +``` + +When looking forwards from event `$E`: + + - With `?event_id`: `/timestamp_to_event?dir=f&ts=500&event_id=$E` -> `404` `{ "errcode": "M_NOT_FOUND", "error":"Unable to find event +from 400 in direction f" }` end of the room as expected ✅ + - Without: `/timestamp_to_event?dir=f&ts=500` -> `{ "event_id": "$C", "origin_server_ts": 999 }` (we just looped back to the middle of the timeline 😵) + +When looking backwards from event `$A`: + + - With `?event_id`: `/timestamp_to_event?dir=b&ts=100&event_id=$A` -> -> `404` `{ "errcode": "M_NOT_FOUND", "error":"Unable to find event +from 400 in direction f" }` before the start of the room as expected ✅ + - Without: `/timestamp_to_event?dir=b&ts=100` -> `{ "event_id": "$B", "origin_server_ts": 50 }` (we just looped back to the middle of the room 😵) + +--- +Random keyword: circular reference +### Client usage + +Basic jump to date client usage will not need or want to use this new `event_id` +parameter as you're just jumping in blind to a certain spot in the timeline without +events to reference. + +It's possible to add some client complexity to use their existing timeline of events and +add some `?event_id` that fits the bill to ensure they keep moving in the desired +direction. This is basically what Matrix Public Archive will probably do. + + +## Potential issues + +While you can still receive a rogue out of place event using `/timestamp_to_event`, we +can at least gurantee that the event comes before or after the given `?event_id` casual +query parameter. + ## Alternatives +For the good intention Gitter case explained in the intro where the only problem is +looping around to the `m.room.create` event, we can probably easily detect that type of +thing since `m.room.create` will always be the first event in the room and we can assume +that we reached the end of the room from our history messages. Which means we can go to +the replacement successor room instead of looping to the beginning of the room again. +But this problem is way broader in other rooms than just this case (a loop can occur +anywhere) so something like this MSC is still necessary. ## Security considerations +No extra data is exposed. It's just a new way to filter it down and sort through it all. ## Unstable prefix +While this feature is in development, the `event_id` querystring parameter can be used as +`org.matrix.mscXXXX.event_id` + +### While the MSC is unstable + +During this period, to detect server support clients should check for the presence of +the `org.matrix.mscXXXX` flag in `unstable_features` on `/versions`. Clients are also +required to use the unstable prefixes (see [unstable prefix](#unstable-prefix)) during +this time. + +### Once the MSC is merged but not in a spec version + +Once this MSC is merged, but is not yet part of the spec, clients should rely on the +presence of the `org.matrix.mscXXXX.stable` flag in `unstable_features` to determine +server support. If the flag is present, clients are required to use stable prefixes (see +[unstable prefix](#unstable-prefix)). + +### Once the MSC is in a spec version + +Once this MSC becomes a part of a spec version, clients should rely on the presence of +the spec version, that supports the MSC, in `versions` on `/versions`, to determine +support. Servers are encouraged to keep the `org.matrix.mscXXXX.stable` flag around for +a reasonable amount of time to help smooth over the transition for clients. "Reasonable" +is intentionally left as an implementation detail, however the MSC process currently +recommends *at most* 2 months from the date of spec release. From e88a3e810fbc090d30360decc0066d2a000cbb1b Mon Sep 17 00:00:00 2001 From: Eric Eastwood Date: Fri, 14 Apr 2023 06:07:39 -0500 Subject: [PATCH 3/4] Use MSC number --- ...d => 3999-timestamp-to-event-causal-parameter.md} | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) rename proposals/{0000-timestamp-to-event-causality-parameter.md => 3999-timestamp-to-event-causal-parameter.md} (94%) diff --git a/proposals/0000-timestamp-to-event-causality-parameter.md b/proposals/3999-timestamp-to-event-causal-parameter.md similarity index 94% rename from proposals/0000-timestamp-to-event-causality-parameter.md rename to proposals/3999-timestamp-to-event-causal-parameter.md index b374a69dae0..5248c8e5353 100644 --- a/proposals/0000-timestamp-to-event-causality-parameter.md +++ b/proposals/3999-timestamp-to-event-causal-parameter.md @@ -1,4 +1,4 @@ -# MSCXXXX: Add causal parameter to `/timestamp_to_event` +# MSC3999: Add causal parameter to `/timestamp_to_event` Causality just means being able to know "A happened before B" or vice versa. @@ -35,7 +35,7 @@ before or after from (a casual relationship). `ts` looking backwards before `event_id` It essentially acts as a signal to keep progressing from this event regardless of what -timestamp shenagins are going on. +timestamp shenanigans are going on. ### Further explanation/example @@ -103,19 +103,19 @@ No extra data is exposed. It's just a new way to filter it down and sort through ## Unstable prefix While this feature is in development, the `event_id` querystring parameter can be used as -`org.matrix.mscXXXX.event_id` +`org.matrix.msc3999.event_id` ### While the MSC is unstable During this period, to detect server support clients should check for the presence of -the `org.matrix.mscXXXX` flag in `unstable_features` on `/versions`. Clients are also +the `org.matrix.msc3999` flag in `unstable_features` on `/versions`. Clients are also required to use the unstable prefixes (see [unstable prefix](#unstable-prefix)) during this time. ### Once the MSC is merged but not in a spec version Once this MSC is merged, but is not yet part of the spec, clients should rely on the -presence of the `org.matrix.mscXXXX.stable` flag in `unstable_features` to determine +presence of the `org.matrix.msc3999.stable` flag in `unstable_features` to determine server support. If the flag is present, clients are required to use stable prefixes (see [unstable prefix](#unstable-prefix)). @@ -123,7 +123,7 @@ server support. If the flag is present, clients are required to use stable prefi Once this MSC becomes a part of a spec version, clients should rely on the presence of the spec version, that supports the MSC, in `versions` on `/versions`, to determine -support. Servers are encouraged to keep the `org.matrix.mscXXXX.stable` flag around for +support. Servers are encouraged to keep the `org.matrix.ms3999.stable` flag around for a reasonable amount of time to help smooth over the transition for clients. "Reasonable" is intentionally left as an implementation detail, however the MSC process currently recommends *at most* 2 months from the date of spec release. From 88bbd0b03284fbac6e9dce1e200a6284b6ee16ab Mon Sep 17 00:00:00 2001 From: Eric Eastwood Date: Fri, 14 Apr 2023 06:11:12 -0500 Subject: [PATCH 4/4] Fix typo --- proposals/3999-timestamp-to-event-causal-parameter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3999-timestamp-to-event-causal-parameter.md b/proposals/3999-timestamp-to-event-causal-parameter.md index 5248c8e5353..0a5bebd2a4e 100644 --- a/proposals/3999-timestamp-to-event-causal-parameter.md +++ b/proposals/3999-timestamp-to-event-causal-parameter.md @@ -79,7 +79,7 @@ direction. This is basically what Matrix Public Archive will probably do. ## Potential issues While you can still receive a rogue out of place event using `/timestamp_to_event`, we -can at least gurantee that the event comes before or after the given `?event_id` casual +can at least guarantee that the event comes before or after the given `?event_id` casual query parameter.