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

Refactor documentation for content/media repository #2068

Merged
merged 4 commits into from
Jun 11, 2019
Merged

Refactor documentation for content/media repository #2068

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1f86e8e
Refactor documentation for content/media repository
turt2live Jun 3, 2019
dc6d89c
Split download endpoints back apart
turt2live Jun 3, 2019
de725c2
Add more clarity to the media repo
turt2live Jun 5, 2019
04930c6
Don't enforce MXC URIs, but also don't confuse people
turt2live Jun 11, 2019
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
126 changes: 108 additions & 18 deletions api/client-server/content-repo.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -58,18 +59,41 @@ paths:
format: byte
responses:
200:
description: The MXC URI for the uploaded content.
description: The `MXC URI`_ for the uploaded content.
schema:
type: object
required: ["content_uri"]
properties:
content_uri:
type: string
description: "The MXC URI to the uploaded content."
description: "The `MXC URI`_ to the uploaded content."
examples:
application/json: {
"content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
}
"content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
}
403:
description: |-
The user does not have permission to upload the content. Some reasons for this error include:

- The server does not permit the file type.
- The user has reached a quota for uploaded content.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot upload this content"
}
schema:
"$ref": "definitions/errors/error.yaml"
413:
description: |-
The uploaded content is too large for the server.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Cannot upload files larger than 100mb"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
Expand Down Expand Up @@ -114,10 +138,23 @@ paths:
description: "The content type of the file that was previously uploaded."
type: "string"
Content-Disposition:
description: "The name of the file that was previously uploaded, if set."
description: |-
The name of the file that was previously uploaded, if set.
type: "string"
schema:
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."
502:
description: |-
The content is too large for the server to serve.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to serve"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
Expand All @@ -126,7 +163,9 @@ paths:
- Media
"/download/{serverName}/{mediaId}/{fileName}":
get:
summary: "Download content from the content repository as a given filename."
summary: |-
Download content from the content repository. This is the same as
the download endpoint above, except permitting a desired file name.
operationId: getContentOverrideName
produces: ["*/*"]
parameters:
Expand All @@ -149,8 +188,7 @@ paths:
name: fileName
x-example: filename.jpg
required: true
description: |
The filename to give in the Content-Disposition
description: A filename to give in the ``Content-Disposition`` header.
- in: query
type: boolean
name: allow_remote
Expand All @@ -169,10 +207,24 @@ paths:
description: "The content type of the file that was previously uploaded."
type: "string"
Content-Disposition:
description: "The name of file given in the request"
description: |-
The ``fileName`` requested or the name of the file that was previously
uploaded, if set.
type: "string"
schema:
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."
502:
description: |-
The content is too large for the server to serve.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to serve"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
Expand All @@ -181,15 +233,17 @@ paths:
- Media
"/thumbnail/{serverName}/{mediaId}":
get:
summary: "Download a thumbnail of the content from the content repository."
summary: |-
Download a thumbnail of content from the content repository. See the `thumbnailing <#thumbnails>`_
section for more information.
operationId: getContentThumbnail
produces: ["image/jpeg", "image/png"]
parameters:
- in: path
type: string
name: serverName
required: true
x-example: matrix.org
x-example: example.org
description: |
The server name from the ``mxc://`` URI (the authoritory component)
- in: path
Expand All @@ -205,22 +259,24 @@ paths:
name: width
required: true
description: |-
The *desired* width of the thumbnail. The actual thumbnail may not
match the size specified.
The *desired* width of the thumbnail. The actual thumbnail may be
larger than the size specified.
Copy link
Member

Choose a reason for hiding this comment

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

Do we want to make it illegal to send a smaller size? If we have a thumbnail that is very slightly smaller than requested and one that is much larger, it doesn't seem like it would be unreasonable for the server to decide to send the smaller one.

Copy link
Member Author

Choose a reason for hiding this comment

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

We do want to make it illegal - this is covered in the thumbnails section to avoid having the requirement in multiple places.

The rationale being the last paragraph of #2060 (comment)

Copy link
Member

Choose a reason for hiding this comment

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

Hmm - so the justification there is that the server will return an image that's a little too small and the client will have to upscale, but, in riot-web at least, if the server returned a version that was too big we'd have to downscale which can still end up introducing artefacts. I thought the intended solution to this was to spec the list of standard sizes a client can request so it can ask for one of them in the knowledge that it ought to get what it asks for.

ICBW but I do seem to remember it being fairly deliberate that servers could return slightly smaller versions as well as slightly larger.

Copy link
Member Author

Choose a reason for hiding this comment

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

@ara4n seems to be the other person with strong opinions here, so pinging to drag him into this. Not sure who else has the context on this problem, but would recommend dragging them in as well.

Goal for this PR is to spec safe assumptions clients can make. I do want to avoid sliding into the position of leaving the spec vague and ignoring the problem though.

Copy link
Member

Choose a reason for hiding this comment

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

the artefacts from upscaling should always be worse than the artefacts from downscaling, given in upscaling we're trying to interpolate data which otherwise isn't there, whereas downscaling we should be able to get stuff which is at least as good quality.

Copy link
Member

