Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-01-31 11:33:43 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge branches 'master' and 'notifications/room' of github.com:matrix-org/matrix-doc into notifications/room

Browse source
This commit is contained in:
Michael Telatynski 2018-05-12 09:24:53 +01:00
parent c305317fa5 5274e9c146
commit 992bc8828a
No known key found for this signature in database
GPG key ID: 3F879DA5AD802A5E
36 changed files with 603 additions and 125 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -6,6 +6,7 @@
/scripts/continuserv/continuserv
/scripts/speculator/speculator
/scripts/swagger
/scripts/tmp
/templating/out
*.pyc
*.swp

8
.travis.yml
View file

@ -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

91
README.rst
View file

@ -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
<https://github.com/matrix-org/matrix-doc/issues>`_.
The following labels are used to help categorize issues:
`spec-omission <https://github.com/matrix-org/matrix-doc/labels/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
<https://github.com/matrix-org/synapse>`_. Normally there will be a design
document in Google Docs or similar which describes the feature.
Examples:
* `Spec PUT /directory/list <https://github.com/matrix-org/matrix-doc/issues/417>`_
* `Unspec'd server_name request param for /join/{roomIdOrAlias}
<https://github.com/matrix-org/matrix-doc/issues/904>`_
`clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
--------------------------------------------------------------------------------
An area where the spec could do with being more explicit.
Examples:
* `Spec the implicit limit on /syncs
<https://github.com/matrix-org/matrix-doc/issues/708>`_
* `Clarify the meaning of the currently_active flags in presence events
<https://github.com/matrix-org/matrix-doc/issues/686>`_
`spec-bug <https://github.com/matrix-org/matrix-doc/labels/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
<https://github.com/matrix-org/matrix-doc/issues/933>`_
* `receipts section still refers to initialSync
<https://github.com/matrix-org/matrix-doc/issues/695>`_
`improvement <https://github.com/matrix-org/matrix-doc/labels/improvement>`_
----------------------------------------------------------------------------
A suggestion for a relatively simple improvement to the protocol.
Examples:
* `We need a 'remove 3PID' API so that users can remove mappings
<https://github.com/matrix-org/matrix-doc/issues/620>`_
* `We should mandate that /publicRooms requires an access_token
<https://github.com/matrix-org/matrix-doc/issues/612>`_
`feature <https://github.com/matrix-org/matrix-doc/labels/feature>`_
--------------------------------------------------------------------
A suggestion for a significant extension to the matrix protocol which
needs considerable consideration before implementation.
Examples:
* `Peer-to-peer Matrix <https://github.com/matrix-org/matrix-doc/issues/710>`_
* `Specify a means for clients to "edit" previous messages
<https://github.com/matrix-org/matrix-doc/issues/682>`_
See `meta/labels.rst <meta/labels.rst>`_ for notes on what the labels mean.

2
api/client-server/content-repo.yaml
View file

@ -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",

2
api/client-server/definitions/timeline_batch.yaml
View file

@ -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

84
api/client-server/list_public_rooms.yaml
View file

@ -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.

2
api/client-server/login.yaml
View file

@ -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: |-

60
api/client-server/registration.yaml
View file

@ -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

9
api/client-server/search.yaml
View file

@ -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

37
api/client-server/whoami.yaml
View file

@ -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

44
api/identity/ping.yaml Normal file
View file

@ -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

24
changelogs/client_server.rst
View file

