wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Clarification to transaction identifier idempotent semantics (#1449)

Browse source
This commit is contained in:
Hugh Nimmo-Smith 2023-03-07 16:45:14 +00:00 • committed by GitHub
parent f9ea0f9d9b
commit 10844fef8c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 30 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/1449.clarification Normal file
View file

@ -0,0 +1 @@
Clarify the semantics that make requests idempotent.

41
content/client-server-api/_index.md
View file

@ -214,19 +214,36 @@ See the [Server Notices](#server-notices) module for more information.
### Transaction identifiers
The client-server API typically uses `HTTP PUT` to submit requests with
a client-generated transaction identifier. This means that these
requests are idempotent. It **only** serves to identify new requests
from retransmits. After the request has finished, the `{txnId}` value
should be changed (how is not specified; a monotonically increasing
integer is recommended).
a client-generated transaction identifier in the HTTP path.
The scope of a transaction ID is a "client session", where that session
is identified by a particular access token. When [refreshing](#refreshing-access-tokens)
an access token, the transaction ID's scope is retained. This means that
if a client with token `A` uses `TXN1` as their transaction ID, refreshes
the token to `B`, and uses `TXN1` again it'll be assumed to be a duplicate
request and ignored. If the client logs out and back in between the `A` and
`B` tokens, `TXN1` could be used once for each.
The purpose of the transaction ID is to allow the homeserver to distinguish a
new request from a retransmission of a previous request so that it can make
the request idempotent.
The transaction ID should **only** be used for this purpose.
From the client perspective, after the request has finished, the `{txnId}`
value should be changed by for the next request (how is not specified; a
monotonically increasing integer is recommended).
The homeserver should identify a request as a retransmission if the
transaction ID is the same as a previous request, and the path of the
HTTP request is the same.
Where a retransmission has been identified, the homeserver should return
the same HTTP response code and content as the original request.
For example, `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`
would return a `200 OK` with the `event_id` of the original request in
the response body.
As well as the HTTP path, the scope of a transaction ID is a "client
session", where that session is identified by a particular access token.
When [refreshing](#refreshing-access-tokens) an access token, the
transaction ID's scope is retained. This means that if a client with
token `A` uses `TXN1` as their transaction ID, refreshes the token to
`B`, and uses `TXN1` again it'll be assumed to be a duplicate request
and ignored. If the client logs out and back in between the `A` and `B`
tokens, `TXN1` could be used once for each.
Some API endpoints may allow or require the use of `POST` requests
without a transaction ID. Where this is optional, the use of a `PUT`