Merge pull request #80 from matrix-org/module-receipts

Receipts module

api/client-server/v2_alpha/receipts.yaml

@@ -0,0 +1,68 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v2 Receipts API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/v2_alpha
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/rooms/{roomId}/receipt/{receiptType}/{eventId}":
+    post:
+      summary: Send a receipt for the given event ID.
+      description: |-
+        This API updates the marker for the given receipt type to the event ID
+        specified.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room in which to send the event.
+          required: true
+          x-example: "!wefuh21ffskfuh345:example.com"
+        - in: path
+          type: string
+          name: receiptType
+          description: The type of receipt to send.
+          required: true
+          x-example: "m.read"
+          enum: ["m.read"]
+        - in: path
+          type: string
+          name: eventId
+          description: The event ID to acknowledge up to.
+          required: true
+          x-example: "$1924376522eioj:example.com"
+        - in: body
+          description: |-
+            Extra receipt information to attach to ``content`` if any. The
+            server will automatically set the ``ts`` field.
+          schema:
+            type: object
+            example: |-
+              {}
+      responses:
+        200:
+          description: The receipt was sent.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object  # empty json object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"

event-schemas/examples/v1/m.receipt

@@ -3,7 +3,7 @@
     "room_id": "!KpjVgQyZpzBwvMBsnT:matrix.org",
     "content": {
         "$1435641916114394fHBLK:matrix.org": {
-            "read": {
+            "m.read": {
                 "@rikj:jki.re": {
                     "ts": 1436451550453
                 }

event-schemas/schema/v1/m.receipt

@@ -5,26 +5,32 @@
     "properties": {
         "content": {
             "type": "object",
-            "description": "The event ids which the receipts relate to.",
             "patternProperties": {
                 "^\\$": {
                     "type": "object",
-                    "description": "The types of the receipts.",
-                    "additionalProperties": {
-                        "type": "object",
-                        "description": "User ids of the receipts",
-                        "patternProperties": {
-                            "^@": {
-                                "type": "object",
-                                "properties": {
-                                    "ts": {
-                                        "type": "number",
-                                        "description": "The timestamp the receipt was sent at"
+                    "x-pattern": "$EVENT_ID",
+                    "title": "Receipts",
+                    "description": "The mapping of event ID to a collection of receipts for this event ID. The event ID is the ID of the event being acknowledged and *not* an ID for the receipt itself.",
+                    "properties": {
+                        "m.read": {
+                            "type": "object",
+                            "title": "Users",
+                            "description": "A collection of users who have sent ``m.read`` receipts for this event.",
+                            "patternProperties": {
+                                "^@": {
+                                    "type": "object",
+                                    "title": "Receipt",
+                                    "description": "The mapping of user ID to receipt. The user ID is the entity who sent this receipt.",
+                                    "x-pattern": "$USER_ID",
+                                    "properties": {
+                                        "ts": {
+                                            "type": "number",
+                                            "description": "The timestamp the receipt was sent at."
+                                        }
                                     }
                                 }
                             }
-                        },
-                        "additionalProperties": false
+                        }
                     }
                 }
             },

specification/modules/receipts.rst

@@ -1,66 +1,64 @@
 Receipts
---------
+========
 
 .. _module:receipts:
 
-Receipts are used to publish which events in a room the user or their devices
-have interacted with. For example, which events the user has read. For
-efficiency this is done as "up to" markers, i.e. marking a particular event
-as, say, ``read`` indicates the user has read all events *up to* that event.
-
-Client-Server API
-~~~~~~~~~~~~~~~~~
-
-Clients will receive receipts in the following format::
-
-     {
-        "type": "m.receipt",
-        "room_id": <room_id>,
-        "content": {
-            <event_id>: {
-                <receipt_type>: {
-                    <user_id>: { "ts": <ts>, ... },
-                    ...
-                }
-            },
-            ...
-        }
-    }
+This module adds in support for receipts. These receipts are a form of
+acknowledgement of an event. This module defines a single acknowledgement:
+``m.read`` which indicates that the user has read up to a given event.
 
-For example::
+Sending a receipt for each event can result in sending large amounts of traffic
+to a homeserver. To prevent this from becoming a problem, receipts are implemented
+using "up to" markers. This marker indicates that the acknowledgement applies
+to all events "up to and including" the event specified. For example, marking
+an event as "read" would indicate that the user had read all events *up to* the
+referenced event.
 
-    {
-        "type": "m.receipt",
-        "room_id": "!KpjVgQyZpzBwvMBsnT:matrix.org",
-        "content": {
-            "$1435641916114394fHBLK:matrix.org": {
-                "read": {
-                    "@erikj:jki.re": { "ts": 1436451550453 },
-                    ...
-                }
-            },
-            ...
-        }
-    }
+Events
+------
+Each ``user_id``, ``receipt_type`` pair must be associated with only a
+single ``event_id``.
 
-For efficiency, receipts are batched into one event per room. In the initialSync
-and v2 sync APIs the receipts are listed in a separate top level ``receipts``
-key. Each ``user_id``, ``receipt_type`` pair must be associated with only a
-single ``event_id``. New receipts that come down the event streams are deltas.
-Deltas update existing mappings, clobbering based on ``user_id``,
-``receipt_type`` pairs.
+{{m_receipt_event}}
 
+Client behaviour
+----------------
 
-A client can update the markers for its user by issuing a request::
+In v1 ``/initialSync``, receipts are listed in a separate top level ``receipts``
+key. In v2 ``/sync``, receipts are contained in the ``ephemeral`` block for a
+room. New receipts that come down the event streams are deltas which update
+existing mappings. Clients should replace older receipt acknowledgements based
+on ``user_id`` and ``receipt_type`` pairs. For example::
 
-    POST /_matrix/client/v2_alpha/rooms/<room_id>/receipt/read/<event_id>
+  Client receives m.receipt:
+    user = @alice:example.com
+    receipt_type = m.read
+    event_id = $aaa:example.com
 
-Where the contents of the ``POST`` will be included in the content sent to
-other users. The server will automatically set the ``ts`` field.
+  Client receives another m.receipt:
+    user = @alice:example.com
+    receipt_type = m.read
+    event_id = $bbb:example.com
 
+  The client should replace the older acknowledgement for $aaa:example.com with
+  this one for $bbb:example.com
 
-Server-Server API
-~~~~~~~~~~~~~~~~~
+Clients should send read receipts when there is some certainty that the event in
+question has been **displayed** to the user. Simply receiving an event does not
+provide enough certainty that the user has seen the event. The user SHOULD need
+to *take some action* such as viewing the room that the event was sent to or
+dismissing a notification in order for the event to count as "read".
+
+A client can update the markers for its user by interacting with the following
+HTTP APIs.
+
+{{v2_receipts_http_api}}
+
+Server behaviour
+----------------
+
+For efficiency, receipts SHOULD be batched into one event per room before
+delivering them to clients.
 
 Receipts are sent across federation as EDUs with type ``m.receipt``. The
 format of the EDUs are::
@@ -75,5 +73,12 @@ format of the EDUs are::
         ...
     }
 
-These are always sent as deltas to previously sent receipts.
+These are always sent as deltas to previously sent receipts. Currently only a
+single ``<receipt_type>`` should be used: ``m.read``.
+
+Security considerations
+-----------------------
+
+As receipts are sent outside the context of the event graph, there are no
+integrity checks performed on the contents of ``m.receipt`` events.
 

templating/matrix_templates/units.py

@@ -19,6 +19,7 @@ import yaml
 V1_CLIENT_API = "../api/client-server/v1"
 V1_EVENT_EXAMPLES = "../event-schemas/examples/v1"
 V1_EVENT_SCHEMA = "../event-schemas/schema/v1"
+V2_CLIENT_API = "../api/client-server/v2_alpha"
 CORE_EVENT_SCHEMA = "../event-schemas/schema/v1/core-event-schema"
 CHANGELOG = "../CHANGELOG.rst"
 TARGETS = "../specification/targets.yaml"
@@ -49,8 +50,17 @@ def get_json_schema_object_fields(obj, enforce_title=False):
     }
     tables = [fields]
 
-    props = obj.get("properties", obj.get("patternProperties"))
     parents = obj.get("allOf")
+    props = obj.get("properties")
+    if not props:
+        props = obj.get("patternProperties")
+        if props:
+            # try to replace horrible regex key names with pretty x-pattern ones
+            for key_name in props.keys():
+                pretty_key = props[key_name].get("x-pattern")
+                if pretty_key:
+                    props[pretty_key] = props[key_name]
+                    del props[key_name]
     if not props and not parents:
         raise Exception(
             "Object %s has no properties or parents." % obj
@@ -70,10 +80,17 @@ def get_json_schema_object_fields(obj, enforce_title=False):
         if props[key_name]["type"] == "object":
             if props[key_name].get("additionalProperties"):
                 # not "really" an object, just a KV store
-                value_type = (
-                    "{string: %s}" %
-                    props[key_name]["additionalProperties"]["type"]
-                )
+                prop_val = props[key_name]["additionalProperties"]["type"]
+                if prop_val == "object":
+                    nested_object = get_json_schema_object_fields(
+                        props[key_name]["additionalProperties"],
+                        enforce_title=True
+                    )
+                    value_type = "{string: %s}" % nested_object[0]["title"]
+                    if not nested_object[0].get("no-table"):
+                        tables += nested_object
+                else:
+                    value_type = "{string: %s}" % prop_val
             else:
                 nested_object = get_json_schema_object_fields(
                     props[key_name], 
@@ -320,18 +337,27 @@ class MatrixUnits(Units):
         }
 
     def load_swagger_apis(self):
-        path = V1_CLIENT_API
+        paths = [
+            V1_CLIENT_API, V2_CLIENT_API
+        ]
         apis = {}
-        for filename in os.listdir(path):
-            if not filename.endswith(".yaml"):
+        for path in paths:
+            is_v2 = (path == V2_CLIENT_API)
+            if not os.path.exists(V2_CLIENT_API):
+                self.log("Skipping v2 apis: %s does not exist." % V2_CLIENT_API)
                 continue
-            self.log("Reading swagger API: %s" % filename)
-            with open(os.path.join(path, filename), "r") as f:
-                # strip .yaml
-                group_name = filename[:-5]
-                api = yaml.load(f.read())
-                api["__meta"] = self._load_swagger_meta(api, group_name)
-                apis[group_name] = api
+            for filename in os.listdir(path):
+                if not filename.endswith(".yaml"):
+                    continue
+                self.log("Reading swagger API: %s" % filename)
+                with open(os.path.join(path, filename), "r") as f:
+                    # strip .yaml
+                    group_name = filename[:-5]
+                    if is_v2:
+                        group_name = "v2_" + group_name
+                    api = yaml.load(f.read())
+                    api["__meta"] = self._load_swagger_meta(api, group_name)
+                    apis[group_name] = api
         return apis
 
     def load_common_event_fields(self):