wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #2087 from matrix-org/travis/1.0/events-are-extensible

Browse source 
Reorganize event structure in c2s spec and clarify event capabilities
This commit is contained in:
Travis Ralston 2019-06-11 09:55:17 -06:00 • committed by GitHub
commit 2d18f81807
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 92 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2087.clarification Normal file
View file

@ -0,0 +1 @@
Reorganize information about events into a common section.

3
event-schemas/schema/core-event-schema/room_event.yaml
View file

@ -1,7 +1,6 @@
allOf:
- $ref: sync_room_event.yaml
description: In addition to the Event fields, Room Events have the following additional
fields.
description: Room Events have the following fields.
properties:
room_id:
description: |-

3
event-schemas/schema/core-event-schema/state_event.yaml
View file

@ -1,7 +1,6 @@
allOf:
- $ref: room_event.yaml
- $ref: sync_state_event.yaml
description: In addition to the Room Event fields, State Events have the following
additional fields.
description: State Events have the following fields.
title: State Event
type: object

1
scripts/templating/matrix_templates/units.py
View file

@ -750,6 +750,7 @@ class MatrixUnits(Units):
with open(filepath, encoding="utf-8") as f:
event_schema = yaml.load(f, OrderedLoader)
event_schema = resolve_references(filepath, event_schema)
schema_info = process_data_type(
event_schema,

82
specification/client_server_api.rst
View file

@ -1430,6 +1430,88 @@ the event ``type`` key SHOULD follow the Java package naming convention,
e.g. ``com.example.myapp.event``. This ensures event types are suitably
namespaced for each application and reduces the risk of clashes.
.. Note::
Events are not limited to the types defined in this specification. New or custom
event types can be created on a whim using the Java package naming convention.
For example, a ``com.example.game.score`` event can be sent by clients and other
clients would receive it through Matrix, assuming the client has access to the
``com.example`` namespace.
Note that the structure of these events may be different than those in the
server-server API.
{{common_event_fields}}
{{common_room_event_fields}}
.. This is normally where we'd put the common_state_event_fields variable for the
.. magic table of what makes up a state event, however the table is verbose in our
.. custom rendering of swagger. To combat this, we just hardcode this particular
.. table.
State Event Fields
++++++++++++++++++
In addition to the fields of a Room Event, State Events have the following fields.
+--------------+--------------+-------------------------------------------------------------+
| Key | Type | Description |
+==============+==============+=============================================================+
| state_key | string | **Required.** A unique key which defines the overwriting |
| | | semantics for this piece of room state. This value is often |
| | | a zero-length string. The presence of this key makes this |
| | | event a State Event. State keys starting with an ``@`` are |
| | | reserved for referencing user IDs, such as room members. |
| | | With the exception of a few events, state events set with |
| | | a given user's ID as the state key MUST only be set by that |
| | | user. |
+--------------+--------------+-------------------------------------------------------------+
| prev_content | EventContent | Optional. The previous ``content`` for this event. If there |
| | | is no previous content, this key will be missing. |
+--------------+--------------+-------------------------------------------------------------+
Size limits
~~~~~~~~~~~
The complete event MUST NOT be larger than 65535 bytes, when formatted as a
`PDU for the Server-Server protocol <../server_server/%SERVER_RELEASE_LABEL%#pdus>`_,
including any signatures, and encoded as `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.
- ``state_key`` MUST NOT exceed 255 bytes.
- ``type`` MUST NOT exceed 255 bytes.
- ``event_id`` MUST NOT exceed 255 bytes.
Some event types have additional size restrictions which are specified in
the description of the event. Additional keys have no limit other than that
implied by the total 65 KB limit on events.
Room Events
~~~~~~~~~~~
.. NOTE::
This section is a work in progress.
This specification outlines several standard event types, all of which are
prefixed with ``m.``
{{m_room_aliases_event}}
{{m_room_canonical_alias_event}}
{{m_room_create_event}}
{{m_room_join_rules_event}}
{{m_room_member_event}}
{{m_room_power_levels_event}}
{{m_room_redaction_event}}
Syncing
~~~~~~~

73
specification/events.rst
View file

@ -1,73 +0,0 @@
.. Copyright 2016 OpenMarket Ltd
..
.. 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.
Event Structure
===============
All communication in Matrix is expressed in the form of data objects called
Events. These are the fundamental building blocks common to the client-server,
server-server and application-service APIs, and are described below.
Note that the structure of these events may be different than those in the
server-server API.
{{common_event_fields}}
{{common_room_event_fields}}
{{common_state_event_fields}}
Size limits
-----------
The complete event MUST NOT be larger than 65535 bytes, when formatted as a
`PDU for the Server-Server protocol <../server_server/%SERVER_RELEASE_LABEL%#pdus>`_,
including any signatures, and encoded as `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.
- ``state_key`` MUST NOT exceed 255 bytes.
- ``type`` MUST NOT exceed 255 bytes.
- ``event_id`` MUST NOT exceed 255 bytes.
Some event types have additional size restrictions which are specified in
the description of the event. Additional keys have no limit other than that
implied by the total 65 KB limit on events.
Room Events
-----------
.. NOTE::
This section is a work in progress.
This specification outlines several standard event types, all of which are
prefixed with ``m.``
{{m_room_aliases_event}}
{{m_room_canonical_alias_event}}
{{m_room_create_event}}
{{m_room_join_rules_event}}
{{m_room_member_event}}
{{m_room_power_levels_event}}
{{m_room_redaction_event}}
.. _`Canonical JSON`: ../appendices.html#canonical-json

6
specification/index.rst
View file

@ -348,6 +348,12 @@ pushed over federation to the participating servers in a room, currently using
full mesh topology. Servers may also request backfill of events over federation
from the other servers participating in a room.
.. Note::
Events are not limited to the types defined in this specification. New or custom
event types can be created on a whim using the Java package naming convention.
For example, a ``com.example.game.score`` event can be sent by clients and other
clients would receive it through Matrix, assuming the client has access to the
``com.example`` namespace.
Room Aliases
++++++++++++

1
specification/targets.yaml
View file

@ -5,7 +5,6 @@ targets:
client_server:
files:
- client_server_api.rst
- { 1: events.rst }
- { 1: modules.rst }
- { 2: feature_profiles.rst }
- { 2: "group:modules" } # reference a group of files