Backend: resolve BASE_URL override through context, drop clear semantics

Address review feedback on the per-user BASE_URL override:
- Resolution moves onto CouchersContext.use_base_url_override (a contextmanager
  that sets the urls contextvar), replacing the free-floating
  use_base_url_override_for_user(session, user_id) helper. The interceptor and
  notification job now go through context, matching how the rest of the codebase
  carries per-operation user state.
- An override is always non-empty: SetBaseUrlOverride rejects an empty base_url
  and the empty-string-clears-the-override semantics is gone (it expires via TTL).
- Add a composite index (user_id, created) serving the active-override lookup,
  replacing the redundant single-column user_id index.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: aapeliv

app/backend/src/couchers/base_url_override.py

@@ -1,52 +1,30 @@
 """
 Dev/testing override of BASE_URL, see couchers.models.rest.BaseUrlOverride.
 
-The active override for a user is set on the urls.base_url_override contextvar for the duration of a request
-(from the authenticated user) or a notification job (from the recipient), so that every link built via
-couchers.urls points back at whatever frontend the developer is testing on. Gated by ENABLE_DEV_APIS, so this is
-entirely inert in real prod (no overrides can ever be created or applied there).
+The active override for a user is applied via CouchersContext.use_base_url_override, which sets the
+urls.base_url_override contextvar for the duration of a request (the authenticated user) or a notification job
+(the recipient), so that every link built via couchers.urls points back at whatever frontend the developer is
+testing on. Gated by ENABLE_DEV_APIS, so this is entirely inert in real prod (no overrides can ever be created
+or applied there).
 """
 
-from collections.abc import Iterator
-from contextlib import contextmanager
 from datetime import timedelta
 
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
-from couchers import urls
-from couchers.config import config
 from couchers.models import BaseUrlOverride
 from couchers.utils import now
 
 BASE_URL_OVERRIDE_TTL = timedelta(minutes=15)
 
 
 def get_active_base_url_override(session: Session, user_id: int) -> str | None:
