More formatting fixes; typos; etc
This commit is contained in:
Kegan Dougal
parent
af32ec194a
commit
faa95e172f
6 changed files with 50 additions and 47 deletions
|
|
@ -63,3 +63,4 @@ The call setup should appear seamless to the user as if they had simply placed
|
|||
a call and the other party had accepted. Thusly, any media stream that had been
|
||||
setup for use on a call should be transferred and used for the call that
|
||||
replaces it.
|
||||
|
||||
|
|
|
|||
|
|
@ -66,13 +66,13 @@ An example HS configuration required to pass traffic to the AS is:
|
|||
application service is merely augmenting the room itself (e.g. providing
|
||||
logging or searching facilities).
|
||||
- Namespaces are represented by POSIX extended regular expressions,
|
||||
e.g.:
|
||||
e.g:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
users:
|
||||
- exclusive: true
|
||||
regex: @irc.freenode.net/.*
|
||||
regex: @irc.freenode.net_.*
|
||||
|
||||
|
||||
Home Server -> Application Service API
|
||||
|
|
@ -326,7 +326,7 @@ but only if the application service has defined the namespace as ``exclusive``.
|
|||
|
||||
ID conventions
|
||||
~~~~~~~~~~~~~~
|
||||
.. NOTE::
|
||||
.. TODO-spec
|
||||
- Giving HSes the freedom to namespace still feels like the Right Thing here.
|
||||
- Exposing a public API provides the consistency which was the main complaint
|
||||
against namespacing.
|
||||
|
|
@ -345,7 +345,7 @@ types, including:
|
|||
- MSISDNs (``tel``)
|
||||
- Email addresses (``mailto``)
|
||||
- IRC nicks (``irc`` - https://tools.ietf.org/html/draft-butcher-irc-url-04)
|
||||
- XMPP (xep-0032)
|
||||
- XMPP (XEP-0032)
|
||||
- SIP URIs (RFC 3261)
|
||||
|
||||
As a result, virtual user IDs SHOULD relate to their URI counterpart. This
|
||||
|
|
@ -403,6 +403,8 @@ blog comment traffic in & out of matrix
|
|||
|
||||
Active Application Services
|
||||
----------------------------
|
||||
.. NOTE::
|
||||
This section is a work in progress.
|
||||
|
||||
.. TODO-spec
|
||||
API that provides hooks into the server so that you can intercept and
|
||||
|
|
@ -419,3 +421,4 @@ Policy Servers
|
|||
|
||||
Enforcing policies
|
||||
------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -2,10 +2,9 @@ Federation API
|
|||
==============
|
||||
|
||||
Matrix home servers use the Federation APIs (also known as server-server APIs)
|
||||
to communicate with each other.
|
||||
Home servers use these APIs to push messages to each other in real-time, to
|
||||
request historic messages from each other, and to query profile and presence
|
||||
information about users on each other's servers.
|
||||
to communicate with each other. Home servers use these APIs to push messages to
|
||||
each other in real-time, to request historic messages from each other, and to
|
||||
query profile and presence information about users on each other's servers.
|
||||
|
||||
The APIs are implemented using HTTPS GETs and PUTs between each of the
|
||||
servers. These HTTPS requests are strongly authenticated using public key
|
||||
|
|
@ -21,7 +20,7 @@ Persisted Data Units (PDUs):
|
|||
context.
|
||||
|
||||
Like email, it is the responsibility of the originating server of a PDU
|
||||
to deliver that event to its recepient servers. However PDUs are signed
|
||||
to deliver that event to its recipient servers. However PDUs are signed
|
||||
using the originating server's public key so that it is possible to
|
||||
deliver them through third-party servers.
|
||||
|
||||
|
|
@ -84,18 +83,19 @@ directly or by querying an intermediate notary server using a
|
|||
response with their own key. A server may query multiple notary servers to
|
||||
ensure that they all report the same public keys.
|
||||
|
||||
This approach is borrowed from the Perspectives Project
|
||||
(http://perspectives-project.org/), but modified to include the NACL keys and to
|
||||
use JSON instead of XML. It has the advantage of avoiding a single trust-root
|
||||
since each server is free to pick which notary servers they trust and can
|
||||
corroborate the keys returned by a given notary server by querying other
|
||||
servers.
|
||||
This approach is borrowed from the `Perspectives Project`_, but modified to
|
||||
include the NACL keys and to use JSON instead of XML. It has the advantage of
|
||||
avoiding a single trust-root since each server is free to pick which notary
|
||||
servers they trust and can corroborate the keys returned by a given notary
|
||||
server by querying other servers.
|
||||
|
||||
.. _Perspectives Project: http://perspectives-project.org/
|
||||
|
||||
Publishing Keys
|
||||
_______________
|
||||
|
||||
Home servers publish the allowed TLS fingerprints and signing keys in a JSON
|
||||
object at ``/_matrix/key/v2/server/${key_id}``. The response contains a list of
|
||||
object at ``/_matrix/key/v2/server/{key_id}``. The response contains a list of
|
||||
``verify_keys`` that are valid for signing federation requests made by the
|
||||
server and for signing events. It contains a list of ``old_verify_keys``
|
||||
which are only valid for signing events. Finally the response contains a list
|
||||
|
|
@ -510,7 +510,7 @@ To backfill events on a given context::
|
|||
|
||||
Retrieves a sliding-window history of previous PDUs that occurred on the given
|
||||
context. Starting from the PDU ID(s) given in the "v" argument, the PDUs that
|
||||
preceeded it are retrieved, up to a total number given by the "limit" argument.
|
||||
preceded it are retrieved, up to a total number given by the "limit" argument.
|
||||
These are then returned in a new Transaction containing all of the PDUs.
|
||||
|
||||
|
||||
|
|
@ -554,9 +554,7 @@ Every HTTP request made by a homeserver is authenticated using public key
|
|||
digital signatures. The request method, target and body are signed by wrapping
|
||||
them in a JSON object and signing it using the JSON signing algorithm. The
|
||||
resulting signatures are added as an Authorization header with an auth scheme
|
||||
of X-Matrix.
|
||||
|
||||
Note that the target field should include the full path starting with
|
||||
of X-Matrix. Note that the target field should include the full path starting with
|
||||
``/_matrix/...``, including the ``?`` and any query parameters if present, but
|
||||
should not include the leading ``https:``, nor the destination server's
|
||||
hostname.
|
||||
|
|
@ -677,8 +675,8 @@ Performing a presence update and poll subscription request::
|
|||
Each should be an object with the following keys:
|
||||
user_id: string containing a User ID
|
||||
presence: "offline"|"unavailable"|"online"|"free_for_chat"
|
||||
status_msg: (optional) string of freeform text
|
||||
last_active_ago: miliseconds since the last activity by the user
|
||||
status_msg: (optional) string of free-form text
|
||||
last_active_ago: milliseconds since the last activity by the user
|
||||
|
||||
poll: (optional): list of strings giving User IDs
|
||||
|
||||
|
|
@ -696,7 +694,7 @@ removed until explicitly requested by a later ``unpoll``.
|
|||
On receipt of a message containing a non-empty ``poll`` list, the receiving
|
||||
server should immediately send the sending server a presence update EDU of its
|
||||
own, containing in a ``push`` list the current state of every user that was in
|
||||
the orginal EDU's ``poll`` list.
|
||||
the original EDU's ``poll`` list.
|
||||
|
||||
Sending a presence invite::
|
||||
|
||||
|
|
@ -721,7 +719,7 @@ Rejecting a presence invite::
|
|||
Content keys - as for m.presence_invite
|
||||
|
||||
.. TODO-doc
|
||||
- Explain the timing-based roundtrip reduction mechanism for presence
|
||||
- Explain the timing-based round-trip reduction mechanism for presence
|
||||
messages
|
||||
- Explain the zero-byte presence inference logic
|
||||
See also: docs/client-server/model/presence
|
||||
|
|
@ -742,8 +740,8 @@ Querying profile information::
|
|||
field: (optional) string giving a field name
|
||||
|
||||
Returns: JSON object containing the following keys:
|
||||
displayname: string of freeform text
|
||||
avatar_url: string containing an http-scheme URL
|
||||
displayname: string of free-form text
|
||||
avatar_url: string containing an HTTP-scheme URL
|
||||
|
||||
If the query contains the optional ``field`` key, it should give the name of a
|
||||
result field. If such is present, then the result should contain only a field
|
||||
|
|
@ -769,3 +767,4 @@ Querying directory information::
|
|||
The list of join candidates is a list of server names that are likely to hold
|
||||
the given room; these are servers that the requesting server may wish to try
|
||||
joining with. This list may or may not include the server answering the query.
|
||||
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ using this representation.
|
|||
value,
|
||||
# Encode code-points outside of ASCII as UTF-8 rather than \u escapes
|
||||
ensure_ascii=False,
|
||||
# Remove unecessary white space.
|
||||
# Remove unnecessary white space.
|
||||
separators=(',',':'),
|
||||
# Sort the keys of dictionaries.
|
||||
sort_keys=True,
|
||||
|
|
|
|||
|
|
@ -39,10 +39,10 @@ thumbnailing method::
|
|||
|
||||
<thumbnail>
|
||||
|
||||
The thumbnail methods are "crop" and "scale". "scale" trys to return an
|
||||
The thumbnail methods are "crop" and "scale". "scale" tries to return an
|
||||
image where either the width or the height is smaller than the requested
|
||||
size. The client should then scale and letterbox the image if it needs to
|
||||
fit within a given rectangle. "crop" trys to return an image where the
|
||||
fit within a given rectangle. "crop" tries to return an image where the
|
||||
width and height are close to the requested size and the aspect matches
|
||||
the requested size. The client should scale the image if it needs to fit
|
||||
within a given rectangle.
|
||||
|
|
@ -53,8 +53,8 @@ the content. Homeservers may return thumbnails of a different size to that
|
|||
requested. However homeservers should provide exact matches where reasonable.
|
||||
Homeservers must never upscale images.
|
||||
|
||||
Security
|
||||
--------
|
||||
Security considerations
|
||||
-----------------------
|
||||
|
||||
Clients may try to upload very large files. Homeservers should not store files
|
||||
that are too large and should not serve them to clients.
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@ Room Rules
|
|||
Sender
|
||||
These rules configure notification behaviour for messages from a specific,
|
||||
named Matrix user ID. The rule_id of Sender rules is always the Matrix user
|
||||
ID of the user whose messages theyt apply to.
|
||||
ID of the user whose messages they'd apply to.
|
||||
Underride
|
||||
These are identical to override rules, but have a lower priority than content,
|
||||
room and sender rules.
|
||||
|
|
@ -112,7 +112,7 @@ In addition, all rules may be enabled or disabled. Disabled rules never match.
|
|||
|
||||
If no rules match an event, the Home Server should not notify for the message
|
||||
(that is to say, the default action is "dont-notify"). Events that the user sent
|
||||
themself are never alerted for.
|
||||
themselves are never alerted for.
|
||||
|
||||
Predefined Rules
|
||||
----------------
|
||||
|
|
@ -128,7 +128,7 @@ with these IDs, their semantics should match those given below:
|
|||
|
||||
{
|
||||
"rule_id": ".m.rule.contains_user_name"
|
||||
"pattern": "[the lcoal part of the user's Matrix ID]",
|
||||
"pattern": "[the local part of the user's Matrix ID]",
|
||||
"actions": [
|
||||
"notify",
|
||||
{
|
||||
|
|
@ -220,7 +220,7 @@ with these IDs, their semantics should match those given below:
|
|||
Push Rules: Actions:
|
||||
--------------------
|
||||
All rules have an associated list of 'actions'. An action affects if and how a
|
||||
notification is delievered for a matching event. This standard defines the
|
||||
notification is delivered for a matching event. This standard defines the
|
||||
following actions, although if Home servers wish to support more, they are free
|
||||
to do so:
|
||||
|
||||
|
|
@ -241,11 +241,11 @@ set_tweak
|
|||
|
||||
Actions that have no parameters are represented as a string. Otherwise, they are
|
||||
represented as a dictionary with a key equal to their name and other keys as
|
||||
their parameters, eg. { "set_tweak": "sound", "value": "default" }
|
||||
their parameters, e.g. ``{ "set_tweak": "sound", "value": "default" }``
|
||||
|
||||
Push Rules: Actions: Tweaks
|
||||
---------------------------
|
||||
The 'set_tweak' key action is used to add an entry to the 'tweaks' dictionary
|
||||
The ``set_tweak`` key action is used to add an entry to the 'tweaks' dictionary
|
||||
that is sent in the notification poke. The following tweaks are defined:
|
||||
|
||||
sound
|
||||
|
|
@ -275,7 +275,7 @@ do so:
|
|||
|
||||
event_match
|
||||
This is a glob pattern match on a field of the event. Parameters:
|
||||
* 'key': The dot-separated field of the event to match, eg. content.body
|
||||
* 'key': The dot-separated field of the event to match, e.g. content.body
|
||||
* 'pattern': The glob-style pattern to match against. Patterns with no
|
||||
special glob characters should be treated as having asterisks
|
||||
prepended and appended when testing the condition.
|
||||
|
|
@ -295,7 +295,7 @@ room_member_count
|
|||
'>=' or '<='. A prefix of '<' matches rooms where the member count is
|
||||
strictly less than the given number and so forth. If no prefix is present,
|
||||
this matches rooms where the member count is exactly equal to the given
|
||||
number (ie. the same as '==').
|
||||
number (i.e. the same as '==').
|
||||
|
||||
Room, Sender, User and Content rules do not have conditions in the same way,
|
||||
but instead have predefined conditions, the behaviour of which can be configured
|
||||
|
|
@ -314,7 +314,7 @@ scope
|
|||
Either 'global' or 'device/<profile_tag>' to specify global rules or
|
||||
device rules for the given profile_tag.
|
||||
kind
|
||||
The kind of rule, ie. 'override', 'underride', 'sender', 'room', 'content'.
|
||||
The kind of rule, i.e. 'override', 'underride', 'sender', 'room', 'content'.
|
||||
rule_id
|
||||
The identifier for the rule.
|
||||
|
||||
|
|
@ -330,7 +330,7 @@ after
|
|||
rule.
|
||||
|
||||
All requests to the push rules API also require an access_token as a query
|
||||
paraemter.
|
||||
parameter.
|
||||
|
||||
The content of the PUT request is a JSON object with a list of actions under the
|
||||
'actions' key and either conditions (under the 'conditions' key) or the
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue