Merge branch 'develop' into na/chat-after-decline

Author: nabramow

app/backend/resources/badges.json

@@ -18,7 +18,8 @@
     {
       "id": "moderator",
       "color": "#c74f5b",
-      "admin_editable": false
+      "admin_editable": false,
+      "flag": "show_moderator_badge"
     },
     {
       "id": "volunteer",

app/backend/src/couchers/context.py

@@ -3,7 +3,6 @@
 import grpc
 
 from couchers import experimentation
-from couchers.config import config
 from couchers.i18n import LocalizationContext
 
 if TYPE_CHECKING:
@@ -181,29 +180,23 @@ def token(self) -> str:
     def localization(self) -> LocalizationContext:
         return self.__localization
 
-    # Feature-flag evaluation methods mirror the OpenFeature evaluation API. The in-code default is
-    # honored even for flags not yet set up in GrowthBook, since get_feature_value falls back to it.
+    # Feature-flag evaluation methods mirror the OpenFeature evaluation API, evaluating for this
+    # context's user. The gating lives in experimentation; we just pass our cached per-request
+    # evaluator. The in-code default is honored even for flags not yet set up in GrowthBook.
     def get_boolean_value(self, flag_key: str, default: bool) -> bool:
-        if config["EXPERIMENTATION_PASS_ALL_GATES"]:
-            return True
-        return self._get_feature_value(flag_key, default)
+        return experimentation._boolean_value(flag_key, default, self._get_growthbook)
 
     def get_string_value(self, flag_key: str, default: str) -> str:
-        return self._get_feature_value(flag_key, default)
+        return experimentation._feature_value(flag_key, default, self._get_growthbook)
 
     def get_integer_value(self, flag_key: str, default: int) -> int:
-        return self._get_feature_value(flag_key, default)
+        return experimentation._feature_value(flag_key, default, self._get_growthbook)
 
     def get_float_value(self, flag_key: str, default: float) -> float:
-        return self._get_feature_value(flag_key, default)
+        return experimentation._feature_value(flag_key, default, self._get_growthbook)
 
     def get_object_value[T](self, flag_key: str, default: T) -> T:
-        return self._get_feature_value(flag_key, default)
-
-    def _get_feature_value[T](self, flag_key: str, default: T) -> T:
-        if not config["EXPERIMENTATION_ENABLED"]:
-            return default
-        return self._get_growthbook().get_feature_value(flag_key, default)  # type: ignore[no-any-return]
+        return experimentation._feature_value(flag_key, default, self._get_growthbook)
 
     def _get_growthbook(self) -> GrowthBook:
         if self._growthbook is None:

app/backend/src/couchers/experimentation.py

@@ -3,25 +3,33 @@
 
 Uses GrowthBook under the hood, but abstracts the implementation details.
 
-Don't evaluate flags by calling into this module directly - go through the CouchersContext methods
-(context.get_boolean_value, get_string_value, etc.), which own the per-request evaluator cache and
-the enabled / pass-all-gates gating. The underscore-prefixed helpers here are internal to that
-wiring; setup_experimentation() is the only public entry point, called once at process startup.
+Two ways to evaluate a flag:
+  - Per-user/request: use the CouchersContext methods (context.get_boolean_value, get_string_value,
+    etc.), which evaluate for the context's user and own the per-request evaluator cache.
+  - Global (no user/request): use the module-level get_global_boolean_value / get_global_string_value
+    / ... below. Use these ONLY when there is genuinely no user to evaluate for and no way to thread
+    one through - per-user evaluation is impossible here, not merely that you don't expect the value
+    to vary per user. Whenever a user is (or could reasonably be) available, use the context: only the
+    per-user path can do percentage rollouts, experiments, and feature-usage tracking.
+
+Both paths share the enabled / pass-all-gates gating helpers here. setup_experimentation() is called
+once at process startup.
 """
 
 import json
 import logging
 import threading
+from collections.abc import Callable
 from typing import Any
 
 import urllib3
 from growthbook import GrowthBook
-from growthbook.common_types import Experiment, Result
+from growthbook.common_types import Experiment, FeatureResult, Result
 from sqlalchemy.dialects.postgresql import insert
 
 from couchers.config import config
 from couchers.db import session_scope
-from couchers.models.logging import ExperimentExposure
+from couchers.models.logging import ExperimentExposure, FeatureUsage
 
 logger = logging.getLogger(__name__)
 
@@ -139,13 +147,18 @@ def _record_exposure(user_id: int, experiment: Experiment, result: Result, **_:
         session.execute(stmt)
 
 
+def _record_feature_usage(user_id: int, key: str, result: FeatureResult, **_: Any) -> None:
+    with session_scope() as session:
+        session.add(FeatureUsage(user_id=user_id, feature_key=key, value=result.value))
+
+
 def _create_evaluator(user_id: int | None) -> GrowthBook:
     """
     Build a per-request GrowthBook evaluator over the current feature snapshot.
 
     Pass user_id=None for an anonymous (logged-out) evaluation: with no `id` attribute GrowthBook
     can't bucket the user, so experiments and percentage rollouts are skipped and flags fall
-    through to their defaults. No exposure is recorded without a user.
+    through to their defaults. No exposure or usage is recorded without a user.
 
     Reads the in-memory snapshot maintained by the background refresh thread - never does HTTP
     from the request path. Constructing without `client_key` keeps the GrowthBook a pure
@@ -164,9 +177,60 @@ def on_experiment_viewed(experiment: Experiment, result: Result, **kwargs: Any)
         if user_id is not None:
             _record_exposure(user_id, experiment, result)
 
+    def on_feature_usage(key: str, result: FeatureResult, *args: Any, **kwargs: Any) -> None:
+        if user_id is not None:
+            _record_feature_usage(user_id, key, result)
+
     return GrowthBook(
         attributes={"id": str(user_id)} if user_id is not None else {},
         features=features,
         savedGroups=saved_groups,
         on_experiment_viewed=on_experiment_viewed,
+        on_feature_usage=on_feature_usage,
     )
+
+
+def _global_evaluator() -> GrowthBook:
+    """Build an anonymous evaluator for flag evaluation with no user/request context."""
+    return _create_evaluator(None)
+
+
+# These two helpers are the single home of the gating logic, shared by the global functions below
+# and by CouchersContext (which passes its own cached per-request evaluator). get_evaluator is only
+# invoked once gating passes, so it stays lazy.
+def _feature_value[T](flag_key: str, default: T, get_evaluator: Callable[[], GrowthBook]) -> T:
+    if not config["EXPERIMENTATION_ENABLED"]:
+        return default
+    return get_evaluator().get_feature_value(flag_key, default)  # type: ignore[no-any-return]
+
+
+def _boolean_value(flag_key: str, default: bool, get_evaluator: Callable[[], GrowthBook]) -> bool:
+    if config["EXPERIMENTATION_PASS_ALL_GATES"]:
+        return True
+    return _feature_value(flag_key, default, get_evaluator)
+
+
+# Global (no-user) flag evaluation. Use these ONLY when there is genuinely no user to evaluate for and
+# no way to thread one through - per-user evaluation is impossible here, not merely that you don't
+# expect the value to vary per user. If a user is (or could reasonably be) available, use the
+# CouchersContext methods instead: only the per-user path does percentage rollouts, experiments, and
+# feature-usage tracking. With no user to bucket, rollouts and experiments are skipped and flags fall
+# through to their in-code defaults unless a rule forces a value globally.
+def get_global_boolean_value(flag_key: str, default: bool) -> bool:
+    return _boolean_value(flag_key, default, _global_evaluator)
+
+
+def get_global_string_value(flag_key: str, default: str) -> str:
+    return _feature_value(flag_key, default, _global_evaluator)
+
+
+def get_global_integer_value(flag_key: str, default: int) -> int:
+    return _feature_value(flag_key, default, _global_evaluator)
+
+
+def get_global_float_value(flag_key: str, default: float) -> float:
+    return _feature_value(flag_key, default, _global_evaluator)
+
+
+def get_global_object_value[T](flag_key: str, default: T) -> T:
+    return _feature_value(flag_key, default, _global_evaluator)

app/backend/src/couchers/jobs/handlers.py

@@ -29,6 +29,7 @@
     update,
 )
 
