[WIP] MSC2370: Resolve URL API by uhoreg · Pull Request #2370 · matrix-org/matrix-spec-proposals

uhoreg · 2019-11-29T20:16:47Z

This is a markdown-ification of #1270, with some clarifications and expansions added.

Rendered: https://github.com/uhoreg/matrix-doc/blob/resolve_url/proposals/2370-resolve-url.md

…ations

uhoreg · 2019-11-29T20:23:12Z

+
+Request:
+```
+POST /_matrix/media/v1/resolve_url


Would this be better as a GET request (like GET /_matrix/media/r0/preview_url )?

Like GET /_matrix/media/v1/resolve_url?url=https://blabla.com? I was going to say it's annoying to have to URL-encode a URL, but seeing as /preview_url already requires this then it's probably fine.

Also why v1 whereas /preview_url is r0?

Also why v1 whereas /preview_url is r0?

Indeed. I copied this from the original doc, but the rest of /media uses r0, so this should too. Fixed.

As far as GET vs POST, I suppose it could be argued that since it causes something to be stored on the server, it should be a POST, whereas /preview_url does not cause anything to be stored on the server (beyond possible caching), so it's fine as a GET. I don't really have strong opinions either way, so if anyone does have opinions, please say so.

Annoyingly media is weird. It's still in the v1 version.

Spec says r0 though. https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-media-r0-preview-url :-/

uhoreg · 2019-11-29T20:25:20Z

+* If the resource cannot be downloaded because it has been blacklisted, it should
+  respond with an `M_FORBIDDEN` error and HTTP code 403.
+* If the resource is larger than the homeserver's upload size limit, it should
+  respond with an `M_TOO_LARGE` error and HTTP code 400.


The original proposal listed this an HTTP code 413. However it seems like 413 is for when the request payload is too large, rather than for when a referenced resource is too large, so I think that just a generic 400 would be better here.

uhoreg · 2019-11-29T20:50:26Z

+* If the resource cannot be downloaded due to the URL returning another error,
+  the endpoint should respond with an `M_UNKNOWN` error and HTTP code 400.
+* If the resource cannot be downloaded because it has been blacklisted, it should
+  respond with an `M_FORBIDDEN` error and HTTP code 403.


For reference, synapse returns M_UNKNOWN with HTTP code 403 on /preview_url, but using M_FORBIDDEN seems more useful.

Indeed, another MSC time? :)

anoadragon453

I was dumb and didn't put my above comments in a review. So here's one to track my current thoughts on the doc.

turt2live · 2019-12-07T02:01:07Z

@NotAFile please use a comment on the diff so others can reply more easily, even if it means putting the comment onto the title.

NotAFile · 2019-12-07T02:09:23Z

+(This document is heavily based on
+https://docs.google.com/document/d/1bbX1yxNETmMa-AxBGjIpb4lNoTuc3vjGXmbZWrNBlzM/edit)
+
+Users sometimes want to upload images to Matrix rooms that they see on other


I don't quite understand why this is necessary. The URL preview API already returns images for links in messages, which riot displays, albeit smaller than full images:

The way some platforms like e.g. Telegram do this is to show message that contain image links with a preview that is very similar in size to posting a full image:

So the data is basically already there, Riot just needs to display image URL previews as big as images.

Doing this over the approach in this MSC has a few advantages in my opinion:

No new API required. No additional Complexity is needed for servers and clients to implement.

Saves storage Space. While the server still needs to proxy the image for privacy reasons, the server does not need to store the image forever. It can cache it short term and re-download it again later on demand.

It requires no changes on the sending clients side, so it instantly works for everyone's messages. It also works with e.g. irc rooms, and in any message history predating this feature.

It preserves the context that this is an image that's not created by the user, but downloaded from some URL.

The semantics are different. If you post a URL, then you are dependent on that server hosting the image. Which means:

if the server goes down, then you no longer have access to the image

if the image on the server changes, then people will see a different image. This may or may not be what you want, depending on context.

Yes, pasting a URL and relying on URL preview may work in some cases, but may not work in others. For those cases where pasting a URL works, people are still free to use that.

Well, I think those objections are correct, but they exist identically for all URL previews, not just specifically sending images.

So, if those semantics are desired, why not still just reuse the URL preview API but query it before sending? URL previews obviously already support returning images.

So I understand why you'd want to get the image on the sender side now, but still not why we need a new, more limited version of an existing API for this functionality.

If you just use the URL preview API:

you don't know if the "preview" is exactly the same image, or a scaled/stripped version

you have to download and re-upload the image, rather than just have the server download the image and keep it

URL preview works that way for images, but what about audio or video files?

URL preview works that way for images, but what about audio or video files?

So, my suggestion is to expand it to audio and video files, as Telegram does.

The reuploading point is valid though. Especially so for bridging.

So, my suggestion is to expand it to audio and video files, as Telegram does.

"Previewing" a video file is semantically different from serving a copy of the file. A preview of a video file could legitimately be a single frame of the video, which would be different from what this MSC proposes. Similarly, a preview of a PDF would probably be a low-resolution image of the first page of the PDF. And, as I mentioned, a preview for an image file could be a scaled-down version of the image, rather than a copy of the original image.

Basically, this API is intended for a different use from the preview API.

Co-Authored-By: Travis Ralston <travpc@gmail.com>

Sorunome · 2020-04-03T19:13:07Z

+
+Additionally, servers implementing this feature should advertise that they do
+so by exposing a `org.matrix.resolve_url` flag in the `unstable_features` part
+of the `/versions` response.


Alternative suggestion: Somehow make like mxc://proxy/<url here> things that will proxy that image, then. That way you can just url-encode the image / file you want an mxc link for and already have it. The media repo can handle something like caching, then, if wanted.

This would actually make bridging easier as you might end up with a lot of image URLs you want to display for just one image in an <img> tag, and that way you don't clutter your servers disk.

uhoreg added 2 commits November 29, 2019 15:08

initial conversion from Google doc, with some expansions and clarific…

5281116

…ations

rename to match MSC number

346b7d1

uhoreg changed the title ~~MSC xxxx: Resolve URL API~~ MSC 2370: Resolve URL API Nov 29, 2019

add information about unstable prefixes

9d88a8e

uhoreg commented Nov 29, 2019

View reviewed changes

uhoreg added the proposal A matrix spec change proposal label Nov 29, 2019

uhoreg commented Nov 29, 2019

View reviewed changes

add a security consideration abound e2ee rooms

5116826

turt2live changed the title ~~MSC 2370: Resolve URL API~~ MSC2370: Resolve URL API Nov 29, 2019

turt2live self-requested a review November 29, 2019 22:15

uhoreg mentioned this pull request Nov 29, 2019

Proposal Add /_matrix/media/v1/resolve_url to Client-Server API: download and preview urls in the clients despite CORS #1270

Closed

anoadragon453 reviewed Dec 3, 2019

View reviewed changes

Comment thread proposals/2370-resolve-url.md

anoadragon453 requested changes Dec 3, 2019

View reviewed changes

use the right prefix

face0c7

NotAFile reviewed Dec 7, 2019

View reviewed changes

turt2live changed the title ~~MSC2370: Resolve URL API~~ [WIP] MSC2370: Resolve URL API Dec 7, 2019

turt2live approved these changes Dec 13, 2019

View reviewed changes

Comment thread proposals/2370-resolve-url.md Outdated

Update proposals/2370-resolve-url.md

11ac726

Co-Authored-By: Travis Ralston <travpc@gmail.com>

Sorunome reviewed Apr 3, 2020

View reviewed changes

turt2live added the kind:feature MSC for not-core and not-maintenance stuff label Apr 20, 2020

turt2live marked this pull request as draft April 8, 2021 23:36

turt2live added the needs-implementation This MSC does not have a qualifying implementation for the SCT to review. The MSC cannot enter FCP. label Jun 8, 2021

turt2live force-pushed the old_master branch from e895827 to dca99ee Compare August 30, 2021 22:34

turt2live mentioned this pull request Jul 17, 2023

Add support for resolve URL API (MSC2370) t2bot/matrix-media-repo#417

Open

t3chguy mentioned this pull request Jul 17, 2023

How to upload an image from a URL matrix-org/matrix-js-sdk#1107

Closed

almereyda mentioned this pull request Aug 11, 2025

URL Preview for private URLs with active integrations (GitHub, GitLab, Jira) element-hq/synapse#18795

Open

Conversation

uhoreg commented Nov 29, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

anoadragon453 left a comment

Choose a reason for hiding this comment

Uh oh!

turt2live commented Dec 7, 2019

Uh oh!

NotAFile Dec 7, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NotAFile Dec 9, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

uhoreg commented Nov 29, 2019 •

edited

Loading

NotAFile Dec 7, 2019 •

edited

Loading

NotAFile Dec 9, 2019 •

edited

Loading