From 4fabef1c973222242531318bdc3fdc7d71b0b063 Mon Sep 17 00:00:00 2001
From: Nick Mills-Barrett <nick@fizzadar.com>
Date: Wed, 17 May 2023 16:17:20 +0100
Subject: [PATCH] Add `allow_redirect` query parameter to relevant media
 endpoints (#1529)

* Add `allow_redirect` query parameter to relevant media endpoints

* Add added in version flag to `allow_redirect` params

* Add 307/308 responses to media endpoints

* Add changelogs
---
 .../client_server/newsfragments/1529.feature  |  1 +
 data/api/client-server/content-repo.yaml      | 69 +++++++++++++++++++
 2 files changed, 70 insertions(+)
 create mode 100644 changelogs/client_server/newsfragments/1529.feature

diff --git a/changelogs/client_server/newsfragments/1529.feature b/changelogs/client_server/newsfragments/1529.feature
new file mode 100644
index 00000000..48f1d90b
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1529.feature
@@ -0,0 +1 @@
+Addition of redirect downloads, as per [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860).
diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml
index 328ae1c4..e12c5612 100644
--- a/data/api/client-server/content-repo.yaml
+++ b/data/api/client-server/content-repo.yaml
@@ -308,6 +308,17 @@ paths:
             content repository can and should impose a maximum value for this
             parameter. The content repository may also choose to respond before
             the timeout.
+        - in: query
+          type: boolean
+          name: allow_redirect
+          x-addedInMatrixVersion: "1.7"
+          x-example: false
+          required: false
+          default: false
+          description: |
+            Indicates to the server that it may return a 307 or 308 redirect response that points
+            at the relevant media content. When not explicitly set to true the server must return
+            the media content itself.
       responses:
         200:
           description: "The content that was previously uploaded."
@@ -323,6 +334,18 @@ paths:
             type: file
             # This is a workaround for us not being able to say the response is required.
             description: "**Required.** The bytes for the uploaded file."
+        307:
+          description: "A redirect to the thumbnail of the requested content."
+          headers:
+            Location:
+              description: "The URL of the thumbnail content."
+              type: "string"
+        308:
+          description: "A redirect to the thumbnail of the requested content."
+          headers:
+            Location:
+              description: "The URL of the thumbnail content."
+              type: "string"
         429:
           description: This request was rate-limited.
           schema:
@@ -404,6 +427,17 @@ paths:
             content repository can and should impose a maximum value for this
             parameter. The content repository may also choose to respond before
             the timeout.
+        - in: query
+          type: boolean
+          name: allow_redirect
+          x-addedInMatrixVersion: "1.7"
+          x-example: false
+          required: false
+          default: false
+          description: |
+            Indicates to the server that it may return a 307 or 308 redirect response that points
+            at the relevant media content. When not explicitly set to true the server must return
+            the media content itself.
       responses:
         200:
           description: "The content that was previously uploaded."
@@ -420,6 +454,18 @@ paths:
             type: file
             # This is a workaround for us not being able to say the response is required.
             description: "**Required.** The bytes for the uploaded file."
+        307:
+          description: "A redirect to the thumbnail of the requested content."
+          headers:
+            Location:
+              description: "The URL of the thumbnail content."
+              type: "string"
+        308:
+          description: "A redirect to the thumbnail of the requested content."
+          headers:
+            Location:
+              description: "The URL of the thumbnail content."
+              type: "string"
         429:
           description: This request was rate-limited.
           schema:
@@ -518,6 +564,17 @@ paths:
             content repository can and should impose a maximum value for this
             parameter. The content repository may also choose to respond before
             the timeout.
+        - in: query
+          type: boolean
+          name: allow_redirect
+          x-addedInMatrixVersion: "1.7"
+          x-example: false
+          required: false
+          default: false
+          description: |
+            Indicates to the server that it may return a 307 or 308 redirect response that points
+            at the relevant media content. When not explicitly set to true the server must return
+            the media content itself.
       responses:
         200:
           description: "A thumbnail of the requested content."
@@ -530,6 +587,18 @@ paths:
             type: file
             # This is a workaround for us not being able to say the response is required.
             description: "**Required.** The bytes for the thumbnail."
+        307:
+          description: "A redirect to the thumbnail of the requested content."
+          headers:
+            Location:
+              description: "The URL of the thumbnail content."
+              type: "string"
+        308:
+          description: "A redirect to the thumbnail of the requested content."
+          headers:
+            Location:
+              description: "The URL of the thumbnail content."
+              type: "string"
         400:
           description: |-
             The request does not make sense to the server, or the server cannot thumbnail