From 946acbf380a4fc510737886f3a94ec024d39f227 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 10 Feb 2019 19:49:55 -0700 Subject: [PATCH 1/3] Clarify v3 event representation in identifier grammar Fixes https://github.com/matrix-org/matrix-doc/issues/1870 Fixes https://github.com/matrix-org/matrix-doc/issues/1869 Fixes https://github.com/matrix-org/matrix-doc/issues/1867 --- specification/appendices/identifier_grammar.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index a0cdf298f..e10348034 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -19,7 +19,7 @@ Identifier Grammar Some identifiers are specific to given room versions, please refer to the `room versions specification`_ for more information. -.. _`room versions specification`: ../index.html#room-versions +.. _`room versions specification`: index.html#room-versions Server Name @@ -234,18 +234,17 @@ A room has exactly one room ID. A room ID has the format:: !opaque_id:domain -An event has exactly one event ID. An event ID has the format:: +An event has exactly one event ID. The format of an event ID depends upon the +`room version specification `_. - $opaque_id:domain - -The ``domain`` of a room/event ID is the `server name`_ of the homeserver which +The ``domain`` of a room ID is the `server name`_ of the homeserver which created the room/event. The domain is used only for namespacing to avoid the risk of clashes of identifiers between different homeservers. There is no implication that the room or event in question is still available at the corresponding homeserver. Event IDs and Room IDs are case-sensitive. They are not meant to be human -readable. +readable. They are intended to be treated as fully opaque strings by clients. .. TODO-spec What is the grammar for the opaque part? https://matrix.org/jira/browse/SPEC-389 @@ -333,6 +332,10 @@ Examples of matrix.to URIs are: * User: ``https://matrix.to/#/@alice:example.org`` * Group: ``https://matrix.to/#/+example:example.org`` +.. Note:: + Event IDs have the potential to contain slashes in some `room versions `_. + No component of the URI should be URL encoded. + .. Note:: Room ID permalinks are unroutable as there is no reliable domain to send requests to upon receipt of the permalink. Clients should do their best route Room IDs to From 42cf72c60f9f5fe6036fc32f65c0cd5d2ed73b6e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 20 Mar 2019 14:43:16 -0600 Subject: [PATCH 2/3] URL encode matrix.to URIs --- .../appendices/identifier_grammar.rst | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index e10348034..17c557d97 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -323,18 +323,27 @@ and instead should perform some sort of action within the client. For example, i the user were to click on a matrix.to URI for a room alias, the client may open a view for the user to participate in the room. +The components of the matrix.to URI (```` and ````) +are to be percent-encoded as per RFC 3986. + Examples of matrix.to URIs are: -* Room alias: ``https://matrix.to/#/#somewhere:example.org`` -* Room: ``https://matrix.to/#/!somewhere:example.org`` -* Permalink by room: ``https://matrix.to/#/!somewhere:example.org/$event:example.org`` +* Room alias: ``https://matrix.to/#/%23somewhere%3Aexample.org`` +* Room: ``https://matrix.to/#/!somewhere%3Aexample.org`` +* Permalink by room: ``https://matrix.to/#/!somewhere%3Aexample.org/%24event%3Aexample.org`` * Permalink by room alias: ``https://matrix.to/#/#somewhere:example.org/$event:example.org`` * User: ``https://matrix.to/#/@alice:example.org`` * Group: ``https://matrix.to/#/+example:example.org`` .. Note:: - Event IDs have the potential to contain slashes in some `room versions `_. - No component of the URI should be URL encoded. + Historically, clients have not produced URIs which are fully encoded. Clients should + try to interpret these cases to the best of their ability. For example, an unencoded + room alias should still work within the client if possible. + +.. Note:: + Clients should be aware that decoding a matrix.to URI may result in extra slashes + appearing due to some `room versions `_. These slashes + should normally be encoded when producing matrix.to URIs, however. .. Note:: Room ID permalinks are unroutable as there is no reliable domain to send requests From 0ec34039e85e777c2b50b532dac9c594513174fe Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 20 Mar 2019 14:44:54 -0600 Subject: [PATCH 3/3] URL encode all the things --- specification/appendices/identifier_grammar.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index 17c557d97..ad0794bde 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -331,9 +331,9 @@ Examples of matrix.to URIs are: * Room alias: ``https://matrix.to/#/%23somewhere%3Aexample.org`` * Room: ``https://matrix.to/#/!somewhere%3Aexample.org`` * Permalink by room: ``https://matrix.to/#/!somewhere%3Aexample.org/%24event%3Aexample.org`` -* Permalink by room alias: ``https://matrix.to/#/#somewhere:example.org/$event:example.org`` -* User: ``https://matrix.to/#/@alice:example.org`` -* Group: ``https://matrix.to/#/+example:example.org`` +* Permalink by room alias: ``https://matrix.to/#/#somewhere:example.org/%24event%3Aexample.org`` +* User: ``https://matrix.to/#/%40alice%3Aexample.org`` +* Group: ``https://matrix.to/#/%2Bexample%3Aexample.org`` .. Note:: Historically, clients have not produced URIs which are fully encoded. Clients should