From a8c326962a773f5234a08f755512d7cbae40ca30 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
Date: Thu, 8 May 2025 10:09:45 +0100
Subject: [PATCH] Add a note to the federation invite endpoints that invites
 can be sent twice (#2067)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

... as this may be non-obvious when implementing behaviour that is triggered by an incoming invite
event.

See https://github.com/matrix-org/matrix-spec/issues/2062 for more context.

Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>
---
 changelogs/server_server/newsfragments/2067.clarification | 1 +
 data/api/server-server/invites-v1.yaml                    | 6 +++++-
 data/api/server-server/invites-v2.yaml                    | 6 +++++-
 3 files changed, 11 insertions(+), 2 deletions(-)
 create mode 100644 changelogs/server_server/newsfragments/2067.clarification

diff --git a/changelogs/server_server/newsfragments/2067.clarification b/changelogs/server_server/newsfragments/2067.clarification
new file mode 100644
index 00000000..4bd8176b
--- /dev/null
+++ b/changelogs/server_server/newsfragments/2067.clarification
@@ -0,0 +1 @@
+Add a note to the invite endpoints that invites to local users may be received twice over federation if the homeserver is already in the room.
\ No newline at end of file
diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml
index 7d241c37..b1771018 100644
--- a/data/api/server-server/invites-v1.yaml
+++ b/data/api/server-server/invites-v1.yaml
@@ -20,7 +20,7 @@ paths:
     put:
       summary: Invites a remote user to a room
       description: |-
-        Invites a remote user to a room. Once the event has been  signed by both the inviting
+        Invites a remote user to a room. Once the event has been signed by both the inviting
         homeserver and the invited homeserver, it can be sent to all of the servers in the
         room by the inviting homeserver.
 
@@ -32,6 +32,10 @@ paths:
         [room version specification](/rooms) for precise event formats. **The request and response
         bodies here describe the common event fields in more detail and may be missing other
         required fields for a PDU.**
+
+        Also note that if the remote homeserver is already in the room, it will receive the
+        invite event twice; once through this endpoint, and again through a [federation
+        transaction](/server-server-api/#transactions).
       operationId: sendInviteV1
       security:
         - signedRequest: []
diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml
index f42c8eea..6ac8bb3e 100644
--- a/data/api/server-server/invites-v2.yaml
+++ b/data/api/server-server/invites-v2.yaml
@@ -24,7 +24,7 @@ paths:
         This API is nearly identical to the v1 API with the exception of the request
         body being different, and the response format fixed.
 
-        Invites a remote user to a room. Once the event has been  signed by both the inviting
+        Invites a remote user to a room. Once the event has been signed by both the inviting
         homeserver and the invited homeserver, it can be sent to all of the servers in the
         room by the inviting homeserver.
 
@@ -36,6 +36,10 @@ paths:
         [room version specification](/rooms) for precise event formats. **The request and response
         bodies here describe the common event fields in more detail and may be missing other
         required fields for a PDU.**
+
+        Also note that if the remote homeserver is already in the room, it will receive the
+        invite event twice; once through this endpoint, and again through a [federation
+        transaction](/server-server-api/#transactions).
       operationId: sendInviteV2
       security:
         - signedRequest: []