Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-23 19:44:09 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

C2S: Append backwards compatibility notes

Browse source
This commit is contained in:
Travis Ralston 2024-06-10 16:26:31 -06:00
parent 3e6ba86889
commit c33390f9f8
2 changed files with 49 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
content/client-server-api/modules/content_repo.md
View file

@ -44,7 +44,7 @@ mxc://<server-name>/<media-id>
<media-id> : An opaque ID which identifies the content.
```
#### Client behaviour
#### Client behaviour {id="content-repo-client-behaviour"}
Clients can access the content repository using the following endpoints.
@ -53,6 +53,33 @@ Clients can access the content repository using the following endpoints.
described below. Instead, they SHOULD use the new endpoints which require authentication.
{{% /boxes/added-in-paragraph %}}
{{% boxes/warning %}}
By Matrix 1.12, servers SHOULD "freeze" the deprecated, unauthenticated, endpoints
to prevent newly-uploaded media from being downloaded. This SHOULD mean that any
media uploaded *before* the freeze remains accessible via the deprecated endpoints,
and any media uploaded *after* (or *during*) the freeze SHOULD only be accessible
through the new, authenticated, endpoints. For remote media, "newly-uploaded" is
determined by the date the cache was populated. This may mean the media is older
than the freeze, but because the server had to re-download it, it is now considered
"new".
Clients SHOULD update to support the authenticated endpoints before servers freeze
unauthenticated access.
Servers SHOULD consider their local ecosystem impact before enacting a freeze.
This could mean ensuring their users' typical clients support the new endpoints
when available, or updating bridges to start using media proxies.
An *example* timeline for a server may be:
* Matrix 1.11 release: Clients begin supporting authenticated media.
* Matrix 1.12 release: Servers freeze unauthenticated media access.
* Media uploaded prior to this point still works with the deprecated endpoints.
* Newly uploaded (or cached) media *only* works on the authenticated endpoints.
Matrix 1.12 is expected to be released in the July-September 2024 calendar quarter.
{{% /boxes/warning %}}
{{% http-api spec="client-server" api="authed-content-repo" %}}
{{% http-api spec="client-server" api="content-repo" %}}

21
data/api/client-server/content-repo.yaml
View file

@ -219,6 +219,13 @@ paths:
get:
deprecated: true
summary: Download content from the content repository.
description: |-
{{% boxes/warning %}}
{{< changed-in v="1.11" >}} This endpoint MAY return `404 M_NOT_FOUND`
for media which exists, but is after the server froze unauthenticated
media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more
information.
{{% /boxes/warning %}}
operationId: getContent
parameters:
- $ref: '#/components/parameters/serverName'
@ -261,6 +268,13 @@ paths:
This will download content from the content repository (same as
the previous endpoint) but replace the target file name with the one
provided by the caller.
{{% boxes/warning %}}
{{< changed-in v="1.11" >}} This endpoint MAY return `404 M_NOT_FOUND`
for media which exists, but is after the server froze unauthenticated
media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more
information.
{{% /boxes/warning %}}
operationId: getContentOverrideName
parameters:
- $ref: '#/components/parameters/serverName'
@ -311,6 +325,13 @@ paths:
description: |-
Download a thumbnail of content from the content repository.
See the [Thumbnails](/client-server-api/#thumbnails) section for more information.
{{% boxes/warning %}}
{{< changed-in v="1.11" >}} This endpoint MAY return `404 M_NOT_FOUND`
for media which exists, but is after the server froze unauthenticated
media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more
information.
{{% /boxes/warning %}}
operationId: getContentThumbnail
parameters:
- $ref: '#/components/parameters/serverName'