From f295e828dc3107260a7979c40175442bf3a7fdc4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 12 Oct 2021 12:04:27 -0600 Subject: [PATCH] Fix non-permanent links in MSCs to withstand time (#3422) As "unstable" changes and "latest" becomes no more, these sorts of links should be updated to reference the approximate section they intended to reference at the time of writing. This change tries to link up the relevant bits for the time of the proposal, though it's not a perfect match. Some MSCs were brought into the spec before an API version could be assigned to the "old" text, so github permalinks are used instead. --- proposals/1442-state-resolution.md | 2 +- proposals/1708-well-known-for-federation.md | 2 +- proposals/1711-x509-for-federation.md | 4 +- proposals/1719-olm_unwedging.md | 2 +- proposals/1819-remove-presence-lists.md | 6 +-- ...ove-prev_event-from-essential-keys-list.md | 2 +- proposals/2312-matrix-uri.md | 40 +++++++++---------- proposals/2320-identity-versions.md | 2 +- ...-starting-verifications-without-request.md | 2 +- .../3173-expose-stripped-state-events.md | 12 +++--- 10 files changed, 37 insertions(+), 37 deletions(-) diff --git a/proposals/1442-state-resolution.md b/proposals/1442-state-resolution.md index 97cd66ba..848fe931 100644 --- a/proposals/1442-state-resolution.md +++ b/proposals/1442-state-resolution.md @@ -571,7 +571,7 @@ rejected. [^1]: In the current room protocol these are: the create event, power levels, membership, join rules and third party invites. See the - [spec](https://matrix.org/docs/spec/server_server/unstable.html#pdu-fields). + [spec](https://github.com/matrix-org/matrix-doc/blob/7cb918407dc8c505c67c750578c63b43042c8425/specification/server_server_api.rst#41pdu-fields). [^2]: In the current protocol these are: power levels, kicks, bans and join rules. diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md index c9f90631..79799fae 100644 --- a/proposals/1708-well-known-for-federation.md +++ b/proposals/1708-well-known-for-federation.md @@ -17,7 +17,7 @@ with a `.well-known` lookup. ## Proposal For reference, the current [specification for resolving server -names](https://matrix.org/docs/spec/server_server/unstable.html#resolving-server-names) +names](https://github.com/matrix-org/matrix-doc/blob/6dab4b28f80f5beeb1d4f475ddc624cf9e7ad085/specification/server_server_api.rst#21resolving-server-names) is as follows: 1. If the hostname is an IP literal, then that IP address should be used, diff --git a/proposals/1711-x509-for-federation.md b/proposals/1711-x509-for-federation.md index e97b8532..7fd90560 100644 --- a/proposals/1711-x509-for-federation.md +++ b/proposals/1711-x509-for-federation.md @@ -65,7 +65,7 @@ approach for servers whose TLS certificates fail validation. However, this fallback will be strictly time-limited, and Matrix S2S spec r0 will not accept self-signed certificates, nor will it include the `tls_fingerprints` property of the -[`/_matrix/key/v2`](https://matrix.org/docs/spec/server_server/unstable.html#retrieving-server-keys) +[`/_matrix/key/v2`](https://github.com/matrix-org/matrix-doc/blob/6dab4b28f80f5beeb1d4f475ddc624cf9e7ad085/specification/server_server_api.rst#23retrieving-server-keys) endpoints. Synapse 1.0 will not accept self-signed certificates by default. The `matrix.org` team will proactively attempt to reach out to homeserver @@ -97,7 +97,7 @@ intercepted by a MitM who can control the DNS response for the `SRV` record (perhaps via cache-poisoning or falsifying DNS responses). This will be in line with the current -[requirements](https://matrix.org/docs/spec/server_server/unstable.html#resolving-server-names) +[requirements](https://github.com/matrix-org/matrix-doc/blob/6dab4b28f80f5beeb1d4f475ddc624cf9e7ad085/specification/server_server_api.rst#21resolving-server-names) in the Federation API specification for the `Host`, and by implication, the TLS Server Name Indication [2](#f2). It is also consistent with the recommendations of diff --git a/proposals/1719-olm_unwedging.md b/proposals/1719-olm_unwedging.md index dffdc8b1..9141d3a8 100644 --- a/proposals/1719-olm_unwedging.md +++ b/proposals/1719-olm_unwedging.md @@ -26,7 +26,7 @@ already created one for that given device in the past 1 hour. Clients may wish to take steps to mitigate the loss of the undecryptable messages. For example, megolm sessions that were sent using the old session would have been lost, so the client can send -[`m.room_key_request`](https://matrix.org/docs/spec/client_server/latest.html#m-room-key-request) +[`m.room_key_request`](https://matrix.org/docs/spec/client_server/r0.6.1.html#m-room-key-request) messages to re-request any megolm sessions that it is unable to decrypt. The spec currently says, "If a client has multiple sessions established with diff --git a/proposals/1819-remove-presence-lists.md b/proposals/1819-remove-presence-lists.md index 7c542509..f82ebac5 100644 --- a/proposals/1819-remove-presence-lists.md +++ b/proposals/1819-remove-presence-lists.md @@ -35,9 +35,9 @@ CS API: Remove /_matrix/client/r0/presence/list/{userId}](https://matrix.org/docs/spec/client_server/r0.4.0.html#get-matrix-client-r0-presence-list-userid) SS API: Remove - * [m.presence_invite](https://matrix.org/docs/spec/server_server/unstable.html#m-presence-invite-schema) - * [m.presence_accept](https://matrix.org/docs/spec/server_server/unstable.html#m-presence-accept-schema) - * [m.presence_deny](https://matrix.org/docs/spec/server_server/unstable.html#m-presence-deny-schema) + * [m.presence_invite](https://github.com/matrix-org/matrix-doc/blob/8b65da1cf6fce5f657a2a46b5c6c8bcc24d32ae3/api/server-server/definitions/event-schemas/m.presence_invite.yaml) + * [m.presence_accept](https://github.com/matrix-org/matrix-doc/blob/8b65da1cf6fce5f657a2a46b5c6c8bcc24d32ae3/api/server-server/definitions/event-schemas/m.presence_accept.yaml) + * [m.presence_deny](https://github.com/matrix-org/matrix-doc/blob/8b65da1cf6fce5f657a2a46b5c6c8bcc24d32ae3/api/server-server/definitions/event-schemas/m.presence_deny.yaml) ## Tradeoffs diff --git a/proposals/1954-remove-prev_event-from-essential-keys-list.md b/proposals/1954-remove-prev_event-from-essential-keys-list.md index 735fac01..ccaab34f 100644 --- a/proposals/1954-remove-prev_event-from-essential-keys-list.md +++ b/proposals/1954-remove-prev_event-from-essential-keys-list.md @@ -27,7 +27,7 @@ implementations) have not implemented the bug and already omit ## Tradeoffs When sending events over federation the events are [hashed and -signed](https://matrix.org/docs/spec/server_server/unstable.html#adding-hashes-and-signatures-to-outgoing-events), +signed](https://matrix.org/docs/spec/server_server/r0.1.0#adding-hashes-and-signatures-to-outgoing-events), this involves operating not only on the original event but also the redacted form of the event. The redacted hash and redacted signed event are necessary if the event is ever redacted in future. As a result, any change of the essential diff --git a/proposals/2312-matrix-uri.md b/proposals/2312-matrix-uri.md index 45bb2187..c66015b4 100644 --- a/proposals/2312-matrix-uri.md +++ b/proposals/2312-matrix-uri.md @@ -2,7 +2,7 @@ This is a proposal of a URI scheme to identify Matrix resources in a wide range of applications (web, desktop, or mobile) both throughout Matrix software -and (especially) outside it. It supersedes +and (especially) outside it. It supersedes [MSC455](https://github.com/matrix-org/matrix-doc/issues/455) in order to continue the discussion in the modern GFM style. @@ -49,7 +49,7 @@ This MSC does not introduce new Matrix entities, nor API endpoints - it merely defines a mapping between URIs with the scheme name `matrix:` and Matrix identifiers, as well as operations on them. The MSC should be sufficient to produce an implementation that would convert Matrix URIs to -a series of [CS API](https://matrix.org/docs/spec/client_server/latest) calls, +a series of [CS API](https://matrix.org/docs/spec/client_server/r0.6.1) calls, entirely on the client side. It is recognised, however, that most of the URI processing logic can and should (eventually) be on the server side in order to facilitate adoption of Matrix URIs; further MSCs are needed @@ -173,7 +173,7 @@ before sending the request to the server (more on that below). #### Scheme name The proposed scheme name is `matrix`. [RFC 7595](https://tools.ietf.org/html/rfc7595) states: - + if there’s one-to-one correspondence between a service name and a scheme name then the scheme name should be the same as the service name. @@ -231,7 +231,7 @@ The path component consists of 1 or more descriptors separated by a slash extensions. This MSC only proposes mappings along `type-qualifier id-without-sigil` syntax; -`nonid-segment` is unused and reserved for future use. +`nonid-segment` is unused and reserved for future use. For the sake of integrity future `nonid-segment` extensions must follow [the ABNF for `segment-nz` as defined in RFC 3986](https://tools.ietf.org/html/rfc3986#appendix-A). @@ -276,7 +276,7 @@ This notably exempts `:` from percent-encoding but includes `/`. See the rationale behind dropping sigils and the respective up/downsides in "Discussion points and tradeoffs" as well as "Alternatives" below. - + #### Query Matrix URI can optionally have @@ -308,7 +308,7 @@ describes two possible actions: clients supporting [canonical direct chats](https://github.com/matrix-org/matrix-doc/pull/2199) SHOULD open the canonical direct chat. - + For both actions, where applicable, client applications SHOULD ask for user confirmation or at least notify the user before joining or creating a new room. Conversely, no additional confirmation/notification is necessary when @@ -327,7 +327,7 @@ perform the default operation suggested by this MSC (see below); e.g., the client may be unable to display a room before joining it, while the URI doesn't have `action=join`. In these cases client applications are free to do what's best for user experience (e.g., suggest joining the room), even if that -means performing an action on a URI with no `action` in the query. +means performing an action on a URI with no `action` in the query. The routing query (`via=`) indicates servers that are likely involved in the room (see also @@ -366,7 +366,7 @@ across the client ecosystem. The reference algorithm of parsing a Matrix URI follows. Note that, although clients are encouraged to use lower-case strings in their URIs, all string -comparisons are case-INsensitive. +comparisons are case-INsensitive. 1. Parse the URI into main components (`scheme name`, `authority`, `path`, `query`, and `fragment`), decoding special or international characters @@ -386,7 +386,7 @@ comparisons are case-INsensitive. fail parsing; the Matrix URI is invalid. 1. To construct the top-level (primary) Matrix identifier: - + a. Pick the leftmost segment of `path` until `/` (path segment) and match it against the following list to produce `sigil-1`: - `u` (or, optionally, `user` - see "Path") -> `@` @@ -397,7 +397,7 @@ comparisons are case-INsensitive. b. Pick the next (2nd) leftmost path segment: - if the segment is empty, fail parsing; - - otherwise, percent-decode the segment (unless the initial URI parse + - otherwise, percent-decode the segment (unless the initial URI parse has already done that) and make `mxid-1` by prepending `sigil-1`. 1. If `sigil-1` is `!` or `#` and the URI path has exactly 4 segments, @@ -408,19 +408,19 @@ comparisons are case-INsensitive. - if the segment is exactly `e` (or, optionally, `event`), proceed; - otherwise, including the case of an empty segment (trailing `/`, e.g.), fail parsing. - + b. Pick the next (4th) leftmost path segment: - if the segment is empty, fail parsing; - - otherwise, percent-decode the segment (unless the initial URI parse + - otherwise, percent-decode the segment (unless the initial URI parse has already done that) and make `mxid-2` by prepending `$`. - + 1. Split the `query` into items separated by `&` character; several subsequent `&` characters delimit empty items, ignored by this algorithm. - + a. If `query` contains one or more items starting with `via=`: for each item, treat the rest of the item as a percent-encoded homeserver name to be used in [routing](https://matrix.org/docs/spec/appendices#routing). - + b. If `query` contains one or more items starting with `action=`: treat _the last_ such item as an instruction, as this proposal defines in [query](#query). @@ -467,7 +467,7 @@ For room and user identifiers (including room aliases): - `prefix-1`; - the remainder of identifier (`id without sigil`), percent-encoded as per [RFC 3986](https://tools.ietf.org/html/rfc3986). - + For event identifiers (assuming they need the room context, see [MSC2695](https://github.com/matrix-org/matrix-doc/pull/2695) and [MSC2779](https://github.com/matrix-org/matrix-doc/issues/2779) that @@ -477,7 +477,7 @@ may change this): 2. Append to the result of previous step: - literal `e/`; - the event id after removing the sigil (`$`) and percent-encoding. - + Clients MUST implement proper percent-encoding of the identifiers; there's no liberty similar to that of matrix.to. @@ -507,7 +507,7 @@ extensions. Here are a few ideas: _routing over federation_ (the case for `via=` query items), as it would be against the spirit of RFC 3986. The authority part can be used in cases when a given Matrix entity is only available from certain servers (the case of - closed federations or non-federating servers). + closed federations or non-federating servers). While being a part of the original proposal in an attempt to address [the respective case](https://github.com/matrix-org/matrix-doc/issues/2309), @@ -572,7 +572,7 @@ further discussion should happen in GitHub comments. be considered a "document". Each event can be retrieved from the server individually, so each event can be viewed as a self-contained document. When/if URI processing is shifted to the server-side, servers are not even - going to receive fragments (as per RFC 3986), which is why usage of + going to receive fragments (as per RFC 3986), which is why usage of fragments to remove the need for percent-encoding in other identifiers would lead to URIs that cannot be resolved on servers. Effectively, all clients would have to implement full URI processing with no chance @@ -648,7 +648,7 @@ to meet the URN's hierarchical order would look confusing for Matrix users (as in example above - is `room` a part of the identifier or the type signifier?). -#### "Full REST" +#### "Full REST" Yet another alternative considered was to go "full REST" and structure URLs in a more traditional way with serverparts coming first, followed diff --git a/proposals/2320-identity-versions.md b/proposals/2320-identity-versions.md index ded50b3b..e7433916 100644 --- a/proposals/2320-identity-versions.md +++ b/proposals/2320-identity-versions.md @@ -29,7 +29,7 @@ this identity server supports. Its response uses the following format: ## Alternative solutions Another solution which was considered was using the status check endpoint ([`GET -/_matrix/api/v1`](https://matrix.org/docs/spec/identity_service/latest#get-matrix-identity-api-v1)) +/_matrix/api/v1`](https://matrix.org/docs/spec/identity_service/r0.2.0#get-matrix-identity-api-v1)) to serve this information. This solution was discarded because it's using a versioned endpoint, which doesn't make sense to advertise the supported versions of the API to use. diff --git a/proposals/3122-deprecate-starting-verifications-without-request.md b/proposals/3122-deprecate-starting-verifications-without-request.md index 9a00699b..df09ce7f 100644 --- a/proposals/3122-deprecate-starting-verifications-without-request.md +++ b/proposals/3122-deprecate-starting-verifications-without-request.md @@ -1,7 +1,7 @@ # MSC3122: Deprecate starting key verifications without requesting first Currently, the [Key verification -framework](https://spec.matrix.org/unstable/client-server-api/#key-verification-framework) +framework](https://matrix.org/docs/spec/client_server/r0.6.1#key-verification-framework) allows a device to begin a verification via to-device messages by sending an `m.key.verification.start` event without first sending or receiving an `m.key.verification.request` message. (The last sentence of the 5th paragraph diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 830a9388..7c35477c 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -9,7 +9,7 @@ the room in some situations: * If the room has `history_visibility: world_readable`, then anyone can inspect it (by calling `/state` on it). -* Rooms in the [room directory](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-publicrooms) +* Rooms in the [room directory](https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-publicrooms) expose some of their state publicly. * [Invited users](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) and [knocking users](https://github.com/matrix-org/matrix-doc/pull/2403) @@ -29,7 +29,7 @@ to include stripped state events which are useful for displaying the invite to a > the room. The recommended events to include are the join rules, canonical alias, > avatar, and name of the room. -The invited user receives these [stripped state events](https://spec.matrix.org/unstable/client-server-api/#get_matrixclientr0sync) +The invited user receives these [stripped state events](https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-sync) as part of the `/sync` response: > The state of a room that the user has been invited to. These state events may @@ -37,7 +37,7 @@ as part of the `/sync` response: > events do not replace any state that the client already has for the room, for > example if the client has archived the room. -These are sent as part of the [`unsigned` content of the `m.room.member` event](https://spec.matrix.org/unstable/client-server-api/#mroommember) +These are sent as part of the [`unsigned` content of the `m.room.member` event](https://matrix.org/docs/spec/client_server/r0.6.1#m-room-member) containing the invite. [MSC2403: Add "knock" feature](https://github.com/matrix-org/matrix-doc/pull/2403) @@ -141,7 +141,7 @@ This does not seem to weaken the security expectations of either join rule. ### Revisions to the room directory A future MSC could include additional information from the stripped state events -in the [room directory](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-publicrooms). +in the [room directory](https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-publicrooms). The main missing piece seems to be the encryption information, but there may also be other pieces of information to include. @@ -174,7 +174,7 @@ N/A ## Footnotes [1]: No changes are proposed to -[the definition of `history_visibility`](https://matrix.org/docs/spec/client_server/latest#room-history-visibility). +[the definition of `history_visibility`](https://matrix.org/docs/spec/client_server/r0.6.1#room-history-visibility). The state of a room which is `world_readable` is available to anyone. This somewhat implies that the stripped state is also available to anyone, regardless of the join rules, but having a `world_readable`, `invite` room does not seem valuable. [↩](#a1) @@ -190,6 +190,6 @@ from Synapse and generally seems useful for a user to know before joining a roo [↩](#a4) [5]: The room topic (`m.room.topic`) is included as part of the -[room directory](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-publicrooms) +[room directory](https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-publicrooms) response for public rooms. It is also planned to be included as part of [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946) in the spaces summary response. [↩](#a5)