From 7f2f100420a355cf8ea50d08329e6f98989fc975 Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Wed, 28 Aug 2024 14:42:30 +0200
Subject: [PATCH] MSC4156: Migrate server_name to via (#1933)

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 .../newsfragments/1933.deprecation            |  1 +
 .../client_server/newsfragments/1933.feature  |  1 +
 data/api/client-server/joining.yaml           | 25 +++++++++++++++++++
 data/api/client-server/knocking.yaml          | 25 +++++++++++++++++++
 4 files changed, 52 insertions(+)
 create mode 100644 changelogs/client_server/newsfragments/1933.deprecation
 create mode 100644 changelogs/client_server/newsfragments/1933.feature

diff --git a/changelogs/client_server/newsfragments/1933.deprecation b/changelogs/client_server/newsfragments/1933.deprecation
new file mode 100644
index 00000000..b65ebdc7
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1933.deprecation
@@ -0,0 +1 @@
+Deprecate the `server_name` query parameter on `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4156](https://github.com/matrix-org/matrix-spec-proposals/pull/4156).
diff --git a/changelogs/client_server/newsfragments/1933.feature b/changelogs/client_server/newsfragments/1933.feature
new file mode 100644
index 00000000..030b5a00
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1933.feature
@@ -0,0 +1 @@
+Add `via` query parameter on `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4156](https://github.com/matrix-org/matrix-spec-proposals/pull/4156).
diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml
index afd19fa8..aead420c 100644
--- a/data/api/client-server/joining.yaml
+++ b/data/api/client-server/joining.yaml
@@ -139,6 +139,31 @@ paths:
             type: string
         - in: query
           name: server_name
+          x-changedInMatrixVersion:
+            "1.12": |-
+              This parameter has been deprecated in favour of `via` and will be removed in
+              a future version of the spec.
+
+              Clients SHOULD use `via` when the homeserver they're talking to supports it.
+              To do this, they MAY either detect server support through the supported spec
+              versions in [`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions)
+              or always include both parameters with identical values.
+
+              Homeservers MUST ignore all `server_name` parameters if any `via` parameters
+              are supplied.
+          description: |-
+            The servers to attempt to join the room through. One of the servers
+            must be participating in the room.
+          example:
+            - matrix.org
+            - elsewhere.ca
+          schema:
+            type: array
+            items:
+              type: string
+        - in: query
+          name: via
+          x-addedInMatrixVersion: "1.12"
           description: |-
             The servers to attempt to join the room through. One of the servers
             must be participating in the room.
diff --git a/data/api/client-server/knocking.yaml b/data/api/client-server/knocking.yaml
index 1eb6cde7..39a928e8 100644
--- a/data/api/client-server/knocking.yaml
+++ b/data/api/client-server/knocking.yaml
@@ -50,6 +50,31 @@ paths:
             type: string
         - in: query
           name: server_name
+          x-changedInMatrixVersion:
+            "1.12": |-
+              This parameter has been deprecated in favour of `via` and will be removed in
+              a future version of the spec.
+
+              Clients SHOULD use `via` when the homeserver they're talking to supports it.
+              To do this, they MAY either detect server support through the supported spec
+              versions in [`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions)
+              or always include both parameters with identical values.
+
+              Homeservers MUST ignore all `server_name` parameters if any `via` parameters
+              are supplied.
+          description: |-
+            The servers to attempt to knock on the room through. One of the servers
+            must be participating in the room.
+          example:
+            - matrix.org
+            - elsewhere.ca
+          schema:
+            type: array
+            items:
+              type: string
+        - in: query
+          name: via
+          x-addedInMatrixVersion: "1.12"
           description: |-
             The servers to attempt to knock on the room through. One of the servers
             must be participating in the room.