search

matrix-org / matrix-spec

The Matrix protocol specification
Apache License 2.0
188 stars 94 forks source link

"Optional" keyword on `device_one_time_keys_count` is confusing #1057

Open turt2live opened 2 years ago

turt2live commented 2 years ago

Link to problem area: https://spec.matrix.org/v1.2/client-server-api/#extensions-to-sync-1

Issue

The spec currently says:

Optional. For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device. If an algorithm is unlisted, the count for that algorithm is assumed to be zero. If this entire parameter is missing, the count for all algorithms is assumed to be zero.

This leads the reader to believe they can just leave the field off of the sync response, but if they read on then they find out that has associated behaviour. As a cheap solution, drop "Optional." and leave the rest of the description as-is. Bonus points for rewording more appropriately though.

neilalexander commented 2 years ago

This leads the reader to believe they can just leave the field off of the sync response, but if they read on then they find out that has associated behaviour.

Honestly the specced behaviour of assuming that a missing value means zero is a footgun anyway. A missing value should mean nothing. If the server doesn't support handling OTKs for example, it should be possible to omit the field and expect that a client will do nothing. We should not be encouraging clients to implement magic behaviours.