diff --git a/.gitignore b/.gitignore index 1742b2a4..84ac4951 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ /scripts/continuserv/continuserv /scripts/speculator/speculator /scripts/swagger +/scripts/tmp /templating/out *.pyc *.swp diff --git a/.travis.yml b/.travis.yml index 03ef6513..7d84f237 100644 --- a/.travis.yml +++ b/.travis.yml @@ -4,5 +4,13 @@ go: sudo: false +# we only need a single git commit +git: + depth: 1 + +# test-and-build does the installation, so tell travis to skip the +# installation step +install: true + script: - ./scripts/test-and-build.sh diff --git a/README.rst b/README.rst index 5c9edac7..76f4ad55 100644 --- a/README.rst +++ b/README.rst @@ -41,7 +41,7 @@ specs and event schemas in this repository. Preparation ----------- -To use the scripts, it is best to create a Python virtualenv as follows:: +To use the scripts, it is best to create a Python 2.x virtualenv as follows:: virtualenv env env/bin/pip install -r scripts/requirements.txt @@ -64,6 +64,23 @@ To rebuild the specification, use ``scripts/gendoc.py``:: The above will write the rendered version of the specification to ``scripts/gen``. To view it, point your browser at ``scripts/gen/index.html``. +Windows users +~~~~~~~~~~~~~ + +If you're on Windows Vista or higher, be sure that the "Symbolic Links" +option was selected when installing Git prior to cloning this repository. If +you're still seeing errors about files not being found it is likely because +the symlink at ``api/client-server/definitions/event-schemas`` looks like a +file. To correct the problem, open an Administrative/Elevated shell in your +cloned matrix-doc directory and run the following:: + + cd api\client-server\definitions + del event-schemas + mklink /D event-schemas "..\..\..\event-schemas" + +This will delete the file and replace it with a symlink. Git should not detect +this as a change, and you should be able to go back to building the project. + Generating the OpenAPI (Swagger) specs -------------------------------------- @@ -121,74 +138,4 @@ Issue tracking Issues with the Matrix specification are tracked in `GitHub `_. -The following labels are used to help categorize issues: - -`spec-omission `_ --------------------------------------------------------------------------------- - -Things which have been implemented but not currently specified. These may range -from entire API endpoints, to particular options or return parameters. - -Issues with this label will have been implemented in `Synapse -`_. Normally there will be a design -document in Google Docs or similar which describes the feature. - -Examples: - -* `Spec PUT /directory/list `_ -* `Unspec'd server_name request param for /join/{roomIdOrAlias} - `_ - -`clarification `_ --------------------------------------------------------------------------------- - -An area where the spec could do with being more explicit. - -Examples: - -* `Spec the implicit limit on /syncs - `_ - -* `Clarify the meaning of the currently_active flags in presence events - `_ - -`spec-bug `_ ----------------------------------------------------------------------- - -Something which is in the spec, but is wrong. - -Note: this is *not* for things that are badly designed or don't work well -(for which see 'improvement' or 'feature') - it is for places where the -spec doesn't match reality. - -Examples: - -* `swagger is wrong for directory PUT - `_ - -* `receipts section still refers to initialSync - `_ - -`improvement `_ ----------------------------------------------------------------------------- - -A suggestion for a relatively simple improvement to the protocol. - -Examples: - -* `We need a 'remove 3PID' API so that users can remove mappings - `_ -* `We should mandate that /publicRooms requires an access_token - `_ - -`feature `_ --------------------------------------------------------------------- - -A suggestion for a significant extension to the matrix protocol which -needs considerable consideration before implementation. - -Examples: - -* `Peer-to-peer Matrix `_ -* `Specify a means for clients to "edit" previous messages - `_ +See `meta/labels.rst `_ for notes on what the labels mean. diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index a17ba21d..03a25fd9 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -252,7 +252,7 @@ paths: "og:image": type: string description: |- - An MXC URI to the image. Ommitted if there is no image. + An MXC URI to the image. Omitted if there is no image. examples: application/json: { "og:title": "Matrix Blog Post", diff --git a/api/client-server/definitions/timeline_batch.yaml b/api/client-server/definitions/timeline_batch.yaml index 44baa39f..ce613ac4 100644 --- a/api/client-server/definitions/timeline_batch.yaml +++ b/api/client-server/definitions/timeline_batch.yaml @@ -19,7 +19,7 @@ properties: on the filter type: boolean prev_batch: - description: A token that can be supplied to to the ``from`` parameter of the + description: A token that can be supplied to the ``from`` parameter of the rooms/{roomId}/messages endpoint type: string type: object diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 6d25a1ac..334d528c 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Client-Server Room Creation API" + title: "Matrix Client-Server Room Directory API" version: "1.0.0" host: localhost:8008 schemes: @@ -25,6 +25,88 @@ consumes: produces: - application/json paths: + "/directory/list/room/{roomId}": + get: + summary: Gets the visibility of a room in the directory + description: |- + Gets the visibility of a given room on the server's public room directory. + operationId: getRoomVisibilityOnDirectory + parameters: + - in: path + type: string + name: roomId + description: The room ID. + required: true + x-example: "!curbf:matrix.org" + responses: + 200: + description: The visibility of the room in the directory + schema: + type: object + properties: + visibility: + type: string + enum: ['private', 'public'] + description: The visibility of the room in the directory. + examples: + application/json: { + "visibility": "public" + } + 404: + description: The room is not known to the server + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Room not found" + } + put: + summary: Sets the visibility of a room in the room directory + description: |- + Sets the visibility of a given room in the server's public room + directory. + + Servers may choose to implement additional access control checks + here, for instance that room visibility can only be changed by + the room creator or a server administrator. + operationId: setRoomVisibilityOnDirectory + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room ID. + required: true + x-example: "!curbf:matrix.org" + - in: body + name: body + required: true + description: |- + The new visibility for the room on the room directory. + schema: + type: object + properties: + visibility: + type: string + enum: ["private", "public"] + description: |- + The new visibility setting for the room. + Defaults to 'public'. + example: { + "visibility": "public" + } + responses: + 200: + description: The visibility was updated, or no change was needed. + examples: + application/json: {} + 404: + description: The room is not known to the server + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Room not found" + } "/publicRooms": get: summary: Lists the public rooms on the server. diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml index 03a1622c..a6e21a38 100644 --- a/api/client-server/login.yaml +++ b/api/client-server/login.yaml @@ -75,7 +75,7 @@ paths: token: type: string description: |- - Required when ``type`` is ``m.login.token``. The login token. + Required when ``type`` is ``m.login.token``. Part of `Token-based`_ login. device_id: type: string description: |- diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index fd8f6832..1c544afe 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -366,3 +366,63 @@ paths: "$ref": "definitions/error.yaml" tags: - User data + "/register/available": + get: + summary: Checks to see if a username is available on the server. + description: |- + Checks to see if a username is available, and valid, for the server. + + The server should check to ensure that, at the time of the request, the + username requested is available for use. This includes verifying that an + application service has not claimed the username and that the username + fits the server's desired requirements (for example, a server could dictate + that it does not permit usernames with underscores). + + Matrix clients may wish to use this API prior to attempting registration, + however the clients must also be aware that using this API does not normally + reserve the username. This can mean that the username becomes unavailable + between checking its availability and attempting to register it. + operationId: checkUsernameAvailability + parameters: + - in: query + name: username + type: string + x-example: my_cool_localpart + required: true + default: my_cool_localpart + description: The username to check the availability of. + responses: + 200: + description: The username is available + examples: + application/json: { + "available": true + } + schema: + type: object + properties: + available: + type: boolean + description: |- + A flag to indicate that the username is available. This should always + be ``true`` when the server replies with 200 OK. + 400: + description: |- + Part of the request was invalid or the username is not available. This may + include one of the following error codes: + + * ``M_USER_IN_USE`` : The desired username is already taken. + * ``M_INVALID_USERNAME`` : The desired username is not a valid user name. + * ``M_EXCLUSIVE`` : The desired username is in the exclusive namespace + claimed by an application service. + examples: + application/json: { + "errcode": "M_USER_IN_USE", + "error": "Desired user ID is already taken." + } + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" + tags: + - User data diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index 946d1ba7..c4f38fa1 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -99,7 +99,9 @@ paths: title: "Ordering" type: string enum: ["recent", "rank"] - description: "The order in which to search for results." + description: |- + The order in which to search for results. + By default, this is ``"rank"``. event_context: title: "Event Context" type: object @@ -112,13 +114,13 @@ paths: title: "Before limit" description: |- How many events before the result are - returned. + returned. By default, this is ``5``. after_limit: type: integer title: "After limit" description: |- How many events after the result are - returned. + returned. By default, this is ``5``. include_profile: type: boolean title: "Return profile information" @@ -126,6 +128,7 @@ paths: Requests that the server returns the historic profile information for the users that sent the events that were returned. + By default, this is ``false``. include_state: type: boolean title: Include current state diff --git a/api/client-server/whoami.yaml b/api/client-server/whoami.yaml index e3262fe4..8f5abdf7 100644 --- a/api/client-server/whoami.yaml +++ b/api/client-server/whoami.yaml @@ -29,7 +29,14 @@ paths: get: summary: Gets information about the owner of an access token. description: |- - Gets information about the owner of a given access token. + Gets information about the owner of a given access token. + + Note that, as with the rest of the Client-Server API, + Application Services may masquerade as users within their + namespace by giving a ``user_id`` query parameter. In this + situation, the server should verify that the given ``user_id`` + is registered by the appservice, and return it in the response + body. operationId: getTokenOwner security: - accessToken: [] @@ -40,8 +47,8 @@ paths: The token belongs to a known user. examples: application/json: { - "user_id": "@joe:example.org" - } + "user_id": "@joe:example.org" + } schema: type: object required: ["user_id"] @@ -49,5 +56,29 @@ paths: user_id: type: string description: The user id that owns the access token. + 401: + description: + The token is not recognised + examples: + application/json: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Unrecognised access token." + } + schema: + "$ref": "definitions/error.yaml" + 403: + description: + The appservice cannot masquerade as the user or has not registered them. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Application service has not registered this user." + } + schema: + "$ref": "definitions/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" tags: - User data diff --git a/api/identity/ping.yaml b/api/identity/ping.yaml new file mode 100644 index 00000000..005160a3 --- /dev/null +++ b/api/identity/ping.yaml @@ -0,0 +1,44 @@ +# Copyright 2018 Kamax Sàrl +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: "2.0" +info: + title: "Matrix Client-Identity Versions API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity +produces: + - application/json +paths: + "/api/v1": + get: + summary: Checks that an Identity server is available at this API endpopint. + description: |- + Checks that an Identity server is available at this API endpopint. + + To discover that an Identity server is available at a specific URL, + this endpoint can be queried and will return an empty object. + + This is primarly used for auto-discovery and health check purposes + by entities acting as a client for the Identity server. + operationId: ping + responses: + 200: + description: An Identity server is ready to serve requests. + examples: + application/json: {} + schema: + type: object diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index b0057681..c29f38c7 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -10,18 +10,40 @@ Unreleased changes - ``GET /rooms/{roomId}/event/{eventId}`` (`#1110 `_). + - Sticker messages: + - Add sticker message event definition. + (`#1158 `_). + - Spec clarifications: + - Update ``ImageInfo`` and ``ThumbnailInfo`` dimension schema descriptions + to clarify that they relate to intended display size, as opposed to the + intrinsic size of the image file. + (`#1158 `_). - Mark ``home_server`` return field for ``/login`` and ``/register`` endpoints as deprecated (`#1097 `_). - Fix response format of ``/keys/changes`` endpoint - (`#1106 `_) + (`#1106 `_). + - Clarify default values for some fields on the /search API + (`#1109 `_). + - Fix the representation of ``m.presence`` events + (`#1137 `_). + - Clarify that ``m.tag`` ordering is done with numbers, not strings + (`#1139 `_). + - Clarify that ``/account/whoami`` should consider application services + (`#1152 `_). - Changes to the API which will be backwards-compatible for clients: - Add 'token' parameter to /keys/query endpoint (`#1104 `_). + - Add the room visibility options for the room directory + (`#1141 `_). + - Add spec for ignoring users + (`#1142 `_). + - Add the ``/register/available`` endpoint for username availability + (`#1151 `_). r0.3.0 ====== diff --git a/event-schemas/examples/m.ignored_user_list b/event-schemas/examples/m.ignored_user_list new file mode 100644 index 00000000..f3a328f7 --- /dev/null +++ b/event-schemas/examples/m.ignored_user_list @@ -0,0 +1,8 @@ +{ + "type": "m.ignored_user_list", + "content": { + "ignored_users": { + "@someone:domain.com": {} + } + } +} diff --git a/event-schemas/examples/m.presence b/event-schemas/examples/m.presence index ead92ccd..824ffcb7 100644 --- a/event-schemas/examples/m.presence +++ b/event-schemas/examples/m.presence @@ -3,9 +3,8 @@ "avatar_url": "mxc://localhost:wefuiwegh8742w", "last_active_ago": 2478593, "presence": "online", - "currently_active": false, - "user_id": "@example:localhost" + "currently_active": false }, - "event_id": "$WLGTSEFSEF:localhost", + "sender": "@example:localhost", "type": "m.presence" } diff --git a/event-schemas/examples/m.sticker b/event-schemas/examples/m.sticker new file mode 100644 index 00000000..f00e5b23 --- /dev/null +++ b/event-schemas/examples/m.sticker @@ -0,0 +1,25 @@ +{ + "age": 242352, + "content": { + "body": "Landing", + "info": { + "mimetype": "image/png", + "thumbnail_info": { + "mimetype": "image/png", + "h": 200, + "w": 140, + "size": 73602 + }, + "h": 200, + "thumbnail_url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP", + "w": 140, + "size": 73602 + }, + "url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP" + }, + "origin_server_ts": 1431961217939, + "event_id": "$WLGTSEFSEF:localhost", + "type": "m.sticker", + "room_id": "!Cuyf34gef24t:localhost", + "sender": "@example:localhost" +} diff --git a/event-schemas/examples/m.tag b/event-schemas/examples/m.tag index 00e81060..53dbc921 100644 --- a/event-schemas/examples/m.tag +++ b/event-schemas/examples/m.tag @@ -2,7 +2,7 @@ "type": "m.tag", "content": { "tags": { - "work": {"order": 1} + "u.work": {"order": 1} } } } diff --git a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml index b4eab413..4d2a9964 100644 --- a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml +++ b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml @@ -2,10 +2,14 @@ $schema: http://json-schema.org/draft-04/schema# description: Metadata about an image. properties: h: - description: The height of the image in pixels. + description: |- + The intended display height of the image in pixels. This may + differ from the intrinsic dimensions of the image file. type: integer w: - description: The width of the image in pixels. + description: |- + The intended display width of the image in pixels. This may + differ from the intrinsic dimensions of the image file. type: integer mimetype: description: The mimetype of the image, e.g. ``image/jpeg``. diff --git a/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml b/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml index 5a233b24..82ffaf5e 100644 --- a/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml +++ b/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml @@ -2,10 +2,14 @@ $schema: http://json-schema.org/draft-04/schema# description: Metadata about a thumbnail image. properties: h: - description: The height of the image in pixels. + description: |- + The intended display height of the image in pixels. This may + differ from the intrinsic dimensions of the image file. type: integer w: - description: The width of the image in pixels. + description: |- + The intended display width of the image in pixels. This may + differ from the intrinsic dimensions of the image file. type: integer mimetype: description: The mimetype of the image, e.g. ``image/jpeg``. diff --git a/event-schemas/schema/m.ignored_user_list b/event-schemas/schema/m.ignored_user_list new file mode 100644 index 00000000..7f7a6604 --- /dev/null +++ b/event-schemas/schema/m.ignored_user_list @@ -0,0 +1,28 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml +description: |- + A map of users which are considered ignored is kept in ``account_data`` + in an event type of ``m.ignored_user_list``. +properties: + content: + type: object + properties: + ignored_users: + type: object + title: "Ignored users" + description: "The map of users to ignore" + patternProperties: + "^@": + type: "object" + title: "Ignored User" + description: "An empty object for future enhancement" + x-pattern: "$USER_ID" + required: + - ignored_users + type: + enum: + - m.ignored_user_list + type: string +title: Ignored User List +type: object diff --git a/event-schemas/schema/m.presence b/event-schemas/schema/m.presence index 36108db6..3c884fd6 100644 --- a/event-schemas/schema/m.presence +++ b/event-schemas/schema/m.presence @@ -29,21 +29,17 @@ "currently_active": { "type": boolean, "description": "Whether the user is currently active" - }, - "user_id": { - "type": "string", - "description": "The user's ID." } }, - "required": ["presence", "user_id"] + "required": ["presence"] }, "type": { "type": "string", "enum": ["m.presence"] }, - "event_id": { + "sender": { "type": "string" } }, - "required": ["event_id", "type", "content"] + "required": ["sender", "type", "content"] } diff --git a/event-schemas/schema/m.sticker b/event-schemas/schema/m.sticker new file mode 100644 index 00000000..1dd1173c --- /dev/null +++ b/event-schemas/schema/m.sticker @@ -0,0 +1,34 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: This message represents a single sticker image. +properties: + content: + properties: + body: + description: |- + A textual representation or associated description of the sticker + image. This could be the alt text of the original image, or a message + to accompany and further describe the sticker. + type: string + info: + allOf: + - $ref: core-event-schema/msgtype_infos/image_info.yaml + description: |- + Metadata about the image referred to in ``url`` including a thumbnail + representation. + url: + description: |- + The URL to the sticker image. This must be a valid ``mxc://`` URI. + type: string + required: + - body + - info + - url + type: object + type: + enum: + - m.sticker + type: string +title: StickerMessage +type: object diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index a6cfad51..698eb027 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -1,8 +1,9 @@ Documentation Style =================== -A brief single sentence to describe what this file contains; in this case a -description of the style to write documentation in. +Each document should begin with a brief single sentence to describe what this +file contains: in this case a description of the style to write documentation +in. Format ------ @@ -24,7 +25,7 @@ complete specification to be merged correctly. These characters are: - ``~`` - ``+`` - ``^`` -- ````` +- \ ````` - ``@`` - ``:`` @@ -49,3 +50,49 @@ Line widths We use 80 characters for line widths. This is a guideline and can be flouted IF AND ONLY IF it makes reading more legible. Use common sense. + +Stylistic notes +--------------- + +General +~~~~~~~ + +Try to write clearly and unambiguously. Remember that many readers will not +have English as their first language. + +Prefer British English (colour, -ise) to American English. + +The word "homeserver" is spelt thus (rather than "home server", "Homeserver", +or (argh) "Home Server"). + +Lists should: + +* Be introduced with a colon. +* Be used where they provide clarity. +* Contain entries which start with a capital and end with a full stop. + +OpenAPI +~~~~~~~ + +When writing OpenAPI specifications for the API endpoints, follow these rules: + +* ``summary``: a phrase summarising what this API does. Start with a capital, + end with a full stop. Examples: "Sends an event."; "Searches the directory." + +* ``description``: a longer description of the behaviour of this API, written + in complete sentences. Use multiple paragraphs if necessary. + + Example: + + This API sends an event to the room. The server must ensure that the user + has permission to post events to this room. + +* ``operationId``: a camelCased unique identifier for this endpoint. This will + be used to automatically generate bindings for the endpoint. + +* Parameter and property ``description``\s: a phrase summarising the behaviour + of this parameter or property, optionally followed by sentences giving more + detailed explanations. Start with a capital, end with a full stop. + + The description is also the place to define default values for optional + properties. Use the wording "Defaults to X [if unspecified]." diff --git a/scripts/continuserv/README b/scripts/continuserv/README index 8ce37850..edb9aef4 100644 --- a/scripts/continuserv/README +++ b/scripts/continuserv/README @@ -1,6 +1,6 @@ continuserv proactively re-generates the spec on filesystem changes, and serves it over HTTP. To run it, you must install the `go` tool. You will also need to install fsnotify by running: - `go get gopkg.in/fsnotify.v1` + `go get gopkg.in/fsnotify/fsnotify.v1` You can then run continuserv by running: `go run main.go` diff --git a/scripts/continuserv/main.go b/scripts/continuserv/main.go index a6117714..330ddca7 100644 --- a/scripts/continuserv/main.go +++ b/scripts/continuserv/main.go @@ -19,7 +19,7 @@ import ( "sync/atomic" "time" - fsnotify "gopkg.in/fsnotify.v1" + fsnotify "gopkg.in/fsnotify/fsnotify.v1" ) var ( diff --git a/scripts/generate-matrix-org-assets b/scripts/generate-matrix-org-assets index 2f8acc5d..cb3cf455 100755 --- a/scripts/generate-matrix-org-assets +++ b/scripts/generate-matrix-org-assets @@ -2,6 +2,8 @@ # # generate a tarball of assets suitable for the matrix.org site +set -e + cd `dirname $0`/.. mkdir -p assets diff --git a/scripts/speculator/main.go b/scripts/speculator/main.go index e6e310ce..0380a3cd 100644 --- a/scripts/speculator/main.go +++ b/scripts/speculator/main.go @@ -712,6 +712,7 @@ func main() { "richvdh": true, "ara4n": true, "leonerd": true, + "rxl881": true, } if err := initCache(); err != nil { log.Fatal(err) diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 1540a7fd..d8cfe1e3 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -694,15 +694,25 @@ class MatrixUnits(Units): for filename in os.listdir(path): if not filename.startswith("m."): continue - with open(os.path.join(path, filename), "r") as f: - event_name = filename.split("#")[0] - example = json.loads(f.read()) - - examples[filename] = examples.get(filename, []) - examples[filename].append(example) - if filename != event_name: - examples[event_name] = examples.get(event_name, []) - examples[event_name].append(example) + + event_name = filename.split("#")[0] + filepath = os.path.join(path, filename) + logger.info("Reading event example: %s" % filepath) + try: + with open(filepath, "r") as f: + example = json.load(f) + examples[filename] = examples.get(filename, []) + examples[filename].append(example) + if filename != event_name: + examples[event_name] = examples.get(event_name, []) + examples[event_name].append(example) + except Exception, e: + e2 = Exception("Error reading event example "+filepath+": "+ + str(e)) + # throw the new exception with the old stack trace, so that + # we don't lose information about where the error occurred. + raise e2, None, sys.exc_info()[2] + return examples def load_event_schemas(self): diff --git a/scripts/test-and-build.sh b/scripts/test-and-build.sh index cd25ded2..7794f826 100755 --- a/scripts/test-and-build.sh +++ b/scripts/test-and-build.sh @@ -17,7 +17,7 @@ pip install -r scripts/requirements.txt mkdir -p "${GOPATH}" export GOPATH go get github.com/hashicorp/golang-lru -go get gopkg.in/fsnotify.v1 +go get gopkg.in/fsnotify/fsnotify.v1 # make sure that the scripts build (cd scripts/continuserv && go build) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 1041dc15..dec3a4f4 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -510,8 +510,9 @@ To use this authentication type, clients should submit an auth dict as follows: The ``nonce`` should be a random string generated by the client for the request. The same ``nonce`` should be used if retrying the request. -There are many ways a client may receive a ``token``, including via an email or -from an existing logged in device. +A client may receive a login ``token`` via some external service, such as email +or SMS. Note that a login token is separate from an access token, the latter +providing general authentication to various API endpoints. The ``txn_id`` may be used by the server to disallow other devices from using the token, thus providing "single use" tokens while still allowing the device diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 19275593..89fcc3e6 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -67,6 +67,11 @@ should allow a 3pid to be mapped to a Matrix user identity, but not in the other direction (i.e. one should not be able to get all 3pids associated with a Matrix user ID, or get all 3pids associated with a 3pid). +Status check +------------ + +{{ping_is_http_api}} + Key management -------------- diff --git a/specification/intro.rst b/specification/intro.rst index 1c795cea..064f9d17 100644 --- a/specification/intro.rst +++ b/specification/intro.rst @@ -116,7 +116,7 @@ model communication history as a partially ordered graph of events known as the room's "event graph", which is synchronised with eventual consistency between the participating servers using the "Server-Server API". This process of synchronising shared conversation history between homeservers run by -different parties is called "Federation". Matrix optimises for the the +different parties is called "Federation". Matrix optimises for the Availability and Partitioned properties of CAP theorem at the expense of Consistency. diff --git a/specification/modules/ignore_users.rst b/specification/modules/ignore_users.rst new file mode 100644 index 00000000..56a410d1 --- /dev/null +++ b/specification/modules/ignore_users.rst @@ -0,0 +1,62 @@ +.. Copyright 2018 Travis Ralston +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +Ignoring Users +============== + +.. _module:ignore_users: + +With all the communication through Matrix it may be desirable to ignore a +particular user for whatever reason. This module defines how clients and +servers can implement the ignoring of users. + +Events +------ + +{{m_ignored_user_list_event}} + +Client behaviour +---------------- +To ignore a user, effectively blocking them, the client should add the target +user to the ``m.ignored_user_list`` event in their account data using +|/user//account_data/|_. Once ignored, the client will no longer +receive events sent by that user, with the exception of state events. The client +should either hide previous content sent by the newly ignored user or perform +a new ``/sync`` with no previous token. + +Invites to new rooms by ignored users will not be sent to the client. The server +may optionally reject the invite on behalf of the client. + +State events will still be sent to the client, even if the user is ignored. +This is to ensure parts, such as the room name, do not appear different to the +user just because they ignored the sender. + +To remove a user from the ignored users list, remove them from the account data +event. The server will resume sending events from the previously ignored user, +however it should not send events that were missed while the user was ignored. +To receive the events that were sent while the user was ignored the client +should perform a fresh sync. The client may also un-hide any events it previously +hid due to the user becoming ignored. + +Server behaviour +---------------- +Following an update of the ``m.ignored_user_list``, the sync API for all clients +should immediately start ignoring (or un-ignoring) the user. Clients are responsible +for determining if they should hide previously sent events or to start a new sync +stream. + +Servers must still send state events sent by ignored users to clients. + +Servers must not send room invites from ignored users to clients. Servers may +optionally decide to reject the invite, however. diff --git a/specification/modules/stickers.rst b/specification/modules/stickers.rst new file mode 100644 index 00000000..346b0d84 --- /dev/null +++ b/specification/modules/stickers.rst @@ -0,0 +1,53 @@ +.. Copyright 2018 New Vector Ltd. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +Sticker Messages +================ + +.. _module:stickers: + +This module allows users to send sticker messages in to rooms or direct +messaging sessions. + +Sticker messages are specialised image messages that are displayed without +controls (e.g. no "download" link, or light-box view on click, as would be +displayed for for `m.image`_ events). + +Sticker messages are intended to provide simple "reaction" events in the message +timeline. The matrix client should provide some mechanism to display the sticker +"body" e.g. as a tooltip on hover, or in a modal when the sticker image is +clicked. + +Events +------ +Sticker events are received as a single ``m.sticker`` event in the +``timeline`` section of a room, in a ``/sync``. + +{{m_sticker_event}} + +Client behaviour +---------------- + +Clients supporting this message type should display the image content from the +event URL directly in the timeline. + +A thumbnail image should be provided in the ``info`` object. This is +largely intended as a fallback for clients that do not fully support the +``m.sticker`` event type. In most cases it is fine to set the thumbnail URL to the +same URL as the main event content. + +It is recommended that sticker image content should be 512x512 pixels in size +or smaller. The dimensions of the image file should be twice the intended +display size specified in the ``info`` object in order to assist +rendering sharp images on higher DPI screens. diff --git a/specification/modules/tags.rst b/specification/modules/tags.rst index 31b3b711..25e48ab3 100644 --- a/specification/modules/tags.rst +++ b/specification/modules/tags.rst @@ -35,12 +35,11 @@ the tags are for. Each tag has an associated JSON object with information about the tag, e.g how to order the rooms with a given tag. -Ordering information is given under the ``order`` key as a string. The string -are compared lexicographically by unicode codepoint to determine which should -displayed first. So a room with a tag with an ``order`` key of ``"apples"`` -would appear before a room with a tag with an ``order`` key of ``"oranges"``. -If a room has a tag without an ``order`` key then it should appear after the -rooms with that tag that have an ``order`` key. +Ordering information is given under the ``order`` key as a number between 0 and +1. The numbers are compared such that 0 is displayed first. Therefore a room +with an ``order`` of ``0.2`` would be displayed before a room with an ``order`` +of ``0.7``. If a room has a tag without an ``order`` key then it should appear +after the rooms with that tag that have an ``order`` key. The name of a tag MUST not exceed 255 bytes. diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 43874321..e9885311 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -520,7 +520,7 @@ the state of the room. #. If ``membership`` is ``invite``: - i. If the ``sender``'s current membership state is not ``joined``, reject. + i. If the ``sender``'s current membership state is not ``join``, reject. #. If *target user*'s current membership state is ``join`` or ``ban``, reject. @@ -535,7 +535,7 @@ the state of the room. i. If the ``sender`` matches ``state_key``, allow if and only if that user's current membership state is ``invite`` or ``join``. - #. If the ``sender``'s current membership state is not ``joined``, reject. + #. If the ``sender``'s current membership state is not ``join``, reject. #. If the *target user*'s current membership state is ``ban``, and the ``sender``'s power level is less than the *ban level*, reject. @@ -548,7 +548,7 @@ the state of the room. #. If ``membership`` is ``ban``: - i. If the ``sender``'s current membership state is not ``joined``, reject. + i. If the ``sender``'s current membership state is not ``join``, reject. #. If the ``sender``'s power level is greater than or equal to the *ban level*, and the *target user*'s power level is less than the @@ -558,7 +558,7 @@ the state of the room. #. Otherwise, the membership is unknown. Reject. -#. If the ``sender``'s current membership state is not ``joined``, reject. +#. If the ``sender``'s current membership state is not ``join``, reject. #. If the event type's *required power level* is greater than the ``sender``'s power level, reject. diff --git a/specification/targets.yaml b/specification/targets.yaml index 62799afe..50a9fb8d 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -61,6 +61,8 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/event_context.rst - modules/cas_login.rst - modules/dm.rst + - modules/ignore_users.rst + - modules/stickers.rst title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]