Merge pull request #78 from matrix-org/module-typing2

Typing module

api/client-server/v1/typing.yaml

@@ -0,0 +1,77 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Typing API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+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}/typing/{userId}":
+    put:
+      summary: Informs the server that the user has started or stopped typing.
+      description: |-
+        This tells the server that the user is typing for the next N
+        milliseconds where N is the value specified in the ``timeout`` key.
+        Alternatively, if ``typing`` is ``false``, it tells the server that the
+        user has stopped typing.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user who has started to type.
+          required: true
+          x-example: "@alice:example.com"
+        - in: path
+          type: string
+          name: roomId
+          description: The room in which the user is typing.
+          required: true
+          x-example: "!wefh3sfukhs:example.com"
+        - in: body
+          name: typingState
+          description: The current typing state.
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "typing": true,
+                "timeout": 30000
+              }
+            properties:
+              typing:
+                type: boolean
+                description: |-
+                  Whether the user is typing or not. If ``false``, the ``timeout``
+                  key can be omitted.
+              timeout:
+                type: integer
+                description: The length of time in milliseconds to mark this user as typing.
+            required: ["typing"]
+      responses:
+        200:
+          description: The new typing state was set.
+          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.typing

@@ -0,0 +1,7 @@
+{
+    "type": "m.typing",
+    "room_id": "!z0mnsuiwhifuhwwfw:matrix.org",
+    "content": {
+        "user_ids": ["@alice:matrix.org", "@bob:example.com"]
+    }
+}

event-schemas/schema/v1/m.typing

@@ -0,0 +1,28 @@
+{
+    "type": "object",
+    "title": "Typing Event",
+    "description": "Informs the client of the list of users currently typing.",
+    "properties": {
+        "content": {
+            "type": "object",
+            "properties": {
+                "user_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "The list of user IDs typing in this room, if any."
+                }
+            },
+            "required": ["user_ids"]
+        },
+        "type": {
+            "type": "string",
+            "enum": ["m.typing"]
+        },
+        "room_id": {
+            "type": "string"
+        }
+    },
+    "required": ["type", "room_id", "content"]
+}

specification/0-intro.rst

@@ -180,6 +180,8 @@ of a "Room".
 Event Graphs
 ~~~~~~~~~~~~
 
+.. _sect:event-graph:
+
 Events exchanged in the context of a room are stored in a directed acyclic graph
 (DAG) called an ``event graph``. The partial ordering of this graph gives the
 chronological ordering of events within the room. Each event in the graph has a

specification/modules/typing_notifications.rst

@@ -1,49 +1,46 @@
 Typing Notifications
---------------------
+====================
 
 .. _module:typing:
 
-Client APIs
-~~~~~~~~~~~
+Users may wish to be informed when another user is typing in a room. This can be
+achieved using typing notifications. These are ephemeral events scoped to a
+``room_id``. This means they do not form part of the `Event Graph`_ but still
+have a ``room_id`` key.
 
-To set "I am typing for the next N msec"::
+.. _Event Graph: `sect:event-graph`_
 
-  PUT .../rooms/<room_id>/typing/<user_id>
-  Content:  { "typing": true, "timeout": N }
-  # timeout is in milliseconds; suggested no more than 20 or 30 seconds
+Events
+------
 
-This should be re-sent by the client to continue informing the server the user
-is still typing; a safety margin of 5 seconds before the expected
-timeout runs out is recommended. Just keep declaring a new timeout, it will
-replace the old one.
+{{m_typing_event}}
 
-To set "I am no longer typing"::
+Client behaviour
+----------------
 
-  PUT ../rooms/<room_id>/typing/<user_id>
-  Content: { "typing": false }
+When a client receives an ``m.typing`` event, it MUST use the user ID list to
+**REPLACE** its knowledge of every user who is currently typing. The reason for
+this is that the server *does not remember* users who are not currently typing
+as that list gets big quickly. The client should mark as not typing any user ID
+who is not in that list.
 
-Client Events
-~~~~~~~~~~~~~
+It is recommended that clients store a ``boolean`` indicating whether the user
+is typing or not. Whilst this value is ``true`` a timer should fire periodically
+every N seconds to send a typing HTTP request. The value of N is recommended to
+be no more than 20-30 seconds. This request should be re-sent by the client to
+continue informing the server the user is still typing. As subsequent
+requests will replace older requests, a safety margin of 5 seconds before the
+expected timeout runs out is recommended. When the user stops typing, the
+state change of the ``boolean`` to ``false`` should trigger another HTTP request
+to inform the server that the user has stopped typing.
 
-All room members will receive an event on the event stream::
+{{typing_http_api}}
 
-  {
-    "type": "m.typing",
-    "room_id": "!room-id-here:matrix.org",
-    "content": {
-      "user_ids": ["list of", "every user", "who is", "currently typing"]
-    }
-  }
-
-The client must use this list to *REPLACE* its knowledge of every user who is
-currently typing. The reason for this is that the server DOES NOT remember
-users who are not currently typing, as that list gets big quickly. The client
-should mark as not typing, any user ID who is not in that list.
-
-Server APIs
-~~~~~~~~~~~
+Server behaviour
+----------------
 
-Servers will emit EDUs in the following form::
+Servers MUST emit typing EDUs in a different form to ``m.typing`` events which
+are shown to clients. This form looks like::
 
   {
     "type": "m.typing",
@@ -54,10 +51,16 @@ Servers will emit EDUs in the following form::
     }
   }
 
-Server EDUs don't (currently) contain timing information; it is up to
-originating HSes to ensure they eventually send "stop" notifications.
+This does not contain timing information so it is up to originating homeservers
+to ensure they eventually send "stop" notifications.
 
 .. TODO
   ((This will eventually need addressing, as part of the wider typing/presence
   timer addition work))
 
+Security considerations
+-----------------------
+
+Clients may not wish to inform everyone in a room that they are typing and
+instead only specific users in the room.
+