OpenCloud
/
MatrixSynapse
mirror of https://github.com/matrix-org/synapse
1
0
Fork 0
Code Issues Releases Wiki Activity

Add an admin API endpoint to support per-user feature flags (#15344)

pull/15507/head
Shay 2023-04-28 11:33:45 -07:00 committed by GitHub
parent eb6f8dc215
commit 89f6fb0d5a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 408 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
changelog.d/15344.feature Normal file
View File

@ -0,0 +1 @@
Add an admin API endpoint to support per-user feature flags.

54
docs/admin_api/experimental_features.md Normal file
View File

@ -0,0 +1,54 @@
# Experimental Features API
This API allows a server administrator to enable or disable some experimental features on a per-user
basis. Currently supported features are [msc3026](https://github.com/matrix-org/matrix-spec-proposals/pull/3026): busy
presence state enabled, [msc2654](https://github.com/matrix-org/matrix-spec-proposals/pull/2654): enable unread counts,
[msc3881](https://github.com/matrix-org/matrix-spec-proposals/pull/3881): enable remotely toggling push notifications
for another client, and [msc3967](https://github.com/matrix-org/matrix-spec-proposals/pull/3967): do not require
UIA when first uploading cross-signing keys.
To use it, you will need to authenticate by providing an `access_token`
for a server admin: see [Admin API](../usage/administration/admin_api/).
## Enabling/Disabling Features
This API allows a server administrator to enable experimental features for a given user. The request must
provide a body containing the user id and listing the features to enable/disable in the following format:
```json
{
"features": {
"msc3026":true,
"msc2654":true
}
}
```
where true is used to enable the feature, and false is used to disable the feature.
The API is:
```
PUT /_synapse/admin/v1/experimental_features/<user_id>
```
## Listing Enabled Features
To list which features are enabled/disabled for a given user send a request to the following API:
```
GET /_synapse/admin/v1/experimental_features/<user_id>
```
It will return a list of possible features and indicate whether they are enabled or disabled for the
user like so:
```json
{
"features": {
"msc3026": true,
"msc2654": true,
"msc3881": false,
"msc3967": false
}
}
```

1
synapse/_scripts/synapse_port_db.py
View File

@ -125,6 +125,7 @@ BOOLEAN_COLUMNS = {
"users": ["shadow_banned", "approved"],
"un_partial_stated_event_stream": ["rejection_status_changed"],
"users_who_share_rooms": ["share_private"],
"per_user_experimental_features": ["enabled"],
}

2
synapse/rest/admin/__init__.py
View File

@ -39,6 +39,7 @@ from synapse.rest.admin.event_reports import (
EventReportDetailRestServlet,
EventReportsRestServlet,
)
from synapse.rest.admin.experimental_features import ExperimentalFeaturesRestServlet
from synapse.rest.admin.federation import (
DestinationMembershipRestServlet,
DestinationResetConnectionRestServlet,
@ -292,6 +293,7 @@ def register_servlets(hs: "HomeServer", http_server: HttpServer) -> None:
BackgroundUpdateEnabledRestServlet(hs).register(http_server)
BackgroundUpdateRestServlet(hs).register(http_server)
BackgroundUpdateStartJobRestServlet(hs).register(http_server)
ExperimentalFeaturesRestServlet(hs).register(http_server)
def register_servlets_for_client_rest_resource(

119
synapse/rest/admin/experimental_features.py Normal file
View File

@ -0,0 +1,119 @@
# Copyright 2023 The Matrix.org Foundation C.I.C
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
from enum import Enum
from http import HTTPStatus
from typing import TYPE_CHECKING, Dict, Tuple
from synapse.api.errors import SynapseError
from synapse.http.servlet import RestServlet, parse_json_object_from_request
from synapse.http.site import SynapseRequest
from synapse.rest.admin import admin_patterns, assert_requester_is_admin
from synapse.types import JsonDict, UserID
if TYPE_CHECKING:
from synapse.server import HomeServer
class ExperimentalFeature(str, Enum):
"""
Currently supported per-user features
"""
MSC3026 = "msc3026"
MSC2654 = "msc2654"
MSC3881 = "msc3881"
MSC3967 = "msc3967"
class ExperimentalFeaturesRestServlet(RestServlet):
"""
Enable or disable experimental features for a user or determine which features are enabled
for a given user
"""
PATTERNS = admin_patterns("/experimental_features/(?P<user_id>[^/]*)")
def __init__(self, hs: "HomeServer"):
super().__init__()
self.auth = hs.get_auth()
self.store = hs.get_datastores().main
self.is_mine = hs.is_mine
async def on_GET(
self,
request: SynapseRequest,
user_id: str,
) -> Tuple[int, JsonDict]:
"""
List which features are enabled for a given user
"""
await assert_requester_is_admin(self.auth, request)
target_user = UserID.from_string(user_id)
if not self.is_mine(target_user):
raise SynapseError(
HTTPStatus.BAD_REQUEST,
"User must be local to check what experimental features are enabled.",
)
enabled_features = await self.store.list_enabled_features(user_id)
user_features = {}
for feature in ExperimentalFeature:
if feature in enabled_features:
user_features[feature] = True
else:
user_features[feature] = False
return HTTPStatus.OK, {"features": user_features}
async def on_PUT(
self, request: SynapseRequest, user_id: str
) -> Tuple[HTTPStatus, Dict]:
"""
Enable or disable the provided features for the requester
"""
await assert_requester_is_admin(self.auth, request)
body = parse_json_object_from_request(request)
target_user = UserID.from_string(user_id)
if not self.is_mine(target_user):
raise SynapseError(
HTTPStatus.BAD_REQUEST,
"User must be local to enable experimental features.",
)
features = body.get("features")
if not features:
raise SynapseError(
HTTPStatus.BAD_REQUEST, "You must provide features to set."
)
# validate the provided features
validated_features = {}
for feature, enabled in features.items():
try:
validated_feature = ExperimentalFeature(feature)
validated_features[validated_feature] = enabled
except ValueError:
raise SynapseError(
HTTPStatus.BAD_REQUEST,
f"{feature!r} is not recognised as a valid experimental feature.",
)
await self.store.set_features_for_user(user_id, validated_features)
return HTTPStatus.OK, {}

2
synapse/storage/databases/main/__init__.py
View File

@ -43,6 +43,7 @@ from .event_federation import EventFederationStore
from .event_push_actions import EventPushActionsStore
from .events_bg_updates import EventsBackgroundUpdatesStore
from .events_forward_extremities import EventForwardExtremitiesStore
from .experimental_features import ExperimentalFeaturesStore
from .filtering import FilteringWorkerStore
from .keys import KeyStore
from .lock import LockStore
@ -82,6 +83,7 @@ logger = logging.getLogger(__name__)
class DataStore(
EventsBackgroundUpdatesStore,
ExperimentalFeaturesStore,
DeviceStore,
RoomMemberStore,
RoomStore,

75
synapse/storage/databases/main/experimental_features.py Normal file
View File

@ -0,0 +1,75 @@
# Copyright 2023 The Matrix.org Foundation C.I.C
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
from typing import TYPE_CHECKING, Dict
from synapse.storage.database import DatabasePool, LoggingDatabaseConnection
from synapse.storage.databases.main import CacheInvalidationWorkerStore
from synapse.types import StrCollection
from synapse.util.caches.descriptors import cached
if TYPE_CHECKING:
from synapse.rest.admin.experimental_features import ExperimentalFeature
from synapse.server import HomeServer
class ExperimentalFeaturesStore(CacheInvalidationWorkerStore):
def __init__(
self,
database: DatabasePool,
db_conn: LoggingDatabaseConnection,
hs: "HomeServer",
) -> None:
super().__init__(database, db_conn, hs)
@cached()
async def list_enabled_features(self, user_id: str) -> StrCollection:
"""
Checks to see what features are enabled for a given user
Args:
user:
the user to be queried on
Returns:
the features currently enabled for the user
"""
enabled = await self.db_pool.simple_select_list(
"per_user_experimental_features",
{"user_id": user_id, "enabled": True},
["feature"],
)
return [feature["feature"] for feature in enabled]
async def set_features_for_user(
self,
user: str,
features: Dict["ExperimentalFeature", bool],
) -> None:
"""
Enables or disables features for a given user
Args:
user:
the user for whom to enable/disable the features
features:
pairs of features and True/False for whether the feature should be enabled
"""
for feature, enabled in features.items():
await self.db_pool.simple_upsert(
table="per_user_experimental_features",
keyvalues={"feature": feature, "user_id": user},
values={"enabled": enabled},
insertion_values={"user_id": user, "feature": feature},
)
await self.invalidate_cache_and_stream("list_enabled_features", (user,))

27
synapse/storage/schema/main/delta/76/03_per_user_experimental_features.sql Normal file
View File

@ -0,0 +1,27 @@
/* Copyright 2023 The Matrix.org Foundation C.I.C
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-- Table containing experimental features and whether they are enabled for a given user
CREATE TABLE per_user_experimental_features (
-- The User ID to check/set the feature for
user_id TEXT NOT NULL,
-- Contains features to be enabled/disabled
feature TEXT NOT NULL,
-- whether the feature is enabled/disabled for a given user, defaults to disabled
enabled BOOLEAN DEFAULT FALSE,
FOREIGN KEY (user_id) REFERENCES users(name),
PRIMARY KEY (user_id, feature)
);

127
tests/rest/admin/test_admin.py
View File

@ -372,3 +372,130 @@ class PurgeHistoryTestCase(unittest.HomeserverTestCase):
self.assertEqual(200, channel.code, msg=channel.json_body)
self.assertEqual("complete", channel.json_body["status"])
class ExperimentalFeaturesTestCase(unittest.HomeserverTestCase):
servlets = [
synapse.rest.admin.register_servlets,
login.register_servlets,
]
def prepare(self, reactor: MemoryReactor, clock: Clock, hs: HomeServer) -> None:
self.admin_user = self.register_user("admin", "pass", admin=True)
self.admin_user_tok = self.login("admin", "pass")
self.other_user = self.register_user("user", "pass")
self.other_user_tok = self.login("user", "pass")
self.url = "/_synapse/admin/v1/experimental_features"
def test_enable_and_disable(self) -> None:
"""
Test basic functionality of ExperimentalFeatures endpoint
"""
# test enabling features works
url = f"{self.url}/{self.other_user}"
channel = self.make_request(
"PUT",
url,
content={
"features": {"msc3026": True, "msc2654": True},
},
access_token=self.admin_user_tok,
)
self.assertEqual(channel.code, 200)
# list which features are enabled and ensure the ones we enabled are listed
self.assertEqual(channel.code, 200)
url = f"{self.url}/{self.other_user}"
channel = self.make_request(
"GET",
url,
access_token=self.admin_user_tok,
)
self.assertEqual(channel.code, 200)
self.assertEqual(
True,
channel.json_body["features"]["msc3026"],
)
self.assertEqual(
True,
channel.json_body["features"]["msc2654"],
)
# test disabling a feature works
url = f"{self.url}/{self.other_user}"
channel = self.make_request(
"PUT",
url,
content={"features": {"msc3026": False}},
access_token=self.admin_user_tok,
)
self.assertEqual(channel.code, 200)
# list the features enabled/disabled and ensure they are still are correct
self.assertEqual(channel.code, 200)
url = f"{self.url}/{self.other_user}"
channel = self.make_request(
"GET",
url,
access_token=self.admin_user_tok,
)
self.assertEqual(channel.code, 200)
self.assertEqual(
False,
channel.json_body["features"]["msc3026"],
)
self.assertEqual(
True,
channel.json_body["features"]["msc2654"],
)
self.assertEqual(
False,
channel.json_body["features"]["msc3881"],
)
self.assertEqual(
False,
channel.json_body["features"]["msc3967"],
)
# test nothing blows up if you try to disable a feature that isn't already enabled
url = f"{self.url}/{self.other_user}"
channel = self.make_request(
"PUT",
url,
content={"features": {"msc3026": False}},
access_token=self.admin_user_tok,
)
self.assertEqual(channel.code, 200)
# test trying to enable a feature without an admin access token is denied
url = f"{self.url}/f{self.other_user}"
channel = self.make_request(
"PUT",
url,
content={"features": {"msc3881": True}},
access_token=self.other_user_tok,
)
self.assertEqual(channel.code, 403)
self.assertEqual(
channel.json_body,
{"errcode": "M_FORBIDDEN", "error": "You are not a server admin"},
)
# test trying to enable a bogus msc is denied
url = f"{self.url}/{self.other_user}"
channel = self.make_request(
"PUT",
url,
content={"features": {"msc6666": True}},
access_token=self.admin_user_tok,
)
self.assertEqual(channel.code, 400)
self.assertEqual(
channel.json_body,
{
"errcode": "M_UNKNOWN",
"error": "'msc6666' is not recognised as a valid experimental feature.",
},
)