3.7 KiB
MSC3523: Timeboxed/ranged relations endpoint
MSC2675 defines a new /relations endpoint
which clients can use to get information about reactions, replies, edits, etc made to an event, however
the endpoint assumes that all events can indefinitely receive changes. For some cases, namely
polls, the client will need to ignore responses
added to a poll after the poll closes.
This proposal introduces additional query parameters to the /relations endpoint to allow clients to
filter the relations down to a specific time period. Clients implementing polls can then use these
parameters to only find responses up until the poll was closed, preventing a case where the server
needs to handle all the rules for polls itself.
Proposal
Two new query parameters are added to MSC2675's
/relations endpoint:
?from_target=[number|event ID]- Optional. The unix timestamp or event ID to start considering relations for the response, inclusive. If ommitted, the start point is unbounded.?to_target=[number|event ID]- Optional. The unix timestamp or event ID to stop considering relations for the response, inclusive. If omitted, the end point is unbounded.
Note: The slightly awkward naming is to avoid conflict/confusion with pagination.
A mix of timestamps and event IDs is permitted (ie: from_target=1637701025885&to_target=$poll_end).
Timestamps are anticipated to be used when the client isn't sure when an event happened, or if the linearized DAG is not an accurate representation of the client's requirements. Event IDs are expected to be used when the client wants to know what happened between two points, such as in the case of backfilling a gappy/limited sync.
The server's handling of relations between event IDs is very similar to how it processes
/messages.
The DAG is linearized and relations between the start and end point are considered.
The response is not changed by this proposal. Repeated calls using the pagination tokens will need
to specify the same from_target and to_target values in order to maintain accurate paging.
Potential issues
For application-specific uses, such as polls, it's possible that clients end up using the wrong combination of timestamps and event IDs. Clients are encouraged to be cautious of this risk, and features which have a potential for concern should be explicit about what shape of the endpoint should be called.
There's not currently a forseeable use case for a from_target or even using event IDs as bounding
points, however the proposal author believes that 2-4 MSCs for related functionality feels needlessly
complicated.
Alternatives
Unclear - the client could try and use /messages to backfill everything, but that seems very
inefficient when trying to get aggregated information about relationships.
Security considerations
Denial of service style attacks are possible, but mitigated with rate limiting and servers setting sensible limits on the to/from range. For example, servers can retrieve all relations like it normally would for the event referenced in the endpoint path then filter down from that set. Servers are strongly discouraged from implementations which walk the DAG between the range points as the caller might very well specify a start point of the room's create event and an end point of hundreds of years into the future.
Unstable prefix
While this MSC is not considered stable, the following transformations apply:
from_target->org.matrix.msc3523.from_targetto_target->org.matrix.msc3523.to_target