Choose a reason for hiding this comment

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

If the original image is smaller than the requested thumbnail size, then do we want the server to upscale the image, or just send the original image?

Copy link
Member Author

Choose a reason for hiding this comment

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

If the original image is smaller than the requested thumbnail size, then do we want the server to upscale the image, or just send the original image?

Send the original image, otherwise the server makes the image useless to everyone.

Copy link
Member

Choose a reason for hiding this comment

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

OK - fair enough if we're sure.

- in: query
type: integer
x-example: 64
name: height
required: true
description: |-
The *desired* height of the thumbnail. The actual thumbnail may not
match the size specified.
The *desired* height of the thumbnail. The actual thumbnail may be
larger than the size specified.
- in: query
type: string
enum: ["crop", "scale"]
name: method
x-example: "scale"
description: The desired resizing method.
description: |-
The desired resizing method. See the `thumbnailing <#thumbnails>`_
section for more information.
- in: query
type: boolean
name: allow_remote
Expand All @@ -241,6 +297,40 @@ paths:
enum: ["image/jpeg", "image/png"]
schema:
type: file
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the thumbnail."
400:
description: |-
The request does not make sense to the server, or the server cannot thumbnail
the content. For example, the client requested non-integer dimensions or asked
for negatively-sized images.
examples:
application/json: {
"errcode": "M_UNKNOWN",
"error": "Cannot generate thumbnails for the requested content"
}
schema:
"$ref": "definitions/errors/error.yaml"
413:
description: |-
The local content is too large for the server to thumbnail.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to thumbnail"
}
schema:
"$ref": "definitions/errors/error.yaml"
502:
description: |-
The remote content is too large for the server to thumbnail.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to thumbnail"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
Expand All @@ -259,7 +349,7 @@ paths:
type: string
x-example: "https://matrix.org"
name: url
description: "The URL to get a preview of"
description: "The URL to get a preview of."
required: true
- in: query
type: integer
Expand Down Expand Up @@ -287,7 +377,7 @@ paths:
"og:image":
type: string
description: |-
An MXC URI to the image. Omitted if there is no image.
An `MXC URI`_ to the image. Omitted if there is no image.
examples:
application/json: {
"og:title": "Matrix Blog Post",
Expand Down
2 changes: 1 addition & 1 deletion api/client-server/room_state.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ paths:
type: object
example: {
"membership": "join",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid"
}
responses:
Expand Down
1 change: 1 addition & 0 deletions changelogs/client_server/newsfragments/2068.clarification
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Clarify how the content repository works, and what it is used for.
2 changes: 1 addition & 1 deletion event-schemas/examples/m.room.member
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"type": "m.room.member",
"content": {
"membership": "join",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid"
}
}
2 changes: 1 addition & 1 deletion event-schemas/examples/m.room.member$invite_room_state
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"$ref": "m.room.member",
"content": {
"membership": "invite",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid"
},
"unsigned": {
Expand Down
2 changes: 1 addition & 1 deletion event-schemas/examples/m.room.member$third_party_invite
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"$ref": "m.room.member",
"content": {
"membership": "invite",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid",
"third_party_invite": {
"display_name": "alice",
Expand Down
2 changes: 1 addition & 1 deletion event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ properties:
type: integer
thumbnail_url:
description: |-
The URL to a thumbnail of the image. Only present if the
The `MXC URI`_ to a thumbnail of the image. Only present if the
turt2live marked this conversation as resolved.
Show resolved Hide resolved
thumbnail is unencrypted.
type: string
thumbnail_file:
Expand Down
2 changes: 1 addition & 1 deletion event-schemas/schema/m.room.message$m.audio
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ properties:
- m.audio
type: string
url:
description: Required if the file is not encrypted. The URL to the audio clip.
description: Required if the file is not encrypted. The `MXC URI`_ to the audio clip.
type: string
file:
description: |-
Expand Down
2 changes: 1 addition & 1 deletion event-schemas/schema/m.room.message$m.file
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ properties:
- m.file
type: string
url:
description: Required if the file is unencrypted. The URL to the file.
description: Required if the file is unencrypted. The `MXC URI`_ to the file.
type: string
file:
description: |-
Expand Down
2 changes: 1 addition & 1 deletion event-schemas/schema/m.room.message$m.image
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ properties:
- m.image
type: string
url:
description: Required if the file is unencrypted. The URL to the image.
description: Required if the file is unencrypted. The `MXC URI`_ to the image.
type: string
file:
description: |-
Expand Down
4 changes: 2 additions & 2 deletions event-schemas/schema/m.room.message$m.video
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ properties:
type: integer
thumbnail_url:
description: |-
The URL to an image thumbnail of the video clip. Only present if the
The `MXC URI`_ to an image thumbnail of the video clip. Only present if the
thumbnail is unencrypted.
type: string
thumbnail_file:
Expand All @@ -48,7 +48,7 @@ properties:
- m.video
type: string
url:
description: Required if the file is unencrypted. The URL to the video clip.
description: Required if the file is unencrypted. The `MXC URI`_ to the video clip.
type: string
file:
description: |-
Expand Down
Loading