From 81ed592b077bb7767829744182be8583fb8ed7e7 Mon Sep 17 00:00:00 2001 From: Nick Barrett Date: Thu, 4 Aug 2022 16:24:42 +0100 Subject: [PATCH 1/9] Add well known media domain proposal --- proposals/xxx-well-known-media-domain.md | 38 ++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 proposals/xxx-well-known-media-domain.md diff --git a/proposals/xxx-well-known-media-domain.md b/proposals/xxx-well-known-media-domain.md new file mode 100644 index 0000000000..5a1902be6d --- /dev/null +++ b/proposals/xxx-well-known-media-domain.md @@ -0,0 +1,38 @@ +# MSCXXX: .well-known Media Domain + +Currently Matrix clients and servers discover homeservers and identify servers via the `.well-known/matrix/client` and `.well-known/matrix/server` endpoints. This is currently limited to the homeserver and for clients the identity server. This MSC proposes adding an additional field that can be used to specify a media server that can optionally be used for `/_matrix/media/*` endpoints. + +The reasoning behind this change is to support hosting media behind a CDN designed and optimised specifically for serving media. Since media transfers and endpoints are very different to the other JSON based endpoints a separate domain offers maximum flexibility for server owners. + + +## Proposals + +### Extend the client .well-known + +Add a new optional field, `m.media_server` that can specify a separate URL to be used for media requests. Clients can then optionally use this field for media endpoints: + +``` +{ + "m.homeserver": { + "base_url": "https://matrix.example.com" + }, + "m.media_server": { + "base_url": "https://matrix-media.example.com" + } +} +``` + +To ensure backwards compatibility the homeserver base URL must also be able to serve the same media requests (via a proxy or some other backend system). + +### Extend the server .well-known + +This is the same as above but for the server endpoint: + +``` +{ + "m.server": "matrix.example.com:443", + "m.media_server": "matrix-media.example.com:443" +} +``` + +As above, the non-media endpoint must also serve media requests. From cb259acb0a1da945babb03b0dad8dfe51edbfe25 Mon Sep 17 00:00:00 2001 From: Nick Barrett Date: Thu, 4 Aug 2022 16:26:10 +0100 Subject: [PATCH 2/9] Rename file --- ...well-known-media-domain.md => 3859-well-known-media-domain.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{xxx-well-known-media-domain.md => 3859-well-known-media-domain.md} (100%) diff --git a/proposals/xxx-well-known-media-domain.md b/proposals/3859-well-known-media-domain.md similarity index 100% rename from proposals/xxx-well-known-media-domain.md rename to proposals/3859-well-known-media-domain.md From f1ca6064193c26d4d173e8cf241be8a8267e76e9 Mon Sep 17 00:00:00 2001 From: Nick Barrett Date: Mon, 8 Aug 2022 13:39:47 +0100 Subject: [PATCH 3/9] Formatting --- proposals/3859-well-known-media-domain.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/proposals/3859-well-known-media-domain.md b/proposals/3859-well-known-media-domain.md index 5a1902be6d..9e23a5846e 100644 --- a/proposals/3859-well-known-media-domain.md +++ b/proposals/3859-well-known-media-domain.md @@ -1,15 +1,21 @@ -# MSCXXX: .well-known Media Domain +# MSC3859: .well-known Media Domain -Currently Matrix clients and servers discover homeservers and identify servers via the `.well-known/matrix/client` and `.well-known/matrix/server` endpoints. This is currently limited to the homeserver and for clients the identity server. This MSC proposes adding an additional field that can be used to specify a media server that can optionally be used for `/_matrix/media/*` endpoints. +Currently Matrix clients and servers discover homeservers and identify servers via the `.well-known/matrix/client` and +`.well-known/matrix/server` endpoints. This is currently limited to the homeserver and for clients the identity server. +This MSC proposes adding an additional field that can be used to specify a media server that can optionally be used +for `/_matrix/media/*` endpoints. -The reasoning behind this change is to support hosting media behind a CDN designed and optimised specifically for serving media. Since media transfers and endpoints are very different to the other JSON based endpoints a separate domain offers maximum flexibility for server owners. +The reasoning behind this change is to support hosting media behind a CDN designed and optimised specifically for +serving media. Since media transfers and endpoints are very different to the other JSON based endpoints a separate +domain offers maximum flexibility for server owners. ## Proposals ### Extend the client .well-known -Add a new optional field, `m.media_server` that can specify a separate URL to be used for media requests. Clients can then optionally use this field for media endpoints: +Add a new optional field, `m.media_server` that can specify a separate URL to be used for media requests. Clients can +then optionally use this field for all media endpoints, including both download and upload. ``` { @@ -22,7 +28,8 @@ Add a new optional field, `m.media_server` that can specify a separate URL to be } ``` -To ensure backwards compatibility the homeserver base URL must also be able to serve the same media requests (via a proxy or some other backend system). +To ensure backwards compatibility the homeserver base URL must also be able to serve the same media requests (via a +proxy or some other backend system). ### Extend the server .well-known From 86123b0b6a5a331b35a984b1b9524c2009b2b591 Mon Sep 17 00:00:00 2001 From: Nick Barrett Date: Mon, 8 Aug 2022 13:45:02 +0100 Subject: [PATCH 4/9] Add missing sections --- proposals/3859-well-known-media-domain.md | 38 +++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/proposals/3859-well-known-media-domain.md b/proposals/3859-well-known-media-domain.md index 9e23a5846e..ee6af63577 100644 --- a/proposals/3859-well-known-media-domain.md +++ b/proposals/3859-well-known-media-domain.md @@ -17,7 +17,7 @@ domain offers maximum flexibility for server owners. Add a new optional field, `m.media_server` that can specify a separate URL to be used for media requests. Clients can then optionally use this field for all media endpoints, including both download and upload. -``` +```json { "m.homeserver": { "base_url": "https://matrix.example.com" @@ -35,7 +35,7 @@ proxy or some other backend system). This is the same as above but for the server endpoint: -``` +```json { "m.server": "matrix.example.com:443", "m.media_server": "matrix-media.example.com:443" @@ -43,3 +43,37 @@ This is the same as above but for the server endpoint: ``` As above, the non-media endpoint must also serve media requests. + + +## Alternatives + +### Redirects + +For the download path, the homeserver could send a redirect response to a CDN backed domain. This is proposed in +MSC3860. + +For the upload path this is not possible under HTTP. + + +## Security Considerations + +Server admins may have to manage two distinct domains/installs increasing management & attack vector. + + +## Unstable Prefix + +While not released in the Matrix spec implementations should use field `com.beeper.msc3859.m.media_server` in place of +`m.media_server` in the well known responses: + +```json +# Client +{ + "com.beeper.msc3859.m.media_server": { + "base_url": "https://matrix-media.example.com" + } +} +# Server +{ + "com.beeper.msc3859.m.media_server": "matrix-media.example.com:443" +} +``` \ No newline at end of file From 7ba95c8174c62e81c5af7754b198ff01478016a6 Mon Sep 17 00:00:00 2001 From: Nick Barrett Date: Mon, 8 Aug 2022 13:49:54 +0100 Subject: [PATCH 5/9] Expand top section about benefits & reasoning --- proposals/3859-well-known-media-domain.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/proposals/3859-well-known-media-domain.md b/proposals/3859-well-known-media-domain.md index ee6af63577..c5e4492d80 100644 --- a/proposals/3859-well-known-media-domain.md +++ b/proposals/3859-well-known-media-domain.md @@ -7,7 +7,14 @@ for `/_matrix/media/*` endpoints. The reasoning behind this change is to support hosting media behind a CDN designed and optimised specifically for serving media. Since media transfers and endpoints are very different to the other JSON based endpoints a separate -domain offers maximum flexibility for server owners. +domain offers maximum flexibility for server owners. This is particularly important for path optimisation between +client and server over long dinstances where home internet providers generally offer inferior routing between countries +than CDN providers do. By allowing clients to upload/download from the closest CDN POP they will benefit from improved +upload and download performance. + +This cannot be achieved currently unless the entire homeserver is served behind a CDN, which may have other cost or +management implications (or simply be impossible, depending on CDN). A separate domain allows server admins to +decide the best setup for their users. ## Proposals From 4e7bf60a31d4e4d2c4407030478cd9e305f698cb Mon Sep 17 00:00:00 2001 From: Nick Barrett Date: Mon, 8 Aug 2022 13:57:11 +0100 Subject: [PATCH 6/9] Link MSC3860 --- proposals/3859-well-known-media-domain.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3859-well-known-media-domain.md b/proposals/3859-well-known-media-domain.md index c5e4492d80..36ee7f9e29 100644 --- a/proposals/3859-well-known-media-domain.md +++ b/proposals/3859-well-known-media-domain.md @@ -57,7 +57,7 @@ As above, the non-media endpoint must also serve media requests. ### Redirects For the download path, the homeserver could send a redirect response to a CDN backed domain. This is proposed in -MSC3860. +[MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860). For the upload path this is not possible under HTTP. From 8aba84757a68ea45c5455e5650a46040e47beaab Mon Sep 17 00:00:00 2001 From: Nick Mills-Barrett Date: Tue, 9 Aug 2022 08:37:59 +0100 Subject: [PATCH 7/9] Expand POP acronym Co-authored-by: Travis Ralston --- proposals/3859-well-known-media-domain.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3859-well-known-media-domain.md b/proposals/3859-well-known-media-domain.md index 36ee7f9e29..5eb36c827a 100644 --- a/proposals/3859-well-known-media-domain.md +++ b/proposals/3859-well-known-media-domain.md @@ -9,7 +9,7 @@ The reasoning behind this change is to support hosting media behind a CDN design serving media. Since media transfers and endpoints are very different to the other JSON based endpoints a separate domain offers maximum flexibility for server owners. This is particularly important for path optimisation between client and server over long dinstances where home internet providers generally offer inferior routing between countries -than CDN providers do. By allowing clients to upload/download from the closest CDN POP they will benefit from improved +than CDN providers do. By allowing clients to upload/download from the closest CDN Point of Presence they will benefit from improved upload and download performance. This cannot be achieved currently unless the entire homeserver is served behind a CDN, which may have other cost or From 305c9fa6154f06ccc96c7ea8989fc1cf652e7f7c Mon Sep 17 00:00:00 2001 From: Nick Mills-Barrett Date: Tue, 9 Aug 2022 08:38:06 +0100 Subject: [PATCH 8/9] Fix typo Co-authored-by: Travis Ralston --- proposals/3859-well-known-media-domain.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3859-well-known-media-domain.md b/proposals/3859-well-known-media-domain.md index 5eb36c827a..7a1f5686d7 100644 --- a/proposals/3859-well-known-media-domain.md +++ b/proposals/3859-well-known-media-domain.md @@ -8,7 +8,7 @@ for `/_matrix/media/*` endpoints. The reasoning behind this change is to support hosting media behind a CDN designed and optimised specifically for serving media. Since media transfers and endpoints are very different to the other JSON based endpoints a separate domain offers maximum flexibility for server owners. This is particularly important for path optimisation between -client and server over long dinstances where home internet providers generally offer inferior routing between countries +client and server over long distances where home internet providers generally offer inferior routing between countries than CDN providers do. By allowing clients to upload/download from the closest CDN Point of Presence they will benefit from improved upload and download performance. From c38579fc089939f5d69859fd982651aba150f5bd Mon Sep 17 00:00:00 2001 From: Nick Mills-Barrett Date: Tue, 9 Aug 2022 08:38:46 +0100 Subject: [PATCH 9/9] Use json5 for comment support in unstable section Co-authored-by: Travis Ralston --- proposals/3859-well-known-media-domain.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/proposals/3859-well-known-media-domain.md b/proposals/3859-well-known-media-domain.md index 7a1f5686d7..a8872cd0b3 100644 --- a/proposals/3859-well-known-media-domain.md +++ b/proposals/3859-well-known-media-domain.md @@ -72,15 +72,14 @@ Server admins may have to manage two distinct domains/installs increasing manage While not released in the Matrix spec implementations should use field `com.beeper.msc3859.m.media_server` in place of `m.media_server` in the well known responses: -```json -# Client +```json5 +// Client { "com.beeper.msc3859.m.media_server": { "base_url": "https://matrix-media.example.com" } } -# Server +// Server { "com.beeper.msc3859.m.media_server": "matrix-media.example.com:443" -} -``` \ No newline at end of file +} \ No newline at end of file