Merge branch 'master' into rav/send_events_api

api/client-server/v1/search.yaml

@@ -0,0 +1,140 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Search 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:
+  "/search":
+    post:
+      summary: Search server side for things.
+      description: |-
+        Performs a full text search across different categories.
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                "search_categories": {
+                  "room_events": {
+                    "keys": [
+                      "content.body"
+                    ],
+                    "search_term": "martians and men"
+                  }
+                }
+              }
+            properties:
+              search_categories:
+                type: object
+                title: "Categories"
+                description: Describes which categories to search in and
+                  their criteria.
+                properties:
+                  room_events:
+                    type: object
+                    title: "Room Events"
+                    description: Mapping of category name to search criteria.
+                    properties:
+                      search_term:
+                        type: string
+                        description: The string to search events for
+                      keys:
+                        type: array
+                        items:
+                          type: string
+                          enum: ["content.body", "content.name", "content.topic"]
+                        description: The keys to search. Defaults to all.
+                    required: ["search_term"]
+            required: ["search_categories"]
+      responses:
+        200:
+          description: Results of the search.
+          schema:
+            type: object
+            title: Results
+            required: ["search_categories"]
+            properties:
+              search_categories:
+                type: object
+                title: Categories
+                description: Describes which categories to search in and
+                  their criteria.
+                properties:
+                  room_events:
+                    type: object
+                    title: Room Event Results
+                    description: Mapping of category name to search criteria.
+                    properties:
+                      count:
+                        type: number
+                        description: Total number of results found
+                      results:
+                        type: object
+                        title: Results
+                        description: Mapping of event_id to result.
+                        additionalProperties:
+                          type: object
+                          title: Result
+                          description: The result object.
+                          properties:
+                            rank:
+                              type: number
+                              description: A number that describes how closely
+                                this result matches the search. Higher is
+                                closer.
+                            result:
+                                type: object
+                                title: Event
+                                description: The event that matched.
+                                allOf:
+                                  - "$ref": "core-event-schema/room_event.json"
+          examples:
+            application/json: |-
+               {
+                  "search_categories": {
+                    "room_events": {
+                      "count": 24,
+                      "results": {
+                        "$144429830826TWwbB:localhost": {
+                          "rank": 0.00424866,
+                          "result": {
+                            "age": 526228296,
+                            "content": {
+                              "body": "Test content",
+                              "msgtype": "m.text"
+                            },
+                            "event_id": "$144429830826TWwbB:localhost",
+                            "origin_server_ts": 1444298308034,
+                            "room_id": "!qPewotXpIctQySfjSy:localhost",
+                            "type": "m.room.message",
+                            "user_id": "@test:localhost"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+        400:
+          description: Part of the request was invalid.
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"

scripts/css/blockquote.css

@@ -0,0 +1,5 @@
+blockquote {
+    margin: 20px 0 30px;
+    border-left: 5px solid;
+    padding-left: 20px;
+}

scripts/gendoc.py

@@ -15,7 +15,7 @@ import yaml
 os.chdir(os.path.dirname(os.path.abspath(__file__)))
 
 stylesheets = {
-    "stylesheet_path": ["basic.css", "nature.css", "codehighlight.css"]
+    "stylesheet_path": glob.glob("css/*.css"),
 }
 
 VERBOSE = False

scripts/speculator/main.go

@@ -365,6 +365,7 @@ func main() {
 		"Kegsay":        true,
 		"NegativeMjark": true,
 		"richvdh":       true,
+		"leonerd":       true,
 	}
 	rand.Seed(time.Now().Unix())
 	masterCloneDir, err := gitClone(matrixDocCloneURL, false)

specification/feature_profiles.rst

@@ -26,6 +26,7 @@ Summary
  `Content Repository`_                 Required   Required   Required   Optional   Optional
  `Managing History Visibility`_        Required   Required   Required   Required   Optional
  `End-to-End Encryption`_              Optional   Optional   Optional   Optional   Optional
+ `Server Side Search`_                 Optional   Optional   Optional   Optional   Optional
 ===================================== ========== ========== ========== ========== ==========
 
 *Please see each module for more details on what clients need to implement.*
@@ -39,6 +40,7 @@ Summary
 .. _VoIP: `module:voip`_
 .. _Content Repository: `module:content`_
 .. _Managing History Visibility: `module:history-visibility`_
+.. _Server Side Search: `module:search`_
 
 Clients
 -------

specification/modules/search.rst

@@ -0,0 +1,46 @@
+Server Side Search
+==================
+
+.. _module:search:
+
+The search API allows clients to perform full text search across events in all
+rooms that the user has been in, including those that they have left. Only
+events that the user is allowed to see will be searched, e.g. it won't include
+events in rooms that happened after you left.
+
+Client behaviour
+----------------
+{{search_http_api}}
+
+Search Categories
+-----------------
+
+The search API allows clients to search in different categories of items.
+Currently the only specified category is ``room_events``.
+
+``room_events``
+~~~~~~~~~~~~~~~
+
+This category covers all events that the user is allowed to see, including
+events in rooms that they have left. The search is performed on certain keys of
+certain event types.
+
+The supported keys to search over are:
+
+- ``content.body`` in ``m.room.message``
+- ``content.name`` in ``m.room.name``
+- ``content.topic`` in ``m.room.topic``
+
+The search will *not* include rooms that are end to end encrypted.
+
+The results include a ``rank`` key that can be used to sort the results by
+revelancy. The higher the ``rank`` the more relevant the result is.
+
+The value of ``count`` may not match the number of results. For example due to
+the search query matching 1000s of results and the server truncating the
+response.
+
+Security considerations
+-----------------------
+The server must only return results that the user has permission to see.
+

specification/targets.yaml

@@ -24,6 +24,8 @@ groups:  # reusable blobs of files when prefixed with 'group:'
     - modules/history_visibility.rst
     - modules/push.rst
     - modules/third_party_invites.rst
+    - modules/search.rst
+
 
 title_styles: ["=", "-", "~", "+", "^", "`"]