From 2f039a114201887f7b2da8b4f8a334bcd9f8f515 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Thu, 24 Sep 2015 15:39:17 +0100 Subject: [PATCH 01/31] Add swagger docs for the v2 filter POST API --- api/client-server/v2_alpha/filter.yaml | 188 +++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 api/client-server/v2_alpha/filter.yaml diff --git a/api/client-server/v2_alpha/filter.yaml b/api/client-server/v2_alpha/filter.yaml new file mode 100644 index 000000000..99dc0ebcf --- /dev/null +++ b/api/client-server/v2_alpha/filter.yaml @@ -0,0 +1,188 @@ +swagger: '2.0' +info: + title: "Matrix Client-Server v2 filter API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https +basePath: /_matrix/client/api/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 +definitions: + EventFilter: + title: + type: object + properties: + types: + type: array + description: |- + A list of event types to include. + If this list is absent then all event types are included. + items: + type: string + not_types: + type: array + description: |- + A list of event types to exclude. + If this list is absent then no event types are excluded. + items: + type: string + senders: + type: array + description: |- + A list of senders IDs to include. + If this list is absent then all senders are included. + items: + type: string + not_senders: + type: array + description: |- + A list of sender IDs to exclude + If this list is absent then no senders are excluded. + items: + type: string + rooms: + type: array + description: |- + A list of room IDs to include. + If this list is absent then all rooms are included. + items: + type: string + not_rooms: + type: array + description: |- + A list of room IDs to exclude + If this list is absent then no rooms are excluded. + items: + type: string + SyncFilter: + room: + type: object + properties: + state: + description: + The state events to include for rooms. + allOf: + - $ref: "#/definitions/EventFilter" + events: + description: + The message and state update events to include for rooms. + allOf: + - $ref: "#/definitions/EventFilter" + ephemeral: + description: |- + The events that aren't recorded in the permenant history, e.g. + typing and receipts, to include for rooms. + allOf: + - $ref: "#/definitions/EventFilter" + public_user_data: + description: |- + The public user data, e.g. profile and presence, to include. + allOf: + - $ref: "#/definitions/EventFilter" + private_user_data: + description: |- + Events that are private to a user but shared amoungst their devices, + e.g. notification settings, to include. + allOf: + - $ref: "#/definitions/EventFilter" + event_format: + description: |- + The format to use for events. "client" will return the events in a + format suitable for clients. "federation" will return the raw event + as receieved over federation. The default is "client". + type: string + event_fields: + type: array + description: |- + List of event fields to include. If this list is absent then all fields + are included. The entries may include "." charaters to indicate + sub-fields. So ["content.body"] will include the "body" field of the + "content" object. A server may include more fields than were requested. + items: + string +paths: + "/user/{userId}/filter": + post: + summary: Upload a new filter. + description: |- + Uploads a new filter definition to the homeserver. + Returns a filter ID that may be used in /sync requests to + retrict which events are returned to the client. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + required: true + description: + The id of the user uploading the filter. The access token must be + authorized to make requests for this user id. + x-example: "@alice:example.com" + - in: body + name: filter + required: true + description: The filter to upload. + schema: + type: object + allOf: + - $ref: "#/definitions/SyncFilter" + example: + type: object + example: |- + { + "room": { + "state": { + "types": ["m.room.*"], + "not_rooms": ["!726s6s6q:example.com"], + }, + "events": { + "types": ["m.room.message"], + "not_rooms": ["!726s6s6q:example.com"], + "not_senders": ["@spam:example.com"] + }, + "emphemeral": { + "types": ["m.receipt", "m.typing"], + "not_rooms": ["!726s6s6q:example.com"], + "not_senders": ["@spam:example.com"] + } + }, + "public_user_data": { + "types": ["m.presence"] + }, + "private_user_data": { + "types": [] + }, + "server_data": { + "types": [] + }, + "event_format": "client", + "event_fields": ["type", "content", "sender"] + } + responses: + 200: + description: The filter was created. + examples: + application/json: |- + { + "filter_id": "66696p746572" + } + schema: + type: object + properties: + filter_id: + type: string + description: + The ID of the filter that was created. + + + From 883105eae69d51e8672f63b9aa48946b6ae5347b Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Thu, 24 Sep 2015 16:25:03 +0100 Subject: [PATCH 02/31] Document the v2 filter GET API --- .../v2_alpha/definitions/definitions | 1 + .../v2_alpha/definitions/event_filter.json | 53 ++++++ .../v2_alpha/definitions/sync_filter.json | 48 ++++++ api/client-server/v2_alpha/filter.yaml | 158 +++++++----------- 4 files changed, 159 insertions(+), 101 deletions(-) create mode 120000 api/client-server/v2_alpha/definitions/definitions create mode 100644 api/client-server/v2_alpha/definitions/event_filter.json create mode 100644 api/client-server/v2_alpha/definitions/sync_filter.json diff --git a/api/client-server/v2_alpha/definitions/definitions b/api/client-server/v2_alpha/definitions/definitions new file mode 120000 index 000000000..945c9b46d --- /dev/null +++ b/api/client-server/v2_alpha/definitions/definitions @@ -0,0 +1 @@ +. \ No newline at end of file diff --git a/api/client-server/v2_alpha/definitions/event_filter.json b/api/client-server/v2_alpha/definitions/event_filter.json new file mode 100644 index 000000000..b8ab1352e --- /dev/null +++ b/api/client-server/v2_alpha/definitions/event_filter.json @@ -0,0 +1,53 @@ +{ + "type": "object", + "properties": { + "types": { + "type": "array", + "description": + "A list of event types to include. If this list is absent then all event types are included.", + "items": { + "type": "string" + } + }, + "not_types": { + "type": "array", + "description": + "A list of event types to exclude. If this list is absent then no event types are excluded.", + "items": { + "type": "string" + } + }, + "senders": { + "type": "array", + "description": + "A list of senders IDs to include. If this list is absent then all senders are included.", + "items": { + "type": "string" + } + }, + "not_senders": { + "type": "array", + "description": + "A list of sender IDs to exclude. If this list is absent then no senders are excluded.", + "items": { + "type": "string" + } + }, + "rooms": { + "type": "array", + "description": + "A list of room IDs to include. If this list is absent then all rooms are included.", + "items": { + "type": "string" + } + }, + "not_rooms": { + "type": "array", + "description": + "A list of room IDs to exclude. If this list is absent then no rooms are excluded.", + "items": { + "type": "string" + } + } + } +} diff --git a/api/client-server/v2_alpha/definitions/sync_filter.json b/api/client-server/v2_alpha/definitions/sync_filter.json new file mode 100644 index 000000000..c9c47646d --- /dev/null +++ b/api/client-server/v2_alpha/definitions/sync_filter.json @@ -0,0 +1,48 @@ +{ + "type": "object", + "properties": { + "room": { + "type": "object", + "properties": { + "state": { + "description": + "The state events to include for rooms.", + "allOf": [{"$ref": "definitions/event_filter.json"}] + }, + "events": { + "description": + "The message and state update events to include for rooms.", + "allOf": [{"$ref": "definitions/event_filter.json"}] + }, + "ephemeral": { + "description": + "The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms.", + "allOf": [{"$ref": "definitions/event_filter.json"}] + } + } + }, + "public_user_data": { + "description": + "The public user data, e.g. profile and presence, to include.", + "allOf": [{"$ref": "definitions/event_filter.json"}] + }, + "private_user_data": { + "description": + "Events that are private to a user but shared amoungst their devices, e.g. notification settings, to include.", + "allOf": [{"$ref": "definitions/event_filter.json"}] + }, + "event_format": { + "description": + "The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as receieved over federation. The default is 'client'.", + "type": "string" + }, + "event_fields": { + "type": "array", + "description": + "List of event fields to include. If this list is absent then all fields are included. The entries may include '.' charaters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A server may include more fields than were requested.", + "items": { + "type": "string" + } + } + } +} diff --git a/api/client-server/v2_alpha/filter.yaml b/api/client-server/v2_alpha/filter.yaml index 99dc0ebcf..115ef2308 100644 --- a/api/client-server/v2_alpha/filter.yaml +++ b/api/client-server/v2_alpha/filter.yaml @@ -16,103 +16,10 @@ securityDefinitions: description: The user_id or application service access_token name: access_token in: query -definitions: - EventFilter: - title: - type: object - properties: - types: - type: array - description: |- - A list of event types to include. - If this list is absent then all event types are included. - items: - type: string - not_types: - type: array - description: |- - A list of event types to exclude. - If this list is absent then no event types are excluded. - items: - type: string - senders: - type: array - description: |- - A list of senders IDs to include. - If this list is absent then all senders are included. - items: - type: string - not_senders: - type: array - description: |- - A list of sender IDs to exclude - If this list is absent then no senders are excluded. - items: - type: string - rooms: - type: array - description: |- - A list of room IDs to include. - If this list is absent then all rooms are included. - items: - type: string - not_rooms: - type: array - description: |- - A list of room IDs to exclude - If this list is absent then no rooms are excluded. - items: - type: string - SyncFilter: - room: - type: object - properties: - state: - description: - The state events to include for rooms. - allOf: - - $ref: "#/definitions/EventFilter" - events: - description: - The message and state update events to include for rooms. - allOf: - - $ref: "#/definitions/EventFilter" - ephemeral: - description: |- - The events that aren't recorded in the permenant history, e.g. - typing and receipts, to include for rooms. - allOf: - - $ref: "#/definitions/EventFilter" - public_user_data: - description: |- - The public user data, e.g. profile and presence, to include. - allOf: - - $ref: "#/definitions/EventFilter" - private_user_data: - description: |- - Events that are private to a user but shared amoungst their devices, - e.g. notification settings, to include. - allOf: - - $ref: "#/definitions/EventFilter" - event_format: - description: |- - The format to use for events. "client" will return the events in a - format suitable for clients. "federation" will return the raw event - as receieved over federation. The default is "client". - type: string - event_fields: - type: array - description: |- - List of event fields to include. If this list is absent then all fields - are included. The entries may include "." charaters to indicate - sub-fields. So ["content.body"] will include the "body" field of the - "content" object. A server may include more fields than were requested. - items: - string paths: - "/user/{userId}/filter": - post: - summary: Upload a new filter. + "/user/{userId}/filter": + post: + summary: Upload a new filter. description: |- Uploads a new filter definition to the homeserver. Returns a filter ID that may be used in /sync requests to @@ -135,7 +42,7 @@ paths: schema: type: object allOf: - - $ref: "#/definitions/SyncFilter" + - $ref: "definitions/sync_filter.json" example: type: object example: |- @@ -181,8 +88,57 @@ paths: properties: filter_id: type: string - description: + description: |- The ID of the filter that was created. - - - + "/user/{userId}/filter/{filterId}": + get: + summary: Download a filter + parameters: + - in: path + name: userId + type: string + description: |- + The user ID to download a filter for. + x-example: "@alice:example.com" + - in: path + name: filterId + description: |- + The filter ID to download. + x-example: "66696p746572" + responses: + 200: + examples: + application/json: |- + { + "room": { + "state": { + "types": ["m.room.*"], + "not_rooms": ["!726s6s6q:example.com"] + }, + "events": { + "types": ["m.room.message"], + "not_rooms": ["!726s6s6q:example.com"], + "not_senders": ["@spam:example.com"] + }, + "emphemeral": { + "types": ["m.receipt", "m.typing"], + "not_rooms": ["!726s6s6q:example.com"], + "not_senders": ["@spam:example.com"] + } + }, + "public_user_data": { + "types": ["m.presence"] + }, + "private_user_data": { + "types": [] + }, + "server_data": { + "types": [] + }, + "event_format": "client", + "event_fields": ["type", "content", "sender"] + } + schema: + type: object + allOf: + - $ref: "definitions/sync_filter.json" From 69298b96121182e44a47a29eab3c69de5e91f37a Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Thu, 24 Sep 2015 16:29:51 +0100 Subject: [PATCH 03/31] Check "v2_alpha" in jenkins --- api/client-server/v2_alpha/filter.yaml | 5 +++++ jenkins.sh | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/api/client-server/v2_alpha/filter.yaml b/api/client-server/v2_alpha/filter.yaml index 115ef2308..f53ef2ba1 100644 --- a/api/client-server/v2_alpha/filter.yaml +++ b/api/client-server/v2_alpha/filter.yaml @@ -100,13 +100,18 @@ paths: description: |- The user ID to download a filter for. x-example: "@alice:example.com" + required: true - in: path name: filterId + type: string description: |- The filter ID to download. x-example: "66696p746572" + required: true responses: 200: + description: |- + "The filter defintion" examples: application/json: |- { diff --git a/jenkins.sh b/jenkins.sh index e10436449..0936de9da 100755 --- a/jenkins.sh +++ b/jenkins.sh @@ -5,5 +5,5 @@ set -ex (cd event-schemas/ && ./check_examples.py) (cd api && ./check_examples.py) (cd scripts && ./gendoc.py) -(cd api && npm install && node validator.js -s "client-server/v1") +(cd api && npm install && node validator.js -s "client-server/v1" && node validator.js -s "client-server/v2_alpha") (cd event-schemas/ && ./check.sh) From a31a446661262872ba668c2c3192c5cf0a180387 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Thu, 24 Sep 2015 16:48:00 +0100 Subject: [PATCH 04/31] Fix the POST example for the v2 filter API --- api/client-server/v2_alpha/filter.yaml | 58 +++++++++++++------------- 1 file changed, 28 insertions(+), 30 deletions(-) diff --git a/api/client-server/v2_alpha/filter.yaml b/api/client-server/v2_alpha/filter.yaml index f53ef2ba1..5296f11ac 100644 --- a/api/client-server/v2_alpha/filter.yaml +++ b/api/client-server/v2_alpha/filter.yaml @@ -43,38 +43,36 @@ paths: type: object allOf: - $ref: "definitions/sync_filter.json" - example: - type: object - example: |- - { - "room": { - "state": { - "types": ["m.room.*"], - "not_rooms": ["!726s6s6q:example.com"], - }, - "events": { - "types": ["m.room.message"], - "not_rooms": ["!726s6s6q:example.com"], - "not_senders": ["@spam:example.com"] - }, - "emphemeral": { - "types": ["m.receipt", "m.typing"], - "not_rooms": ["!726s6s6q:example.com"], - "not_senders": ["@spam:example.com"] - } - }, - "public_user_data": { - "types": ["m.presence"] - }, - "private_user_data": { - "types": [] + example: |- + { + "room": { + "state": { + "types": ["m.room.*"], + "not_rooms": ["!726s6s6q:example.com"] }, - "server_data": { - "types": [] + "events": { + "types": ["m.room.message"], + "not_rooms": ["!726s6s6q:example.com"], + "not_senders": ["@spam:example.com"] }, - "event_format": "client", - "event_fields": ["type", "content", "sender"] - } + "emphemeral": { + "types": ["m.receipt", "m.typing"], + "not_rooms": ["!726s6s6q:example.com"], + "not_senders": ["@spam:example.com"] + } + }, + "public_user_data": { + "types": ["m.presence"] + }, + "private_user_data": { + "types": [] + }, + "server_data": { + "types": [] + }, + "event_format": "client", + "event_fields": ["type", "content", "sender"] + } responses: 200: description: The filter was created. From e1f73f523318951d2303e2d538b26fb3478abeda Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Fri, 25 Sep 2015 18:09:17 +0100 Subject: [PATCH 05/31] Add a limit to filters --- api/client-server/v2_alpha/definitions/event_filter.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/api/client-server/v2_alpha/definitions/event_filter.json b/api/client-server/v2_alpha/definitions/event_filter.json index b8ab1352e..76d8be64e 100644 --- a/api/client-server/v2_alpha/definitions/event_filter.json +++ b/api/client-server/v2_alpha/definitions/event_filter.json @@ -1,6 +1,11 @@ { "type": "object", "properties": { + "limit": { + "type": "integer", + "description": + "The maximum number of events to return." + }, "types": { "type": "array", "description": From a0068e1adaa028d29bc00d5ad62dd5a5b6371b1b Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Fri, 25 Sep 2015 18:10:28 +0100 Subject: [PATCH 06/31] Draft documention for the v2 sync api --- .../v2_alpha/definitions/event_batch.json | 12 ++ .../v2_alpha/definitions/timeline_batch.json | 14 ++ api/client-server/v2_alpha/sync.yaml | 167 ++++++++++++++++++ 3 files changed, 193 insertions(+) create mode 100644 api/client-server/v2_alpha/definitions/event_batch.json create mode 100644 api/client-server/v2_alpha/definitions/timeline_batch.json create mode 100644 api/client-server/v2_alpha/sync.yaml diff --git a/api/client-server/v2_alpha/definitions/event_batch.json b/api/client-server/v2_alpha/definitions/event_batch.json new file mode 100644 index 000000000..c7cdbfb30 --- /dev/null +++ b/api/client-server/v2_alpha/definitions/event_batch.json @@ -0,0 +1,12 @@ +{ + "type": "object", + "properties": { + "events": { + "type": "array", + "description": "List of indicies into an events array", + "items": { + "type": "integer" + } + } + } +} diff --git a/api/client-server/v2_alpha/definitions/timeline_batch.json b/api/client-server/v2_alpha/definitions/timeline_batch.json new file mode 100644 index 000000000..dc62724bb --- /dev/null +++ b/api/client-server/v2_alpha/definitions/timeline_batch.json @@ -0,0 +1,14 @@ +{ + "type": "object", + "allOf": [{"$ref":"definitions/event_batch.json"}], + "properties": { + "limited": { + "type": "boolean", + "description": "Whether there are more events on the server" + }, + "prev_batch": { + "type": "string", + "description": "If the batch was limited then this is a token that can be supplied to the server to retrieve more events" + } + } +} diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml new file mode 100644 index 000000000..c857d2729 --- /dev/null +++ b/api/client-server/v2_alpha/sync.yaml @@ -0,0 +1,167 @@ +swagger: '2.0' +info: + title: "Matrix Client-Server v2 sync API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https +basePath: /_matrix/client/api/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: + "/sync": + get: + summary: Synchronise the client's state and receive new messages. + description: |- + Synchronise the client's state with the latest state on the server. + Client's use this API when they first log in to get an initial snapshot + of the state on the server, and then continue to call this API to get + incremental deltas to the state, and to receive new messages. + security: + - accessToken: [] + parameters: + - in: query + name: filter + type: string + description: |- + The ID of a filter created using the filter API. + - in: query + name: since + type: string + description: |- + A point in time to continue a sync from. + - in: query + name: timeout + type: integer + description: |- + The maximum time to poll in milliseconds before returning this + request. + responses: + 200: + description: + The initial snapshot or delta for the client to use to update their + state. + schema: + type: object + properties: + next_batch: + type: string + description: |- + The batch token to supply in the ``since`` param of the next + ``/sync`` request. + events: + type: array + description: |- + A list of event objects that are referred to by index in the + rest of the ``sync`` response. + items: + type: object + rooms: + type: array + description: |- + A list of rooms that the client needs to update. + items: + type: object + properties: + room_id: + type: string + description: |- + The ID of the room. + state: + description: |- + The state updates for the room. + allOf: + - $ref: "definitions/event_batch.json" + timeline: + description: |- + The timeline of messages and state changes in the room. + allOf: + - $ref: "definitions/timeline_batch.json" + ephemeral: + description: |- + The ephemeral events in the room that aren't recorded + in the timeline or state of the room. E.g. typing. + allOf: + - $ref: "definitions/event_batch.json" + public_user_data: + description: |- + The updates to publically visible user data. + allOf: + - $ref: "definitions/event_batch.json" + private_user_data: + description: |- + Updates to the data which is private to the user but shared + amoungst their devices. + allOf: + - $ref: "definitions/event_batch.json" + examples: + application/json: |- + { + "next_batch": "s72595_4483_1934", + "events": [ + { + "sender": "@bob:example.com", + "type": "com.example.weird.setting", + "content": {"setting1": true, "setting2": false} + }, + { + "sender": "@alice:example.com", + "type": "m.profile.display_name", + "content": {"display_name": "Alice"} + }, + { + "sender": "@alice:example.com", + "type": "m.presence", + "content": {"presence": "online"} + }, + { + "room_id": "!726s6s6q:example.com", + "type": "m.typing", + "content": {"user_ids": ["@alice:example.com"]} + }, + { + "sender": "@alice:example.com", + "room_id": "!726s6s6q:example.com", + "type": "m.room.member", + "state_key": "@alice:example.com", + "content": {"membership": "join"}, + "origin_server_ts": 1417731086795 + }, + { + "sender": "@bob:example.com", + "room_id": "!726s6s6q:example.com", + "type": "m.room.member", + "state_key": "@bob:example.com", + "content": {"membership": "join"}, + "origin_server_ts": 1417731086795 + }, + { + "sender": "@alice:example.com", + "room_id": "!726s6s6q:example.com", + "type": "m.room.message", + "unsigned": {"age": "124524", "txn_id": "1234"}, + "content": {"body": "I am a fish", "msgtype": "m.text"}, + "origin_server_ts": 1417731086797 + } + ], + "private_user_data": {"events": [0]}, + "public_user_data": {"events": [1, 2]}, + "rooms": [{ + "room_id": "!726s6s6q:example.com", + "ephemeral": {"events": [3]}, + "state": {"events": [4, 5]}, + "timeline": { + "events": [5,6], + "limited": true, + "prev_batch": "t34-23535_0_0" + } + }] + } From de07586ab786d8cc8431dfc1b23030e9a77d6b57 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Fri, 25 Sep 2015 19:34:55 +0100 Subject: [PATCH 07/31] Rename 'events' to 'timeline' in the sync filter --- api/client-server/v2_alpha/definitions/sync_filter.json | 2 +- api/client-server/v2_alpha/filter.yaml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/api/client-server/v2_alpha/definitions/sync_filter.json b/api/client-server/v2_alpha/definitions/sync_filter.json index c9c47646d..bfc8b51d6 100644 --- a/api/client-server/v2_alpha/definitions/sync_filter.json +++ b/api/client-server/v2_alpha/definitions/sync_filter.json @@ -9,7 +9,7 @@ "The state events to include for rooms.", "allOf": [{"$ref": "definitions/event_filter.json"}] }, - "events": { + "timeline": { "description": "The message and state update events to include for rooms.", "allOf": [{"$ref": "definitions/event_filter.json"}] diff --git a/api/client-server/v2_alpha/filter.yaml b/api/client-server/v2_alpha/filter.yaml index 5296f11ac..3e564f4b5 100644 --- a/api/client-server/v2_alpha/filter.yaml +++ b/api/client-server/v2_alpha/filter.yaml @@ -50,7 +50,7 @@ paths: "types": ["m.room.*"], "not_rooms": ["!726s6s6q:example.com"] }, - "events": { + "timeline": { "types": ["m.room.message"], "not_rooms": ["!726s6s6q:example.com"], "not_senders": ["@spam:example.com"] @@ -118,7 +118,7 @@ paths: "types": ["m.room.*"], "not_rooms": ["!726s6s6q:example.com"] }, - "events": { + "timeline": { "types": ["m.room.message"], "not_rooms": ["!726s6s6q:example.com"], "not_senders": ["@spam:example.com"] From c3b3b2df63ed8964d72517d0092b298988009d3f Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Fri, 25 Sep 2015 19:37:41 +0100 Subject: [PATCH 08/31] Add "set_presence" in the sync parameters --- api/client-server/v2_alpha/sync.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index c857d2729..5018080e9 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -38,6 +38,11 @@ paths: type: string description: |- A point in time to continue a sync from. + - in: query + name: set_presence + type: string + description: |- + Set the presence status of this client. - in: query name: timeout type: integer From 393d2831399e07316686129418d21b671571bfe7 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 28 Sep 2015 11:22:31 +0100 Subject: [PATCH 09/31] Add a "limit" to the timeline key in the example filter --- api/client-server/v2_alpha/filter.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/client-server/v2_alpha/filter.yaml b/api/client-server/v2_alpha/filter.yaml index 3e564f4b5..9bda2359d 100644 --- a/api/client-server/v2_alpha/filter.yaml +++ b/api/client-server/v2_alpha/filter.yaml @@ -51,6 +51,7 @@ paths: "not_rooms": ["!726s6s6q:example.com"] }, "timeline": { + "limit": 10, "types": ["m.room.message"], "not_rooms": ["!726s6s6q:example.com"], "not_senders": ["@spam:example.com"] @@ -119,6 +120,7 @@ paths: "not_rooms": ["!726s6s6q:example.com"] }, "timeline": { + "limit": 10, "types": ["m.room.message"], "not_rooms": ["!726s6s6q:example.com"], "not_senders": ["@spam:example.com"] From 1aa916d690bac548625f5a460ad916a0c6fdf43d Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 28 Sep 2015 12:52:12 +0100 Subject: [PATCH 10/31] s/indicies/indices/ --- api/client-server/v2_alpha/definitions/event_batch.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/v2_alpha/definitions/event_batch.json b/api/client-server/v2_alpha/definitions/event_batch.json index c7cdbfb30..ed2730c87 100644 --- a/api/client-server/v2_alpha/definitions/event_batch.json +++ b/api/client-server/v2_alpha/definitions/event_batch.json @@ -3,7 +3,7 @@ "properties": { "events": { "type": "array", - "description": "List of indicies into an events array", + "description": "List of indices into an events array", "items": { "type": "integer" } From f50e6d4c0ad8648dc601344b6ac67c468f4e25f8 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 28 Sep 2015 13:02:52 +0100 Subject: [PATCH 11/31] Add x-example fields for v2 /sync --- api/client-server/v2_alpha/sync.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 5018080e9..d307a683f 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -33,22 +33,26 @@ paths: type: string description: |- The ID of a filter created using the filter API. + x-example: "66696p746572" - in: query name: since type: string description: |- A point in time to continue a sync from. + x-example: "s72594_4483_1934" - in: query name: set_presence type: string description: |- Set the presence status of this client. + x-example: "online" - in: query name: timeout type: integer description: |- The maximum time to poll in milliseconds before returning this request. + x-example: 30000 responses: 200: description: From 3204c2f2b6cedf748618c594b86c514c2bf0b2b2 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 28 Sep 2015 13:04:37 +0100 Subject: [PATCH 12/31] Fix spelling --- api/client-server/v2_alpha/sync.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index d307a683f..318a1ab5b 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -108,7 +108,7 @@ paths: private_user_data: description: |- Updates to the data which is private to the user but shared - amoungst their devices. + amongst their devices. allOf: - $ref: "definitions/event_batch.json" examples: From 00fd4aac264619ec6a53afecd0757149ad7c038c Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 28 Sep 2015 13:06:04 +0100 Subject: [PATCH 13/31] s/publically/publicly/ --- api/client-server/v2_alpha/sync.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 318a1ab5b..e678d2d8e 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -102,7 +102,7 @@ paths: - $ref: "definitions/event_batch.json" public_user_data: description: |- - The updates to publically visible user data. + The updates to publicly visible user data. allOf: - $ref: "definitions/event_batch.json" private_user_data: From 41bc09ea22e8b18d0e509e666e30033dd3143e04 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 28 Sep 2015 13:20:01 +0100 Subject: [PATCH 14/31] Split the event_filter into a event_filter and a room_event_filter that extends it. So that we don't include "rooms" and "not_rooms" keys for the public_user_data and private_user_data filters. --- .../v2_alpha/definitions/event_filter.json | 16 -------------- .../definitions/room_event_filter.json | 21 +++++++++++++++++++ .../v2_alpha/definitions/sync_filter.json | 6 +++--- 3 files changed, 24 insertions(+), 19 deletions(-) create mode 100644 api/client-server/v2_alpha/definitions/room_event_filter.json diff --git a/api/client-server/v2_alpha/definitions/event_filter.json b/api/client-server/v2_alpha/definitions/event_filter.json index 76d8be64e..c15b81339 100644 --- a/api/client-server/v2_alpha/definitions/event_filter.json +++ b/api/client-server/v2_alpha/definitions/event_filter.json @@ -37,22 +37,6 @@ "items": { "type": "string" } - }, - "rooms": { - "type": "array", - "description": - "A list of room IDs to include. If this list is absent then all rooms are included.", - "items": { - "type": "string" - } - }, - "not_rooms": { - "type": "array", - "description": - "A list of room IDs to exclude. If this list is absent then no rooms are excluded.", - "items": { - "type": "string" - } } } } diff --git a/api/client-server/v2_alpha/definitions/room_event_filter.json b/api/client-server/v2_alpha/definitions/room_event_filter.json new file mode 100644 index 000000000..c234448e1 --- /dev/null +++ b/api/client-server/v2_alpha/definitions/room_event_filter.json @@ -0,0 +1,21 @@ +{ + "type": "object", + "properties": { + "rooms": { + "type": "array", + "description": + "A list of room IDs to include. If this list is absent then all rooms are included.", + "items": { + "type": "string" + } + }, + "not_rooms": { + "type": "array", + "description": + "A list of room IDs to exclude. If this list is absent then no rooms are excluded.", + "items": { + "type": "string" + } + } + } +} diff --git a/api/client-server/v2_alpha/definitions/sync_filter.json b/api/client-server/v2_alpha/definitions/sync_filter.json index bfc8b51d6..4ad3aa82d 100644 --- a/api/client-server/v2_alpha/definitions/sync_filter.json +++ b/api/client-server/v2_alpha/definitions/sync_filter.json @@ -7,17 +7,17 @@ "state": { "description": "The state events to include for rooms.", - "allOf": [{"$ref": "definitions/event_filter.json"}] + "allOf": [{"$ref": "definitions/room_event_filter.json"}] }, "timeline": { "description": "The message and state update events to include for rooms.", - "allOf": [{"$ref": "definitions/event_filter.json"}] + "allOf": [{"$ref": "definitions/room_event_filter.json"}] }, "ephemeral": { "description": "The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms.", - "allOf": [{"$ref": "definitions/event_filter.json"}] + "allOf": [{"$ref": "definitions/room_event_filter.json"}] } } }, From 940e22940dbde376db926b1b64fcda411cceffdd Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 28 Sep 2015 13:28:58 +0100 Subject: [PATCH 15/31] Document how the "not_foo" keys interact with the "foo" keys --- api/client-server/v2_alpha/definitions/event_filter.json | 4 ++-- api/client-server/v2_alpha/definitions/room_event_filter.json | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/api/client-server/v2_alpha/definitions/event_filter.json b/api/client-server/v2_alpha/definitions/event_filter.json index c15b81339..269bb5f04 100644 --- a/api/client-server/v2_alpha/definitions/event_filter.json +++ b/api/client-server/v2_alpha/definitions/event_filter.json @@ -17,7 +17,7 @@ "not_types": { "type": "array", "description": - "A list of event types to exclude. If this list is absent then no event types are excluded.", + "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter", "items": { "type": "string" } @@ -33,7 +33,7 @@ "not_senders": { "type": "array", "description": - "A list of sender IDs to exclude. If this list is absent then no senders are excluded.", + "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter", "items": { "type": "string" } diff --git a/api/client-server/v2_alpha/definitions/room_event_filter.json b/api/client-server/v2_alpha/definitions/room_event_filter.json index c234448e1..5be0fcd28 100644 --- a/api/client-server/v2_alpha/definitions/room_event_filter.json +++ b/api/client-server/v2_alpha/definitions/room_event_filter.json @@ -1,5 +1,6 @@ { "type": "object", + "allOf": [{"$ref": "definitions/event_filter.json"}], "properties": { "rooms": { "type": "array", @@ -12,7 +13,7 @@ "not_rooms": { "type": "array", "description": - "A list of room IDs to exclude. If this list is absent then no rooms are excluded.", + "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter", "items": { "type": "string" } From c115b4c2f4cfda43bdb6409edf9f14bfb8004151 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 28 Sep 2015 13:47:04 +0100 Subject: [PATCH 16/31] Document the valid values for the "set_presence" parameter --- api/client-server/v2_alpha/sync.yaml | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index e678d2d8e..0fe9173d9 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -43,9 +43,14 @@ paths: - in: query name: set_presence type: string + enum: ["offline"] description: |- - Set the presence status of this client. - x-example: "online" + Controls whether the client is automatically marked as online by + polling this API. If this parameter is omitted then the client is + automatically marked as online when it uses this API. Otherwise if + the parameter is set to "offline" then the client is not marked as + being online when it uses this API. + x-example: "offline" - in: query name: timeout type: integer From 14b42a41d653f601d7f6a7cc61539a1ccf7f55c7 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 28 Sep 2015 13:58:07 +0100 Subject: [PATCH 17/31] Document wildcard's in filters --- api/client-server/v2_alpha/definitions/event_filter.json | 8 ++++---- .../v2_alpha/definitions/room_event_filter.json | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/api/client-server/v2_alpha/definitions/event_filter.json b/api/client-server/v2_alpha/definitions/event_filter.json index 269bb5f04..1cdcb1f41 100644 --- a/api/client-server/v2_alpha/definitions/event_filter.json +++ b/api/client-server/v2_alpha/definitions/event_filter.json @@ -9,7 +9,7 @@ "types": { "type": "array", "description": - "A list of event types to include. If this list is absent then all event types are included.", + "A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters.", "items": { "type": "string" } @@ -17,7 +17,7 @@ "not_types": { "type": "array", "description": - "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter", + "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any sequence of characters.", "items": { "type": "string" } @@ -25,7 +25,7 @@ "senders": { "type": "array", "description": - "A list of senders IDs to include. If this list is absent then all senders are included.", + "A list of senders IDs to include. If this list is absent then all senders are included. A '*' can be used as a wildcard to match any sequence of characters.", "items": { "type": "string" } @@ -33,7 +33,7 @@ "not_senders": { "type": "array", "description": - "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter", + "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter. A '*' can be used as a wildcard to match any sequence of characters.", "items": { "type": "string" } diff --git a/api/client-server/v2_alpha/definitions/room_event_filter.json b/api/client-server/v2_alpha/definitions/room_event_filter.json index 5be0fcd28..86375781c 100644 --- a/api/client-server/v2_alpha/definitions/room_event_filter.json +++ b/api/client-server/v2_alpha/definitions/room_event_filter.json @@ -5,7 +5,7 @@ "rooms": { "type": "array", "description": - "A list of room IDs to include. If this list is absent then all rooms are included.", + "A list of room IDs to include. If this list is absent then all rooms are included. A '*' can be used as a wildcard to match any sequence of characters.", "items": { "type": "string" } @@ -13,7 +13,7 @@ "not_rooms": { "type": "array", "description": - "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter", + "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter. A '*' can be used as a wildcard to match any sequence of characters.", "items": { "type": "string" } From 9dd3b073948740b202e7301624eef6beaebd27c0 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 28 Sep 2015 14:00:56 +0100 Subject: [PATCH 18/31] Allow '.' characters in event field names to be escaped with '\' so that fields including a '.' can be included in a filter. I considered replacing '.' with '/'. Since '/' was less likely to appear in event field names. However if we used '\' to escape a literal '/' we risk confusing it with the JSON escape '\/'. --- api/client-server/v2_alpha/definitions/sync_filter.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/v2_alpha/definitions/sync_filter.json b/api/client-server/v2_alpha/definitions/sync_filter.json index 4ad3aa82d..b4f87e5fd 100644 --- a/api/client-server/v2_alpha/definitions/sync_filter.json +++ b/api/client-server/v2_alpha/definitions/sync_filter.json @@ -39,7 +39,7 @@ "event_fields": { "type": "array", "description": - "List of event fields to include. If this list is absent then all fields are included. The entries may include '.' charaters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A server may include more fields than were requested.", + "List of event fields to include. If this list is absent then all fields are included. The entries may include '.' charaters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A literal '.' character in a field name may be escaped using a '\\'. A server may include more fields than were requested.", "items": { "type": "string" } From 6ad6c40147cf5d80801aa076f76dad2bd54d609e Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 28 Sep 2015 14:11:45 +0100 Subject: [PATCH 19/31] List the allowed values for the 'event_format' as an enum --- api/client-server/v2_alpha/definitions/sync_filter.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/client-server/v2_alpha/definitions/sync_filter.json b/api/client-server/v2_alpha/definitions/sync_filter.json index b4f87e5fd..b909830b5 100644 --- a/api/client-server/v2_alpha/definitions/sync_filter.json +++ b/api/client-server/v2_alpha/definitions/sync_filter.json @@ -34,7 +34,8 @@ "event_format": { "description": "The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as receieved over federation. The default is 'client'.", - "type": "string" + "type": "string", + "enum": ["client", "federation"] }, "event_fields": { "type": "array", From 218cf94ead2dacce3b3f4443250465ef2f23fd24 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Tue, 29 Sep 2015 19:10:31 +0100 Subject: [PATCH 20/31] Replace the events array with events_map inside the room objects. Only use indirection for the state and timeline events. Use event_ids to reference the state and timeline events. --- .../v2_alpha/definitions/event_batch.json | 4 +- .../definitions/room_event_batch.json | 12 ++ .../v2_alpha/definitions/timeline_batch.json | 2 +- api/client-server/v2_alpha/sync.yaml | 134 ++++++++++-------- 4 files changed, 90 insertions(+), 62 deletions(-) create mode 100644 api/client-server/v2_alpha/definitions/room_event_batch.json diff --git a/api/client-server/v2_alpha/definitions/event_batch.json b/api/client-server/v2_alpha/definitions/event_batch.json index ed2730c87..75762d758 100644 --- a/api/client-server/v2_alpha/definitions/event_batch.json +++ b/api/client-server/v2_alpha/definitions/event_batch.json @@ -3,9 +3,9 @@ "properties": { "events": { "type": "array", - "description": "List of indices into an events array", + "description": "List of events", "items": { - "type": "integer" + "type": "object" } } } diff --git a/api/client-server/v2_alpha/definitions/room_event_batch.json b/api/client-server/v2_alpha/definitions/room_event_batch.json new file mode 100644 index 000000000..fcf148f36 --- /dev/null +++ b/api/client-server/v2_alpha/definitions/room_event_batch.json @@ -0,0 +1,12 @@ +{ + "type": "object", + "properties": { + "events": { + "type": "array", + "description": "List of event ids", + "items": { + "type": "string" + } + } + } +} diff --git a/api/client-server/v2_alpha/definitions/timeline_batch.json b/api/client-server/v2_alpha/definitions/timeline_batch.json index dc62724bb..ddf8d3416 100644 --- a/api/client-server/v2_alpha/definitions/timeline_batch.json +++ b/api/client-server/v2_alpha/definitions/timeline_batch.json @@ -1,6 +1,6 @@ { "type": "object", - "allOf": [{"$ref":"definitions/event_batch.json"}], + "allOf": [{"$ref":"definitions/room_event_batch.json"}], "properties": { "limited": { "type": "boolean", diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 0fe9173d9..1df7dace1 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -71,13 +71,6 @@ paths: description: |- The batch token to supply in the ``since`` param of the next ``/sync`` request. - events: - type: array - description: |- - A list of event objects that are referred to by index in the - rest of the ``sync`` response. - items: - type: object rooms: type: array description: |- @@ -89,11 +82,20 @@ paths: type: string description: |- The ID of the room. + event_map: + type: object + description: |- + A map from event ID to events for this room. The events + are referenced from the ``timeline`` and ``state`` keys + for this room. + additionalProperties: + description: An event object. + type: object state: description: |- The state updates for the room. allOf: - - $ref: "definitions/event_batch.json" + - $ref: "definitions/room_event_batch.json" timeline: description: |- The timeline of messages and state changes in the room. @@ -120,62 +122,76 @@ paths: application/json: |- { "next_batch": "s72595_4483_1934", - "events": [ - { - "sender": "@bob:example.com", - "type": "com.example.weird.setting", - "content": {"setting1": true, "setting2": false} - }, - { - "sender": "@alice:example.com", - "type": "m.profile.display_name", - "content": {"display_name": "Alice"} - }, - { - "sender": "@alice:example.com", - "type": "m.presence", - "content": {"presence": "online"} - }, - { - "room_id": "!726s6s6q:example.com", - "type": "m.typing", - "content": {"user_ids": ["@alice:example.com"]} - }, - { - "sender": "@alice:example.com", - "room_id": "!726s6s6q:example.com", - "type": "m.room.member", - "state_key": "@alice:example.com", - "content": {"membership": "join"}, - "origin_server_ts": 1417731086795 - }, - { - "sender": "@bob:example.com", - "room_id": "!726s6s6q:example.com", - "type": "m.room.member", - "state_key": "@bob:example.com", - "content": {"membership": "join"}, - "origin_server_ts": 1417731086795 - }, - { - "sender": "@alice:example.com", - "room_id": "!726s6s6q:example.com", - "type": "m.room.message", - "unsigned": {"age": "124524", "txn_id": "1234"}, - "content": {"body": "I am a fish", "msgtype": "m.text"}, - "origin_server_ts": 1417731086797 - } - ], - "private_user_data": {"events": [0]}, - "public_user_data": {"events": [1, 2]}, + "private_user_data": { + "events": [ + { + "sender": "@bob:example.com", + "type": "com.example.weird.setting", + "content": {"setting1": true, "setting2": false} + } + ] + }, + "public_user_data": { + "events": [ + { + "sender": "@alice:example.com", + "type": "m.profile.display_name", + "content": {"display_name": "Alice"} + }, + { + "sender": "@alice:example.com", + "type": "m.presence", + "content": {"presence": "online"} + } + ] + }, "rooms": [{ "room_id": "!726s6s6q:example.com", - "ephemeral": {"events": [3]}, - "state": {"events": [4, 5]}, + "event_map": { + "$66697273743031:example.com": { + "sender": "@alice:example.com", + "type": "m.room.member", + "state_key": "@alice:example.com", + "content": {"membership": "join"}, + "origin_server_ts": 1417731086795 + }, + "$7365636s6r6432:example.com": { + "sender": "@bob:example.com", + "type": "m.room.member", + "state_key": "@bob:example.com", + "content": {"membership": "join"}, + "origin_server_ts": 1417731086795 + }, + "$74686972643033:example.com": { + "sender": "@alice:example.com", + "type": "m.room.message", + "unsigned": {"age": "124524", "txn_id": "1234"}, + "content": {"body": "I am a fish", "msgtype": "m.text"}, + "origin_server_ts": 1417731086797 + } + }, + "state": { + "events": [ + "$66697273743031:example.com", + "$7365636s6r6432:example.com" + ] + }, "timeline": { - "events": [5,6], + "events": [ + "$7365636s6r6432:example.com", + "$74686972643033:example.com" + ], "limited": true, "prev_batch": "t34-23535_0_0" + }, + "ephemeral": { + "events": [ + { + "room_id": "!726s6s6q:example.com", + "type": "m.typing", + "content": {"user_ids": ["@alice:example.com"]} + } + ] } }] } From 4cb3f78d2bc8205c87e566e16a049732c2f3bad5 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Tue, 29 Sep 2015 19:48:48 +0100 Subject: [PATCH 21/31] Wrap the "rooms" list inside an object so that we can add keys for pagination later --- api/client-server/v2_alpha/sync.yaml | 165 ++++++++++++++------------- 1 file changed, 85 insertions(+), 80 deletions(-) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 1df7dace1..58a2c4956 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -72,41 +72,44 @@ paths: The batch token to supply in the ``since`` param of the next ``/sync`` request. rooms: - type: array - description: |- - A list of rooms that the client needs to update. - items: - type: object - properties: - room_id: - type: string - description: |- - The ID of the room. - event_map: + type: object + properties: + roomlist: + type: array + description: |- + A list of rooms that the client needs to update. + items: type: object - description: |- - A map from event ID to events for this room. The events - are referenced from the ``timeline`` and ``state`` keys - for this room. - additionalProperties: - description: An event object. - type: object - state: - description: |- - The state updates for the room. - allOf: - - $ref: "definitions/room_event_batch.json" - timeline: - description: |- - The timeline of messages and state changes in the room. - allOf: - - $ref: "definitions/timeline_batch.json" - ephemeral: - description: |- - The ephemeral events in the room that aren't recorded - in the timeline or state of the room. E.g. typing. - allOf: - - $ref: "definitions/event_batch.json" + properties: + room_id: + type: string + description: |- + The ID of the room. + event_map: + type: object + description: |- + A map from event ID to events for this room. The events + are referenced from the ``timeline`` and ``state`` keys + for this room. + additionalProperties: + description: An event object. + type: object + state: + description: |- + The state updates for the room. + allOf: + - $ref: "definitions/room_event_batch.json" + timeline: + description: |- + The timeline of messages and state changes in the room. + allOf: + - $ref: "definitions/timeline_batch.json" + ephemeral: + description: |- + The ephemeral events in the room that aren't recorded + in the timeline or state of the room. E.g. typing. + allOf: + - $ref: "definitions/event_batch.json" public_user_data: description: |- The updates to publicly visible user data. @@ -145,53 +148,55 @@ paths: } ] }, - "rooms": [{ - "room_id": "!726s6s6q:example.com", - "event_map": { - "$66697273743031:example.com": { - "sender": "@alice:example.com", - "type": "m.room.member", - "state_key": "@alice:example.com", - "content": {"membership": "join"}, - "origin_server_ts": 1417731086795 + "rooms": { + "roomlist": [{ + "room_id": "!726s6s6q:example.com", + "event_map": { + "$66697273743031:example.com": { + "sender": "@alice:example.com", + "type": "m.room.member", + "state_key": "@alice:example.com", + "content": {"membership": "join"}, + "origin_server_ts": 1417731086795 + }, + "$7365636s6r6432:example.com": { + "sender": "@bob:example.com", + "type": "m.room.member", + "state_key": "@bob:example.com", + "content": {"membership": "join"}, + "origin_server_ts": 1417731086795 + }, + "$74686972643033:example.com": { + "sender": "@alice:example.com", + "type": "m.room.message", + "unsigned": {"age": "124524", "txn_id": "1234"}, + "content": {"body": "I am a fish", "msgtype": "m.text"}, + "origin_server_ts": 1417731086797 + } }, - "$7365636s6r6432:example.com": { - "sender": "@bob:example.com", - "type": "m.room.member", - "state_key": "@bob:example.com", - "content": {"membership": "join"}, - "origin_server_ts": 1417731086795 + "state": { + "events": [ + "$66697273743031:example.com", + "$7365636s6r6432:example.com" + ] }, - "$74686972643033:example.com": { - "sender": "@alice:example.com", - "type": "m.room.message", - "unsigned": {"age": "124524", "txn_id": "1234"}, - "content": {"body": "I am a fish", "msgtype": "m.text"}, - "origin_server_ts": 1417731086797 + "timeline": { + "events": [ + "$7365636s6r6432:example.com", + "$74686972643033:example.com" + ], + "limited": true, + "prev_batch": "t34-23535_0_0" + }, + "ephemeral": { + "events": [ + { + "room_id": "!726s6s6q:example.com", + "type": "m.typing", + "content": {"user_ids": ["@alice:example.com"]} + } + ] } - }, - "state": { - "events": [ - "$66697273743031:example.com", - "$7365636s6r6432:example.com" - ] - }, - "timeline": { - "events": [ - "$7365636s6r6432:example.com", - "$74686972643033:example.com" - ], - "limited": true, - "prev_batch": "t34-23535_0_0" - }, - "ephemeral": { - "events": [ - { - "room_id": "!726s6s6q:example.com", - "type": "m.typing", - "content": {"user_ids": ["@alice:example.com"]} - } - ] - } - }] + }] + } } From 931057accfdd2756686c3c896a22157b3f5faf51 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Wed, 30 Sep 2015 10:30:39 +0100 Subject: [PATCH 22/31] Add a top level presence key for the presence events and remove the public_user_data/private_user_data for now --- .../v2_alpha/definitions/sync_filter.json | 9 ++----- api/client-server/v2_alpha/filter.yaml | 22 +++++----------- api/client-server/v2_alpha/sync.yaml | 26 +++---------------- 3 files changed, 11 insertions(+), 46 deletions(-) diff --git a/api/client-server/v2_alpha/definitions/sync_filter.json b/api/client-server/v2_alpha/definitions/sync_filter.json index b909830b5..0cd6a7986 100644 --- a/api/client-server/v2_alpha/definitions/sync_filter.json +++ b/api/client-server/v2_alpha/definitions/sync_filter.json @@ -21,14 +21,9 @@ } } }, - "public_user_data": { + "presence": { "description": - "The public user data, e.g. profile and presence, to include.", - "allOf": [{"$ref": "definitions/event_filter.json"}] - }, - "private_user_data": { - "description": - "Events that are private to a user but shared amoungst their devices, e.g. notification settings, to include.", + "The presence updates to include.", "allOf": [{"$ref": "definitions/event_filter.json"}] }, "event_format": { diff --git a/api/client-server/v2_alpha/filter.yaml b/api/client-server/v2_alpha/filter.yaml index 9bda2359d..30d528447 100644 --- a/api/client-server/v2_alpha/filter.yaml +++ b/api/client-server/v2_alpha/filter.yaml @@ -62,14 +62,9 @@ paths: "not_senders": ["@spam:example.com"] } }, - "public_user_data": { - "types": ["m.presence"] - }, - "private_user_data": { - "types": [] - }, - "server_data": { - "types": [] + "presence": { + "types": ["m.presence"], + "not_senders": ["@alice:example.com"] }, "event_format": "client", "event_fields": ["type", "content", "sender"] @@ -131,14 +126,9 @@ paths: "not_senders": ["@spam:example.com"] } }, - "public_user_data": { - "types": ["m.presence"] - }, - "private_user_data": { - "types": [] - }, - "server_data": { - "types": [] + "presence": { + "types": ["m.presence"], + "not_senders": ["@alice:example.com"] }, "event_format": "client", "event_fields": ["type", "content", "sender"] diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 58a2c4956..238fab630 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -110,37 +110,17 @@ paths: in the timeline or state of the room. E.g. typing. allOf: - $ref: "definitions/event_batch.json" - public_user_data: + presence: description: |- - The updates to publicly visible user data. - allOf: - - $ref: "definitions/event_batch.json" - private_user_data: - description: |- - Updates to the data which is private to the user but shared - amongst their devices. + The updates to the presence status of other users. allOf: - $ref: "definitions/event_batch.json" examples: application/json: |- { "next_batch": "s72595_4483_1934", - "private_user_data": { + "presence": { "events": [ - { - "sender": "@bob:example.com", - "type": "com.example.weird.setting", - "content": {"setting1": true, "setting2": false} - } - ] - }, - "public_user_data": { - "events": [ - { - "sender": "@alice:example.com", - "type": "m.profile.display_name", - "content": {"display_name": "Alice"} - }, { "sender": "@alice:example.com", "type": "m.presence", From a73cc50aa963f05d86783272a1ab105a70a84f34 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Fri, 2 Oct 2015 13:03:39 +0100 Subject: [PATCH 23/31] s|client/api/v2_alpha|client/v2_alpha| --- api/client-server/v2_alpha/filter.yaml | 2 +- api/client-server/v2_alpha/sync.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/v2_alpha/filter.yaml b/api/client-server/v2_alpha/filter.yaml index 30d528447..37a0a3aaa 100644 --- a/api/client-server/v2_alpha/filter.yaml +++ b/api/client-server/v2_alpha/filter.yaml @@ -5,7 +5,7 @@ info: host: localhost:8008 schemes: - https -basePath: /_matrix/client/api/v2_alpha +basePath: /_matrix/client/v2_alpha consumes: - application/json produces: diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 238fab630..7daa33f52 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -5,7 +5,7 @@ info: host: localhost:8008 schemes: - https -basePath: /_matrix/client/api/v2_alpha +basePath: /_matrix/client/v2_alpha consumes: - application/json produces: From bde003fe8618195122dd300b03913dc1b28710c3 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Fri, 2 Oct 2015 16:14:24 +0100 Subject: [PATCH 24/31] Split the rooms out into a separate top level key. Divide the rooms into separate groups in preparation for adding tag support. Further subdivide the rooms into "joined/invited/archived" based the membership of the user in the room because that membership affects what events the user can view from the room. E.g only users that are joined to a room may see the ephemeral events for the room. --- api/client-server/v2_alpha/sync.yaml | 114 +++++++++++++++++---------- 1 file changed, 74 insertions(+), 40 deletions(-) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 7daa33f52..7a003745e 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -5,7 +5,7 @@ info: host: localhost:8008 schemes: - https -basePath: /_matrix/client/v2_alpha +basePath: /_matrix/client/api/v2_alpha consumes: - application/json produces: @@ -73,43 +73,71 @@ paths: ``/sync`` request. rooms: type: object - properties: - roomlist: - type: array - description: |- - A list of rooms that the client needs to update. - items: + description: |- + The updates to rooms, grouped according to the filter. By + default there is a single ``default`` group. + additionalProperties: + joined: + type: array + description: |- + A list of room ids that the user is a member of that + have updates. + items: + type: string. + invited: + type: array + description: |- + A list of room ids that the user has been invited to. + The entries in the room_map will have a ``invite`` key + containing the ``m.room.member`` event of the invite. + items: + type: string. + archived: + type: array + description: |- + A list of room ids that the user has left or been + banned from. The entries in the room_map will have a + ``state`` key and a ``timeline`` key. But will lack the + ``emphemeral`` key. + items: + type: string. + room_map: + description: |- + Map from room id to the updates for that room. The room ids + are referenced from the ``rooms`` key. + type: object + additionalProperties: + type: object + properties: + room_id: + type: string + description: |- + The ID of the room. + event_map: type: object - properties: - room_id: - type: string - description: |- - The ID of the room. - event_map: - type: object - description: |- - A map from event ID to events for this room. The events - are referenced from the ``timeline`` and ``state`` keys - for this room. - additionalProperties: - description: An event object. - type: object - state: - description: |- - The state updates for the room. - allOf: - - $ref: "definitions/room_event_batch.json" - timeline: - description: |- - The timeline of messages and state changes in the room. - allOf: - - $ref: "definitions/timeline_batch.json" - ephemeral: - description: |- - The ephemeral events in the room that aren't recorded - in the timeline or state of the room. E.g. typing. - allOf: - - $ref: "definitions/event_batch.json" + description: |- + A map from event ID to events for this room. The events + are referenced from the ``timeline`` and ``state`` keys + for this room. + additionalProperties: + description: An event object. + type: object + state: + description: |- + The state updates for the room. + allOf: + - $ref: "definitions/room_event_batch.json" + timeline: + description: |- + The timeline of messages and state changes in the room. + allOf: + - $ref: "definitions/timeline_batch.json" + ephemeral: + description: |- + The ephemeral events in the room that aren't recorded + in the timeline or state of the room. E.g. typing. + allOf: + - $ref: "definitions/event_batch.json" presence: description: |- The updates to the presence status of other users. @@ -129,8 +157,14 @@ paths: ] }, "rooms": { - "roomlist": [{ - "room_id": "!726s6s6q:example.com", + "default": { + "invited": [], + "archived": [], + "joined": ["!726s6s6q:example.com"] + } + }, + "room_map": { + "!726s6s6q:example.com": { "event_map": { "$66697273743031:example.com": { "sender": "@alice:example.com", @@ -177,6 +211,6 @@ paths: } ] } - }] + } } } From 047419f2ad9b9b72ed7de144d9c97bcc17e62030 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Fri, 2 Oct 2015 16:21:48 +0100 Subject: [PATCH 25/31] Remove the room_id since it is redundent. Remove text about invite event handling till we've thought about it some more. --- api/client-server/v2_alpha/sync.yaml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 7a003745e..6b7a1b2ae 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -88,8 +88,6 @@ paths: type: array description: |- A list of room ids that the user has been invited to. - The entries in the room_map will have a ``invite`` key - containing the ``m.room.member`` event of the invite. items: type: string. archived: @@ -109,10 +107,6 @@ paths: additionalProperties: type: object properties: - room_id: - type: string - description: |- - The ID of the room. event_map: type: object description: |- From 97cdd8106cec02871d58a54f1abcafe7b33481a2 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 5 Oct 2015 14:21:16 +0100 Subject: [PATCH 26/31] s|client/api/v2_alpha|/client/v2_alpha| --- api/client-server/v2_alpha/sync.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 6b7a1b2ae..c502d926f 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -5,7 +5,7 @@ info: host: localhost:8008 schemes: - https -basePath: /_matrix/client/api/v2_alpha +basePath: /_matrix/client/v2_alpha consumes: - application/json produces: From ed0f6d3ff38848250f830ad8ade02838d9c82f3e Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 5 Oct 2015 14:22:50 +0100 Subject: [PATCH 27/31] Typo --- api/client-server/v2_alpha/sync.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index c502d926f..437af251e 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -96,7 +96,7 @@ paths: A list of room ids that the user has left or been banned from. The entries in the room_map will have a ``state`` key and a ``timeline`` key. But will lack the - ``emphemeral`` key. + ``ephemeral`` key. items: type: string. room_map: From a7b808c5cd8ec423342a9844241a31bdc339eff8 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 5 Oct 2015 15:26:33 +0100 Subject: [PATCH 28/31] Add a invite_state key for holding the state that is bundled with an invite. This is kept separate from the actual state for the room as it may be derived from an incomplete, unverified copy of the state that was bundled with an invite event received over federation. --- api/client-server/v2_alpha/sync.yaml | 38 +++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 437af251e..070788231 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -88,6 +88,9 @@ paths: type: array description: |- A list of room ids that the user has been invited to. + The entries in the room_map will have an + ``invite_state`` key. But will lack the ``ephemeral`` + key, the ``timeline`` key and the ``state`` key. items: type: string. archived: @@ -132,6 +135,21 @@ paths: in the timeline or state of the room. E.g. typing. allOf: - $ref: "definitions/event_batch.json" + invite_state: + description: |- + The state of a room that the user has been invited to. + These state events may only have the ``type``, + ``state_key`` and ``content`` keys present. + These events do not replace any state that the client + already has for the room, for example if the client has + archived the room. Instead the client should keep two + separate copies of the state: the one from the + ``invite_state`` and one from the archived ``state``. + If the client joins the room then the current state + will be given as a delta against the archived ``state`` + not the ``invite_state``. + allOf: + - $ref: "definitions/event_batch.json" presence: description: |- The updates to the presence status of other users. @@ -152,7 +170,7 @@ paths: }, "rooms": { "default": { - "invited": [], + "invited": ["!696r7674:example.com"], "archived": [], "joined": ["!726s6s6q:example.com"] } @@ -205,6 +223,24 @@ paths: } ] } + }, + "!696r7674:example.com": { + "invite_state": { + "events": [ + { + "sender": "@alice:example.com", + "type": "m.room.name", + "state_key": "@alice:example.com", + "content": {"name": "My Room Name"} + }, + { + "sender": "@alice:example.com", + "type": "m.room.name", + "state_key": "", + "content": {"membership": "invite"} + } + ] + } } } } From bbb5fa9398447f2196cf7c62ec457c7f717704ce Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 5 Oct 2015 15:36:01 +0100 Subject: [PATCH 29/31] Fix the state_key in the example v2 response, include the "sender" key in the list of keys included with invite_state events --- api/client-server/v2_alpha/sync.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 070788231..49f42c6e1 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -138,8 +138,8 @@ paths: invite_state: description: |- The state of a room that the user has been invited to. - These state events may only have the ``type``, - ``state_key`` and ``content`` keys present. + These state events may only have the `sender``, + ``type``, ``state_key`` and ``content`` keys present. These events do not replace any state that the client already has for the room, for example if the client has archived the room. Instead the client should keep two @@ -230,13 +230,13 @@ paths: { "sender": "@alice:example.com", "type": "m.room.name", - "state_key": "@alice:example.com", + "state_key": "", "content": {"name": "My Room Name"} }, { "sender": "@alice:example.com", "type": "m.room.name", - "state_key": "", + "state_key": "@bob:example.com", "content": {"membership": "invite"} } ] From 0e5b00feaaa9c337fd097e13780fa7d06158ac0d Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 5 Oct 2015 16:10:25 +0100 Subject: [PATCH 30/31] Fix event type in v2 sync example --- api/client-server/v2_alpha/sync.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 49f42c6e1..1b83d1d9d 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -235,7 +235,7 @@ paths: }, { "sender": "@alice:example.com", - "type": "m.room.name", + "type": "m.room.member", "state_key": "@bob:example.com", "content": {"membership": "invite"} } From 0ce533d153e9656818dfdefa565b1356afa4b391 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Tue, 6 Oct 2015 13:42:03 +0100 Subject: [PATCH 31/31] Split the room_map into separate sections based on whether they are "joined/invited/archived". Rename the room_map to rooms and remove the grouping indirection. When we want groups then we can add them under a separate key, either at the top-level or as part of the events themselves. --- api/client-server/v2_alpha/sync.yaml | 295 ++++++++++++++------------- 1 file changed, 153 insertions(+), 142 deletions(-) diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 1b83d1d9d..7d60d6392 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -74,82 +74,92 @@ paths: rooms: type: object description: |- - The updates to rooms, grouped according to the filter. By - default there is a single ``default`` group. - additionalProperties: - joined: - type: array - description: |- - A list of room ids that the user is a member of that - have updates. - items: - type: string. - invited: - type: array - description: |- - A list of room ids that the user has been invited to. - The entries in the room_map will have an - ``invite_state`` key. But will lack the ``ephemeral`` - key, the ``timeline`` key and the ``state`` key. - items: - type: string. - archived: - type: array - description: |- - A list of room ids that the user has left or been - banned from. The entries in the room_map will have a - ``state`` key and a ``timeline`` key. But will lack the - ``ephemeral`` key. - items: - type: string. - room_map: - description: |- - Map from room id to the updates for that room. The room ids - are referenced from the ``rooms`` key. - type: object - additionalProperties: - type: object - properties: - event_map: + Updates to rooms. + properties: + joined: + type: object + additionalProperties: + type: object + properties: + event_map: + type: object + description: |- + A map from event ID to events for this room. The + events are referenced from the ``timeline`` and + ``state`` keys for this room. + additionalProperties: + description: An event object. + type: object + state: + description: |- + The state updates for the room. + allOf: + - $ref: "definitions/room_event_batch.json" + timeline: + description: |- + The timeline of messages and state changes in the + room. + allOf: + - $ref: "definitions/timeline_batch.json" + ephemeral: + description: |- + The ephemeral events in the room that aren't + recorded in the timeline or state of the room. + e.g. typing. + allOf: + - $ref: "definitions/event_batch.json" + invited: + type: object + description: |- + The rooms that the user has been invited to. + additionalProperties: type: object - description: |- - A map from event ID to events for this room. The events - are referenced from the ``timeline`` and ``state`` keys - for this room. - additionalProperties: - description: An event object. - type: object - state: - description: |- - The state updates for the room. - allOf: - - $ref: "definitions/room_event_batch.json" - timeline: - description: |- - The timeline of messages and state changes in the room. - allOf: - - $ref: "definitions/timeline_batch.json" - ephemeral: - description: |- - The ephemeral events in the room that aren't recorded - in the timeline or state of the room. E.g. typing. - allOf: - - $ref: "definitions/event_batch.json" - invite_state: - description: |- - The state of a room that the user has been invited to. - These state events may only have the `sender``, - ``type``, ``state_key`` and ``content`` keys present. - These events do not replace any state that the client - already has for the room, for example if the client has - archived the room. Instead the client should keep two - separate copies of the state: the one from the - ``invite_state`` and one from the archived ``state``. - If the client joins the room then the current state - will be given as a delta against the archived ``state`` - not the ``invite_state``. - allOf: - - $ref: "definitions/event_batch.json" + properties: + invite_state: + description: |- + The state of a room that the user has been invited + to. These state events may only have the `sender``, + ``type``, ``state_key`` and ``content`` keys + present. These events do not replace any state that + the client already has for the room, for example if + the client has archived the room. Instead the + client should keep two separate copies of the + state: the one from the ``invite_state`` and one + from the archived ``state``. If the client joins + the room then the current state will be given as a + delta against the archived ``state`` not the + ``invite_state``. + allOf: + - $ref: "definitions/event_batch.json" + archived: + type: object + description: |- + The rooms that the user has left or been banned from. The + entries in the room_map will lack an ``ephemeral`` key. + additionalProperties: + type: object + properties: + event_map: + type: object + description: |- + A map from event ID to events for this room. The + events are referenced from the ``timeline`` and + ``state`` keys for this room. + additionalProperties: + description: An event object. + type: object + state: + description: |- + The state updates for the room up to the point when + the user left. + allOf: + - $ref: "definitions/room_event_batch.json" + timeline: + description: |- + The timeline of messages and state changes in the + room up to the point when the user left. + allOf: + - $ref: "definitions/timeline_batch.json" presence: description: |- The updates to the presence status of other users. @@ -169,78 +179,79 @@ paths: ] }, "rooms": { - "default": { - "invited": ["!696r7674:example.com"], - "archived": [], - "joined": ["!726s6s6q:example.com"] - } - }, - "room_map": { - "!726s6s6q:example.com": { - "event_map": { - "$66697273743031:example.com": { - "sender": "@alice:example.com", - "type": "m.room.member", - "state_key": "@alice:example.com", - "content": {"membership": "join"}, - "origin_server_ts": 1417731086795 - }, - "$7365636s6r6432:example.com": { - "sender": "@bob:example.com", - "type": "m.room.member", - "state_key": "@bob:example.com", - "content": {"membership": "join"}, - "origin_server_ts": 1417731086795 - }, - "$74686972643033:example.com": { - "sender": "@alice:example.com", - "type": "m.room.message", - "unsigned": {"age": "124524", "txn_id": "1234"}, - "content": {"body": "I am a fish", "msgtype": "m.text"}, - "origin_server_ts": 1417731086797 - } - }, - "state": { - "events": [ - "$66697273743031:example.com", - "$7365636s6r6432:example.com" - ] - }, - "timeline": { - "events": [ - "$7365636s6r6432:example.com", - "$74686972643033:example.com" - ], - "limited": true, - "prev_batch": "t34-23535_0_0" - }, - "ephemeral": { - "events": [ - { - "room_id": "!726s6s6q:example.com", - "type": "m.typing", - "content": {"user_ids": ["@alice:example.com"]} - } - ] - } - }, - "!696r7674:example.com": { - "invite_state": { - "events": [ - { + "joined": { + "!726s6s6q:example.com": { + "event_map": { + "$66697273743031:example.com": { "sender": "@alice:example.com", - "type": "m.room.name", - "state_key": "", - "content": {"name": "My Room Name"} + "type": "m.room.member", + "state_key": "@alice:example.com", + "content": {"membership": "join"}, + "origin_server_ts": 1417731086795 }, - { - "sender": "@alice:example.com", + "$7365636s6r6432:example.com": { + "sender": "@bob:example.com", "type": "m.room.member", "state_key": "@bob:example.com", - "content": {"membership": "invite"} + "content": {"membership": "join"}, + "origin_server_ts": 1417731086795 + }, + "$74686972643033:example.com": { + "sender": "@alice:example.com", + "type": "m.room.message", + "unsigned": {"age": "124524", "txn_id": "1234"}, + "content": { + "body": "I am a fish", + "msgtype": "m.text" + }, + "origin_server_ts": 1417731086797 } - ] + }, + "state": { + "events": [ + "$66697273743031:example.com", + "$7365636s6r6432:example.com" + ] + }, + "timeline": { + "events": [ + "$7365636s6r6432:example.com", + "$74686972643033:example.com" + ], + "limited": true, + "prev_batch": "t34-23535_0_0" + }, + "ephemeral": { + "events": [ + { + "room_id": "!726s6s6q:example.com", + "type": "m.typing", + "content": {"user_ids": ["@alice:example.com"]} + } + ] + } } - } + }, + "invited": { + "!696r7674:example.com": { + "invite_state": { + "events": [ + { + "sender": "@alice:example.com", + "type": "m.room.name", + "state_key": "", + "content": {"name": "My Room Name"} + }, + { + "sender": "@alice:example.com", + "type": "m.room.member", + "state_key": "@bob:example.com", + "content": {"membership": "invite"} + } + ] + } + } + }, + "archived": {} } }