+from couchers import experimentation
 from couchers.config import config
 from couchers.constants import (
     ACTIVENESS_PROBE_EXPIRY_TIME,
@@ -838,6 +839,9 @@ def update_badges(payload: empty_pb2.Empty) -> None:
 
         def update_badge(badge_id: str, members: Sequence[int]) -> None:
             badge = get_badge_dict()[badge_id]
+            # this batch job has no per-user context to evaluate the gate against, so it's global
+            if badge.flag is not None and not experimentation.get_global_boolean_value(badge.flag, default=True):
+                members = []
             user_ids = session.execute(select(UserBadge.user_id).where(UserBadge.badge_id == badge.id)).scalars().all()
             # in case the user ids don't exist in the db
             actual_members = session.execute(select(User.id).where(User.id.in_(members))).scalars().all()

app/backend/src/couchers/migrations/versions/0157_log_feature_flag_usage_per_user.py

@@ -0,0 +1,46 @@
+"""Log feature flag usage per user
+
+Revision ID: 0157
+Revises: 0156
+Create Date: 2026-05-23 05:13:52.193316
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = "0157"
+down_revision = "0156"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "feature_usage",
+        sa.Column("id", sa.BigInteger(), nullable=False),
+        sa.Column("time", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("user_id", sa.BigInteger(), nullable=False),
+        sa.Column("feature_key", sa.String(), nullable=False),
+        sa.Column("value", postgresql.JSONB(astext_type=sa.Text()), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_feature_usage")),
+        schema="logging",
+    )
+    op.create_index(
+        "ix_logging_feature_usage_feature_key_time",
+        "feature_usage",
+        ["feature_key", "time"],
+        unique=False,
+        schema="logging",
+    )
+    op.create_index(
+        "ix_logging_feature_usage_user_id_time", "feature_usage", ["user_id", "time"], unique=False, schema="logging"
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_logging_feature_usage_user_id_time", table_name="feature_usage", schema="logging")
+    op.drop_index("ix_logging_feature_usage_feature_key_time", table_name="feature_usage", schema="logging")
+    op.drop_table("feature_usage", schema="logging")

app/backend/src/couchers/models/logging.py

@@ -156,3 +156,33 @@ class ExperimentExposure(Base, kw_only=True):
         Index("ix_logging_experiment_exposures_user_id_created", "user_id", "created"),
         {"schema": "logging"},
     )
+
+
+class FeatureUsage(Base, kw_only=True):
+    """
+    Append-only log of feature flag evaluations.
+
+    Populated by GrowthBook's on_feature_usage callback - one row per check.
+    """
+
+    __tablename__ = "feature_usage"
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, init=False)
+
+    # when the feature was checked
+    time: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), init=False)
+
+    # user the feature was checked for
+    user_id: Mapped[int] = mapped_column(BigInteger)
+
+    # feature identifier from GrowthBook
+    feature_key: Mapped[str] = mapped_column(String)
+
+    # the feature value the user received
+    value: Mapped[Any] = mapped_column(JSONB)
+
+    __table_args__ = (
+        Index("ix_logging_feature_usage_feature_key_time", "feature_key", "time"),
+        Index("ix_logging_feature_usage_user_id_time", "user_id", "time"),
+        {"schema": "logging"},
+    )

app/backend/src/couchers/resources.py

@@ -77,6 +77,9 @@ class Badge:
     id: str
     color: str
     admin_editable: bool
+    # if set, the badge is only awarded while this feature flag is on (the flag defaults to on, so
+    # the badge keeps being awarded until the flag is turned off)
+    flag: str | None = None
 
 
 @functools.cache

app/backend/src/couchers/servicers/bugs.py

@@ -1,11 +1,11 @@
 import json
 import time
 from datetime import UTC, datetime
-from typing import cast
+from typing import Any, cast
 
 import grpc
 import requests
-from google.protobuf import empty_pb2
+from google.protobuf import empty_pb2, struct_pb2
 from sqlalchemy import insert, select
 from sqlalchemy.orm import Session
 from sqlalchemy.sql import func
@@ -137,3 +137,20 @@ def GeolocationClickInfo(
         self, request: bugs_pb2.GeolocationClickInfoReq, context: CouchersContext, session: Session
     ) -> empty_pb2.Empty:
         return empty_pb2.Empty()
+
+    def EvaluateFeatureFlag(
+        self, request: bugs_pb2.EvaluateFeatureFlagReq, context: CouchersContext, session: Session
+    ) -> bugs_pb2.EvaluateFeatureFlagRes:
+        # None default: an unconfigured flag comes back as None and the value field is left unset, so
+        # the frontend applies its own in-code default. get_object_value is the generic typed
+        # accessor; like every value method it fires exposure/usage logging as a side effect, here
+        # for exactly the one flag the client is reading.
+        value: Any = context.get_object_value(request.flag_key, None)
+        res = bugs_pb2.EvaluateFeatureFlagRes()
+        if value is not None:
+            # google.protobuf.Value has no direct constructor from a Python value; round-trip
+            # through a Struct, which knows how to encode bool/number/str/list/dict.
+            holder = struct_pb2.Struct()
+            holder["value"] = value
+            res.value.CopyFrom(holder.fields["value"])
+        return res

app/backend/src/tests/test_bg_jobs.py

@@ -10,6 +10,7 @@
 from sqlalchemy.sql import delete, func
 
 import couchers.jobs.worker
+from couchers import experimentation
 from couchers.config import config
 from couchers.constants import HOST_REQUEST_MAX_REMINDERS, HOST_REQUEST_REMINDER_INTERVAL
 from couchers.crypto import urlsafe_secure_token
@@ -1342,6 +1343,50 @@ def test_update_badges(db, push_collector: PushCollector):
     assert push.content.body == "The Verified Phone badge was added to your profile."
 
 
+def test_update_badges_awards_moderator_to_superuser(db):
+    """The show_moderator_badge flag defaults on, so superusers are awarded the moderator badge."""
+    superuser, _ = generate_user(is_superuser=True, last_donated=None)
+
+    update_badges(empty_pb2.Empty())
+
+    with session_scope() as session:
+        assert (
+            session.execute(
+                select(func.count())
+                .select_from(UserBadge)
+                .where(UserBadge.user_id == superuser.id, UserBadge.badge_id == "moderator")
+            ).scalar()
+            == 1
+        )
+
+
+def test_update_badges_skips_moderator_when_flag_off(db, monkeypatch):
+    """With show_moderator_badge forced off, superusers are not awarded the moderator badge."""
+    # force show_moderator_badge off for everyone (force rule with no coverage applies globally)
+    monkeypatch.setattr(experimentation, "_initialized", True)
+    monkeypatch.setattr(
+        experimentation,
+        "_state",
+        {"features": {"show_moderator_badge": {"defaultValue": True, "rules": [{"force": False}]}}, "savedGroups": {}},
+    )
+    monkeypatch.setitem(config, "EXPERIMENTATION_ENABLED", True)
+    monkeypatch.setitem(config, "EXPERIMENTATION_PASS_ALL_GATES", False)
+
+    superuser, _ = generate_user(is_superuser=True, last_donated=None)
+
+    update_badges(empty_pb2.Empty())
+
+    with session_scope() as session:
+        assert (
+            session.execute(
+                select(func.count())
+                .select_from(UserBadge)
+                .where(UserBadge.user_id == superuser.id, UserBadge.badge_id == "moderator")
+            ).scalar()
+            == 0
+        )
+
+
 def test_send_request_notifications_blocked_users_no_notification(db, moderator):
     """
     Regression test: send_request_notifications should not send notifications