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

Reword some of the sentences to make it clearer.

Browse source
This commit is contained in:
Erik Johnston 2014-10-13 11:46:55 +01:00
parent a2d9e8ca22
commit e7599bdf46
1 changed files with 22 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

42
drafts/core_model.rst
View file

@ -9,13 +9,13 @@ Server
Events Events
------ ------
An event is a collection of data (the `payload`) and metadata associated with An event is a collection of data (the `payload`) and metadata to be distributed
it to be distributed across servers and is the primary data unit in Matrix. across servers and is the primary data unit in Matrix. Events are extensible
Events are extensible so that clients and servers can add extra fields to the so that clients and servers can add extra arbitrary fields to both the payload
payload or metadata that are not in this specification. or metadata.
Events are distributed to interested servers upon creation. Historical events Events are distributed to interested servers upon creation. Historical events
may be requested from servers, though servers are not required to produce all may be requested from servers; servers are not required to produce all
or any events requested. or any events requested.
All events have a metadata `type` field that is used by client and servers to All events have a metadata `type` field that is used by client and servers to
@ -23,10 +23,12 @@ determine how the payload should be processed and used. There are a number of
types reserved by the protocol for particular uses, but otherwise types may be types reserved by the protocol for particular uses, but otherwise types may be
defined by applications, clients or servers for their own purposes. defined by applications, clients or servers for their own purposes.
.. TODO : Namespacing of new types.
Graph Graph
~~~~~ ~~~~~
Each event has a list of zero or more `parent` events. These relations form Each event has a list of zero or more `parent` events. These relations form
directed acyclic graphs of events, called `event graphs`. Every event graph has directed acyclic graphs of events called `event graphs`. Every event graph has
a single root event. a single root event.
Event graphs give a partial ordering of events, i.e. given two events one may Event graphs give a partial ordering of events, i.e. given two events one may
@ -50,7 +52,7 @@ event is distributed and referenced by later events, they effectively become
immutable]. immutable].
The payload may also be encrypted by clients, except in the case where the The payload may also be encrypted by clients, except in the case where the
payload need to be interpreted by the servers. A list of event types that payload needs to be interpreted by the servers. A list of event types that
cannot have an encrypted payload are given later. cannot have an encrypted payload are given later.
@ -58,17 +60,17 @@ State
----- -----
Event graphs may have meta information associated with them, called `state`. Event graphs may have meta information associated with them, called `state`.
State can be updated over time by servers or clients, subject to State can be updated over time by servers or clients, subject to
authentication. authorisation.
The state of a graph is split into `sections` that can be atomically updated The state of a graph is split into `sections` that can be atomically updated
independently of each other. independently of each other.
State is stored within the graph itself, and can be computed by looking at the State is stored within the graph itself, and can be computed by looking at the
graph in its entirety. Thus we can define the state at a given event to be the graph in its entirety. We define the state at a given event to be the state of
state of the sub graph of all events "before" and including that event. the sub graph of all events "before" and including that event.
Some sections of the state may determine behaviour of the protocol, including Some sections of the state may determine behaviour of the protocol, including
authorization and distribution. These sections must not be encrypted. authorisation and distribution. These sections must not be encrypted.
State Events State Events
~~~~~~~~~~~~ ~~~~~~~~~~~~
@ -77,9 +79,8 @@ state events hold all the same properties of events, and are part of the event
graph. The payload of the event is the replacement value for the particular graph. The payload of the event is the replacement value for the particular
section of state being updated. section of state being updated.
State events must also include a `state_key` metadata field, which in State events must also include a `state_key` metadata field. The pair of fields
conjunction with the type field defines the section of state that is to be type and state_key uniquely defines the section of state that is to be updated.
updated.
State Resolution State Resolution
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
@ -87,9 +88,10 @@ A given state section may have multiple state events associated with it in a
given graph. A consistent method of selecting which state event takes given graph. A consistent method of selecting which state event takes
precedence is therefore required. precedence is therefore required.
This is done by taking the latest state events, i.e. the set of events that This is done by taking the latest state events, i.e. the set of events that are
either incomparable or after every other event. A state resolution algorithm is either incomparable or after every other event in the graph. A state resolution
then applied to this set to select one. algorithm is then applied to this set to select the single event that takes
precedence.
The state resolution algorithm must be transitive and not depend on server The state resolution algorithm must be transitive and not depend on server
state, as it must consistently select the same event irrespective of the server state, as it must consistently select the same event irrespective of the server
@ -102,9 +104,9 @@ which set the section to its current value. The state dictionary, like the
state itself, depends on the events currently in the graph and so is updated state itself, depends on the events currently in the graph and so is updated
with each new event received. with each new event received.
Since the sections of the state are defined by a pair of strings that came from Since the sections of the state are defined by the pair of strings from the
the type and state_key of the events that update them, the state dictionary can type and state_key of the events that update them, the state dictionary can be
be defined as a mapping from the pair (type, state_key) to a state event with defined as a mapping from the pair (type, state_key) to a state event with
those values in the graph. those values in the graph.
Deleting State Deleting State