Spec `?format=event|content` on `GET /state/:type[/:key]`

turt2live commented 2 years ago

This has always been missing from the spec, but appears to have always been a feature of Synapse.

This is quite useful as a feature given how many things could do with knowing the event ID of state event, and how many MSCs currently try to work around the issue. Off the top of my head:

File trees (to be able to rel_type: m.reference file metadata)
Location sharing for beacons, if the sender lost their local state
Various conference bot actions which rely on room state
... and a lot more that escape me as of writing.

Currently if a client wants this information and is sticking to the spec then they must call /sync or similar to locate the state event of interest. This is in fact what some clients, like the conference bot, do.

Evidence using curl

``` $ curl -s -X GET -H "Authorization: Bearer ${token}" 'http://localhost:8338/_matrix/client/v3/rooms/!GiwgmfWtVmChIrRDMe:localhost/state/m.room.create?format=event' | python -m json.tool { "type": "m.room.create", "room_id": "!GiwgmfWtVmChIrRDMe:localhost", "sender": "@travis:localhost", "content": { "room_version": "org.matrix.msc3787", "predecessor": { "room_id": "!FFDoPrcpeoLvVNcbmo:localhost", "event_id": "$RqUrDYxf9LIklWsLelCnyFd-Qq95LXB0gXlUfgUwPEw" }, "creator": "@travis:localhost" }, "state_key": "", "origin_server_ts": 1651631163723, "unsigned": { "age_ts": 1651631163723 } } $ curl -s -X GET -H "Authorization: Bearer ${token}" 'http://localhost:8338/_matrix/client/v3/rooms/!GiwgmfWtVmChIrRDMe:localhost/state/m.room.create?format=content' | python -m json.tool { "room_version": "org.matrix.msc3787", "predecessor": { "room_id": "!FFDoPrcpeoLvVNcbmo:localhost", "event_id": "$RqUrDYxf9LIklWsLelCnyFd-Qq95LXB0gXlUfgUwPEw" }, "creator": "@travis:localhost" } $ curl -s -X GET -H "Authorization: Bearer ${token}" 'http://localhost:8338/_matrix/client/v3/rooms/!GiwgmfWtVmChIrRDMe:localhost/state/m.room.create' | python -m json.tool { "room_version": "org.matrix.msc3787", "predecessor": { "room_id": "!FFDoPrcpeoLvVNcbmo:localhost", "event_id": "$RqUrDYxf9LIklWsLelCnyFd-Qq95LXB0gXlUfgUwPEw" }, "creator": "@travis:localhost" } ```

turt2live commented 2 years ago

I've counted this as a spec omission given it's come up a lot but seemingly everyone forgot that Synapse has this. Out of band proposals have always been to add a ?format=event style parameter so this feels more than reasonable to put into spec.

richvdh commented 2 years ago

for reference: this is similar to, but different from, the event_format parameter on filters (https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3useruseridfilter), which has the options client (the default) and federation.

There is no way to request "federation" format events from GET /state - the choices are client format or just the raw content.

ShadowJonathan commented 2 years ago

For the purposes of tracking changes to the spec, could this still be included as a changelog entry? (As this is technically no MSC)

turt2live commented 2 years ago

@ShadowJonathan all changes require a changelog entry? Not sure what the ask is...

ShadowJonathan commented 2 years ago

I'm just making sure this is included, as there's no strong precedent for this, so I wasn't entirely sure on the stance for small changes like this, thanks.

turt2live commented 2 years ago

There is a very strong precedent for this sort of change: we do it all the time in the form of clarifications. Every change to the spec requires a changelog entry. Every. Single. One. :)

DMRobertson commented 2 years ago

This contributed to confusion here.

turt2live commented 1 year ago

This came up again while trying to write some bot-based scripts (the bot doesn't retain state).

I don't think this needs an MSC to contribute as-is. Improvements, like a possible federation format, should go through the MSC process though.

MTRNord commented 9 months ago

This came back up again in spec room about the creator field being missing in room version 11 in the m.room.create as the default/spec version of this endpoint only returns the content there was assumed to be no way to get the sender :)

matrix-org / matrix-spec

Spec `?format=event|content` on `GET /state/:type[/:key]` #1047