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

Jump to bottom

MSC4177: Add upload location hints proposal #4177

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

MSC4177: Add upload location hints proposal #4177

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2a07139
Add upload location hints proposal
Fizzadar Aug 13, 2024
2b65481
Add PR number
Fizzadar Aug 13, 2024
76e4e42
Linkify MSC numbers, fix title, fix spelling
Fizzadar Aug 13, 2024
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
63 changes: 63 additions & 0 deletions proposals/4177-upload-location-hints.md
View file
Open in desktop
Copy link
Member

Choose a reason for hiding this comment

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

Implementation requirements:

  • Client
  • Server

Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# MSC4177: Upload Location Hints
Copy link
Member

Choose a reason for hiding this comment

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

Is this only useful for uploads, or is would something similar also be useful for downloads?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Both really - specified at upload time but yields benefits on download (assuming others downloading are in the same location/region).


This MSC proposes extensions to the media APIs that allow servers and clients to provide each other
location hints for uploaded media.

Often Matrix homeservers serve users in many geographical locations. For media that is uploaded and
downloaded via a CDN (see: [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860),
[MSC3870](https://github.com/matrix-org/matrix-spec-proposals/pull/3870)) it is advantageous to use
a location as close to the user as possible. This MSC allows servers to advertise available media
storage locations and for clients to request media is uploaded to one of these locations.

All the changes are optional, ultimately the server retains control of where media gets put.

## Proposal

Firstly, to provide available locations to clients, the [`/_matrix/client/v1/media/config`](https://spec.matrix.org/v1.11/client-server-api/#get_matrixclientv1mediaconfig)
endpoint is extended with a new response field:

```json
{
"m.upload.locations": ["EU", "NA"],
...
}
```

The `m.upload.locations` field is a list of strings. Interpretation of the strings is up to clients
and servers and undefined in the spec. (Note: does this make sense?)

When clients wish to upload media, they can then include one of the location hints from the config
in upload or create media requests using the `location` query parameter, for example:

- `POST /_matrix/media/v1/upload?location=EU`
- `POST /_matrix/media/v1/create?location=EU`

When clients request a location the server MAY use that location hint to upload the media to a
bucket matching that location. Clients must not expect this to be guaranteed and ultimately the
server decides.

## Potential issues

How do clients/servers interpret location hints? Is it sensible to leave this undefined/open. We
could provide explicit options, or a baseline of options, "it is recommended location hints use
geographical ISO codes" for example.
Copy link
Contributor

Choose a reason for hiding this comment

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

Is the idea that a client would auto-select the most appropriate hint or would the user have to manually pick from the hints the server presents? For auto-selection to work, I think at least a recommendation of hint formats would be needed.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

That’s the idea, perhaps with a speed test endpoint as mentioned above.


## Alternatives
Copy link
Member

Choose a reason for hiding this comment

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

This sounds more like a routing issue and not a protocol issue. Can using something like Anycast routing or geo-based DNS help find the closest location?

Copy link
Contributor

Choose a reason for hiding this comment

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

I think the term you are looking for is EDNS Client Subnet. https://en.wikipedia.org/wiki/EDNS_Client_Subnet

What Wikipedia doesn't mention is NextDNS (and DNS0) and Adguard having more private implementations of it.

Copy link
Member

@clokep clokep Aug 14, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Kind of, I'm talking about how authoritative servers use that + the original source IP to serve close servers, like the GeoIP backend of PowerDNS or Route53 geolocation routing.

Maybe that's one in the same, but more the application instead of the underlying technology.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Can using something like Anycast routing or geo-based DNS help find the closest location?

Definitely, although requires a more complicated setup. But also using request IP would satisfy most use cases here I think.

My thought process for the PR was to give explicit control/negotiation of locations over to clients/servers rather than the server guessing the best location for a client to upload files to.

Now that I’ve said that I’m not sure there’s really much improvement with this change..


Server could use request IP to achieve this without any hints, though inaccurate and invalid when
a user is abroad. This is reasonable fallback behaviour for a server when clients do not provide
any location hint.
Copy link
Member

Choose a reason for hiding this comment

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

I don't have a whole lot of experience with CDNs, but would it be reasonable to expose an endpoint that would allow the client to measure the network speed, e.g. by uploading/downloading a small file, from each location? And then it can use the location with the shortest time. It might not be entirely accurate, but might be better than guessing based on IP address, or trying to divine the right location based on a location code?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yeah a test endpoint per location would be a handy addition here so clients can make informed decisions.


## Security considerations

None? Reveals bucket locations (to logged in users), but servers are aware of this and there's
no security issue (I think).
Copy link
Contributor

Choose a reason for hiding this comment

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

Since the hints are expected to be more accurate than IPs, the server would possibly gain more metadata about the client.


## Unstable prefix

`com.beeper.m.upload.locations`

## Dependencies

Though not a hard dependency uploads will only get speed benefits from this MSC once [MSC3870](https://github.com/matrix-org/matrix-spec-proposals/pull/3870)
is merged (otherwise uploads still route through the users homeserver location).