-    """The most recently set, non-expired, non-empty base url override for the user, if any."""
-    base_url = session.execute(
+    """The most recently set, non-expired base url override for the user, if any."""
+    return session.execute(
         select(BaseUrlOverride.base_url)
         .where(BaseUrlOverride.user_id == user_id)
         .where(BaseUrlOverride.created > now() - BASE_URL_OVERRIDE_TTL)
         .order_by(BaseUrlOverride.created.desc(), BaseUrlOverride.id.desc())
         .limit(1)
     ).scalar_one_or_none()
-    return base_url or None
-
-
-@contextmanager
-def use_base_url_override_for_user(session: Session, user_id: int | None) -> Iterator[None]:
-    """Set the base url override contextvar to the user's active override for the duration of the block."""
-    override = None
-    if config["ENABLE_DEV_APIS"] and user_id is not None:
-        override = get_active_base_url_override(session, user_id)
-
-    if not override:
-        yield
-        return
-
-    token = urls.base_url_override.set(override)
-    try:
-        yield
-    finally:
-        urls.base_url_override.reset(token)

app/backend/src/couchers/context.py

@@ -1,8 +1,13 @@
+from collections.abc import Iterator
+from contextlib import contextmanager
 from typing import TYPE_CHECKING, NoReturn, cast
 
 import grpc
+from sqlalchemy.orm import Session
 
-from couchers import experimentation
+from couchers import experimentation, urls
+from couchers.base_url_override import get_active_base_url_override
+from couchers.config import config
 from couchers.i18n import LocalizationContext
 
 if TYPE_CHECKING:
@@ -204,6 +209,27 @@ def _get_growthbook(self) -> GrowthBook:
             self._growthbook = experimentation._create_evaluator(self._user_id)
         return self._growthbook
 
+    @contextmanager
+    def use_base_url_override(self, session: Session) -> Iterator[None]:
+        """
+        Point links built via couchers.urls at this context's user's active base url override (if any) for the
+        duration of the block. Gated by ENABLE_DEV_APIS, so it's a no-op in real prod. See
+        couchers.base_url_override.
+        """
+        override = None
+        if config["ENABLE_DEV_APIS"] and self._user_id is not None:
+            override = get_active_base_url_override(session, self._user_id)
+
+        if not override:
+            yield
+            return
+
+        token = urls.base_url_override.set(override)
+        try:
+            yield
+        finally:
+            urls.base_url_override.reset(token)
+
 
 def make_interactive_context(
     grpc_context: grpc.ServicerContext,

app/backend/src/couchers/interceptors.py

@@ -19,7 +19,6 @@
 from sqlalchemy import Function, literal_column, select
 from sqlalchemy.sql import and_, func
 
-from couchers.base_url_override import use_base_url_override_for_user
 from couchers.constants import (
     CALL_CANCELLED_ERROR_MESSAGE,
     COOKIES_AND_AUTH_HEADER_ERROR_MESSAGE,
@@ -319,7 +318,7 @@ def function_without_couchers_stuff(req: Message, grpc_context: grpc.ServicerCon
 
             with session_scope() as session:
                 try:
-                    with use_base_url_override_for_user(session, auth_info.user_id if auth_info else None):
+                    with couchers_context.use_base_url_override(session):
                         _res = prev_function(req, couchers_context, session)  # type: ignore[call-arg, arg-type]
                     res = cast(Message, _res)
                     finished = perf_counter_ns()

app/backend/src/couchers/migrations/versions/0158_add_base_url_overrides.py

@@ -26,9 +26,9 @@ def upgrade() -> None:
         sa.ForeignKeyConstraint(["user_id"], ["users.id"], name=op.f("fk_base_url_overrides_user_id_users")),
         sa.PrimaryKeyConstraint("id", name=op.f("pk_base_url_overrides")),
     )
-    op.create_index(op.f("ix_base_url_overrides_user_id"), "base_url_overrides", ["user_id"], unique=False)
+    op.create_index("ix_base_url_overrides_active", "base_url_overrides", ["user_id", "created"], unique=False)
 
 
 def downgrade() -> None:
-    op.drop_index(op.f("ix_base_url_overrides_user_id"), table_name="base_url_overrides")
+    op.drop_index("ix_base_url_overrides_active", table_name="base_url_overrides")
     op.drop_table("base_url_overrides")

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

@@ -626,10 +626,14 @@ class BaseUrlOverride(Base, kw_only=True):
     id: Mapped[int] = mapped_column(BigInteger, primary_key=True, init=False)
     created: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), init=False)
 
-    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
 
-    # the base url to use, e.g. "https://my-preview.vercel.app". Empty string clears the override (records that
-    # the user explicitly went back to the configured BASE_URL).
+    # the base url to use, e.g. "https://my-preview.vercel.app"
     base_url: Mapped[str] = mapped_column(String)
 
     user: Mapped[User] = relationship(init=False)
+
+    __table_args__ = (
+        # serves the active-override lookup: filter by user_id, range on created, ordered by created desc
+        Index("ix_base_url_overrides_active", user_id, created),
+    )

app/backend/src/couchers/notifications/background.py

@@ -6,7 +6,6 @@
 from sqlalchemy.orm import Session
 from sqlalchemy.sql import exists, func
 
-from couchers.base_url_override import use_base_url_override_for_user
 from couchers.config import config
 from couchers.context import make_background_user_context
 from couchers.db import session_scope
@@ -133,7 +132,7 @@ def handle_notification(payload: jobs_pb2.HandleNotificationPayload) -> None:
                     )
                 )
                 session.flush()
-                with use_base_url_override_for_user(session, user.id):
+                with make_background_user_context(user.id).use_base_url_override(session):
                     _send_email_notification(session, user, notification)
             elif delivery_type == NotificationDeliveryType.digest:
                 # for digest notifications, add to digest queue
@@ -154,7 +153,7 @@ def handle_notification(payload: jobs_pb2.HandleNotificationPayload) -> None:
                     )
                 )
                 session.flush()
-                with use_base_url_override_for_user(session, user.id):
+                with make_background_user_context(user.id).use_base_url_override(session):
                     _send_push_notification(session, user, notification)
 
 

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

