Add an admin API endpoint to support per-user feature flags

changelog.d/15344.feature

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

docs/admin_api/experimental_features.md

@@ -0,0 +1,38 @@
+# 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/).
+
+## Enable a Feature
+
+This API allows a server administrator to enable an experimental feature for a given user, where the
+user_id is the user id of the user for whom to enable the feature, and the feature is referred to by
+the msc number - i.e. to enable unread counts, the parameter `msc2654` would be added to the url. 
+
+The API is:
+
+```
+PUT /_synapse/admin/v1/experimental_features/<user_id>/<feature>
+```
+
+## Disable a Feature
+
+To disable a currently enabled feature, the API is:
+
+```
+DELETE /_synapse/admin/v1/experimental_features/<user_id>/<feature>
+```
+
+## Check if a feature is enabled
+
+To check if a given feature is enabled for a given user, the API is:
+
+```
+GET /_synapse/admin/v1/experimental_features/<user_id>/<feature>
+```

synapse/handlers/experimental_features.py

@@ -0,0 +1,55 @@
+# 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, Tuple
+
+if TYPE_CHECKING:
+ from synapse.server import HomeServer
+
+
+class ExperimentalFeaturesHandler:
+ def __init__(self, hs: "HomeServer"):
+ self.store = hs.get_datastores().main
+
+ async def get_feature_enabled(self, user: str, feature: str) -> bool:
+ """
+ Determine whether a given feature is enabled for the user.
+ Args:
+ user:
+ the user in question
+ feature:
+ the feature to determine is enabled
+ Returns:
+ True if the feature is enabled, False if not
+ """
+ return await self.store.get_feature_enabled(user, feature)
+
+ async def set_feature_for_user(
+ self, user: str, feature: str, enabled: bool
+ ) -> Tuple[str, str, bool]:
+ """
+ Set a feature to be enabled/disabled for a given user
+ Args:
+ user:
+ the user in question
+ feature:
+ the feature to set
+ enabled:
+ True to enable, False to disable
+ Returns:
+ a tuple of the user, the feature, and a bool indicating whether the feature is
+ enabled
+ """
+ return await self.store.set_feature_for_user(user, feature, enabled)

synapse/rest/admin/__init__.py

@@ -39,6 +39,7 @@
  EventReportDetailRestServlet,
  EventReportsRestServlet,
 )
+from synapse.rest.admin.experimental_features import ExperimentalFeaturesRestServlet
 from synapse.rest.admin.federation import (
  DestinationMembershipRestServlet,
  DestinationResetConnectionRestServlet,
@@ -288,6 +289,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(

synapse/rest/admin/experimental_features.py

@@ -0,0 +1,147 @@
+# 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 http import HTTPStatus
+from typing import TYPE_CHECKING, Tuple
+
+from synapse.api.errors import SynapseError
+from synapse.http.servlet import RestServlet
+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 ExperimentalFeaturesRestServlet(RestServlet):
+ """
+ Enable or disable an experimental feature or determine whether a given experimental
+ feature is enabled
+ """
+
+ PATTERNS = admin_patterns(
+ "/experimental_features/(?P<user_id>[^/]*)/(?P<feature>[^/]*)"
+ )
+
+ def __init__(self, hs: "HomeServer"):
+ super().__init__()
+ self.auth = hs.get_auth()
+ self.store = hs.get_datastores().main
+ self.is_mine = hs.is_mine
+ self.handler = hs.get_experimental_features_manager()
+
+ async def on_GET(
+ self,
+ request: SynapseRequest,
+ user_id: str,
+ feature: str,
+ ) -> Tuple[int, JsonDict]:
+ """
+ Checks if a given feature is 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.",
+ )
+
+ # do a basic validation of the given feature
+ validated = feature in [
+ "msc3026",
+ "msc2654",
+ "msc3881",
+ "msc3967",
+ ]
+
+ if not validated:
+ raise SynapseError(
+ HTTPStatus.BAD_REQUEST, "Please provide a valid experimental feature."
+ )
+
+ enabled = await self.handler.get_feature_enabled(user_id, feature)
+
+ return HTTPStatus.OK, {"user": user_id, "feature": feature, "enabled": enabled}
+
+ async def on_PUT(
+ self, request: SynapseRequest, user_id: str, feature: str
+ ) -> Tuple[int, JsonDict]:
+ """
+ Enables a given feature for the requester
+ """
+ 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 enable experimental features.",
+ )
+
+ # validate the feature
+ validated = feature in [
+ "msc3026",
+ "msc2654",
+ "msc3881",
+ "msc3967",
+ ]
+
+ if not validated:
+ raise SynapseError(
+ HTTPStatus.BAD_REQUEST, "Please provide a valid experimental feature."
+ )
+
+ user, feature, enabled = await self.handler.set_feature_for_user(
+ user_id, feature, True
+ )
+
+ return HTTPStatus.OK, {"user": user, "feature": feature, "enabled": enabled}
+
+ async def on_DELETE(
+ self, request: SynapseRequest, user_id: str, feature: str
+ ) -> Tuple[int, JsonDict]:
+ """
+ Disables the requested feature for the 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 disable an experimental feature.",
+ )
+
+ # validate the feature
+ validated = feature in [
+ "msc3026",
+ "msc2654",
+ "msc3881",
+ "msc3967",
+ ]
+
+ if not validated:
+ raise SynapseError(
+ HTTPStatus.BAD_REQUEST, "Please provide a valid experimental feature."
+ )
+
+ user, feature, enabled = await self.handler.set_feature_for_user(
+ user_id, feature, False
+ )
+
+ return HTTPStatus.OK, {"user": user, "feature": feature, "enabled": enabled}

synapse/server.py

@@ -68,6 +68,7 @@
 from synapse.handlers.e2e_room_keys import E2eRoomKeysHandler
 from synapse.handlers.event_auth import EventAuthHandler
 from synapse.handlers.events import EventHandler, EventStreamHandler
+from synapse.handlers.experimental_features import ExperimentalFeaturesHandler
 from synapse.handlers.federation import FederationHandler
 from synapse.handlers.federation_event import FederationEventHandler
 from synapse.handlers.identity import IdentityHandler
@@ -875,3 +876,7 @@ def get_request_ratelimiter(self) -> RequestRatelimiter:
  def get_common_usage_metrics_manager(self) -> CommonUsageMetricsManager:
  """Usage metrics shared between phone home stats and the prometheus exporter."""
  return CommonUsageMetricsManager(self)
+
+ @cache_in_self
+ def get_experimental_features_manager(self) -> ExperimentalFeaturesHandler:
+ return ExperimentalFeaturesHandler(self)

synapse/storage/databases/main/__init__.py

@@ -43,6 +43,7 @@
 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 @@
 
 class DataStore(
  EventsBackgroundUpdatesStore,
+ ExperimentalFeaturesStore,
  DeviceStore,
  RoomMemberStore,
  RoomStore,

synapse/storage/databases/main/experimental_features.py

@@ -0,0 +1,80 @@
+# 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, Tuple
+
+from synapse.api.errors import StoreError
+from synapse.storage._base import SQLBaseStore
+from synapse.storage.database import DatabasePool, LoggingDatabaseConnection
+
+if TYPE_CHECKING:
+ from synapse.server import HomeServer
+
+
+class ExperimentalFeaturesStore(SQLBaseStore):
+ def __init__(
+ self,
+ database: DatabasePool,
+ db_conn: LoggingDatabaseConnection,
+ hs: "HomeServer",
+ ) -> None:
+ super().__init__(database, db_conn, hs)
+
+ async def get_feature_enabled(self, user_id: str, feature: str) -> bool:
+ """
+ Checks to see if a given feature is enabled for the user
+ Args:
+ user:
+ the user to be queried on
+ feature:
+ the feature in question
+ Returns:
+ True if the feature is enabled, False if it is not or if the feature was
+ not found.
+ """
+ enabled = await self.db_pool.simple_select_one(
+ "per_user_experimental_features",
+ {"user_id": user_id},
+ [feature],
+ allow_none=True,
+ )
+
+ if not enabled or not enabled[feature]:
+ return False
+ else:
+ return True
+
+ async def set_feature_for_user(
+ self, user: str, feature: str, enabled: bool
+ ) -> Tuple[str, str, bool]:
+ """
+ Enables or disables a given feature for a given user
+ Args:
+ user:
+ the user for whom to enable/disable a feature
+ feature:
+ the feature to be enabled/diabled
+ enabled:
+ True to enable, False to disable
+ Returns:
+ A tuple of user, feature, and a bool indicating that the feature is enabled
+ or disabled
+ """
+ success = await self.db_pool.simple_upsert(
+ "per_user_experimental_features", {"user_id": user}, {feature: enabled}
+ )
+ if not success:
+ raise StoreError(500, "There was a problem setting your feature.")
+
+ return user, feature, enabled