Skip to content

Commit 1945589

Browse files
richvdhrichvdh
authored
Clarifications to AS spec, including MSC3905 (#1305)
Primarily this is the spec for MSC3905, but I've also taken the opportunity to clean up the section a bit and move the definition out to a .yaml file.
1 parent 830f80f commit 1945589

File tree

4 files changed

+137
-57
lines changed

4 files changed

+137
-57
lines changed

‎changelogs/application_service/newsfragments/1305.clarification

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Clarify that application services can only register an interest in local users, as per [MSC3905](https://github.com/matrix-org/matrix-spec-proposals/issues/3905).

‎content/application-service-api.md

Lines changed: 34 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -37,14 +37,8 @@ registration for suspicious regex strings.
3737
{{% /boxes/note %}}
3838

3939
Application services register "namespaces" of user IDs, room aliases and
40-
room IDs. These namespaces are represented as regular expressions. An
41-
application service is said to be "interested" in a given event if one
42-
of the IDs in the event match the regular expression provided by the
43-
application service, such as the room having an alias or ID in the
44-
relevant namespaces. Similarly, the application service is said to be
45-
interested in a given event if one of the application service's
46-
namespaced users is the target of the event, or is a joined member of
47-
the room where the event occurred.
40+
room IDs. An application service is said to be "interested" in a given event
41+
if it matches any of the namespaces.
4842

4943
An application service can also state whether they should be the only
5044
ones who can manage a specified namespace. This is referred to as an
@@ -53,28 +47,12 @@ application services from creating/deleting entities in that namespace.
5347
Typically, exclusive namespaces are used when the rooms represent real
5448
rooms on another service (e.g. IRC). Non-exclusive namespaces are used
5549
when the application service is merely augmenting the room itself (e.g.
56-
providing logging or searching facilities). Namespaces are represented
57-
by POSIX extended regular expressions and look like:
50+
providing logging or searching facilities).
5851

59-
users:
60-
- exclusive: true
61-
regex: "@_irc_bridge_.*"
62-
63-
Application services may define the following namespaces (with none
64-
being explicitly required):
65-
66-
| Name | Description |
67-
|----------|------------------------------------------------------------|
68-
| users | Events which are sent from certain users. |
69-
| aliases | Events which are sent in rooms with certain room aliases. |
70-
| rooms | Events which are sent in rooms with certain room IDs. |
71-
72-
Each individual namespace MUST declare the following fields:
52+
The registration is represented by a series of key-value pairs, which
53+
is normally encoded as an object in a YAML file. It has the following structure:
7354

74-
| Name | Description |
75-
|------------|------------------------------------------------------------------------------------------------------------------------------------|
76-
| exclusive | **Required** A true or false value stating whether this application service has exclusive access to events within this namespace. |
77-
| regex | **Required** A regular expression defining which values this namespace includes. |
55+
{{% definition path="api/application-service/definitions/registration" %}}
7856

7957
Exclusive user and alias namespaces should begin with an underscore
8058
after the sigil to avoid collisions with other users on the homeserver.
@@ -83,38 +61,37 @@ they represent in the reserved namespace. For example, `@_irc_.*` would
8361
be a good namespace to register for an application service which deals
8462
with IRC.
8563

86-
The registration is represented by a series of key-value pairs, which
87-
this specification will present as YAML. See below for the possible
88-
options along with their explanation:
89-
90-
91-
| Name | Description |
92-
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
93-
| id | **Required** A unique, user-defined ID of the application service which will never change. |
94-
| 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. |
95-
| as_token | **Required** A unique token for application services to use to authenticate requests to Homeservers. |
96-
| hs_token | **Required** A unique token for Homeservers to use to authenticate requests to application services. |
97-
| sender_localpart | **Required** The localpart of the user associated with the application service. |
98-
| namespaces | **Required** A list of `users`, `aliases` and `rooms` namespaces that the application service controls. |
99-
| rate_limited | Whether requests from masqueraded users are rate-limited. The sender is excluded. |
100-
| protocols | The external protocols which the application service provides (e.g. IRC). |
101-
10264
An example registration file for an IRC-bridging application service is
10365
below:
10466

105-
id: "IRC Bridge"
106-
url: "http://127.0.0.1:1234"
107-
as_token: "30c05ae90a248a4188e620216fa72e349803310ec83e2a77b34fe90be6081f46"
108-
hs_token: "312df522183efd404ec1cd22d2ffa4bbc76a8c1ccf541dd692eef281356bb74e"
109-
sender_localpart: "_irc_bot" # Will result in @_irc_bot:example.org
110-
namespaces:
111-
users:
112-
- exclusive: true
113-
regex: "@_irc_bridge_.*"
114-
aliases:
115-
- exclusive: false
116-
regex: "#_irc_bridge_.*"
117-
rooms: []
67+
```yaml
68+
id: "IRC Bridge"
69+
url: "http://127.0.0.1:1234"
70+
as_token: "30c05ae90a248a4188e620216fa72e349803310ec83e2a77b34fe90be6081f46"
71+
hs_token: "312df522183efd404ec1cd22d2ffa4bbc76a8c1ccf541dd692eef281356bb74e"
72+
sender_localpart: "_irc_bot" # Will result in @_irc_bot:example.org
73+
namespaces:
74+
users:
75+
- exclusive: true
76+
regex: "@_irc_bridge_.*"
77+
aliases:
78+
- exclusive: false
79+
regex: "#_irc_bridge_.*"
80+
rooms: []
81+
```
82+
83+
{{% boxes/note %}}
84+
For the `users` namespace, application services can only register interest in
85+
*local* users (i.e., users whose IDs end with the `server_name` of the local
86+
homeserver). Events affecting users on other homeservers are not sent to an application
87+
service, even if the user happens to match the one of the `users` namespaces (unless,
88+
of course, the event affects a room that the application service is interested in
89+
for another room - for example, because there is another user in the room that the
90+
application service is interested in).
91+
92+
For the `rooms` and `aliases` namespaces, all events in a matching room will be
93+
sent to the application service.
94+
{{% /boxes/note %}}
11895

11996
{{% boxes/warning %}}
12097
If the homeserver in question has multiple application services, each

‎data/api/application-service/definitions/namespace_list.yaml

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Copyright 2022 The Matrix.org Foundation C.I.C
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
type: array
16+
items:
17+
type: object
18+
title: Namespace
19+
properties:
20+
regex:
21+
type: string
22+
description: A POSIX regular expression defining which values this namespace includes.
23+
exclusive:
24+
type: boolean
25+
description: A true or false value stating whether this application service has exclusive access to events within this namespace.
26+
required:
27+
- regex
28+
- exclusive

‎data/api/application-service/definitions/registration.yaml

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Copyright 2022 The Matrix.org Foundation C.I.C
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
type: object
16+
title: Registration
17+
properties:
18+
id:
19+
type: string
20+
description: A unique, user-defined ID of the application service which will never change.
21+
url:
22+
type: string
23+
description: The URL for the application service. May include a path after the domain name. Optionally set to null if no traffic is required.
24+
as_token:
25+
type: string
26+
description: A secret token that the application service will use to authenticate requests to the homeserver.
27+
hs_token:
28+
type: string
29+
description: A secret token that the homeserver will use authenticate requests to the application service.
30+
sender_localpart:
31+
type: string
32+
description: The localpart of the user associated with the application service.
33+
namespaces:
34+
type: object
35+
title: Namespaces
36+
description: The namespaces that the application service is interested in.
37+
properties:
38+
users:
39+
allOf:
40+
- $ref: namespace_list.yaml
41+
- description: |-
42+
A list of namespaces defining the user IDs that the application
43+
service is interested in. Events will be sent to the AS if a
44+
local user matching one of the namespaces is the target of the event,
45+
or is a joined member of the room where the event occurred.
46+
rooms:
47+
allOf:
48+
- $ref: namespace_list.yaml
49+
- description: |-
50+
A list of namespaces defining the room IDs that the application
51+
service is interested in. All events sent in a room with an ID
52+
which matches one of the namespaces will be sent to the AS.
53+
aliases:
54+
allOf:
55+
- $ref: namespace_list.yaml
56+
- description: |-
57+
A list of namespaces defining the room aliases that the application
58+
service is interested in. All events sent in a room with an alias
59+
which matches one of the namespaces will be sent to the AS.
60+
rate_limited:
61+
type: boolean
62+
description: Whether requests from masqueraded users are rate-limited. The sender is excluded.
63+
protocols:
64+
type: array
65+
description: The external protocols which the application service provides (e.g. IRC).
66+
items:
67+
type: string
68+
required:
69+
- id
70+
- url
71+
- as_token
72+
- hs_token
73+
- sender_localpart
74+
- namespaces

0 commit comments

Comments
 (0)