From 9ca62edda0a664f65ac7ff31b659a77efce7edb1 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 25 May 2018 19:39:54 +0100 Subject: [PATCH 1/3] Document new application service registration file options. --- .../application_service.yaml | 2 +- specification/application_service_api.rst | 89 +++++++++++++++---- 2 files changed, 75 insertions(+), 16 deletions(-) diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index c39ce198..a63774a2 100644 --- a/api/application-service/application_service.yaml +++ b/api/application-service/application_service.yaml @@ -43,7 +43,7 @@ paths: x-example: "35" - in: body name: body - description: A list of events + description: A list of events. schema: type: object example: { diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index b4950eac..6eb8e87e 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -83,34 +83,93 @@ 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): + ++------------------+-----------------------------------------------------------+ +| 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. | ++------------------+-----------------------------------------------------------------------------------------------------------------------------------+ + +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. | ++------------------+-----------------------------------------------------------+ + +.. WARNING:: + + Users that are matched by ``group_id`` should not be publically listed by + Homeservers. The intention is to differentiate users, perhaps with a flair, + rather than having a list of people to spam. 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 -traffic to the AS is: +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: .. code-block:: yaml - id: - url: - as_token: - hs_token: - sender_localpart: + 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: # Namespaces of users which should be delegated to the AS - - exclusive: - 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 + 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 used to identify the application service. The homeserver MUST enforce this. - Homeserver -> Application Service API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From d6fb5afd16ad1682d90c9dd3bd505e9baf60e513 Mon Sep 17 00:00:00 2001 From: user Date: Mon, 28 May 2018 23:30:40 +0100 Subject: [PATCH 2/3] 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 | 66 ++++++++++++----------- 1 file changed, 34 insertions(+), 32 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). | -+------------------+----------------------------------------------------------------------------------------------------------+ ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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: +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:: From 339a2748e806a8a42925afd0384521cafbd57d2d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 21 Aug 2018 09:49:41 -0600 Subject: [PATCH 3/3] Take out groups for now; Move namespace mention Groups aren't landing in the spec yet, so we shouldn't include them yet. --- specification/application_service_api.rst | 31 +++++------------------ 1 file changed, 6 insertions(+), 25 deletions(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 9e84339f..258f80c0 100644 --- a/specification/application_service_api.rst +++ b/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 -service can also state whether they should be the only ones who +An application 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, @@ -91,7 +90,6 @@ regular expressions and look like: users: - exclusive: true regex: "@_irc.freenode.net_.*" - group_id: "+irc:matrix.org" Application services may define the following namespaces (with none being explicitly required): @@ -115,22 +113,11 @@ Each individual namespace MUST declare the following fields: | regex | **Required** A regular expression defining which values this namespace includes. | +------------------+-----------------------------------------------------------------------------------------------------------------------------------+ -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 | 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 publicly listed by - Homeservers. The intention is to differentiate users, perhaps with a flair, - rather than having a list of people to spam. - +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 specification will present as YAML. See below for the possible options along @@ -174,12 +161,6 @@ An example registration file for an IRC-bridging application service is below: 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:: If the homeserver in question has multiple application services, each ``as_token`` and ``id`` MUST be unique per application service as these are