diff --git a/drafts/core_model.rst b/drafts/core_model.rst new file mode 100644 index 00000000..b8f103ec --- /dev/null +++ b/drafts/core_model.rst @@ -0,0 +1,112 @@ +Models +====== + +Client +------ + +Server +------ + +Events +------ +An event is a collection of data (the `payload`) and metadata associated with +it to be distributed across servers and is the primary data unit in Matrix. +Events are extensible so that clients and servers can add extra fields to the +payload or metadata that are not in this specification. + +Events are distributed to interested servers upon creation. Historical events +may be requested from servers, though servers are not required to produce all +or any events requested. + +All events have a metadata `type` field that is used by client and servers to +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 +defined by applications, clients or servers for their own purposes. + +Graph +~~~~~ +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 +a single root event. + +Event graphs give a partial ordering of events, i.e. given two events one may +be considered to have come before the other if one is an ancestor of the other. +Since two events may be on separate branches, not all events can be compared in +this manner. + +Every event has a metadata `depth` field that is a positive integer that is +strictly greater than the depths of any of its parents. The root event should +have a depth of 1. + +[Note: if one event is before another, then it must have a strictly smaller +depth] + +Integrity +~~~~~~~~~ +Portions of events will be signed by one or more servers or clients. The parent +relations, type, depth and payload (as well as other metadata fields that will +be specified) must be signed by the originating server. [Note: Thus, once an +event is distributed and referenced by later events, they effectively become +immutable]. + +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 +cannot have an encrypted payload are given later. + + +State +----- +Event graphs may have meta information associated with them, called `state`. +State can be updated over time by servers or clients, subject to +authentication. + +The state of a graph is split into `sections` that can be atomically updated +independently of each other. + +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 +state of the sub graph of all events "before" and including that event. + +Some sections of the state may determine behaviour of the protocol, including +authorization and distribution. These sections must not be encrypted. + +State Events +~~~~~~~~~~~~ +`State events` are events that update a section of the state of a graph. These +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 +section of state being updated. + +State events must also include a `state_key` metadata field, which in +conjunction with the type field defines the section of state that is to be +updated. + +State Resolution +~~~~~~~~~~~~~~~~ +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 +precedence is therefore required. + +This is done by taking the latest state events, i.e. the set of events that +either incomparable or after every other event. A state resolution algorithm is +then applied to this set to select one. + +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 +or the order the events were received in. + +State Dictionary +~~~~~~~~~~~~~~~~ +The state dictionary is the mapping from sections of state to the state events +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 +with each new event received. + +Since the sections of the state are defined by a pair of strings that came from +the type and state_key of the events that update them, the state dictionary can +be defined as a mapping from the pair (type, state_key) to a state event with +those values in the graph. + +Deleting State +~~~~~~~~~~~~~~ +TODO