mirror of
https://git.anonymousland.org/anonymousland/synapse-product.git
synced 2024-09-08 12:52:04 +00:00
Specced out state/non-state events. Start working on the myriad of syncing APIs.
This commit is contained in:
parent
fa6b3490e2
commit
401c16559d
@ -391,22 +391,101 @@ If all members in a room leave, that room becomes eligible for deletion.
|
|||||||
|
|
||||||
Events in a room
|
Events in a room
|
||||||
----------------
|
----------------
|
||||||
- Split into state and non-state data
|
Room events can be split into two categories:
|
||||||
- Explain what they are, semantics, give examples of clobbering / not, use cases (msgs vs room names).
|
|
||||||
Not too much detail on the actual event contents.
|
|
||||||
- API to hit.
|
|
||||||
- Extensibility provided by the API for custom events. Examples.
|
|
||||||
- How this hooks into ``initialSync``.
|
|
||||||
- See the "Room Events" section for actual spec on each type.
|
|
||||||
|
|
||||||
Syncing a room
|
:State Events:
|
||||||
--------------
|
These are events which replace events that came before it, depending on a set of unique keys.
|
||||||
- Single room initial sync. ``rooms/<room id>/initialSync`` API to hit. Why it might be used (lazy loading)
|
These keys are the event ``type`` and a ``state_key``. Events with the same set of keys will
|
||||||
|
be overwritten. Typically, state events are used to store state, hence their name.
|
||||||
|
|
||||||
Getting grouped state events
|
:Non-state events:
|
||||||
----------------------------
|
These are events which cannot be overwritten after sending. The list of events continues
|
||||||
- ``/members`` and ``/messages`` and the events they return.
|
to grow as more events are sent. As this list grows, it becomes necessary to
|
||||||
- ``/state`` and it returns ALL THE THINGS.
|
provide a mechanism for navigating this list. Pagination APIs are used to view the list
|
||||||
|
of historical non-state events. Typically, non-state events are used to send messages.
|
||||||
|
|
||||||
|
This specification outlines several events, all with the event type prefix ``m.``. However,
|
||||||
|
applications may wish to add their own type of event, and this can be achieved using the
|
||||||
|
REST API detailed in the following sections. If new events are added, 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.
|
||||||
|
|
||||||
|
State events
|
||||||
|
------------
|
||||||
|
State events can be sent by ``PUT`` ing to ``/rooms/<room id>/state/<event type>/<state key>``.
|
||||||
|
These events will be overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all match.
|
||||||
|
If the state event has no ``state_key``, it can be omitted from the path. These requests
|
||||||
|
**cannot use transaction IDs** like other ``PUT`` paths because they cannot be differentiated
|
||||||
|
from the ``state key``. Furthermore, ``POST`` is unsupported on state paths. Valid requests
|
||||||
|
look like::
|
||||||
|
|
||||||
|
PUT /rooms/!roomid:domain/state/m.example.event
|
||||||
|
{ "key" : "without a state key" }
|
||||||
|
|
||||||
|
PUT /rooms/!roomid:domain/state/m.another.example.event/foo
|
||||||
|
{ "key" : "with 'foo' as the state key" }
|
||||||
|
|
||||||
|
In contrast, these requests are invalid::
|
||||||
|
|
||||||
|
POST /rooms/!roomid:domain/state/m.example.event/
|
||||||
|
{ "key" : "cannot use POST here" }
|
||||||
|
|
||||||
|
PUT /rooms/!roomid:domain/state/m.another.example.event/foo/11
|
||||||
|
{ "key" : "txnIds are not supported" }
|
||||||
|
|
||||||
|
Care should be taken to avoid setting the wrong ``state key``::
|
||||||
|
|
||||||
|
PUT /rooms/!roomid:domain/state/m.another.example.event/11
|
||||||
|
{ "key" : "with '11' as the state key, but was probably intended to be a txnId" }
|
||||||
|
|
||||||
|
The ``state_key`` is often used to store state about individual users, by using the user ID as the
|
||||||
|
value. For example::
|
||||||
|
|
||||||
|
PUT /rooms/!roomid:domain/state/m.favorite.animal.event/%40my_user%3Adomain.com
|
||||||
|
{ "animal" : "cat", "reason": "fluffy" }
|
||||||
|
|
||||||
|
In some cases, there may be no need for a ``state_key``, so it can be omitted::
|
||||||
|
|
||||||
|
PUT /rooms/!roomid:domain/state/m.room.bgd.color
|
||||||
|
{ "color": "red", "hex": "#ff0000" }
|
||||||
|
|
||||||
|
See "Room Events" for the ``m.`` event specification.
|
||||||
|
|
||||||
|
Non-state events
|
||||||
|
----------------
|
||||||
|
Non-state events can be sent by sending a request to ``/rooms/<room id>/send/<event type>``.
|
||||||
|
These requests *can* use transaction IDs and ``PUT``/``POST`` methods. Non-state events
|
||||||
|
allow access to historical events and pagination, making it best suited for sending messages.
|
||||||
|
For example::
|
||||||
|
|
||||||
|
POST /rooms/!roomid:domain/send/m.custom.example.message
|
||||||
|
{ "text": "Hello world!" }
|
||||||
|
|
||||||
|
PUT /rooms/!roomid:domain/send/m.custom.example.message/11
|
||||||
|
{ "text": "Goodbye world!" }
|
||||||
|
|
||||||
|
See "Room Events" for the ``m.`` event specification.
|
||||||
|
|
||||||
|
Syncing rooms
|
||||||
|
-------------
|
||||||
|
When a client logs in, they may have a list of rooms which they have already joined. These rooms
|
||||||
|
may also have a list of events associated with them. The purpose of 'syncing' is to present the
|
||||||
|
current room and event information in a convenient, compact manner. There are two APIs provided:
|
||||||
|
|
||||||
|
- ``/initialSync`` : A global sync which will present room and event information for all rooms
|
||||||
|
the user has joined.
|
||||||
|
|
||||||
|
- ``/rooms/<room id>/initialSync`` : A sync scoped to a single room. Presents room and event
|
||||||
|
information for this room only.
|
||||||
|
|
||||||
|
- TODO: JSON response format for both types
|
||||||
|
- TODO: when would you use global? when would you use scoped?
|
||||||
|
|
||||||
|
Getting grouped state events for a room
|
||||||
|
---------------------------------------
|
||||||
|
- ``/members`` and ``/messages`` and the event types they return. Spec JSON response format.
|
||||||
|
- ``/state`` and it returns ALL THE THINGS.
|
||||||
|
|
||||||
Room Events
|
Room Events
|
||||||
===========
|
===========
|
||||||
|
Loading…
Reference in New Issue
Block a user