From 9ac53ef8cfe595b5606b97c52fb4aaf6fb35e9df Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 7 Oct 2014 11:38:02 +0100 Subject: [PATCH] SPEC-3: First hack at defining some of the various event related concepts --- docs/definitions.rst | 53 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/definitions.rst diff --git a/docs/definitions.rst b/docs/definitions.rst new file mode 100644 index 0000000000..b0f95ae9d7 --- /dev/null +++ b/docs/definitions.rst @@ -0,0 +1,53 @@ +Definitions +=========== + +# *Event* -- A JSON object that represents a piece of information to be +distributed to the the room. The object includes a payload and metadata, +including a `type` used to indicate what the payload is for and how to process +them. It also includes one or more references to previous events. + +# *Event graph* -- Events and their references to previous events form a +directed acyclic graph. All events must be a descendant of the first event in a +room, except for a few special circumstances. + +# *State event* -- A state event is an event that has a non-null string valued +`state_key` field. It may also include a `prev_state` key referencing exactly +one state event with the same type and state key, in the same event graph. + +# *State tree* -- A state tree is a tree formed by a collection of state events +that have the same type and state key (all in the same event graph. + +# *State resolution algorithm* -- An algorithm that takes a state tree as input +and selects a single leaf node. + +# *Current state event* -- The leaf node of a given state tree that has been +selected by the state resolution algorithm. + +# *Room state* / *state dictionary* / *current state* -- A mapping of the pair +(event type, state key) to the current state event for that pair. + +# *Room* -- An event graph and its associated state dictionary. An event is in +the room if it is part of the event graph. + +# *Topological ordering* -- The partial ordering that can be extracted from the +event graph due to it being a DAG. + +(The state definitions are purposely slightly ill-defined, since if we allow +deleting events we might end up with multiple state trees for a given event +type and state key pair.) + +Federation specific +------------------- +# *(Persistent data unit) PDU* -- An encoding of an event for distribution of +the server to server protocol. + +# *(Ephemeral data unit) EDU* -- A piece of information that is sent between +servers and doesn't encode an event. + +Client specific +--------------- +# *Child events* -- Events that reference a single event in the same room +independently of the event graph. + +# *Collapsed events* -- Events that have all child events that reference it +included in the JSON object.