From 2f528029c9ff77367b84afa7fce8aa0e3582e3af Mon Sep 17 00:00:00 2001 From: reivilibre Date: Tue, 11 Jun 2024 15:22:12 +0100 Subject: [PATCH 01/70] Note that /logout doesn't take a body (#1644) --- .../client_server/newsfragments/1644.clarification | 1 + content/client-server-api/_index.md | 13 ++++++++++--- 2 files changed, 11 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1644.clarification diff --git a/changelogs/client_server/newsfragments/1644.clarification b/changelogs/client_server/newsfragments/1644.clarification new file mode 100644 index 00000000..78c0919d --- /dev/null +++ b/changelogs/client_server/newsfragments/1644.clarification @@ -0,0 +1 @@ +Clarify specification by adding `/logout` to the overview list of endpoints that don't take a JSON request body. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 71f92bec..9a6c6a68 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -22,13 +22,20 @@ recommended outside test environments. Clients are authenticated using opaque `access_token` strings (see [Client Authentication](#client-authentication) for details). -All `POST` and `PUT` endpoints, with the exception of [`POST -/_matrix/media/v3/upload`](#post_matrixmediav3upload) and [`PUT -/_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid), +All `POST` and `PUT` endpoints, with the exception of those listed below, require the client to supply a request body containing a (potentially empty) JSON object. Clients should supply a `Content-Type` header of `application/json` for all requests with JSON bodies, but this is not required. +The exceptions are: + +- [`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload) and + [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid), + both of which take the uploaded media as the request body. +- [`POST /_matrix/client/v3/logout`](#post_matrixclientv3logout) and + [`POST /_matrix/client/v3/logout/all`](#post_matrixclientv3logoutall), + which take an empty request body. + Similarly, all endpoints require the server to return a JSON object, with the exception of 200 responses to [`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](#get_matrixmediav3downloadservernamemediaid) From c4b4c896b74a13b0eb0782e7de175f578a9dfe72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 11 Jun 2024 17:59:29 +0200 Subject: [PATCH 02/70] Replace references to RFC7235 and RFC7230 with references to RFC9110 (#1844) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../server_server/newsfragments/1844.clarification | 1 + content/server-server-api.md | 11 +++++++++-- 2 files changed, 10 insertions(+), 2 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1844.clarification diff --git a/changelogs/server_server/newsfragments/1844.clarification b/changelogs/server_server/newsfragments/1844.clarification new file mode 100644 index 00000000..81013eb6 --- /dev/null +++ b/changelogs/server_server/newsfragments/1844.clarification @@ -0,0 +1 @@ +Replace references to RFC 7235 and RFC 7230 that are obsoleted by RFC 9110. \ No newline at end of file diff --git a/content/server-server-api.md b/content/server-server-api.md index e92d871c..365613df 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -349,14 +349,14 @@ def authorization_headers(origin_name, origin_signing_key, ``` The format of the Authorization header is given in -[RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1). In +[Section 11.4 of RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#section-11.4). In summary, the header begins with authorization scheme `X-Matrix`, followed by one or more spaces, followed by a comma-separated list of parameters written as name=value pairs. Zero or more spaces and tabs around each comma are allowed. The names are case insensitive and order does not matter. The values must be enclosed in quotes if they contain characters that are not allowed in `token`s, as defined in -[RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6); if a +[Section 5.6.2 of RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#section-5.6.2); if a value is a valid `token`, it may or may not be enclosed in quotes. Quoted values may include backslash-escaped characters. When parsing the header, the recipient must unescape the characters. That is, a backslash-character pair is @@ -388,6 +388,13 @@ The authorization parameters to include are: Unknown parameters are ignored. +{{% boxes/note %}} +{{< changed-in v="1.11" >}} +This section used to reference [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1) +and [RFC 7230](https://datatracker.ietf.org/doc/html/rfc9110#section-5.6.2), that +were obsoleted by RFC 9110 without changes to the sections of interest here. +{{% /boxes/note %}} + ### Response Authentication Responses are authenticated by the TLS server certificate. A homeserver From acec09f567a7bef7e3ac09df15b13f7ce2c920b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 11 Jun 2024 18:03:53 +0200 Subject: [PATCH 03/70] Do not add empty arrays to examples (#1849) --- changelogs/internal/newsfragments/1849.clarification | 1 + layouts/partials/json-schema/resolve-example.html | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) create mode 100644 changelogs/internal/newsfragments/1849.clarification diff --git a/changelogs/internal/newsfragments/1849.clarification b/changelogs/internal/newsfragments/1849.clarification new file mode 100644 index 00000000..fc7c5d88 --- /dev/null +++ b/changelogs/internal/newsfragments/1849.clarification @@ -0,0 +1 @@ +Do not add empty arrays to examples. diff --git a/layouts/partials/json-schema/resolve-example.html b/layouts/partials/json-schema/resolve-example.html index 09b4254e..8fa98400 100644 --- a/layouts/partials/json-schema/resolve-example.html +++ b/layouts/partials/json-schema/resolve-example.html @@ -35,9 +35,9 @@ */}} {{ if reflect.IsMap $this_object.items }} {{ $items_example := partial "json-schema/resolve-example" $this_object.items }} - {{ $example = slice $items_example }} - {{ else }} - {{ $example = slice }} + {{ if $items_example }} + {{ $example = slice $items_example }} + {{ end }} {{ end }} {{ end }} From a7a7eadf2cad1dbe72f41488b3f9bfcb08ea1c37 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 11 Jun 2024 13:02:46 -0400 Subject: [PATCH 04/70] Clarify when an event is returned from /send_join. (#1840) --- changelogs/server_server/newsfragments/1834.clarification | 2 +- changelogs/server_server/newsfragments/1840.clarification | 1 + data/api/server-server/joins-v2.yaml | 6 +++--- 3 files changed, 5 insertions(+), 4 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1840.clarification diff --git a/changelogs/server_server/newsfragments/1834.clarification b/changelogs/server_server/newsfragments/1834.clarification index fa927cca..80c2fa48 100644 --- a/changelogs/server_server/newsfragments/1834.clarification +++ b/changelogs/server_server/newsfragments/1834.clarification @@ -1 +1 @@ -Clarify that the `event` field of the `/v2/send_join` response is only required when `join_authorised_via_users_server` was present in the `content` field of the request. +Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server. diff --git a/changelogs/server_server/newsfragments/1840.clarification b/changelogs/server_server/newsfragments/1840.clarification new file mode 100644 index 00000000..80c2fa48 --- /dev/null +++ b/changelogs/server_server/newsfragments/1840.clarification @@ -0,0 +1 @@ +Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server. diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 7804a6f6..465207e9 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -207,9 +207,9 @@ paths: title: SignedMembershipEvent x-addedInMatrixVersion: "1.2" description: |- - Required if the `content` of the event in the request contained the `join_authorised_via_users_server` - field. The signed copy of the membership event sent to other servers by the resident server, - including the resident server's signature. + The membership event sent to other servers by the resident server including a signature + from the resident server. Required if the room is [restricted](/client-server-api/#restricted-rooms) + and the joining user is authorised by one of the conditions. servers_in_room: type: array x-addedInMatrixVersion: "1.6" From 784b8984f36aa3d0317471d858ccbc875a78893e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 11 Jun 2024 23:24:23 +0200 Subject: [PATCH 05/70] Generate ToC with Hugo rather than JavaScript (#1851) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .github/workflows/main.yml | 2 +- .htmltest.yaml | 1 + README.md | 2 +- .../internal/newsfragments/1851.clarification | 1 + config.toml | 6 +- content/client-server-api/_index.md | 78 ++++---- layouts/partials/sidebar-tree.html | 83 +++++++++ layouts/partials/toc.html | 15 ++ layouts/shortcodes/changelog/changelogs.html | 2 +- layouts/shortcodes/cs-module.html | 2 +- static/js/toc.js | 170 ------------------ 11 files changed, 148 insertions(+), 214 deletions(-) create mode 100644 changelogs/internal/newsfragments/1851.clarification create mode 100644 layouts/partials/sidebar-tree.html create mode 100644 layouts/partials/toc.html diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 09a184a7..cb14a0c1 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -193,7 +193,7 @@ jobs: - name: "➕ Setup Hugo" uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0 with: - hugo-version: '0.113.0' + hugo-version: '0.117.0' extended: true - name: "📥 Source checkout" uses: actions/checkout@v4 diff --git a/.htmltest.yaml b/.htmltest.yaml index 1563408b..52eedee5 100644 --- a/.htmltest.yaml +++ b/.htmltest.yaml @@ -4,3 +4,4 @@ IgnoreDirectoryMissingTrailingSlash: true DirectoryPath: spec CheckExternal: false +IgnoreInternalEmptyHash: true diff --git a/README.md b/README.md index 17fa5614..a0ba854e 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ place after an MSC has been accepted, not as part of a proposal itself. 1. Install the extended version (often the OS default) of Hugo: . Note that at least Hugo - v0.113.0 is required. + v0.117.0 is required. Alternatively, use the Docker image at https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required diff --git a/changelogs/internal/newsfragments/1851.clarification b/changelogs/internal/newsfragments/1851.clarification new file mode 100644 index 00000000..e89777c5 --- /dev/null +++ b/changelogs/internal/newsfragments/1851.clarification @@ -0,0 +1 @@ +Generate ToC with Hugo rather than JavaScript. diff --git a/config.toml b/config.toml index a4245d0b..15003eee 100644 --- a/config.toml +++ b/config.toml @@ -37,6 +37,10 @@ description = "Home of the Matrix specification for decentralised communication" weight = 30 [markup] + [markup.tableOfContents] + startLevel = 2 + endLevel = 6 + ordered = true [markup.goldmark] [markup.goldmark.renderer] # Enables us to render raw HTML @@ -130,7 +134,7 @@ sidebar_menu_compact = true [module] [module.hugoVersion] extended = true - min = "0.113.0" + min = "0.117.0" [[module.imports]] path = "github.com/matrix-org/docsy" disable = false diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 9a6c6a68..86dcda1a 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2812,42 +2812,42 @@ operations and run in a resource constrained environment. Like embedded applications, they are not intended to be fully-fledged communication systems. -{{< cs-module name="instant_messaging" >}} -{{< cs-module name="rich_replies" >}} -{{< cs-module name="voip_events" >}} -{{< cs-module name="typing_notifications" >}} -{{< cs-module name="receipts" >}} -{{< cs-module name="read_markers" >}} -{{< cs-module name="presence" >}} -{{< cs-module name="content_repo" >}} -{{< cs-module name="send_to_device" >}} -{{< cs-module name="device_management" >}} -{{< cs-module name="end_to_end_encryption" >}} -{{< cs-module name="secrets" >}} -{{< cs-module name="history_visibility" >}} -{{< cs-module name="push" >}} -{{< cs-module name="third_party_invites" >}} -{{< cs-module name="search" >}} -{{< cs-module name="guest_access" >}} -{{< cs-module name="room_previews" >}} -{{< cs-module name="tags" >}} -{{< cs-module name="account_data" >}} -{{< cs-module name="admin" >}} -{{< cs-module name="event_context" >}} -{{< cs-module name="sso_login" >}} -{{< cs-module name="dm" >}} -{{< cs-module name="ignore_users" >}} -{{< cs-module name="stickers" >}} -{{< cs-module name="report_content" >}} -{{< cs-module name="third_party_networks" >}} -{{< cs-module name="openid" >}} -{{< cs-module name="server_acls" >}} -{{< cs-module name="mentions" >}} -{{< cs-module name="room_upgrades" >}} -{{< cs-module name="server_notices" >}} -{{< cs-module name="moderation_policies" >}} -{{< cs-module name="spaces" >}} -{{< cs-module name="event_replacements" >}} -{{< cs-module name="event_annotations" >}} -{{< cs-module name="threading" >}} -{{< cs-module name="reference_relations" >}} +{{% cs-module name="instant_messaging" %}} +{{% cs-module name="rich_replies" %}} +{{% cs-module name="voip_events" %}} +{{% cs-module name="typing_notifications" %}} +{{% cs-module name="receipts" %}} +{{% cs-module name="read_markers" %}} +{{% cs-module name="presence" %}} +{{% cs-module name="content_repo" %}} +{{% cs-module name="send_to_device" %}} +{{% cs-module name="device_management" %}} +{{% cs-module name="end_to_end_encryption" %}} +{{% cs-module name="secrets" %}} +{{% cs-module name="history_visibility" %}} +{{% cs-module name="push" %}} +{{% cs-module name="third_party_invites" %}} +{{% cs-module name="search" %}} +{{% cs-module name="guest_access" %}} +{{% cs-module name="room_previews" %}} +{{% cs-module name="tags" %}} +{{% cs-module name="account_data" %}} +{{% cs-module name="admin" %}} +{{% cs-module name="event_context" %}} +{{% cs-module name="sso_login" %}} +{{% cs-module name="dm" %}} +{{% cs-module name="ignore_users" %}} +{{% cs-module name="stickers" %}} +{{% cs-module name="report_content" %}} +{{% cs-module name="third_party_networks" %}} +{{% cs-module name="openid" %}} +{{% cs-module name="server_acls" %}} +{{% cs-module name="mentions" %}} +{{% cs-module name="room_upgrades" %}} +{{% cs-module name="server_notices" %}} +{{% cs-module name="moderation_policies" %}} +{{% cs-module name="spaces" %}} +{{% cs-module name="event_replacements" %}} +{{% cs-module name="event_annotations" %}} +{{% cs-module name="threading" %}} +{{% cs-module name="reference_relations" %}} diff --git a/layouts/partials/sidebar-tree.html b/layouts/partials/sidebar-tree.html new file mode 100644 index 00000000..f5a34b23 --- /dev/null +++ b/layouts/partials/sidebar-tree.html @@ -0,0 +1,83 @@ +{{/* + + A modified version of the siderbar-tree.html partial in Docsy, adding: + + * The "toc.html" partial at L45. + +*/}} + +{{/* We cache this partial for bigger sites and set the active class client side. */ -}} +{{ $sidebarCacheLimit := .Site.Params.ui.sidebar_cache_limit | default 2000 -}} +{{ $shouldDelayActive := ge (len .Site.Pages) $sidebarCacheLimit -}} +
+ {{ if not .Site.Params.ui.sidebar_search_disable -}} +
+ {{ partial "search-input.html" . }} + +
+ {{ else -}} +
+
+ {{ partial "search-input.html" . }} + +
+
+
+ {{ end -}} + +
+{{ define "section-tree-nav-section" -}} +{{ $s := .section -}} +{{ $p := .page -}} +{{ $shouldDelayActive := .shouldDelayActive -}} +{{ $sidebarMenuTruncate := .sidebarMenuTruncate -}} +{{ $treeRoot := cond (eq .ulNr 0) true false -}} +{{ $ulNr := .ulNr -}} +{{ $ulShow := .ulShow -}} +{{ $active := and (not $shouldDelayActive) (eq $s $p) -}} +{{ $activePath := and (not $shouldDelayActive) (or (eq $p $s) ($p.IsDescendant $s)) -}} +{{ $show := cond (or (lt $ulNr $ulShow) $activePath (and (not $shouldDelayActive) (eq $s.Parent $p.Parent)) (and (not $shouldDelayActive) (eq $s.Parent $p)) (not $p.Site.Params.ui.sidebar_menu_compact) (and (not $shouldDelayActive) ($p.IsDescendant $s.Parent))) true false -}} +{{ $mid := printf "m-%s" ($s.RelPermalink | anchorize) -}} +{{ $pages_tmp := where (union $s.Pages $s.Sections).ByWeight ".Params.toc_hide" "!=" true -}} +{{ $pages := $pages_tmp | first $sidebarMenuTruncate -}} +{{ $withChild := gt (len $pages) 0 -}} +{{ $manualLink := cond (isset $s.Params "manuallink") $s.Params.manualLink ( cond (isset $s.Params "manuallinkrelref") (relref $s $s.Params.manualLinkRelref) $s.RelPermalink) -}} +{{ $manualLinkTitle := cond (isset $s.Params "manuallinktitle") $s.Params.manualLinkTitle $s.Title -}} +
  • + {{ if (and $p.Site.Params.ui.sidebar_menu_foldable (ge $ulNr 1)) -}} + + + {{ else -}} + {{ with $s.Params.Icon}}{{ end }}{{ $s.LinkTitle }} + {{- end }} + {{- if $withChild }} + {{- $ulNr := add $ulNr 1 }} +
      + {{ range $pages -}} + {{ if (not (and (eq $s $p.Site.Home) (eq .Params.toc_root true))) -}} + {{ template "section-tree-nav-section" (dict "page" $p "section" . "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" $ulShow) }} + {{- end }} + {{- end }} +
    + {{- end }} +
    • +{{- end }} \ No newline at end of file diff --git a/layouts/partials/toc.html b/layouts/partials/toc.html new file mode 100644 index 00000000..318335f2 --- /dev/null +++ b/layouts/partials/toc.html @@ -0,0 +1,15 @@ +{{/* + + A modified version of the toc.html partial in Docsy. + +*/}} +{{ $page := .Params }} +{{ if not .Params.notoc -}} + {{ with .TableOfContents -}} +
    +
    + {{ $page.Title }} + {{ . }} +
    + {{ end -}} +{{ end -}} diff --git a/layouts/shortcodes/changelog/changelogs.html b/layouts/shortcodes/changelog/changelogs.html index 78b5932f..f42963da 100644 --- a/layouts/shortcodes/changelog/changelogs.html +++ b/layouts/shortcodes/changelog/changelogs.html @@ -5,6 +5,6 @@ {{ with .Page.Resources.Match "*.md" }} {{ range ((sort . "Params.date" "desc")) }} -{{ .Content }} +{{ .RenderShortcodes }} {{ end }} {{ end }} diff --git a/layouts/shortcodes/cs-module.html b/layouts/shortcodes/cs-module.html index 475ebd48..52c9a5d9 100644 --- a/layouts/shortcodes/cs-module.html +++ b/layouts/shortcodes/cs-module.html @@ -11,6 +11,6 @@ {{ with .Site.GetPage "client-server-api/modules" }} {{ with .Resources.GetMatch (printf "%s%s" $name ".md") }} -{{ .Content }} +{{ .RenderShortcodes }} {{ end }} {{ end }} diff --git a/static/js/toc.js b/static/js/toc.js index 6386e40d..786ec6c6 100644 --- a/static/js/toc.js +++ b/static/js/toc.js @@ -14,174 +14,6 @@ See the License for the specific language governing permissions and limitations under the License. */ -/* -Account for id attributes that are in the sidebar nav -*/ -function populateIds() { - const navItems = document.querySelectorAll(".td-sidebar-nav li"); - return Array.from(navItems).map(item => item.id).filter(id => id != ""); -} - -/* -Given an ID and an array of IDs, return s version of the original ID that's -not equal to any of the IDs in the array. -*/ -function uniquifyHeadingId(id, uniqueIDs) { - const baseId = id; - let counter = 0; - while (uniqueIDs.includes(id)) { - counter = counter + 1; - id = baseId + "-" + counter.toString(); - } - return id; -} - -/* -Given an array of heading nodes, ensure they all have unique IDs. - -We have to do this mostly because of client-server modules, which are -rendered separately then glued together with a template. -Because heading IDs are generated in rendering, this means they can and will -end up with duplicate IDs. -*/ -function uniquifyHeadingIds(headings) { - const uniqueIDs = populateIds(); - for (let heading of headings) { - const uniqueID = uniquifyHeadingId(heading.id, uniqueIDs); - uniqueIDs.push(uniqueID); - heading.id = uniqueID; - } -} - -/* -The document contains "normal" headings, and these have corresponding items -in the ToC. - -The document might also contain H1 headings that act as titles for blocks of -rendered data, like HTTP APIs or event schemas. Unlike "normal" headings, -these headings don't appear in the ToC. But they do have anchor IDs to enable -links to them. When someone follows a link to one of these "rendered data" -headings we want to scroll the ToC to the item corresponding to the "normal" -heading preceding the "rendered data" heading we have visited. - -To support this we need to add `data` attributes to ToC items. -These attributes identify which "rendered data" headings live underneath -the heading corresponding to that ToC item. -*/ -function setTocItemChildren(toc, headings) { - let tocEntryForHeading = null; - for (const heading of headings) { - // H1 headings are rendered-data headings - if (heading.tagName !== "H1") { - tocEntryForHeading = document.querySelector(`nav li a[href="#${heading.id}"]`); - } else { - // on the ToC entry for the parent heading, - // set a data-* attribute whose name is the child's fragment ID - tocEntryForHeading.setAttribute(`data-${heading.id}`, "true"); - } - } -} - -/* -Generate a table of contents based on the headings in the document. -*/ -function makeToc() { - - // make the title from the H1 - const h1 = document.body.querySelector("h1"); - const title = document.createElement("a"); - title.id = "toc-title"; - title.setAttribute("href", "#"); - title.textContent = h1.textContent; - - // make the content - const content = document.body.querySelector(".td-content"); - let headings = [].slice.call(content.querySelectorAll("h2, h3, h4, h5, h6, .rendered-data > details > summary > h1")); - - // exclude headings that don't have IDs. - headings = headings.filter(heading => heading.id); - uniquifyHeadingIds(headings); - - // exclude .rendered-data > h1 headings from the ToC - const tocTargets = headings.filter(heading => heading.tagName !== "H1"); - - // we have to adjust heading IDs to ensure that they are unique - const nav = document.createElement("nav"); - nav.id = "TableOfContents"; - - const section = makeTocSection(tocTargets, 0); - nav.appendChild(section.content); - // build the TOC and append to it title and content - const toc = document.createElement("div"); - toc.id = "toc"; - toc.appendChild(title); - toc.appendChild(nav); - - // append TOC to the section navigation - const section_nav = document.body.querySelector("#td-section-nav"); - let hr = document.createElement("hr"); - section_nav.appendChild(hr); - section_nav.appendChild(toc); - - // tell ToC items about any rendered-data headings they contain - setTocItemChildren(section.content, headings); -} - -// create a single ToC entry -function makeTocEntry(heading) { - const li = document.createElement("li"); - const a = document.createElement("a"); - a.setAttribute("href", `#${heading.id}`); - a.textContent = heading.textContent; - li.appendChild(a); - return li; -} - -/* -Each ToC section is an `
      ` element. -ToC entries are `
    1. ` elements and these contain nested ToC sections, -whenever we go to the next heading level down. -*/ -function makeTocSection(headings, index) { - const ol = document.createElement("ol"); - let previousHeading = null; - let previousLi = null; - let i = index; - const lis = []; - for (i; i < headings.length; i++) { - const thisHeading = headings[i]; - if (previousHeading && (thisHeading.tagName > previousHeading.tagName)) { - // we are going down a heading level, create a new nested section - const section = makeTocSection(headings, i); - previousLi.appendChild(section.content); - i = section.index -1; - } - else if (previousHeading && (previousHeading.tagName > thisHeading.tagName)) { - // we have come back up a level, so a section is finished - for (let li of lis) { - ol.appendChild(li); - } - return { - content: ol, - index: i - } - } - else { - // we are still processing this section, so add this heading to the current section - previousLi = makeTocEntry(thisHeading); - lis.push(previousLi); - previousHeading = thisHeading; - } - } - for (let li of lis) { - ol.appendChild(li); - } - return { - content: ol, - index: i - } -} - /* Set a new ToC entry. Clear any previously highlighted ToC items, set the new one, @@ -303,8 +135,6 @@ for the corresponding ToC entry. */ window.addEventListener('DOMContentLoaded', () => { - makeToc(); - const toc = document.querySelector("#toc"); toc.addEventListener("click", event => { if (event.target.tagName === "A") { From 520b8398d86e8211f237ca0e8c0ef46915bdf9e3 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 11 Jun 2024 23:36:24 +0200 Subject: [PATCH 06/70] Add missing word header (#1852) * Add missing word header Signed-off-by: Johannes Marbach * Add changelog --------- Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/1852.clarification | 1 + content/client-server-api/_index.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1852.clarification diff --git a/changelogs/client_server/newsfragments/1852.clarification b/changelogs/client_server/newsfragments/1852.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1852.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 86dcda1a..126a5103 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -234,7 +234,7 @@ return a standard error response of the form: ``` Homeservers SHOULD include a [`Retry-After`](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after) -for any response with a 429 status code. +header for any response with a 429 status code. The `retry_after_ms` property MAY be included to tell the client how long they have to wait in milliseconds before they can try again. This property is From da3e884aaa388c246944262038f4229d2d354641 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 11 Jun 2024 17:42:46 -0400 Subject: [PATCH 07/70] Fix broken link to push rule condition kinds. (#1841) --- changelogs/client_server/newsfragments/1841.clarification | 1 + data/api/client-server/definitions/push_condition.yaml | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1841.clarification diff --git a/changelogs/client_server/newsfragments/1841.clarification b/changelogs/client_server/newsfragments/1841.clarification new file mode 100644 index 00000000..faf8aae9 --- /dev/null +++ b/changelogs/client_server/newsfragments/1841.clarification @@ -0,0 +1 @@ +Fix broken link to push rule condition kinds. diff --git a/data/api/client-server/definitions/push_condition.yaml b/data/api/client-server/definitions/push_condition.yaml index 4c35cfe4..1e7a8583 100644 --- a/data/api/client-server/definitions/push_condition.yaml +++ b/data/api/client-server/definitions/push_condition.yaml @@ -18,7 +18,7 @@ properties: kind: type: string description: |- - The kind of condition to apply. See [conditions](/client-server-api/#conditions) for + The kind of condition to apply. See [conditions](/client-server-api/#conditions-1) for more information on the allowed kinds and how they work. key: type: string From 3517846916c83aac01bfcbfd763fd118230d4b87 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 12 Jun 2024 03:38:33 +0200 Subject: [PATCH 08/70] Add missing modules to feature profiles (#1860) * Add missing modules to feature profiles Signed-off-by: Johannes Marbach * Add changelog --------- Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/1860.clarification | 1 + content/client-server-api/_index.md | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1860.clarification diff --git a/changelogs/client_server/newsfragments/1860.clarification b/changelogs/client_server/newsfragments/1860.clarification new file mode 100644 index 00000000..ca6e4117 --- /dev/null +++ b/changelogs/client_server/newsfragments/1860.clarification @@ -0,0 +1 @@ +Add missing secrets, third-party invites and room tagging modules to feature profiles table. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 126a5103..851c64cb 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2764,6 +2764,9 @@ that profile. | [Event Annotations and reactions](#event-annotations-and-reactions) | Optional | Optional | Optional | Optional | Optional | | [Threading](#threading) | Optional | Optional | Optional | Optional | Optional | | [Reference Relations](#reference-relations) | Optional | Optional | Optional | Optional | Optional | +| [Secrets](#secrets) | Optional | Optional | Optional | Optional | Optional | +| [Third-party Invites](#third-party-invites) | Optional | Required | Optional | Optional | Optional | +| [Room Tagging](#room-tagging) | Optional | Optional | Optional | Optional | Optional | *Please see each module for more details on what clients need to implement.* From 7916032a787b4e7bbbb163ff9da2fb5d965514d2 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 12 Jun 2024 10:11:07 +0200 Subject: [PATCH 09/70] Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes (#1850) Fixes: #1826 Relates to: #1001 Signed-off-by: Johannes Marbach --- .../appendices/newsfragments/1850.clarification | 1 + .../client_server/newsfragments/1850.clarification | 1 + content/appendices.md | 13 +++++++++---- content/client-server-api/_index.md | 9 ++++----- 4 files changed, 15 insertions(+), 9 deletions(-) create mode 100644 changelogs/appendices/newsfragments/1850.clarification create mode 100644 changelogs/client_server/newsfragments/1850.clarification diff --git a/changelogs/appendices/newsfragments/1850.clarification b/changelogs/appendices/newsfragments/1850.clarification new file mode 100644 index 00000000..cc200bdf --- /dev/null +++ b/changelogs/appendices/newsfragments/1850.clarification @@ -0,0 +1 @@ +Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. diff --git a/changelogs/client_server/newsfragments/1850.clarification b/changelogs/client_server/newsfragments/1850.clarification new file mode 100644 index 00000000..cc200bdf --- /dev/null +++ b/changelogs/client_server/newsfragments/1850.clarification @@ -0,0 +1 @@ +Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. diff --git a/content/appendices.md b/content/appendices.md index 9c7cf82a..f9dbb455 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -556,7 +556,7 @@ The `domain` of a user ID is the [server name](#server-name) of the homeserver which allocated the account. The length of a user ID, including the `@` sigil and the domain, MUST -NOT exceed 255 characters. +NOT exceed 255 bytes. The complete grammar for a legal user ID is: @@ -663,6 +663,9 @@ Room IDs are case-sensitive. They are not meant to be human-readable. They are intended to be treated as fully opaque strings by clients. +The length of a room ID, including the `!` sigil and the domain, MUST +NOT exceed 255 bytes. + #### Room Aliases A room may have zero or more aliases. A room alias has the format: @@ -673,8 +676,8 @@ The `domain` of a room alias is the [server name](#server-name) of the homeserver which created the alias. Other servers may contact this homeserver to look up the alias. -Room aliases MUST NOT exceed 255 bytes (including the `#` sigil and the -domain). +The length of a room alias, including the `#` sigil and the domain, MUST +NOT exceed 255 bytes. #### Event IDs @@ -686,10 +689,12 @@ However, the precise format depends upon the [room version specification](/rooms): early room versions included a `domain` component, whereas more recent versions omit the domain and use a base64-encoded hash instead. +In addition to the requirements of the room version, the length of an event ID, +including the `$` sigil and the domain where present, MUST NOT exceed 255 bytes. + Event IDs are case-sensitive. They are not meant to be human-readable. They are intended to be treated as fully opaque strings by clients. - ### URIs There are two major kinds of referring to a resource in Matrix: matrix.to diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 851c64cb..c2c01465 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1849,16 +1849,15 @@ updates not being sent. The complete event MUST NOT be larger than 65536 bytes, when formatted with the [federation event format](#room-event-format), including any -signatures, and encoded as [Canonical -JSON](/appendices#canonical-json). +signatures, and encoded as [Canonical JSON](/appendices#canonical-json). There are additional restrictions on sizes per key: -- `sender` MUST NOT exceed 255 bytes (including domain). -- `room_id` MUST NOT exceed 255 bytes. +- `sender` MUST NOT exceed the size limit for [user IDs](/appendices/#user-identifiers). +- `room_id` MUST NOT exceed the size limit for [room IDs](/appendices/#room-ids). - `state_key` MUST NOT exceed 255 bytes. - `type` MUST NOT exceed 255 bytes. -- `event_id` MUST NOT exceed 255 bytes. +- `event_id` MUST NOT exceed the size limit for [event IDs](/appendices/#event-ids). Some event types have additional size restrictions which are specified in the description of the event. Additional keys have no limit other From eb49b28ea9f0182931d5dab36492acff188a81e1 Mon Sep 17 00:00:00 2001 From: davidegirardi <16451191+davidegirardi@users.noreply.github.com> Date: Wed, 12 Jun 2024 15:14:37 +0200 Subject: [PATCH 10/70] Use environment variables in workflow (#1865) * Use environment variables in workflow * Add newsfragment --- .github/workflows/netlify.yaml | 5 ++++- changelogs/internal/newsfragments/1865.clarification | 1 + 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 changelogs/internal/newsfragments/1865.clarification diff --git a/.github/workflows/netlify.yaml b/.github/workflows/netlify.yaml index 889d6eed..7c59f64c 100644 --- a/.github/workflows/netlify.yaml +++ b/.github/workflows/netlify.yaml @@ -25,8 +25,11 @@ jobs: id: readctx # we need to find the PR number that corresponds to the branch, which we do by # searching the GH API + env: + OWNER_LOGIN: ${{ github.event.workflow_run.head_repository.owner.login }} + HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }} run: | - head_branch='${{github.event.workflow_run.head_repository.owner.login}}:${{github.event.workflow_run.head_branch}}' + head_branch="${OWNER_LOGIN}:${HEAD_BRANCH}" echo "head branch: $head_branch" pulls_uri="https://api.github.com/repos/${{ github.repository }}/pulls?head=$(jq -Rr '@uri' <<<$head_branch)" pr_number=$(curl -H 'Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' "$pulls_uri" | diff --git a/changelogs/internal/newsfragments/1865.clarification b/changelogs/internal/newsfragments/1865.clarification new file mode 100644 index 00000000..f50be96f --- /dev/null +++ b/changelogs/internal/newsfragments/1865.clarification @@ -0,0 +1 @@ +Use environment variables for Netlify build job. From cd8ce97563205ea950b67c95a22d860638205df7 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 12 Jun 2024 22:17:37 +0100 Subject: [PATCH 11/70] Minor clarifications to the "end-to-end encryption" module (#1863) --- changelogs/client_server/newsfragments/1863.clarification | 1 + .../client-server-api/modules/end_to_end_encryption.md | 8 +++++--- 2 files changed, 6 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1863.clarification diff --git a/changelogs/client_server/newsfragments/1863.clarification b/changelogs/client_server/newsfragments/1863.clarification new file mode 100644 index 00000000..d054d41d --- /dev/null +++ b/changelogs/client_server/newsfragments/1863.clarification @@ -0,0 +1 @@ +Minor clarifications to the "end-to-end encryption" module. diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 1b3bd7b3..c3a801f9 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1530,9 +1530,11 @@ claiming to have sent messages which they didn't. `sender` must correspond to the user who sent the event, `recipient` to the local user, and `recipient_keys` to the local ed25519 key. -Clients must confirm that the `sender_key` and the `ed25519` field value -under the `keys` property match the keys returned by [`/keys/query`](/client-server-api/#post_matrixclientv3keysquery) for -the given user, and must also verify the signature of the keys from the +Clients must confirm that the `sender_key` property in the cleartext +`m.room.encrypted` event body, and the `keys.ed25519` property in the +decrypted plaintext, match the keys returned by +[`/keys/query`](#post_matrixclientv3keysquery) for +the given user. Clients must also verify the signature of the keys from the `/keys/query` response. Without this check, a client cannot be sure that the sender device owns the private part of the ed25519 key it claims to have in the Olm payload. This is crucial when the ed25519 key corresponds From 4a280bcd87ae233f0e4e923dea8d5fd1f4b5317e Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 12 Jun 2024 22:48:50 +0100 Subject: [PATCH 12/70] Clarifications around encoding of data within verification QR codes (#1839) --- .../newsfragments/1839.clarification | 1 + .../modules/end_to_end_encryption.md | 26 ++++++++++++------- 2 files changed, 17 insertions(+), 10 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1839.clarification diff --git a/changelogs/client_server/newsfragments/1839.clarification b/changelogs/client_server/newsfragments/1839.clarification new file mode 100644 index 00000000..eea109b1 --- /dev/null +++ b/changelogs/client_server/newsfragments/1839.clarification @@ -0,0 +1 @@ +Specify the encoding to be used when generating QR codes for device verification. diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index c3a801f9..5787205a 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1179,10 +1179,16 @@ The process between Alice and Bob verifying each other would be: ###### QR code format -The QR codes to be displayed and scanned using this format will encode binary -strings in the general form: +The QR codes to be displayed and scanned MUST be +compatible with [ISO/IEC 18004:2015](https://www.iso.org/standard/62021.html) and +contain a single segment that uses the byte mode encoding. -- the ASCII string `MATRIX` +The error correction level can be chosen by the device displaying the QR code. + +The binary segment MUST be of the following form: + +- the string `MATRIX` encoded as one ASCII byte per character (i.e. `0x4D`, + `0x41`, `0x54`, `0x52`, `0x49`, `0x58`) - one byte indicating the QR code version (must be `0x02`) - one byte indicating the QR code verification mode. Should be one of the following values: @@ -1194,23 +1200,23 @@ strings in the general form: request event, encoded as: - two bytes in network byte order (big-endian) indicating the length in bytes of the ID as a UTF-8 string - - the ID as a UTF-8 string + - the ID encoded as a UTF-8 string - the first key, as 32 bytes. The key to use depends on the mode field: - if `0x00` or `0x01`, then the current user's own master cross-signing public key - if `0x02`, then the current device's Ed25519 signing key - the second key, as 32 bytes. The key to use depends on the mode field: - if `0x00`, then what the device thinks the other user's master - cross-signing key is + cross-signing public key is - if `0x01`, then what the device thinks the other device's Ed25519 signing + public key is + - if `0x02`, then what the device thinks the user's master cross-signing public key is - - if `0x02`, then what the device thinks the user's master cross-signing key - is -- a random shared secret, as a byte string. It is suggested to use a secret +- a random shared secret, as a sequence of bytes. It is suggested to use a secret that is about 8 bytes long. Note: as we do not share the length of the secret, and it is not a fixed size, clients will just use the remainder of - binary string as the shared secret. + binary segment as the shared secret. -For example, if Alice displays a QR code encoding the following binary string: +For example, if Alice displays a QR code encoding the following binary data: ``` "MATRIX" |ver|mode| len | event ID From 7a51ae879c4c9274c638d19cd36eda630eb75e41 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 13 Jun 2024 12:08:27 -0600 Subject: [PATCH 13/70] Add authenticated media (MSC3916) (#1858) * C2S: Deprecate now-legacy endpoints * C2S: Fix MXC URI code block while we're here * C2S: Describe the authentication and deprecation requirements * C2S: Intro the upload/download endpoints differently * C2S: Literally copy/paste the `content-repo.yaml` spec * C2S: Drop `/upload` and `/create` because we aren't replacing them today * C2S: Fix notes while we're here * C2S: Update metadata for new endpoints * C2S: Add authentication to new endpoints * C2S: Drop `allow_remote` and `allow_redirect` on new endpoints * C2S: Append backwards compatibility notes * C2S: Decorate old media endpoints with pointers to the new ones The server-server spec might have a harder time linking to these, but that can be fixed with verbiage. * C2S: Annotate IdP icon spec with media auth implications * S2S: Modernize section text * S2S: Create content repository API This is largely a copy/paste of the new authed content repo API in the Client-Server API, though some keywords (like "client") have been changed. Paths and response formats have also been changed to support the federation-specific requirements. * C2S & S2S: Add plethora of changelogs * Reference RFC 1341 * Upgrade keywords in changed text * Mention caching * Cross-reference IdP icons * Update content/client-server-api/modules/content_repo.md --- .../newsfragments/1858.deprecation | 1 + .../newsfragments/1858.feature.1 | 1 + .../newsfragments/1858.feature.2 | 1 + .../client_server/newsfragments/1858.new.1 | 1 + .../client_server/newsfragments/1858.new.2 | 1 + .../client_server/newsfragments/1858.new.3 | 1 + .../client_server/newsfragments/1858.new.4 | 1 + .../client_server/newsfragments/1858.new.5 | 1 + .../newsfragments/1858.deprecation | 1 + .../server_server/newsfragments/1858.feature | 1 + .../server_server/newsfragments/1858.new.1 | 1 + .../server_server/newsfragments/1858.new.2 | 1 + content/client-server-api/_index.md | 5 +- .../client-server-api/modules/content_repo.md | 58 +- content/server-server-api.md | 23 +- .../client-server/authed-content-repo.yaml | 518 ++++++++++++++++++ data/api/client-server/content-repo.yaml | 51 +- .../definitions/sso_login_flow.yaml | 12 + .../api/server-server/content_repository.yaml | 303 ++++++++++ 19 files changed, 967 insertions(+), 15 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1858.deprecation create mode 100644 changelogs/client_server/newsfragments/1858.feature.1 create mode 100644 changelogs/client_server/newsfragments/1858.feature.2 create mode 100644 changelogs/client_server/newsfragments/1858.new.1 create mode 100644 changelogs/client_server/newsfragments/1858.new.2 create mode 100644 changelogs/client_server/newsfragments/1858.new.3 create mode 100644 changelogs/client_server/newsfragments/1858.new.4 create mode 100644 changelogs/client_server/newsfragments/1858.new.5 create mode 100644 changelogs/server_server/newsfragments/1858.deprecation create mode 100644 changelogs/server_server/newsfragments/1858.feature create mode 100644 changelogs/server_server/newsfragments/1858.new.1 create mode 100644 changelogs/server_server/newsfragments/1858.new.2 create mode 100644 data/api/client-server/authed-content-repo.yaml create mode 100644 data/api/server-server/content_repository.yaml diff --git a/changelogs/client_server/newsfragments/1858.deprecation b/changelogs/client_server/newsfragments/1858.deprecation new file mode 100644 index 00000000..6e93dca5 --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.deprecation @@ -0,0 +1 @@ +Use of the `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.feature.1 b/changelogs/client_server/newsfragments/1858.feature.1 new file mode 100644 index 00000000..02b9b51e --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.feature.1 @@ -0,0 +1 @@ +Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.feature.2 b/changelogs/client_server/newsfragments/1858.feature.2 new file mode 100644 index 00000000..63dfbb78 --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.feature.2 @@ -0,0 +1 @@ +Some media endpoints are now consistently under `/_matrix/client/{version}/media/*` instead of `/_matrix/media/*`, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.1 b/changelogs/client_server/newsfragments/1858.new.1 new file mode 100644 index 00000000..9d02447f --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.new.1 @@ -0,0 +1 @@ +[`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.2 b/changelogs/client_server/newsfragments/1858.new.2 new file mode 100644 index 00000000..07e7763a --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.new.2 @@ -0,0 +1 @@ +[`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.3 b/changelogs/client_server/newsfragments/1858.new.3 new file mode 100644 index 00000000..49b67f04 --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.new.3 @@ -0,0 +1 @@ +[`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.4 b/changelogs/client_server/newsfragments/1858.new.4 new file mode 100644 index 00000000..dda53b33 --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.new.4 @@ -0,0 +1 @@ +[`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.5 b/changelogs/client_server/newsfragments/1858.new.5 new file mode 100644 index 00000000..021b4023 --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.new.5 @@ -0,0 +1 @@ +[`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid) \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.deprecation b/changelogs/server_server/newsfragments/1858.deprecation new file mode 100644 index 00000000..fd3d2576 --- /dev/null +++ b/changelogs/server_server/newsfragments/1858.deprecation @@ -0,0 +1 @@ +Use of the Client-Server API `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.feature b/changelogs/server_server/newsfragments/1858.feature new file mode 100644 index 00000000..02b9b51e --- /dev/null +++ b/changelogs/server_server/newsfragments/1858.feature @@ -0,0 +1 @@ +Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.new.1 b/changelogs/server_server/newsfragments/1858.new.1 new file mode 100644 index 00000000..e50d5fd1 --- /dev/null +++ b/changelogs/server_server/newsfragments/1858.new.1 @@ -0,0 +1 @@ +[`GET /_matrix/federation/v1/media/download/{mediaId}`](/server-server-api/#get_matrixfederationv1mediadownloadmediaid) \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.new.2 b/changelogs/server_server/newsfragments/1858.new.2 new file mode 100644 index 00000000..1da2a693 --- /dev/null +++ b/changelogs/server_server/newsfragments/1858.new.2 @@ -0,0 +1 @@ +[`GET /_matrix/federation/v1/media/thumbnail/{mediaId}`](/server-server-api/#get_matrixfederationv1mediathumbnailmediaid) \ No newline at end of file diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index c2c01465..3e8a8670 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -37,9 +37,8 @@ The exceptions are: which take an empty request body. Similarly, all endpoints require the server to return a JSON object, -with the exception of 200 responses to -[`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](#get_matrixmediav3downloadservernamemediaid) -and [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](#get_matrixmediav3thumbnailservernamemediaid). +with the exception of 200 responses to the media download endpoints in the +[Content Repository module](#content-repository). Servers must include a `Content-Type` header of `application/json` for all JSON responses. All JSON data, in requests or responses, must be encoded using UTF-8. diff --git a/content/client-server-api/modules/content_repo.md b/content/client-server-api/modules/content_repo.md index cef70b3d..a0138156 100644 --- a/content/client-server-api/modules/content_repo.md +++ b/content/client-server-api/modules/content_repo.md @@ -23,19 +23,67 @@ When serving content, the server SHOULD provide a interacting with the media repository. {{% /boxes/added-in-paragraph %}} +{{% boxes/added-in-paragraph %}} +{{< changed-in v="1.11" >}} The unauthenticated download endpoints have been +deprecated in favour of newer, authenticated, ones. This change includes updating +the paths of all media endpoints from `/_matrix/media/*` to `/_matrix/client/{version}/media/*`, +with the exception of the `/upload` and `/create` endpoints. The upload/create +endpoints are expected to undergo a similar transition in a later version of the +specification. +{{% /boxes/added-in-paragraph %}} + #### Matrix Content (`mxc://`) URIs Content locations are represented as Matrix Content (`mxc://`) URIs. They look like: - mxc:/// +``` +mxc:/// - : The name of the homeserver where this content originated, e.g. matrix.org - : An opaque ID which identifies the content. + : The name of the homeserver where this content originated, e.g. matrix.org + : An opaque ID which identifies the content. +``` -#### Client behaviour +#### Client behaviour {id="content-repo-client-behaviour"} -Clients can upload and download content using the following HTTP APIs. +Clients can access the content repository using the following endpoints. + +{{% boxes/added-in-paragraph %}} +{{< changed-in v="1.11" >}} Clients SHOULD NOT use the deprecated media 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. + +In addition to the above, servers SHOULD exclude [IdP icons used in the `m.login.sso` flow](/client-server-api/#definition-mloginsso-flow-schema) +from the freeze. See the `m.login.sso` flow schema for details. + +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" %}} diff --git a/content/server-server-api.md b/content/server-server-api.md index 365613df..9e92bfd9 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -1196,15 +1196,26 @@ using the following EDU: Attachments to events (images, files, etc) are uploaded to a homeserver via the Content Repository described in the [Client-Server -API](/client-server-api). When a server wishes +API](/client-server-api/#content-repository). When a server wishes to serve content originating from a remote server, it needs to ask the remote server for the media. -Servers should use the server described in the Matrix Content URI, which -has the format `mxc://{ServerName}/{MediaID}`. Servers should use the -download endpoint described in the [Client-Server -API](/client-server-api), being sure to use -the `allow_remote` parameter (set to `false`). +Servers MUST use the server described in the [Matrix Content URI](/client-server-api/#matrix-content-mxc-uris). +Formatted as `mxc://{ServerName}/{MediaID}`, servers MUST download the media from +`ServerName` using the below endpoints. + +{{% boxes/added-in-paragraph %}} +{{< changed-in v="1.11" >}} Servers were previously advised to use the `/_matrix/media/*` +endpoints described by the [Content Repository module in the Client-Server API](/client-server-api/#content-repository), +however, those endpoints have been deprecated. New endpoints are introduced which +require authentication. Naturally, as a server is not a user, they cannot provide +the required access token to those endpoints. Instead, servers MUST try the endpoints +described below before falling back to the deprecated `/_matrix/media/*` endpoints +when they receive a `404 M_UNRECOGNIZED` error. When falling back, servers MUST +be sure to set `allow_remote` to `false`. +{{% /boxes/added-in-paragraph %}} + +{{% http-api spec="server-server" api="content_repository" %}} ## Server Access Control Lists (ACLs) diff --git a/data/api/client-server/authed-content-repo.yaml b/data/api/client-server/authed-content-repo.yaml new file mode 100644 index 00000000..9741d618 --- /dev/null +++ b/data/api/client-server/authed-content-repo.yaml @@ -0,0 +1,518 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2019-2024 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. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +openapi: 3.1.0 +info: + title: Matrix Client-Server (Authenticated) Content Repository API + version: 1.0.0 +paths: + "/media/download/{serverName}/{mediaId}": + get: + x-addedInMatrixVersion: "1.11" + summary: Download content from the content repository. + description: |- + {{% boxes/note %}} + Clients SHOULD NOT generate or use URLs which supply the access token in + the query string. These URLs may be copied by users verbatim and provided + in a chat message to another user, disclosing the sender's access token. + {{% /boxes/note %}} + + Clients MAY be redirected using the 307/308 responses below to download + the request object. This is typical when the homeserver uses a Content + Delivery Network (CDN). + operationId: getContentAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + parameters: + - $ref: '#/components/parameters/serverName' + - $ref: '#/components/parameters/mediaId' + - $ref: '#/components/parameters/timeout_ms' + responses: + "200": + description: The content that was previously uploaded. + headers: + Content-Type: + $ref: '#/components/headers/downloadContentType' + Content-Disposition: + description: The name of the file that was previously uploaded, if set. + schema: + type: string + content: + application/octet-stream: + schema: + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the uploaded file." + "307": + $ref: '#/components/responses/downloadRedirect' + "308": + $ref: '#/components/responses/downloadRedirect' + "429": + $ref: '#/components/responses/rateLimited' + "502": + $ref: '#/components/responses/downloadTooLarge' + "504": + $ref: '#/components/responses/notYetUploaded' + tags: + - Media + "/media/download/{serverName}/{mediaId}/{fileName}": + get: + x-addedInMatrixVersion: "1.11" + summary: Download content from the content repository overriding the file name. + description: |- + This will download content from the content repository (same as + the previous endpoint) but replaces the target file name with the one + provided by the caller. + + {{% boxes/note %}} + Clients SHOULD NOT generate or use URLs which supply the access token in + the query string. These URLs may be copied by users verbatim and provided + in a chat message to another user, disclosing the sender's access token. + {{% /boxes/note %}} + + Clients MAY be redirected using the 307/308 responses below to download + the request object. This is typical when the homeserver uses a Content + Delivery Network (CDN). + operationId: getContentOverrideNameAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + parameters: + - $ref: '#/components/parameters/serverName' + - $ref: '#/components/parameters/mediaId' + - in: path + name: fileName + required: true + description: A filename to give in the `Content-Disposition` header. + example: filename.jpg + schema: + type: string + - $ref: '#/components/parameters/timeout_ms' + responses: + "200": + description: The content that was previously uploaded. + headers: + Content-Type: + $ref: '#/components/headers/downloadContentType' + Content-Disposition: + description: |- + The `fileName` requested or the name of the file that was previously + uploaded, if set. + schema: + type: string + content: + application/octet-stream: + schema: + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the uploaded file." + "307": + $ref: '#/components/responses/downloadRedirect' + "308": + $ref: '#/components/responses/downloadRedirect' + "429": + $ref: '#/components/responses/rateLimited' + "502": + $ref: '#/components/responses/downloadTooLarge' + "504": + $ref: '#/components/responses/notYetUploaded' + tags: + - Media + "/media/thumbnail/{serverName}/{mediaId}": + get: + x-addedInMatrixVersion: "1.11" + summary: Download a thumbnail of content from the content repository + description: |- + Download a thumbnail of content from the content repository. + See the [Thumbnails](/client-server-api/#thumbnails) section for more information. + + {{% boxes/note %}} + Clients SHOULD NOT generate or use URLs which supply the access token in + the query string. These URLs may be copied by users verbatim and provided + in a chat message to another user, disclosing the sender's access token. + {{% /boxes/note %}} + + Clients MAY be redirected using the 307/308 responses below to download + the request object. This is typical when the homeserver uses a Content + Delivery Network (CDN). + operationId: getContentThumbnailAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + parameters: + - $ref: '#/components/parameters/serverName' + - $ref: '#/components/parameters/mediaId' + - in: query + name: width + required: true + description: |- + The *desired* width of the thumbnail. The actual thumbnail may be + larger than the size specified. + example: 64 + schema: + type: integer + - in: query + name: height + required: true + description: |- + The *desired* height of the thumbnail. The actual thumbnail may be + larger than the size specified. + example: 64 + schema: + type: integer + - in: query + name: method + description: |- + The desired resizing method. See the [Thumbnails](/client-server-api/#thumbnails) + section for more information. + example: scale + schema: + type: string + enum: + - crop + - scale + - $ref: '#/components/parameters/timeout_ms' + - in: query + name: animated + x-addedInMatrixVersion: "1.11" + required: false + description: | + Indicates preference for an animated thumbnail from the server, if possible. Animated + thumbnails typically use the content types `image/gif`, `image/png` (with APNG format), + `image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg` + content types. + + When `true`, the server SHOULD return an animated thumbnail if possible and supported. + When `false`, the server MUST NOT return an animated thumbnail. For example, returning a + static `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT + return an animated thumbnail. + + Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation. + + When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the + server should behave as though `animated` is `false`. + example: false + schema: + type: boolean + responses: + "200": + description: A thumbnail of the requested content. + headers: + Content-Type: + description: The content type of the thumbnail. + schema: + type: string + enum: + - image/jpeg + - image/png + - image/apng + - image/gif + - image/webp + content: + image/jpeg: + schema: + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the thumbnail." + image/png: + schema: + x-changedInMatrixVersion: + "1.11": The PNG may be of the APNG variety if animation is supported and requested. + description: | + **Required.** The bytes for the thumbnail. The thumbnail MAY use an animated + format if `animated=true`. + image/apng: + schema: + x-addedInMatrixVersion: "1.11" + description: "**Required.** The bytes for the *animated* thumbnail." + image/gif: + schema: + x-addedInMatrixVersion: "1.11" + description: "**Required.** The bytes for the *animated* thumbnail." + image/webp: + schema: + x-addedInMatrixVersion: "1.11" + description: "**Required.** The bytes for the *animated* thumbnail." + "307": + $ref: '#/components/responses/thumbnailRedirect' + "308": + $ref: '#/components/responses/thumbnailRedirect' + "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. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN", + "error": "Cannot generate thumbnails for the requested content" + } + "413": + description: The local content is too large for the server to thumbnail. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "429": + $ref: '#/components/responses/rateLimited' + "502": + description: The remote content is too large for the server to thumbnail. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "504": + $ref: '#/components/responses/notYetUploaded' + tags: + - Media + /media/preview_url: + get: + x-addedInMatrixVersion: "1.11" + summary: Get information about a URL for a client + description: |- + Get information about a URL for the client. Typically this is called when a + client sees a URL in a message and wants to render a preview for the user. + + {{% boxes/note %}} + Clients should consider avoiding this endpoint for URLs posted in encrypted + rooms. Encrypted rooms often contain more sensitive information the users + do not want to share with the homeserver, and this can mean that the URLs + being shared should also not be shared with the homeserver. + {{% /boxes/note %}} + operationId: getUrlPreviewAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + parameters: + - in: query + name: url + description: The URL to get a preview of. + required: true + example: https://matrix.org + schema: + type: string + format: uri + - in: query + name: ts + description: |- + The preferred point in time to return a preview for. The server may + return a newer version if it does not have the requested version + available. + example: 1510610716656 + schema: + type: integer + format: int64 + responses: + "200": + description: |- + The OpenGraph data for the URL, which may be empty. Some values are + replaced with matrix equivalents if they are provided in the response. + The differences from the OpenGraph protocol are described here. + content: + application/json: + schema: + type: object + properties: + matrix:image:size: + type: integer + format: int64 + description: The byte-size of the image. Omitted if there is no image attached. + og:image: + type: string + format: uri + description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to + the image. Omitted if there is no image. + examples: + response: + value: { + "og:title": "Matrix Blog Post", + "og:description": "This is a really cool blog post from matrix.org", + "og:image": "mxc://example.com/ascERGshawAWawugaAcauga", + "og:image:type": "image/png", + "og:image:height": 48, + "og:image:width": 48, + "matrix:image:size": 102400 + } + "429": + $ref: '#/components/responses/rateLimited' + tags: + - Media + /media/config: + get: + x-addedInMatrixVersion: "1.11" + summary: Get the configuration for the content repository. + description: |- + This endpoint allows clients to retrieve the configuration of the content + repository, such as upload limitations. + Clients SHOULD use this as a guide when using content repository endpoints. + All values are intentionally left optional. Clients SHOULD follow + the advice given in the field description when the field is not available. + + {{% boxes/note %}} + Both clients and server administrators should be aware that proxies + between the client and the server may affect the apparent behaviour of content + repository APIs, for example, proxies may enforce a lower upload size limit + than is advertised by the server on this endpoint. + {{% /boxes/note %}} + operationId: getConfigAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + responses: + "200": + description: The public content repository configuration for the matrix server. + content: + application/json: + schema: + type: object + properties: + m.upload.size: + type: integer + format: int64 + description: |- + The maximum size an upload can be in bytes. + Clients SHOULD use this as a guide when uploading content. + If not listed or null, the size limit should be treated as unknown. + examples: + response: + value: { + "m.upload.size": 50000000 + } + "429": + $ref: '#/components/responses/rateLimited' + tags: + - Media +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + accessTokenQuery: + $ref: definitions/security.yaml#/accessTokenQuery + accessTokenBearer: + $ref: definitions/security.yaml#/accessTokenBearer + parameters: + serverName: + in: path + name: serverName + required: true + description: | + The server name from the `mxc://` URI (the authority component). + example: matrix.org + schema: + type: string + format: mx-server-name + mediaId: + in: path + name: mediaId + required: true + description: | + The media ID from the `mxc://` URI (the path component). + example: ascERGshawAWawugaAcauga + schema: + type: string + timeout_ms: + in: query + name: timeout_ms + x-addedInMatrixVersion: "1.7" + description: | + The maximum number of milliseconds that the client is willing to wait to + start receiving data, in the case that the content has not yet been + uploaded. The default value is 20000 (20 seconds). The content + repository can and should impose a maximum value for this parameter. The + content repository may also choose to respond before the timeout. + example: 5000 + schema: + type: integer + format: int64 + default: 20000 + responses: + rateLimited: + description: This request was rate-limited. + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + notYetUploaded: + description: |- + The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) + will be returned with the `errcode` `M_NOT_YET_UPLOADED`. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_YET_UPLOADED", + "error": "Content has not yet been uploaded" + } + downloadRedirect: + description: A redirect to the requested content. + headers: + Location: + description: The URL of the content. + schema: + type: string + format: uri + downloadTooLarge: + description: The content is too large for the server to serve. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to serve" + } + thumbnailRedirect: + description: A redirect to the thumbnail of the requested content. + headers: + Location: + description: The URL of the thumbnail content. + schema: + type: string + format: uri + headers: + downloadContentType: + description: The content type of the file that was previously uploaded. + schema: + type: string + diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index e6d55b51..1dac8b10 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -217,7 +217,20 @@ paths: - Media "/media/v3/download/{serverName}/{mediaId}": get: + deprecated: true summary: Download content from the content repository. + description: |- + {{% boxes/note %}} + Replaced by [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid) + (requires authentication). + {{% /boxes/note %}} + + {{% 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' @@ -254,11 +267,24 @@ paths: - Media "/media/v3/download/{serverName}/{mediaId}/{fileName}": get: + deprecated: true summary: Download content from the content repository overriding the file name description: |- + {{% boxes/note %}} + Replaced by [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename) + (requires authentication). + {{% /boxes/note %}} + 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' @@ -304,10 +330,23 @@ paths: - Media "/media/v3/thumbnail/{serverName}/{mediaId}": get: + deprecated: true summary: Download a thumbnail of content from the content repository description: |- + {{% boxes/note %}} + Replaced by [`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid) + (requires authentication). + {{% /boxes/note %}} + 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' @@ -455,8 +494,13 @@ paths: - Media /media/v3/preview_url: get: + deprecated: true summary: Get information about a URL for a client description: |- + {{% boxes/note %}} + Replaced by [`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url). + {{% /boxes/note %}} + Get information about a URL for the client. Typically this is called when a client sees a URL in a message and wants to render a preview for the user. @@ -525,8 +569,13 @@ paths: - Media /media/v3/config: get: + deprecated: true summary: Get the configuration for the content repository. description: |- + {{% boxes/note %}} + Replaced by [`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig). + {{% /boxes/note %}} + This endpoint allows clients to retrieve the configuration of the content repository, such as upload limitations. Clients SHOULD use this as a guide when using content repository endpoints. @@ -625,7 +674,7 @@ components: Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. - + Defaults to `true` if not provided. example: false schema: diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index 3b95e664..0996511e 100644 --- a/data/api/client-server/definitions/sso_login_flow.yaml +++ b/data/api/client-server/definitions/sso_login_flow.yaml @@ -53,6 +53,18 @@ properties: description: |- Optional `mxc://` URI to provide an image/icon representing the IdP. Intended to be shown alongside the `name` if provided. + + {{% boxes/note %}} + Clients SHOULD use the deprecated [`/download`](/client-server-api/#get_matrixmediav3downloadservernamemediaid) + and [`/thumbnail`](/client-server-api/#get_matrixmediav3thumbnailservernamemediaid) + endpoints to retrieve this media item because clients will not have + an access token they can authenticate with yet. Servers SHOULD ensure + media used for IdP icons is excluded from the freeze described by the + [Content Repository module's Client Behaviour section](/client-server-api/#content-repo-client-behaviour). + + This may be addressed in the future with proposals like [MSC4148](https://github.com/matrix-org/matrix-spec-proposals/pull/4148), + or removed entirely through the transition to OIDC. + {{% /boxes/note %}} example: "mxc://example.org/abc123" brand: type: string diff --git a/data/api/server-server/content_repository.yaml b/data/api/server-server/content_repository.yaml new file mode 100644 index 00000000..6c19d6ec --- /dev/null +++ b/data/api/server-server/content_repository.yaml @@ -0,0 +1,303 @@ +# Copyright 2024 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. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +openapi: 3.1.0 +info: + title: Matrix Federation Content Repository API + version: 1.0.0 +paths: + "/media/download/{mediaId}": + get: + x-addedInMatrixVersion: "1.11" + summary: Download content from the content repository. + operationId: getContent + security: + - signedRequest: [] + parameters: + - $ref: '#/components/parameters/mediaId' + - $ref: '#/components/parameters/timeout_ms' + responses: + "200": + description: The content that was previously uploaded. + headers: + Content-Type: + $ref: '#/components/headers/downloadContentType' + content: + multipart/mixed: + schema: + # This is a workaround for us not being able to say the response is required. + description: |- + **Required.** MUST contain a `boundary` (per [RFC 1341](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html)) + delineating exactly two parts: + + The first part has a `Content-Type` header of `application/json` + and describes the media's metadata, if any. Currently, this will + always be an empty object. + + The second part is either: + + 1. the bytes of the media itself, using `Content-Type` and + `Content-Disposition` headers as appropriate; + 2. or a `Location` header to redirect the caller to where the media + can be retrieved. The URL at `Location` SHOULD have appropriate + `Content-Type` and `Content-Disposition` headers which describe + the media. + + When `Location` is present, servers SHOULD NOT cache the URL. + The remote server may have applied time limits on its validity. + If the caller requires an up-to-date URL, it SHOULD re-request + the media download. + "429": + $ref: '#/components/responses/rateLimited' + "502": + description: The content is too large for the server to serve. + content: + application/json: + schema: + # XXX: We should move error definitions into a more generic place. + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to serve" + } + "504": + $ref: '#/components/responses/notYetUploaded' + tags: + - Media + "/media/thumbnail/{mediaId}": + get: + x-addedInMatrixVersion: "1.11" + summary: Download a thumbnail of content from the content repository + description: |- + Download a thumbnail of content from the content repository. + See the [Client-Server API Thumbnails](/client-server-api/#thumbnails) + section for more information. + operationId: getContentThumbnail + security: + - signedRequest: [] + parameters: + - $ref: '#/components/parameters/mediaId' + - in: query + name: width + required: true + description: |- + The *desired* width of the thumbnail. The actual thumbnail may be + larger than the size specified. + example: 64 + schema: + type: integer + - in: query + name: height + required: true + description: |- + The *desired* height of the thumbnail. The actual thumbnail may be + larger than the size specified. + example: 64 + schema: + type: integer + - in: query + name: method + description: |- + The desired resizing method. See the [Client-Server API Thumbnails](/client-server-api/#thumbnails) + section for more information. + example: scale + schema: + type: string + enum: + - crop + - scale + - $ref: '#/components/parameters/timeout_ms' + - in: query + name: animated + x-addedInMatrixVersion: "1.11" + required: false + description: | + Indicates preference for an animated thumbnail from the server, if possible. Animated + thumbnails typically use the content types `image/gif`, `image/png` (with APNG format), + `image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg` + content types. + + When `true`, the server SHOULD return an animated thumbnail if possible and supported. + When `false`, the server MUST NOT return an animated thumbnail. For example, returning a + static `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT + return an animated thumbnail. + + Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation. + + When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the + server should behave as though `animated` is `false`. + example: false + schema: + type: boolean + responses: + "200": + description: A thumbnail of the requested content. + headers: + Content-Type: + description: Must be `multipart/mixed`. + schema: + type: string + content: + multipart/mixed: + schema: + # This is a workaround for us not being able to say the response is required. + description: |- + **Required.** MUST contain a `boundary` (per [RFC 1341](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html)) + delineating exactly two parts: + + The first part has a `Content-Type` header of `application/json` + and describes the media's metadata, if any. Currently, this will + always be an empty object. + + The second part is either: + + 1. the bytes of the media itself, using `Content-Type` and + `Content-Disposition` headers as appropriate; + 2. or a `Location` header to redirect the caller to where the media + can be retrieved. The URL at `Location` SHOULD have appropriate + `Content-Type` and `Content-Disposition` headers which describe + the media. + + When `Location` is present, servers SHOULD NOT cache the URL. + The remote server may have applied time limits on its validity. + If the caller requires an up-to-date URL, it SHOULD re-request + the media download. + + {{% boxes/note %}} + The `Content-Type` for the second part SHOULD be one of: + * `image/png` (possibly of the APNG variety) + * `image/apng` + * `image/jpeg` + * `image/gif` + * `image/webp` + {{% /boxes/note %}} + "400": + description: |- + The request does not make sense to the server, or the server cannot thumbnail + the content. For example, the caller requested non-integer dimensions or asked + for negatively-sized images. + content: + application/json: + schema: + # XXX: We should move error definitions into a more generic place. + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN", + "error": "Cannot generate thumbnails for the requested content" + } + "413": + description: The local content is too large for the server to thumbnail. + content: + application/json: + schema: + # XXX: We should move error definitions into a more generic place. + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "429": + $ref: '#/components/responses/rateLimited' + "502": + description: The remote content is too large for the server to thumbnail. + content: + application/json: + schema: + # XXX: We should move error definitions into a more generic place. + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "504": + $ref: '#/components/responses/notYetUploaded' + tags: + - Media +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + signedRequest: + $ref: definitions/security.yaml#/signedRequest + parameters: + mediaId: + in: path + name: mediaId + required: true + description: | + The media ID from the `mxc://` URI (the path component). + example: ascERGshawAWawugaAcauga + schema: + type: string + timeout_ms: + in: query + name: timeout_ms + x-addedInMatrixVersion: "1.7" + description: | + The maximum number of milliseconds that the client is willing to wait to + start receiving data, in the case that the content has not yet been + uploaded. The default value is 20000 (20 seconds). The content + repository can and should impose a maximum value for this parameter. The + content repository may also choose to respond before the timeout. + example: 5000 + schema: + type: integer + format: int64 + default: 20000 + responses: + rateLimited: + description: This request was rate-limited. + content: + application/json: + schema: + # XXX: We should move error definitions into a more generic place. + $ref: ../client-server/definitions/errors/rate_limited.yaml + notYetUploaded: + description: |- + The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) + will be returned with the `errcode` `M_NOT_YET_UPLOADED`. + content: + application/json: + schema: + # XXX: We should move error definitions into a more generic place. + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_YET_UPLOADED", + "error": "Content has not yet been uploaded" + } + headers: + downloadContentType: + description: |- + Must be `multipart/mixed`. + schema: + type: string From f38b0525690b7fe331b4156e8fde74484097a228 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 13 Jun 2024 12:27:06 -0600 Subject: [PATCH 14/70] Use RFC 2119 keywords across the content repository spec (#1861) * Use RFC 2119 keywords across the content repository spec * changelog --- changelogs/client_server/newsfragments/1861.clarification | 1 + data/api/client-server/authed-content-repo.yaml | 6 +++--- data/api/client-server/content-repo.yaml | 6 +++--- data/api/server-server/content_repository.yaml | 6 +++--- 4 files changed, 10 insertions(+), 9 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1861.clarification diff --git a/changelogs/client_server/newsfragments/1861.clarification b/changelogs/client_server/newsfragments/1861.clarification new file mode 100644 index 00000000..9d877ff5 --- /dev/null +++ b/changelogs/client_server/newsfragments/1861.clarification @@ -0,0 +1 @@ +Use RFC 2119 keywords more consistently throughout various parts of the specification. \ No newline at end of file diff --git a/data/api/client-server/authed-content-repo.yaml b/data/api/client-server/authed-content-repo.yaml index 9741d618..43cb5881 100644 --- a/data/api/client-server/authed-content-repo.yaml +++ b/data/api/client-server/authed-content-repo.yaml @@ -200,7 +200,7 @@ paths: Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation. When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the - server should behave as though `animated` is `false`. + server SHOULD behave as though `animated` is `false`. example: false schema: type: boolean @@ -454,8 +454,8 @@ components: The maximum number of milliseconds that the client is willing to wait to start receiving data, in the case that the content has not yet been uploaded. The default value is 20000 (20 seconds). The content - repository can and should impose a maximum value for this parameter. The - content repository may also choose to respond before the timeout. + repository SHOULD impose a maximum value for this parameter. The + content repository MAY respond before the timeout. example: 5000 schema: type: integer diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 1dac8b10..038ac618 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -401,7 +401,7 @@ paths: Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation. When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the - server should behave as though `animated` is `false`. + server SHOULD behave as though `animated` is `false`. example: false schema: type: boolean @@ -688,8 +688,8 @@ components: The maximum number of milliseconds that the client is willing to wait to start receiving data, in the case that the content has not yet been uploaded. The default value is 20000 (20 seconds). The content - repository can and should impose a maximum value for this parameter. The - content repository may also choose to respond before the timeout. + repository SHOULD impose a maximum value for this parameter. The + content repository MAY respond before the timeout. example: 5000 schema: type: integer diff --git a/data/api/server-server/content_repository.yaml b/data/api/server-server/content_repository.yaml index 6c19d6ec..bd07e252 100644 --- a/data/api/server-server/content_repository.yaml +++ b/data/api/server-server/content_repository.yaml @@ -137,7 +137,7 @@ paths: Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation. When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the - server should behave as though `animated` is `false`. + server SHOULD behave as though `animated` is `false`. example: false schema: type: boolean @@ -265,8 +265,8 @@ components: The maximum number of milliseconds that the client is willing to wait to start receiving data, in the case that the content has not yet been uploaded. The default value is 20000 (20 seconds). The content - repository can and should impose a maximum value for this parameter. The - content repository may also choose to respond before the timeout. + repository SHOULD impose a maximum value for this parameter. The + content repository MAY respond before the timeout. example: 5000 schema: type: integer From 672af37cbd2a9b7c78e72e5e847b593154ebc7be Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 13 Jun 2024 20:34:54 +0200 Subject: [PATCH 15/70] Clarify that relations recursion should be capped at a certain depth (#1854) --- .../client_server/newsfragments/1854.clarification | 1 + data/api/client-server/relations.yaml | 9 ++++----- 2 files changed, 5 insertions(+), 5 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1854.clarification diff --git a/changelogs/client_server/newsfragments/1854.clarification b/changelogs/client_server/newsfragments/1854.clarification new file mode 100644 index 00000000..cb996bd6 --- /dev/null +++ b/changelogs/client_server/newsfragments/1854.clarification @@ -0,0 +1 @@ + Clarify that relations recursion should be capped at a certain depth. diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index 3f3d5baa..c4b0228c 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -315,11 +315,10 @@ components: If set to `false`, only events which have a direct relation with the given event will be included. - If set to `true`, all events which relate to the given event, or relate to - events that relate to the given event, will be included. - - It is recommended that homeservers traverse at least 3 levels of relationships. - Implementations may perform more but should be careful to not infinitely recurse. + If set to `true`, events which have an indirect relation with the given event + will be included additionally up to a certain depth level. Homeservers SHOULD traverse + at least 3 levels of relationships. Implementations MAY perform more but MUST be careful + to not infinitely recurse. The default value is `false`. schema: From f434fdfba7c1d0f651e9e002bcfdb5ef9224501f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 13 Jun 2024 23:37:07 +0200 Subject: [PATCH 16/70] Replace references to obsolete RFC 1341 with RFC 2046 (#1869) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Replace references to obsolete RFC 1341 with RFC 2046 Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- changelogs/server_server/newsfragments/1869.feature | 1 + data/api/server-server/content_repository.yaml | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1869.feature diff --git a/changelogs/server_server/newsfragments/1869.feature b/changelogs/server_server/newsfragments/1869.feature new file mode 100644 index 00000000..02b9b51e --- /dev/null +++ b/changelogs/server_server/newsfragments/1869.feature @@ -0,0 +1 @@ +Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/data/api/server-server/content_repository.yaml b/data/api/server-server/content_repository.yaml index bd07e252..66439b79 100644 --- a/data/api/server-server/content_repository.yaml +++ b/data/api/server-server/content_repository.yaml @@ -37,7 +37,7 @@ paths: schema: # This is a workaround for us not being able to say the response is required. description: |- - **Required.** MUST contain a `boundary` (per [RFC 1341](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html)) + **Required.** MUST contain a `boundary` (per [RFC 2046](https://datatracker.ietf.org/doc/html/rfc2046#section-5.1)) delineating exactly two parts: The first part has a `Content-Type` header of `application/json` @@ -154,7 +154,7 @@ paths: schema: # This is a workaround for us not being able to say the response is required. description: |- - **Required.** MUST contain a `boundary` (per [RFC 1341](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html)) + **Required.** MUST contain a `boundary` (per [RFC 2046](https://datatracker.ietf.org/doc/html/rfc2046#section-5.1)) delineating exactly two parts: The first part has a `Content-Type` header of `application/json` From 5f47b9624088a94518b735c90c082bcff762d913 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Fri, 14 Jun 2024 12:34:35 +0100 Subject: [PATCH 17/70] Clarify when server name is used and link to definition (#1862) * Clarify when server name is used and link to definition * Changelog --- changelogs/client_server/newsfragments/1862.clarification | 1 + content/client-server-api/_index.md | 4 ++-- content/client-server-api/modules/sso_login.md | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1862.clarification diff --git a/changelogs/client_server/newsfragments/1862.clarification b/changelogs/client_server/newsfragments/1862.clarification new file mode 100644 index 00000000..021b117c --- /dev/null +++ b/changelogs/client_server/newsfragments/1862.clarification @@ -0,0 +1 @@ +Clarify when server name is used and link to the definition. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 3e8a8670..8b40fe99 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -355,9 +355,9 @@ as per the [CORS](#web-browser-clients) section in this specification. The `.well-known` method uses a JSON file at a predetermined location to specify parameter values. The flow for this method is as follows: -1. Extract the server name from the user's Matrix ID by splitting the +1. Extract the [server name](/appendices/#server-name) from the user's Matrix ID by splitting the Matrix ID at the first colon. -2. Extract the hostname from the server name. +2. Extract the hostname from the server name as described by the [grammar](/appendices/#server-name). 3. Make a GET request to `https://hostname/.well-known/matrix/client`. 1. If the returned status code is 404, then `IGNORE`. 2. If the returned status code is not 200, or the response body is diff --git a/content/client-server-api/modules/sso_login.md b/content/client-server-api/modules/sso_login.md index 1a46c84d..f50a2eb1 100644 --- a/content/client-server-api/modules/sso_login.md +++ b/content/client-server-api/modules/sso_login.md @@ -123,8 +123,8 @@ authentication is successful, the browser will be redirected to that For example, consider a web-based client at `https://client.example.com`, which wants to initiate SSO login on - the homeserver at `server.example.org`. It does this by storing the - homeserver name in a query parameter for the `redirectUrl`: it + the homeserver with [server name](/appendices/#server-name) `server.example.org`. It does this by storing the + server name in a query parameter for the `redirectUrl`: it redirects to `https://server.example.org/login/sso/redirect?redirectUrl=https://client.example.com?hs=server.example.org`. From 7773716d189b16c1d5fa1dd2bfb8a1685bfb1108 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 14 Jun 2024 16:44:01 +0200 Subject: [PATCH 18/70] Clarify that asynchronous media upload requires authentication (#1872) Fixes: #1554 Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/1872.clarification | 1 + data/api/client-server/content-repo.yaml | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1872.clarification diff --git a/changelogs/client_server/newsfragments/1872.clarification b/changelogs/client_server/newsfragments/1872.clarification new file mode 100644 index 00000000..4bcea39e --- /dev/null +++ b/changelogs/client_server/newsfragments/1872.clarification @@ -0,0 +1 @@ +Clarify that `/media/v3/upload/{serverName}/{mediaId}` requires authentication. diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 038ac618..d0a6e5bb 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -81,6 +81,9 @@ paths: earlier via [POST /_matrix/media/v1/create](/client-server-api/#post_matrixmediav1create). operationId: uploadContentToMXC x-addedInMatrixVersion: "1.7" + security: + - accessTokenQuery: [] + - accessTokenBearer: [] parameters: - $ref: '#/components/parameters/serverName' description: | From 6dfab46268d68e139255c6cd74260a17cf1f69ab Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 18 Jun 2024 16:20:57 +0200 Subject: [PATCH 19/70] Fix typo in SRV delegation (#1877) Signed-off-by: Johannes Marbach --- changelogs/server_server/newsfragments/1877.clarification | 1 + content/server-server-api.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/1877.clarification diff --git a/changelogs/server_server/newsfragments/1877.clarification b/changelogs/server_server/newsfragments/1877.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/server_server/newsfragments/1877.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/server-server-api.md b/content/server-server-api.md index 9e92bfd9..5c9bd31e 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -166,7 +166,7 @@ to send. The process overall is as follows: target server must present a valid certificate for ``. 5. If no SRV record is found, an IP address is resolved using CNAME, AAAA - or A records. Requests are then made to the resolve IP address + or A records. Requests are then made to the resolved IP address and a port of 8448, using a `Host` header of ``. The target server must present a valid certificate for ``. From 4e32fca05fd89492a3acb82b7a2a922d155ee824 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 18 Jun 2024 17:59:26 +0200 Subject: [PATCH 20/70] Clarify that an access token is optional on `/account/password` and `/account/deactivate` (#1843) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- changelogs/client_server/newsfragments/1843.clarification | 1 + data/api/client-server/registration.yaml | 2 ++ 2 files changed, 3 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1843.clarification diff --git a/changelogs/client_server/newsfragments/1843.clarification b/changelogs/client_server/newsfragments/1843.clarification new file mode 100644 index 00000000..7ccfe4a7 --- /dev/null +++ b/changelogs/client_server/newsfragments/1843.clarification @@ -0,0 +1 @@ +Clarify that an access token is optional on the `POST /account/password` and `POST /account/deactivate` endpoints. \ No newline at end of file diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index afd30459..84aef5b1 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -387,6 +387,7 @@ paths: access token provided in the request. Whether other access tokens for the user are revoked depends on the request parameters. security: + - {} - accessTokenQuery: [] - accessTokenBearer: [] operationId: changePassword @@ -592,6 +593,7 @@ paths: parameter because the homeserver is expected to sign the request to the identity server instead. security: + - {} - accessTokenQuery: [] - accessTokenBearer: [] operationId: deactivateAccount From 9c46fa3f35f5e1517c401b7654a2faad1fbf65d7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 19 Jun 2024 21:52:21 -0600 Subject: [PATCH 21/70] Normalize the changelog for Matrix 1.11 --- changelogs/application_service/newsfragments/1810.clarification | 2 +- changelogs/client_server/newsfragments/1644.clarification | 2 +- .../newsfragments/{1755.clarification => 1755.feature} | 0 changelogs/client_server/newsfragments/1757.feature | 2 +- changelogs/client_server/newsfragments/1772.clarification | 1 - changelogs/client_server/newsfragments/1808.clarification | 1 - changelogs/client_server/newsfragments/1808.deprecation | 1 + changelogs/client_server/newsfragments/1813.clarification | 2 +- .../newsfragments/{1816.clarification => 1816.feature} | 0 changelogs/client_server/newsfragments/1841.clarification | 2 +- changelogs/client_server/newsfragments/1846.clarification | 2 +- changelogs/client_server/newsfragments/1847.feature | 2 +- changelogs/client_server/newsfragments/1861.clarification | 2 +- changelogs/client_server/newsfragments/1863.clarification | 2 +- changelogs/identity_service/newsfragments/1772.clarification | 1 - changelogs/identity_service/newsfragments/1808.clarification | 1 - changelogs/identity_service/newsfragments/1808.deprecation | 1 + changelogs/internal/newsfragments/1769.clarification | 2 +- changelogs/internal/newsfragments/1770.clarification | 2 +- changelogs/internal/newsfragments/1771.clarification | 2 +- .../newsfragments/1772.clarification | 0 changelogs/internal/newsfragments/1781.clarification | 2 +- changelogs/internal/newsfragments/1786.clarification | 2 +- .../internal/newsfragments/{1793.misc => 1793.clarification} | 0 changelogs/internal/newsfragments/1803.clarification | 2 +- changelogs/internal/newsfragments/1804.clarification | 2 +- changelogs/internal/newsfragments/1813.clarification | 1 + .../newsfragments/1822.clarification | 0 changelogs/room_versions/newsfragments/1827.clarification | 2 +- changelogs/server_server/newsfragments/1772.clarification | 1 - changelogs/server_server/newsfragments/1813.clarification | 2 +- 31 files changed, 21 insertions(+), 23 deletions(-) rename changelogs/client_server/newsfragments/{1755.clarification => 1755.feature} (100%) delete mode 100644 changelogs/client_server/newsfragments/1772.clarification delete mode 100644 changelogs/client_server/newsfragments/1808.clarification create mode 100644 changelogs/client_server/newsfragments/1808.deprecation rename changelogs/client_server/newsfragments/{1816.clarification => 1816.feature} (100%) delete mode 100644 changelogs/identity_service/newsfragments/1772.clarification delete mode 100644 changelogs/identity_service/newsfragments/1808.clarification create mode 100644 changelogs/identity_service/newsfragments/1808.deprecation rename changelogs/{application_service => internal}/newsfragments/1772.clarification (100%) rename changelogs/internal/newsfragments/{1793.misc => 1793.clarification} (100%) create mode 100644 changelogs/internal/newsfragments/1813.clarification rename changelogs/{client_server => internal}/newsfragments/1822.clarification (100%) delete mode 100644 changelogs/server_server/newsfragments/1772.clarification diff --git a/changelogs/application_service/newsfragments/1810.clarification b/changelogs/application_service/newsfragments/1810.clarification index 66dab495..fd21375c 100644 --- a/changelogs/application_service/newsfragments/1810.clarification +++ b/changelogs/application_service/newsfragments/1810.clarification @@ -1 +1 @@ -Clarify that appservices should be notified of events relating to the sender_localpart user. +Clarify that appservices should be notified of events relating to the `sender_localpart` user. diff --git a/changelogs/client_server/newsfragments/1644.clarification b/changelogs/client_server/newsfragments/1644.clarification index 78c0919d..279c4312 100644 --- a/changelogs/client_server/newsfragments/1644.clarification +++ b/changelogs/client_server/newsfragments/1644.clarification @@ -1 +1 @@ -Clarify specification by adding `/logout` to the overview list of endpoints that don't take a JSON request body. +Add `/logout` and clarify the endpoints which do not take a JSON request body. diff --git a/changelogs/client_server/newsfragments/1755.clarification b/changelogs/client_server/newsfragments/1755.feature similarity index 100% rename from changelogs/client_server/newsfragments/1755.clarification rename to changelogs/client_server/newsfragments/1755.feature diff --git a/changelogs/client_server/newsfragments/1757.feature b/changelogs/client_server/newsfragments/1757.feature index 3471c1b9..f65d48ba 100644 --- a/changelogs/client_server/newsfragments/1757.feature +++ b/changelogs/client_server/newsfragments/1757.feature @@ -1 +1 @@ -Add optional `animated` query string option to `GET /_matrix/media/v3/thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). \ No newline at end of file +Add optional `animated` query string option to `GET /thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1772.clarification b/changelogs/client_server/newsfragments/1772.clarification deleted file mode 100644 index b2aafa0d..00000000 --- a/changelogs/client_server/newsfragments/1772.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the OpenAPI definition of the security schemes. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1808.clarification b/changelogs/client_server/newsfragments/1808.clarification deleted file mode 100644 index ff2c1651..00000000 --- a/changelogs/client_server/newsfragments/1808.clarification +++ /dev/null @@ -1 +0,0 @@ -Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). diff --git a/changelogs/client_server/newsfragments/1808.deprecation b/changelogs/client_server/newsfragments/1808.deprecation new file mode 100644 index 00000000..ae9f620d --- /dev/null +++ b/changelogs/client_server/newsfragments/1808.deprecation @@ -0,0 +1 @@ +Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. diff --git a/changelogs/client_server/newsfragments/1813.clarification b/changelogs/client_server/newsfragments/1813.clarification index af643e2e..fa76c2a1 100644 --- a/changelogs/client_server/newsfragments/1813.clarification +++ b/changelogs/client_server/newsfragments/1813.clarification @@ -1 +1 @@ -Use `patternProperties` in more places with supported formats. +Link to existing grammar where possible in types. diff --git a/changelogs/client_server/newsfragments/1816.clarification b/changelogs/client_server/newsfragments/1816.feature similarity index 100% rename from changelogs/client_server/newsfragments/1816.clarification rename to changelogs/client_server/newsfragments/1816.feature diff --git a/changelogs/client_server/newsfragments/1841.clarification b/changelogs/client_server/newsfragments/1841.clarification index faf8aae9..3ccb2333 100644 --- a/changelogs/client_server/newsfragments/1841.clarification +++ b/changelogs/client_server/newsfragments/1841.clarification @@ -1 +1 @@ -Fix broken link to push rule condition kinds. +Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1846.clarification b/changelogs/client_server/newsfragments/1846.clarification index 6f57eb35..ee5387a8 100644 --- a/changelogs/client_server/newsfragments/1846.clarification +++ b/changelogs/client_server/newsfragments/1846.clarification @@ -1 +1 @@ -Clarify that per-request UIA for /login/get_token is an RFC 2119 MUST requirement. +Use RFC 2119 keywords more consistently. diff --git a/changelogs/client_server/newsfragments/1847.feature b/changelogs/client_server/newsfragments/1847.feature index 25d1914b..ab3dbc34 100644 --- a/changelogs/client_server/newsfragments/1847.feature +++ b/changelogs/client_server/newsfragments/1847.feature @@ -1 +1 @@ -Add the new `unsigned.membership` property to events served over the client-server API, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115). +Add the new `unsigned.membership` property to events, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115). diff --git a/changelogs/client_server/newsfragments/1861.clarification b/changelogs/client_server/newsfragments/1861.clarification index 9d877ff5..ee5387a8 100644 --- a/changelogs/client_server/newsfragments/1861.clarification +++ b/changelogs/client_server/newsfragments/1861.clarification @@ -1 +1 @@ -Use RFC 2119 keywords more consistently throughout various parts of the specification. \ No newline at end of file +Use RFC 2119 keywords more consistently. diff --git a/changelogs/client_server/newsfragments/1863.clarification b/changelogs/client_server/newsfragments/1863.clarification index d054d41d..688288cf 100644 --- a/changelogs/client_server/newsfragments/1863.clarification +++ b/changelogs/client_server/newsfragments/1863.clarification @@ -1 +1 @@ -Minor clarifications to the "end-to-end encryption" module. +Clarify where keys reside when checking an `m.room.encrypted` event. diff --git a/changelogs/identity_service/newsfragments/1772.clarification b/changelogs/identity_service/newsfragments/1772.clarification deleted file mode 100644 index b2aafa0d..00000000 --- a/changelogs/identity_service/newsfragments/1772.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the OpenAPI definition of the security schemes. \ No newline at end of file diff --git a/changelogs/identity_service/newsfragments/1808.clarification b/changelogs/identity_service/newsfragments/1808.clarification deleted file mode 100644 index ff2c1651..00000000 --- a/changelogs/identity_service/newsfragments/1808.clarification +++ /dev/null @@ -1 +0,0 @@ -Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). diff --git a/changelogs/identity_service/newsfragments/1808.deprecation b/changelogs/identity_service/newsfragments/1808.deprecation new file mode 100644 index 00000000..ae9f620d --- /dev/null +++ b/changelogs/identity_service/newsfragments/1808.deprecation @@ -0,0 +1 @@ +Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. diff --git a/changelogs/internal/newsfragments/1769.clarification b/changelogs/internal/newsfragments/1769.clarification index ebf8030d..c092b8f7 100644 --- a/changelogs/internal/newsfragments/1769.clarification +++ b/changelogs/internal/newsfragments/1769.clarification @@ -1 +1 @@ -Formatting fixes in CONTRIBUTING.rst. +Formatting fixes in `CONTRIBUTING.rst`. diff --git a/changelogs/internal/newsfragments/1770.clarification b/changelogs/internal/newsfragments/1770.clarification index e5fb516f..0eb57682 100644 --- a/changelogs/internal/newsfragments/1770.clarification +++ b/changelogs/internal/newsfragments/1770.clarification @@ -1 +1 @@ -Reduce whitespace on mobile viewports +Improve rendering on mobile devices. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1771.clarification b/changelogs/internal/newsfragments/1771.clarification index b1941e18..0eb57682 100644 --- a/changelogs/internal/newsfragments/1771.clarification +++ b/changelogs/internal/newsfragments/1771.clarification @@ -1 +1 @@ -Arrange rows in `.basic-info` tables vertically when horizontal space is constrained. +Improve rendering on mobile devices. \ No newline at end of file diff --git a/changelogs/application_service/newsfragments/1772.clarification b/changelogs/internal/newsfragments/1772.clarification similarity index 100% rename from changelogs/application_service/newsfragments/1772.clarification rename to changelogs/internal/newsfragments/1772.clarification diff --git a/changelogs/internal/newsfragments/1781.clarification b/changelogs/internal/newsfragments/1781.clarification index 4fb58650..8776d77b 100644 --- a/changelogs/internal/newsfragments/1781.clarification +++ b/changelogs/internal/newsfragments/1781.clarification @@ -1 +1 @@ -Fix `github-labels.rst` +Fix `github-labels.rst`. diff --git a/changelogs/internal/newsfragments/1786.clarification b/changelogs/internal/newsfragments/1786.clarification index 1810c632..c66e15e3 100644 --- a/changelogs/internal/newsfragments/1786.clarification +++ b/changelogs/internal/newsfragments/1786.clarification @@ -1 +1 @@ -Upgrade jsonschema and python-jsonpath CI scripts dependencies. +Update dependencies. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1793.misc b/changelogs/internal/newsfragments/1793.clarification similarity index 100% rename from changelogs/internal/newsfragments/1793.misc rename to changelogs/internal/newsfragments/1793.clarification diff --git a/changelogs/internal/newsfragments/1803.clarification b/changelogs/internal/newsfragments/1803.clarification index dbfaa8c9..c66e15e3 100644 --- a/changelogs/internal/newsfragments/1803.clarification +++ b/changelogs/internal/newsfragments/1803.clarification @@ -1 +1 @@ -Update most CI actions. +Update dependencies. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1804.clarification b/changelogs/internal/newsfragments/1804.clarification index 39249cb8..c66e15e3 100644 --- a/changelogs/internal/newsfragments/1804.clarification +++ b/changelogs/internal/newsfragments/1804.clarification @@ -1 +1 @@ -Update typos CI action. +Update dependencies. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1813.clarification b/changelogs/internal/newsfragments/1813.clarification new file mode 100644 index 00000000..af643e2e --- /dev/null +++ b/changelogs/internal/newsfragments/1813.clarification @@ -0,0 +1 @@ +Use `patternProperties` in more places with supported formats. diff --git a/changelogs/client_server/newsfragments/1822.clarification b/changelogs/internal/newsfragments/1822.clarification similarity index 100% rename from changelogs/client_server/newsfragments/1822.clarification rename to changelogs/internal/newsfragments/1822.clarification diff --git a/changelogs/room_versions/newsfragments/1827.clarification b/changelogs/room_versions/newsfragments/1827.clarification index c122052d..ca5f3aea 100644 --- a/changelogs/room_versions/newsfragments/1827.clarification +++ b/changelogs/room_versions/newsfragments/1827.clarification @@ -1 +1 @@ -Fix minor spelling mistake of object being spelt "obiect". +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1772.clarification b/changelogs/server_server/newsfragments/1772.clarification deleted file mode 100644 index b2aafa0d..00000000 --- a/changelogs/server_server/newsfragments/1772.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the OpenAPI definition of the security schemes. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1813.clarification b/changelogs/server_server/newsfragments/1813.clarification index af643e2e..fa76c2a1 100644 --- a/changelogs/server_server/newsfragments/1813.clarification +++ b/changelogs/server_server/newsfragments/1813.clarification @@ -1 +1 @@ -Use `patternProperties` in more places with supported formats. +Link to existing grammar where possible in types. From 560f29cff35c497a0a088e0c25391d958575d163 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 19 Jun 2024 22:08:20 -0600 Subject: [PATCH 22/70] Update release documentation (Q2 2024 edition) (#1759) * Update release documentation (Q2 2024 edition) * changelog * Drop the ranges we don't follow * Don't discourage maintenance * Patch releases just aren't a good idea --- .github/ISSUE_TEMPLATE/release.md | 24 ++++---- .../internal/newsfragments/1759.clarification | 1 + meta/releasing.md | 59 +++++++++---------- 3 files changed, 43 insertions(+), 41 deletions(-) create mode 100644 changelogs/internal/newsfragments/1759.clarification diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md index 4128bb9b..bbe12160 100644 --- a/.github/ISSUE_TEMPLATE/release.md +++ b/.github/ISSUE_TEMPLATE/release.md @@ -16,20 +16,22 @@ Previous release: Preflight checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)): +* [ ] Pin this issue to the repo. * [ ] Ensure the social media account holders are available for the release day. -* [ ] Blog post written -* [ ] Check for release blockers that may have been missed -* [ ] Review/fix the changelog +* [ ] Blog post written. +* [ ] Check for release blockers that may have been missed. +* [ ] Review/fix the changelog. Release checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)): -* [ ] Branch stuffs -* [ ] Github release artifact -* [ ] Published to spec.matrix.org -* [ ] All links work -* [ ] Publish blog post -* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted -* [ ] Post to Twitter/Mastodon -* [ ] Close this issue +* [ ] Branch stuffs. +* [ ] Github release artifact. +* [ ] Published to spec.matrix.org. +* [ ] All links work. +* [ ] Publish blog post. +* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted. +* [ ] Post to Twitter/Mastodon. +* [ ] Close this issue. +* [ ] Unpin this issue from the repo. Known release blockers: * [ ] diff --git a/changelogs/internal/newsfragments/1759.clarification b/changelogs/internal/newsfragments/1759.clarification new file mode 100644 index 00000000..a44c98df --- /dev/null +++ b/changelogs/internal/newsfragments/1759.clarification @@ -0,0 +1 @@ +Update the spec release process and related documentation. \ No newline at end of file diff --git a/meta/releasing.md b/meta/releasing.md index 83261385..eb2c16b7 100644 --- a/meta/releasing.md +++ b/meta/releasing.md @@ -6,48 +6,43 @@ machinery works. ## Timeline -The spec is released each calendar quarter. The target release dates are within the -following ranges: +The spec is released each calendar quarter. The *target* months are: -* Q1: January 20-27 (critically, before FOSDEM). -* Q2: May 20-27. -* Q3: August 20-27. -* Q4: November 1-15 (before recurring November conflicts, like IETF). +* Q1: January or February. +* Q2: May. +* Q3: August. +* Q4: November. -The SCT aims to have dates picked out by: - -* Q1: January 10. -* Q2: May 1. -* Q3: August 1. -* Q4: October 15. +The SCT aims to have dates picked out 2 weeks before the chosen release date. When +possible, releases should be scheduled for Thursdays and Fridays to allow a few +consecutive business days for identifying blockers. When a release date is picked, a [checklist](https://github.com/matrix-org/matrix-spec/issues/new?assignees=&labels=release-blocker&projects=&template=release.md&title=Matrix+1.X) -issue is created to track details of the release. Release blockers should continue to -be accepted up until 7 calendar days prior to the release date. +issue is created to track details of the release. Release blockers should continue +to be accepted at the discretion of whoever is doing the release (typically, blockers +should be allowed up to 1-2 days before the release date). **Release dates are not promises.** The SCT reserves the ability to change, cancel, postpone, etc a release for any reason. Do not rely on a release happening on a given day until the release has actually happened & blog post published. -Once a release is scheduled, the SCT will begin planning what the next release is +Once a release is *scheduled*, the SCT will begin planning what the next release is expected to look like. The plan should be included in the spec release blog post, and be ready for execution on spec release day. Plans are guides and not promises. -A blog post for the SCT members to review should be ready at minimum 1 week before -the target release date. 1-2 days before the release itself, the prerequisite steps -below are executed to ensure the spec release can go ahead. +A blog post for the SCT members to review should be ready 2-3 days prior to the +release at minimum. Preferably a week in advance. + +1-2 days before the release itself, the prerequisite steps below are executed to +ensure the spec release can go ahead. ## Release composition *This section is a work in progress.* -Mentioned above, the SCT aims to have spec releases quarterly. Each quarter has a -slightly different theme to it: - -* Q1: Massive feature release, if possible. This generally happens thanks to FOSDEM. -* Q2: Regular feature release, if possible. -* Q3: Momentum-continuing feature release, if possible. -* Q4: Preferably a maintenance release, but will accept features per normal. +Spec releases do not currently have attached themes, though when planning a release +a broad theme may be considered. Ideally, each release contains a "hero feature" +which is highlighted in the later blog post. ## Prerequisites / preparation @@ -115,12 +110,16 @@ release. ## Patching a release -From time to time we'll need to update a release in the wild. Examples include fixing typos, -updating build machinery, etc. Typically it is not considered a good idea to patch a release -more than 1 month after the original release date - this is because the administrative effort -is typically best reserved for the next release cycle. +Patch releases are used to fix the most recent release on record. Typically a patch +release will be deployed if there is an issue with the build machinery, a factual +error is introduced by the release, or there are notable clarity issues introduced +by the release which may affect implementation. It's usually not a good idea to +ship a patch release if it can be avoided. -**Patch releases are not to be used for spec changes. Only typos and equivalent.** +Typos and similar do not generally require a patch release. + +**Patch releases must not to be used for spec changes (new MSCs, etc) beyond fixing +factual errors.** 1. Add the required changes to the release branch (`release/v1.2` for example). 2. Fast forward the `v1.2` tag to the release branch head. From 5fbfdd6821bc3b7aa02976a888052272fd16fbe4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 20 Jun 2024 10:42:40 +0200 Subject: [PATCH 23/70] Fix generated HTML (#1880) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add tr as child of thead in HTML tables It is invalid HTML for th to be the direct children of thead Signed-off-by: Kévin Commaille * Remove unnecessary HTML code end tag Signed-off-by: Kévin Commaille * Avoid nesting p HTML elements A p HTML element cannot contain other block elements, so the "parent" element is closed when the first "child" one is opened. We need to use Page.RenderString with options to force Hugo to keep the wrapping p elements even if the content contains a single paragraph. Signed-off-by: Kévin Commaille * Add missing HTML details end tags Signed-off-by: Kévin Commaille * Replace HTML a self-closing tag with start and end tags The a element start and end tags are mandatory. Signed-off-by: Kévin Commaille * Replace obsolete HTML name attribute with id Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --- .../internal/newsfragments/1880.clarification | 1 + content/client-server-api/modules/push.md | 14 +++++++------- layouts/partials/events/render-event.html | 2 ++ .../partials/openapi/render-content-type.html | 6 ++++-- .../partials/openapi/render-object-table.html | 16 ++++++++++------ layouts/partials/openapi/render-operation.html | 2 +- layouts/partials/openapi/render-responses.html | 6 ++++-- layouts/shortcodes/definition.html | 2 ++ 8 files changed, 31 insertions(+), 18 deletions(-) create mode 100644 changelogs/internal/newsfragments/1880.clarification diff --git a/changelogs/internal/newsfragments/1880.clarification b/changelogs/internal/newsfragments/1880.clarification new file mode 100644 index 00000000..56090e20 --- /dev/null +++ b/changelogs/internal/newsfragments/1880.clarification @@ -0,0 +1 @@ +Fix validation errors in generated HTML. diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index c674bac9..2d828a01 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -521,7 +521,7 @@ Definition: } ``` - **`.m.rule.is_user_mention`** + **`.m.rule.is_user_mention`** {{< added-in v="1.7" >}} @@ -555,7 +555,7 @@ Definition: } ``` - **`.m.rule.contains_display_name`** + **`.m.rule.contains_display_name`** {{% changed-in v="1.7" %}} @@ -590,7 +590,7 @@ Definition: } ``` - **`.m.rule.is_room_mention`** + **`.m.rule.is_room_mention`** {{< added-in v="1.7" >}} @@ -624,7 +624,7 @@ Definition: } ``` - **`.m.rule.roomnotif`** + **`.m.rule.roomnotif`** {{% changed-in v="1.7" %}} @@ -662,7 +662,7 @@ Definition: } ``` -**`.m.rule.tombstone`** +**`.m.rule.tombstone`** Matches any state event whose type is `m.room.tombstone`. This is intended to notify users of a room when it is upgraded, similar to what @@ -696,7 +696,7 @@ Definition: } ``` -**`.m.rule.reaction`** +**`.m.rule.reaction`** {{% added-in v="1.7" %}} @@ -776,7 +776,7 @@ Definition: ##### Default Content Rules - **`.m.rule.contains_user_name`** + **`.m.rule.contains_user_name`** {{% changed-in v="1.7" %}} diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html index 71ba60bd..154e51bf 100644 --- a/layouts/partials/events/render-event.html +++ b/layouts/partials/events/render-event.html @@ -101,4 +101,6 @@ {{ end }} {{ end }} + + diff --git a/layouts/partials/openapi/render-content-type.html b/layouts/partials/openapi/render-content-type.html index 036522de..96033e16 100644 --- a/layouts/partials/openapi/render-content-type.html +++ b/layouts/partials/openapi/render-content-type.html @@ -16,8 +16,10 @@ - - + + + + {{ range $idx, $content_type := $content_types }} diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index d2b09acb..3fd49f0b 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -31,9 +31,11 @@ {{ end }} - - - + + + + + {{ range $property_name, $property := $properties }} @@ -68,7 +70,7 @@ {{ if reflect.IsMap .additionalProperties }} - + @@ -90,8 +92,10 @@ resolve-additional-types.) {{ end }} - - + + + + {{ $property := . }} diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 8c6fce0e..ef525353 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -46,7 +46,7 @@ {{ partial "changed-in" (dict "changes_dict" (index $operation_data "x-changedInMatrixVersion")) }} {{ end -}} -

      {{ $operation_data.description | markdownify }}

      +{{ $operation_data.description | page.RenderString (dict "display" "block") }}
      Content-TypeDescription
      Content-TypeDescription
      {{ . }}
      NameTypeDescription
      NameTypeDescription
      <Other properties><Other properties> {{ partial "partials/property-type" .additionalProperties | safeHTML }} {{ partial "partials/property-description" (dict "property" .additionalProperties) }}
      {{ . }}
      TypeDescription
      TypeDescription
      diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 0ffc4884..80dcb582 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -20,8 +20,10 @@
      - - + + + + {{ range $code, $response := $responses }} diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html index a1f0904e..f5d50e75 100644 --- a/layouts/shortcodes/definition.html +++ b/layouts/shortcodes/definition.html @@ -66,4 +66,6 @@ {{ jsonify (dict "indent" " ") $example }} ``` + + From 27e71fff1018cde9529767e729793b93c6e42307 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 20 Jun 2024 10:46:33 +0200 Subject: [PATCH 24/70] Render added/changed in info on request and response content types (#1876) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Render added/changed in info on request and response content types Fixes: #1774 Signed-off-by: Johannes Marbach Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com> --- .../internal/newsfragments/1876.clarification | 1 + data/api/client-server/content-repo.yaml | 5 +++-- .../partials/openapi/render-content-type.html | 18 +++++++++--------- layouts/partials/openapi/render-request.html | 8 +------- layouts/partials/openapi/render-responses.html | 8 +------- 5 files changed, 15 insertions(+), 25 deletions(-) create mode 100644 changelogs/internal/newsfragments/1876.clarification diff --git a/changelogs/internal/newsfragments/1876.clarification b/changelogs/internal/newsfragments/1876.clarification new file mode 100644 index 00000000..9f840914 --- /dev/null +++ b/changelogs/internal/newsfragments/1876.clarification @@ -0,0 +1 @@ +Render added/changed in info on request and response content types. diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index d0a6e5bb..92ca6caa 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -715,8 +715,9 @@ components: bytes: content: application/octet-stream: - example: - description: The content to be uploaded. + schema: + description: The content to be uploaded. + example: required: true responses: uploadTooLarge: diff --git a/layouts/partials/openapi/render-content-type.html b/layouts/partials/openapi/render-content-type.html index 96033e16..a7c90e1a 100644 --- a/layouts/partials/openapi/render-content-type.html +++ b/layouts/partials/openapi/render-content-type.html @@ -1,16 +1,12 @@ {{/* - Render a table showing content types and their descriptions, given - two arrays with equal length: + Render a table showing content types and their descriptions, given: - * `content_types`: the content type strings - - * `descriptions`: the description strings + * `content_types`: OpenAPI data specifying the content types as a dictionary of the form {string: {"schema": JsonSchema}} */}} {{ $content_types := .content_types }} -{{ $descriptions := .descriptions}} {{ if (gt (len $content_types) 0) }} @@ -21,10 +17,14 @@ - {{ range $idx, $content_type := $content_types }} + {{ range $mime, $body := $content_types }} - - + + {{ end }}
      StatusDescription
      StatusDescription
      Description
      {{ $content_type }}{{ index $descriptions $idx | markdownify -}}{{ $mime }} + {{ $body.schema.description | markdownify -}} + {{ if (index $body.schema "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index $body.schema "x-addedInMatrixVersion")) }}{{ end -}} + {{ if (index $body.schema "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index $body.schema "x-changedInMatrixVersion")) }}{{ end -}} +
      diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index 5fa0c255..92811f12 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -50,13 +50,7 @@ {{/* Show the content types and description. */}} - {{ $mimes := slice }} - {{ $descriptions := slice }} - {{ range $mime, $body := $request_body.content }} - {{ $mimes = $mimes | append $mime }} - {{ $descriptions = $descriptions | append $request_body.description }} - {{ end }} - {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }} + {{ partial "openapi/render-content-type" (dict "content_types" $request_body.content) }} {{ end }}

      Request body example

      diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 80dcb582..f26110b4 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -123,13 +123,7 @@ {{/* Show the content types and description. */}} - {{ $mimes := slice }} - {{ $descriptions := slice }} - {{ range $mime, $body := $response.content }} - {{ $mimes = $mimes | append $mime }} - {{ $descriptions = $descriptions | append $body.schema.description }} - {{ end }} - {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }} + {{ partial "openapi/render-content-type" (dict "content_types" $response.content) }} {{ end }} {{ end }} {{ end }} From 8ef84d1cc7c7dd4494c1232150c4d4ec6dca2fd8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 20 Jun 2024 09:26:58 -0600 Subject: [PATCH 25/70] More normalization --- changelogs/internal/newsfragments/1851.clarification | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/internal/newsfragments/1851.clarification b/changelogs/internal/newsfragments/1851.clarification index e89777c5..af7c653e 100644 --- a/changelogs/internal/newsfragments/1851.clarification +++ b/changelogs/internal/newsfragments/1851.clarification @@ -1 +1 @@ -Generate ToC with Hugo rather than JavaScript. +Generate the Table of Contents with Hugo rather than JavaScript. From 094e25b6cdf3c4bac4606dd180d8ae0fd77c3583 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 20 Jun 2024 17:36:33 +0200 Subject: [PATCH 26/70] Ensure more uniqueness for generated HTML IDs (#1881) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Include method in all API endpoint children's IDs Avoids duplicate IDs for object of endpoints that use the same path but a different method. Signed-off-by: Kévin Commaille * Differentiate API endpoints' request and response children's IDs Ensures that the objects have a unique ID compared to other parts of the endpoint. Mostly useful for the Error type that can be used for responses with different status codes. Signed-off-by: Kévin Commaille * Differentiate the names of both SessionData formats Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- changelogs/internal/newsfragments/1881.clarification | 1 + content/client-server-api/modules/end_to_end_encryption.md | 4 ++-- .../client-server/definitions/key_backup_session_data.yaml | 2 +- .../client-server/definitions/megolm_export_session_data.yaml | 1 + layouts/partials/openapi/render-operation.html | 4 ++-- layouts/partials/openapi/render-request.html | 3 ++- layouts/partials/openapi/render-responses.html | 3 ++- 7 files changed, 11 insertions(+), 7 deletions(-) create mode 100644 changelogs/internal/newsfragments/1881.clarification diff --git a/changelogs/internal/newsfragments/1881.clarification b/changelogs/internal/newsfragments/1881.clarification new file mode 100644 index 00000000..d698545f --- /dev/null +++ b/changelogs/internal/newsfragments/1881.clarification @@ -0,0 +1 @@ +Ensure most generated HTML IDs are unique. diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 5787205a..49b053f6 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1349,7 +1349,7 @@ the following format: The `session_data` field in the backups is constructed as follows: 1. Encode the session key to be backed up as a JSON object using the - `SessionData` format defined below. + `BackedUpSessionData` format defined below. 2. Generate an ephemeral curve25519 key, and perform an ECDH with the ephemeral key and the backup's public key to generate a shared @@ -1427,7 +1427,7 @@ user-supplied passphrase, and is created as follows: ###### Key export format -The exported sessions are formatted as a JSON array of `SessionData` +The exported sessions are formatted as a JSON array of `ExportedSessionData` objects described as follows: {{% definition path="api/client-server/definitions/megolm_export_session_data" %}} diff --git a/data/api/client-server/definitions/key_backup_session_data.yaml b/data/api/client-server/definitions/key_backup_session_data.yaml index 18963cbe..bc61bb30 100644 --- a/data/api/client-server/definitions/key_backup_session_data.yaml +++ b/data/api/client-server/definitions/key_backup_session_data.yaml @@ -14,7 +14,7 @@ type: object -title: SessionData +title: BackedUpSessionData description: |- The format of a backed-up session key, prior to encryption, when using the `m.megolm_backup.v1.curve25519-aes-sha2` algorithm. diff --git a/data/api/client-server/definitions/megolm_export_session_data.yaml b/data/api/client-server/definitions/megolm_export_session_data.yaml index 8c1e5010..f5d1e409 100644 --- a/data/api/client-server/definitions/megolm_export_session_data.yaml +++ b/data/api/client-server/definitions/megolm_export_session_data.yaml @@ -16,6 +16,7 @@ allOf: - $ref: key_backup_session_data.yaml - type: object + title: ExportedSessionData description: |- The format used to encode a Megolm session key for export. diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index ef525353..13e7128c 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -20,14 +20,14 @@ {{ $method := .method }} {{ $endpoint := .endpoint }} {{ $operation_data := .operation_data }} -{{ $anchor := anchorize $endpoint }} +{{ $anchor := printf "%s%s" (lower $method) (anchorize $endpoint) }}
      -

      +

      {{ $method }} {{ $endpoint }}

      diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index 92811f12..80b352c6 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -16,6 +16,7 @@ {{ $parameters := .parameters }} {{ $request_body := .request_body }} {{ $anchor_base := .anchor_base }} +{{ $anchor := printf "%s_request" $anchor_base }}

      Request

      @@ -42,7 +43,7 @@ */}} {{ $schema := $json_body.schema }} - {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} + {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }} {{ range $additional_types }} {{ partial "openapi/render-object-table" . }} {{ end }} diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index f26110b4..084e9481 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -39,6 +39,7 @@ {{ range $code, $response := $responses }} {{ if $response.content }} + {{ $anchor := printf "%s_response-%s" $anchor_base $code }}

      {{$code}} response

      {{/* Display defined headers */}} {{ if $response.headers }} @@ -97,7 +98,7 @@ response. (This will be a no-op for response types which aren't objects or arrays.) */}} - {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} + {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }} {{ range $additional_types }} {{ partial "openapi/render-object-table" . }} {{ end }} From bd20d946c49016bca6e8eca77e1cece6b0eeab5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 20 Jun 2024 17:39:44 +0200 Subject: [PATCH 27/70] Fix the rendering of the event format for room versions 1 and 2 (#1883) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix rendering of array with items using anyOf Signed-off-by: Kévin Commaille * Use a single definition for Event Hash Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille * Add ending newline Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- .../newsfragments/1883.clarification | 1 + .../server-server/definitions/event_hash.yaml | 13 ++++++++++ data/api/server-server/definitions/pdu.yaml | 14 +---------- .../server-server/definitions/pdu_v11.yaml | 14 +---------- .../api/server-server/definitions/pdu_v3.yaml | 14 +---------- .../definitions/unsigned_pdu_base.yaml | 24 ++----------------- .../json-schema/resolve-additional-types.html | 4 ++++ .../partials/openapi/render-object-table.html | 12 ++++++++-- 8 files changed, 33 insertions(+), 63 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/1883.clarification create mode 100644 data/api/server-server/definitions/event_hash.yaml diff --git a/changelogs/room_versions/newsfragments/1883.clarification b/changelogs/room_versions/newsfragments/1883.clarification new file mode 100644 index 00000000..0676c664 --- /dev/null +++ b/changelogs/room_versions/newsfragments/1883.clarification @@ -0,0 +1 @@ +Fix the rendering of the event format for room versions 1 and 2. diff --git a/data/api/server-server/definitions/event_hash.yaml b/data/api/server-server/definitions/event_hash.yaml new file mode 100644 index 00000000..b88ac82e --- /dev/null +++ b/data/api/server-server/definitions/event_hash.yaml @@ -0,0 +1,13 @@ +type: object +title: Event Hash +description: |- + Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). +example: { + "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted" +} +properties: + sha256: + type: string + description: The hash. + example: ThisHashCoversAllFieldsInCaseThisIsRedacted +required: ['sha256'] diff --git a/data/api/server-server/definitions/pdu.yaml b/data/api/server-server/definitions/pdu.yaml index 5903f80e..00b83321 100644 --- a/data/api/server-server/definitions/pdu.yaml +++ b/data/api/server-server/definitions/pdu.yaml @@ -25,19 +25,7 @@ allOf: description: For redaction events, the ID of the event being redacted. example: "$def456:matrix.org" hashes: - type: object - title: Event Hash - description: |- - Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). - example: { - "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted" - } - properties: - sha256: - type: string - description: The hash. - example: ThisHashCoversAllFieldsInCaseThisIsRedacted - required: ['sha256'] + $ref: "event_hash.yaml" signatures: type: object description: |- diff --git a/data/api/server-server/definitions/pdu_v11.yaml b/data/api/server-server/definitions/pdu_v11.yaml index 3edfb6c8..60f9b3ac 100644 --- a/data/api/server-server/definitions/pdu_v11.yaml +++ b/data/api/server-server/definitions/pdu_v11.yaml @@ -47,19 +47,7 @@ allOf: Must contain less than or equal to 20 events. example: ["$URLsafe-base64EncodedHash", "$Another_Event"] hashes: - type: object - title: Event Hash - description: |- - Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). - example: { - "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted" - } - properties: - sha256: - type: string - description: The hash. - example: ThisHashCoversAllFieldsInCaseThisIsRedacted - required: ['sha256'] + $ref: "event_hash.yaml" signatures: type: object description: |- diff --git a/data/api/server-server/definitions/pdu_v3.yaml b/data/api/server-server/definitions/pdu_v3.yaml index 32d05b36..e801518c 100644 --- a/data/api/server-server/definitions/pdu_v3.yaml +++ b/data/api/server-server/definitions/pdu_v3.yaml @@ -49,19 +49,7 @@ allOf: Must contain less than or equal to 20 events. example: ["$base64EncodedHash", "$AnotherEvent"] hashes: - type: object - title: Event Hash - description: |- - Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). - example: { - "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted" - } - properties: - sha256: - type: string - description: The hash. - example: ThisHashCoversAllFieldsInCaseThisIsRedacted - required: ['sha256'] + $ref: "event_hash.yaml" signatures: type: object description: |- diff --git a/data/api/server-server/definitions/unsigned_pdu_base.yaml b/data/api/server-server/definitions/unsigned_pdu_base.yaml index ce42236f..a2ec9552 100644 --- a/data/api/server-server/definitions/unsigned_pdu_base.yaml +++ b/data/api/server-server/definitions/unsigned_pdu_base.yaml @@ -60,17 +60,7 @@ properties: - type: string title: Event ID example: "$abc123:matrix.org" - - type: object - title: Event Hash - example: { - "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" - } - properties: - sha256: - type: string - description: The event hash. - example: Base64EncodedSha256HashesShouldBe43BytesLong - required: ['sha256'] + - $ref: "event_hash.yaml" depth: type: integer description: |- @@ -96,17 +86,7 @@ properties: - type: string title: Event ID example: "$abc123:matrix.org" - - type: object - title: Event Hash - example: { - "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" - } - properties: - sha256: - type: string - description: The event hash. - example: Base64EncodedSha256HashesShouldBe43BytesLong - required: ['sha256'] + - $ref: "event_hash.yaml" unsigned: type: object title: UnsignedData diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html index f6f09646..9d5e630a 100644 --- a/layouts/partials/json-schema/resolve-additional-types.html +++ b/layouts/partials/json-schema/resolve-additional-types.html @@ -155,6 +155,7 @@ {{ if eq $this_object.type "array" }} /* Add any nested objects referenced in this object's `items` */ {{ if $this_object.items.anyOf }} + {{ $updated_schemas := slice }} {{ range $idx, $item := $this_object.items.anyOf }} {{ $res := partial "get-additional-objects" (dict "this_object" $item @@ -163,7 +164,10 @@ "name" (printf "%s.items[%d]" $name $idx) ) }} {{ $all_objects = $res.objects }} + {{ $updated_schemas = $updated_schemas | append $res.schema }} {{ end }} + /* Update the top-level schema with the updated subschemas for the items */ + {{ $this_object = merge $this_object (dict "items" (dict "anyOf" $updated_schemas)) }} {{ else if reflect.IsMap $this_object.items}} {{ $res := partial "get-additional-objects" (dict "this_object" $this_object.items diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 3fd49f0b..656f556a 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -117,6 +117,9 @@ resolve-additional-types.) * `oneOf`: optional array of dictionaries describing the different formats that the property can have + + * `anyOf`: optional array of dictionaries describing the different formats + that the property can have * `properties`: if the type is an object, optional dictionary for well-defined properties, each given as: `property_name` : `property_data` @@ -158,13 +161,14 @@ resolve-additional-types.) {{ $type = . }} {{ end }} {{ end }} - {{ else if or (reflect.IsSlice .type) .oneOf }} + {{ else if or (reflect.IsSlice .type) .oneOf .anyOf }} {{/* It's legal to specify an array of types. - There are two ways to do that: + There are three ways to do that: - Use an array of strings. - Use oneOf, with items having a schema. + - Use anyOf, with items having a schema. Join them together in that case, like `type|other_type`. */}} @@ -174,6 +178,10 @@ resolve-additional-types.) {{ range .oneOf }} {{ $types = $types | append (partial "property-type" .) }} {{ end }} + {{ else if .anyOf }} + {{ range .anyOf }} + {{ $types = $types | append (partial "property-type" .) }} + {{ end }} {{ else }} {{ range .type }} {{ $types = $types | append (htmlEscape .) }} From 18628dc5d74eb3cc03ac5e89968c23c9fa27c982 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 20 Jun 2024 17:39:50 +0200 Subject: [PATCH 28/70] Allow to specify a prefix for generated HTML IDs of API endpoints (#1882) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Allow to specify a prefix for generated HTML IDs of API endpoints Allows to deduplicate IDs of duplicate endpoints Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- .../internal/newsfragments/1882.clarification | 1 + content/client-server-api/modules/room_previews.md | 2 +- .../modules/third_party_invites.md | 2 +- layouts/partials/openapi/render-api.html | 13 +++++++++---- layouts/partials/openapi/render-operation.html | 9 ++++++++- layouts/shortcodes/http-api.html | 6 +++++- 6 files changed, 25 insertions(+), 8 deletions(-) create mode 100644 changelogs/internal/newsfragments/1882.clarification diff --git a/changelogs/internal/newsfragments/1882.clarification b/changelogs/internal/newsfragments/1882.clarification new file mode 100644 index 00000000..99c0ca05 --- /dev/null +++ b/changelogs/internal/newsfragments/1882.clarification @@ -0,0 +1 @@ +Allow to specify a prefix for generated HTML IDs of API endpoints. diff --git a/content/client-server-api/modules/room_previews.md b/content/client-server-api/modules/room_previews.md index 277f7c39..ef9238b2 100644 --- a/content/client-server-api/modules/room_previews.md +++ b/content/client-server-api/modules/room_previews.md @@ -21,7 +21,7 @@ Clients can of course also call other endpoints such as [GET and [GET /search](#post_matrixclientv3search) to access events outside the `/events` stream. -{{% http-api spec="client-server" api="peeking_events" %}} +{{% http-api spec="client-server" api="peeking_events" anchor_base="peeking" %}} #### Server behaviour diff --git a/content/client-server-api/modules/third_party_invites.md b/content/client-server-api/modules/third_party_invites.md index aff7b530..7e418e15 100644 --- a/content/client-server-api/modules/third_party_invites.md +++ b/content/client-server-api/modules/third_party_invites.md @@ -33,7 +33,7 @@ invitee does indeed own that third-party identifier. See the A client asks a server to invite a user by their third-party identifier. -{{% http-api spec="client-server" api="third_party_membership" %}} +{{% http-api spec="client-server" api="third_party_membership" anchor_base="thirdparty" %}} #### Server behaviour diff --git a/layouts/partials/openapi/render-api.html b/layouts/partials/openapi/render-api.html index fcbb1cfc..608cfa33 100644 --- a/layouts/partials/openapi/render-api.html +++ b/layouts/partials/openapi/render-api.html @@ -5,11 +5,16 @@ * `api_data`: the OpenAPI data * `base_url`: the base URL: that is, the part we glue onto the front of each value in `paths` to get a complete URL. + * `anchor_base`: an optional prefix for the HTML IDs generated by + this template. + + This template replaces the old {{*_http_api}} template. */}} {{ $api_data := index .api_data }} {{ $base_url := .base_url }} +{{ $anchor_base := .anchor_base }} {{ range $path_name, $path_data := $api_data.paths }} @@ -21,28 +26,28 @@ {{ with $path_data.get }} - {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . ) }} + {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . "anchor_base" $anchor_base) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} {{ with $path_data.post }} - {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . ) }} + {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . "anchor_base" $anchor_base) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} {{ with $path_data.put }} - {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . ) }} + {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . "anchor_base" $anchor_base) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} {{ with $path_data.delete }} - {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . ) }} + {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . "anchor_base" $anchor_base) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 13e7128c..9b0e25d1 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -5,6 +5,8 @@ * `method`: the method, e.g. GET, PUT * `endpoint`: the endpoint * `operation_data`: the OpenAPI data for the operation + * `anchor_base`: an optional prefix for the HTML IDs generated by + this template. This template renders the operation as a `
      ` containing: @@ -20,7 +22,12 @@ {{ $method := .method }} {{ $endpoint := .endpoint }} {{ $operation_data := .operation_data }} -{{ $anchor := printf "%s%s" (lower $method) (anchorize $endpoint) }} + +{{ $anchor := "" }} +{{ if .anchor_base }} + {{ $anchor = printf "%s_" .anchor_base }} +{{ end }} +{{ $anchor = printf "%s%s%s" $anchor (lower $method) (anchorize $endpoint) }}
      diff --git a/layouts/shortcodes/http-api.html b/layouts/shortcodes/http-api.html index 489385de..b5201c49 100644 --- a/layouts/shortcodes/http-api.html +++ b/layouts/shortcodes/http-api.html @@ -11,6 +11,9 @@ The file extension is omitted. For example: {{% http-api spec="server-server" api="public_rooms" %}} + * an optional `anchor_base` parameter, which should be used as a + prefix for the HTML IDs generated by this template. It should only + be necessary to provide one for duplicate endpoints. This template replaces the old {{*_http_api}} template. @@ -18,6 +21,7 @@ {{ $spec := .Params.spec}} {{ $api := .Params.api}} +{{ $anchor_base := .Params.anchor_base}} {{ $api_data := index .Site.Data.api .Params.spec .Params.api }} {{ $base_url := (index $api_data.servers 0).variables.basePath.default }} @@ -26,4 +30,4 @@ {{ $api_data = partial "json-schema/resolve-refs" (dict "schema" $api_data "path" $path) }} {{ $api_data = partial "json-schema/resolve-allof" $api_data }} -{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url) }} +{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "anchor_base" $anchor_base) }} From 3af77f0cb45fdd066826da83f5955461d6e3e310 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 20 Jun 2024 17:47:09 +0200 Subject: [PATCH 29/70] Fix the table of content for room versions (#1884) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix ToC for room versions pages Like for the cs-module shortcode, use .RenderShortcodes instead of .Content for the rver-fragment shortcode, so the headings are detected by Hugo. Signed-off-by: Kévin Commaille * Change the way "this version" is detected in added-in and changed-in shortcodes Now that we use .RenderShortcodes in the rver-fragment shortcode, we cannot remove the output of these shortcodes dynamically because they are replaced by a temporary placeholder due to Hugo's internals. Instead, since the `this` parameter was only used for room version, we always use the `v` parameter and compare with the version provided in the page's front matter. Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille * Add version front matter for v11 Signed-off-by: Kévin Commaille * Update changelogs/room_versions/newsfragments/1884.clarification --------- Signed-off-by: Kévin Commaille Co-authored-by: Travis Ralston --- .../room_versions/newsfragments/1884.clarification | 1 + content/rooms/fragments/v3-auth-rules.md | 2 +- content/rooms/fragments/v3-handling-redactions.md | 2 +- content/rooms/fragments/v4-event-ids.md | 2 +- content/rooms/fragments/v8-auth-rules.md | 4 ++-- content/rooms/v1.md | 1 + content/rooms/v10.md | 9 +++++---- content/rooms/v11.md | 7 ++++--- content/rooms/v2.md | 3 ++- content/rooms/v3.md | 11 +++++------ content/rooms/v4.md | 3 ++- content/rooms/v5.md | 1 + content/rooms/v6.md | 11 ++++++----- content/rooms/v7.md | 9 +++++---- content/rooms/v8.md | 7 ++++--- content/rooms/v9.md | 7 ++++--- layouts/shortcodes/added-in.html | 13 +++++++------ layouts/shortcodes/changed-in.html | 13 +++++++------ layouts/shortcodes/rver-fragment.html | 2 +- meta/documentation_style.rst | 3 --- 20 files changed, 60 insertions(+), 51 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/1884.clarification diff --git a/changelogs/room_versions/newsfragments/1884.clarification b/changelogs/room_versions/newsfragments/1884.clarification new file mode 100644 index 00000000..af7c653e --- /dev/null +++ b/changelogs/room_versions/newsfragments/1884.clarification @@ -0,0 +1 @@ +Generate the Table of Contents with Hugo rather than JavaScript. diff --git a/content/rooms/fragments/v3-auth-rules.md b/content/rooms/fragments/v3-auth-rules.md index 05b8065a..9fb56327 100644 --- a/content/rooms/fragments/v3-auth-rules.md +++ b/content/rooms/fragments/v3-auth-rules.md @@ -1,6 +1,6 @@ --- --- -{{< added-in this=true >}} In room versions 1 and 2, events need a +{{< added-in v=3 >}} In room versions 1 and 2, events need a signature from the domain of the `event_id` in order to be considered valid. This room version does not include an `event_id` over federation in the same respect, so does not need a signature from that server. diff --git a/content/rooms/fragments/v3-handling-redactions.md b/content/rooms/fragments/v3-handling-redactions.md index 5a9aa7c6..80d478bf 100644 --- a/content/rooms/fragments/v3-handling-redactions.md +++ b/content/rooms/fragments/v3-handling-redactions.md @@ -1,6 +1,6 @@ --- --- -{{% added-in this=true %}} In room versions 1 and 2, redactions were +{{% added-in v=3 %}} In room versions 1 and 2, redactions were explicitly part of the [authorization rules](/rooms/v1/#authorization-rules) under Rule 11. As of room version 3, these conditions no longer exist as represented by [this version's authorization rules](#authorization-rules). diff --git a/content/rooms/fragments/v4-event-ids.md b/content/rooms/fragments/v4-event-ids.md index 804d97ec..d6ad398f 100644 --- a/content/rooms/fragments/v4-event-ids.md +++ b/content/rooms/fragments/v4-event-ids.md @@ -1,6 +1,6 @@ --- --- -{{% added-in this=true %}} The event ID is the [reference +{{% added-in v=4 %}} The event ID is the [reference hash](/server-server-api#calculating-the-reference-hash-for-an-event) of the event encoded using a variation of [Unpadded Base64](/appendices#unpadded-base64) which replaces the 62nd and diff --git a/content/rooms/fragments/v8-auth-rules.md b/content/rooms/fragments/v8-auth-rules.md index 3571057e..8fe2654d 100644 --- a/content/rooms/fragments/v8-auth-rules.md +++ b/content/rooms/fragments/v8-auth-rules.md @@ -54,7 +54,7 @@ The rules are as follows: 4. If type is `m.room.member`: 1. If there is no `state_key` property, or no `membership` property in `content`, reject. - 2. {{< added-in this=true >}} + 2. {{< added-in v=8 >}} If `content` has a `join_authorised_via_users_server` property: 1. If the event is not validly signed by the homeserver of the user ID denoted by the key, reject. @@ -65,7 +65,7 @@ The rules are as follows: 3. If the `sender` is banned, reject. 4. If the `join_rule` is `invite` or `knock` then allow if membership state is `invite` or `join`. - 5. {{< added-in this=true >}} + 5. {{< added-in v=8 >}} If the `join_rule` is `restricted`: 1. If membership state is `join` or `invite`, allow. 2. If the `join_authorised_via_users_server` key in `content` diff --git a/content/rooms/v1.md b/content/rooms/v1.md index 04055e8c..1b950f11 100644 --- a/content/rooms/v1.md +++ b/content/rooms/v1.md @@ -2,6 +2,7 @@ title: Room Version 1 type: docs weight: 10 +version: 1 --- This room version is the first ever version for rooms, and contains the diff --git a/content/rooms/v10.md b/content/rooms/v10.md index 8ec4832a..ad56ce05 100644 --- a/content/rooms/v10.md +++ b/content/rooms/v10.md @@ -2,6 +2,7 @@ title: Room Version 10 type: docs weight: 100 +version: 10 --- This room version builds on [version 9](/rooms/v9) to enforce that power level @@ -140,7 +141,7 @@ The rules are as follows: 3. If the `sender` is banned, reject. 4. If the `join_rule` is `invite` or `knock` then allow if membership state is `invite` or `join`. - 5. {{< changed-in this="true" >}} + 5. {{< changed-in v=10 >}} If the `join_rule` is `restricted` or `knock_restricted`: 1. If membership state is `join` or `invite`, allow. 2. If the `join_authorised_via_users_server` key in `content` @@ -196,7 +197,7 @@ The rules are as follows: than the `sender`'s power level, allow. 3. Otherwise, reject. 7. If `membership` is `knock`: - 1. {{< changed-in this="true" >}} + 1. {{< changed-in v=10 >}} If the `join_rule` is anything other than `knock` or `knock_restricted`, reject. 2. If `sender` does not match `state_key`, reject. @@ -213,11 +214,11 @@ The rules are as follows: 8. If the event has a `state_key` that starts with an `@` and does not match the `sender`, reject. 9. If type is `m.room.power_levels`: - 1. {{< added-in this="true" >}} + 1. {{< added-in v=10 >}} If any of the properties `users_default`, `events_default`, `state_default`, `ban`, `redact`, `kick`, or `invite` in `content` are present and not an integer, reject. - 2. {{< added-in this="true" >}} + 2. {{< added-in v=10 >}} If either of the properties `events` or `notifications` in `content` are present and not an object with values that are integers, reject. diff --git a/content/rooms/v11.md b/content/rooms/v11.md index d21c76ba..5821eb06 100644 --- a/content/rooms/v11.md +++ b/content/rooms/v11.md @@ -2,6 +2,7 @@ title: Room Version 11 type: docs weight: 100 +version: 11 --- This room version builds on [version 10](/rooms/v10) while clarifying redaction @@ -11,7 +12,7 @@ rules. ### Redactions -{{< added-in this=true >}} The top-level `origin`, `membership`, and `prev_state` properties +{{< added-in v=11 >}} The top-level `origin`, `membership`, and `prev_state` properties are no longer protected from redaction. The [`m.room.create`](/client-server-api#mroomcreate) event now keeps the entire `content` property. The [`m.room.redaction`](/client-server-api#mroomredaction) event keeps the `redacts` property under `content`. The @@ -111,7 +112,7 @@ the [Handling redactions](#handling-redactions) section. The rules are as follows: -1. {{< changed-in this="true" >}} +1. {{< changed-in v=11 >}} If type is `m.room.create`: 1. If it has any `prev_events`, reject. 2. If the domain of the `room_id` does not match the domain of the @@ -141,7 +142,7 @@ The rules are as follows: 1. If the event is not validly signed by the homeserver of the user ID denoted by the key, reject. 3. If `membership` is `join`: - 1. {{< changed-in this="true" >}} + 1. {{< changed-in v=11 >}} If the only previous event is an `m.room.create` and the `state_key` is the sender, allow. 2. If the `sender` does not match `state_key`, reject. diff --git a/content/rooms/v2.md b/content/rooms/v2.md index 097f2554..f9980261 100644 --- a/content/rooms/v2.md +++ b/content/rooms/v2.md @@ -2,6 +2,7 @@ title: Room Version 2 type: docs weight: 20 +version: 2 --- This room version builds on [version 1](/rooms/v1) with an improved @@ -27,7 +28,7 @@ changing only the state resolution algorithm. ### State resolution -{{% added-in this=true %}} +{{% added-in v=2 %}} {{% rver-fragment name="v2-state-res" %}} diff --git a/content/rooms/v3.md b/content/rooms/v3.md index ad9ff698..bee12698 100644 --- a/content/rooms/v3.md +++ b/content/rooms/v3.md @@ -2,6 +2,7 @@ title: Room Version 3 type: docs weight: 30 +version: 3 --- This room version builds on [version 2](/rooms/v2) with an improved event @@ -39,8 +40,7 @@ all the remaining behaviour described by [room version 2](/rooms/v2). ### Handling redactions - -{{% rver-fragment name="v3-handling-redactions" withVersioning=true %}} +{{% rver-fragment name="v3-handling-redactions" %}} ### Event IDs @@ -54,7 +54,7 @@ the use of a dedicated event ID, servers are required to track the hashes on an event to determine its ID. {{% /boxes/rationale %}} -{{% added-in this=true %}} The event ID is the [reference +{{% added-in v=3 %}} The event ID is the [reference hash](/server-server-api#calculating-the-reference-hash-for-an-event) of the event encoded using [Unpadded Base64](/appendices#unpadded-base64), prefixed with `$`. A @@ -90,7 +90,7 @@ The complete structure of a event in a v3 room is shown below. ### Authorization rules {{% boxes/note %}} -{{< added-in this=true >}} `m.room.redaction` events are subject to auth rules in +{{< added-in v=3 >}} `m.room.redaction` events are subject to auth rules in the same way as any other event. In practice, that means they will normally be allowed by the auth rules, unless the `m.room.power_levels` event sets a power level requirement for `m.room.redaction`events via the `events` or `events_default` properties. In @@ -101,8 +101,7 @@ be performed. Receiving servers must perform additional checks, as described in the [Handling Redactions](#handling-redactions) section. {{% /boxes/note %}} - -{{< rver-fragment name="v3-auth-rules" withVersioning=true >}} +{{% rver-fragment name="v3-auth-rules" %}} ## Unchanged from v2 diff --git a/content/rooms/v4.md b/content/rooms/v4.md index c329f342..bd5651e1 100644 --- a/content/rooms/v4.md +++ b/content/rooms/v4.md @@ -2,6 +2,7 @@ title: Room Version 4 type: docs weight: 40 +version: 4 --- This room version builds on [version 3](/rooms/v3) using a different @@ -46,7 +47,7 @@ being interpreted differently by some reverse proxy software, and generally made administration harder. {{% /boxes/rationale %}} -{{% rver-fragment name="v4-event-ids" withVersioning="true" %}} +{{% rver-fragment name="v4-event-ids" %}} ## Unchanged from v3 diff --git a/content/rooms/v5.md b/content/rooms/v5.md index 25147e9e..665b0568 100644 --- a/content/rooms/v5.md +++ b/content/rooms/v5.md @@ -2,6 +2,7 @@ title: Room Version 5 type: docs weight: 50 +version: 5 --- This room version builds on [version 4](/rooms/v4) while enforcing signing diff --git a/content/rooms/v6.md b/content/rooms/v6.md index 9761ffdb..a3f4a682 100644 --- a/content/rooms/v6.md +++ b/content/rooms/v6.md @@ -2,6 +2,7 @@ title: Room Version 6 type: docs weight: 60 +version: 6 --- This room version builds on [version 5](/rooms/v5) while changing various @@ -15,7 +16,7 @@ which implement the redaction algorithm locally should refer to the ### Redactions -{{< added-in this=true >}} All significant meaning for `m.room.aliases` +{{< added-in v=6 >}} All significant meaning for `m.room.aliases` has been removed from the redaction algorithm. The remaining rules are the same as past room versions. @@ -40,11 +41,11 @@ in [room version 5](/rooms/v5). ### Authorization rules -{{< added-in this=true >}} Rule 4, which related specifically to events +{{< added-in v=6 >}} Rule 4, which related specifically to events of type `m.room.aliases`, is removed. `m.room.aliases` events must still pass authorization checks relating to state events. -{{< added-in this=true >}} Additionally, the authorization rules for events of +{{< added-in v=6 >}} Additionally, the authorization rules for events of type `m.room.power_levels` now include a `notifications` property under `content`. This updates rules 10.4 and 10.5 (now 9.4 and 9.5), which checked the `events` property. @@ -174,12 +175,12 @@ The rules are as follows: power level, reject. 2. If the new value is higher than the `sender`'s current power level, reject. - 4. {{< changed-in this="true" >}} + 4. {{< changed-in v=6 >}} For each entry being changed in, or removed from, the `events` or `notifications` properties: 1. If the current value is greater than the `sender`'s current power level, reject. - 5. {{< changed-in this="true" >}} + 5. {{< changed-in v=6 >}} For each entry being added to, or changed in, the `events` or `notifications` properties: 1. If the new value is greater than the `sender`'s current power diff --git a/content/rooms/v7.md b/content/rooms/v7.md index b5c0f28a..2af07c16 100644 --- a/content/rooms/v7.md +++ b/content/rooms/v7.md @@ -2,6 +2,7 @@ title: Room Version 7 type: docs weight: 70 +version: 7 --- This room version builds on [version 6](/rooms/v6) to introduce knocking @@ -32,7 +33,7 @@ as do the versions v6 is based upon. ### Authorization rules -{{< added-in this=true >}} For checks performed upon `m.room.member` events, a +{{< added-in v=7 >}} For checks performed upon `m.room.member` events, a new point for `membership=knock` is added. Events must be signed by the server denoted by the `sender` property. @@ -89,7 +90,7 @@ The rules are as follows: `state_key` is the creator, allow. 2. If the `sender` does not match `state_key`, reject. 3. If the `sender` is banned, reject. - 4. {{< changed-in this=true >}} + 4. {{< changed-in v=7 >}} If the `join_rule` is `invite` or `knock` then allow if membership state is `invite` or `join`. 5. If the `join_rule` is `public`, allow. @@ -121,7 +122,7 @@ The rules are as follows: the *invite level*, allow. 5. Otherwise, reject. 4. If `membership` is `leave`: - 1. {{< changed-in this=true >}} + 1. {{< changed-in v=7 >}} If the `sender` matches `state_key`, allow if and only if that user's current membership state is `invite`, `join`, or `knock`. @@ -141,7 +142,7 @@ The rules are as follows: the *ban level*, and the *target user*'s power level is less than the `sender`'s power level, allow. 3. Otherwise, reject. - 6. {{< added-in this=true >}} + 6. {{< added-in v=7 >}} If `membership` is `knock`: 1. If the `join_rule` is anything other than `knock`, reject. 2. If `sender` does not match `state_key`, reject. diff --git a/content/rooms/v8.md b/content/rooms/v8.md index ab4cd970..173073c5 100644 --- a/content/rooms/v8.md +++ b/content/rooms/v8.md @@ -2,6 +2,7 @@ title: Room Version 8 type: docs weight: 80 +version: 8 --- This room version builds on [version 7](/rooms/v7) to introduce a new @@ -27,7 +28,7 @@ Clients which implement the redaction algorithm locally should refer to the ### Redactions -{{% added-in this=true %}} `m.room.join_rules` events now keep `allow` in addition to other +{{% added-in v=8 %}} `m.room.join_rules` events now keep `allow` in addition to other keys in `content` when being redacted. {{% boxes/warning %}} @@ -83,11 +84,11 @@ room without invite. Otherwise, the room version inherits all properties of ### Authorization rules -{{< added-in this=true >}} For checks performed upon `m.room.member` events, new +{{< added-in v=8 >}} For checks performed upon `m.room.member` events, new points for handling `content.join_authorised_via_users_server` are added (Rule 4.2 and 4.3.5). -{{< rver-fragment name="v8-auth-rules" withVersioning=true >}} +{{% rver-fragment name="v8-auth-rules" %}} ### Redactions diff --git a/content/rooms/v9.md b/content/rooms/v9.md index cef269c6..5573b957 100644 --- a/content/rooms/v9.md +++ b/content/rooms/v9.md @@ -2,6 +2,7 @@ title: Room Version 9 type: docs weight: 90 +version: 9 --- This room version builds on [version 8](/rooms/v8) to add additional redaction @@ -17,7 +18,7 @@ Clients which implement the redaction algorithm locally should refer to the ### Redactions -{{< added-in this=true >}} [`m.room.member`](/client-server-api#mroommember) events +{{< added-in v=9 >}} [`m.room.member`](/client-server-api#mroommember) events now keep `join_authorised_via_users_server` in addition to other keys in `content` when being redacted. @@ -38,7 +39,7 @@ information. The full redaction algorithm follows. -{{% rver-fragment name="v9-redactions" withVersioning="true" %}} +{{% rver-fragment name="v9-redactions" %}} ## Server implementation components @@ -83,7 +84,7 @@ completeness. ### Authorization rules -{{< rver-fragment name="v8-auth-rules" >}} +{{% rver-fragment name="v8-auth-rules" %}} ### State resolution diff --git a/layouts/shortcodes/added-in.html b/layouts/shortcodes/added-in.html index 149be685..9f18809d 100644 --- a/layouts/shortcodes/added-in.html +++ b/layouts/shortcodes/added-in.html @@ -1,8 +1,9 @@ -{{ $ver := .Params.v }} -{{ $this := .Params.this }} +{{- $ver := .Params.v -}} -{{ if $this }} - [New in this version] -{{ else }} +{{- with page.Params.version -}} + {{- if eq $ver . -}} + [New in this version] + {{- end -}} +{{- else -}} [Added in v{{ $ver }}] -{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}} +{{- end -}} diff --git a/layouts/shortcodes/changed-in.html b/layouts/shortcodes/changed-in.html index 8da2559a..17c1c787 100644 --- a/layouts/shortcodes/changed-in.html +++ b/layouts/shortcodes/changed-in.html @@ -1,8 +1,9 @@ -{{ $ver := .Params.v }} -{{ $this := .Params.this }} +{{- $ver := .Params.v -}} -{{ if $this }} - [Changed in this version] -{{ else }} +{{- with page.Params.version -}} + {{- if eq $ver . -}} + [Changed in this version] + {{- end -}} +{{- else -}} [Changed in v{{ $ver }}] -{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}} +{{- end -}} diff --git a/layouts/shortcodes/rver-fragment.html b/layouts/shortcodes/rver-fragment.html index a10be8b5..894e6f0b 100644 --- a/layouts/shortcodes/rver-fragment.html +++ b/layouts/shortcodes/rver-fragment.html @@ -19,7 +19,7 @@ {{ with .Site.GetPage "rooms/fragments" }} {{ with .Resources.GetMatch (printf "%s%s" $name ".md") }} - {{ $content := .Content }} + {{ $content := .RenderShortcodes }} {{ if not $withVersioning }} {{ $content = (replace $content "[New in this version]" "") }} {{ $content = (replace $content "[Changed in this version]" "") }} diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 89c462f8..6ed1b23a 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -91,9 +91,6 @@ current version is `v1.1` then annotate your changes with `v1.2`. * `{{% added-in v="1.2" %}}` or `{{% changed-in v="1.2" %}}` within Markdown documents. * `x-addedInMatrixVersion` and `x-changedInMatrixVersion` within OpenAPI. -In rare cases, `this=true` can be used on the Markdown syntax to adjust the wording. -This is most commonly used in room version specifications. - **Tip**: If you're trying to inline the Markdown version and getting unexpected results, try replacing the `%` symbols with `<` and `>`, changing how Hugo renders the shortcode. From e2cb3a739af068c30600371058b164643ecdf6a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 20 Jun 2024 18:20:16 +0200 Subject: [PATCH 30/70] Fix ToC of spec proposals (#1885) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix ToC of spec proposals Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- changelogs/internal/newsfragments/1885.clarification | 1 + layouts/shortcodes/proposal-tables.html | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/internal/newsfragments/1885.clarification diff --git a/changelogs/internal/newsfragments/1885.clarification b/changelogs/internal/newsfragments/1885.clarification new file mode 100644 index 00000000..af7c653e --- /dev/null +++ b/changelogs/internal/newsfragments/1885.clarification @@ -0,0 +1 @@ +Generate the Table of Contents with Hugo rather than JavaScript. diff --git a/layouts/shortcodes/proposal-tables.html b/layouts/shortcodes/proposal-tables.html index f61f168b..06443909 100644 --- a/layouts/shortcodes/proposal-tables.html +++ b/layouts/shortcodes/proposal-tables.html @@ -33,7 +33,7 @@ {{ $states := .Site.Data.msc.proposals }} {{ range $states }} -

      {{ .title }}

      +### {{ .title }} {.proposal-table-title} {{ if .proposals }} From bed4ad589e0975f9d7f3f7010472afcb34a85e7e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 20 Jun 2024 10:04:19 -0600 Subject: [PATCH 31/70] Queue Matrix 1.11 --- config.toml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config.toml b/config.toml index 15003eee..b2856375 100644 --- a/config.toml +++ b/config.toml @@ -64,14 +64,14 @@ privacy_policy = "https://matrix.org/legal/privacy-notice" [params.version] # must be one of "unstable", "current", "historical" # this is used to decide whether to show a banner pointing to the current release -status = "unstable" +status = "stable" # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner. current_version_url = "https://spec.matrix.org/latest" # The following is used when status = "stable", and is displayed in various UI elements on a released version # of the spec. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created. -# major = "1" -# minor = "10" -# release_date = "March 22, 2024" +major = "1" +minor = "11" +release_date = "June 20, 2024" # User interface configuration [params.ui] From 1fc8f8856fe47849f90344cfa91601c984627acb Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 20 Jun 2024 10:20:50 -0600 Subject: [PATCH 32/70] Matrix 1.11 --- .../newsfragments/1791.clarification | 1 - .../newsfragments/1819.clarification | 1 - .../appendices/newsfragments/1823.deprecation | 1 - .../newsfragments/1850.clarification | 1 - .../newsfragments/1810.clarification | 1 - .../newsfragments/1644.clarification | 1 - .../client_server/newsfragments/1755.feature | 1 - .../client_server/newsfragments/1757.feature | 1 - .../newsfragments/1776.clarification | 1 - .../newsfragments/1808.deprecation | 1 - .../client_server/newsfragments/1812.feature | 1 - .../newsfragments/1813.clarification | 1 - .../client_server/newsfragments/1816.feature | 1 - .../newsfragments/1819.clarification | 1 - .../client_server/newsfragments/1828.feature | 1 - .../newsfragments/1829.clarification | 1 - .../newsfragments/1832.clarification | 1 - .../newsfragments/1839.clarification | 1 - .../newsfragments/1841.clarification | 1 - .../newsfragments/1843.clarification | 1 - .../newsfragments/1846.clarification | 1 - .../client_server/newsfragments/1847.feature | 1 - .../newsfragments/1850.clarification | 1 - .../newsfragments/1852.clarification | 1 - .../newsfragments/1853.clarification | 1 - .../newsfragments/1854.clarification | 1 - .../newsfragments/1858.deprecation | 1 - .../newsfragments/1858.feature.1 | 1 - .../newsfragments/1858.feature.2 | 1 - .../client_server/newsfragments/1858.new.1 | 1 - .../client_server/newsfragments/1858.new.2 | 1 - .../client_server/newsfragments/1858.new.3 | 1 - .../client_server/newsfragments/1858.new.4 | 1 - .../client_server/newsfragments/1858.new.5 | 1 - .../newsfragments/1860.clarification | 1 - .../newsfragments/1861.clarification | 1 - .../newsfragments/1862.clarification | 1 - .../newsfragments/1863.clarification | 1 - .../newsfragments/1872.clarification | 1 - .../newsfragments/1808.deprecation | 1 - .../internal/newsfragments/1759.clarification | 1 - .../internal/newsfragments/1765.clarification | 1 - .../internal/newsfragments/1769.clarification | 1 - .../internal/newsfragments/1770.clarification | 1 - .../internal/newsfragments/1771.clarification | 1 - .../internal/newsfragments/1772.clarification | 1 - .../internal/newsfragments/1773.clarification | 1 - .../internal/newsfragments/1775.clarification | 1 - .../internal/newsfragments/1781.clarification | 1 - .../internal/newsfragments/1786.clarification | 1 - .../internal/newsfragments/1787.clarification | 1 - .../internal/newsfragments/1788.clarification | 1 - .../internal/newsfragments/1789.clarification | 1 - .../internal/newsfragments/1793.clarification | 1 - .../internal/newsfragments/1794.clarification | 1 - .../internal/newsfragments/1796.clarification | 1 - .../internal/newsfragments/1797.clarification | 1 - .../internal/newsfragments/1798.clarification | 1 - .../internal/newsfragments/1799.clarification | 1 - .../internal/newsfragments/1800.clarification | 1 - .../internal/newsfragments/1801.clarification | 1 - .../internal/newsfragments/1802.clarification | 1 - .../internal/newsfragments/1803.clarification | 1 - .../internal/newsfragments/1804.clarification | 1 - .../internal/newsfragments/1805.clarification | 1 - .../internal/newsfragments/1806.clarification | 1 - .../internal/newsfragments/1809.clarification | 1 - .../internal/newsfragments/1813.clarification | 1 - .../internal/newsfragments/1814.clarification | 1 - .../internal/newsfragments/1822.clarification | 1 - .../internal/newsfragments/1831.clarification | 1 - .../internal/newsfragments/1849.clarification | 1 - .../internal/newsfragments/1851.clarification | 1 - .../internal/newsfragments/1856.clarification | 1 - .../internal/newsfragments/1865.clarification | 1 - .../internal/newsfragments/1876.clarification | 1 - .../internal/newsfragments/1880.clarification | 1 - .../internal/newsfragments/1881.clarification | 1 - .../internal/newsfragments/1882.clarification | 1 - .../internal/newsfragments/1885.clarification | 1 - .../newsfragments/1824.clarification | 1 - .../newsfragments/1827.clarification | 1 - .../newsfragments/1848.clarification | 1 - .../newsfragments/1883.clarification | 1 - .../newsfragments/1884.clarification | 1 - .../newsfragments/1813.clarification | 1 - .../newsfragments/1818.clarification | 1 - .../newsfragments/1834.clarification | 1 - .../newsfragments/1840.clarification | 1 - .../newsfragments/1844.clarification | 1 - .../newsfragments/1858.deprecation | 1 - .../server_server/newsfragments/1858.feature | 1 - .../server_server/newsfragments/1858.new.1 | 1 - .../server_server/newsfragments/1858.new.2 | 1 - .../server_server/newsfragments/1869.feature | 1 - .../newsfragments/1877.clarification | 1 - content/changelog/v1.11.md | 170 ++++++++++++++++++ 97 files changed, 170 insertions(+), 96 deletions(-) delete mode 100644 changelogs/appendices/newsfragments/1791.clarification delete mode 100644 changelogs/appendices/newsfragments/1819.clarification delete mode 100644 changelogs/appendices/newsfragments/1823.deprecation delete mode 100644 changelogs/appendices/newsfragments/1850.clarification delete mode 100644 changelogs/application_service/newsfragments/1810.clarification delete mode 100644 changelogs/client_server/newsfragments/1644.clarification delete mode 100644 changelogs/client_server/newsfragments/1755.feature delete mode 100644 changelogs/client_server/newsfragments/1757.feature delete mode 100644 changelogs/client_server/newsfragments/1776.clarification delete mode 100644 changelogs/client_server/newsfragments/1808.deprecation delete mode 100644 changelogs/client_server/newsfragments/1812.feature delete mode 100644 changelogs/client_server/newsfragments/1813.clarification delete mode 100644 changelogs/client_server/newsfragments/1816.feature delete mode 100644 changelogs/client_server/newsfragments/1819.clarification delete mode 100644 changelogs/client_server/newsfragments/1828.feature delete mode 100644 changelogs/client_server/newsfragments/1829.clarification delete mode 100644 changelogs/client_server/newsfragments/1832.clarification delete mode 100644 changelogs/client_server/newsfragments/1839.clarification delete mode 100644 changelogs/client_server/newsfragments/1841.clarification delete mode 100644 changelogs/client_server/newsfragments/1843.clarification delete mode 100644 changelogs/client_server/newsfragments/1846.clarification delete mode 100644 changelogs/client_server/newsfragments/1847.feature delete mode 100644 changelogs/client_server/newsfragments/1850.clarification delete mode 100644 changelogs/client_server/newsfragments/1852.clarification delete mode 100644 changelogs/client_server/newsfragments/1853.clarification delete mode 100644 changelogs/client_server/newsfragments/1854.clarification delete mode 100644 changelogs/client_server/newsfragments/1858.deprecation delete mode 100644 changelogs/client_server/newsfragments/1858.feature.1 delete mode 100644 changelogs/client_server/newsfragments/1858.feature.2 delete mode 100644 changelogs/client_server/newsfragments/1858.new.1 delete mode 100644 changelogs/client_server/newsfragments/1858.new.2 delete mode 100644 changelogs/client_server/newsfragments/1858.new.3 delete mode 100644 changelogs/client_server/newsfragments/1858.new.4 delete mode 100644 changelogs/client_server/newsfragments/1858.new.5 delete mode 100644 changelogs/client_server/newsfragments/1860.clarification delete mode 100644 changelogs/client_server/newsfragments/1861.clarification delete mode 100644 changelogs/client_server/newsfragments/1862.clarification delete mode 100644 changelogs/client_server/newsfragments/1863.clarification delete mode 100644 changelogs/client_server/newsfragments/1872.clarification delete mode 100644 changelogs/identity_service/newsfragments/1808.deprecation delete mode 100644 changelogs/internal/newsfragments/1759.clarification delete mode 100644 changelogs/internal/newsfragments/1765.clarification delete mode 100644 changelogs/internal/newsfragments/1769.clarification delete mode 100644 changelogs/internal/newsfragments/1770.clarification delete mode 100644 changelogs/internal/newsfragments/1771.clarification delete mode 100644 changelogs/internal/newsfragments/1772.clarification delete mode 100644 changelogs/internal/newsfragments/1773.clarification delete mode 100644 changelogs/internal/newsfragments/1775.clarification delete mode 100644 changelogs/internal/newsfragments/1781.clarification delete mode 100644 changelogs/internal/newsfragments/1786.clarification delete mode 100644 changelogs/internal/newsfragments/1787.clarification delete mode 100644 changelogs/internal/newsfragments/1788.clarification delete mode 100644 changelogs/internal/newsfragments/1789.clarification delete mode 100644 changelogs/internal/newsfragments/1793.clarification delete mode 100644 changelogs/internal/newsfragments/1794.clarification delete mode 100644 changelogs/internal/newsfragments/1796.clarification delete mode 100644 changelogs/internal/newsfragments/1797.clarification delete mode 100644 changelogs/internal/newsfragments/1798.clarification delete mode 100644 changelogs/internal/newsfragments/1799.clarification delete mode 100644 changelogs/internal/newsfragments/1800.clarification delete mode 100644 changelogs/internal/newsfragments/1801.clarification delete mode 100644 changelogs/internal/newsfragments/1802.clarification delete mode 100644 changelogs/internal/newsfragments/1803.clarification delete mode 100644 changelogs/internal/newsfragments/1804.clarification delete mode 100644 changelogs/internal/newsfragments/1805.clarification delete mode 100644 changelogs/internal/newsfragments/1806.clarification delete mode 100644 changelogs/internal/newsfragments/1809.clarification delete mode 100644 changelogs/internal/newsfragments/1813.clarification delete mode 100644 changelogs/internal/newsfragments/1814.clarification delete mode 100644 changelogs/internal/newsfragments/1822.clarification delete mode 100644 changelogs/internal/newsfragments/1831.clarification delete mode 100644 changelogs/internal/newsfragments/1849.clarification delete mode 100644 changelogs/internal/newsfragments/1851.clarification delete mode 100644 changelogs/internal/newsfragments/1856.clarification delete mode 100644 changelogs/internal/newsfragments/1865.clarification delete mode 100644 changelogs/internal/newsfragments/1876.clarification delete mode 100644 changelogs/internal/newsfragments/1880.clarification delete mode 100644 changelogs/internal/newsfragments/1881.clarification delete mode 100644 changelogs/internal/newsfragments/1882.clarification delete mode 100644 changelogs/internal/newsfragments/1885.clarification delete mode 100644 changelogs/room_versions/newsfragments/1824.clarification delete mode 100644 changelogs/room_versions/newsfragments/1827.clarification delete mode 100644 changelogs/room_versions/newsfragments/1848.clarification delete mode 100644 changelogs/room_versions/newsfragments/1883.clarification delete mode 100644 changelogs/room_versions/newsfragments/1884.clarification delete mode 100644 changelogs/server_server/newsfragments/1813.clarification delete mode 100644 changelogs/server_server/newsfragments/1818.clarification delete mode 100644 changelogs/server_server/newsfragments/1834.clarification delete mode 100644 changelogs/server_server/newsfragments/1840.clarification delete mode 100644 changelogs/server_server/newsfragments/1844.clarification delete mode 100644 changelogs/server_server/newsfragments/1858.deprecation delete mode 100644 changelogs/server_server/newsfragments/1858.feature delete mode 100644 changelogs/server_server/newsfragments/1858.new.1 delete mode 100644 changelogs/server_server/newsfragments/1858.new.2 delete mode 100644 changelogs/server_server/newsfragments/1869.feature delete mode 100644 changelogs/server_server/newsfragments/1877.clarification create mode 100644 content/changelog/v1.11.md diff --git a/changelogs/appendices/newsfragments/1791.clarification b/changelogs/appendices/newsfragments/1791.clarification deleted file mode 100644 index 22f59c5a..00000000 --- a/changelogs/appendices/newsfragments/1791.clarification +++ /dev/null @@ -1 +0,0 @@ -Define 'Opaque Identifier Grammar'. diff --git a/changelogs/appendices/newsfragments/1819.clarification b/changelogs/appendices/newsfragments/1819.clarification deleted file mode 100644 index dafeb10f..00000000 --- a/changelogs/appendices/newsfragments/1819.clarification +++ /dev/null @@ -1 +0,0 @@ -Define common cryptographic key representation. diff --git a/changelogs/appendices/newsfragments/1823.deprecation b/changelogs/appendices/newsfragments/1823.deprecation deleted file mode 100644 index 968bdfe4..00000000 --- a/changelogs/appendices/newsfragments/1823.deprecation +++ /dev/null @@ -1 +0,0 @@ -Deprecate linking to events in rooms identified by alias, as per [MSC4132](https://github.com/matrix-org/matrix-spec-proposals/pull/4132). \ No newline at end of file diff --git a/changelogs/appendices/newsfragments/1850.clarification b/changelogs/appendices/newsfragments/1850.clarification deleted file mode 100644 index cc200bdf..00000000 --- a/changelogs/appendices/newsfragments/1850.clarification +++ /dev/null @@ -1 +0,0 @@ -Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. diff --git a/changelogs/application_service/newsfragments/1810.clarification b/changelogs/application_service/newsfragments/1810.clarification deleted file mode 100644 index fd21375c..00000000 --- a/changelogs/application_service/newsfragments/1810.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that appservices should be notified of events relating to the `sender_localpart` user. diff --git a/changelogs/client_server/newsfragments/1644.clarification b/changelogs/client_server/newsfragments/1644.clarification deleted file mode 100644 index 279c4312..00000000 --- a/changelogs/client_server/newsfragments/1644.clarification +++ /dev/null @@ -1 +0,0 @@ -Add `/logout` and clarify the endpoints which do not take a JSON request body. diff --git a/changelogs/client_server/newsfragments/1755.feature b/changelogs/client_server/newsfragments/1755.feature deleted file mode 100644 index 65c5ba36..00000000 --- a/changelogs/client_server/newsfragments/1755.feature +++ /dev/null @@ -1 +0,0 @@ -Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291). diff --git a/changelogs/client_server/newsfragments/1757.feature b/changelogs/client_server/newsfragments/1757.feature deleted file mode 100644 index f65d48ba..00000000 --- a/changelogs/client_server/newsfragments/1757.feature +++ /dev/null @@ -1 +0,0 @@ -Add optional `animated` query string option to `GET /thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1776.clarification b/changelogs/client_server/newsfragments/1776.clarification deleted file mode 100644 index 4d2def20..00000000 --- a/changelogs/client_server/newsfragments/1776.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the `type` of the `POST /login` request must be one of the types returned by the `GET /login` response. diff --git a/changelogs/client_server/newsfragments/1808.deprecation b/changelogs/client_server/newsfragments/1808.deprecation deleted file mode 100644 index ae9f620d..00000000 --- a/changelogs/client_server/newsfragments/1808.deprecation +++ /dev/null @@ -1 +0,0 @@ -Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. diff --git a/changelogs/client_server/newsfragments/1812.feature b/changelogs/client_server/newsfragments/1812.feature deleted file mode 100644 index baa9aa7d..00000000 --- a/changelogs/client_server/newsfragments/1812.feature +++ /dev/null @@ -1 +0,0 @@ -Specify terms of services at registration, as per [MSC1692](https://github.com/matrix-org/matrix-spec-proposals/pull/1692). diff --git a/changelogs/client_server/newsfragments/1813.clarification b/changelogs/client_server/newsfragments/1813.clarification deleted file mode 100644 index fa76c2a1..00000000 --- a/changelogs/client_server/newsfragments/1813.clarification +++ /dev/null @@ -1 +0,0 @@ -Link to existing grammar where possible in types. diff --git a/changelogs/client_server/newsfragments/1816.feature b/changelogs/client_server/newsfragments/1816.feature deleted file mode 100644 index e1b97854..00000000 --- a/changelogs/client_server/newsfragments/1816.feature +++ /dev/null @@ -1 +0,0 @@ -Add support for mathematical messages, as per [MSC2191](https://github.com/matrix-org/matrix-spec-proposals/pull/2191). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1819.clarification b/changelogs/client_server/newsfragments/1819.clarification deleted file mode 100644 index f04c85d4..00000000 --- a/changelogs/client_server/newsfragments/1819.clarification +++ /dev/null @@ -1 +0,0 @@ -Rename "recovery key" to "backup decryption key". diff --git a/changelogs/client_server/newsfragments/1828.feature b/changelogs/client_server/newsfragments/1828.feature deleted file mode 100644 index 65d7420b..00000000 --- a/changelogs/client_server/newsfragments/1828.feature +++ /dev/null @@ -1 +0,0 @@ -Do not require UIA when first uploading cross-signing keys, as per [MSC3967](https://github.com/matrix-org/matrix-spec-proposals/pull/3967). diff --git a/changelogs/client_server/newsfragments/1829.clarification b/changelogs/client_server/newsfragments/1829.clarification deleted file mode 100644 index 68ce6207..00000000 --- a/changelogs/client_server/newsfragments/1829.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the device's Ed25519 signing key should be used in QR code verification (as opposed to the device's Curve25519 identity key). diff --git a/changelogs/client_server/newsfragments/1832.clarification b/changelogs/client_server/newsfragments/1832.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/1832.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1839.clarification b/changelogs/client_server/newsfragments/1839.clarification deleted file mode 100644 index eea109b1..00000000 --- a/changelogs/client_server/newsfragments/1839.clarification +++ /dev/null @@ -1 +0,0 @@ -Specify the encoding to be used when generating QR codes for device verification. diff --git a/changelogs/client_server/newsfragments/1841.clarification b/changelogs/client_server/newsfragments/1841.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/1841.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1843.clarification b/changelogs/client_server/newsfragments/1843.clarification deleted file mode 100644 index 7ccfe4a7..00000000 --- a/changelogs/client_server/newsfragments/1843.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that an access token is optional on the `POST /account/password` and `POST /account/deactivate` endpoints. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1846.clarification b/changelogs/client_server/newsfragments/1846.clarification deleted file mode 100644 index ee5387a8..00000000 --- a/changelogs/client_server/newsfragments/1846.clarification +++ /dev/null @@ -1 +0,0 @@ -Use RFC 2119 keywords more consistently. diff --git a/changelogs/client_server/newsfragments/1847.feature b/changelogs/client_server/newsfragments/1847.feature deleted file mode 100644 index ab3dbc34..00000000 --- a/changelogs/client_server/newsfragments/1847.feature +++ /dev/null @@ -1 +0,0 @@ -Add the new `unsigned.membership` property to events, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115). diff --git a/changelogs/client_server/newsfragments/1850.clarification b/changelogs/client_server/newsfragments/1850.clarification deleted file mode 100644 index cc200bdf..00000000 --- a/changelogs/client_server/newsfragments/1850.clarification +++ /dev/null @@ -1 +0,0 @@ -Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. diff --git a/changelogs/client_server/newsfragments/1852.clarification b/changelogs/client_server/newsfragments/1852.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/1852.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1853.clarification b/changelogs/client_server/newsfragments/1853.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/1853.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1854.clarification b/changelogs/client_server/newsfragments/1854.clarification deleted file mode 100644 index cb996bd6..00000000 --- a/changelogs/client_server/newsfragments/1854.clarification +++ /dev/null @@ -1 +0,0 @@ - Clarify that relations recursion should be capped at a certain depth. diff --git a/changelogs/client_server/newsfragments/1858.deprecation b/changelogs/client_server/newsfragments/1858.deprecation deleted file mode 100644 index 6e93dca5..00000000 --- a/changelogs/client_server/newsfragments/1858.deprecation +++ /dev/null @@ -1 +0,0 @@ -Use of the `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.feature.1 b/changelogs/client_server/newsfragments/1858.feature.1 deleted file mode 100644 index 02b9b51e..00000000 --- a/changelogs/client_server/newsfragments/1858.feature.1 +++ /dev/null @@ -1 +0,0 @@ -Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.feature.2 b/changelogs/client_server/newsfragments/1858.feature.2 deleted file mode 100644 index 63dfbb78..00000000 --- a/changelogs/client_server/newsfragments/1858.feature.2 +++ /dev/null @@ -1 +0,0 @@ -Some media endpoints are now consistently under `/_matrix/client/{version}/media/*` instead of `/_matrix/media/*`, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.1 b/changelogs/client_server/newsfragments/1858.new.1 deleted file mode 100644 index 9d02447f..00000000 --- a/changelogs/client_server/newsfragments/1858.new.1 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.2 b/changelogs/client_server/newsfragments/1858.new.2 deleted file mode 100644 index 07e7763a..00000000 --- a/changelogs/client_server/newsfragments/1858.new.2 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.3 b/changelogs/client_server/newsfragments/1858.new.3 deleted file mode 100644 index 49b67f04..00000000 --- a/changelogs/client_server/newsfragments/1858.new.3 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.4 b/changelogs/client_server/newsfragments/1858.new.4 deleted file mode 100644 index dda53b33..00000000 --- a/changelogs/client_server/newsfragments/1858.new.4 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.5 b/changelogs/client_server/newsfragments/1858.new.5 deleted file mode 100644 index 021b4023..00000000 --- a/changelogs/client_server/newsfragments/1858.new.5 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1860.clarification b/changelogs/client_server/newsfragments/1860.clarification deleted file mode 100644 index ca6e4117..00000000 --- a/changelogs/client_server/newsfragments/1860.clarification +++ /dev/null @@ -1 +0,0 @@ -Add missing secrets, third-party invites and room tagging modules to feature profiles table. diff --git a/changelogs/client_server/newsfragments/1861.clarification b/changelogs/client_server/newsfragments/1861.clarification deleted file mode 100644 index ee5387a8..00000000 --- a/changelogs/client_server/newsfragments/1861.clarification +++ /dev/null @@ -1 +0,0 @@ -Use RFC 2119 keywords more consistently. diff --git a/changelogs/client_server/newsfragments/1862.clarification b/changelogs/client_server/newsfragments/1862.clarification deleted file mode 100644 index 021b117c..00000000 --- a/changelogs/client_server/newsfragments/1862.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify when server name is used and link to the definition. diff --git a/changelogs/client_server/newsfragments/1863.clarification b/changelogs/client_server/newsfragments/1863.clarification deleted file mode 100644 index 688288cf..00000000 --- a/changelogs/client_server/newsfragments/1863.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify where keys reside when checking an `m.room.encrypted` event. diff --git a/changelogs/client_server/newsfragments/1872.clarification b/changelogs/client_server/newsfragments/1872.clarification deleted file mode 100644 index 4bcea39e..00000000 --- a/changelogs/client_server/newsfragments/1872.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that `/media/v3/upload/{serverName}/{mediaId}` requires authentication. diff --git a/changelogs/identity_service/newsfragments/1808.deprecation b/changelogs/identity_service/newsfragments/1808.deprecation deleted file mode 100644 index ae9f620d..00000000 --- a/changelogs/identity_service/newsfragments/1808.deprecation +++ /dev/null @@ -1 +0,0 @@ -Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. diff --git a/changelogs/internal/newsfragments/1759.clarification b/changelogs/internal/newsfragments/1759.clarification deleted file mode 100644 index a44c98df..00000000 --- a/changelogs/internal/newsfragments/1759.clarification +++ /dev/null @@ -1 +0,0 @@ -Update the spec release process and related documentation. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1765.clarification b/changelogs/internal/newsfragments/1765.clarification deleted file mode 100644 index c1b999bf..00000000 --- a/changelogs/internal/newsfragments/1765.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix npm release script for `@matrix-org/spec`. diff --git a/changelogs/internal/newsfragments/1769.clarification b/changelogs/internal/newsfragments/1769.clarification deleted file mode 100644 index c092b8f7..00000000 --- a/changelogs/internal/newsfragments/1769.clarification +++ /dev/null @@ -1 +0,0 @@ -Formatting fixes in `CONTRIBUTING.rst`. diff --git a/changelogs/internal/newsfragments/1770.clarification b/changelogs/internal/newsfragments/1770.clarification deleted file mode 100644 index 0eb57682..00000000 --- a/changelogs/internal/newsfragments/1770.clarification +++ /dev/null @@ -1 +0,0 @@ -Improve rendering on mobile devices. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1771.clarification b/changelogs/internal/newsfragments/1771.clarification deleted file mode 100644 index 0eb57682..00000000 --- a/changelogs/internal/newsfragments/1771.clarification +++ /dev/null @@ -1 +0,0 @@ -Improve rendering on mobile devices. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1772.clarification b/changelogs/internal/newsfragments/1772.clarification deleted file mode 100644 index b2aafa0d..00000000 --- a/changelogs/internal/newsfragments/1772.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the OpenAPI definition of the security schemes. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1773.clarification b/changelogs/internal/newsfragments/1773.clarification deleted file mode 100644 index 53d959d1..00000000 --- a/changelogs/internal/newsfragments/1773.clarification +++ /dev/null @@ -1 +0,0 @@ -Simplify uses of `resolve-refs` partial. diff --git a/changelogs/internal/newsfragments/1775.clarification b/changelogs/internal/newsfragments/1775.clarification deleted file mode 100644 index 649503a0..00000000 --- a/changelogs/internal/newsfragments/1775.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix Hugo warnings. diff --git a/changelogs/internal/newsfragments/1781.clarification b/changelogs/internal/newsfragments/1781.clarification deleted file mode 100644 index 8776d77b..00000000 --- a/changelogs/internal/newsfragments/1781.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix `github-labels.rst`. diff --git a/changelogs/internal/newsfragments/1786.clarification b/changelogs/internal/newsfragments/1786.clarification deleted file mode 100644 index c66e15e3..00000000 --- a/changelogs/internal/newsfragments/1786.clarification +++ /dev/null @@ -1 +0,0 @@ -Update dependencies. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1787.clarification b/changelogs/internal/newsfragments/1787.clarification deleted file mode 100644 index 5d2d1378..00000000 --- a/changelogs/internal/newsfragments/1787.clarification +++ /dev/null @@ -1 +0,0 @@ -Solve `allOf` recursively in OpenAPI and JSON Schemas. diff --git a/changelogs/internal/newsfragments/1788.clarification b/changelogs/internal/newsfragments/1788.clarification deleted file mode 100644 index 649503a0..00000000 --- a/changelogs/internal/newsfragments/1788.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix Hugo warnings. diff --git a/changelogs/internal/newsfragments/1789.clarification b/changelogs/internal/newsfragments/1789.clarification deleted file mode 100644 index f90c8934..00000000 --- a/changelogs/internal/newsfragments/1789.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix property type resolution in `render-object-table` partial. diff --git a/changelogs/internal/newsfragments/1793.clarification b/changelogs/internal/newsfragments/1793.clarification deleted file mode 100644 index bc5abca9..00000000 --- a/changelogs/internal/newsfragments/1793.clarification +++ /dev/null @@ -1 +0,0 @@ -Factor out common definition of `Tag` type. diff --git a/changelogs/internal/newsfragments/1794.clarification b/changelogs/internal/newsfragments/1794.clarification deleted file mode 100644 index 3c38016a..00000000 --- a/changelogs/internal/newsfragments/1794.clarification +++ /dev/null @@ -1 +0,0 @@ -Update the version of Hugo used to render the spec to v0.124.1. diff --git a/changelogs/internal/newsfragments/1796.clarification b/changelogs/internal/newsfragments/1796.clarification deleted file mode 100644 index 6a489a01..00000000 --- a/changelogs/internal/newsfragments/1796.clarification +++ /dev/null @@ -1 +0,0 @@ -Add support for pattern formats for `patternProperties`. diff --git a/changelogs/internal/newsfragments/1797.clarification b/changelogs/internal/newsfragments/1797.clarification deleted file mode 100644 index d98e89f0..00000000 --- a/changelogs/internal/newsfragments/1797.clarification +++ /dev/null @@ -1 +0,0 @@ -Clean up unnecessary `allOf`s in OpenAPI definitions. diff --git a/changelogs/internal/newsfragments/1798.clarification b/changelogs/internal/newsfragments/1798.clarification deleted file mode 100644 index 5bd28a93..00000000 --- a/changelogs/internal/newsfragments/1798.clarification +++ /dev/null @@ -1 +0,0 @@ -Show information about "Additional Properties" in object tables. diff --git a/changelogs/internal/newsfragments/1799.clarification b/changelogs/internal/newsfragments/1799.clarification deleted file mode 100644 index d47e0183..00000000 --- a/changelogs/internal/newsfragments/1799.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix anchors for schemas under `oneOf`. diff --git a/changelogs/internal/newsfragments/1800.clarification b/changelogs/internal/newsfragments/1800.clarification deleted file mode 100644 index 7dfac999..00000000 --- a/changelogs/internal/newsfragments/1800.clarification +++ /dev/null @@ -1 +0,0 @@ -Use reference to `OneTimeKeys` schema in OpenAPI definitions. diff --git a/changelogs/internal/newsfragments/1801.clarification b/changelogs/internal/newsfragments/1801.clarification deleted file mode 100644 index 6d01cfb7..00000000 --- a/changelogs/internal/newsfragments/1801.clarification +++ /dev/null @@ -1 +0,0 @@ -Do not use the `title` of objects containing only `additionalProperties` or `patternProperties`. diff --git a/changelogs/internal/newsfragments/1802.clarification b/changelogs/internal/newsfragments/1802.clarification deleted file mode 100644 index 09aebc5d..00000000 --- a/changelogs/internal/newsfragments/1802.clarification +++ /dev/null @@ -1 +0,0 @@ -Add anchors in `definition` shortcode. diff --git a/changelogs/internal/newsfragments/1803.clarification b/changelogs/internal/newsfragments/1803.clarification deleted file mode 100644 index c66e15e3..00000000 --- a/changelogs/internal/newsfragments/1803.clarification +++ /dev/null @@ -1 +0,0 @@ -Update dependencies. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1804.clarification b/changelogs/internal/newsfragments/1804.clarification deleted file mode 100644 index c66e15e3..00000000 --- a/changelogs/internal/newsfragments/1804.clarification +++ /dev/null @@ -1 +0,0 @@ -Update dependencies. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1805.clarification b/changelogs/internal/newsfragments/1805.clarification deleted file mode 100644 index c1b09b62..00000000 --- a/changelogs/internal/newsfragments/1805.clarification +++ /dev/null @@ -1 +0,0 @@ -Set python version for the Towncrier CI job. diff --git a/changelogs/internal/newsfragments/1806.clarification b/changelogs/internal/newsfragments/1806.clarification deleted file mode 100644 index 88b875bb..00000000 --- a/changelogs/internal/newsfragments/1806.clarification +++ /dev/null @@ -1 +0,0 @@ -Replace `set-output` with environment files in CI. diff --git a/changelogs/internal/newsfragments/1809.clarification b/changelogs/internal/newsfragments/1809.clarification deleted file mode 100644 index e1124a53..00000000 --- a/changelogs/internal/newsfragments/1809.clarification +++ /dev/null @@ -1 +0,0 @@ -Render response headers. diff --git a/changelogs/internal/newsfragments/1813.clarification b/changelogs/internal/newsfragments/1813.clarification deleted file mode 100644 index af643e2e..00000000 --- a/changelogs/internal/newsfragments/1813.clarification +++ /dev/null @@ -1 +0,0 @@ -Use `patternProperties` in more places with supported formats. diff --git a/changelogs/internal/newsfragments/1814.clarification b/changelogs/internal/newsfragments/1814.clarification deleted file mode 100644 index a540ea7e..00000000 --- a/changelogs/internal/newsfragments/1814.clarification +++ /dev/null @@ -1 +0,0 @@ -Add support for rendering string formats. diff --git a/changelogs/internal/newsfragments/1822.clarification b/changelogs/internal/newsfragments/1822.clarification deleted file mode 100644 index 034deb48..00000000 --- a/changelogs/internal/newsfragments/1822.clarification +++ /dev/null @@ -1 +0,0 @@ -Refactor the OpenAPI definitions of the content repository endpoints. diff --git a/changelogs/internal/newsfragments/1831.clarification b/changelogs/internal/newsfragments/1831.clarification deleted file mode 100644 index 8ce17713..00000000 --- a/changelogs/internal/newsfragments/1831.clarification +++ /dev/null @@ -1 +0,0 @@ -Clean up pull request template. diff --git a/changelogs/internal/newsfragments/1849.clarification b/changelogs/internal/newsfragments/1849.clarification deleted file mode 100644 index fc7c5d88..00000000 --- a/changelogs/internal/newsfragments/1849.clarification +++ /dev/null @@ -1 +0,0 @@ -Do not add empty arrays to examples. diff --git a/changelogs/internal/newsfragments/1851.clarification b/changelogs/internal/newsfragments/1851.clarification deleted file mode 100644 index af7c653e..00000000 --- a/changelogs/internal/newsfragments/1851.clarification +++ /dev/null @@ -1 +0,0 @@ -Generate the Table of Contents with Hugo rather than JavaScript. diff --git a/changelogs/internal/newsfragments/1856.clarification b/changelogs/internal/newsfragments/1856.clarification deleted file mode 100644 index 838b8af5..00000000 --- a/changelogs/internal/newsfragments/1856.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix syntax errors in the spec release issue template. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1865.clarification b/changelogs/internal/newsfragments/1865.clarification deleted file mode 100644 index f50be96f..00000000 --- a/changelogs/internal/newsfragments/1865.clarification +++ /dev/null @@ -1 +0,0 @@ -Use environment variables for Netlify build job. diff --git a/changelogs/internal/newsfragments/1876.clarification b/changelogs/internal/newsfragments/1876.clarification deleted file mode 100644 index 9f840914..00000000 --- a/changelogs/internal/newsfragments/1876.clarification +++ /dev/null @@ -1 +0,0 @@ -Render added/changed in info on request and response content types. diff --git a/changelogs/internal/newsfragments/1880.clarification b/changelogs/internal/newsfragments/1880.clarification deleted file mode 100644 index 56090e20..00000000 --- a/changelogs/internal/newsfragments/1880.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix validation errors in generated HTML. diff --git a/changelogs/internal/newsfragments/1881.clarification b/changelogs/internal/newsfragments/1881.clarification deleted file mode 100644 index d698545f..00000000 --- a/changelogs/internal/newsfragments/1881.clarification +++ /dev/null @@ -1 +0,0 @@ -Ensure most generated HTML IDs are unique. diff --git a/changelogs/internal/newsfragments/1882.clarification b/changelogs/internal/newsfragments/1882.clarification deleted file mode 100644 index 99c0ca05..00000000 --- a/changelogs/internal/newsfragments/1882.clarification +++ /dev/null @@ -1 +0,0 @@ -Allow to specify a prefix for generated HTML IDs of API endpoints. diff --git a/changelogs/internal/newsfragments/1885.clarification b/changelogs/internal/newsfragments/1885.clarification deleted file mode 100644 index af7c653e..00000000 --- a/changelogs/internal/newsfragments/1885.clarification +++ /dev/null @@ -1 +0,0 @@ -Generate the Table of Contents with Hugo rather than JavaScript. diff --git a/changelogs/room_versions/newsfragments/1824.clarification b/changelogs/room_versions/newsfragments/1824.clarification deleted file mode 100644 index 6f830830..00000000 --- a/changelogs/room_versions/newsfragments/1824.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that redaction events are still subject to all applicable auth rules. diff --git a/changelogs/room_versions/newsfragments/1827.clarification b/changelogs/room_versions/newsfragments/1827.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/room_versions/newsfragments/1827.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/room_versions/newsfragments/1848.clarification b/changelogs/room_versions/newsfragments/1848.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/room_versions/newsfragments/1848.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/room_versions/newsfragments/1883.clarification b/changelogs/room_versions/newsfragments/1883.clarification deleted file mode 100644 index 0676c664..00000000 --- a/changelogs/room_versions/newsfragments/1883.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the rendering of the event format for room versions 1 and 2. diff --git a/changelogs/room_versions/newsfragments/1884.clarification b/changelogs/room_versions/newsfragments/1884.clarification deleted file mode 100644 index af7c653e..00000000 --- a/changelogs/room_versions/newsfragments/1884.clarification +++ /dev/null @@ -1 +0,0 @@ -Generate the Table of Contents with Hugo rather than JavaScript. diff --git a/changelogs/server_server/newsfragments/1813.clarification b/changelogs/server_server/newsfragments/1813.clarification deleted file mode 100644 index fa76c2a1..00000000 --- a/changelogs/server_server/newsfragments/1813.clarification +++ /dev/null @@ -1 +0,0 @@ -Link to existing grammar where possible in types. diff --git a/changelogs/server_server/newsfragments/1818.clarification b/changelogs/server_server/newsfragments/1818.clarification deleted file mode 100644 index 8c50b6ac..00000000 --- a/changelogs/server_server/newsfragments/1818.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that whitespace around commas is allowed in the `X-Matrix` `Authorization` header value params list. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1834.clarification b/changelogs/server_server/newsfragments/1834.clarification deleted file mode 100644 index 80c2fa48..00000000 --- a/changelogs/server_server/newsfragments/1834.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server. diff --git a/changelogs/server_server/newsfragments/1840.clarification b/changelogs/server_server/newsfragments/1840.clarification deleted file mode 100644 index 80c2fa48..00000000 --- a/changelogs/server_server/newsfragments/1840.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server. diff --git a/changelogs/server_server/newsfragments/1844.clarification b/changelogs/server_server/newsfragments/1844.clarification deleted file mode 100644 index 81013eb6..00000000 --- a/changelogs/server_server/newsfragments/1844.clarification +++ /dev/null @@ -1 +0,0 @@ -Replace references to RFC 7235 and RFC 7230 that are obsoleted by RFC 9110. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.deprecation b/changelogs/server_server/newsfragments/1858.deprecation deleted file mode 100644 index fd3d2576..00000000 --- a/changelogs/server_server/newsfragments/1858.deprecation +++ /dev/null @@ -1 +0,0 @@ -Use of the Client-Server API `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.feature b/changelogs/server_server/newsfragments/1858.feature deleted file mode 100644 index 02b9b51e..00000000 --- a/changelogs/server_server/newsfragments/1858.feature +++ /dev/null @@ -1 +0,0 @@ -Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.new.1 b/changelogs/server_server/newsfragments/1858.new.1 deleted file mode 100644 index e50d5fd1..00000000 --- a/changelogs/server_server/newsfragments/1858.new.1 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/federation/v1/media/download/{mediaId}`](/server-server-api/#get_matrixfederationv1mediadownloadmediaid) \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.new.2 b/changelogs/server_server/newsfragments/1858.new.2 deleted file mode 100644 index 1da2a693..00000000 --- a/changelogs/server_server/newsfragments/1858.new.2 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/federation/v1/media/thumbnail/{mediaId}`](/server-server-api/#get_matrixfederationv1mediathumbnailmediaid) \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1869.feature b/changelogs/server_server/newsfragments/1869.feature deleted file mode 100644 index 02b9b51e..00000000 --- a/changelogs/server_server/newsfragments/1869.feature +++ /dev/null @@ -1 +0,0 @@ -Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1877.clarification b/changelogs/server_server/newsfragments/1877.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/server_server/newsfragments/1877.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/content/changelog/v1.11.md b/content/changelog/v1.11.md new file mode 100644 index 00000000..f3a60b55 --- /dev/null +++ b/content/changelog/v1.11.md @@ -0,0 +1,170 @@ +--- +date: 2024-06-20T10:20:43-06:00 +--- + + +## v1.11 + +
      + + +
      Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.11
      Release dateJune 20, 2024
      + + + +### Client-Server API + +**Deprecations** + +- Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. ([#1808](https://github.com/matrix-org/matrix-spec/issues/1808)) +- Use of the `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**New Endpoints** + +- [`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**Backwards Compatible Changes** + +- Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291). ([#1755](https://github.com/matrix-org/matrix-spec/issues/1755)) +- Add optional `animated` query string option to `GET /thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). ([#1757](https://github.com/matrix-org/matrix-spec/issues/1757)) +- Specify terms of services at registration, as per [MSC1692](https://github.com/matrix-org/matrix-spec-proposals/pull/1692). ([#1812](https://github.com/matrix-org/matrix-spec/issues/1812)) +- Add support for mathematical messages, as per [MSC2191](https://github.com/matrix-org/matrix-spec-proposals/pull/2191). ([#1816](https://github.com/matrix-org/matrix-spec/issues/1816)) +- Do not require UIA when first uploading cross-signing keys, as per [MSC3967](https://github.com/matrix-org/matrix-spec-proposals/pull/3967). ([#1828](https://github.com/matrix-org/matrix-spec/issues/1828)) +- Add the new `unsigned.membership` property to events, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115). ([#1847](https://github.com/matrix-org/matrix-spec/issues/1847)) +- Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- Some media endpoints are now consistently under `/_matrix/client/{version}/media/*` instead of `/_matrix/media/*`, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**Spec Clarifications** + +- Add `/logout` and clarify the endpoints which do not take a JSON request body. ([#1644](https://github.com/matrix-org/matrix-spec/issues/1644)) +- Clarify that the `type` of the `POST /login` request must be one of the types returned by the `GET /login` response. ([#1776](https://github.com/matrix-org/matrix-spec/issues/1776)) +- Link to existing grammar where possible in types. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813)) +- Rename "recovery key" to "backup decryption key". ([#1819](https://github.com/matrix-org/matrix-spec/issues/1819)) +- Clarify that the device's Ed25519 signing key should be used in QR code verification (as opposed to the device's Curve25519 identity key). ([#1829](https://github.com/matrix-org/matrix-spec/issues/1829)) +- Fix various typos throughout the specification. ([#1832](https://github.com/matrix-org/matrix-spec/issues/1832), [#1841](https://github.com/matrix-org/matrix-spec/issues/1841), [#1852](https://github.com/matrix-org/matrix-spec/issues/1852), [#1853](https://github.com/matrix-org/matrix-spec/issues/1853)) +- Specify the encoding to be used when generating QR codes for device verification. ([#1839](https://github.com/matrix-org/matrix-spec/issues/1839)) +- Clarify that an access token is optional on the `POST /account/password` and `POST /account/deactivate` endpoints. ([#1843](https://github.com/matrix-org/matrix-spec/issues/1843)) +- Use RFC 2119 keywords more consistently. ([#1846](https://github.com/matrix-org/matrix-spec/issues/1846), [#1861](https://github.com/matrix-org/matrix-spec/issues/1861)) +- Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. ([#1850](https://github.com/matrix-org/matrix-spec/issues/1850)) +- Clarify that relations recursion should be capped at a certain depth. ([#1854](https://github.com/matrix-org/matrix-spec/issues/1854)) +- Add missing secrets, third-party invites and room tagging modules to feature profiles table. ([#1860](https://github.com/matrix-org/matrix-spec/issues/1860)) +- Clarify when server name is used and link to the definition. ([#1862](https://github.com/matrix-org/matrix-spec/issues/1862)) +- Clarify where keys reside when checking an `m.room.encrypted` event. ([#1863](https://github.com/matrix-org/matrix-spec/issues/1863)) +- Clarify that `/media/v3/upload/{serverName}/{mediaId}` requires authentication. ([#1872](https://github.com/matrix-org/matrix-spec/issues/1872)) + + +### Server-Server API + +**Deprecations** + +- Use of the Client-Server API `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**New Endpoints** + +- [`GET /_matrix/federation/v1/media/download/{mediaId}`](/server-server-api/#get_matrixfederationv1mediadownloadmediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/federation/v1/media/thumbnail/{mediaId}`](/server-server-api/#get_matrixfederationv1mediathumbnailmediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**Backwards Compatible Changes** + +- Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858), [#1869](https://github.com/matrix-org/matrix-spec/issues/1869)) + +**Spec Clarifications** + +- Link to existing grammar where possible in types. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813)) +- Clarify that whitespace around commas is allowed in the `X-Matrix` `Authorization` header value params list. ([#1818](https://github.com/matrix-org/matrix-spec/issues/1818)) +- Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server. ([#1834](https://github.com/matrix-org/matrix-spec/issues/1834), [#1840](https://github.com/matrix-org/matrix-spec/issues/1840)) +- Replace references to RFC 7235 and RFC 7230 that are obsoleted by RFC 9110. ([#1844](https://github.com/matrix-org/matrix-spec/issues/1844)) +- Fix various typos throughout the specification. ([#1877](https://github.com/matrix-org/matrix-spec/issues/1877)) + + +### Application Service API + +**Spec Clarifications** + +- Clarify that appservices should be notified of events relating to the `sender_localpart` user. ([#1810](https://github.com/matrix-org/matrix-spec/issues/1810)) + + +### Identity Service API + +**Deprecations** + +- Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. ([#1808](https://github.com/matrix-org/matrix-spec/issues/1808)) + + +### Push Gateway API + +No significant changes. + + +### Room Versions + +**Spec Clarifications** + +- Clarify that redaction events are still subject to all applicable auth rules. ([#1824](https://github.com/matrix-org/matrix-spec/issues/1824)) +- Fix various typos throughout the specification. ([#1827](https://github.com/matrix-org/matrix-spec/issues/1827), [#1848](https://github.com/matrix-org/matrix-spec/issues/1848)) +- Fix the rendering of the event format for room versions 1 and 2. ([#1883](https://github.com/matrix-org/matrix-spec/issues/1883)) +- Generate the Table of Contents with Hugo rather than JavaScript. ([#1884](https://github.com/matrix-org/matrix-spec/issues/1884)) + + +### Appendices + +**Deprecations** + +- Deprecate linking to events in rooms identified by alias, as per [MSC4132](https://github.com/matrix-org/matrix-spec-proposals/pull/4132). ([#1823](https://github.com/matrix-org/matrix-spec/issues/1823)) + +**Spec Clarifications** + +- Define 'Opaque Identifier Grammar'. ([#1791](https://github.com/matrix-org/matrix-spec/issues/1791)) +- Define common cryptographic key representation. ([#1819](https://github.com/matrix-org/matrix-spec/issues/1819)) +- Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. ([#1850](https://github.com/matrix-org/matrix-spec/issues/1850)) + + +### Internal Changes/Tooling + +**Spec Clarifications** + +- Update the spec release process and related documentation. ([#1759](https://github.com/matrix-org/matrix-spec/issues/1759)) +- Fix npm release script for `@matrix-org/spec`. ([#1765](https://github.com/matrix-org/matrix-spec/issues/1765)) +- Formatting fixes in `CONTRIBUTING.rst`. ([#1769](https://github.com/matrix-org/matrix-spec/issues/1769)) +- Improve rendering on mobile devices. ([#1770](https://github.com/matrix-org/matrix-spec/issues/1770), [#1771](https://github.com/matrix-org/matrix-spec/issues/1771)) +- Fix the OpenAPI definition of the security schemes. ([#1772](https://github.com/matrix-org/matrix-spec/issues/1772)) +- Simplify uses of `resolve-refs` partial. ([#1773](https://github.com/matrix-org/matrix-spec/issues/1773)) +- Fix Hugo warnings. ([#1775](https://github.com/matrix-org/matrix-spec/issues/1775), [#1788](https://github.com/matrix-org/matrix-spec/issues/1788)) +- Fix `github-labels.rst`. ([#1781](https://github.com/matrix-org/matrix-spec/issues/1781)) +- Update dependencies. ([#1786](https://github.com/matrix-org/matrix-spec/issues/1786), [#1803](https://github.com/matrix-org/matrix-spec/issues/1803), [#1804](https://github.com/matrix-org/matrix-spec/issues/1804)) +- Solve `allOf` recursively in OpenAPI and JSON Schemas. ([#1787](https://github.com/matrix-org/matrix-spec/issues/1787)) +- Fix property type resolution in `render-object-table` partial. ([#1789](https://github.com/matrix-org/matrix-spec/issues/1789)) +- Factor out common definition of `Tag` type. ([#1793](https://github.com/matrix-org/matrix-spec/issues/1793)) +- Update the version of Hugo used to render the spec to v0.124.1. ([#1794](https://github.com/matrix-org/matrix-spec/issues/1794)) +- Add support for pattern formats for `patternProperties`. ([#1796](https://github.com/matrix-org/matrix-spec/issues/1796)) +- Clean up unnecessary `allOf`s in OpenAPI definitions. ([#1797](https://github.com/matrix-org/matrix-spec/issues/1797)) +- Show information about "Additional Properties" in object tables. ([#1798](https://github.com/matrix-org/matrix-spec/issues/1798)) +- Fix anchors for schemas under `oneOf`. ([#1799](https://github.com/matrix-org/matrix-spec/issues/1799)) +- Use reference to `OneTimeKeys` schema in OpenAPI definitions. ([#1800](https://github.com/matrix-org/matrix-spec/issues/1800)) +- Do not use the `title` of objects containing only `additionalProperties` or `patternProperties`. ([#1801](https://github.com/matrix-org/matrix-spec/issues/1801)) +- Add anchors in `definition` shortcode. ([#1802](https://github.com/matrix-org/matrix-spec/issues/1802)) +- Set python version for the Towncrier CI job. ([#1805](https://github.com/matrix-org/matrix-spec/issues/1805)) +- Replace `set-output` with environment files in CI. ([#1806](https://github.com/matrix-org/matrix-spec/issues/1806)) +- Render response headers. ([#1809](https://github.com/matrix-org/matrix-spec/issues/1809)) +- Use `patternProperties` in more places with supported formats. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813)) +- Add support for rendering string formats. ([#1814](https://github.com/matrix-org/matrix-spec/issues/1814)) +- Refactor the OpenAPI definitions of the content repository endpoints. ([#1822](https://github.com/matrix-org/matrix-spec/issues/1822)) +- Clean up pull request template. ([#1831](https://github.com/matrix-org/matrix-spec/issues/1831)) +- Do not add empty arrays to examples. ([#1849](https://github.com/matrix-org/matrix-spec/issues/1849)) +- Generate the Table of Contents with Hugo rather than JavaScript. ([#1851](https://github.com/matrix-org/matrix-spec/issues/1851), [#1885](https://github.com/matrix-org/matrix-spec/issues/1885)) +- Fix syntax errors in the spec release issue template. ([#1856](https://github.com/matrix-org/matrix-spec/issues/1856)) +- Use environment variables for Netlify build job. ([#1865](https://github.com/matrix-org/matrix-spec/issues/1865)) +- Render added/changed in info on request and response content types. ([#1876](https://github.com/matrix-org/matrix-spec/issues/1876)) +- Fix validation errors in generated HTML. ([#1880](https://github.com/matrix-org/matrix-spec/issues/1880)) +- Ensure most generated HTML IDs are unique. ([#1881](https://github.com/matrix-org/matrix-spec/issues/1881)) +- Allow to specify a prefix for generated HTML IDs of API endpoints. ([#1882](https://github.com/matrix-org/matrix-spec/issues/1882)) From 9f2891d95cc35401ec835436006ccde4cfb95ea5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 20 Jun 2024 10:25:12 -0600 Subject: [PATCH 33/70] Return to unstable --- config.toml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config.toml b/config.toml index b2856375..6b669a79 100644 --- a/config.toml +++ b/config.toml @@ -64,14 +64,14 @@ privacy_policy = "https://matrix.org/legal/privacy-notice" [params.version] # must be one of "unstable", "current", "historical" # this is used to decide whether to show a banner pointing to the current release -status = "stable" +status = "unstable" # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner. current_version_url = "https://spec.matrix.org/latest" # The following is used when status = "stable", and is displayed in various UI elements on a released version # of the spec. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created. -major = "1" -minor = "11" -release_date = "June 20, 2024" +# major = "1" +# minor = "11" +# release_date = "June 20, 2024" # User interface configuration [params.ui] From 7820771fddbcd6008313fb65cea88786cabfdc00 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 25 Jun 2024 16:40:21 +0200 Subject: [PATCH 34/70] Clarify that room avatars cannot be encrypted (#1871) Fixes: #562 Signed-off-by: Johannes Marbach --- .../newsfragments/1871.clarification | 1 + .../msgtype_infos/avatar_info.yaml | 28 +++++++++++++++++++ data/event-schemas/schema/m.room.avatar.yaml | 2 +- 3 files changed, 30 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1871.clarification create mode 100644 data/event-schemas/schema/core-event-schema/msgtype_infos/avatar_info.yaml diff --git a/changelogs/client_server/newsfragments/1871.clarification b/changelogs/client_server/newsfragments/1871.clarification new file mode 100644 index 00000000..fec9054e --- /dev/null +++ b/changelogs/client_server/newsfragments/1871.clarification @@ -0,0 +1 @@ +Clarify that room avatars cannot be encrypted. diff --git a/data/event-schemas/schema/core-event-schema/msgtype_infos/avatar_info.yaml b/data/event-schemas/schema/core-event-schema/msgtype_infos/avatar_info.yaml new file mode 100644 index 00000000..c21dfb48 --- /dev/null +++ b/data/event-schemas/schema/core-event-schema/msgtype_infos/avatar_info.yaml @@ -0,0 +1,28 @@ +description: Metadata about an avatar image. +properties: + h: + description: |- + The intended display height of the image in pixels. This may + differ from the intrinsic dimensions of the image file. + type: integer + w: + description: |- + The intended display width of the image in pixels. This may + differ from the intrinsic dimensions of the image file. + type: integer + mimetype: + description: The mimetype of the image, e.g. `image/jpeg`. + type: string + size: + description: Size of the image in bytes. + type: integer + thumbnail_url: + description: |- + The URL (typically [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris)) to a thumbnail of the image. + type: string + thumbnail_info: + allOf: + - $ref: thumbnail_info.yaml + description: Metadata about the image referred to in `thumbnail_url`. +title: AvatarInfo +type: object diff --git a/data/event-schemas/schema/m.room.avatar.yaml b/data/event-schemas/schema/m.room.avatar.yaml index a4777af4..5c6c7140 100644 --- a/data/event-schemas/schema/m.room.avatar.yaml +++ b/data/event-schemas/schema/m.room.avatar.yaml @@ -7,7 +7,7 @@ properties: properties: info: allOf: - - $ref: core-event-schema/msgtype_infos/image_info.yaml + - $ref: core-event-schema/msgtype_infos/avatar_info.yaml description: Metadata about the image referred to in `url`. url: description: |- From 7eda6ad2992da2e41e867c19af3f8c508f1b1ed6 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 25 Jun 2024 16:55:46 +0200 Subject: [PATCH 35/70] Improve recommendation for how to form transaction IDs (#1888) Fixes: #1706 Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/1888.clarification | 1 + content/client-server-api/_index.md | 7 ++++--- 2 files changed, 5 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1888.clarification diff --git a/changelogs/client_server/newsfragments/1888.clarification b/changelogs/client_server/newsfragments/1888.clarification new file mode 100644 index 00000000..7ede3094 --- /dev/null +++ b/changelogs/client_server/newsfragments/1888.clarification @@ -0,0 +1 @@ +Improve recommendation for how to form transaction IDs. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 8b40fe99..2acf7777 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -251,9 +251,10 @@ the request idempotent. The transaction ID should **only** be used for this purpose. -From the client perspective, after the request has finished, the `{txnId}` -value should be changed by for the next request (how is not specified; a -monotonically increasing integer is recommended). +After the request has finished, clients should change the `{txnId}` value for +the next request. How this is achieved, is left as an implementation detail. +It is recommended that clients use either version 4 UUIDs or a concatenation +of the current timestamp and a monotonically increasing integer. The homeserver should identify a request as a retransmission if the transaction ID is the same as a previous request, and the path of the From d7299b5a32236f6c21f9678f276d68a3d93b9581 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 26 Jun 2024 17:53:28 +0200 Subject: [PATCH 36/70] Rename and sort the modules in the feature profiles table for easier skimming (#1855) * Rename modules to match section titles. * Sort the table by requiredness, then alphabetically by module name. --- .../newsfragments/1855.clarification | 1 + content/client-server-api/_index.md | 58 +++++++++---------- 2 files changed, 30 insertions(+), 29 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1855.clarification diff --git a/changelogs/client_server/newsfragments/1855.clarification b/changelogs/client_server/newsfragments/1855.clarification new file mode 100644 index 00000000..7b178cf9 --- /dev/null +++ b/changelogs/client_server/newsfragments/1855.clarification @@ -0,0 +1 @@ +Rename and sort the modules in the feature profiles table for easier skimming. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 2acf7777..9558d536 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2727,45 +2727,45 @@ that profile. | Module / Profile | Web | Mobile | Desktop | CLI | Embedded | |------------------------------------------------------------|-----------|----------|----------|----------|----------| -| [Instant Messaging](#instant-messaging) | Required | Required | Required | Required | Optional | -| [Rich replies](#rich-replies) | Optional | Optional | Optional | Optional | Optional | +| [Content Repository](#content-repository) | Required | Required | Required | Optional | Optional | | [Direct Messaging](#direct-messaging) | Required | Required | Required | Required | Optional | -| [Mentions](#user-and-room-mentions) | Required | Required | Required | Optional | Optional | +| [Ignoring Users](#ignoring-users) | Required | Required | Required | Optional | Optional | +| [Instant Messaging](#instant-messaging) | Required | Required | Required | Required | Optional | | [Presence](#presence) | Required | Required | Required | Required | Optional | | [Push Notifications](#push-notifications) | Optional | Required | Optional | Optional | Optional | | [Receipts](#receipts) | Required | Required | Required | Required | Optional | -| [Fully read markers](#fully-read-markers) | Optional | Optional | Optional | Optional | Optional | -| [Typing Notifications](#typing-notifications) | Required | Required | Required | Required | Optional | -| [VoIP](#voice-over-ip) | Required | Required | Required | Optional | Optional | -| [Ignoring Users](#ignoring-users) | Required | Required | Required | Optional | Optional | -| [Reporting Content](#reporting-content) | Optional | Optional | Optional | Optional | Optional | -| [Content Repository](#content-repository) | Required | Required | Required | Optional | Optional | -| [Managing History Visibility](#room-history-visibility) | Required | Required | Required | Required | Optional | -| [Server Side Search](#server-side-search) | Optional | Optional | Optional | Optional | Optional | +| [Room History Visibility](#room-history-visibility) | Required | Required | Required | Required | Optional | | [Room Upgrades](#room-upgrades) | Required | Required | Required | Required | Optional | -| [Server Administration](#server-administration) | Optional | Optional | Optional | Optional | Optional | -| [Event Context](#event-context) | Optional | Optional | Optional | Optional | Optional | -| [Third-party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional | -| [Send-to-Device Messaging](#send-to-device-messaging) | Optional | Optional | Optional | Optional | Optional | +| [Third-party Invites](#third-party-invites) | Optional | Required | Optional | Optional | Optional | +| [Typing Notifications](#typing-notifications) | Required | Required | Required | Required | Optional | +| [User and Room Mentions](#user-and-room-mentions) | Required | Required | Required | Optional | Optional | +| [Voice over IP](#voice-over-ip) | Required | Required | Required | Optional | Optional | +| [Client Config](#client-config) | Optional | Optional | Optional | Optional | Optional | | [Device Management](#device-management) | Optional | Optional | Optional | Optional | Optional | | [End-to-End Encryption](#end-to-end-encryption) | Optional | Optional | Optional | Optional | Optional | -| [Guest Accounts](#guest-access) | Optional | Optional | Optional | Optional | Optional | -| [Room Previews](#room-previews) | Optional | Optional | Optional | Optional | Optional | -| [Client Config](#client-config) | Optional | Optional | Optional | Optional | Optional | -| [SSO Login](#sso-client-loginauthentication) | Optional | Optional | Optional | Optional | Optional | -| [OpenID](#openid) | Optional | Optional | Optional | Optional | Optional | -| [Stickers](#sticker-messages) | Optional | Optional | Optional | Optional | Optional | -| [Server ACLs](#server-access-control-lists-acls-for-rooms) | Optional | Optional | Optional | Optional | Optional | -| [Server Notices](#server-notices) | Optional | Optional | Optional | Optional | Optional | -| [Moderation policies](#moderation-policy-lists) | Optional | Optional | Optional | Optional | Optional | -| [Spaces](#spaces) | Optional | Optional | Optional | Optional | Optional | -| [Event Replacements](#event-replacements) | Optional | Optional | Optional | Optional | Optional | | [Event Annotations and reactions](#event-annotations-and-reactions) | Optional | Optional | Optional | Optional | Optional | -| [Threading](#threading) | Optional | Optional | Optional | Optional | Optional | +| [Event Context](#event-context) | Optional | Optional | Optional | Optional | Optional | +| [Event Replacements](#event-replacements) | Optional | Optional | Optional | Optional | Optional | +| [Fully read markers](#fully-read-markers) | Optional | Optional | Optional | Optional | Optional | +| [Guest Access](#guest-access) | Optional | Optional | Optional | Optional | Optional | +| [Moderation Policy Lists](#moderation-policy-lists) | Optional | Optional | Optional | Optional | Optional | +| [OpenID](#openid) | Optional | Optional | Optional | Optional | Optional | | [Reference Relations](#reference-relations) | Optional | Optional | Optional | Optional | Optional | -| [Secrets](#secrets) | Optional | Optional | Optional | Optional | Optional | -| [Third-party Invites](#third-party-invites) | Optional | Required | Optional | Optional | Optional | +| [Reporting Content](#reporting-content) | Optional | Optional | Optional | Optional | Optional | +| [Rich replies](#rich-replies) | Optional | Optional | Optional | Optional | Optional | +| [Room Previews](#room-previews) | Optional | Optional | Optional | Optional | Optional | | [Room Tagging](#room-tagging) | Optional | Optional | Optional | Optional | Optional | +| [SSO Client Login/Authentication](#sso-client-loginauthentication) | Optional | Optional | Optional | Optional | Optional | +| [Secrets](#secrets) | Optional | Optional | Optional | Optional | Optional | +| [Send-to-Device Messaging](#send-to-device-messaging) | Optional | Optional | Optional | Optional | Optional | +| [Server Access Control Lists (ACLs)](#server-access-control-lists-acls-for-rooms) | Optional | Optional | Optional | Optional | Optional | +| [Server Administration](#server-administration) | Optional | Optional | Optional | Optional | Optional | +| [Server Notices](#server-notices) | Optional | Optional | Optional | Optional | Optional | +| [Server Side Search](#server-side-search) | Optional | Optional | Optional | Optional | Optional | +| [Spaces](#spaces) | Optional | Optional | Optional | Optional | Optional | +| [Sticker Messages](#sticker-messages) | Optional | Optional | Optional | Optional | Optional | +| [Third-party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional | +| [Threading](#threading) | Optional | Optional | Optional | Optional | Optional | *Please see each module for more details on what clients need to implement.* From d528ff684b6cd625852f68fd287adc53ea952853 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 28 Jun 2024 14:14:32 +0200 Subject: [PATCH 37/70] Fix minor typos in third-party networks module (#1892) --- changelogs/client_server/newsfragments/1892.clarification | 1 + data/api/application-service/definitions/protocol.yaml | 8 ++++---- data/api/application-service/definitions/user.yaml | 2 +- data/api/client-server/third_party_lookup.yaml | 4 ++-- 4 files changed, 8 insertions(+), 7 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1892.clarification diff --git a/changelogs/client_server/newsfragments/1892.clarification b/changelogs/client_server/newsfragments/1892.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1892.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/data/api/application-service/definitions/protocol.yaml b/data/api/application-service/definitions/protocol.yaml index c442a1b1..ff6300db 100644 --- a/data/api/application-service/definitions/protocol.yaml +++ b/data/api/application-service/definitions/protocol.yaml @@ -42,9 +42,9 @@ properties: example: "mxc://example.org/aBcDeFgH" field_types: description: |- - The type definitions for the fields defined in the `user_fields` and - `location_fields`. Each entry in those arrays MUST have an entry here. The - `string` key for this object is field name itself. + The type definitions for the fields defined in `user_fields` and + `location_fields`. Each entry in those arrays MUST have an entry here. + The `string` key for this object is the field name itself. May be an empty object if no fields are defined. type: object @@ -60,7 +60,7 @@ properties: may apply additional validation or filtering. type: string placeholder: - description: An placeholder serving as a valid example of the field value. + description: A placeholder serving as a valid example of the field value. type: string required: ['regexp', 'placeholder'] example: { diff --git a/data/api/application-service/definitions/user.yaml b/data/api/application-service/definitions/user.yaml index 3178b56d..62cac033 100644 --- a/data/api/application-service/definitions/user.yaml +++ b/data/api/application-service/definitions/user.yaml @@ -15,7 +15,7 @@ # TODO: Change userid to user_id as a breaking change properties: userid: - description: A Matrix User ID represting a third-party user. + description: A Matrix User ID representing a third-party user. type: string example: "@_gitter_jim:matrix.org" protocol: diff --git a/data/api/client-server/third_party_lookup.yaml b/data/api/client-server/third_party_lookup.yaml index 1abcb771..97547a6f 100644 --- a/data/api/client-server/third_party_lookup.yaml +++ b/data/api/client-server/third_party_lookup.yaml @@ -158,7 +158,7 @@ paths: schema: $ref: ../application-service/definitions/user_batch.yaml "404": - description: The Matrix User ID was not found + description: The Matrix User ID was not found. content: application/json: schema: @@ -232,7 +232,7 @@ paths: schema: $ref: ../application-service/definitions/user_batch.yaml "404": - description: The Matrix User ID was not found + description: The Matrix User ID was not found. content: application/json: schema: From 7bbc6a0b38827fa401a2475d219ab25c9a5fbe29 Mon Sep 17 00:00:00 2001 From: Stuart Mumford Date: Tue, 2 Jul 2024 15:52:26 +0100 Subject: [PATCH 38/70] Fix markup syntax in v2 state res (#1896) Signed-off-by: Stuart Mumford --- changelogs/room_versions/newsfragments/1896.clarification.rst | 1 + content/rooms/fragments/v2-state-res.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/room_versions/newsfragments/1896.clarification.rst diff --git a/changelogs/room_versions/newsfragments/1896.clarification.rst b/changelogs/room_versions/newsfragments/1896.clarification.rst new file mode 100644 index 00000000..402a3711 --- /dev/null +++ b/changelogs/room_versions/newsfragments/1896.clarification.rst @@ -0,0 +1 @@ +Fix a formatting issue in v2 state res. diff --git a/content/rooms/fragments/v2-state-res.md b/content/rooms/fragments/v2-state-res.md index 731070a7..658f9e77 100644 --- a/content/rooms/fragments/v2-state-res.md +++ b/content/rooms/fragments/v2-state-res.md @@ -138,7 +138,7 @@ The *resolution* of a set of states is obtained as follows: 1. Select the set *X* of all *power events* that appear in the *full conflicted set*. For each such power event *P*, enlarge *X* by adding the events in the auth chain of *P* which also belong to the full - conflicted set. Sort $X$ into a list using the *reverse topological + conflicted set. Sort *X* into a list using the *reverse topological power ordering*. 2. Apply the *iterative auth checks algorithm*, starting from the *unconflicted state map*, to the list of events from the previous From 7d94efe136bb9516666a940ebef51b4b6180240c Mon Sep 17 00:00:00 2001 From: davidegirardi <16451191+davidegirardi@users.noreply.github.com> Date: Wed, 3 Jul 2024 16:00:01 +0200 Subject: [PATCH 39/70] Spell out secure secret storage and sharing (#1875) Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Co-authored-by: Travis Ralston --- changelogs/client_server/newsfragments/1875.clarification | 1 + content/client-server-api/modules/secrets.md | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1875.clarification diff --git a/changelogs/client_server/newsfragments/1875.clarification b/changelogs/client_server/newsfragments/1875.clarification new file mode 100644 index 00000000..4e627ea0 --- /dev/null +++ b/changelogs/client_server/newsfragments/1875.clarification @@ -0,0 +1 @@ +Document the acronyms and alternate names for the "Secrets" section. diff --git a/content/client-server-api/modules/secrets.md b/content/client-server-api/modules/secrets.md index 541ca877..3e586bc4 100644 --- a/content/client-server-api/modules/secrets.md +++ b/content/client-server-api/modules/secrets.md @@ -15,6 +15,9 @@ secret when storing, fetching, requesting, or sharing the secret. Secrets are plain strings; structured data can be stored by encoding it as a string. +The mechanism described in this section is known as "secure secret storage and +sharing", "SSSS", or "4S". + #### Storage When secrets are stored on the server, they are stored in the user's From e53e6ea8764b95f0bdb738549fca6f9f3f901298 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 5 Jul 2024 12:54:42 +0200 Subject: [PATCH 40/70] Fix callback function for fallback login (#1899) --- changelogs/client_server/newsfragments/1899.clarification | 1 + content/client-server-api/_index.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1899.clarification diff --git a/changelogs/client_server/newsfragments/1899.clarification b/changelogs/client_server/newsfragments/1899.clarification new file mode 100644 index 00000000..6edeff05 --- /dev/null +++ b/changelogs/client_server/newsfragments/1899.clarification @@ -0,0 +1 @@ +Clarify that the fallback login page calls `window.matrixLogin.onLogin` instead of `window.onLogin`. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 9558d536..be9a2384 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1401,7 +1401,7 @@ fallback login API: This returns an HTML and JavaScript page which can perform the entire login process. The page will attempt to call the JavaScript function -`window.onLogin` when login has been successfully completed. +`window.matrixLogin.onLogin` when login has been successfully completed. {{% added-in v="1.1" %}} Non-credential parameters valid for the `/login` endpoint can be provided as query string parameters here. These are to be From 5abc31111f28ec8b25cd9d834c0d7889aa2c61e1 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 8 Jul 2024 13:51:27 +0200 Subject: [PATCH 41/70] Clarify arguments of window.matrixLogin.onLogin (#1905) --- changelogs/client_server/newsfragments/1905.clarification | 1 + content/client-server-api/_index.md | 5 ++++- 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1905.clarification diff --git a/changelogs/client_server/newsfragments/1905.clarification b/changelogs/client_server/newsfragments/1905.clarification new file mode 100644 index 00000000..341391db --- /dev/null +++ b/changelogs/client_server/newsfragments/1905.clarification @@ -0,0 +1 @@ +Clarify that `window.matrixLogin.onLogin` is called with the response body of `POST /_matrix/client/v3/login`. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index be9a2384..a9c813c4 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1401,7 +1401,10 @@ fallback login API: This returns an HTML and JavaScript page which can perform the entire login process. The page will attempt to call the JavaScript function -`window.matrixLogin.onLogin` when login has been successfully completed. +`window.matrixLogin.onLogin(response)` when login has been successfully +completed. The argument, `response`, is the JSON response body of +[`POST /_matrix/client/v3/login`](#post_matrixclientv3login) parsed +into a JavaScript object. {{% added-in v="1.1" %}} Non-credential parameters valid for the `/login` endpoint can be provided as query string parameters here. These are to be From 2261c03bcdefa375a23425d79711af6e456a3426 Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Tue, 9 Jul 2024 19:36:55 +0300 Subject: [PATCH 42/70] Clarify "real name" in contributor requirements (#1886) This updates the sign-off requirements to match what most other matrix-org and element-hq repos already have. The change was first made in synapse: https://github.com/matrix-org/synapse/pull/3467 Signed-off-by: Tulir Asokan --- CONTRIBUTING.rst | 12 ++++++++---- changelogs/internal/newsfragments/1886.clarification | 1 + 2 files changed, 9 insertions(+), 4 deletions(-) create mode 100644 changelogs/internal/newsfragments/1886.clarification diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index f93b44f4..a1228769 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -163,10 +163,14 @@ include the line in your commit or pull request comment:: Signed-off-by: Your Name -...using your real name; unfortunately pseudonyms and anonymous contributions -can't be accepted. Git makes this trivial - just use the -s flag when you do -``git commit``, having first set ``user.name`` and ``user.email`` git configs -(which you should have done anyway :) +We accept contributions under a legally identifiable name, such as +your name on government documentation or common-law names (names +claimed by legitimate usage or repute). Unfortunately, we cannot +accept anonymous contributions at this time. + +Git allows you to add this signoff automatically when using the ``-s`` +flag to ``git commit``, which uses the name and email set in your +``user.name`` and ``user.email`` git configs. Private sign off ~~~~~~~~~~~~~~~~ diff --git a/changelogs/internal/newsfragments/1886.clarification b/changelogs/internal/newsfragments/1886.clarification new file mode 100644 index 00000000..4a21158c --- /dev/null +++ b/changelogs/internal/newsfragments/1886.clarification @@ -0,0 +1 @@ +Clarified "real name" in contributor requirements to match other matrix-org projects. From e4589bbc8a0e30187e7519e60b97e5867d8706ee Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 10 Jul 2024 03:35:57 +0200 Subject: [PATCH 43/70] Clarify that dont_notify and coalesce MUST be gracefully ignored (#1890) --- .../client_server/newsfragments/1890.clarification | 1 + content/client-server-api/modules/push.md | 10 ++++++---- 2 files changed, 7 insertions(+), 4 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1890.clarification diff --git a/changelogs/client_server/newsfragments/1890.clarification b/changelogs/client_server/newsfragments/1890.clarification new file mode 100644 index 00000000..1e97a8e5 --- /dev/null +++ b/changelogs/client_server/newsfragments/1890.clarification @@ -0,0 +1 @@ +Clarify that the deprecated `dont_notify` and `coalesce` push rule actions MUST be ignored, not rejected. diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 2d828a01..0b8e132e 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -184,11 +184,13 @@ they are represented as a dictionary with a key equal to their name and other keys as their parameters, e.g. `{ "set_tweak": "sound", "value": "default" }`. -{{% boxes/note %}} +###### Historical Actions + Older versions of the Matrix specification included the `dont_notify` and -`coalesce` actions. These should both be considered no-ops (ignored, not -rejected) if received from a client. -{{% /boxes/note %}} +`coalesce` actions. Clients and homeservers MUST ignore these actions, for +instance, by stripping them from actions arrays they encounter. This means, +for example, that a rule with `["dont_notify"]` actions MUST be equivalent +to a rule with an empty actions array. ##### Conditions From b1349dd06ff477e45dc4fa4559d25e95d7f9b534 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 10 Jul 2024 05:44:26 +0200 Subject: [PATCH 44/70] Remove the deprecated name attribute on HTML anchor elements (#1870) * Remove the deprecated name attribute on HTML anchor elements Fixes: #1790 Signed-off-by: Johannes Marbach * Add changelog * Update content/client-server-api/modules/instant_messaging.md Co-authored-by: Travis Ralston * Update content/client-server-api/modules/instant_messaging.md Co-authored-by: Travis Ralston * Update changelogs/client_server/newsfragments/1870.deprecation * Rename 1870.deprecation to 1870.removal --------- Signed-off-by: Johannes Marbach Co-authored-by: Travis Ralston Co-authored-by: Hubert Chathi --- changelogs/client_server/newsfragments/1870.removal | 1 + content/client-server-api/modules/instant_messaging.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1870.removal diff --git a/changelogs/client_server/newsfragments/1870.removal b/changelogs/client_server/newsfragments/1870.removal new file mode 100644 index 00000000..e7eddce8 --- /dev/null +++ b/changelogs/client_server/newsfragments/1870.removal @@ -0,0 +1 @@ +Remove the deprecated name attribute on HTML anchor elements as per [MSC4159](https://github.com/matrix-org/matrix-spec-proposals/pull/4159). diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index e35a1cdf..de388e9e 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -74,7 +74,7 @@ the tag. | Tag | Permitted Attributes | |--------|--------------------------------------------------------------------------------------------------------------------------------------------| | `span` | `data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see [spoiler messages](#spoiler-messages)), `data-mx-maths` (see [mathematical messages](#mathematical-messages)) | -| `a` | `name`, `target`, `href` (provided the value is not relative and has a scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`) | +| `a` | `target`, `href` (provided the value is not relative and has a scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`) | | `img` | `width`, `height`, `alt`, `title`, `src` (provided it is a [Matrix Content (`mxc://`) URI](#matrix-content-mxc-uris)) | | `ol` | `start` | | `code` | `class` (only classes which start with `language-` for syntax highlighting) | From 40d5e48716c410b29c49ebd2e0c9ef1b9b57ca5f Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 10 Jul 2024 18:13:37 +0200 Subject: [PATCH 45/70] Add missing references in capabilities table (#1897) * Add missing references in capabilities table Fixes: #1548 Signed-off-by: Johannes Marbach * Add changelog --------- Signed-off-by: Johannes Marbach --- .../newsfragments/1897.clarification | 1 + data/api/client-server/capabilities.yaml | 31 +++++++++++++------ 2 files changed, 23 insertions(+), 9 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1897.clarification diff --git a/changelogs/client_server/newsfragments/1897.clarification b/changelogs/client_server/newsfragments/1897.clarification new file mode 100644 index 00000000..7bc903ba --- /dev/null +++ b/changelogs/client_server/newsfragments/1897.clarification @@ -0,0 +1 @@ +Add missing references to `m.set_displayname`, `m.set_avatar_url` and `m.3pid_changes` in capabilities table. diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml index 99f07962..fc5b47e2 100644 --- a/data/api/client-server/capabilities.yaml +++ b/data/api/client-server/capabilities.yaml @@ -46,16 +46,8 @@ paths: type: object properties: m.change_password: - type: object + $ref: '#/components/schemas/booleanCapability' description: Capability to indicate if the user can change their password. - title: ChangePasswordCapability - properties: - enabled: - type: boolean - description: True if the user can change their password, false otherwise. - example: false - required: - - enabled m.room_versions: type: object description: The room versions the server supports. @@ -78,6 +70,16 @@ paths: required: - default - available + m.set_displayname: + $ref: '#/components/schemas/booleanCapability' + description: Capability to indicate if the user can change their display name. + m.set_avatar_url: + $ref: '#/components/schemas/booleanCapability' + description: Capability to indicate if the user can change their avatar. + m.3pid_changes: + $ref: '#/components/schemas/booleanCapability' + description: Capability to indicate if the user can change 3PID associations + on their account. examples: response: value: { @@ -125,3 +127,14 @@ components: $ref: definitions/security.yaml#/accessTokenQuery accessTokenBearer: $ref: definitions/security.yaml#/accessTokenBearer + schemas: + booleanCapability: + type: object + title: BooleanCapability + properties: + enabled: + type: boolean + description: True if the user can perform the action, false otherwise. + example: false + required: + - enabled From cbe8092d8a629d3fbb5ce82fc071ef8dabfbeb86 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 15 Jul 2024 15:38:57 +0200 Subject: [PATCH 46/70] Spec for MSC2867 (Marking rooms as unread) (#1895) Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- .../client_server/newsfragments/1895.feature | 1 + content/client-server-api/_index.md | 2 +- .../client-server-api/modules/read_markers.md | 50 +++++++++++++++++-- .../examples/m.marked_unread.yaml | 7 +++ .../event-schemas/schema/m.marked_unread.yaml | 25 ++++++++++ 5 files changed, 80 insertions(+), 5 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1895.feature create mode 100644 data/event-schemas/examples/m.marked_unread.yaml create mode 100644 data/event-schemas/schema/m.marked_unread.yaml diff --git a/changelogs/client_server/newsfragments/1895.feature b/changelogs/client_server/newsfragments/1895.feature new file mode 100644 index 00000000..5e806a7f --- /dev/null +++ b/changelogs/client_server/newsfragments/1895.feature @@ -0,0 +1 @@ +Add support for marking rooms as unread as per [MSC2867](https://github.com/matrix-org/matrix-spec-proposals/pull/2867). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index a9c813c4..7689ff13 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2749,7 +2749,7 @@ that profile. | [Event Annotations and reactions](#event-annotations-and-reactions) | Optional | Optional | Optional | Optional | Optional | | [Event Context](#event-context) | Optional | Optional | Optional | Optional | Optional | | [Event Replacements](#event-replacements) | Optional | Optional | Optional | Optional | Optional | -| [Fully read markers](#fully-read-markers) | Optional | Optional | Optional | Optional | Optional | +| [Read and Unread Markers](#read-and-unread-markers) | Optional | Optional | Optional | Optional | Optional | | [Guest Access](#guest-access) | Optional | Optional | Optional | Optional | Optional | | [Moderation Policy Lists](#moderation-policy-lists) | Optional | Optional | Optional | Optional | Optional | | [OpenID](#openid) | Optional | Optional | Optional | Optional | Optional | diff --git a/content/client-server-api/modules/read_markers.md b/content/client-server-api/modules/read_markers.md index aa0baf47..55e73dd5 100644 --- a/content/client-server-api/modules/read_markers.md +++ b/content/client-server-api/modules/read_markers.md @@ -1,5 +1,6 @@ +### Read and unread markers -### Fully read markers +#### Fully read markers The history for a given room may be split into three sections: messages the user has read (or indicated they aren't interested in them), @@ -8,7 +9,7 @@ user hasn't seen yet. The "fully read marker" (also known as a "read marker") marks the last event of the first section, whereas the user's read receipt marks the last event of the second section. -#### Events +##### Events The user's fully read marker is kept as an event in the room's [account data](#client-config). The event may be read to determine the user's @@ -22,7 +23,7 @@ should be considered to be the user's read receipt location. {{% event event="m.fully_read" %}} -#### Client behaviour +##### Client behaviour The client cannot update fully read markers by directly modifying the `m.fully_read` account data event. Instead, the client must make use of @@ -41,7 +42,7 @@ might wish to save an extra HTTP call. Providing `m.read` and/or {{% http-api spec="client-server" api="read_markers" %}} -#### Server behaviour +##### Server behaviour The server MUST prevent clients from setting `m.fully_read` directly in room account data. The server must additionally ensure that it treats @@ -53,3 +54,44 @@ Upon updating the `m.fully_read` event due to a request to `/read_markers`, the server MUST send the updated account data event through to the client via the event stream (eg: `/sync`), provided any applicable filters are also satisfied. + +#### Unread markers + +Clients may use "unread markers" to allow users to label rooms for later +attention irrespective of [read receipts](#receipts) or +[fully read markers](#fully-read-markers). + +##### Events + +The user's unread marker in a room is kept under an `m.marked_unread` +event in the room's [account data](#client-config). The event may be read +to determine the user's current unread marker state in the room. Just +like other account data events, the event will be pushed down the event +stream when updated. + +{{% event event="m.marked_unread" %}} + +##### Client behaviour + +Clients MUST update unread markers by directly modifying the `m.marked_unread` +room account data event. When marking a room as unread, clients SHOULD NOT change +the `m.fully_read` marker, so that the user's read position in the room is +retained. + +When the `unread` field is `true`, clients SHOULD visually annotate the room +to indicate that it is unread. Exactly how this is achieved is left as an +implementation detail. It is RECOMMENDED that clients use a treatment similar +to how they represent rooms with unread notifications. + +Clients SHOULD reset the unread marker by setting `unread` to `false` when +opening a room to display its timeline. + +Clients that offer functionality to mark a room as _read_ by sending a read +receipt for the last event, SHOULD reset the unread marker simultaneously. + +If the `m.marked_unread` event does not exist on the user's account data, +clients MUST behave as if `unread` was `false`. + +##### Server behaviour + +Servers have no additional requirements placed on them by this submodule. diff --git a/data/event-schemas/examples/m.marked_unread.yaml b/data/event-schemas/examples/m.marked_unread.yaml new file mode 100644 index 00000000..b9937196 --- /dev/null +++ b/data/event-schemas/examples/m.marked_unread.yaml @@ -0,0 +1,7 @@ +{ + "$ref": "core/event.json", + "type": "m.marked_unread", + "content": { + "unread": true + } +} diff --git a/data/event-schemas/schema/m.marked_unread.yaml b/data/event-schemas/schema/m.marked_unread.yaml new file mode 100644 index 00000000..56b3ba62 --- /dev/null +++ b/data/event-schemas/schema/m.marked_unread.yaml @@ -0,0 +1,25 @@ +{ + "type": "object", + "title": "Unread Marker Event", + "description": "The current state of the user's unread marker in a room. This event appears in the user's room account data for the room the marker is applicable for.", + "allOf": [{ + "$ref": "core-event-schema/event.yaml" + }], + "properties": { + "content": { + "type": "object", + "properties": { + "unread": { + "type": "boolean", + "description": "Whether the room is marked unread or not." + } + }, + "required": ["unread"] + }, + "type": { + "type": "string", + "enum": ["m.marked_unread"] + } + }, + "required": ["type", "content"] +} From c8eb7f552678b7522ad5f65fb0b3651b68e3f82f Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 17 Jul 2024 00:15:44 +0200 Subject: [PATCH 47/70] Document the removal changelog category (#1907) * Document the removal changelog category Signed-off-by: Johannes Marbach * Add changelog --------- Signed-off-by: Johannes Marbach --- CONTRIBUTING.rst | 2 ++ changelogs/internal/newsfragments/1907.clarification | 1 + 2 files changed, 3 insertions(+) create mode 100644 changelogs/internal/newsfragments/1907.clarification diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index a1228769..def7ced2 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -99,6 +99,8 @@ the ``newsfragments`` directory. The ``type`` can be one of the following: * ``deprecation`` - Used when deprecating something. +* ``removal`` - Used when removing something that was unused or previously deprecated. + All news fragments must have a brief summary explaining the change in the contents of the file. The summary must end in a full stop to be in line with the style guide and formatting must be done using Markdown. diff --git a/changelogs/internal/newsfragments/1907.clarification b/changelogs/internal/newsfragments/1907.clarification new file mode 100644 index 00000000..9185f533 --- /dev/null +++ b/changelogs/internal/newsfragments/1907.clarification @@ -0,0 +1 @@ +Document the `removal` changelog category. From 149d5d2a959de088f9b3f13c329b0c8ecc17a14c Mon Sep 17 00:00:00 2001 From: Matthias Ahouansou Date: Wed, 17 Jul 2024 14:26:28 +0000 Subject: [PATCH 48/70] remove confusing description of restricted rooms with no valid conditions (#1903) --- changelogs/client_server/newsfragments/1903.clarification | 1 + content/client-server-api/_index.md | 3 --- 2 files changed, 1 insertion(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1903.clarification diff --git a/changelogs/client_server/newsfragments/1903.clarification b/changelogs/client_server/newsfragments/1903.clarification new file mode 100644 index 00000000..3ec46ef2 --- /dev/null +++ b/changelogs/client_server/newsfragments/1903.clarification @@ -0,0 +1 @@ +Remove confusing description of restricted rooms with no valid conditions. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 7689ff13..ba013735 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2574,9 +2574,6 @@ join is happening over federation, the remote server will check the conditions before accepting the join. See the [Server-Server Spec](/server-server-api/#restricted-rooms) for more information. -If the room is `restricted` but no valid conditions are presented then the -room is effectively invite only. - The user does not need to maintain the conditions in order to stay a member of the room: the conditions are only checked/evaluated during the join process. From d9c447e194180df5efa75ab25803d317d7df5f7f Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 19 Jul 2024 12:13:10 +0200 Subject: [PATCH 49/70] Document m.get_login_token capability (#1908) --- .../newsfragments/1908.clarification | 1 + content/client-server-api/_index.md | 21 +++++++++++++++++++ data/api/client-server/capabilities.yaml | 4 ++++ data/api/client-server/login_token.yaml | 6 +++--- 4 files changed, 29 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1908.clarification diff --git a/changelogs/client_server/newsfragments/1908.clarification b/changelogs/client_server/newsfragments/1908.clarification new file mode 100644 index 00000000..d9dc2e8c --- /dev/null +++ b/changelogs/client_server/newsfragments/1908.clarification @@ -0,0 +1 @@ +Document the `m.get_login_token` capability as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index ba013735..1a6f1c6e 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1654,6 +1654,27 @@ An example of the capability API's response for this capability is: } ``` +### `m.get_login_token` capability + +This capability has a single flag, `enabled`, to denote whether the user +is able to use [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) +to generate single-use, time-limited tokens to log unauthenticated clients +into their account. + +When not listed, clients SHOULD assume the user is unable to generate tokens. + +An example of the capability API's response for this capability is: + +```json +{ + "capabilities": { + "m.get_login_token": { + "enabled": false + } + } +} +``` + ## Filtering Filters can be created on the server and can be passed as a parameter to diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml index fc5b47e2..3ae26b22 100644 --- a/data/api/client-server/capabilities.yaml +++ b/data/api/client-server/capabilities.yaml @@ -80,6 +80,10 @@ paths: $ref: '#/components/schemas/booleanCapability' description: Capability to indicate if the user can change 3PID associations on their account. + m.get_login_token: + $ref: '#/components/schemas/booleanCapability' + description: Capability to indicate if the user can generate tokens to log further + clients into their account. examples: response: value: { diff --git a/data/api/client-server/login_token.yaml b/data/api/client-server/login_token.yaml index 19fa350e..f14e1a0a 100644 --- a/data/api/client-server/login_token.yaml +++ b/data/api/client-server/login_token.yaml @@ -33,7 +33,7 @@ paths: Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes this feature if the server is not offering it. Authenticated clients can check for support on - a per-user basis with the `m.get_login_token` [capability](/client-server-api/#capabilities-negotiation), + a per-user basis with the [`m.get_login_token`](/client-server-api/#mget_login_token-capability) capability, while unauthenticated clients can detect server support by looking for an `m.login.token` login flow with `get_login_token: true` on [`GET /login`](/client-server-api/#post_matrixclientv3login). @@ -98,8 +98,8 @@ paths: The request was malformed, or the user does not have an ability to generate tokens for their devices, as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). - Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token` - [capability](/client-server-api/#capabilities-negotiation). + Clients should verify whether the user has an ability to call this endpoint with the + [`m.get_login_token`](/client-server-api/#mget_login_token-capability) capability. content: application/json: schema: From 2017515ca96c82feb1c4b84a56d31c9c896363c0 Mon Sep 17 00:00:00 2001 From: Josh Simmons Date: Thu, 25 Jul 2024 16:41:12 -0700 Subject: [PATCH 50/70] update DCO, no legal name needed (#1914) * update DCO, no legal name needed * add a changelog entry, if needed * add necessary fullstop for style guide --------- Co-authored-by: Josh Simmons --- CONTRIBUTING.rst | 19 +------------------ .../internal/newsfragments/1914.clarification | 1 + 2 files changed, 2 insertions(+), 18 deletions(-) create mode 100644 changelogs/internal/newsfragments/1914.clarification diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index def7ced2..eb3c30f6 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -165,23 +165,6 @@ include the line in your commit or pull request comment:: Signed-off-by: Your Name -We accept contributions under a legally identifiable name, such as -your name on government documentation or common-law names (names -claimed by legitimate usage or repute). Unfortunately, we cannot -accept anonymous contributions at this time. - Git allows you to add this signoff automatically when using the ``-s`` flag to ``git commit``, which uses the name and email set in your -``user.name`` and ``user.email`` git configs. - -Private sign off -~~~~~~~~~~~~~~~~ - -If you would like to provide your legal name privately to the Matrix.org -Foundation (instead of in a public commit or comment), you can do so by emailing -your legal name and a link to the pull request to dco@matrix.org. It helps to -include "sign off" or similar in the subject line. You will then be instructed -further. - -Once private sign off is complete, doing so for future contributions will not -be required. +``user.name`` and ``user.email`` git configs. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1914.clarification b/changelogs/internal/newsfragments/1914.clarification new file mode 100644 index 00000000..bbf1f102 --- /dev/null +++ b/changelogs/internal/newsfragments/1914.clarification @@ -0,0 +1 @@ +The Matrix.org Foundation no longer requires "real" or "legally identifiable" names in order to contribute to projects. From 5d91b628c9482bbea96155f77813d0e3f29b8a55 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 30 Jul 2024 19:37:29 +0200 Subject: [PATCH 51/70] Don't mention that `GET /_matrix/client/v3/profile/{userId}` can return additional properties because this is true for almost every endpoint (#1910) Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/1910.clarification | 1 + data/api/client-server/profile.yaml | 3 +-- 2 files changed, 2 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1910.clarification diff --git a/changelogs/client_server/newsfragments/1910.clarification b/changelogs/client_server/newsfragments/1910.clarification new file mode 100644 index 00000000..3664eaf6 --- /dev/null +++ b/changelogs/client_server/newsfragments/1910.clarification @@ -0,0 +1 @@ +Don't mention that `GET /_matrix/client/v3/profile/{userId}` can return additional properties because this is true for almost every endpoint. diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index e00bdd96..1a55084c 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -195,8 +195,7 @@ paths: description: |- Get the combined profile information for this user. This API may be used to fetch the user's own profile information or other users; either - locally or on remote homeservers. This API may return keys which are not - limited to `displayname` or `avatar_url`. + locally or on remote homeservers. operationId: getUserProfile parameters: - in: path From 9bac118aec7a95740610147013753b3de687bd1a Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 30 Jul 2024 19:37:49 +0200 Subject: [PATCH 52/70] Clarify that the `User identifier` object in `POST /_matrix/client/v3/login` contains additional properties that depend on the identification type (#1909) Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/1909.clarification | 1 + data/api/client-server/definitions/user_identifier.yaml | 7 +++++-- 2 files changed, 6 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1909.clarification diff --git a/changelogs/client_server/newsfragments/1909.clarification b/changelogs/client_server/newsfragments/1909.clarification new file mode 100644 index 00000000..da6575cd --- /dev/null +++ b/changelogs/client_server/newsfragments/1909.clarification @@ -0,0 +1 @@ +The `User identifier` object in `POST /_matrix/client/v3/login` contains additional properties that depend on the identification type. diff --git a/data/api/client-server/definitions/user_identifier.yaml b/data/api/client-server/definitions/user_identifier.yaml index 7e6eca9c..add848fd 100644 --- a/data/api/client-server/definitions/user_identifier.yaml +++ b/data/api/client-server/definitions/user_identifier.yaml @@ -18,7 +18,10 @@ type: object properties: type: type: string - description: The type of identification. See [Identifier types](/client-server-api/#identifier-types) for supported values and additional property descriptions. + description: |- + The type of identification. See [Identifier types](/client-server-api/#identifier-types) + for supported values and additional property descriptions. required: - type -additionalProperties: true +additionalProperties: + description: Keys dependent on the identification type. From 56914b72efa9c830391a23ed1c3ccfc407da9063 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 1 Aug 2024 10:33:41 -0400 Subject: [PATCH 53/70] Remove references to device-specific push rules. (#1842) Device-specific push rules have never been implemented and aren't properly specified. --- .../client_server/newsfragments/1842.removal | 1 + .../definitions/push_ruleset.yaml | 187 ++++++++++++ data/api/client-server/pushrules.yaml | 274 ++---------------- 3 files changed, 211 insertions(+), 251 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1842.removal diff --git a/changelogs/client_server/newsfragments/1842.removal b/changelogs/client_server/newsfragments/1842.removal new file mode 100644 index 00000000..cd9124c9 --- /dev/null +++ b/changelogs/client_server/newsfragments/1842.removal @@ -0,0 +1 @@ +Remove references to device-specific push rules. diff --git a/data/api/client-server/definitions/push_ruleset.yaml b/data/api/client-server/definitions/push_ruleset.yaml index bbd07f7c..0a2148e0 100644 --- a/data/api/client-server/definitions/push_ruleset.yaml +++ b/data/api/client-server/definitions/push_ruleset.yaml @@ -33,3 +33,190 @@ properties: $ref: push_rule.yaml type: array type: object +example: { + "content": [ + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ], + "default": true, + "enabled": true, + "pattern": "alice", + "rule_id": ".m.rule.contains_user_name" + } + ], + "override": [ + { + "actions": [], + "conditions": [], + "default": true, + "enabled": false, + "rule_id": ".m.rule.master" + }, + { + "actions": [], + "conditions": [ + { + "key": "content.msgtype", + "kind": "event_match", + "pattern": "m.notice" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.suppress_notices" + } + ], + "room": [], + "sender": [], + "underride": [ + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "ring" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.call.invite" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.call" + }, + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ], + "conditions": [ + { + "kind": "contains_display_name" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.contains_display_name" + }, + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "kind": "room_member_count", + "is": "2" + }, + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.message" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.room_one_to_one" + }, + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + }, + { + "key": "content.membership", + "kind": "event_match", + "pattern": "invite" + }, + { + "key": "state_key", + "kind": "event_match", + "pattern": "@alice:example.com" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.invite_for_me" + }, + { + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.member_event" + }, + { + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.message" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.message" + } + ] +} diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml index d85e3d85..fd56f46e 100644 --- a/data/api/client-server/pushrules.yaml +++ b/data/api/client-server/pushrules.yaml @@ -20,10 +20,8 @@ paths: get: summary: Retrieve all push rulesets. description: |- - Retrieve all push rulesets for this user. Clients can "drill-down" on - the rulesets by suffixing a `scope` to this path e.g. - `/pushrules/global/`. This will return a subset of this data under the - specified key e.g. the `global` key. + Retrieve all push rulesets for this user. Currently the only push ruleset + defined is `global`. operationId: getPushRules security: - accessTokenQuery: [] @@ -44,200 +42,27 @@ paths: title: Ruleset allOf: - $ref: definitions/push_ruleset.yaml - examples: - response: - value: { - "global": { - "content": [ - { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight" - } - ], - "default": true, - "enabled": true, - "pattern": "alice", - "rule_id": ".m.rule.contains_user_name" - } - ], - "override": [ - { - "actions": [], - "conditions": [], - "default": true, - "enabled": false, - "rule_id": ".m.rule.master" - }, - { - "actions": [], - "conditions": [ - { - "key": "content.msgtype", - "kind": "event_match", - "pattern": "m.notice" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.suppress_notices" - } - ], - "room": [], - "sender": [], - "underride": [ - { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "ring" - }, - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.call.invite" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.call" - }, - { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight" - } - ], - "conditions": [ - { - "kind": "contains_display_name" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.contains_display_name" - }, - { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "kind": "room_member_count", - "is": "2" - }, - { - "kind": "event_match", - "key": "type", - "pattern": "m.room.message" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.room_one_to_one" - }, - { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.room.member" - }, - { - "key": "content.membership", - "kind": "event_match", - "pattern": "invite" - }, - { - "key": "state_key", - "kind": "event_match", - "pattern": "@alice:example.com" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.invite_for_me" - }, - { - "actions": [ - "notify", - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.room.member" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.member_event" - }, - { - "actions": [ - "notify", - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.room.message" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.message" - } - ] - } - } tags: - Push notifications - "/pushrules/{scope}/{kind}/{ruleId}": + /pushrules/global/: + get: + summary: Retrieve all push rules. + description: |- + Retrieve all push rules for this user. + operationId: getPushRulesGlobal + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + responses: + "200": + description: All the push rules for this user. + content: + application/json: + schema: + $ref: definitions/push_ruleset.yaml + tags: + - Push notifications + "/pushrules/global/{kind}/{ruleId}": get: summary: Retrieve a push rule. description: Retrieve a single specified push rule. @@ -246,13 +71,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: "`global` to specify global rules." - example: global - schema: - type: string - in: path name: kind required: true @@ -318,13 +136,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: "`global` to specify global rules." - example: global - schema: - type: string - in: path name: kind required: true @@ -395,13 +206,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: "`global` to specify global rules." - example: global - schema: - type: string - in: path name: kind required: true @@ -523,7 +327,7 @@ paths: $ref: definitions/errors/rate_limited.yaml tags: - Push notifications - "/pushrules/{scope}/{kind}/{ruleId}/enabled": + "/pushrules/global/{kind}/{ruleId}/enabled": get: summary: Get whether a push rule is enabled description: This endpoint gets whether the specified push rule is enabled. @@ -532,15 +336,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: |- - Either `global` or `device/` to specify global - rules or device rules for the given `profile_tag`. - example: global - schema: - type: string - in: path name: kind required: true @@ -604,13 +399,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: "`global` to specify global rules." - example: global - schema: - type: string - in: path name: kind required: true @@ -674,7 +462,7 @@ paths: } tags: - Push notifications - "/pushrules/{scope}/{kind}/{ruleId}/actions": + "/pushrules/global/{kind}/{ruleId}/actions": get: summary: The actions for a push rule description: This endpoint get the actions for the specified push rule. @@ -683,15 +471,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: |- - Either `global` or `device/` to specify global - rules or device rules for the given `profile_tag`. - example: global - schema: - type: string - in: path name: kind required: true @@ -764,13 +543,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: "`global` to specify global rules." - example: global - schema: - type: string - in: path name: kind required: true From c2fd278da025b3c75ef00a079632a3e9c48faa30 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 12 Aug 2024 11:53:18 +0200 Subject: [PATCH 54/70] Additional .well-known keys don't have to be objects (#1920) --- changelogs/client_server/newsfragments/1920.clarification | 1 + data/api/client-server/definitions/wellknown/full.yaml | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1920.clarification diff --git a/changelogs/client_server/newsfragments/1920.clarification b/changelogs/client_server/newsfragments/1920.clarification new file mode 100644 index 00000000..007bba3d --- /dev/null +++ b/changelogs/client_server/newsfragments/1920.clarification @@ -0,0 +1 @@ +Additional properties in `.well-known/matrix/client` don't have to be objects. diff --git a/data/api/client-server/definitions/wellknown/full.yaml b/data/api/client-server/definitions/wellknown/full.yaml index 8d8f4038..eaa9294a 100644 --- a/data/api/client-server/definitions/wellknown/full.yaml +++ b/data/api/client-server/definitions/wellknown/full.yaml @@ -22,7 +22,6 @@ properties: "m.identity_server": $ref: "identity_server.yaml" additionalProperties: - type: object description: Application-dependent keys using Java package naming convention. required: - m.homeserver From f9c4aeeea41b57f74b93b9d6009ed593043320b1 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 12 Aug 2024 13:01:54 +0200 Subject: [PATCH 55/70] Remove leftover origin field from unsigned PDU example (#1918) --- changelogs/server_server/newsfragments/1918.clarification | 1 + data/api/server-server/examples/unsigned_pdu_base.json | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/1918.clarification diff --git a/changelogs/server_server/newsfragments/1918.clarification b/changelogs/server_server/newsfragments/1918.clarification new file mode 100644 index 00000000..ff9274d4 --- /dev/null +++ b/changelogs/server_server/newsfragments/1918.clarification @@ -0,0 +1 @@ +Remove `origin` field from PDU example because it doesn't exist in the schema anymore. diff --git a/data/api/server-server/examples/unsigned_pdu_base.json b/data/api/server-server/examples/unsigned_pdu_base.json index 4826ccef..079ee1ea 100644 --- a/data/api/server-server/examples/unsigned_pdu_base.json +++ b/data/api/server-server/examples/unsigned_pdu_base.json @@ -1,7 +1,6 @@ { "room_id": "!UcYsUzyxTGDxLBEvLy:example.org", "sender": "@alice:example.com", - "origin": "example.com", "origin_server_ts": 1404838188000, "depth": 12, "auth_events": [ From c6d974975ea44caea11360cb0181c6c9bad645a7 Mon Sep 17 00:00:00 2001 From: Kim Brose <2803622+HarHarLinks@users.noreply.github.com> Date: Wed, 14 Aug 2024 18:36:33 +0200 Subject: [PATCH 56/70] Improve wording of the unauthenticated media deprecation box (#1916) --- changelogs/client_server/newsfragments/1916.clarification | 1 + content/client-server-api/modules/content_repo.md | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1916.clarification diff --git a/changelogs/client_server/newsfragments/1916.clarification b/changelogs/client_server/newsfragments/1916.clarification new file mode 100644 index 00000000..936c3111 --- /dev/null +++ b/changelogs/client_server/newsfragments/1916.clarification @@ -0,0 +1 @@ +Improve wording of the unauthenticated media deprecation box. Contributed by @HarHarLinks. diff --git a/content/client-server-api/modules/content_repo.md b/content/client-server-api/modules/content_repo.md index a0138156..c9ac06d7 100644 --- a/content/client-server-api/modules/content_repo.md +++ b/content/client-server-api/modules/content_repo.md @@ -49,8 +49,9 @@ mxc:/// Clients can access the content repository using the following endpoints. {{% boxes/added-in-paragraph %}} -{{< changed-in v="1.11" >}} Clients SHOULD NOT use the deprecated media endpoints -described below. Instead, they SHOULD use the new endpoints which require authentication. +{{< changed-in v="1.11" >}} A number of endpoints under the /_matrix/media hierarchy +have been deprecated and replaced with new endpoints which require authentication. +The deprecated endpoints are marked in the section below. {{% /boxes/added-in-paragraph %}} {{% boxes/warning %}} From 87de68c35e0dea4bd0652a9a0927e481fa0c6f5d Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Wed, 14 Aug 2024 20:51:12 +0300 Subject: [PATCH 57/70] Fix required fields in `/_matrix/key/v2/server` response schema (#1930) Fixes #613 --- changelogs/server_server/newsfragments/1930.clarification | 1 + data/api/server-server/definitions/keys.yaml | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/1930.clarification diff --git a/changelogs/server_server/newsfragments/1930.clarification b/changelogs/server_server/newsfragments/1930.clarification new file mode 100644 index 00000000..facff83c --- /dev/null +++ b/changelogs/server_server/newsfragments/1930.clarification @@ -0,0 +1 @@ +Fix required fields in `/_matrix/key/v2/server` response schema. diff --git a/data/api/server-server/definitions/keys.yaml b/data/api/server-server/definitions/keys.yaml index efb76f26..748debd8 100644 --- a/data/api/server-server/definitions/keys.yaml +++ b/data/api/server-server/definitions/keys.yaml @@ -98,4 +98,4 @@ properties: publishes a key which is valid for a significant amount of time without a way for the homeserver owner to revoke it. example: 1052262000000 -required: ["server_name", "verify_keys"] +required: ["server_name", "verify_keys", "signatures", "valid_until_ts"] From dc017c2dd3c2e7526353342da93581c7463300ca Mon Sep 17 00:00:00 2001 From: Kim Brose <2803622+HarHarLinks@users.noreply.github.com> Date: Thu, 15 Aug 2024 11:31:50 +0200 Subject: [PATCH 58/70] Document that the spec uses RFC 2119 (#1928) Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> --- .../appendices/newsfragments/1928.clarification | 1 + .../newsfragments/1928.clarification | 1 + .../client_server/newsfragments/1928.clarification | 1 + .../newsfragments/1928.clarification | 1 + .../internal/newsfragments/1928.clarification | 1 + .../push_gateway/newsfragments/1928.clarification | 1 + .../room_versions/newsfragments/1928.clarification | 1 + .../server_server/newsfragments/1928.clarification | 1 + content/_index.md | 14 ++++++++++++++ 9 files changed, 22 insertions(+) create mode 100644 changelogs/appendices/newsfragments/1928.clarification create mode 100644 changelogs/application_service/newsfragments/1928.clarification create mode 100644 changelogs/client_server/newsfragments/1928.clarification create mode 100644 changelogs/identity_service/newsfragments/1928.clarification create mode 100644 changelogs/internal/newsfragments/1928.clarification create mode 100644 changelogs/push_gateway/newsfragments/1928.clarification create mode 100644 changelogs/room_versions/newsfragments/1928.clarification create mode 100644 changelogs/server_server/newsfragments/1928.clarification diff --git a/changelogs/appendices/newsfragments/1928.clarification b/changelogs/appendices/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/appendices/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. diff --git a/changelogs/application_service/newsfragments/1928.clarification b/changelogs/application_service/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/application_service/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. diff --git a/changelogs/client_server/newsfragments/1928.clarification b/changelogs/client_server/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/client_server/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. diff --git a/changelogs/identity_service/newsfragments/1928.clarification b/changelogs/identity_service/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/identity_service/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. diff --git a/changelogs/internal/newsfragments/1928.clarification b/changelogs/internal/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/internal/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. diff --git a/changelogs/push_gateway/newsfragments/1928.clarification b/changelogs/push_gateway/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/push_gateway/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. diff --git a/changelogs/room_versions/newsfragments/1928.clarification b/changelogs/room_versions/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/room_versions/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. diff --git a/changelogs/server_server/newsfragments/1928.clarification b/changelogs/server_server/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/server_server/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. diff --git a/content/_index.md b/content/_index.md index a8c53809..ba49dc3a 100644 --- a/content/_index.md +++ b/content/_index.md @@ -99,6 +99,20 @@ services - be that for instant messages, VoIP call setups, or any other objects that need to be reliably and persistently pushed from A to B in an interoperable and federated manner. +### Requirement levels + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" across all parts of the +specification are to be interpreted as described in +[RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). + +Some entire sections of the specification might be optional depending on the +circumstances. For example, the +[modules of the client-server API](/client-server-api/#modules) +apply depending on the use case. The requirement level expressed by the above +key words appearing in such a section is only relevant if the section itself is +applicable. + ### Spec Change Proposals To propose a change to the Matrix Spec, see the explanations at From 215982abc203004c2f892495e6b06565cf3f599b Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 19 Aug 2024 14:11:05 +0200 Subject: [PATCH 59/70] Use dedicated fonts for better support of mathematical symbols (#1919) --- assets/scss/_variables_project.scss | 18 ++++++++++-------- .../internal/newsfragments/1919.clarification | 1 + content/rooms/fragments/v2-state-res.md | 2 +- 3 files changed, 12 insertions(+), 9 deletions(-) create mode 100644 changelogs/internal/newsfragments/1919.clarification diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss index 350e39cd..c2ec03c6 100644 --- a/assets/scss/_variables_project.scss +++ b/assets/scss/_variables_project.scss @@ -40,15 +40,17 @@ $table-bg: $secondary-lightest-background; $td-enable-google-fonts: false; /* - * Replace the default font with Inter. - * - * The $font-family-sans-serif definition here overrides the default value set by docsy: - * https://github.com/matrix-org/docsy/blob/66a4e61d2d34edc7196b9df83a7d09cd4af14b47/assets/scss/_variables.scss#L68 - * and adds "Inter" to the front. - * - * The font itself is loaded via stylesheet link layouts/partials/hooks/head-end.html. + * The $font-family-sans-serif definition here overrides the default value set by docsy + * (https://github.com/matrix-org/docsy/blob/66a4e61d2d34edc7196b9df83a7d09cd4af14b47/assets/scss/_variables.scss#L68) */ -$font-family-sans-serif: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; +$font-family-sans-serif: + // Add "Inter" to the front, making it the default. The font itself is loaded via stylesheet + // links in layouts/partials/hooks/head-end.html. + "Inter", + -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", + // Insert fonts suited for mathematical symbols on different platforms before "Arial" + "STIX Two Math", "Cambria Math", "Noto Sans Math", "Dejavu Sans", + Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; // Disable smooth scrolling as it makes TOC highlighting jump during the transition. $enable-smooth-scroll: false; diff --git a/changelogs/internal/newsfragments/1919.clarification b/changelogs/internal/newsfragments/1919.clarification new file mode 100644 index 00000000..478404e9 --- /dev/null +++ b/changelogs/internal/newsfragments/1919.clarification @@ -0,0 +1 @@ +Use dedicated fonts for better support of mathematical symbols. diff --git a/content/rooms/fragments/v2-state-res.md b/content/rooms/fragments/v2-state-res.md index 658f9e77..725cd08f 100644 --- a/content/rooms/fragments/v2-state-res.md +++ b/content/rooms/fragments/v2-state-res.md @@ -50,7 +50,7 @@ chain for each state *S**i*, that is the union of the auth chains for each event in *S**i*, and then taking every event that doesn't appear in every auth chain. If *C**i* is the full auth chain of *S**i*, then the auth difference is - ∪ *C**i* −  ∩ *C**i*. +∪ *C**i* − ∩ *C**i*. **Full conflicted set.** The *full conflicted set* is the union of the conflicted state set and From 7f2f100420a355cf8ea50d08329e6f98989fc975 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 28 Aug 2024 14:42:30 +0200 Subject: [PATCH 60/70] MSC4156: Migrate server_name to via (#1933) Signed-off-by: Johannes Marbach --- .../newsfragments/1933.deprecation | 1 + .../client_server/newsfragments/1933.feature | 1 + data/api/client-server/joining.yaml | 25 +++++++++++++++++++ data/api/client-server/knocking.yaml | 25 +++++++++++++++++++ 4 files changed, 52 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1933.deprecation create mode 100644 changelogs/client_server/newsfragments/1933.feature diff --git a/changelogs/client_server/newsfragments/1933.deprecation b/changelogs/client_server/newsfragments/1933.deprecation new file mode 100644 index 00000000..b65ebdc7 --- /dev/null +++ b/changelogs/client_server/newsfragments/1933.deprecation @@ -0,0 +1 @@ +Deprecate the `server_name` query parameter on `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4156](https://github.com/matrix-org/matrix-spec-proposals/pull/4156). diff --git a/changelogs/client_server/newsfragments/1933.feature b/changelogs/client_server/newsfragments/1933.feature new file mode 100644 index 00000000..030b5a00 --- /dev/null +++ b/changelogs/client_server/newsfragments/1933.feature @@ -0,0 +1 @@ +Add `via` query parameter on `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4156](https://github.com/matrix-org/matrix-spec-proposals/pull/4156). diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml index afd19fa8..aead420c 100644 --- a/data/api/client-server/joining.yaml +++ b/data/api/client-server/joining.yaml @@ -139,6 +139,31 @@ paths: type: string - in: query name: server_name + x-changedInMatrixVersion: + "1.12": |- + This parameter has been deprecated in favour of `via` and will be removed in + a future version of the spec. + + Clients SHOULD use `via` when the homeserver they're talking to supports it. + To do this, they MAY either detect server support through the supported spec + versions in [`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions) + or always include both parameters with identical values. + + Homeservers MUST ignore all `server_name` parameters if any `via` parameters + are supplied. + description: |- + The servers to attempt to join the room through. One of the servers + must be participating in the room. + example: + - matrix.org + - elsewhere.ca + schema: + type: array + items: + type: string + - in: query + name: via + x-addedInMatrixVersion: "1.12" description: |- The servers to attempt to join the room through. One of the servers must be participating in the room. diff --git a/data/api/client-server/knocking.yaml b/data/api/client-server/knocking.yaml index 1eb6cde7..39a928e8 100644 --- a/data/api/client-server/knocking.yaml +++ b/data/api/client-server/knocking.yaml @@ -50,6 +50,31 @@ paths: type: string - in: query name: server_name + x-changedInMatrixVersion: + "1.12": |- + This parameter has been deprecated in favour of `via` and will be removed in + a future version of the spec. + + Clients SHOULD use `via` when the homeserver they're talking to supports it. + To do this, they MAY either detect server support through the supported spec + versions in [`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions) + or always include both parameters with identical values. + + Homeservers MUST ignore all `server_name` parameters if any `via` parameters + are supplied. + description: |- + The servers to attempt to knock on the room through. One of the servers + must be participating in the room. + example: + - matrix.org + - elsewhere.ca + schema: + type: array + items: + type: string + - in: query + name: via + x-addedInMatrixVersion: "1.12" description: |- The servers to attempt to knock on the room through. One of the servers must be participating in the room. From 415fb43848e7e732a95c791d3b13110fa3d45c32 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Mon, 2 Sep 2024 10:41:33 +0200 Subject: [PATCH 61/70] Specify `Content-Type` and `Content-Disposition` usage in the media repo (#1935) --- .../newsfragments/1935.clarification | 1 + .../client-server-api/modules/content_repo.md | 47 ++++++++++ .../client-server/authed-content-repo.yaml | 78 ++++++++++++++-- data/api/client-server/content-repo.yaml | 88 +++++++++++++++++-- 4 files changed, 203 insertions(+), 11 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1935.clarification diff --git a/changelogs/client_server/newsfragments/1935.clarification b/changelogs/client_server/newsfragments/1935.clarification new file mode 100644 index 00000000..de90b5da --- /dev/null +++ b/changelogs/client_server/newsfragments/1935.clarification @@ -0,0 +1 @@ +Specify `Content-Type` and `Content-Disposition` usage in the media repo, as per [MSC2701](https://github.com/matrix-org/matrix-spec-proposals/pull/2701) and [MSC2702](https://github.com/matrix-org/matrix-spec-proposals/pull/2702). \ No newline at end of file diff --git a/content/client-server-api/modules/content_repo.md b/content/client-server-api/modules/content_repo.md index c9ac06d7..17715504 100644 --- a/content/client-server-api/modules/content_repo.md +++ b/content/client-server-api/modules/content_repo.md @@ -168,3 +168,50 @@ Homeservers have additional content-specific concerns: - Clients or remote homeservers may try to upload malicious files targeting vulnerabilities in either the homeserver thumbnailing or the client decoders. + +##### Serving inline content + +Clients with insecure configurations may be vulnerable to Cross-Site Scripting +attacks when served media with a `Content-Disposition` of `inline`. Clients +SHOULD NOT be hosted on the same domain as the media endpoints for the homeserver +to mitigate most of this risk. Servers SHOULD restrict `Content-Type` headers to +one of the following values when serving content with `Content-Disposition: inline`: + +* `text/css` +* `text/plain` +* `text/csv` +* `application/json` +* `application/ld+json` +* `image/jpeg` +* `image/gif` +* `image/png` +* `image/apng` +* `image/webp` +* `image/avif` +* `video/mp4` +* `video/webm` +* `video/ogg` +* `video/quicktime` +* `audio/mp4` +* `audio/webm` +* `audio/aac` +* `audio/mpeg` +* `audio/ogg` +* `audio/wave` +* `audio/wav` +* `audio/x-wav` +* `audio/x-pn-wav` +* `audio/flac` +* `audio/x-flac` + +These types are unlikely to cause Cross-Site Scripting issues when a `Content-Type` +header is provided, as clients will only try to render the data using that content +type. For example, if a HTML file is uploaded with a `Content-Type` of `image/png`, +clients will just assume that the image is corrupted, and won't render it as a +HTML page. Therefore, there is no risk in trusting the user-defined content type, +as long as the `Content-Disposition` is calculated based on that type. + +Clients SHOULD NOT rely on servers returning `inline` rather than `attachment` +on `/download`. Server implementations might decide out of an abundance of +caution that all downloads are responded to with `attachment`, regardless of +content type - clients should not be surprised by this behaviour. diff --git a/data/api/client-server/authed-content-repo.yaml b/data/api/client-server/authed-content-repo.yaml index 43cb5881..53416cf3 100644 --- a/data/api/client-server/authed-content-repo.yaml +++ b/data/api/client-server/authed-content-repo.yaml @@ -46,9 +46,29 @@ paths: Content-Type: $ref: '#/components/headers/downloadContentType' Content-Disposition: - description: The name of the file that was previously uploaded, if set. + x-changedInMatrixVersion: + "1.12": This header became required. + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be one of `inline` or `attachment`, + and SHOULD contain a file name. + + If the `Content-Type` is allowed in the [restrictions for serving + inline content](/client-server-api/#serving-inline-content), + servers SHOULD use `inline`, otherwise they SHOULD use + `attachment`. + + If the upload was made with a `filename`, this header MUST + contain the same `filename`. Otherwise, `filename` is excluded + from the header. If the media being downloaded is remote, the + remote server's `filename` in the `Content-Disposition` header + is used as the `filename` instead. When the header is not + supplied, or does not supply a `filename`, the local download + response does not include a `filename`. + required: true schema: type: string + example: "inline; filename=\"filename.jpg\"" content: application/octet-stream: schema: @@ -106,11 +126,21 @@ paths: Content-Type: $ref: '#/components/headers/downloadContentType' Content-Disposition: - description: |- - The `fileName` requested or the name of the file that was previously - uploaded, if set. + x-changedInMatrixVersion: + "1.12": This header became required. + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be one of `inline` or `attachment`, + and MUST contain the file name requested in the path. + + If the `Content-Type` is allowed in the [restrictions for serving + inline content](/client-server-api/#serving-inline-content), + servers SHOULD use `inline`, otherwise they SHOULD use + `attachment`. + required: true schema: type: string + example: "inline; filename=\"filename.jpg\"" content: application/octet-stream: schema: @@ -208,8 +238,24 @@ paths: "200": description: A thumbnail of the requested content. headers: + Content-Disposition: + x-addedInMatrixVersion: "1.12" + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be `inline`, and SHOULD contain a file name (e.g. `thumbnail.png`). + + Servers should note the [Content-Type restrictions for serving inline content](/client-server-api/#serving-inline-content), + as these limitations imply which formats should be used for thumbnail generation. + required: true + schema: + type: string + example: "inline; filename=\"thumbnail.png\"" Content-Type: + x-changedInMatrixVersion: + "1.12": | + This header became required in order to support `Content-Disposition`. description: The content type of the thumbnail. + required: true schema: type: string enum: @@ -512,7 +558,29 @@ components: format: uri headers: downloadContentType: - description: The content type of the file that was previously uploaded. + description: | + The content type of the file that was previously uploaded. + + The server MUST return a `Content-Type` which is either exactly the same + as the original upload, or reasonably close. The bounds of "reasonable" + are: + + * Adding a charset to `text/*` content types. + * Detecting HTML and using `text/html` instead of `text/plain`. + * Using `application/octet-stream` when the server determines the + content type is obviously wrong. For example, an encrypted file being + claimed as `image/png`. + * Returning `application/octet-stream` when the media has an + unknown/unprovided `Content-Type`. For example, being uploaded before + the server tracked content types or when the remote server is + non-compliantly omitting the header entirely. + + Actions not in the spirit of the above are not considered "reasonable". + x-changedInMatrixVersion: + "1.12": | + This header became required in order to support `Content-Disposition`, + and the behaviour to compute its value was clarified. + required: true schema: type: string diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 92ca6caa..f50850bd 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -248,9 +248,29 @@ paths: Content-Type: $ref: '#/components/headers/downloadContentType' Content-Disposition: - description: The name of the file that was previously uploaded, if set. + x-changedInMatrixVersion: + "1.12": This header became required. + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be one of `inline` or `attachment`, + and SHOULD contain a file name. + + If the `Content-Type` is allowed in the [restrictions for serving + inline content](/client-server-api/#serving-inline-content), + servers SHOULD use `inline`, otherwise they SHOULD use + `attachment`. + + If the upload was made with a `filename`, this header MUST + contain the same `filename`. Otherwise, `filename` is excluded + from the header. If the media being downloaded is remote, the + remote server's `filename` in the `Content-Disposition` header + is used as the `filename` instead. When the header is not + supplied, or does not supply a `filename`, the local download + response does not include a `filename`. + required: true schema: type: string + example: "inline; filename=\"filename.jpg\"" content: application/octet-stream: schema: @@ -309,11 +329,21 @@ paths: Content-Type: $ref: '#/components/headers/downloadContentType' Content-Disposition: - description: |- - The `fileName` requested or the name of the file that was previously - uploaded, if set. + x-changedInMatrixVersion: + "1.12": This header became required. + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be one of `inline` or `attachment`, + and MUST contain the file name requested in the path. + + If the `Content-Type` is allowed in the [restrictions for serving + inline content](/client-server-api/#serving-inline-content), + servers SHOULD use `inline`, otherwise they SHOULD use + `attachment`. + required: true schema: type: string + example: "inline; filename=\"filename.jpg\"" content: application/octet-stream: schema: @@ -412,8 +442,24 @@ paths: "200": description: A thumbnail of the requested content. headers: + Content-Disposition: + x-addedInMatrixVersion: "1.12" + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be `inline`, and SHOULD contain a file name (e.g. `thumbnail.png`). + + Servers should note the [Content-Type restrictions for serving inline content](/client-server-api/#serving-inline-content), + as these limitations imply which formats should be used for thumbnail generation. + required: true + schema: + type: string + example: "inline; filename=\"thumbnail.png\"" Content-Type: + x-changedInMatrixVersion: + "1.12": | + This header became required in order to support `Content-Disposition`. description: The content type of the thumbnail. + required: true schema: type: string enum: @@ -639,7 +685,15 @@ components: contentType: in: header name: Content-Type - description: The content type of the file being uploaded + description: | + **Optional.** The content type of the file being uploaded. + + Clients SHOULD always supply this header. + + Defaults to `application/octet-stream` if it is not set. + x-changedInMatrixVersion: + "1.12": | + This header became explicitly optional with a default value. example: application/pdf schema: type: string @@ -782,7 +836,29 @@ components: format: uri headers: downloadContentType: - description: The content type of the file that was previously uploaded. + description: | + The content type of the file that was previously uploaded. + + The server MUST return a `Content-Type` which is either exactly the same + as the original upload, or reasonably close. The bounds of "reasonable" + are: + + * Adding a charset to `text/*` content types. + * Detecting HTML and using `text/html` instead of `text/plain`. + * Using `application/octet-stream` when the server determines the + content type is obviously wrong. For example, an encrypted file being + claimed as `image/png`. + * Returning `application/octet-stream` when the media has an + unknown/unprovided `Content-Type`. For example, being uploaded before + the server tracked content types or when the remote server is + non-compliantly omitting the header entirely. + + Actions not in the spirit of the above are not considered "reasonable". + x-changedInMatrixVersion: + "1.12": | + This header became required in order to support `Content-Disposition`, + and the behaviour to compute its value was clarified. + required: true schema: type: string From 6d088e03a1e767fbd55576e9683f243fa1fb13dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Wed, 4 Sep 2024 14:53:06 +0200 Subject: [PATCH 62/70] Add `added-in` shortcode for unread markers section (#1941) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/1941.feature | 1 + content/client-server-api/modules/read_markers.md | 2 ++ 2 files changed, 3 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1941.feature diff --git a/changelogs/client_server/newsfragments/1941.feature b/changelogs/client_server/newsfragments/1941.feature new file mode 100644 index 00000000..5e806a7f --- /dev/null +++ b/changelogs/client_server/newsfragments/1941.feature @@ -0,0 +1 @@ +Add support for marking rooms as unread as per [MSC2867](https://github.com/matrix-org/matrix-spec-proposals/pull/2867). diff --git a/content/client-server-api/modules/read_markers.md b/content/client-server-api/modules/read_markers.md index 55e73dd5..830a441f 100644 --- a/content/client-server-api/modules/read_markers.md +++ b/content/client-server-api/modules/read_markers.md @@ -57,6 +57,8 @@ applicable filters are also satisfied. #### Unread markers +{{% added-in v="1.12" %}} + Clients may use "unread markers" to allow users to label rooms for later attention irrespective of [read receipts](#receipts) or [fully read markers](#fully-read-markers). From 75e77b96ff56464c6e11e4605a3b160ba15710b0 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 11 Sep 2024 13:51:27 +0200 Subject: [PATCH 63/70] Additional keys in GET /capabilities don't have to be objects (#1945) --- changelogs/client_server/newsfragments/1945.clarification | 1 + data/api/client-server/capabilities.yaml | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1945.clarification diff --git a/changelogs/client_server/newsfragments/1945.clarification b/changelogs/client_server/newsfragments/1945.clarification new file mode 100644 index 00000000..651ea6d3 --- /dev/null +++ b/changelogs/client_server/newsfragments/1945.clarification @@ -0,0 +1 @@ +Additional keys in `GET /capabilities` don't have to be objects. diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml index 3ae26b22..523c6091 100644 --- a/data/api/client-server/capabilities.yaml +++ b/data/api/client-server/capabilities.yaml @@ -43,7 +43,9 @@ paths: The custom capabilities the server supports, using the Java package naming convention. additionalProperties: - type: object + description: |- + Application-dependent keys using the + [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar). properties: m.change_password: $ref: '#/components/schemas/booleanCapability' From 2cbf6067a6d50ea2160e72d2a570f2cb8eeb0a20 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 11 Sep 2024 14:56:14 +0200 Subject: [PATCH 64/70] Use "server name" instead of "DNS name" to avoid confusion (#1946) Fixes: #1911 Signed-off-by: Johannes Marbach --- changelogs/server_server/newsfragments/1946.clarification | 1 + data/api/server-server/definitions/keys.yaml | 2 +- data/api/server-server/joins-v1.yaml | 2 +- data/api/server-server/joins-v2.yaml | 2 +- data/api/server-server/keys_query.yaml | 2 +- data/api/server-server/query.yaml | 6 ++++-- 6 files changed, 9 insertions(+), 6 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1946.clarification diff --git a/changelogs/server_server/newsfragments/1946.clarification b/changelogs/server_server/newsfragments/1946.clarification new file mode 100644 index 00000000..baf02987 --- /dev/null +++ b/changelogs/server_server/newsfragments/1946.clarification @@ -0,0 +1 @@ + Use "server name" instead of "DNS name" to avoid confusion with the "DNS name" component of "server names" as defined in the appendices. \ No newline at end of file diff --git a/data/api/server-server/definitions/keys.yaml b/data/api/server-server/definitions/keys.yaml index 748debd8..c3f71083 100644 --- a/data/api/server-server/definitions/keys.yaml +++ b/data/api/server-server/definitions/keys.yaml @@ -19,7 +19,7 @@ example: properties: server_name: type: string - description: DNS name of the homeserver. + description: The homeserver's [server name](/appendices/#server-name). example: "example.org" verify_keys: type: object diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index a56315d1..a361836c 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -341,7 +341,7 @@ paths: properties: origin: type: string - description: The resident server's DNS name. + description: The resident server's [server name](/appendices/#server-name). auth_chain: type: array description: |- diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 465207e9..31f8098c 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -162,7 +162,7 @@ paths: properties: origin: type: string - description: The resident server's DNS name. + description: The resident server's [server name](/appendices/#server-name). members_omitted: type: boolean description: "`true` if `m.room.member` events have been omitted from `state`." diff --git a/data/api/server-server/keys_query.yaml b/data/api/server-server/keys_query.yaml index ed9e6302..791deb0a 100644 --- a/data/api/server-server/keys_query.yaml +++ b/data/api/server-server/keys_query.yaml @@ -26,7 +26,7 @@ paths: parameters: - in: path name: serverName - description: The server's DNS name to query + description: The [server name](/appendices/#server-name) to query required: true example: matrix.org schema: diff --git a/data/api/server-server/query.yaml b/data/api/server-server/query.yaml index efb3a6c9..16ed5e40 100644 --- a/data/api/server-server/query.yaml +++ b/data/api/server-server/query.yaml @@ -45,7 +45,8 @@ paths: description: |- Performs a query to get the mapped room ID and list of resident homeservers in the room for a given room alias. Homeservers should only query room aliases - that belong to the target server (identified by the DNS Name in the alias). + that belong to the target server (identified by the [server name](/appendices/#server-name) + in the alias). Servers may wish to cache the response to this query to avoid requesting the information too often. @@ -111,7 +112,8 @@ paths: description: |- Performs a query to get profile information, such as a display name or avatar, for a given user. Homeservers should only query profiles for users that belong - to the target server (identified by the DNS Name in the user ID). + to the target server (identified by the [server name](/appendices/#server-name) + in the user ID). Servers may wish to cache the response to this query to avoid requesting the information too often. From ace2712719705b3d105e1dad013fcce74f1d9483 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 26 Sep 2024 15:19:45 +0200 Subject: [PATCH 65/70] MSC3939: Account locking (#1934) --- .../client_server/newsfragments/1934.feature | 1 + content/client-server-api/_index.md | 56 +++++++++++++++++++ 2 files changed, 57 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1934.feature diff --git a/changelogs/client_server/newsfragments/1934.feature b/changelogs/client_server/newsfragments/1934.feature new file mode 100644 index 00000000..75b55688 --- /dev/null +++ b/changelogs/client_server/newsfragments/1934.feature @@ -0,0 +1 @@ +Add account locking as per [MSC3939](https://github.com/matrix-org/matrix-spec-proposals/pull/3939). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 1a6f1c6e..e9efe8ec 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -100,6 +100,9 @@ section](#soft-logout) for more information. `M_MISSING_TOKEN` No access token was specified for the request. +`M_USER_LOCKED` +The account has been [locked](#account-locking) and cannot be used at this time. + `M_BAD_JSON` Request contained valid JSON, but it was malformed in some way, e.g. missing required keys, invalid values for keys. @@ -516,6 +519,10 @@ token available. If it does not have a refresh token available, or refreshing fails with `soft_logout: true`, the client can acquire a new access token by specifying the device ID it is already using to the login API. +{{% changed-in v="1.12" %}} A client that receives such a response together +with an `M_USER_LOCKED` error code, cannot obtain a new access token until +the account has been [unlocked](#account-locking). + ### User-Interactive Authentication API #### Overview @@ -1425,6 +1432,55 @@ number and a symbol and be at a minimum 8 characters in length. Servers MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. {{% /boxes/warning %}} +#### Account locking + +{{% added-in v="1.12" %}} + +Server administrators may apply locks to prevent users from usefully +using their accounts, for instance, due to safety or security concerns. +In contrast to account deactivation, locking is a non-destructive action +that can be reversed. This specification describes the behaviour of clients +and servers when an account is locked. It deliberately leaves the methods +for locking and unlocking accounts as a server implementation detail. + +When an account is locked, servers MUST return a `401 Unauthorized` error +response with an `M_USER_LOCKED` error code and [`soft_logout`](#soft-logout) +set to `true` on all but the following Client-Server APIs: + +- [`POST /logout`](#post_matrixclientv3logout) +- [`POST /logout/all`](#post_matrixclientv3logoutall) + +Servers MAY additionally include details of why the lock was applied in +the `error` field. + +``` +HTTP/1.1 401 Unauthorized +Content-Type: application/json +``` + +```json +{ + "errcode": "M_USER_LOCKED", + "error": "This account has been locked", + "soft_logout": true +} +``` + +Servers SHOULD NOT invalidate access tokens on locked accounts unless the +client requests a logout (using the above endpoints). This ensures that +users can retain their sessions without having to log back in if the account +becomes unlocked. + +Upon receiving an `M_USER_LOCKED` error, clients SHOULD retain session +information including encryption state and inform the user that their account +has been locked. While the lock is applied, clients SHOULD hide the normal UI +from the user, preventing general use of their account. Clients SHOULD, however, +continue to make rate-limited requests to [`/sync`](#get_matrixclientv3sync) +and other APIs to detect when the lock has been lifted. + +To enable users to appeal to a lock clients MAY use +[server contact discovery](#getwell-knownmatrixsupport). + ### Adding Account Administrative Contact Information A homeserver may keep some contact information for administrative use. From 00af39ecca278084ef9f138f7819a298ed185596 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 27 Sep 2024 14:00:00 +0200 Subject: [PATCH 66/70] Provide MD checklists for the changelog (#1937) * Output changelog checklists Fixes: #1682 Signed-off-by: Johannes Marbach --- .github/workflows/main.yml | 2 +- changelogs/header.md | 3 +-- .../internal/newsfragments/1937.clarification | 1 + changelogs/template.md.jinja | 2 +- config.toml | 8 ++++++ content/changelog/_index.md | 7 +++++ content/changelog/{index.md => historical.md} | 27 ++++++++++--------- content/changelog/v1.1.md | 19 ++++++++----- content/changelog/v1.10.md | 25 ++++++++++------- content/changelog/v1.11.md | 25 ++++++++++------- content/changelog/v1.2.md | 23 +++++++++------- content/changelog/v1.3.md | 23 +++++++++------- content/changelog/v1.4.md | 25 ++++++++++------- content/changelog/v1.5.md | 25 ++++++++++------- content/changelog/v1.6.md | 25 ++++++++++------- content/changelog/v1.7.md | 25 ++++++++++------- content/changelog/v1.8.md | 25 ++++++++++------- content/changelog/v1.9.md | 25 ++++++++++------- layouts/_default/single.checklist.md | 4 +++ .../changelog/changelog-description.html | 19 ------------- layouts/shortcodes/changelog/changelogs.html | 10 +++---- scripts/generate-changelog.sh | 22 ++++++++++++--- 22 files changed, 219 insertions(+), 151 deletions(-) create mode 100644 changelogs/internal/newsfragments/1937.clarification create mode 100644 content/changelog/_index.md rename content/changelog/{index.md => historical.md} (82%) create mode 100644 layouts/_default/single.checklist.md delete mode 100644 layouts/shortcodes/changelog/changelog-description.html diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index cb14a0c1..fe0c77a4 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -177,7 +177,7 @@ jobs: uses: actions/upload-artifact@v4 with: name: changelog-artifact - path: content/changelog/vUNSTABLE.md + path: content/changelog/unstable.md build-spec: name: "📖 Build the spec" diff --git a/changelogs/header.md b/changelogs/header.md index 21b35106..a8fd04ba 100644 --- a/changelogs/header.md +++ b/changelogs/header.md @@ -6,11 +6,10 @@ Variables: DATE = Replaced by the date (eg: April 01, 2021) --> -## VERSION - +
      Git commithttps://github.com/matrix-org/matrix-spec/tree/VERSION
      Release dateDATE
      Checklistchecklist.md
      diff --git a/changelogs/internal/newsfragments/1937.clarification b/changelogs/internal/newsfragments/1937.clarification new file mode 100644 index 00000000..f54b5bf6 --- /dev/null +++ b/changelogs/internal/newsfragments/1937.clarification @@ -0,0 +1 @@ +Provide markdown checklists for changelogs under `/changelog/$VERSION/checklist.md`. diff --git a/changelogs/template.md.jinja b/changelogs/template.md.jinja index 38de4b92..cc456efd 100644 --- a/changelogs/template.md.jinja +++ b/changelogs/template.md.jinja @@ -1,7 +1,7 @@ {% for section_name, section in sections.items() %} {% if section_name %} -### {{section_name}} +## {{section_name}} {% endif %} {% if section %} diff --git a/config.toml b/config.toml index 6b669a79..b9a66cb8 100644 --- a/config.toml +++ b/config.toml @@ -138,3 +138,11 @@ sidebar_menu_compact = true [[module.imports]] path = "github.com/matrix-org/docsy" disable = false + +# custom output formats + +[outputFormats] + [outputFormats.Checklist] + mediaType = "text/markdown" + isPlainText = true + baseName = "checklist" diff --git a/content/changelog/_index.md b/content/changelog/_index.md new file mode 100644 index 00000000..ccb55f6f --- /dev/null +++ b/content/changelog/_index.md @@ -0,0 +1,7 @@ +--- +title: Changelog +type: docs +weight: 1000 +--- + +{{% changelog/changelogs %}} diff --git a/content/changelog/index.md b/content/changelog/historical.md similarity index 82% rename from content/changelog/index.md rename to content/changelog/historical.md index 560cb43b..72f1d9a2 100644 --- a/content/changelog/index.md +++ b/content/changelog/historical.md @@ -1,18 +1,15 @@ --- -title: Changelog +title: Historical versions type: docs -weight: 1000 +outputs: + - html --- -{{% changelog/changelog-description %}} +Before version 1.1, versioning was applied at the level of individual API specifications. +This section includes links to these versions of the APIs. -{{% changelog/changelogs %}} +## Client-Server API -

      Historical versions

      - -Before version 1.1, versioning was applied at the level of individual API specifications. This section includes links to these versions of the APIs. - -* **Client-Server API** - [r0.6.1](https://matrix.org/docs/spec/client_server/r0.6.1.html) - [r0.6.0](https://matrix.org/docs/spec/client_server/r0.6.0.html) - [r0.5.0](https://matrix.org/docs/spec/client_server/r0.5.0.html) @@ -26,22 +23,26 @@ Before version 1.1, versioning was applied at the level of individual API specif The last draft before the spec was formally released in version r0.0.0. -* **Server-Server API** +## Server-Server API + - [r0.1.4](https://matrix.org/docs/spec/server_server/r0.1.4.html) - [r0.1.3](https://matrix.org/docs/spec/server_server/r0.1.3.html) - [r0.1.2](https://matrix.org/docs/spec/server_server/r0.1.2.html) - [r0.1.1](https://matrix.org/docs/spec/server_server/r0.1.1.html) - [r0.1.0](https://matrix.org/docs/spec/server_server/r0.1.0.html) -* **Application Service API** +## Application Service API + - [r0.1.1](https://matrix.org/docs/spec/application_service/r0.1.1.html) - [r0.1.0](https://matrix.org/docs/spec/application_service/r0.1.0.html) -* **Identity Service API** +## Identity Service API + - [r0.3.0](https://matrix.org/docs/spec/identity_service/r0.3.0.html) - [r0.2.1](https://matrix.org/docs/spec/identity_service/r0.2.1.html) - [r0.2.0](https://matrix.org/docs/spec/identity_service/r0.2.0.html) - [r0.1.0](https://matrix.org/docs/spec/identity_service/r0.1.0.html) -* **Push Gateway API** +## Push Gateway API + - [r0.1.0](https://matrix.org/docs/spec/push_gateway/r0.1.0.html) diff --git a/content/changelog/v1.1.md b/content/changelog/v1.1.md index 8cf43878..91a79581 100644 --- a/content/changelog/v1.1.md +++ b/content/changelog/v1.1.md @@ -1,4 +1,10 @@ --- +title: v1.1 Changelog +linkTitle: v1.1 +type: docs +outputs: + - html + - checklist date: 2021-11-09T00:00:00+0000 --- -## v1.1 - +
      Git commithttps://github.com/matrix-org/matrix-doc/tree/v1.1
      Release dateNovember 09, 2021
      Checklistchecklist.md
      -### Client-Server API +## Client-Server API Breaking Changes @@ -110,7 +115,7 @@ Variables: - Fix documentation errors around `threepid_creds`. ([#3471](https://github.com/matrix-org/matrix-doc/issues/3471)) -### Server-Server API +## Server-Server API New Endpoints @@ -136,7 +141,7 @@ Variables: - Tweak the example PDU diagram to better demonstrate situations with multiple `prev_events`. ([#3340](https://github.com/matrix-org/matrix-doc/issues/3340)) -### Application Service API +## Application Service API Spec Clarifications @@ -145,7 +150,7 @@ Variables: - Fix various typos throughout the specification. ([#2888](https://github.com/matrix-org/matrix-doc/issues/2888)) -### Identity Service API +## Identity Service API New Endpoints @@ -168,7 +173,7 @@ Variables: - Describe how [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844) affects the `/versions` endpoint. ([#3459](https://github.com/matrix-org/matrix-doc/issues/3459)) -### Push Gateway API +## Push Gateway API Spec Clarifications diff --git a/content/changelog/v1.10.md b/content/changelog/v1.10.md index 16b3217d..38fb0501 100644 --- a/content/changelog/v1.10.md +++ b/content/changelog/v1.10.md @@ -1,4 +1,10 @@ --- +title: v1.10 Changelog +linkTitle: v1.10 +type: docs +outputs: + - html + - checklist date: 2024-03-22T09:59:45-06:00 --- -## v1.10 - +
      Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.10
      Release dateMarch 22, 2024
      Checklistchecklist.md
      -### Client-Server API +## Client-Server API **Backwards Compatible Changes** @@ -50,7 +55,7 @@ Variables: - Clarify that the `m.push_rules` account data type cannot be set using the `/account_data` API, as per [MSC4010](https://github.com/matrix-org/matrix-spec-proposals/pull/4010). ([#1763](https://github.com/matrix-org/matrix-spec/issues/1763)) -### Server-Server API +## Server-Server API **Spec Clarifications** @@ -59,36 +64,36 @@ Variables: - Clarify that the `children_state`, `room_type` and `allowed_room_ids` properties in the items of the `children` array of the response of the `GET /hierarchy` endpoint are not required. ([#1741](https://github.com/matrix-org/matrix-spec/issues/1741)) -### Application Service API +## Application Service API **Spec Clarifications** - Clarify that the `/login` and `/register` endpoints should fail when using the `m.login.application_service` login type without a valid `as_token`. ([#1744](https://github.com/matrix-org/matrix-spec/issues/1744)) -### Identity Service API +## Identity Service API No significant changes. -### Push Gateway API +## Push Gateway API No significant changes. -### Room Versions +## Room Versions **Spec Clarifications** - For room versions 7 through 11: Clarify that `invite->knock` is not a legal transition. ([#1717](https://github.com/matrix-org/matrix-spec/issues/1717)) -### Appendices +## Appendices No significant changes. -### Internal Changes/Tooling +## Internal Changes/Tooling **Spec Clarifications** diff --git a/content/changelog/v1.11.md b/content/changelog/v1.11.md index f3a60b55..cb20f57b 100644 --- a/content/changelog/v1.11.md +++ b/content/changelog/v1.11.md @@ -1,4 +1,10 @@ --- +title: v1.11 Changelog +linkTitle: v1.11 +type: docs +outputs: + - html + - checklist date: 2024-06-20T10:20:43-06:00 --- -## v1.11 - +
      Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.11
      Release dateJune 20, 2024
      Checklistchecklist.md
      -### Client-Server API +## Client-Server API **Deprecations** @@ -63,7 +68,7 @@ Variables: - Clarify that `/media/v3/upload/{serverName}/{mediaId}` requires authentication. ([#1872](https://github.com/matrix-org/matrix-spec/issues/1872)) -### Server-Server API +## Server-Server API **Deprecations** @@ -87,26 +92,26 @@ Variables: - Fix various typos throughout the specification. ([#1877](https://github.com/matrix-org/matrix-spec/issues/1877)) -### Application Service API +## Application Service API **Spec Clarifications** - Clarify that appservices should be notified of events relating to the `sender_localpart` user. ([#1810](https://github.com/matrix-org/matrix-spec/issues/1810)) -### Identity Service API +## Identity Service API **Deprecations** - Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. ([#1808](https://github.com/matrix-org/matrix-spec/issues/1808)) -### Push Gateway API +## Push Gateway API No significant changes. -### Room Versions +## Room Versions **Spec Clarifications** @@ -116,7 +121,7 @@ No significant changes. - Generate the Table of Contents with Hugo rather than JavaScript. ([#1884](https://github.com/matrix-org/matrix-spec/issues/1884)) -### Appendices +## Appendices **Deprecations** @@ -129,7 +134,7 @@ No significant changes. - Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. ([#1850](https://github.com/matrix-org/matrix-spec/issues/1850)) -### Internal Changes/Tooling +## Internal Changes/Tooling **Spec Clarifications** diff --git a/content/changelog/v1.2.md b/content/changelog/v1.2.md index 22deb1ac..5f06e8a7 100644 --- a/content/changelog/v1.2.md +++ b/content/changelog/v1.2.md @@ -1,4 +1,10 @@ --- +title: v1.2 Changelog +linkTitle: v1.2 +type: docs +outputs: + - html + - checklist date: 2022-02-02T00:00:00+0000 --- -## v1.2 - +
      Git commithttps://github.com/matrix-org/matrix-doc/tree/v1.2
      Release dateFebruary 02, 2022
      Checklistchecklist.md
      -### Client-Server API +## Client-Server API Breaking Changes @@ -65,7 +70,7 @@ Variables: - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674)) -### Server-Server API +## Server-Server API New Endpoints @@ -88,7 +93,7 @@ Variables: - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674)) -### Application Service API +## Application Service API Spec Clarifications @@ -99,7 +104,7 @@ Variables: - Correct the documentation for the response value for `GET /_matrix/app/v1/thirdparty/protocol/{protocol}`. ([#3675](https://github.com/matrix-org/matrix-doc/issues/3675)) -### Identity Service API +## Identity Service API Backwards Compatible Changes @@ -114,7 +119,7 @@ Variables: - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674)) -### Push Gateway API +## Push Gateway API Spec Clarifications @@ -123,7 +128,7 @@ Variables: - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674)) -### Room Versions +## Room Versions Backwards Compatible Changes @@ -144,7 +149,7 @@ Variables: - Fix auth rules to allow membership of `knock` -> `leave` in v7, v8, and v9. ([#3694](https://github.com/matrix-org/matrix-doc/issues/3694)) -### Appendices +## Appendices Backwards Compatible Changes diff --git a/content/changelog/v1.3.md b/content/changelog/v1.3.md index bc05b1cc..46e7f0d4 100644 --- a/content/changelog/v1.3.md +++ b/content/changelog/v1.3.md @@ -1,4 +1,10 @@ --- +title: v1.3 Changelog +linkTitle: v1.3 +type: docs +outputs: + - html + - checklist date: 2022-06-15T00:00:00+0100 --- -## v1.3 - +
      Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.3
      Release dateJune 15, 2022
      Checklistchecklist.md
      -### Client-Server API +## Client-Server API Deprecations @@ -55,7 +60,7 @@ Variables: - Fix membership state transitions to denote that `invite->knock` and `external->leave` are valid transitions. ([#3730](https://github.com/matrix-org/matrix-spec-proposals/issues/3730)) -### Server-Server API +## Server-Server API Backwards Compatible Changes @@ -79,7 +84,7 @@ Variables: - Clarify that the `content` for `X-Matrix` signature validation is the parsed JSON body. ([#3727](https://github.com/matrix-org/matrix-spec-proposals/issues/3727)) -### Application Service API +## Application Service API Backwards Compatible Changes @@ -88,19 +93,19 @@ Variables: - Add timestamp massaging as per [MSC3316](https://github.com/matrix-org/matrix-spec-proposals/pull/3316). ([#1094](https://github.com/matrix-org/matrix-spec/issues/1094)) -### Identity Service API +## Identity Service API No significant changes. -### Push Gateway API +## Push Gateway API No significant changes. -### Room Versions +## Room Versions Backwards Compatible Changes @@ -124,7 +129,7 @@ No significant changes. - For room versions 7, 8, 9, and 10: fix join membership authorization rules when `join_rule` is `knock`. ([#3737](https://github.com/matrix-org/matrix-spec-proposals/issues/3737)) -### Appendices +## Appendices No significant changes. diff --git a/content/changelog/v1.4.md b/content/changelog/v1.4.md index 7d22c00e..6515e570 100644 --- a/content/changelog/v1.4.md +++ b/content/changelog/v1.4.md @@ -1,4 +1,10 @@ --- +title: v1.4 Changelog +linkTitle: v1.4 +type: docs +outputs: + - html + - checklist date: 2022-09-29T00:00:00+0100 --- -## v1.4 - +
      Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.4
      Release dateSeptember 29, 2022
      Checklistchecklist.md
      -### Client-Server API +## Client-Server API Removed Endpoints @@ -58,7 +63,7 @@ Variables: - Clarify enum values by separating possible values with commas. ([#1240](https://github.com/matrix-org/matrix-spec/issues/1240)) -### Server-Server API +## Server-Server API Backwards Compatible Changes @@ -75,7 +80,7 @@ Variables: - Update "API Standards" section to clarify how JSON is used. ([#1185](https://github.com/matrix-org/matrix-spec/issues/1185)) -### Application Service API +## Application Service API Breaking Changes @@ -90,7 +95,7 @@ Variables: - Add HTML anchors for object definitions in the formatted specification. ([#1174](https://github.com/matrix-org/matrix-spec/issues/1174)) -### Identity Service API +## Identity Service API Spec Clarifications @@ -100,7 +105,7 @@ Variables: - Update "API Standards" section to clarify how JSON is used. ([#1185](https://github.com/matrix-org/matrix-spec/issues/1185)) -### Push Gateway API +## Push Gateway API Spec Clarifications @@ -109,7 +114,7 @@ Variables: - Add HTML anchors for object definitions in the formatted specification. ([#1174](https://github.com/matrix-org/matrix-spec/issues/1174)) -### Room Versions +## Room Versions Spec Clarifications @@ -120,13 +125,13 @@ Variables: - For room versions 7 through 10: Clarify that `invite->knock` is actually a legal transition. ([#1175](https://github.com/matrix-org/matrix-spec/issues/1175)) -### Appendices +## Appendices No significant changes. -### Internal Changes/Tooling +## Internal Changes/Tooling Backwards Compatible Changes diff --git a/content/changelog/v1.5.md b/content/changelog/v1.5.md index 258aabfa..cc099ebe 100644 --- a/content/changelog/v1.5.md +++ b/content/changelog/v1.5.md @@ -1,4 +1,10 @@ --- +title: v1.5 Changelog +linkTitle: v1.5 +type: docs +outputs: + - html + - checklist date: 2022-11-17T08:22:11-07:00 --- -## v1.5 - +
      Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.5
      Release dateNovember 17, 2022
      Checklistchecklist.md
      -### Client-Server API +## Client-Server API Backwards Compatible Changes @@ -45,7 +50,7 @@ Variables: - Add example read receipt to `GET /_matrix/client/v3/sync` response example. ([#1341](https://github.com/matrix-org/matrix-spec/issues/1341)) -### Server-Server API +## Server-Server API Spec Clarifications @@ -54,7 +59,7 @@ Variables: - Fix a number of broken links in the specification. ([#1330](https://github.com/matrix-org/matrix-spec/issues/1330)) -### Application Service API +## Application Service API Spec Clarifications @@ -63,7 +68,7 @@ Variables: - Clarify that application services can only register an interest in local users, as per [MSC3905](https://github.com/matrix-org/matrix-spec-proposals/issues/3905). ([#1305](https://github.com/matrix-org/matrix-spec/issues/1305)) -### Identity Service API +## Identity Service API Spec Clarifications @@ -72,13 +77,13 @@ Variables: - Fix a number of broken links in the specification. ([#1330](https://github.com/matrix-org/matrix-spec/issues/1330)) -### Push Gateway API +## Push Gateway API No significant changes. -### Room Versions +## Room Versions Spec Clarifications @@ -89,13 +94,13 @@ No significant changes. - Fix a number of broken links in the specification. ([#1330](https://github.com/matrix-org/matrix-spec/issues/1330)) -### Appendices +## Appendices No significant changes. -### Internal Changes/Tooling +## Internal Changes/Tooling Backwards Compatible Changes diff --git a/content/changelog/v1.6.md b/content/changelog/v1.6.md index 07574ff3..d0e14a0a 100644 --- a/content/changelog/v1.6.md +++ b/content/changelog/v1.6.md @@ -1,4 +1,10 @@ --- +title: v1.6 Changelog +linkTitle: v1.6 +type: docs +outputs: + - html + - checklist date: 2023-02-14T08:25:40-07:00 --- -## v1.6 - +
      Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.6
      Release dateFebruary 14, 2023
      Checklistchecklist.md
      -### Client-Server API +## Client-Server API Backwards Compatible Changes @@ -45,7 +50,7 @@ Variables: - Improve distinction between tags and their attributes in the rich text section. Contributed by Nico. ([#1433](https://github.com/matrix-org/matrix-spec/issues/1433)) -### Server-Server API +## Server-Server API Breaking Changes @@ -73,7 +78,7 @@ Variables: - Fix `edu_type` in EDU examples. ([#1383](https://github.com/matrix-org/matrix-spec/issues/1383)) -### Application Service API +## Application Service API Backwards Compatible Changes @@ -82,7 +87,7 @@ Variables: - Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347)) -### Identity Service API +## Identity Service API Backwards Compatible Changes @@ -91,7 +96,7 @@ Variables: - Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347)) -### Push Gateway API +## Push Gateway API Backwards Compatible Changes @@ -100,7 +105,7 @@ Variables: - Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347)) -### Room Versions +## Room Versions Backwards Compatible Changes @@ -116,13 +121,13 @@ Variables: - Fix various typos throughout the specification. ([#1423](https://github.com/matrix-org/matrix-spec/issues/1423)) -### Appendices +## Appendices No significant changes. -### Internal Changes/Tooling +## Internal Changes/Tooling Spec Clarifications diff --git a/content/changelog/v1.7.md b/content/changelog/v1.7.md index 61ade090..8cbe1985 100644 --- a/content/changelog/v1.7.md +++ b/content/changelog/v1.7.md @@ -1,4 +1,10 @@ --- +title: v1.7 Changelog +linkTitle: v1.7 +type: docs +outputs: + - html + - checklist date: 2023-05-25T09:47:21-06:00 --- -## v1.7 - +
      Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.7
      Release dateMay 25, 2023
      Checklistchecklist.md
      -### Client-Server API +## Client-Server API New Endpoints @@ -63,7 +68,7 @@ Variables: - Add missing `knock_restricted` join rule to the `m.room.join_rules` schema. ([#1535](https://github.com/matrix-org/matrix-spec/issues/1535)) -### Server-Server API +## Server-Server API Spec Clarifications @@ -75,7 +80,7 @@ Variables: - Remove extraneous `age_ts` field from the reference hash calculation section. ([#1536](https://github.com/matrix-org/matrix-spec/issues/1536)) -### Application Service API +## Application Service API New Endpoints @@ -97,7 +102,7 @@ Variables: - Fix various typos throughout the specification. ([#1447](https://github.com/matrix-org/matrix-spec/issues/1447)) -### Identity Service API +## Identity Service API Spec Clarifications @@ -106,13 +111,13 @@ Variables: - Corrections to the response format of `/_matrix/identity/v2/store-invite`. ([#1486](https://github.com/matrix-org/matrix-spec/issues/1486)) -### Push Gateway API +## Push Gateway API No significant changes. -### Room Versions +## Room Versions Spec Clarifications @@ -121,7 +126,7 @@ No significant changes. - Clarifications of event ID formats in early room versions ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484)) -### Appendices +## Appendices Spec Clarifications @@ -132,7 +137,7 @@ No significant changes. - Clarifications of event ID formats in early room versions. ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484)) -### Internal Changes/Tooling +## Internal Changes/Tooling Spec Clarifications diff --git a/content/changelog/v1.8.md b/content/changelog/v1.8.md index 0d25f6a2..2ff0e7a4 100644 --- a/content/changelog/v1.8.md +++ b/content/changelog/v1.8.md @@ -1,4 +1,10 @@ --- +title: v1.8 Changelog +linkTitle: v1.8 +type: docs +outputs: + - html + - checklist date: 2023-08-23T09:23:53-06:00 --- -## v1.8 - +
      Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.8
      Release dateAugust 23, 2023
      Checklistchecklist.md
      -### Client-Server API +## Client-Server API **Backwards Compatible Changes** @@ -36,7 +41,7 @@ Variables: - Fix various typos throughout the specification. ([#1597](https://github.com/matrix-org/matrix-spec/issues/1597)) -### Server-Server API +## Server-Server API **Deprecations** @@ -58,26 +63,26 @@ Variables: - Switch to ordered list for server name resolution steps. ([#1623](https://github.com/matrix-org/matrix-spec/issues/1623)) -### Application Service API +## Application Service API **Spec Clarifications** - Fix type of custom `fields` in thirdparty lookup queries. ([#1584](https://github.com/matrix-org/matrix-spec/issues/1584)) -### Identity Service API +## Identity Service API **Spec Clarifications** - Make sure examples types match schema in definitions. ([#1563](https://github.com/matrix-org/matrix-spec/issues/1563)) -### Push Gateway API +## Push Gateway API No significant changes. -### Room Versions +## Room Versions **Backwards Compatible Changes** @@ -88,7 +93,7 @@ No significant changes. - Update the redaction rules in room version 11, as per [MSC2176](https://github.com/matrix-org/matrix-spec-proposals/pull/2176) and [MSC3821](https://github.com/matrix-org/matrix-spec-proposals/pull/3821). ([#1604](https://github.com/matrix-org/matrix-spec/issues/1604)) -### Appendices +## Appendices **Backwards Compatible Changes** @@ -99,7 +104,7 @@ No significant changes. - Clarify spec re canonical JSON to handle negative-zero; also, give an example of negative-zero and a large power of ten. ([#1573](https://github.com/matrix-org/matrix-spec/issues/1573)) -### Internal Changes/Tooling +## Internal Changes/Tooling **Backwards Compatible Changes** diff --git a/content/changelog/v1.9.md b/content/changelog/v1.9.md index 46a79f37..6679dd98 100644 --- a/content/changelog/v1.9.md +++ b/content/changelog/v1.9.md @@ -1,4 +1,10 @@ --- +title: v1.9 Changelog +linkTitle: v1.9 +type: docs +outputs: + - html + - checklist date: 2023-11-29T10:04:26-07:00 --- -## v1.9 - +
      Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.9
      Release dateNovember 29, 2023
      Checklistchecklist.md
      -### Client-Server API +## Client-Server API **Backwards Compatible Changes** @@ -38,7 +43,7 @@ Variables: - Clarify that thread roots are not considered within the thread. ([#1677](https://github.com/matrix-org/matrix-spec/issues/1677)) -### Server-Server API +## Server-Server API **Spec Clarifications** @@ -47,27 +52,27 @@ Variables: - Clarify that federation requests for non-local users are invalid. ([#1672](https://github.com/matrix-org/matrix-spec/issues/1672)) -### Application Service API +## Application Service API No significant changes. -### Identity Service API +## Identity Service API No significant changes. -### Push Gateway API +## Push Gateway API No significant changes. -### Room Versions +## Room Versions No significant changes. -### Appendices +## Appendices **Spec Clarifications** @@ -75,7 +80,7 @@ No significant changes. - Fix various typos throughout the specification. ([#1652](https://github.com/matrix-org/matrix-spec/issues/1652)) -### Internal Changes/Tooling +## Internal Changes/Tooling **Backwards Compatible Changes** diff --git a/layouts/_default/single.checklist.md b/layouts/_default/single.checklist.md new file mode 100644 index 00000000..f885a316 --- /dev/null +++ b/layouts/_default/single.checklist.md @@ -0,0 +1,4 @@ +{{ .RawContent + | replaceRE "\n- " "\n- [ ] " + | replaceRE "\n?" "" + | replaceRE "Checklist.*\n" "" }} diff --git a/layouts/shortcodes/changelog/changelog-description.html b/layouts/shortcodes/changelog/changelog-description.html deleted file mode 100644 index 3c719725..00000000 --- a/layouts/shortcodes/changelog/changelog-description.html +++ /dev/null @@ -1,19 +0,0 @@ -{{/* - - This template is used to provide different content for the unstable spec - version and for a versioned release. - -*/}} - -{{ $status := .Site.Params.version.status }} - -{{ if eq $status "unstable"}} - -

      This is the unstable version of the Matrix specification.

      -

      This changelog lists changes made since the last release of the specification.

      - -{{ else }} - -

      This is version v{{ .Site.Params.version.major }}.{{ .Site.Params.version.minor }} of the Matrix specification.

      - -{{ end }} diff --git a/layouts/shortcodes/changelog/changelogs.html b/layouts/shortcodes/changelog/changelogs.html index f42963da..2c201a1b 100644 --- a/layouts/shortcodes/changelog/changelogs.html +++ b/layouts/shortcodes/changelog/changelogs.html @@ -1,10 +1,8 @@ {{/* - This template is used to render all of the changelog sections under - "content/changelogs" + This template is used to redirect the changelog section under + "content/changelogs" to the latest version's changelog page. */}} -{{ with .Page.Resources.Match "*.md" }} -{{ range ((sort . "Params.date" "desc")) }} -{{ .RenderShortcodes }} -{{ end }} +{{ with index .Page.RegularPages.ByDate.Reverse 0 }} + {{ end }} diff --git a/scripts/generate-changelog.sh b/scripts/generate-changelog.sh index 45132619..9447dac5 100755 --- a/scripts/generate-changelog.sh +++ b/scripts/generate-changelog.sh @@ -16,24 +16,38 @@ rm -f rendered.md # Generate changelog towncrier --yes +if [ "$VERSION" = "vUNSTABLE" ]; then + TITLE="Changes since last release" + LINKTITLE="Unstable" + FILENAME="unstable.md" +else + TITLE="$VERSION Changelog" + LINKTITLE="$VERSION" + FILENAME="$VERSION.md" +fi + { # Prepare the header # We include the generation date in the front matter so that we can use it # to sort the changelogs at build time. cat < ../content/changelog/$VERSION.md +} > ../content/changelog/$FILENAME # Cleanup rm -v rendered.md From 938022b1ff671e6c862b3d71cf8c3c470ef40f90 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 30 Sep 2024 14:16:40 +0200 Subject: [PATCH 67/70] Exclude checklists from alternate output formats (#1954) --- changelogs/internal/newsfragments/1954.clarification | 1 + config.toml | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/internal/newsfragments/1954.clarification diff --git a/changelogs/internal/newsfragments/1954.clarification b/changelogs/internal/newsfragments/1954.clarification new file mode 100644 index 00000000..c0b1bdb4 --- /dev/null +++ b/changelogs/internal/newsfragments/1954.clarification @@ -0,0 +1 @@ +Exclude markdown checklists from alternate output formats. diff --git a/config.toml b/config.toml index b9a66cb8..ebead0e2 100644 --- a/config.toml +++ b/config.toml @@ -146,3 +146,4 @@ sidebar_menu_compact = true mediaType = "text/markdown" isPlainText = true baseName = "checklist" + notAlternative = true From c8ad740ba4c0e6f28638d7aa9b1f9beba7e90e69 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 30 Sep 2024 18:29:55 +0200 Subject: [PATCH 68/70] Use relative permalink to redirect to latest changelog (#1956) --- changelogs/internal/newsfragments/1956.clarification | 1 + layouts/shortcodes/changelog/changelogs.html | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/internal/newsfragments/1956.clarification diff --git a/changelogs/internal/newsfragments/1956.clarification b/changelogs/internal/newsfragments/1956.clarification new file mode 100644 index 00000000..6b6213fc --- /dev/null +++ b/changelogs/internal/newsfragments/1956.clarification @@ -0,0 +1 @@ +Use relative permalink to redirect to latest changelog. diff --git a/layouts/shortcodes/changelog/changelogs.html b/layouts/shortcodes/changelog/changelogs.html index 2c201a1b..96a82860 100644 --- a/layouts/shortcodes/changelog/changelogs.html +++ b/layouts/shortcodes/changelog/changelogs.html @@ -4,5 +4,5 @@ */}} {{ with index .Page.RegularPages.ByDate.Reverse 0 }} - + {{ end }} From 9486237f1bef581dfca7a727b57656138a1af2ef Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 30 Sep 2024 19:36:17 +0200 Subject: [PATCH 69/70] Allow guests to access media (MSC4189) (#1959) MSC: https://github.com/matrix-org/matrix-spec-proposals/pull/4189 --- changelogs/client_server/newsfragments/1959.feature | 1 + content/client-server-api/modules/guest_access.md | 5 ++++- 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1959.feature diff --git a/changelogs/client_server/newsfragments/1959.feature b/changelogs/client_server/newsfragments/1959.feature new file mode 100644 index 00000000..0fdd25f1 --- /dev/null +++ b/changelogs/client_server/newsfragments/1959.feature @@ -0,0 +1 @@ +Guest accounts can now download/thumbnail media from the new authenticated endpoints, as per [MSC4189](https://github.com/matrix-org/matrix-spec-proposals/pull/4189). \ No newline at end of file diff --git a/content/client-server-api/modules/guest_access.md b/content/client-server-api/modules/guest_access.md index 873908bb..86ac031a 100644 --- a/content/client-server-api/modules/guest_access.md +++ b/content/client-server-api/modules/guest_access.md @@ -33,7 +33,7 @@ rather than allowing all homeservers to enforce the rules on each other. #### Client behaviour The following API endpoints are allowed to be accessed by guest accounts -for retrieving events: +for retrieving events and associated media: * [GET /rooms/{roomId}/state](#get_matrixclientv3roomsroomidstate) * [GET /rooms/{roomId}/context/{eventId}](#get_matrixclientv3roomsroomidcontexteventid) @@ -44,6 +44,9 @@ for retrieving events: * [GET /rooms/{roomId}/initialSync](#get_matrixclientv3roomsroomidinitialsync) * [GET /sync](#get_matrixclientv3sync) * [GET /events](#get_matrixclientv3events) as used for room previews. +* {{< added-in v="1.12" >}} [GET /media/download/{serverName}/{mediaId}](#get_matrixclientv1mediadownloadservernamemediaid) +* {{< added-in v="1.12" >}} [GET /media/download/{serverName}/{mediaId}/{fileName}](#get_matrixclientv1mediadownloadservernamemediaidfilename) +* {{< added-in v="1.12" >}} [GET /media/thumbnail/{serverName}/{mediaId}](#get_matrixclientv1mediathumbnailservernamemediaid) The following API endpoints are allowed to be accessed by guest accounts for sending events: From 27b4cdcc9e9fe708605f9579c2b294450d9e8653 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 1 Oct 2024 15:39:57 +0200 Subject: [PATCH 70/70] Add the `deprecated` field to OpenAPI definitions and JSON Schemas (#1940) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I did a quick search of the "deprecated" word in the data folder and set the field where the description says that a property is deprecated. This does not change the rendering of the spec because the descriptions already talk about the deprecation, but it can be used by tools that rely on the OpenAPI definitions and JSON Schemas. Signed-off-by: Kévin Commaille --- changelogs/internal/newsfragments/1940.clarification | 1 + data/api/client-server/joining.yaml | 1 + data/api/client-server/knocking.yaml | 1 + data/api/client-server/login.yaml | 4 ++++ data/api/client-server/registration.yaml | 1 + data/event-schemas/schema/m.room.encrypted.yaml | 2 ++ 6 files changed, 10 insertions(+) create mode 100644 changelogs/internal/newsfragments/1940.clarification diff --git a/changelogs/internal/newsfragments/1940.clarification b/changelogs/internal/newsfragments/1940.clarification new file mode 100644 index 00000000..15885433 --- /dev/null +++ b/changelogs/internal/newsfragments/1940.clarification @@ -0,0 +1 @@ +Add the `deprecated` field to properties of OpenAPI definitions and JSON Schemas. diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml index aead420c..dda0d867 100644 --- a/data/api/client-server/joining.yaml +++ b/data/api/client-server/joining.yaml @@ -139,6 +139,7 @@ paths: type: string - in: query name: server_name + deprecated: true x-changedInMatrixVersion: "1.12": |- This parameter has been deprecated in favour of `via` and will be removed in diff --git a/data/api/client-server/knocking.yaml b/data/api/client-server/knocking.yaml index 39a928e8..085aa74f 100644 --- a/data/api/client-server/knocking.yaml +++ b/data/api/client-server/knocking.yaml @@ -50,6 +50,7 @@ paths: type: string - in: query name: server_name + deprecated: true x-changedInMatrixVersion: "1.12": |- This parameter has been deprecated in favour of `via` and will be removed in diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index b37d1742..385eb33b 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -119,15 +119,18 @@ paths: $ref: definitions/user_identifier.yaml user: type: string + deprecated: true description: The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of `identifier`. medium: type: string + deprecated: true description: When logging in using a third-party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`. address: type: string + deprecated: true description: Third-party identifier for the user. Deprecated in favour of `identifier`. password: @@ -194,6 +197,7 @@ paths: x-addedInMatrixVersion: "1.3" home_server: type: string + deprecated: true description: |- The server_name of the homeserver on which the account has been registered. diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index 84aef5b1..1dd314b8 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -169,6 +169,7 @@ paths: x-addedInMatrixVersion: "1.3" home_server: type: string + deprecated: true description: |- The server_name of the homeserver on which the account has been registered. diff --git a/data/event-schemas/schema/m.room.encrypted.yaml b/data/event-schemas/schema/m.room.encrypted.yaml index 95e05ff7..f608a6e2 100644 --- a/data/event-schemas/schema/m.room.encrypted.yaml +++ b/data/event-schemas/schema/m.room.encrypted.yaml @@ -41,6 +41,7 @@ properties: Olm event. For more details, see [Messaging Algorithms](/client-server-api/#messaging-algorithms). sender_key: type: string + deprecated: true x-changedInMatrixVersion: "1.3": |- Previously this field was required, however given it offers no additional @@ -56,6 +57,7 @@ properties: for more information. device_id: type: string + deprecated: true x-changedInMatrixVersion: "1.3": |- Previously this field was required for Megolm messages, however given it