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.

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

MSC3860: Media Download Redirects #3860

Merged
merged 16 commits into from
May 9, 2023
Merged
46 changes: 46 additions & 0 deletions proposals/3860-media-download-redirect.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# MSC3860: Media Download Redirects
Fizzadar marked this conversation as resolved.
Show resolved Hide resolved
anoadragon453 marked this conversation as resolved.
Show resolved Hide resolved

Currently the media download endpoints must return either a 200 with content or error responses. This
means the media server instance must stream the data from wherever it is stored, which is likely not
local to itself. Allowing redirects on these endpoints would make it possible for the media repo to
tell clients/servers to pull data direct from the source, e.g. a CDN.
anoadragon453 marked this conversation as resolved.
Show resolved Hide resolved

## Proposal

This MSC proposes that a 307 redirect code is allowed and followed according to the `Location`
Fizzadar marked this conversation as resolved.
Show resolved Hide resolved
header. It is possible some clients would already follow these which needs to be confirmed. Specific
endpoints in question:

+ `/_matrix/media/v3/download/{serverName}/{mediaId}`
+ `/_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}`
+ `/_matrix/media/v3/thumbnail/{serverName}/{mediaId}`
anoadragon453 marked this conversation as resolved.
Show resolved Hide resolved

To prevent breaking clients that don't properly follow the redirect response this functionality will
be enabled by a query string flag `allow_redirect=true`. So specifically in the above cases if a
client respects redirect responses it can make requests like so to the media endpoints:
anoadragon453 marked this conversation as resolved.
Show resolved Hide resolved

+ `/_matrix/media/v3/download/{serverName}/{mediaId}?allow_redirect=true`
+ `/_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}?allow_redirect=true`
+ `/_matrix/media/v3/thumbnail/{serverName}/{mediaId}?allow_redirect=true`
Copy link
Member

Choose a reason for hiding this comment

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

The next versioned media endpoints after this MSC gets accepted (e.g. if MSC3911 gets accepted) should drop the allow_redirect parameter and clients that call it should handle redirects..


## Potential Issues

None, as opt-in functionality this change is 100% backwards compatible.

## Alternatives

None at this time.

## Security Considerations

A media repo could redirect requests to a bad actor, although this would make the primary media
repo itself a bad actor, thus this does not present any increased security issues.

## Unstable Prefix

Until this functionality has landed in the spec, the `allow_redirect` query
parameter should be prefixed with `com.beeper.msc3860.`:

```
?com.beeper.msc3860.allow_redirect=true
```