adr006-use-event-relations-for-topic-submissions.md

ADR006: Use event relations for topic submissions

Status: accepted

Context

The barcamp widget allows users to submit topics they want to discuss. These topics are stored as Matrix room events that the users send into the room (see ADR004).

But there are limitations on the data quality that the Widget API provides for these kinds of events. It is based on the Client's (ex: Element) local timeline, which provides all available state events (ex: tracks), but might only provide a limited window of room events (ex: submissions) of the complete room timeline. This leads to the situation where the widget can't be sure whether all topics that are available on the homeserver are also made available by the Widget API. “Event Relationships” and “Serverside aggregations of message relationships” are features of the Client-Server API that allows us to relate events to each other and retrieve a collection of related events from the server. MSC3869 brings this feature to the Widget API and enables us to provide a reliable and deterministic way to load elements in the widget.

We want to be able to use readEventRelations of MSC3869 instead of receiveRoomEvents to read the topic submissions. We accept that the described guarantees will only apply to submissions that are created after this change. We won't upgrade existing session grids with this feature.

Decision

1. We will emit a new net.nordeck.barcamp.session_grid.start event when a session grid is created:

   # the type of event
   type: 'net.nordeck.barcamp.session_grid.start'
   
   # the room of the event
   room_id: '!my-room:…'
   
   # the user that created the session grid.
   sender: '@user-id'
   
   # the time of the event creation. we don't use it for anything yet.
   origin_server_ts: 0
   
   # the id of this event. it will be the target for all event relations.
   event_id: '<session-grid-start-event-id>'
   
   # empty content. can be extended in the future.
   content: {}
   #…

2. We will store the reference to the start event in the session grid event:

     type: 'net.nordeck.barcamp.session_grid'
     state_key: '!lobby-room'
     room_id: '!my-room:…'
     content:
   +   # the event_id of the start event
   +   topicStartEventId: '<session-grid-start-event-id>'
       consumedTopicSubmissions: []
       tracks: []
       timeSlots: []
       sessions: []
       parkingLots: []
       #…
   event_id: '$…'
   #…

3. We will change the topic events to relate to the start event:

     type: 'net.nordeck.barcamp.topic'
     state_key: '$aaaaa'
     content:
       title: 'Data Security in Chat Systems'
       description: 'How secure is our communication infrastructure? …'
       authors:
         - id: '@primary-author:matrix.to'
   
   +   # m.relates_to by MSC2674
   +   m.relates_to:
   +     # m.reference by MSC3267
   +     rel_type: 'm.reference'
   +
   +     # the id of the start event
   +     event_id: '<session-grid-start-event-id>'
   
     room_id: '!…'
     event_id: '$…'
     origin_server_ts: …
     # …

Resulting data model:

  ┌──────────────────────────────────────┐
  │                                      │
  │   net.nordeck.barcamp.session_grid   │
  │                                      │
  └────┬─────────────────────────────────┘
       │
       │ topicStartEventId
       │
       ▼
  ┌──────────────────────────────────────┐
  │                                      │
  │net.nordeck.barcamp.session_grid.start│
  │                                      │
  └──────────────────────────────────────┘
       ▲
       │
       │ m.relates_to: m.reference
       │
       │
       │           ┌─────────────────────────┐
       │           │                         │
       ├───────────┤net.nordeck.barcamp.topic│
       │           │                         │
       │           └─────────────────────────┘
       │
       │           ┌─────────────────────────┐
       │           │                         │
       ├───────────┤net.nordeck.barcamp.topic│
       │           │                         │
       │           └─────────────────────────┘
       │
       │           ┌─────────────────────────┐
       │           │                         │
       └───────────┤net.nordeck.barcamp.topic│
                   │                         │
                   └─────────────────────────┘

Consequences

After applying the changes to the events, we need to change how we read the topics:

1. Read the session grid and extract the topicStartEventId.
2. Is topicStartEventId defined?
   • Yes: Fetch all events that have a m.reference relation to the topicStartEventId.
   • No: Fetch the events with readRoomEvents

Drawbacks

Similar drawbacks are documented in our poll widget.

Errors on missing events: When the start event could not be loaded, the topics can't be loaded. These errors can happen when:

1. The history visibility of the room is configured so that users can't see events before they joined.
2. The Client can't decrypt some events.

We accept that this fails and rely on the the global error handling that will show an error in this case. We already initialize the history visibility correctly during the widget setup and also already show a warning that the widget might run into trouble in encrypted rooms.