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/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,158 @@
+# 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, 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 ValidFeatures(str, Enum):
+    """
+    Currently supported per-user features
+    """
+
+    MSC3026 = "msc3026"
+    MSC2654 = "msc2654"
+    MSC3881 = "msc3881"
+    MSC3967 = "msc3967"
+
+
+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
+
+    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 [
+            ValidFeatures.MSC3026,
+            ValidFeatures.MSC2654,
+            ValidFeatures.MSC3881,
+            ValidFeatures.MSC3967,
+        ]
+
+        if not validated:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST, "Please provide a valid experimental feature."
+            )
+
+        enabled = await self.store.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 [
+            ValidFeatures.MSC3026,
+            ValidFeatures.MSC2654,
+            ValidFeatures.MSC3881,
+            ValidFeatures.MSC3967,
+        ]
+
+        if not validated:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST, "Please provide a valid experimental feature."
+            )
+
+        user, feature, enabled = await self.store.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 [
+            ValidFeatures.MSC3026,
+            ValidFeatures.MSC2654,
+            ValidFeatures.MSC3881,
+            ValidFeatures.MSC3967,
+        ]
+
+        if not validated:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST, "Please provide a valid experimental feature."
+            )
+
+        user, feature, enabled = await self.store.set_feature_for_user(
+            user_id, feature, False
+        )
+
+        return HTTPStatus.OK, {"user": user, "feature": feature, "enabled": enabled}

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

synapse/storage/schema/main/delta/75/01_per_user_experimental_features.sql

@@ -0,0 +1,34 @@
+/* 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 a list of 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 PRIMARY KEY,
+
+    -- busy presence state enabled
+    msc3026 BOOLEAN,
+
+    -- enable unread counts
+    msc2654 BOOLEAN,
+
+    -- enable remotely toggling push notifications for another client
+    msc3881 BOOLEAN,
+
+    -- Do not require UIA when first uploading cross signing keys
+    msc3967 BOOLEAN
+);
+