Skip to content

Commit

Permalink
Wrap lines to 120 chars
Browse files Browse the repository at this point in the history
  • Loading branch information
alfogrillo committed May 29, 2023
1 parent a5f7d0e commit 4623275
Showing 1 changed file with 18 additions and 7 deletions.
25 changes: 18 additions & 7 deletions proposals/4013-poll-history-cache.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,18 @@ The purpose of this MSC is to allow clients to quickly fetch all the polls in a

## Problem

Clients sometimes may want to access quickly to all the polls sent in a given room (similarly to how they may want to access all the media being sent in a room).
Today clients don’t have an efficient way to make such an operation. Clients that want to implement this feature for encrypted rooms on the status quo may need to backward paginate on the room’s timeline until all the polls are found or they reach the beginning of the timeline.
For unencrypted rooms the problem doesn't exist since clients can call the [messages API](https://spec.matrix.org/v1.6/client-server-api/#get_matrixclientv3roomsroomidmessages) filtering by event type (e.g. by `m.poll.start`).
Clients sometimes may want to access quickly to all the polls sent in a given room (similarly to how they may want to
access all the media being sent in a room).Today clients don’t have an efficient way to make such an operation.
Clients that want to implement this feature for encrypted rooms on the status quo may need to backward paginate on the
room’s timeline until all the polls are found or they reach the beginning of the timeline. For unencrypted rooms the
problem doesn't exist since clients can call the
[messages API](https://spec.matrix.org/v1.6/client-server-api/#get_matrixclientv3roomsroomidmessages)
filtering by event type (e.g. by `m.poll.start`).

## Proposal

Introduce a new state event `m.room.poll_history`. This state event is supposed to be referenced by any `m.poll.start` that will be sent next in the room. The new state event must have an empty string as `state_key`.
Introduce a new state event `m.room.poll_history`. This state event is supposed to be referenced by any `m.poll.start`
that will be sent next in the room. The new state event must have an empty string as `state_key`.
More information on polls can be found on the [MSC3381](https://github.com/matrix-org/matrix-spec-proposals/pull/3381).

This is how the new state event would look like:
Expand All @@ -30,7 +35,8 @@ This is how the new state event would look like:
- [MSC3381](https://github.com/matrix-org/matrix-spec-proposals/pull/338)

## Client behaviour
First of all a room creator sends the new `m.room.poll_history` state event in the `initial_state` when calling the [createRoom API](https://spec.matrix.org/v1.6/client-server-api/#post_matrixclientv3createroom).
First of all a room creator sends the new `m.room.poll_history` state event in the `initial_state` when calling the
[createRoom API](https://spec.matrix.org/v1.6/client-server-api/#post_matrixclientv3createroom).

For example the body when creating a new encrypted room would look like this:

Expand Down Expand Up @@ -85,13 +91,18 @@ Any time a client starts a new poll, it also includes a reference to the above s

Clients can now use the event relationship to fetch the history of polls in the room:

1. They call the [relations API](https://spec.matrix.org/v1.6/client-server-api/#get_matrixclientv1roomsroomidrelationseventid) with the new state event’s event identifier (`poll_history_id` in the example). Since the API takes a timeline direction and a pagination token, clients still have the flexibility to decide how many polls they want to fetch in a given room and in which direction.
1. They call the [relations API](https://spec.matrix.org/v1.6/client-server-api/#get_matrixclientv1roomsroomidrelationseventid)
with the new state event’s event identifier (`poll_history_id` in the example). Since the API takes a timeline direction
and a pagination token, clients still have the flexibility to decide how many polls they want to fetch in a given room
and in which direction.

The request would look like this:

`/_matrix/client/v1/rooms/{Room ID}/relations/poll_history_id/m.reference?from=from_token&dir=b&limit=100`

The [response](https://spec.matrix.org/v1.6/client-server-api/#server-side-aggregation-of-mreference) will contain an array of related event identifiers. In encrypted rooms these events have likely the type `m.room.encrypted`. After the decryption clients should keep just decrypted events of type `m.poll.start`.
The [response](https://spec.matrix.org/v1.6/client-server-api/#server-side-aggregation-of-mreference) will contain
an array of related event identifiers. In encrypted rooms these events have likely the type `m.room.encrypted`.
After the decryption clients should keep just decrypted events of type `m.poll.start`.
4. For each event `id_some` kept from the previous step, clients need to make the poll aggregation either by fetching data from a local database (if available) or by calling again the relations API again with the `id_some` event id. At this point clients have all the information they need to build the full poll history.

## Potential issues
Expand Down

0 comments on commit 4623275

Please sign in to comment.