diff --git a/api/client-server/v1/search.yaml b/api/client-server/v1/search.yaml new file mode 100644 index 00000000..885e62b3 --- /dev/null +++ b/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" diff --git a/scripts/basic.css b/scripts/css/basic.css similarity index 100% rename from scripts/basic.css rename to scripts/css/basic.css diff --git a/scripts/css/blockquote.css b/scripts/css/blockquote.css new file mode 100644 index 00000000..151d3bce --- /dev/null +++ b/scripts/css/blockquote.css @@ -0,0 +1,5 @@ +blockquote { + margin: 20px 0 30px; + border-left: 5px solid; + padding-left: 20px; +} diff --git a/scripts/codehighlight.css b/scripts/css/codehighlight.css similarity index 100% rename from scripts/codehighlight.css rename to scripts/css/codehighlight.css diff --git a/scripts/nature.css b/scripts/css/nature.css similarity index 100% rename from scripts/nature.css rename to scripts/css/nature.css diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 74a6c1da..ed36a5a7 100755 --- a/scripts/gendoc.py +++ b/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 diff --git a/scripts/speculator/main.go b/scripts/speculator/main.go index dab624df..e6992d4a 100644 --- a/scripts/speculator/main.go +++ b/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) diff --git a/specification/feature_profiles.rst b/specification/feature_profiles.rst index 6c11dd2f..f79b92c5 100644 --- a/specification/feature_profiles.rst +++ b/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 ------- diff --git a/specification/modules/search.rst b/specification/modules/search.rst new file mode 100644 index 00000000..089953d2 --- /dev/null +++ b/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. + diff --git a/specification/targets.yaml b/specification/targets.yaml index 4ac34ae3..2482dcfd 100644 --- a/specification/targets.yaml +++ b/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: ["=", "-", "~", "+", "^", "`"]