From 0dc22e721755fa31ca4af105459275eda2762707 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 28 Aug 2015 14:50:31 +0100 Subject: [PATCH 1/7] Document receipts --- specification/46_receipts.rst | 64 +++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 specification/46_receipts.rst diff --git a/specification/46_receipts.rst b/specification/46_receipts.rst new file mode 100644 index 00000000..43b84947 --- /dev/null +++ b/specification/46_receipts.rst @@ -0,0 +1,64 @@ +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, e.g., 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": "!KpjVgQyZpzBwvMBsnT:matrix.org" + "content": { + "$1435641916114394fHBLK:matrix.org": { + "read": { + "@erikj:jki.re": { "ts": 1436451550453 }, + ... + } + }, + ... + } + } + +For efficiency, receipts are batched into one event per room. In the initialSync +and v2 sync APIs the receipts are listed in a seperate 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. + + +A client can update the markers for its user by issuing a request:: + + POST /_matrix/client/v2_alpha/rooms//receipt/read/ + +Where the contents will of the POST will be included in the content sent to +other users. The server will automatically set the ``ts`` field. + + +Server-Server API +----------------- + +Receipts are sent across federation as EDUs with type ``m.receipt``. The +format of the EDUs are:: + + { + : { + : { + : { } + }, + .... + }, + ... + } + +These are always sent as deltas to previously sent reciepts. + From 83dfc2bf61ef776ad32f7a897c82a67f95e0caa3 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 28 Aug 2015 15:01:02 +0100 Subject: [PATCH 2/7] Fix some mistakes/typos --- specification/46_receipts.rst | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/specification/46_receipts.rst b/specification/46_receipts.rst index 43b84947..6428d6b5 100644 --- a/specification/46_receipts.rst +++ b/specification/46_receipts.rst @@ -5,16 +5,32 @@ 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, e.g., read indicates the user has read all events *up to* that 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": , + "content": { + : { + : { + : { "ts": , ... }, + ... + } + }, + ... + } + } + +For example:: + { "type": "m.receipt", - "room_id": "!KpjVgQyZpzBwvMBsnT:matrix.org" + "room_id": "!KpjVgQyZpzBwvMBsnT:matrix.org", "content": { "$1435641916114394fHBLK:matrix.org": { "read": { @@ -27,7 +43,8 @@ Clients will receive receipts in the following format:: } For efficiency, receipts are batched into one event per room. In the initialSync -and v2 sync APIs the receipts are listed in a seperate top level receipts key. +and v2 sync APIs the receipts are listed in a seperate top level ``receipts`` +key. Each ``user_id``, ``receipt_type`` pair must be associated with only a single ``event_id``. @@ -40,7 +57,7 @@ A client can update the markers for its user by issuing a request:: POST /_matrix/client/v2_alpha/rooms//receipt/read/ -Where the contents will of the POST will be included in the content sent to +Where the contents of the ``POST`` will be included in the content sent to other users. The server will automatically set the ``ts`` field. @@ -55,7 +72,7 @@ format of the EDUs are:: : { : { } }, - .... + ... }, ... } From e58f816ad39c26461527c2ba47d2db8d544f7cb1 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 8 Sep 2015 16:49:14 +0100 Subject: [PATCH 3/7] Add m.receipt schema --- event-schemas/examples/v1/m.receipt | 13 +++++++++ event-schemas/schema/v1/m.receipt | 43 +++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 event-schemas/examples/v1/m.receipt create mode 100644 event-schemas/schema/v1/m.receipt diff --git a/event-schemas/examples/v1/m.receipt b/event-schemas/examples/v1/m.receipt new file mode 100644 index 00000000..83515317 --- /dev/null +++ b/event-schemas/examples/v1/m.receipt @@ -0,0 +1,13 @@ +{ + "type": "m.receipt", + "room_id": "!KpjVgQyZpzBwvMBsnT:matrix.org", + "content": { + "$1435641916114394fHBLK:matrix.org": { + "read": { + "@rikj:jki.re": { + "ts": 1436451550453 + } + } + } + } +} diff --git a/event-schemas/schema/v1/m.receipt b/event-schemas/schema/v1/m.receipt new file mode 100644 index 00000000..b9d29c30 --- /dev/null +++ b/event-schemas/schema/v1/m.receipt @@ -0,0 +1,43 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "title": "Receipt Event", + "description": "Informs the client of new receipts.", + "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" + } + } + } + }, + "additionalProperties": false + } + } + }, + "additionalProperties": false + }, + "type": { + "type": "string", + "enum": ["m.presence"] + }, + "room_id": { + "type": "string" + } + }, + "required": ["room_id", "type", "content"] +} From 5157c2f52ed6dfc3019b097387d6c3678413a87e Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 8 Sep 2015 16:51:08 +0100 Subject: [PATCH 4/7] More escapes --- event-schemas/schema/v1/m.receipt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event-schemas/schema/v1/m.receipt b/event-schemas/schema/v1/m.receipt index b9d29c30..9848f6c6 100644 --- a/event-schemas/schema/v1/m.receipt +++ b/event-schemas/schema/v1/m.receipt @@ -8,7 +8,7 @@ "type": "object", "description": "The event ids which the receipts relate to.", "patternProperties": { - "^\$": { + "^\\$": { "type": "object", "description": "The types of the receipts." "additionalProperties": { From 53756cfd73ed18d74839b16fe4b697f0dd25cc70 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 8 Sep 2015 16:52:43 +0100 Subject: [PATCH 5/7] More commas --- event-schemas/schema/v1/m.receipt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event-schemas/schema/v1/m.receipt b/event-schemas/schema/v1/m.receipt index 9848f6c6..3f242eb0 100644 --- a/event-schemas/schema/v1/m.receipt +++ b/event-schemas/schema/v1/m.receipt @@ -10,7 +10,7 @@ "patternProperties": { "^\\$": { "type": "object", - "description": "The types of the receipts." + "description": "The types of the receipts.", "additionalProperties": { "type": "object", "description": "User ids of the receipts", From 500b4eb32de4054281b5bbeda69df1dc5f4fdf96 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 8 Sep 2015 16:54:14 +0100 Subject: [PATCH 6/7] Typo --- event-schemas/schema/v1/m.receipt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event-schemas/schema/v1/m.receipt b/event-schemas/schema/v1/m.receipt index 3f242eb0..4bd9f17b 100644 --- a/event-schemas/schema/v1/m.receipt +++ b/event-schemas/schema/v1/m.receipt @@ -33,7 +33,7 @@ }, "type": { "type": "string", - "enum": ["m.presence"] + "enum": ["m.receipt"] }, "room_id": { "type": "string" From a92fa6392d1b7eb9dd9c75f6d209506a2898ca30 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Tue, 8 Sep 2015 17:14:31 +0100 Subject: [PATCH 7/7] Include patternProperties as normal properties (they basically are just patterns instead of keys; we could probably annotate this more nicely in the future) --- templating/matrix_templates/units.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index d607160f..2ae6cd0b 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -30,7 +30,7 @@ def get_json_schema_object_fields(obj, enforce_title=False): } tables = [fields] - props = obj.get("properties") + props = obj.get("properties", obj.get("patternProperties")) parents = obj.get("allOf") if not props and not parents: raise Exception(