@ -75,8 +75,7 @@ said to be interested in a given event if one of the application service's names
users is the target of the event, or is a joined member of the room where the event
users is the target of the event, or is a joined member of the room where the event
occurred.
occurred.
An application
An application service can also state whether they should be the only ones who
service can also state whether they should be the only ones who
can manage a specified namespace. This is referred to as an "exclusive"
can manage a specified namespace. This is referred to as an "exclusive"
namespace. An exclusive namespace prevents humans and other application
namespace. An exclusive namespace prevents humans and other application
services from creating/deleting entities in that namespace. Typically,
services from creating/deleting entities in that namespace. Typically,
@ -90,33 +89,77 @@ regular expressions and look like:
users:
users:
- exclusive: true
- exclusive: true
regex: @_irc.freenode.net_.*
regex: "@_irc.freenode.net_.*"
Application services may define the following namespaces (with none being explicitly required):
+------------------+-----------------------------------------------------------+
| Name | Description |
+==================+===========================================================+
| users | Events which are sent from certain users. |
+------------------+-----------------------------------------------------------+
| aliases | Events which are sent in rooms with certain room aliases. |
+------------------+-----------------------------------------------------------+
| rooms | Events which are sent in rooms with certain room IDs. |
+------------------+-----------------------------------------------------------+
Each individual namespace MUST declare the following fields:
+------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| Name | Description |
+==================+===================================================================================================================================+
| exclusive | **Required** A true or false value stating whether this application service has exclusive access to events within this namespace. |
+------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| regex | **Required** A regular expression defining which values this namespace includes. |
+------------------+-----------------------------------------------------------------------------------------------------------------------------------+
Exclusive user and alias namespaces should begin with an underscore after the
sigil to avoid collisions with other users on the homeserver. Application
services should additionally attempt to identify the service they represent
in the reserved namespace. For example, `` @_irc_.* `` would be a good namespace
to register for an application service which deals with IRC.
The registration is represented by a series of key-value pairs, which this
The registration is represented by a series of key-value pairs, which this
specification will present as YAML. An example HS configuration required to pass
specification will present as YAML. See below for the possible options along
traffic to the AS is:
with their explanation:
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| Name | Description |
+==================+====================================================================================================================================================+
| id | **Required.** A unique, user-defined ID of the application service which will never change. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| url | **Required.** The URL for the application service. May include a path after the domain name. Optionally set to `` null `` if no traffic is required. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| as_token | **Required.** A unique token for application services to use to authenticate requests to Homeservers. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| hs_token | **Required.** A unique token for Homeservers to use to authenticate requests to application services. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| sender_localpart | **Required.** The localpart of the user associated with the application service. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| namespaces | **Required.** A list of `` users `` , `` aliases `` and `` rooms `` namespaces that the application service controls. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| rate_limited | Whether requests from masqueraded users are rate-limited. The sender is excluded. |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| protocols | The external protocols which the application service provides (e.g. IRC). |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
An example registration file for an IRC-bridging application service is below:
.. code-block :: yaml.. code-block :: yaml
id: <user-defined unique ID of AS which will never change>
id: "IRC Bridge"
url: <base url of AS>
url: "http://127.0.0.1:1234"
as_token: <token AS will add to requests to HS>
as_token: "30c05ae90a248a4188e620216fa72e349803310ec83e2a77b34fe90be6081f46"
hs_token: <token HS will add to requests to AS>
hs_token: "312df522183efd404ec1cd22d2ffa4bbc76a8c1ccf541dd692eef281356bb74e"
sender_localpart: <localpart of AS user>
sender_localpart: "_irc_bot" # Will result in @_irc_bot:domain.com
namespaces:
namespaces:
users: # Namespaces of users which should be delegated to the AS
users:
- exclusive: <bool>
- exclusive: true
regex: <regex>
regex: "@_irc_bridge_.*"
- ...
aliases:
aliases: [] # Namespaces of room aliases which should be delegated to the AS
- exclusive: false
rooms: [] # Namespaces of room ids which should be delegated to the AS
regex: "#_irc_bridge_.*"
rooms: []
Exclusive user and alias namespaces should begin with an underscore after the
sigil to avoid collisions with other users on the homeserver. Application
services should additionally attempt to identify the service they represent
in the reserved namespace. For example, `` @_irc_.* `` would be a good namespace
to register for an application service which deals with IRC.
.. WARNING :: .. WARNING ::
If the homeserver in question has multiple application services, each
If the homeserver in question has multiple application services, each
@ -155,6 +198,8 @@ be made without blocking other aspects of the homeserver. Homeservers MUST NOT
alter (e.g. add more) events they were going to send within that transaction ID
alter (e.g. add more) events they were going to send within that transaction ID
on retries, as the AS may have already processed the events.
on retries, as the AS may have already processed the events.
{{transactions_as_http_api}}
Querying
Querying
++++++++
++++++++
@ -180,13 +225,25 @@ this request (e.g. to join a room alias).
{{query_room_as_http_api}}
{{query_room_as_http_api}}
HTTP APIs
Third party networks
+++++++++
++++++++++++++++++++
Application services may declare which protocols they support via their registration
configuration for the homeserver. These networks are generally for third party services
such as IRC that the application service is managing. Application services may populate
a Matrix room directory for their registered protocols, as defined in the Client-Server
API Extensions.
This contains application service APIs which are used by the homeserver. All
Each protocol may have several "locations" (also known as "third party locations" or "3PLs").
application services MUST implement these APIs. These APIs are defined below.
A location within a protocol is a place in the third party network, such as an IRC channel.
Users of the third party network may also be represented by the application service.
{{application_service_as_http_api}}
Locations and users can be searched by fields defined by the application service, such
as by display name or other attribute. When clients request the homeserver to search
in a particular "network" (protocol), the search fields will be passed along to the
application service for filtering.
{{protocols_as_http_api}}
.. _create the user: `sect:asapi-permissions`_ .. _create the user: `sect:asapi-permissions`_
@ -198,6 +255,9 @@ Application services can use a more powerful version of the
client-server API by identifying itself as an application service to the
client-server API by identifying itself as an application service to the
homeserver.
homeserver.
Endpoints defined in this section MUST be supported by homeservers in the
client-server API as accessible only by application services.
Identity assertion
Identity assertion
++++++++++++++++++
++++++++++++++++++
The client-server API infers the user ID from the `` access_token `` provided in
The client-server API infers the user ID from the `` access_token `` provided in
@ -294,6 +354,15 @@ API MUST do so with a virtual user (provide a ``user_id`` via the query string).
is expected that the application service use the transactions pushed to it to
is expected that the application service use the transactions pushed to it to
handle events rather than syncing with the user implied by `` sender_localpart `` .
handle events rather than syncing with the user implied by `` sender_localpart `` .
Application service room directories
++++++++++++++++++++++++++++++++++++
Application services can maintain their own room directories for their defined
third party protocols. These room directories may be accessed by clients through
additional parameters on the `` /publicRooms `` client-server endpoint.
{{appservice_room_directory_cs_http_api}}
Event fields
Event fields
~~~~~~~~~~~~
~~~~~~~~~~~~
Travis Ralston
6 years ago