Clarification to transaction identifier idempotent semantics (#1449)

pull/1462/head
Hugh Nimmo-Smith 2 years ago committed by GitHub
parent f9ea0f9d9b
commit 10844fef8c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

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

@ -214,19 +214,36 @@ See the [Server Notices](#server-notices) module for more information.
### Transaction identifiers ### Transaction identifiers
The client-server API typically uses `HTTP PUT` to submit requests with The client-server API typically uses `HTTP PUT` to submit requests with
a client-generated transaction identifier. This means that these a client-generated transaction identifier in the HTTP path.
requests are idempotent. It **only** serves to identify new requests
from retransmits. After the request has finished, the `{txnId}` value The purpose of the transaction ID is to allow the homeserver to distinguish a
should be changed (how is not specified; a monotonically increasing new request from a retransmission of a previous request so that it can make
integer is recommended). the request idempotent.
The scope of a transaction ID is a "client session", where that session The transaction ID should **only** be used for this purpose.
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 From the client perspective, after the request has finished, the `{txnId}`
if a client with token `A` uses `TXN1` as their transaction ID, refreshes value should be changed by for the next request (how is not specified; a
the token to `B`, and uses `TXN1` again it'll be assumed to be a duplicate monotonically increasing integer is recommended).
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 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 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` without a transaction ID. Where this is optional, the use of a `PUT`

Loading…
Cancel
Save