What the product must send to its homeserver, or feed to another device
-- design doc section 3bis. body is JSON this library never
interprets, sent as-is; kind is an open tag mirroring upstream's own
request kinds, deliberately typed string rather than a union for the
same reason CryptoAlgorithm is open (the set grows upstream, and a
consumer must already handle a value it does not recognise).
Today's values, the endpoint each addresses, and what
markRequestSent's own responseJson must contain to report one
sent -- that endpoint's response body, unwrapped, exactly as the
homeserver returned it, and nothing this library adds or removes. No
count stands over the table: the tag is open, the table grew by a row in
this release, and a count is the part of a claim most likely to go stale
and least likely to be re-read.
A wrong responseJson is not reliably rejected, so do not treat the
column below as validated input. A body that is not shaped like that
endpoint's response is always rejected with malformed_payload: being an
object with no keys, or carrying at least one of the fields in its row
below, is what that means.
Being shaped right is necessary, not sufficient. A body carrying a real
field alongside a Matrix error's errcode, a gateway's error or a
challenge's flows is still rejected, and {} is rejected for
keys_upload, keys_claim and room_message, whose responses each have
one required field. What survives all of that, and why, is set out once in
markRequestFailed.
kind
Method & path
responseJson must contain
'keys_upload'
POST /_matrix/client/v3/keys/upload
{ one_time_key_counts: { [algorithm: string]: number } }
'keys_query'
POST /_matrix/client/v3/keys/query
{ device_keys?, master_keys?, self_signing_keys?, user_signing_keys?, failures? } (all optional; {} is valid). Accepted is not the same as answered here. A query about your own account only satisfies bootstrapCrossSigning's ordering gate when the body names that account in one of the four user-keyed maps, which is what every measured homeserver sends even for an account it holds nothing for. See markRequestFailed
'keys_claim'
POST /_matrix/client/v3/keys/claim
{ one_time_keys: {...}, failures? }
'to_device'
PUT /_matrix/client/v3/sendToDevice/{eventType}/{txnId}
{}, and only {}. The machine ignores the contents and the response type declares no fields, so there is no field that could widen the shape: an object with any key at all is rejected here
'signature_upload'
POST /_matrix/client/v3/keys/signatures/upload
{ failures? } (optional; {} is valid)
'room_message'
PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}
{ event_id: string }
'signing_keys_upload'
POST /_matrix/client/v3/keys/device_signing/upload
{}, and only {}, for the reason 'to_device' gives: the response type declares no fields, so no key could widen the shape. This is the row where that costs you something. The endpoint is user-interactive, its refusal is a 401 with a challenge, and {} is also what a 502 with no body arrives as. Branch on the status and send anything that is not a 2xx to markRequestFailed: reporting a challenge here would mark an identity published that never was
'to_device' and 'room_message' carry their own path segments
(eventType/txnId, and for the latter roomId too) inside body
itself, alongside the wire content, since this library has no other way
to hand them to the product -- see the two disclosed exceptions the
core's own describe_outgoing documents for itself.
See shareScopeKey's own doc comment for the order a key has to
travel in, which is not optional: design doc section 3ter. See
takeOutgoingRequests for the separate rule that a batch must be
sent in the order it was handed to you, while marking stays unordered.
What the product must send to its homeserver, or feed to another device -- design doc section 3bis.
bodyis JSON this library never interprets, sent as-is;kindis an open tag mirroring upstream's own request kinds, deliberately typedstringrather than a union for the same reasonCryptoAlgorithmis open (the set grows upstream, and a consumer must already handle a value it does not recognise).Today's values, the endpoint each addresses, and what markRequestSent's own
responseJsonmust contain to report one sent -- that endpoint's response body, unwrapped, exactly as the homeserver returned it, and nothing this library adds or removes. No count stands over the table: the tag is open, the table grew by a row in this release, and a count is the part of a claim most likely to go stale and least likely to be re-read.A wrong
responseJsonis not reliably rejected, so do not treat the column below as validated input. A body that is not shaped like that endpoint's response is always rejected withmalformed_payload: being an object with no keys, or carrying at least one of the fields in its row below, is what that means.Being shaped right is necessary, not sufficient. A body carrying a real field alongside a Matrix error's
errcode, a gateway'serroror a challenge'sflowsis still rejected, and{}is rejected forkeys_upload,keys_claimandroom_message, whose responses each have one required field. What survives all of that, and why, is set out once in markRequestFailed.kindresponseJsonmust contain'keys_upload'POST /_matrix/client/v3/keys/upload{ one_time_key_counts: { [algorithm: string]: number } }'keys_query'POST /_matrix/client/v3/keys/query{ device_keys?, master_keys?, self_signing_keys?, user_signing_keys?, failures? }(all optional;{}is valid). Accepted is not the same as answered here. A query about your own account only satisfies bootstrapCrossSigning's ordering gate when the body names that account in one of the four user-keyed maps, which is what every measured homeserver sends even for an account it holds nothing for. See markRequestFailed'keys_claim'POST /_matrix/client/v3/keys/claim{ one_time_keys: {...}, failures? }'to_device'PUT /_matrix/client/v3/sendToDevice/{eventType}/{txnId}{}, and only{}. The machine ignores the contents and the response type declares no fields, so there is no field that could widen the shape: an object with any key at all is rejected here'signature_upload'POST /_matrix/client/v3/keys/signatures/upload{ failures? }(optional;{}is valid)'room_message'PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}{ event_id: string }'signing_keys_upload'POST /_matrix/client/v3/keys/device_signing/upload{}, and only{}, for the reason'to_device'gives: the response type declares no fields, so no key could widen the shape. This is the row where that costs you something. The endpoint is user-interactive, its refusal is a401with a challenge, and{}is also what a 502 with no body arrives as. Branch on the status and send anything that is not a 2xx to markRequestFailed: reporting a challenge here would mark an identity published that never was'to_device'and'room_message'carry their own path segments (eventType/txnId, and for the latterroomIdtoo) insidebodyitself, alongside the wire content, since this library has no other way to hand them to the product -- see the two disclosed exceptions the core's owndescribe_outgoingdocuments for itself.See shareScopeKey's own doc comment for the order a key has to travel in, which is not optional: design doc section 3ter. See takeOutgoingRequests for the separate rule that a batch must be sent in the order it was handed to you, while marking stays unordered.