New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Specify how room versioning works #1516

Merged
merged 3 commits into from Aug 24, 2018
File filter...
Filter file types
Jump to file or symbol
Failed to load files and symbols.
+85 −2
Diff settings

Always

Just for now

@@ -147,14 +147,22 @@ paths:
type: string
description: The invitee's third party identifier.
required: ["id_server", "medium", "address"]
room_version:
type: string
description: |-
The room version to set for the room. If not provided, the homeserver is
to use its configured default. If provided, the homeserver will return a
400 error with the errcode ``M_UNSUPPORTED_ROOM_VERSION`` if it does not
support the room version.
example: "1"
creation_content:
title: CreationContent
type: object
description: |-
Extra keys, such as ``m.federate``, to be added to the content
of the `m.room.create`_ event. The server will clobber the following
keys: ``creator``. Future versions of the specification may allow
the server to clobber other keys.
keys: ``creator``, ``room_version``. Future versions of the specification
may allow the server to clobber other keys.
initial_state:
type: array
description: |-
Copy path View file
@@ -49,6 +49,15 @@ paths:
description: The user ID the join event will be for.
required: true
x-example: "@someone:example.org"
- in: query
type: array
items:
type: string
name: ver
description: |-
The room versions the sending server has support for. Defaults
to ``[1]``.
x-example: ["1", "2"]
responses:
200:
description: |-
@@ -142,6 +151,30 @@ paths:
["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}]
]
}
400:
description: |-
The request is invalid or the room the server is attempting
to join has a version that is not listed in the ``ver``
parameters.
The error should be passed through to clients so that they
may give better feedback to users.
schema:
allOf:
- $ref: "../client-server/definitions/errors/error.yaml"
- type: object
properties:
room_version:
type: string
description: |-
The version of the room. Required if the ``errcode``
is ``M_INCOMPATIBLE_ROOM_VERSION``.
examples:
application/json: {
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",
"error": "Your homeserver does not support the features required to join this room",
"room_version": "3"
}
"/send_join/{roomId}/{eventId}":
put:
summary: Submit a signed join event to a resident server
@@ -0,0 +1 @@
Add support for Room Versions.
@@ -11,6 +11,9 @@ properties:
m.federate:
description: Whether users on other servers can join this room. Defaults to ``true`` if key does not exist.
type: boolean
room_version:
description: The version of the room. Defaults to ``"1"`` if the key does not exist.
type: string
required:
- creator
type: object
@@ -41,6 +41,37 @@ Examples of valid server names are:
* ``[1234:5678::abcd]:5678`` (IPv6 literal with explicit port)


Room Versions
~~~~~~~~~~~~~

Room versions are used to change properties of rooms that may not be compatible
with other servers. For example, changing the rules for event authorization would
cause older servers to potentially end up in a split-brain situation due to them
not understanding the new rules.

A room version is defined as a string of characters which MUST NOT exceed 32
codepoints in length. Room versions MUST NOT be empty and SHOULD contain only
the characters ``a-z``, ``0-9``, ``.``, and ``-``.

Room versions are not intended to be parsed and should be treated as opaque
identifiers. Room versions consisting only of the characters ``0-9`` and ``.``
are reserved for future versions of the Matrix protocol.

The complete grammar for a legal room version is::

room_version = 1*room_version_char
room_version_char = DIGIT
/ %x61-7A ; a-z
/ "-" / "."

Examples of valid room versions are:

* ``1`` (would be reserved by the Matrix protocol)
* ``1.2`` (would be reserved by the Matrix protocol)
* ``1.2-beta``
* ``com.example.version``


Common Identifier Format
~~~~~~~~~~~~~~~~~~~~~~~~

@@ -148,6 +148,13 @@ Some requests have unique error codes:
:``M_SERVER_NOT_TRUSTED``:
The client's request used a third party server, eg. ID server, that this server does not trust.

:``M_UNSUPPORTED_ROOM_VERSION``:
The client's request to create a room used a room version that the server does not support.

:``M_INCOMPATIBLE_ROOM_VERSION``:
The client attempted to join a room that has a version the server does not support. Inspect the
``room_version`` property of the error response for the room's version.

.. _sect:txn_ids:

The client-server API typically uses ``HTTP PUT`` to submit requests with a
ProTip! Use n and p to navigate between commits in a pull request.