matrix-org / matrix-org/matrix-spec
Confusing cycle: S-S API -> room version auth rules -> S-S api auth events selection
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
To find out what checks need to be made of incoming PDUs, one must consult [the server-server API](https://spec.matrix.org/v1.2/server-server-api/#checks-performed-on-receipt-of-a-pdu). For checking the `auth_events` in particular, we learn [here](https://spec.matrix.org/v1.2/server-server-api/#authorization-rules) that tells you that the rules depend on the room version.
Each individual room version has the following as step 2:
> 2. Reject if event has auth_events that:
> 1. have duplicate entries for a given type and state_key pair
> 2. have entries whose type and state_key don’t match those specified by the [auth events selection](https://spec.matrix.org/v1.2/server-server-api#auth-events-selection) algorithm described in the server specification.
Following that link takes you back to the server-server API. I found that confusing. Then for steps 3 onward you switch back to the room version document.
It might be clearer to make the auth event selection rules part of the room version itself---particularly if we might want to change those rules in the future?
Contributor guide
Research direction
Start by comparing the server-server API sections on checks performed on receipt of a PDU, authorization rules, and auth events selection with the individual room version documents. Determine where the auth event selection rules should live so readers do not loop between documents; done means the specification presents a clear, consistent path for checking auth_events.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100