@@ -358,6 +358,9 @@ def SetBaseUrlOverride(
         if not config["ENABLE_DEV_APIS"]:
             context.abort_with_error_code(grpc.StatusCode.UNAVAILABLE, "dev_apis_disabled")
 
+        if not request.base_url:
+            context.abort(grpc.StatusCode.INVALID_ARGUMENT, "base_url must not be empty")
+
         session.add(BaseUrlOverride(user_id=context.user_id, base_url=request.base_url))
         return empty_pb2.Empty()
 
@@ -377,14 +380,9 @@ def GetBaseUrlOverrides(
             .all()
         )
 
-        # The active override is the most recent row within the TTL, and only if it's non-empty (an empty
-        # base_url is an explicit clear). This mirrors base_url_override.get_active_base_url_override.
+        # The active override is the most recent row within the TTL. Mirrors get_active_base_url_override.
         cutoff = now() - BASE_URL_OVERRIDE_TTL
-        active_id = None
-        for override in overrides:
-            if override.created > cutoff:
-                active_id = override.id if override.base_url else None
-                break
+        active_id = next((o.id for o in overrides if o.created > cutoff), None)
 
         return notifications_pb2.GetBaseUrlOverridesRes(
             overrides=[

app/backend/src/tests/test_notifications.py

@@ -14,11 +14,10 @@
 from couchers.base_url_override import (
     BASE_URL_OVERRIDE_TTL,
     get_active_base_url_override,
-    use_base_url_override_for_user,
 )
 from couchers.config import config
 from couchers.constants import DATETIME_INFINITY
-from couchers.context import make_background_user_context
+from couchers.context import make_background_user_context, make_logged_out_context
 from couchers.crypto import b64decode
 from couchers.db import session_scope
 from couchers.i18n import LocalizationContext
@@ -1940,40 +1939,34 @@ def test_get_active_base_url_override(db):
         session.flush()
         assert get_active_base_url_override(session, user.id) == "https://b.example"
 
-        # an empty base_url is an explicit clear
-        session.add(BaseUrlOverride(user_id=user.id, base_url=""))
-        session.flush()
-        assert get_active_base_url_override(session, user.id) is None
-
-        # an expired override is ignored
-        expired = BaseUrlOverride(user_id=user.id, base_url="https://c.example")
-        session.add(expired)
-        session.flush()
+        # expired overrides are ignored
         session.execute(
             update(BaseUrlOverride)
-            .where(BaseUrlOverride.id == expired.id)
+            .where(BaseUrlOverride.user_id == user.id)
             .values(created=now() - BASE_URL_OVERRIDE_TTL - timedelta(minutes=1))
         )
         assert get_active_base_url_override(session, user.id) is None
 
 
-def test_use_base_url_override_for_user(db):
+def test_context_use_base_url_override(db):
     user, _ = generate_user()
     with session_scope() as session:
         session.add(BaseUrlOverride(user_id=user.id, base_url="https://preview.example.org"))
         session.flush()
 
+        context = make_background_user_context(user.id)
+
         # inert unless dev APIs are enabled
-        with use_base_url_override_for_user(session, user.id):
+        with context.use_base_url_override(session):
             assert urls.base_url() == config["BASE_URL"]
 
         with patch.dict(config, {"ENABLE_DEV_APIS": True}):
-            with use_base_url_override_for_user(session, user.id):
+            with context.use_base_url_override(session):
                 assert urls.base_url() == "https://preview.example.org"
             # restored on exit
             assert urls.base_url() == config["BASE_URL"]
-            # a missing user is a no-op
-            with use_base_url_override_for_user(session, None):
+            # a logged-out context is a no-op
+            with make_logged_out_context(LocalizationContext.en_utc()).use_base_url_override(session):
                 assert urls.base_url() == config["BASE_URL"]
 
 
@@ -1991,17 +1984,13 @@ def test_SetBaseUrlOverride_and_GetBaseUrlOverrides(db):
     assert res.overrides[1].active is False
 
 
-def test_SetBaseUrlOverride_clear(db):
+def test_SetBaseUrlOverride_rejects_empty(db):
     user, token = generate_user()
     with patch.dict(config, {"ENABLE_DEV_APIS": True}):
         with notifications_session(token) as notifications:
-            notifications.SetBaseUrlOverride(notifications_pb2.SetBaseUrlOverrideReq(base_url="https://a.example"))
-            notifications.SetBaseUrlOverride(notifications_pb2.SetBaseUrlOverrideReq(base_url=""))
-            res = notifications.GetBaseUrlOverrides(empty_pb2.Empty())
-
-    # clearing records a row but nothing is active
-    assert [o.base_url for o in res.overrides] == ["", "https://a.example"]
-    assert all(not o.active for o in res.overrides)
+            with pytest.raises(grpc.RpcError) as e:
+                notifications.SetBaseUrlOverride(notifications_pb2.SetBaseUrlOverrideReq(base_url=""))
+    assert e.value.code() == grpc.StatusCode.INVALID_ARGUMENT
 
 
 def test_SetBaseUrlOverride_dev_apis_disabled(db):

app/proto/notifications.proto

@@ -185,8 +185,8 @@ message DebugRedeliverPushNotificationReq {
 }
 
 message SetBaseUrlOverrideReq {
-  // the base url to point generated links at, e.g. "https://my-preview.vercel.app".
-  // An empty string clears the override (links go back to the configured BASE_URL).
+  // the base url to point generated links at, e.g. "https://my-preview.vercel.app". Must be non-empty; the
+  // override applies for ~15 min, after which links go back to the configured BASE_URL.
   string base_url = 1;
 }