From d6fb5afd16ad1682d90c9dd3bd505e9baf60e513 Mon Sep 17 00:00:00 2001 From: user Date: Mon, 28 May 2018 23:30:40 +0100 Subject: [PATCH] Clarified group_id group visibility, url possibilities, regex starters Changed Application Service capatalization to be consistent with the rest of the document. --- specification/application_service_api.rst | 68 ++++++++++++----------- 1 file changed, 35 insertions(+), 33 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 6eb8e87e..31983a0c 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -83,10 +83,10 @@ regular expressions and look like: users: - exclusive: true - regex: "@irc.freenode.net_.*" + regex: "@_irc.freenode.net_.*" group_id: "+irc:matrix.org" -Application Services may define the following namespaces (with none being explicitly required): +Application services may define the following namespaces (with none being explicitly required): +------------------+-----------------------------------------------------------+ | Name | Description | @@ -103,22 +103,24 @@ 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. | +| 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. | +------------------+-----------------------------------------------------------------------------------------------------------------------------------+ -An optional ``group_id`` field may be added to the users namespace: +An application service's users and regex field MUST begin with an underscore (``_``), in +order to provide a visually clear distinction between AS users and regular +users. An optional ``group_id`` field may be added to the ``users`` namespace: -+------------------+-----------------------------------------------------------+ -| Name | Description | -+==================+===========================================================+ -| group_id | All matching users will be considered part of this group. | -+------------------+-----------------------------------------------------------+ ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Description | ++==================+============================================================================================================================================================================================================================================================================+ +| group_id | An existing group that all matching user IDs will be considered a part of. Users who are joined to this group through an application service are not to be listed when querying for the group's members, however the group should be listed when querying a user's groups. | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. WARNING:: - Users that are matched by ``group_id`` should not be publically listed by + Users that are matched by ``group_id`` should not be publicly listed by Homeservers. The intention is to differentiate users, perhaps with a flair, rather than having a list of people to spam. @@ -127,27 +129,27 @@ 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 base URL for the Application Service. | -+------------------+----------------------------------------------------------------------------------------------------------+ -| 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: ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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 @@ -159,10 +161,10 @@ An example registration file for an IRC-bridging Application Service is below: namespaces: users: - exclusive: true - regex: "@irc_bridge_.*" + regex: "@_irc_bridge_.*" aliases: - exclusive: false - regex: "#irc_bridge_.*" + regex: "#_irc_bridge_.*" rooms: [] .. WARNING::