Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update transaction ID scope #1526

Merged
merged 1 commit into from
May 16, 2023
Merged

Update transaction ID scope #1526

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/client_server/newsfragments/1526.feature
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Update the scope of transaction IDs, as per [MSC3970](https://github.com/matrix-org/matrix-spec-proposals/pull/3970).
30 changes: 21 additions & 9 deletions content/client-server-api/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -237,19 +237,32 @@ 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.
The scope of a transaction ID is for a single [device](../index.html#devices),
and a single HTTP endpoint. In other words: a single device could use the same
transaction ID for a request to [`PUT
/_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`](#put_matrixclientv3roomsroomidsendeventtypetxnid)
and [`PUT
/_matrix/client/v3/sendToDevice/{eventType}/{txnId}`](#put_matrixclientv3sendtodeviceeventtypetxnid),
and the two requests would be considered distinct because the two are
considered separate endpoints. Similarly, if a client logs out and back in
between two requests using the same transaction ID, the requests are distinct
because the act of logging in and out creates a new device (unless an existing
`device_id` is passed to [`POST
/_matrix/client/v3/login`](#post_matrixclientv3login)). On the other hand, if a
client re-uses a transaction ID for the same endpoint after
[refreshing](#refreshing-access-tokens) an access token, it will be assumed to
be a duplicate request and ignored. See also
[Relationship between access tokens and devices](#relationship-between-access-tokens-and-devices).

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`
request is strongly recommended.

{{% boxes/rationale %}}
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I considered adding a {{% changed-in %}} box at the top of the section, but the change feels a bit trivial for that. In practice, we don't think any implementations are affected.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, seems unnecessary.

Prior to `v1.7`, transaction IDs were scoped to "client sessions" rather than
devices.
{{% /boxes/rationale %}}

## Web Browser Clients

It is realistic to expect that some clients will be written to be run
Expand Down Expand Up @@ -2671,4 +2684,3 @@ systems.
{{< cs-module name="event_annotations" >}}
{{< cs-module name="threading" >}}
{{< cs-module name="reference_relations" >}}