archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases 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
pull/977/head
Travis Ralston 6 years ago committed by GitHub
parent 8ac555f870 c9345ba6a3
commit 2d18f81807
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 92 additions and 78 deletions
Show Stats Download Patch File Download Diff File

1
changelogs/client_server/newsfragments/2087.clarification
Unescape Escape View File

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

3
event-schemas/schema/core-event-schema/room_event.yaml
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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

Write Preview
Loading…
Cancel
Save