@ -10,18 +10,40 @@ Unreleased changes
- ``GET /rooms/{roomId}/event/{eventId}``
(`#1110 <https://github.com/matrix-org/matrix-doc/pull/1110>`_).
- Sticker messages:
- Add sticker message event definition.
(`#1158 <https://github.com/matrix-org/matrix-doc/pull/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 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
- Mark ``home_server`` return field for ``/login`` and ``/register``
endpoints as deprecated
(`#1097 <https://github.com/matrix-org/matrix-doc/pull/1097>`_).
- Fix response format of ``/keys/changes`` endpoint
(`#1106 <https://github.com/matrix-org/matrix-doc/pull/1106>`_)
(`#1106 <https://github.com/matrix-org/matrix-doc/pull/1106>`_).
- Clarify default values for some fields on the /search API
(`#1109 <https://github.com/matrix-org/matrix-doc/pull/1109>`_).
- Fix the representation of ``m.presence`` events
(`#1137 <https://github.com/matrix-org/matrix-doc/pull/1137>`_).
- Clarify that ``m.tag`` ordering is done with numbers, not strings
(`#1139 <https://github.com/matrix-org/matrix-doc/pull/1139>`_).
- Clarify that ``/account/whoami`` should consider application services
(`#1152 <https://github.com/matrix-org/matrix-doc/pull/1152>`_).
- Changes to the API which will be backwards-compatible for clients:
- Add 'token' parameter to /keys/query endpoint
(`#1104 <https://github.com/matrix-org/matrix-doc/pull/1104>`_).
- Add the room visibility options for the room directory
(`#1141 <https://github.com/matrix-org/matrix-doc/pull/1141>`_).
- Add spec for ignoring users
(`#1142 <https://github.com/matrix-org/matrix-doc/pull/1142>`_).
- Add the ``/register/available`` endpoint for username availability
(`#1151 <https://github.com/matrix-org/matrix-doc/pull/1151>`_).
r0.3.0
======

8
event-schemas/examples/m.ignored_user_list Normal file
View file

@ -0,0 +1,8 @@
{
"type": "m.ignored_user_list",
"content": {
"ignored_users": {
"@someone:domain.com": {}
}
}
}

5
event-schemas/examples/m.presence
View file

@ -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"
}

25
event-schemas/examples/m.sticker Normal file
View file

@ -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"
}

2
event-schemas/examples/m.tag
View file

@ -2,7 +2,7 @@
"type": "m.tag",
"content": {
"tags": {
"work": {"order": 1}
"u.work": {"order": 1}
}
}
}

8
event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml
View file

@ -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``.

8
event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml
View file

@ -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``.

28
event-schemas/schema/m.ignored_user_list Normal file
View file

@ -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

10
event-schemas/schema/m.presence
View file

@ -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"]
}

34
event-schemas/schema/m.sticker Normal file
View file

@ -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

53
meta/documentation_style.rst
View file

@ -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]."

2
scripts/continuserv/README
View file

@ -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`

2
scripts/continuserv/main.go
View file

@ -19,7 +19,7 @@ import (
"sync/atomic"
"time"
fsnotify "gopkg.in/fsnotify.v1"
fsnotify "gopkg.in/fsnotify/fsnotify.v1"
)
var (

2
scripts/generate-matrix-org-assets
View file

@ -2,6 +2,8 @@
#
# generate a tarball of assets suitable for the matrix.org site
set -e
cd `dirname $0`/..
mkdir -p assets

1
scripts/speculator/main.go
View file

@ -712,6 +712,7 @@ func main() {
"richvdh": true,
"ara4n": true,
"leonerd": true,
"rxl881": true,
}
if err := initCache(); err != nil {
log.Fatal(err)

26
scripts/templating/matrix_templates/units.py
View file

@ -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):

2
scripts/test-and-build.sh
View file

@ -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)

5
specification/client_server_api.rst
View file

@ -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

5
specification/identity_service_api.rst
View file

@ -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
--------------

2
specification/intro.rst
View file

@ -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.

62
specification/modules/ignore_users.rst Normal file
View file

@ -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/<user_id>/account_data/<type>|_. 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.

53
specification/modules/stickers.rst Normal file
View file

@ -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.

11
specification/modules/tags.rst
View file

@ -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.

8
specification/server_server_api.rst
View file

@ -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.

2
specification/targets.yaml
View file

@ -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: ["=", "-", "~", "+", "^", "`", "@", ":"]