Merge pull request #1262 from matrix-org/anoa/document_as_options

Document new application service registration file options

specification/application_service_api.rst

@@ -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
 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"
 namespace. An exclusive namespace prevents humans and other application
 services from creating/deleting entities in that namespace. Typically,
@@ -90,27 +89,29 @@ regular expressions and look like:
 
    users:
      - exclusive: true
-       regex: @_irc.freenode.net_.*
+       regex: "@_irc.freenode.net_.*"
 
+Application services may define the following namespaces (with none being explicitly required):
 
-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
+| Name             | Description                                               |
-traffic to the AS is:
++==================+===========================================================+
+| 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.     |
++------------------+-----------------------------------------------------------+
 
-.. code-block:: yaml
+Each individual namespace MUST declare the following fields:
 
-    id: <user-defined unique ID of AS which will never change>
++------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    url: <base url of AS>
+| Name             | Description                                                                                                                       |
-    as_token: <token AS will add to requests to HS>
++==================+===================================================================================================================================+
-    hs_token: <token HS will add to requests to AS>
+| exclusive        | **Required** A true or false value stating whether this application service has exclusive access to events within this namespace. |
-    sender_localpart: <localpart of AS user>
++------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    namespaces:
+| regex            | **Required** A regular expression defining which values this namespace includes.                                                  |
-      users:  # Namespaces of users which should be delegated to the AS
++------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-        - exclusive: <bool>
-          regex: <regex>
-        - ...
-      aliases: []  # Namespaces of room aliases which should be delegated to the AS
-      rooms: [] # Namespaces of room ids which should be delegated to the AS
 
 Exclusive user and alias namespaces should begin with an underscore after the
 sigil to avoid collisions with other users on the homeserver. Application
@@ -118,6 +119,48 @@ 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
+specification will present as YAML. See below for the possible options along
+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
+
+    id: "IRC Bridge"
+    url: "http://127.0.0.1:1234"
+    as_token: "30c05ae90a248a4188e620216fa72e349803310ec83e2a77b34fe90be6081f46"
+    hs_token: "312df522183efd404ec1cd22d2ffa4bbc76a8c1ccf541dd692eef281356bb74e"
+    sender_localpart: "_irc_bot" # Will result in @_irc_bot:domain.com
+    namespaces:
+      users:
+        - exclusive: true
+          regex: "@_irc_bridge_.*"
+      aliases:
+        - exclusive: false 
+          regex: "#_irc_bridge_.*"
+      rooms: []
+
 .. WARNING::
   If the homeserver in question has multiple application services, each
   ``as_token`` and ``id`` MUST be unique per application service as these are