Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

fix(db): bind a tenant per unit of background work, not per task (CHOO-2623)

Wojciech Wojtyniak417f922217df
diff --git a/core/switch_core/bridges/agent/protocol/service.py b/core/switch_core/bridges/agent/protocol/service.py
index 86cfa2067..3695760eb 100644
--- a/core/switch_core/bridges/agent/protocol/service.py
+++ b/core/switch_core/bridges/agent/protocol/service.py
@@ -72,7 +72,7 @@ from switch_core.db.models import (
Tool,
User,
)
-from switch_core.db.session_scope import tenant_session, unscoped_session
+from switch_core.db.session_scope import unscoped_session
from switch_core.db.stores.agent_runtime_state_store import (
IDLE as RUNTIME_STATE_IDLE,
)
@@ -475,7 +475,12 @@ class ProtocolService:
the source of truth, that guess would confirm itself forever.
"""
token_hash = hashlib.sha256(registration_token.encode()).hexdigest()
- async with self.session_factory() as session:
+ # Resolving a credential is unscoped by definition — `key_hash` is one
+ # of the two columns deliberately left globally unique for exactly
+ # this reason — and it is the read that *produces* the tenant bound
+ # below. Answering it under a tenant would make it either a tautology
+ # or a false "invalid token".
+ async with unscoped_session(self.session_factory) as session:
key = await self.api_key_store.get_by_hash(session, token_hash)
if key is None or key.type not in REGISTRATION_KEY_TYPES:
raise PermissionError("Invalid registration token")
@@ -1564,39 +1569,52 @@ class ProtocolService:
"""
# This sweep spans every tenant by nature — it is the one place that
# decides whether *any* stale row anywhere needs resetting — so the
- # initial read is unscoped. Each row is itself tenant-scoped
- # (agent_runtime_states carries tenant_id), so the rest of the work
- # for that row binds its own tenant rather than the whole sweep, and
- # a row from one tenant can never leak its binding into the next.
+ # initial read is unscoped. Everything done *with* a row then happens
+ # inside that row's own tenant, including the emit at the end: the
+ # clear event goes out to a bridge, which resolves a mention handle
+ # and posts a message, and those are writes in the row's tenant like
+ # any other. Closing the binding after the upsert and leaving the tail
+ # outside it would put exactly the visible half of the work back on
+ # whatever was ambient.
async with unscoped_session(self.session_factory) as session:
rows = await self.agent_runtime_state_store.get_active(session)
for row in rows:
if self.connections.has_session_in(row.agent_id, row.room_id):
continue
- async with tenant_session(self.session_factory, row.tenant_id) as session:
- live = await self.agent_session_store.get_live_agent_ids(
- session, [row.agent_id], row.room_id
- )
- if row.agent_id in live:
- continue
- async with tenant_session(self.session_factory, row.tenant_id) as session:
- agent = await self.agent_store.get(session, row.agent_id)
- room = await self.room_store.get(session, row.room_id)
- if agent is None or room is None:
- continue
- await self.agent_runtime_state_store.upsert(
- session, row.agent_id, row.room_id, RUNTIME_STATE_IDLE
- )
- await session.commit()
- await self._emit_runtime_state(
- agent_id=agent.id,
- agent_name=agent.name,
- matrix_room_id=room.matrix_room_id,
- room_id=room.id,
- state=RUNTIME_STATE_IDLE,
- mention_handle=await self._mention_handle_for(agent, room.bridge_id),
- thread_id=None,
+ with tenant_scope(row.tenant_id):
+ await self._sweep_one_runtime_state(row.agent_id, row.room_id)
+
+ async def _sweep_one_runtime_state(self, agent_id: str, room_id: str) -> None:
+ """One stale row's worth of the sweep, under its tenant.
+
+ Split out so the binding is the whole body rather than a prefix of it:
+ an early `return` here cannot accidentally leave later work outside
+ the scope the way an early `continue` in the loop could.
+ """
+ async with self.session_factory() as session:
+ live = await self.agent_session_store.get_live_agent_ids(
+ session, [agent_id], room_id
)
+ if agent_id in live:
+ return
+ async with self.session_factory() as session:
+ agent = await self.agent_store.get(session, agent_id)
+ room = await self.room_store.get(session, room_id)
+ if agent is None or room is None:
+ return
+ await self.agent_runtime_state_store.upsert(
+ session, agent_id, room_id, RUNTIME_STATE_IDLE
+ )
+ await session.commit()
+ await self._emit_runtime_state(
+ agent_id=agent.id,
+ agent_name=agent.name,
+ matrix_room_id=room.matrix_room_id,
+ room_id=room.id,
+ state=RUNTIME_STATE_IDLE,
+ mention_handle=await self._mention_handle_for(agent, room.bridge_id),
+ thread_id=None,
+ )
async def _mention_handle_for(
self, agent: Agent, bridge_id: str | None
diff --git a/core/switch_core/bridges/agent/server_connectors/core.py b/core/switch_core/bridges/agent/server_connectors/core.py
index 24bcb132c..7746b1855 100644
--- a/core/switch_core/bridges/agent/server_connectors/core.py
+++ b/core/switch_core/bridges/agent/server_connectors/core.py
@@ -20,6 +20,7 @@ from switch_core.bridges.agent.server_connectors.base import (
DiscoveredAgent,
ServerSideConnector,
)
+from switch_core.tenant_context import no_tenant, tenant_scope
if TYPE_CHECKING:
from switch_core.bridges.agent.protocol.service import ProtocolService
@@ -78,12 +79,17 @@ class ConnectorCore:
self,
*,
connector_id: str,
+ connector_tenant_id: str,
connector_type: str,
connector: ServerSideConnector,
registration_token: str,
protocol: ProtocolService,
) -> None:
self._connector_id = connector_id
+ # The tenant of the connector's own row. Held, never bound for the
+ # life of anything: each poll and each event it produces binds it for
+ # that piece of work and releases it again.
+ self._connector_tenant_id = connector_tenant_id
self._connector_type = connector_type
self._connector = connector
self._registration_token = registration_token
@@ -133,29 +139,30 @@ class ConnectorCore:
# ── internal ─────────────────────────────────────────────────────────
async def _register_agent(self, agent: DiscoveredAgent) -> None:
- # Runs from `start()`, which the caller wraps in the connector's own
- # tenant (ServerSideConnectorLifecycleService.start_all binds it
- # before starting each connector's task; an admin registering one
- # over HTTP already has it bound). register_agent_with_token
- # additionally binds the registration token's own tenant for the
- # write itself — the same tenant either way — see its docstring.
+ # Registering one agent is one unit of work for this connector's row,
+ # so it binds that row's tenant here rather than inheriting anything.
+ # `register_agent_with_token` additionally binds the registration
+ # token's own tenant for the write itself — the same tenant either
+ # way — see its docstring.
try:
- result = await self._protocol.register_agent_with_token(
- registration_token=self._registration_token,
- name=agent.name,
- description=agent.description,
- connector_type=f"server-side:{self._connector_type}",
- integration_profile=agent.integration_profile,
- tools=agent.tools,
- models=agent.models,
- metadata={"server_connector_id": self._connector_id},
- overwrite=True,
- # A server-side connector agent is a service the deployment
- # offers everyone, not one person's assistant; it is owned by
- # whoever holds the registration token only in the bookkeeping
- # sense. Owner-only would make it answer to that account alone.
- owner_only=False,
- )
+ with tenant_scope(self._connector_tenant_id):
+ result = await self._protocol.register_agent_with_token(
+ registration_token=self._registration_token,
+ name=agent.name,
+ description=agent.description,
+ connector_type=f"server-side:{self._connector_type}",
+ integration_profile=agent.integration_profile,
+ tools=agent.tools,
+ models=agent.models,
+ metadata={"server_connector_id": self._connector_id},
+ overwrite=True,
+ # A server-side connector agent is a service the
+ # deployment offers everyone, not one person's assistant;
+ # it is owned by whoever holds the registration token only
+ # in the bookkeeping sense. Owner-only would make it
+ # answer to that account alone.
+ owner_only=False,
+ )
except Exception:
logger.exception(
"Failed to register agent %s from connector %s",
@@ -178,42 +185,56 @@ class ConnectorCore:
return _ProtocolReporter(self._protocol, handle)
async def _poll_loop(self, handle: _AgentHandle) -> None:
+ """One agent's long-poll loop.
+
+ `no_tenant` around the loop and `tenant_scope` around each pass: the
+ loop itself is a task and owns no tenant, while one poll and the
+ events it returns are one unit of work for this connector's row. The
+ binding is taken and released per pass, so a loop that has been
+ running for days is in exactly the same state as one that just
+ started.
+ """
logger.info(
"Starting poll loop for agent %s (%s)",
handle.agent_name,
handle.agent_id,
)
- while True:
- try:
- events = await self._protocol.poll_events(
- handle.agent_id, timeout=CONNECTOR_POLL_TIMEOUT_SECONDS
- )
- for event in events:
- payload = event.payload
-
- if isinstance(payload, MessagePayload):
- await self._handle_message(handle, event.room_id, payload)
- elif isinstance(payload, CommandPayload):
- await self._handle_command(handle, event.room_id, payload)
- elif isinstance(payload, TaskDelegatePayload):
- await self._handle_task_delegate(handle, event.room_id, payload)
- elif isinstance(payload, TaskUpdatePayload):
- await self._handle_task_update(handle, event.room_id, payload)
- elif isinstance(payload, TaskFinalisePayload):
- await self._handle_task_finalise(handle, event.room_id, payload)
- elif isinstance(payload, TaskCancelPayload):
- await self._handle_task_cancel(handle, event.room_id, payload)
- except asyncio.CancelledError:
- logger.info("Poll loop cancelled for agent %s", handle.agent_name)
- return
- except Exception:
- logger.exception(
- "Error in poll loop for agent %s (%s)",
- handle.agent_name,
- handle.agent_id,
- )
- await asyncio.sleep(5)
+ with no_tenant():
+ while True:
+ try:
+ with tenant_scope(self._connector_tenant_id):
+ await self._poll_once(handle)
+ except asyncio.CancelledError:
+ logger.info("Poll loop cancelled for agent %s", handle.agent_name)
+ return
+ except Exception:
+ logger.exception(
+ "Error in poll loop for agent %s (%s)",
+ handle.agent_name,
+ handle.agent_id,
+ )
+ await asyncio.sleep(5)
+
+ async def _poll_once(self, handle: _AgentHandle) -> None:
+ events = await self._protocol.poll_events(
+ handle.agent_id, timeout=CONNECTOR_POLL_TIMEOUT_SECONDS
+ )
+ for event in events:
+ payload = event.payload
+
+ if isinstance(payload, MessagePayload):
+ await self._handle_message(handle, event.room_id, payload)
+ elif isinstance(payload, CommandPayload):
+ await self._handle_command(handle, event.room_id, payload)
+ elif isinstance(payload, TaskDelegatePayload):
+ await self._handle_task_delegate(handle, event.room_id, payload)
+ elif isinstance(payload, TaskUpdatePayload):
+ await self._handle_task_update(handle, event.room_id, payload)
+ elif isinstance(payload, TaskFinalisePayload):
+ await self._handle_task_finalise(handle, event.room_id, payload)
+ elif isinstance(payload, TaskCancelPayload):
+ await self._handle_task_cancel(handle, event.room_id, payload)
async def _handle_message(
self,
diff --git a/core/switch_core/bridges/agent/server_connectors/lifecycle.py b/core/switch_core/bridges/agent/server_connectors/lifecycle.py
index 1297c99e9..8b1d804f3 100644
--- a/core/switch_core/bridges/agent/server_connectors/lifecycle.py
+++ b/core/switch_core/bridges/agent/server_connectors/lifecycle.py
@@ -17,7 +17,6 @@ from switch_core.db.models import ApiKey, ServerConnector
from switch_core.db.session_scope import unscoped_session
from switch_core.db.stores.api_key_store import ApiKeyStore
from switch_core.db.stores.server_connector_store import ServerConnectorStore
-from switch_core.tenant_context import tenant_scope
logger = logging.getLogger(__name__)
@@ -54,17 +53,16 @@ class ServerSideConnectorLifecycleService:
async def start_all(self) -> None:
# Every tenant's active connectors in one pass — unscoped by nature,
# same reasoning as CollaborationBridgeLifecycleService.start_all.
- # Each row carries its own tenant; bind it only around starting that
- # one connector, and the poll loop `start` spawns keeps it for that
- # task's own life via the context asyncio.create_task snapshots.
+ # Nothing is bound around `start`: it reads the connector's own row
+ # and hands that row's tenant to the core, which binds it per unit of
+ # work rather than once for the poll loop's life.
async with unscoped_session(self._session_factory) as session:
connectors = await self._connector_store.get_active(session)
logger.info("Starting %d server-side connectors", len(connectors))
for record in connectors:
try:
- with tenant_scope(record.tenant_id):
- await self.start(record.id)
+ await self.start(record.id)
except Exception:
logger.exception("Failed to start connector %s", record.id)
@@ -118,7 +116,10 @@ class ServerSideConnectorLifecycleService:
return record
async def start(self, connector_id: str) -> None:
- async with self._session_factory() as session:
+ # Unscoped: the read that answers which tenant this connector is in,
+ # reached both from boot with nothing bound and from an HTTP request
+ # whose tenant is the caller's, not necessarily the connector's.
+ async with unscoped_session(self._session_factory) as session:
record = await self._connector_store.get(session, connector_id)
if record is None:
raise ValueError(f"Connector not found: {connector_id}")
@@ -140,6 +141,7 @@ class ServerSideConnectorLifecycleService:
core = ConnectorCore(
connector_id=connector_id,
+ connector_tenant_id=record.tenant_id,
connector_type=record.type,
connector=connector,
registration_token=registration_token,
diff --git a/core/switch_core/bridges/collaboration/bridge_core.py b/core/switch_core/bridges/collaboration/bridge_core.py
index 8c8cd7c01..6a563eb6e 100644
--- a/core/switch_core/bridges/collaboration/bridge_core.py
+++ b/core/switch_core/bridges/collaboration/bridge_core.py
@@ -30,7 +30,7 @@ from switch_core.clients.admin_messages import ADMIN_MARKER, AdminMessageType
from switch_core.clients.client_base import ClientBase, ClientConfig
from switch_core.clients.mentions import mention_regex, strip_emphasis
from switch_core.db.models import BridgeMessageMap, ExternalUser
-from switch_core.db.session_scope import tenant_session
+from switch_core.db.session_scope import tenant_session, unscoped_session
from switch_core.db.stores.agent_store import AgentStore
from switch_core.db.stores.bridge_message_map_store import BridgeMessageMapStore
from switch_core.db.stores.client_store import ClientStore
@@ -40,7 +40,7 @@ from switch_core.events import AgentRuntimeStateEvent
from switch_core.logging_context import log_context
from switch_core.provisioning import Provisioning
from switch_core.room_service import RoomCreateConfig
-from switch_core.tenant_context import tenant_scope
+from switch_core.tenant_context import no_tenant, tenant_scope
from switch_core.transport import (
InboundMedia as TransportMedia,
)
@@ -122,6 +122,7 @@ class BridgeCore:
self,
*,
bridge_id: str,
+ bridge_tenant_id: str,
bridge_type: str,
bridge_display_name: str,
adapter: CollaborationAdapter,
@@ -139,6 +140,14 @@ class BridgeCore:
max_attachment_bytes: int,
) -> None:
self._bridge_id = bridge_id
+ # The tenant of this bridge's own row. Read once here because it is
+ # immutable, but never *bound* for the life of anything: each unit of
+ # work binds it at the point it acts, and room-scoped work binds the
+ # room's tenant instead. The schema makes those the same value —
+ # `rooms` has a composite foreign key to `collaboration_bridges` on
+ # `tenant_id` — but the code does not lean on that, so a room whose
+ # tenant somehow differs is still handled under its own.
+ self._bridge_tenant_id = bridge_tenant_id
self._bridge_type = bridge_type
self._bridge_display_name = bridge_display_name
self._adapter = adapter
@@ -157,12 +166,10 @@ class BridgeCore:
self._channel_to_room: dict[str, tuple[str, str]] = {}
self._room_to_channel: dict[tuple[str, str], str] = {}
- # Switch room id -> its tenant, populated wherever a room is looked
- # up or created. A room's tenant is as immutable as its channel
- # mapping, unlike this bridge's own — a bridge can in principle carry
- # rooms in more than one tenant over time — so each unit of work
- # binds the room it is actually for rather than one tenant cached for
- # the whole bridge. See `_room_tenant`.
+ # Switch room id -> its tenant. Filled by `add_room_mapping`, which is
+ # the one way a room enters the channel maps at all, so a room that
+ # has a channel mapping always has a tenant here — including rooms
+ # created long after this bridge started. See `_room_tenant`.
self._room_tenants: dict[str, str] = {}
self._user_puppets: dict[str, str] = {}
# External user ids whose stored name is known not to be a platform id,
@@ -210,7 +217,7 @@ class BridgeCore:
self, handler: Callable[[_InboundEventT], Awaitable[None]]
) -> Callable[[_InboundEventT], Awaitable[None]]:
"""Give each inbound platform event its own id in the logs, and bind
- the tenant of the room it is for, when that room already exists.
+ the tenant the event belongs to.
An event fans out across room lookup, identity provisioning and the
transport, so without this the lines from two events arriving at once
@@ -219,21 +226,32 @@ class BridgeCore:
choke point is where the tenant is bound, so a handler needs no
session-opening call site of its own to remember it.
- A channel with no room yet (auto-room-creation, still to come in the
- handler) binds nothing here: which tenant a *new* room lands in is an
- ambient decision, the same as any other creation, not something this
- wrapper can derive from a room that does not exist.
+ This is what makes the platform irrelevant. An adapter is free to
+ deliver from anywhere: Mattermost's websocket runs on an OS thread and
+ hands the coroutine over with `asyncio.run_coroutine_threadsafe`,
+ which starts it in an *empty* context, while Slack's dispatches from a
+ task that inherited whatever created it. Binding here rather than
+ relying on what the handler inherits means both arrive at the same
+ tenant, so which platform a message came in on stops being able to
+ decide where its room lands.
+
+ A channel with no room yet — auto-room-creation, still to come in the
+ handler — binds the **bridge's** tenant. There is no room to ask, but
+ there is nothing ambient about the answer either: a room this bridge
+ creates belongs to the tenant that owns the bridge, and the schema
+ agrees (`rooms` keys to `collaboration_bridges` on `tenant_id`).
"""
async def traced(event: _InboundEventT) -> None:
event_id = uuid.uuid4().hex[:16]
with log_context(request_id=f"{self._bridge_type}-{event_id}"):
room_ids = self._channel_to_room.get(event.channel_id)
- if room_ids is None:
- await handler(event)
- return
- room_id, _ = room_ids
- with tenant_scope(await self._room_tenant(room_id)):
+ tenant_id = (
+ self._bridge_tenant_id
+ if room_ids is None
+ else await self._room_tenant(room_ids[0])
+ )
+ with tenant_scope(tenant_id):
await handler(event)
return traced
@@ -268,14 +286,18 @@ class BridgeCore:
# ── Startup loading ──────────────────────────────────────────────────────
async def _load_channel_map(self) -> None:
- async with self._session_factory() as session:
+ async with tenant_session(
+ self._session_factory, self._bridge_tenant_id
+ ) as session:
rooms = await self._room_store.get_by_bridge(session, self._bridge_id)
for room in rooms:
- self._room_tenants[room.id] = room.tenant_id
if room.external_channel_id:
- key = (room.id, room.matrix_room_id)
- self._channel_to_room[room.external_channel_id] = key
- self._room_to_channel[key] = room.external_channel_id
+ self.add_room_mapping(
+ room.id,
+ room.matrix_room_id,
+ room.external_channel_id,
+ room.tenant_id,
+ )
async def _room_tenant(self, room_id: str) -> str:
"""The tenant `room_id` belongs to, resolved and cached.
@@ -285,11 +307,19 @@ class BridgeCore:
tenant, only on a given room's tenant never changing once it exists —
the same invariant `_channel_to_room` already relies on for the
channel mapping.
+
+ A miss should not happen — `add_room_mapping` fills the tenant along
+ with the channel mapping, and this is only ever asked about a room
+ that has one — but if it does, the read is deliberately **unscoped**.
+ Asking "which tenant is this room in" while a tenant is bound would
+ either confirm the guess or return nothing, and the second reads as
+ "no such room" for a room that exists in another tenant. The whole
+ point of resolving is that the answer is not known yet.
"""
cached = self._room_tenants.get(room_id)
if cached is not None:
return cached
- async with self._session_factory() as session:
+ async with unscoped_session(self._session_factory) as session:
room = await self._room_store.get(session, room_id)
if room is None:
raise ValueError(f"Room not found: {room_id}")
@@ -297,7 +327,9 @@ class BridgeCore:
return room.tenant_id
async def _load_existing_puppets(self) -> None:
- async with self._session_factory() as session:
+ async with tenant_session(
+ self._session_factory, self._bridge_tenant_id
+ ) as session:
users = await self._external_user_store.get_by_bridge(
session, self._bridge_id
)
@@ -327,7 +359,15 @@ class BridgeCore:
A bare create_task swallows whatever the coroutine raises, so anything
escaping the per-agent handling below would vanish without trace.
- Cancellation is ordinary shutdown and says so quietly."""
+ Cancellation is ordinary shutdown and says so quietly.
+
+ `no_tenant` for the same reason the bridge's own task does it: this is
+ a task, and a task keeps whatever context created it. The work inside
+ binds the bridge's tenant for itself."""
+ with no_tenant():
+ await self._run_agent_identities_unbound()
+
+ async def _run_agent_identities_unbound(self) -> None:
try:
await self._create_agent_identities()
except asyncio.CancelledError:
@@ -342,7 +382,9 @@ class BridgeCore:
)
async def _create_agent_identities(self) -> None:
- async with self._session_factory() as session:
+ async with tenant_session(
+ self._session_factory, self._bridge_tenant_id
+ ) as session:
agents = await self._agent_store.get_all(session)
failed = 0
@@ -381,7 +423,9 @@ class BridgeCore:
bridge's channels. Runs on startup so capture self-heals after a restart
or a notification-URL change (e.g. a rotated tunnel). A no-op for
adapters that don't use expiring subscriptions."""
- async with self._session_factory() as session:
+ async with tenant_session(
+ self._session_factory, self._bridge_tenant_id
+ ) as session:
rooms = await self._room_store.get_by_bridge(session, self._bridge_id)
channels: list[tuple[str, str]] = []
for room in rooms:
@@ -401,8 +445,16 @@ class BridgeCore:
know whether to override what it already has. Either field being None
within a hit means the same thing one field down: the agent was given
no value, and the adapter's default stands.
+
+ Installed on the adapter, so it is called from the adapter's own task
+ with nothing bound rather than through `_traced` — hence the explicit
+ bind. Agent names are unique per tenant, not globally, so an unscoped
+ read here would raise `MultipleResultsFound` the day a second tenant
+ has an agent of the same name.
"""
- async with self._session_factory() as session:
+ async with tenant_session(
+ self._session_factory, self._bridge_tenant_id
+ ) as session:
agent = await self._agent_store.get_by_name(session, agent_name)
if agent is None:
return None
@@ -827,7 +879,12 @@ class BridgeCore:
"""
lock = self._channel_locks.setdefault(old_id, asyncio.Lock())
async with lock:
- async with self._session_factory() as session:
+ # Reached from the adapter's own task rather than through
+ # `_traced`, so nothing is bound: this is one unit of work for one
+ # bridge, and it binds that bridge's tenant to find its room.
+ async with tenant_session(
+ self._session_factory, self._bridge_tenant_id
+ ) as session:
room = await self._room_store.get_by_external_channel(
session, self._bridge_id, old_id
)
@@ -860,10 +917,8 @@ class BridgeCore:
await self._room_store.update_external_channel(session, room.id, new_id)
await session.commit()
- key = (room.id, room.matrix_room_id)
self._channel_to_room.pop(old_id, None)
- self._channel_to_room[new_id] = key
- self._room_to_channel[key] = new_id
+ self.add_room_mapping(room.id, room.matrix_room_id, new_id, room.tenant_id)
logger.warning(
"Re-pointed room %s from channel %s to %s after the platform "
"reissued the id",
@@ -884,14 +939,15 @@ class BridgeCore:
"""If a room already exists in the DB for this channel on this bridge,
register it in the in-memory map and return its (room_id,
matrix_room_id). Returns None if no such room exists. Idempotent."""
- async with self._session_factory() as session:
+ async with tenant_session(
+ self._session_factory, self._bridge_tenant_id
+ ) as session:
room = await self._room_store.get_by_external_channel(
session, self._bridge_id, channel_id
)
if room is None:
return None
- self._room_tenants[room.id] = room.tenant_id
- self.add_room_mapping(room.id, room.matrix_room_id, channel_id)
+ self.add_room_mapping(room.id, room.matrix_room_id, channel_id, room.tenant_id)
logger.debug("Adopted existing room %s for channel %s", room.id, channel_id)
return (room.id, room.matrix_room_id)
@@ -967,8 +1023,7 @@ class BridgeCore:
return None
room = result.room
- self._room_tenants[room.id] = room.tenant_id
- self.add_room_mapping(room.id, room.matrix_room_id, channel_id)
+ self.add_room_mapping(room.id, room.matrix_room_id, channel_id, room.tenant_id)
logger.info(
"Auto-created %s room %s for %s channel %s",
channel_type,
@@ -1259,61 +1314,77 @@ class BridgeCore:
async def _create_puppet(
self, external_user_id: str, external_username: str
) -> str:
+ """Mint the Matrix identity that stands in for a person on the platform.
+
+ Bound to the **bridge's** tenant, not to whatever room the message
+ that triggered it arrived in. A puppet is per-bridge and outlives that
+ message: the same client is reused for every room this person speaks
+ in, so a client row stamped with the first room's tenant would be
+ wrong for the second — and the client task it starts must not carry
+ that tenant either, which is why `ClientLifecycleService` unbinds
+ before running one.
+ """
lock = self._puppet_locks.setdefault(external_user_id, asyncio.Lock())
async with lock:
- existing = self._user_puppets.get(external_user_id)
- if existing is not None:
- return existing
-
- # Defence in depth against agent/user misdetection: a
- # bridged agent must never be puppeted as an external user. If the
- # name collides with a registered Switch agent, refuse loudly rather
- # than create a duplicate "user" identity for it.
- async with self._session_factory() as session:
- agent = await self._agent_store.get_by_name(session, external_username)
- if agent is not None:
- raise ValueError(
- f"Refusing to create external-user puppet for '{external_username}'"
- " on bridge "
- f"{self._bridge_id}: name collides with a registered Switch agent"
- " (likely a bridged agent bot misclassified as a user)"
+ with tenant_scope(self._bridge_tenant_id):
+ return await self._create_puppet_locked(
+ external_user_id, external_username
)
- sanitized = re.sub(r"[^a-z0-9_-]", "-", external_username.lower()).strip(
- "-"
- )
- # Scope to the bridge: the same username on two bridges of the same
- # type (e.g. two Slack workspaces) must map to distinct Matrix users,
- # since matrix_user_id is globally unique but usernames are not.
- localpart = f"switch-{self._bridge_type}-{self._bridge_id}-{sanitized}"
+ async def _create_puppet_locked(
+ self, external_user_id: str, external_username: str
+ ) -> str:
+ existing = self._user_puppets.get(external_user_id)
+ if existing is not None:
+ return existing
- client = await self._client_lifecycle.create_and_start(
- client_type="user",
- display_name=external_username,
- localpart=localpart,
- )
+ # Defence in depth against agent/user misdetection: a
+ # bridged agent must never be puppeted as an external user. If the
+ # name collides with a registered Switch agent, refuse loudly rather
+ # than create a duplicate "user" identity for it.
+ async with self._session_factory() as session:
+ agent = await self._agent_store.get_by_name(session, external_username)
+ if agent is not None:
+ raise ValueError(
+ f"Refusing to create external-user puppet for '{external_username}'"
+ " on bridge "
+ f"{self._bridge_id}: name collides with a registered Switch agent"
+ " (likely a bridged agent bot misclassified as a user)"
+ )
+
+ sanitized = re.sub(r"[^a-z0-9_-]", "-", external_username.lower()).strip("-")
+ # Scope to the bridge: the same username on two bridges of the same
+ # type (e.g. two Slack workspaces) must map to distinct Matrix users,
+ # since matrix_user_id is globally unique but usernames are not.
+ localpart = f"switch-{self._bridge_type}-{self._bridge_id}-{sanitized}"
+
+ client = await self._client_lifecycle.create_and_start(
+ client_type="user",
+ display_name=external_username,
+ localpart=localpart,
+ )
- ext_user = ExternalUser(
- bridge_id=self._bridge_id,
- external_user_id=external_user_id,
- external_username=external_username,
- client_id=client.client_id,
- )
- async with self._session_factory() as session:
- await self._external_user_store.create(session, ext_user)
- await session.commit()
+ ext_user = ExternalUser(
+ bridge_id=self._bridge_id,
+ external_user_id=external_user_id,
+ external_username=external_username,
+ client_id=client.client_id,
+ )
+ async with self._session_factory() as session:
+ await self._external_user_store.create(session, ext_user)
+ await session.commit()
- self._user_puppets[external_user_id] = client.client_id
- self._puppet_matrix_ids.add(client.matrix_user_id)
- self._adapter.prime_mention_targets({external_username: external_user_id})
+ self._user_puppets[external_user_id] = client.client_id
+ self._puppet_matrix_ids.add(client.matrix_user_id)
+ self._adapter.prime_mention_targets({external_username: external_user_id})
- logger.info(
- "Created puppet %s for external user %s on bridge %s",
- client.matrix_user_id,
- external_user_id,
- self._bridge_id,
- )
- return client.client_id
+ logger.info(
+ "Created puppet %s for external user %s on bridge %s",
+ client.matrix_user_id,
+ external_user_id,
+ self._bridge_id,
+ )
+ return client.client_id
def _find_channel(
self, room_id: str | None = None, matrix_room_id: str | None = None
@@ -1966,14 +2037,29 @@ class BridgeCore:
self._provisioning_channels.discard(external_channel_id)
def add_room_mapping(
- self, room_id: str, matrix_room_id: str, external_channel_id: str
+ self,
+ room_id: str,
+ matrix_room_id: str,
+ external_channel_id: str,
+ tenant_id: str,
) -> None:
+ """Register a room↔channel mapping, and the room's tenant with it.
+
+ The tenant is a required argument rather than something looked up
+ later because every caller already has the room row in hand. Taking it
+ here is what lets `_traced` bind a tenant for a room created *after*
+ this bridge started without a database read on the inbound path — and,
+ more to the point, without a read that would run under whatever tenant
+ happened to be bound at the time.
+ """
key = (room_id, matrix_room_id)
self._channel_to_room[external_channel_id] = key
self._room_to_channel[key] = external_channel_id
+ self._room_tenants[room_id] = tenant_id
def remove_room_mapping(self, room_id: str, matrix_room_id: str) -> None:
key = (room_id, matrix_room_id)
channel_id = self._room_to_channel.pop(key, None)
if channel_id is not None:
self._channel_to_room.pop(channel_id, None)
+ self._room_tenants.pop(room_id, None)
diff --git a/core/switch_core/bridges/collaboration/lifecycle_service.py b/core/switch_core/bridges/collaboration/lifecycle_service.py
index 71269a52a..59d57888f 100644
--- a/core/switch_core/bridges/collaboration/lifecycle_service.py
+++ b/core/switch_core/bridges/collaboration/lifecycle_service.py
@@ -15,7 +15,7 @@ from switch_core.clients.bridge_client import BridgeClient, BridgeClientConfig
from switch_core.clients.client_factory import ClientFactory
from switch_core.config import SwitchConfig
from switch_core.db.models import CollaborationBridge
-from switch_core.db.session_scope import unscoped_session
+from switch_core.db.session_scope import tenant_session, unscoped_session
from switch_core.db.stores.agent_store import AgentStore
from switch_core.db.stores.bridge_message_map_store import BridgeMessageMapStore
from switch_core.db.stores.client_store import ClientStore
@@ -23,7 +23,7 @@ from switch_core.db.stores.collaboration_bridge_store import CollaborationBridge
from switch_core.db.stores.external_user_store import ExternalUserStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.provisioning import Provisioning
-from switch_core.tenant_context import tenant_scope
+from switch_core.tenant_context import no_tenant
if TYPE_CHECKING:
from switch_core.clients.client_lifecycle_service import ClientLifecycleService
@@ -191,20 +191,19 @@ class CollaborationBridgeLifecycleService:
async def start_all(self) -> None:
# Every tenant's active bridges in one pass, so the read is unscoped
- # by nature. Each row already carries its own tenant; bind that one
- # only around starting it, not the whole fan-out. `start` spawns the
- # bridge's long-lived task from inside this binding, and an asyncio
- # task snapshots the context it was created under, so the task keeps
- # this tenant for its own life without the loop needing to hold it
- # open past the moment the task exists.
+ # by nature. Nothing is bound around `start`: the bridge's tenant is
+ # read from its own row inside `start`, and bound by each unit of work
+ # that needs it. Binding here instead would only decide what the
+ # long-lived task snapshots, which is exactly what must not matter —
+ # `start` is also reached from an HTTP request, and a bridge cannot
+ # run under whichever tenant happened to restart it.
async with unscoped_session(self._session_factory) as session:
bridges = await self._bridge_store.get_active(session)
logger.info("Starting %d collaboration bridges", len(bridges))
for bridge in bridges:
try:
- with tenant_scope(bridge.tenant_id):
- await self.start(bridge.id)
+ await self.start(bridge.id)
except Exception:
logger.exception("Failed to start bridge %s", bridge.id)
@@ -227,7 +226,12 @@ class CollaborationBridgeLifecycleService:
if wanted is None:
return
- async with self._session_factory() as session:
+ # Deliberately across every tenant. Two tenants binding the same Slack
+ # workspace, or the same Teams listen port, is precisely the collision
+ # this exists to refuse — the resource is a property of the host and
+ # the platform, not of a tenant — so narrowing to the caller's tenant
+ # would make it miss the case it was written for.
+ async with unscoped_session(self._session_factory) as session:
existing = await self._bridge_store.get_all(session)
for other in existing:
# Guard the None case explicitly: an unflushed row has no id yet, and
@@ -344,10 +348,15 @@ class CollaborationBridgeLifecycleService:
return bridge
async def start(self, bridge_id: str) -> None:
- async with self._session_factory() as session:
+ # Unscoped: this is the read that answers which tenant the bridge is
+ # in, and it is reached both from boot (nothing bound) and from an
+ # HTTP request (the caller's tenant bound, which is not necessarily
+ # the bridge's). Everything below derives its tenant from this row.
+ async with unscoped_session(self._session_factory) as session:
bridge = await self._bridge_store.get(session, bridge_id)
if bridge is None:
raise ValueError(f"Bridge not found: {bridge_id}")
+ tenant_id = bridge.tenant_id
adapter_cls = self._adapter_registry.get(bridge.type)
config_cls = self._config_registry.get(bridge.type)
@@ -371,11 +380,13 @@ class CollaborationBridgeLifecycleService:
typed_config = config_cls.model_validate(bridge.connection_config or {})
adapter = adapter_cls(config=typed_config) # type: ignore[call-arg]
adapter.set_service_url_persister(
- lambda service_url: self._persist_service_url(bridge_id, service_url)
+ lambda service_url: self._persist_service_url(
+ bridge_id, tenant_id, service_url
+ )
)
adapter.set_channel_team_persister(
lambda channel_id, team_id: self._persist_channel_team(
- bridge_id, channel_id, team_id
+ bridge_id, tenant_id, channel_id, team_id
)
)
adapter.set_max_attachment_bytes(self._config.agent_media_max_bytes)
@@ -394,7 +405,7 @@ class CollaborationBridgeLifecycleService:
bridge_id,
)
- async with self._session_factory() as session:
+ async with tenant_session(self._session_factory, tenant_id) as session:
bridge_client_record = await self._client_store.get(
session, bridge.client_id
)
@@ -403,6 +414,7 @@ class CollaborationBridgeLifecycleService:
bridge_core = BridgeCore(
bridge_id=bridge_id,
+ bridge_tenant_id=tenant_id,
bridge_type=bridge.type,
bridge_display_name=bridge.display_name,
adapter=adapter,
@@ -432,7 +444,7 @@ class CollaborationBridgeLifecycleService:
)
task = asyncio.create_task(
- self._run_bridge(bridge_id, bridge_core, bridge_client)
+ self._run_bridge(bridge_id, tenant_id, bridge_core, bridge_client)
)
self._bridges[bridge_id] = bridge_core
self._tasks[bridge_id] = task
@@ -441,25 +453,32 @@ class CollaborationBridgeLifecycleService:
logger.info("Started collaboration bridge %s (%s)", bridge_id, bridge.type)
- async def _persist_service_url(self, bridge_id: str, service_url: str) -> None:
+ async def _persist_service_url(
+ self, bridge_id: str, tenant_id: str, service_url: str
+ ) -> None:
"""Persist an outbound serviceUrl an adapter learned from inbound traffic
- so outbound survives a restart (used by the Teams adapter)."""
- async with self._session_factory() as session:
+ so outbound survives a restart (used by the Teams adapter).
+
+ Called from inside the adapter's own task, which binds nothing, so the
+ bridge's tenant is carried here explicitly rather than inherited."""
+ async with tenant_session(self._session_factory, tenant_id) as session:
await self._bridge_store.set_service_url(session, bridge_id, service_url)
await session.commit()
async def _persist_channel_team(
- self, bridge_id: str, channel_id: str, team_id: str
+ self, bridge_id: str, tenant_id: str, channel_id: str, team_id: str
) -> None:
"""Persist the team an adapter learned a channel belongs to, so channel
capture survives a restart (used by the Teams adapter)."""
- async with self._session_factory() as session:
+ async with tenant_session(self._session_factory, tenant_id) as session:
await self._bridge_store.set_channel_team(
session, bridge_id, channel_id, team_id
)
await session.commit()
- async def _record_bridge_memberships(self, bridge_id: str, client_id: str) -> None:
+ async def _record_bridge_memberships(
+ self, bridge_id: str, tenant_id: str, client_id: str
+ ) -> None:
"""Make the bridge's rooms its recorded memberships before it starts.
A bridge belongs in every room it carries, and that was expressed by
@@ -472,7 +491,7 @@ class CollaborationBridgeLifecycleService:
Run at every start rather than repaired once, because the rooms a
bridge carries change while it is stopped.
"""
- async with self._session_factory() as session:
+ async with tenant_session(self._session_factory, tenant_id) as session:
rooms = await self._room_store.get_by_bridge(session, bridge_id)
added = 0
for room in rooms:
@@ -492,18 +511,34 @@ class CollaborationBridgeLifecycleService:
async def _run_bridge(
self,
bridge_id: str,
+ tenant_id: str,
bridge_core: BridgeCore,
bridge_client: BridgeClient,
) -> None:
- try:
- await self._record_bridge_memberships(bridge_id, bridge_client.client_id)
- await bridge_core.start()
- await bridge_client.start()
- except Exception:
- logger.exception("Bridge %s crashed", bridge_id)
- self._bridges.pop(bridge_id, None)
- self._tasks.pop(bridge_id, None)
- self._held_resources.pop(bridge_id, None)
+ """The bridge's own long-lived task.
+
+ `no_tenant` first, because an `asyncio.Task` snapshots the contextvars
+ of whoever created it — and `start` is reached from an HTTP request as
+ often as from boot, so without this the bridge would spend its whole
+ life acting as the operator who happened to restart it. Nothing here
+ is ambient afterwards: `_record_bridge_memberships` binds the bridge's
+ tenant for its own writes, `BridgeCore.start` binds it around each
+ piece of bridge-level loading it does, and `bridge_client.start()` —
+ which runs until shutdown — binds nothing at all, leaving each
+ delivery to bind the tenant of the room it is for.
+ """
+ with no_tenant():
+ try:
+ await self._record_bridge_memberships(
+ bridge_id, tenant_id, bridge_client.client_id
+ )
+ await bridge_core.start()
+ await bridge_client.start()
+ except Exception:
+ logger.exception("Bridge %s crashed", bridge_id)
+ self._bridges.pop(bridge_id, None)
+ self._tasks.pop(bridge_id, None)
+ self._held_resources.pop(bridge_id, None)
async def stop(self, bridge_id: str) -> None:
bridge_core = self._bridges.get(bridge_id)
diff --git a/core/switch_core/clients/agent_client.py b/core/switch_core/clients/agent_client.py
index 554c448b2..c4b22f1ee 100644
--- a/core/switch_core/clients/agent_client.py
+++ b/core/switch_core/clients/agent_client.py
@@ -44,6 +44,7 @@ from switch_core.clients.mentions import (
)
from switch_core.clients.room_meta import RoomMeta
from switch_core.db.models import Agent
+from switch_core.db.session_scope import unscoped_session
from switch_core.db.stores.agent_session_store import AgentSessionStore
from switch_core.db.stores.agent_store import AgentStore
from switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStore
@@ -297,7 +298,16 @@ class AgentClient(ClientBase[ClientConfig]):
return self.agent
async def start(self) -> None:
- async with self.session_factory() as session:
+ """Resolve the agent this client is, then run.
+
+ Unscoped, deliberately: this runs at the top of the client's own task,
+ which binds nothing, and it is the lookup that says which tenant this
+ client belongs to at all. `clients.id` is globally unique, so there is
+ nothing for a tenant to disambiguate — while a guessed one would turn
+ "this client is an agent" into "no agent found for client" and fail
+ the client at boot over a row that exists.
+ """
+ async with unscoped_session(self.session_factory) as session:
agent = await self._agent_store.get_by_client_id(session, self.client_id)
if agent is None:
raise RuntimeError(f"No agent found for client: {self.client_id}")
diff --git a/core/switch_core/clients/client_lifecycle_service.py b/core/switch_core/clients/client_lifecycle_service.py
index b45a1fde5..c8c57b5b0 100644
--- a/core/switch_core/clients/client_lifecycle_service.py
+++ b/core/switch_core/clients/client_lifecycle_service.py
@@ -14,7 +14,7 @@ from switch_core.db.models import Client
from switch_core.db.session_scope import unscoped_session
from switch_core.db.stores.client_store import ClientStore
from switch_core.provisioning import Provisioning
-from switch_core.tenant_context import tenant_scope
+from switch_core.tenant_context import no_tenant
logger = logging.getLogger(__name__)
@@ -57,14 +57,13 @@ class ClientLifecycleService:
async def start_all(self) -> None:
# Every tenant's clients in one pass at boot, so this read is
- # unscoped by nature. Each row carries its own tenant; bind it only
- # around starting that one client. `_start_task` spawns the client's
- # own long-lived task from inside this binding, and an asyncio task
- # snapshots the context it was created under, so the task keeps this
- # tenant as its default for its own life — a bootstrap fallback for
- # a read like AgentClient.start() resolving its own row, not a cache
- # any room-scoped work relies on: PostgresTransport binds the tenant
- # of the room it is actually acting on for each of those.
+ # unscoped by nature. Nothing is bound around `_start_task`: a client
+ # is not a single-tenant actor for the purposes of its own task. It
+ # reads which rooms it is in — a lookup keyed by a globally unique
+ # client id — and then works one room at a time, binding that room's
+ # tenant per delivery. A boot-time binding would only decide what the
+ # task snapshots, and the whole point is that nothing downstream may
+ # depend on that.
async with unscoped_session(self._session_factory) as session:
records = await self._client_store.get_all(session)
@@ -75,8 +74,7 @@ class ClientLifecycleService:
client = self._client_factory.create(record)
self._clients[record.id] = client
self._client_types[record.id] = record.type
- with tenant_scope(record.tenant_id):
- self._start_task(record.id, client)
+ self._start_task(record.id, client)
async def create_client(
self,
@@ -188,11 +186,24 @@ class ClientLifecycleService:
async def _run_client(
self, client_id: str, client: ClientBase[ClientConfig]
) -> None:
- try:
- await client.start()
- except Exception:
- logger.exception(
- "Client %s (%s) crashed", client.display_name, client.matrix_user_id
- )
- self._clients.pop(client_id, None)
- self._tasks.pop(client_id, None)
+ """A client's long-lived task, deliberately ambient-free.
+
+ `no_tenant` because a task keeps the context of whoever created it,
+ and the creators differ: boot, a gateway request that added an agent,
+ or an inbound bridge message that minted a puppet mid-conversation.
+ A puppet in particular is reused for every room the person it stands
+ for speaks in, so the first room's tenant is exactly the value that
+ must not survive into the second. Everything the client does binds
+ the tenant of the room it is acting on, or — for the two lookups that
+ answer *which* tenant, its own row and its room list — is unscoped on
+ purpose.
+ """
+ with no_tenant():
+ try:
+ await client.start()
+ except Exception:
+ logger.exception(
+ "Client %s (%s) crashed", client.display_name, client.matrix_user_id
+ )
+ self._clients.pop(client_id, None)
+ self._tasks.pop(client_id, None)
diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.py
index d9a56257b..d90c99663 100644
--- a/core/switch_core/db/models.py
+++ b/core/switch_core/db/models.py
@@ -91,14 +91,18 @@ TENANT_ZERO_ID = "00000000-0000-0000-0000-000000000000"
def _tenant_id_default() -> str:
"""The tenant a new scoped row lands in when nothing tells it otherwise.
- Prefers the tenant bound to the current request/session context; falls
- back to tenant zero only when nothing is bound. The fallback is still
- load-bearing: the ~206 background call sites that open a session from the
- factory directly (`docs/old/multi-tenancy-phase1-db.md`, "Setting the
- tenant") bind no tenant at all today, and removing this fallback before
- they are converted — and before the row-level-security policies land to
- make an unscoped write fail loudly instead — would break every one of
- them. Remove it once both have shipped.
+ Prefers the tenant bound to the current unit of work; falls back to tenant
+ zero only when nothing is bound. The fallback is still load-bearing, and
+ now for a sharper reason than before: the long-lived background tasks
+ deliberately bind *nothing* for their lifetime
+ (`switch_core.tenant_context.no_tenant`), so a write reached from one that
+ did not bind the row's tenant lands here rather than on someone else's
+ tenant. That is the right failure while there is one tenant and no policy
+ to raise instead. It is the wrong one the day there are two — a write that
+ should have been refused becomes a write into tenant zero — so this goes
+ when row-level security lands, not before, and the raw-session inventory
+ in `tests/switch_core/db/test_unscoped_session_allowlist.py` is what
+ tracks how much is still relying on it.
"""
return current_tenant_id() or TENANT_ZERO_ID
diff --git a/core/switch_core/db/session_scope.py b/core/switch_core/db/session_scope.py
index d92c8cccc..c00e679ae 100644
--- a/core/switch_core/db/session_scope.py
+++ b/core/switch_core/db/session_scope.py
@@ -6,33 +6,41 @@ Everything in a request already gets a tenant for free: `gateway/auth.py` and
`after_begin` hook (`db/tenant_session.py`) stamps it on every transaction
that session opens from then on, at any depth, with no call site to remember.
-Nothing does that for the roughly 206 places that open a session from the
+Nothing does that for the roughly 197 places that open a session from the
factory directly with no request behind them — the delivery loop, the
collaboration and server-connector lifecycle services, the startup seeding in
`main.py`, the periodic sweeps. Each needs to say, at the point it opens a
session, which of two things it is doing:
- **`tenant_session`** binds a tenant for the life of one session, the same
- way a request does. This is the answer for a unit of work that acts for one
- room, one bridge, or one connector — a message delivery, an inbound bridge
- event, a bridge's own startup, one row out of a cross-tenant sweep. Bind at
- the natural unit of work: derive the tenant from whatever the work is
- actually for (the room, the bridge, the connector row), not once per
- long-lived object and reused, since a client or a bridge is not guaranteed
- to act for only one tenant over its life.
-
-- **`unscoped_session`** opens a session with no tenant bound at all — the
- fail-open hatch inside an otherwise fail-closed design. It exists for work
- that is legitimately cross-tenant: reading every row before fanning out
- work per row (a sweep, a lifecycle enumeration), and startup seeding that
- runs before any tenant can be said to exist. Nothing today stops a query on
- a session it opens from reading across every tenant there is — that is
- exactly what "unscoped" means — so its callers are pinned to an explicit
- allowlist by
- `tests/switch_core/db/test_unscoped_session_allowlist.py`, which fails on a
- new one and says what to do about it. Reach for `tenant_session` first;
- reach for this only when the work really cannot be attributed to one
- tenant.
+ way a request does. This is the answer for a unit of work that acts on one
+ row: a message delivery, an inbound bridge event, one bridge's startup, one
+ row out of a cross-tenant sweep. Derive the tenant from the row the work is
+ actually for — the room, the bridge, the connector — at the point the work
+ happens. Never once per long-lived object, and never once per task: see
+ `tenant_context.no_tenant` for why.
+
+- **`unscoped_session`** opens a session with **no tenant bound at all**, for
+ the duration of the block, whatever the caller had bound going in. It is
+ the fail-open hatch inside an otherwise fail-closed design, and it exists
+ for two shapes of work:
+
+ - reading every row before fanning out work per row — a sweep, a lifecycle
+ enumeration, startup seeding that runs before any tenant exists;
+ - a lookup whose whole job is to answer *which* tenant something is in, or
+ that is keyed by something globally unique and spans tenants by nature:
+ resolving a room from its transport id, or a client's rooms from its id.
+ Inheriting a caller's tenant here is not a smaller answer, it is a wrong
+ one.
+
+ The unbinding is the point, and it is why this is not a synonym for calling
+ the factory. A helper that merely *named* the intent while inheriting
+ whatever was ambient would have the hook stamp the caller's tenant onto the
+ transaction, and the cross-tenant read the call site asked for would
+ silently be a single-tenant one. Its callers are pinned to an explicit
+ allowlist by `tests/switch_core/db/test_unscoped_session_allowlist.py`,
+ which fails on a new one and says what to do about it. Reach for
+ `tenant_session` first.
Both are thin: the tenant binding is a contextvar (`tenant_context.py`), and
the `after_begin` hook is what actually turns it into `set_config` on the
@@ -48,7 +56,7 @@ from contextlib import asynccontextmanager
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
-from switch_core.tenant_context import bind_tenant_id, unbind_tenant_id
+from switch_core.tenant_context import bind_tenant_id, no_tenant, unbind_tenant_id
@asynccontextmanager
@@ -75,12 +83,14 @@ async def unscoped_session(
) -> AsyncIterator[AsyncSession]:
"""Open a session with no tenant bound — the fail-open hatch.
- Behaves exactly like calling `session_factory()` directly today, because
- that is what it is: no binding, no unbinding, nothing hidden. The point of
- naming it is not to change what it does but to make every place that does
- it say so, so the allowlist in
- `tests/switch_core/db/test_unscoped_session_allowlist.py` has something to
- pin.
+ Unbinds for the duration of the block and restores the caller's binding on
+ the way out, so a query issued here reads across every tenant *whether or
+ not* the caller had one bound. That is the whole contract: a call site
+ that says "unscoped" and then quietly ran scoped, because it was reached
+ from a request or from inside a `tenant_scope`, would be the worst
+ available outcome — an allowlist certifying a cross-tenant read that never
+ happened.
"""
- async with session_factory() as session:
- yield session
+ with no_tenant():
+ async with session_factory() as session:
+ yield session
diff --git a/core/switch_core/room_service.py b/core/switch_core/room_service.py
index 7a0d898a3..45265d3dc 100644
--- a/core/switch_core/room_service.py
+++ b/core/switch_core/room_service.py
@@ -540,7 +540,7 @@ class RoomService:
if bridge_core and external_channel_id:
bridge_core.add_room_mapping(
- room.id, matrix_room_id, external_channel_id
+ room.id, matrix_room_id, external_channel_id, room.tenant_id
)
finally:
if bridge_core and external_channel_id:
@@ -781,15 +781,23 @@ class RoomService:
logger.info("Removed %d agents from room %s", len(agent_ids), room_id)
- async def _room_tenant(self, room_id: str) -> str:
- """The tenant a room belongs to, resolved fresh — never cached beside
- a room id, since nothing here holds one room for longer than a call.
+ async def _load_room(self, room_id: str) -> Room:
+ """A room row, read with no tenant bound.
+
+ The bootstrap read: every caller below is about to bind the tenant
+ this returns, so scoping the read to a tenant would be circular — and
+ worse than circular under policies, where the wrong guess turns into
+ `Room not found` for a room that exists. Nothing is cached: no caller
+ here holds a room for longer than the call.
"""
- async with self._session_factory() as session:
+ async with unscoped_session(self._session_factory) as session:
room = await self._room_store.get(session, room_id)
if room is None:
raise ValueError(f"Room not found: {room_id}")
- return room.tenant_id
+ return room
+
+ async def _room_tenant(self, room_id: str) -> str:
+ return (await self._load_room(room_id)).tenant_id
async def update_room(
self,
@@ -941,7 +949,7 @@ class RoomService:
if bridge_core and external_channel_id:
bridge_core.add_room_mapping(
- room.id, room.matrix_room_id, external_channel_id
+ room.id, room.matrix_room_id, external_channel_id, room.tenant_id
)
await self._ensure_channel_capture(
bridge_core, external_channel_id, channel_type
@@ -1054,7 +1062,7 @@ class RoomService:
await session.commit()
new_bridge.add_room_mapping(
- room_id, matrix_room_id, external_channel_id
+ room_id, matrix_room_id, external_channel_id, room.tenant_id
)
finally:
new_bridge.end_provisioning(external_channel_id)
@@ -1182,10 +1190,8 @@ class RoomService:
"""Invite a single running client to the room (it auto-joins) and record
its membership. Idempotent — safe to call repeatedly, e.g. on every
bridged message from an external user's puppet."""
- async with self._session_factory() as session:
- room = await self._room_store.get(session, room_id)
- if room is None:
- raise ValueError(f"Room not found: {room_id}")
+ room = await self._load_room(room_id)
+ async with tenant_session(self._session_factory, room.tenant_id) as session:
already_member = client_id in await self._room_store.get_client_ids(
session, room_id
)
diff --git a/core/switch_core/tenant_context.py b/core/switch_core/tenant_context.py
index fd9f63aab..a64e5a9c6 100644
--- a/core/switch_core/tenant_context.py
+++ b/core/switch_core/tenant_context.py
@@ -15,7 +15,9 @@ decide what happens when nothing is bound — callers do, deliberately:
has no tenant and must not be given one it invented.
- `db/models.py`'s `TenantScoped` default treats "nothing bound" as tenant
zero, because the background call sites that still write through it have
- not been converted to bind one yet.
+ not been converted to bind one yet — and because the long-lived tasks now
+ unbind deliberately (`no_tenant` below), "nothing bound" is the ordinary
+ state there rather than an accident.
Neither of those fallbacks lives here. A `current_tenant_id()` that quietly
substituted a default would make both of those call sites indistinguishable
@@ -48,6 +50,16 @@ def unbind_tenant_id(token: Token[str | None]) -> None:
_current_tenant_id.reset(token)
+def clear_tenant_id() -> Token[str | None]:
+ """Unbind whatever tenant is bound, returning a token to restore it with.
+
+ Distinct from never having bound one only in that it can be undone. What
+ the reader sees is the same: `current_tenant_id()` is `None` and the
+ `after_begin` hook issues no `set_config`.
+ """
+ return _current_tenant_id.set(None)
+
+
@contextmanager
def tenant_scope(tenant_id: str) -> Iterator[None]:
"""Bind `tenant_id` for the duration of the block."""
@@ -56,3 +68,27 @@ def tenant_scope(tenant_id: str) -> Iterator[None]:
yield
finally:
unbind_tenant_id(token)
+
+
+@contextmanager
+def no_tenant() -> Iterator[None]:
+ """Unbind for the duration of the block, whatever was bound going in.
+
+ Two uses, and they are the same idea from both ends:
+
+ - a lookup that must span tenants (which tenant is this room in? which
+ rooms is this client a member of?) must not inherit a caller's tenant,
+ or it silently narrows to it;
+ - a long-lived background task must not inherit the context of whatever
+ created it. An `asyncio.Task` snapshots the contextvars of its creator,
+ so a bridge restarted from an HTTP request would otherwise run its whole
+ life under the requesting user's tenant. Entering this at the top of the
+ task body makes the task ambient-free, so every unit of work inside it
+ has to bind the tenant of the row it is acting on — and one that forgets
+ reads nothing rather than reading the wrong tenant.
+ """
+ token = clear_tenant_id()
+ try:
+ yield
+ finally:
+ unbind_tenant_id(token)
diff --git a/core/switch_core/transport/postgres.py b/core/switch_core/transport/postgres.py
index 5734f1c63..bd00bfa6a 100644
--- a/core/switch_core/transport/postgres.py
+++ b/core/switch_core/transport/postgres.py
@@ -42,7 +42,7 @@ from typing import TYPE_CHECKING, Any
from switch_core.attachments import ATTACHMENT_GROUP_KEY
from switch_core.db.models import ClientRoom, MediaBlob, Message, MessageAttachment
-from switch_core.db.session_scope import tenant_session
+from switch_core.db.session_scope import tenant_session, unscoped_session
from switch_core.messages.recorded_types import EPHEMERAL
from switch_core.messages.row import attachments_in, text_field, thread_root_of
from switch_core.tenant_context import tenant_scope
@@ -272,15 +272,16 @@ class PostgresTransport:
noticed keeps every guard downstream in play, and covers whatever else
depended on hearing its own join.
"""
- async with self._session_factory() as session:
- room_id = await self._resolve_room(session, transport_room_id)
- if room_id in self._cursors:
- return
- self._cursors[room_id] = (
- from_seq
- if from_seq is not None
- else await self._message_store.head_seq(session, room_id)
- )
+ room_id, tenant_id = await self._resolve_room_and_tenant(transport_room_id)
+ if room_id in self._cursors:
+ return
+ if from_seq is not None:
+ self._cursors[room_id] = from_seq
+ else:
+ async with tenant_session(self._session_factory, tenant_id) as session:
+ self._cursors[room_id] = await self._message_store.head_seq(
+ session, room_id
+ )
self._watching[room_id] = transport_room_id
self._listener.subscribe(room_id, self._on_room_advanced)
self._ephemeral.subscribe(transport_room_id, self._on_ephemeral)
@@ -555,8 +556,8 @@ class PostgresTransport:
Scoped to the room, so an id from elsewhere cannot be read through it —
the caller is resolving a thread root supplied by an agent.
"""
- async with self._session_factory() as session:
- switch_room_id = await self._resolve_room(session, room_id)
+ switch_room_id, tenant_id = await self._resolve_room_and_tenant(room_id)
+ async with tenant_session(self._session_factory, tenant_id) as session:
rows = await self._message_store.list_by_transport_event_ids(
session, switch_room_id, [event_id]
)
@@ -629,8 +630,21 @@ class PostgresTransport:
return True
async def joined_rooms(self) -> list[str]:
- """The transport-side ids of this client's rooms."""
- async with self._session_factory() as session:
+ """The transport-side ids of this client's rooms.
+
+ Unscoped, and that is the point rather than an oversight. This runs
+ once, at the top of `receive_forever`, in a task that binds nothing —
+ so a tenant here could only come from whatever created the task, and
+ answering "which rooms is this client in" under a guessed tenant
+ returns a *subset* with no error to say so. The failure would be
+ silent and total: the client watches the rooms it was allowed to see
+ and is simply deaf in the rest, forever, with nothing in the log.
+
+ The key it reads by is `clients.id`, which is globally unique, so
+ there is nothing for a tenant to disambiguate. Each room that comes
+ back is then watched under its own tenant, resolved from its own row.
+ """
+ async with unscoped_session(self._session_factory) as session:
rooms = await self._room_store.get_for_client(session, self.client_id)
return [room.matrix_room_id for room in rooms if room.matrix_room_id]
@@ -643,11 +657,13 @@ class PostgresTransport:
async def _resolve_room(self, session: AsyncSession, transport_room_id: str) -> str:
"""The Switch room id for `transport_room_id`, resolved and cached.
- No tenant is bound on `session` yet when this runs the first time for
- a room — resolving which room (and so which tenant) this is is the
- thing that determines one, the same bootstrap as authenticating a
- request. It caches the tenant alongside the id from the very same
- row, so nothing downstream needs a second unscoped read to learn it.
+ Takes the caller's session, for callers that are going on to use it.
+ The read itself is tenant-agnostic in the only sense that matters:
+ `rooms.matrix_room_id` is unique per tenant, not globally, so a caller
+ that hands in a session bound to the wrong tenant gets "not a Switch
+ room" rather than another tenant's row. `_resolve_room_and_tenant` is
+ the entry point for a caller that does not yet know which tenant to
+ bind, and it is the one used everywhere the answer is in doubt.
"""
cached = self._room_ids.get(transport_room_id)
if cached is not None:
@@ -660,17 +676,17 @@ class PostgresTransport:
return room.id
async def _resolve_room_and_tenant(self, transport_room_id: str) -> tuple[str, str]:
- """Like `_resolve_room`, but for a caller about to bind the tenant it
- returns rather than reuse the session that resolved it.
+ """The Switch room id and tenant for a transport-side id.
- Opens its own short-lived, unscoped session only on a cache miss —
- the same one-time bootstrap `_resolve_room` always needed. Once
- cached, resolving costs nothing: no session, no query.
+ Deliberately unscoped on a cache miss: this is the lookup that decides
+ *which* tenant the caller is about to bind, so inheriting one would
+ make it either a tautology or a false negative. Once cached, resolving
+ costs nothing: no session, no query, no round trip.
"""
cached = self._room_ids.get(transport_room_id)
if cached is not None:
return cached, self._room_tenants[cached]
- async with self._session_factory() as session:
+ async with unscoped_session(self._session_factory) as session:
room_id = await self._resolve_room(session, transport_room_id)
return room_id, self._room_tenants[room_id]
diff --git a/core/tests/switch_core/bridges/agent/protocol/test_sweep_runtime_states_tenant_binding.py b/core/tests/switch_core/bridges/agent/protocol/test_sweep_runtime_states_tenant_binding.py
index f20959e24..b45e231ba 100644
--- a/core/tests/switch_core/bridges/agent/protocol/test_sweep_runtime_states_tenant_binding.py
+++ b/core/tests/switch_core/bridges/agent/protocol/test_sweep_runtime_states_tenant_binding.py
@@ -4,10 +4,13 @@ that finds them is unscoped. Each row is itself tenant-scoped, so the rest of
the work for that row — the liveness check and the reset — binds that row's
own tenant, one at a time, rather than the whole sweep.
-This pins the two things that matter about that: each row's write is bound to
-its own tenant, and a row from one tenant cannot leak its binding into the
-next row's work, even when the two are processed back to back in the same
-sweep.
+This pins three things about that: each row's write is bound to its own
+tenant; a row from one tenant cannot leak its binding into the next row's
+work, even when the two are processed back to back in the same sweep; and the
+*whole* of a row's work is inside its binding, the emit at the end included.
+That last one is not decoration — the emit is the visible half. It resolves a
+mention handle and posts to a bridge, and leaving it outside the scope would
+put every write a reader actually sees back on whatever was ambient.
"""
from __future__ import annotations
@@ -156,3 +159,39 @@ async def test_sweep_binds_each_row_s_own_tenant_and_does_not_leak(
row_b = await store.get(session, agent_b, room_b)
assert row_a is not None and row_a.state == "idle"
assert row_b is not None and row_b.state == "idle"
+
+
+async def test_the_tail_of_a_row_s_work_is_still_inside_its_binding(
+ session_factory: async_sessionmaker[AsyncSession],
+) -> None:
+ """`_mention_handle_for` and `_emit_runtime_state` run after the upsert's
+ session has closed. They are still that row's work — the handle is read
+ from `external_users`, and what the emit provokes is a post into the
+ room — so they must still be under the row's tenant."""
+ tenant_a = f"tenant-{uuid.uuid4().hex[:8]}"
+ tenant_b = f"tenant-{uuid.uuid4().hex[:8]}"
+ async with session_factory() as session:
+ await _make_tenant(session, tenant_a)
+ await _make_tenant(session, tenant_b)
+ agent_a, _ = await _make_stale_runtime_state(session, tenant_id=tenant_a)
+ agent_b, _ = await _make_stale_runtime_state(session, tenant_id=tenant_b)
+ await session.commit()
+
+ service = _service(session_factory)
+ emitted: dict[str, str | None] = {}
+ handles: dict[str, str | None] = {}
+
+ async def _record_emit(**kwargs: object) -> None:
+ emitted[str(kwargs["agent_id"])] = current_tenant_id()
+
+ async def _record_handle(agent: object, bridge_id: object) -> None:
+ handles[str(getattr(agent, "id", agent))] = current_tenant_id()
+
+ service._emit_runtime_state = _record_emit # type: ignore[attr-defined,method-assign]
+ service._mention_handle_for = _record_handle # type: ignore[attr-defined,method-assign]
+
+ await service.sweep_runtime_states()
+
+ assert emitted == {agent_a: tenant_a, agent_b: tenant_b}
+ assert handles == {agent_a: tenant_a, agent_b: tenant_b}
+ assert current_tenant_id() is None
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_agent_display_names.py b/core/tests/switch_core/bridges/collaboration/test_bridge_agent_display_names.py
index 39785e159..892df5562 100644
--- a/core/tests/switch_core/bridges/collaboration/test_bridge_agent_display_names.py
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_agent_display_names.py
@@ -99,6 +99,7 @@ def _bridge(*agents: SimpleNamespace) -> BridgeCore:
"""A BridgeCore with only the two collaborators the resolver and the echo
check touch — the rest of `__init__` needs a live Matrix stack."""
bridge = BridgeCore.__new__(BridgeCore)
+ bridge._bridge_tenant_id = "tenant-1"
bridge._agent_store = _AgentStore({a.name: a for a in agents}) # type: ignore[assignment]
bridge._session_factory = _Session # type: ignore[assignment]
return bridge
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_agent_icons.py b/core/tests/switch_core/bridges/collaboration/test_bridge_agent_icons.py
index f4c95fcf7..3a0148d9f 100644
--- a/core/tests/switch_core/bridges/collaboration/test_bridge_agent_icons.py
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_agent_icons.py
@@ -39,6 +39,7 @@ class _AgentStore:
def _bridge(agents: dict[str, SimpleNamespace]) -> BridgeCore:
bridge = BridgeCore.__new__(BridgeCore)
+ bridge._bridge_tenant_id = "tenant-1"
bridge._agent_store = _AgentStore(agents) # type: ignore[assignment]
bridge._session_factory = _Session # type: ignore[assignment]
return bridge
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_channel_capture.py b/core/tests/switch_core/bridges/collaboration/test_bridge_channel_capture.py
index 2443c6bd5..a3fcffaa3 100644
--- a/core/tests/switch_core/bridges/collaboration/test_bridge_channel_capture.py
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_channel_capture.py
@@ -49,6 +49,7 @@ async def test_ensure_channel_captures_forwards_valid_channels() -> None:
_room_store=_RoomStore(),
_adapter=_Adapter(),
_bridge_id="bridge-1",
+ _bridge_tenant_id="tenant-1",
)
await BridgeCore._ensure_channel_captures(bridge)
@@ -79,6 +80,7 @@ async def test_ensure_channel_captures_noop_without_channels() -> None:
_room_store=_RoomStore(),
_adapter=_Adapter(),
_bridge_id="bridge-1",
+ _bridge_tenant_id="tenant-1",
)
await BridgeCore._ensure_channel_captures(bridge)
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_channel_migration.py b/core/tests/switch_core/bridges/collaboration/test_bridge_channel_migration.py
index 156104360..2634a4dfc 100644
--- a/core/tests/switch_core/bridges/collaboration/test_bridge_channel_migration.py
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_channel_migration.py
@@ -60,6 +60,8 @@ class _Session:
def _make_bridge(rooms: dict[str, SimpleNamespace]) -> BridgeCore:
bridge = BridgeCore.__new__(BridgeCore)
bridge._bridge_id = "bridge-1"
+ bridge._bridge_tenant_id = "tenant-1"
+ bridge._room_tenants = {}
bridge._channel_locks = {}
bridge._channel_to_room = {}
bridge._room_to_channel = {}
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_duplicate_room_race.py b/core/tests/switch_core/bridges/collaboration/test_bridge_duplicate_room_race.py
index e40cca85d..5ee8f35e0 100644
--- a/core/tests/switch_core/bridges/collaboration/test_bridge_duplicate_room_race.py
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_duplicate_room_race.py
@@ -46,6 +46,7 @@ def _make_bridge(**overrides: Any) -> BridgeCore:
bridge._room_tenants = {}
bridge._channel_locks = {}
bridge._bridge_id = "bridge-1"
+ bridge._bridge_tenant_id = "tenant-1"
bridge._bridge_display_name = "Switch"
bridge._adapter = _Adapter() # type: ignore[assignment]
bridge._room_service = SimpleNamespace(create_room=create_room) # type: ignore[assignment]
@@ -188,6 +189,7 @@ async def test_adopt_existing_room_registers_mapping() -> None:
bridge._room_to_channel = {}
bridge._room_tenants = {}
bridge._bridge_id = "bridge-1"
+ bridge._bridge_tenant_id = "tenant-1"
bridge._session_factory = _Session # type: ignore[assignment]
bridge._room_store = _RoomStore() # type: ignore[assignment]
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_inbound_tenant_binding.py b/core/tests/switch_core/bridges/collaboration/test_bridge_inbound_tenant_binding.py
new file mode 100644
index 000000000..099bf75a4
--- /dev/null
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_inbound_tenant_binding.py
@@ -0,0 +1,212 @@
+"""An inbound platform event acts under the tenant it belongs to (CHOO-2623).
+
+`_traced` is the one choke point every inbound handler goes through, and it is
+where the tenant is bound: the room's, when the channel already maps to one;
+the bridge's, when it does not and the handler is about to create the room.
+
+Two properties fall out of doing it there, and both are pinned below.
+
+**A room created after the bridge started resolves like any other.** The
+channel map is not only loaded at boot — `add_room_mapping` is called whenever
+a room is created, adopted or moved onto a channel — so it, and not the boot
+load, is what has to carry the tenant. It does, which is why the inbound path
+reads no row at all.
+
+**The platform stops mattering.** Mattermost's websocket runs on an OS thread
+and hands its coroutine over with `asyncio.run_coroutine_threadsafe`, which
+starts it in an *empty* context; Slack's dispatches from a task that inherited
+whatever created it. Binding at the choke point rather than depending on what
+the handler inherits means both land in the same tenant, so which platform a
+message arrived on can no longer decide where its room goes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+
+from switch_core.bridges.collaboration.bridge_core import BridgeCore
+from switch_core.tenant_context import current_tenant_id, tenant_scope
+
+BRIDGE_TENANT = "tenant-bridge"
+ROOM_TENANT = "tenant-room"
+
+
+class _ExplodingSessionFactory:
+ """A session factory that fails if anything opens a session.
+
+ The inbound path must resolve a tenant from what it already holds. A read
+ here would not merely be slow: it would run under whatever tenant is bound
+ at the time, which on this path is the question being asked.
+ """
+
+ def __call__(self) -> Any:
+ raise AssertionError(
+ "the inbound path opened a database session to resolve a tenant; "
+ "add_room_mapping is supposed to have recorded it already"
+ )
+
+
+def _bridge() -> BridgeCore:
+ bridge = BridgeCore.__new__(BridgeCore)
+ bridge._bridge_id = "bridge-1"
+ bridge._bridge_tenant_id = BRIDGE_TENANT
+ bridge._bridge_type = "mattermost"
+ bridge._channel_to_room = {}
+ bridge._room_to_channel = {}
+ bridge._room_tenants = {}
+ bridge._session_factory = _ExplodingSessionFactory() # type: ignore[assignment]
+ return bridge
+
+
+def _event(channel_id: str) -> SimpleNamespace:
+ return SimpleNamespace(channel_id=channel_id)
+
+
+async def test_a_room_created_after_the_bridge_started_resolves_its_tenant() -> None:
+ """The defect this replaces: `add_room_mapping` filled the channel maps
+ and not the tenant map, so every room created after boot missed the cache
+ and fell into a database read under whatever was ambient."""
+ bridge = _bridge()
+ seen: list[str | None] = []
+
+ async def _handler(event: object) -> None:
+ seen.append(current_tenant_id())
+
+ traced = bridge._traced(_handler)
+
+ # Exactly what room creation does once the room exists (room_service),
+ # long after `_load_channel_map` ran.
+ bridge.add_room_mapping("room-new", "!new:test", "C-new", ROOM_TENANT)
+
+ await traced(_event("C-new"))
+
+ assert seen == [ROOM_TENANT]
+
+
+async def test_an_unmapped_channel_binds_the_bridges_own_tenant() -> None:
+ """Auto-room-creation. There is no room to ask, but the answer is not
+ ambient either: a room this bridge creates belongs to the tenant that owns
+ the bridge, and the schema agrees — `rooms` keys to
+ `collaboration_bridges` on `tenant_id`."""
+ bridge = _bridge()
+ seen: list[str | None] = []
+
+ async def _handler(event: object) -> None:
+ seen.append(current_tenant_id())
+
+ await bridge._traced(_handler)(_event("C-unknown"))
+
+ assert seen == [BRIDGE_TENANT]
+
+
+async def test_the_binding_does_not_outlive_the_event() -> None:
+ bridge = _bridge()
+ bridge.add_room_mapping("room-1", "!one:test", "C1", ROOM_TENANT)
+
+ async def _handler(event: object) -> None:
+ assert current_tenant_id() == ROOM_TENANT
+
+ await bridge._traced(_handler)(_event("C1"))
+
+ assert current_tenant_id() is None
+
+
+async def test_removing_a_mapping_forgets_the_tenant_with_it() -> None:
+ """Otherwise the tenant map is the one part of the mapping that only ever
+ grows, and a room id reused after a bridge move would resolve to a stale
+ answer with nothing to correct it."""
+ bridge = _bridge()
+ bridge.add_room_mapping("room-1", "!one:test", "C1", ROOM_TENANT)
+ bridge.remove_room_mapping("room-1", "!one:test")
+
+ assert bridge._room_tenants == {}
+
+
+async def test_a_thread_dispatched_event_lands_in_the_same_tenant() -> None:
+ """Mattermost, in miniature.
+
+ `asyncio.run_coroutine_threadsafe` starts the coroutine in an empty
+ context — nothing the bridge's task had bound reaches it. Under the model
+ this replaces, that made auto-created rooms land in tenant zero on
+ Mattermost and in the bridge's tenant everywhere else: a per-platform
+ lottery. Both dispatch styles now agree.
+ """
+ bridge = _bridge()
+ bridge.add_room_mapping("room-1", "!one:test", "C1", ROOM_TENANT)
+ seen: list[str | None] = []
+
+ async def _handler(event: object) -> None:
+ seen.append(current_tenant_id())
+
+ traced = bridge._traced(_handler)
+ loop = asyncio.get_running_loop()
+
+ # Dispatched the way the Mattermost adapter does it, from a thread with no
+ # context of its own, and the way every other adapter does it, inline.
+ await asyncio.wrap_future(
+ asyncio.run_coroutine_threadsafe(traced(_event("C1")), loop)
+ )
+ await traced(_event("C1"))
+
+ assert seen == [ROOM_TENANT, ROOM_TENANT]
+
+
+class TestAPuppetIsMintedInTheBridgesTenant:
+ """A puppet is per-bridge and reused for every room the person it stands
+ for ever speaks in, so it cannot be stamped with the tenant of whichever
+ room happened to trigger it first. The rooms a bridge carries are all in
+ its tenant (`rooms` keys to `collaboration_bridges` on `tenant_id`), so
+ the bridge's is the only answer that holds for all of them.
+ """
+
+ async def test_the_identity_is_created_under_the_bridges_tenant(self) -> None:
+ bridge = BridgeCore.__new__(BridgeCore)
+ bridge._bridge_id = "bridge-1"
+ bridge._bridge_tenant_id = BRIDGE_TENANT
+ bridge._bridge_type = "mattermost"
+ bridge._puppet_locks = {}
+ bridge._user_puppets = {}
+ bridge._puppet_matrix_ids = set()
+ seen: list[str | None] = []
+
+ async def _locked(external_user_id: str, external_username: str) -> str:
+ seen.append(current_tenant_id())
+ return "client-1"
+
+ bridge._create_puppet_locked = _locked # type: ignore[assignment]
+
+ # Reached from inside an inbound event for a room — the binding the
+ # puppet must *not* adopt, were the two ever to differ.
+ with tenant_scope(ROOM_TENANT):
+ assert await bridge._create_puppet("U1", "alice") == "client-1"
+
+ assert seen == [BRIDGE_TENANT]
+
+ async def test_a_cached_puppet_is_returned_without_reminting(self) -> None:
+ bridge = BridgeCore.__new__(BridgeCore)
+ bridge._bridge_tenant_id = BRIDGE_TENANT
+ bridge._puppet_locks = {}
+ bridge._user_puppets = {"U1": "client-1"}
+
+ # The cache check lives inside the locked half, so this proves the
+ # split did not move it out from under the lock.
+ bridge._create_puppet_locked = BridgeCore._create_puppet_locked.__get__(bridge) # type: ignore[assignment]
+
+ assert await bridge._create_puppet("U1", "alice") == "client-1"
+
+
[email protected]("tenant", [BRIDGE_TENANT, ROOM_TENANT])
+async def test_the_mapping_records_whatever_tenant_it_is_given(tenant: str) -> None:
+ """`add_room_mapping` does not guess. Its caller has the room row in hand
+ and passes the row's tenant, so a room whose tenant somehow differs from
+ its bridge's is still handled under its own."""
+ bridge = _bridge()
+ room_id = f"room-{uuid.uuid4().hex[:8]}"
+ bridge.add_room_mapping(room_id, f"!{room_id}:test", "C1", tenant)
+
+ assert await bridge._room_tenant(room_id) == tenant
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_mention_resolution.py b/core/tests/switch_core/bridges/collaboration/test_bridge_mention_resolution.py
index 0f2ae6a9c..648c0e119 100644
--- a/core/tests/switch_core/bridges/collaboration/test_bridge_mention_resolution.py
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_mention_resolution.py
@@ -1,5 +1,6 @@
from __future__ import annotations
+import functools
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from types import SimpleNamespace
@@ -64,6 +65,7 @@ def _loading_bridge(adapter: SlackAdapter, users: list[SimpleNamespace]) -> Any:
return SimpleNamespace(
_adapter=adapter,
_bridge_id=BRIDGE_ID,
+ _bridge_tenant_id="tenant-1",
_session_factory=_session_factory(),
_external_user_store=SimpleNamespace(get_by_bridge=_get_by_bridge),
_client_store=SimpleNamespace(get=_get_client),
@@ -138,6 +140,7 @@ async def test_new_puppet_is_mentionable_without_waiting_for_a_restart() -> None
_adapter=adapter,
_bridge_id=BRIDGE_ID,
_bridge_type="slack",
+ _bridge_tenant_id="tenant-1",
_session_factory=_session_factory(),
_puppet_locks={},
_user_puppets={},
@@ -146,6 +149,9 @@ async def test_new_puppet_is_mentionable_without_waiting_for_a_restart() -> None
_client_lifecycle=SimpleNamespace(create_and_start=_create_and_start),
_external_user_store=SimpleNamespace(create=_create),
)
+ bridge._create_puppet_locked = functools.partial(
+ BridgeCore._create_puppet_locked, bridge
+ )
await BridgeCore._create_puppet(bridge, "U789", "new.person")
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_no_agents_notice.py b/core/tests/switch_core/bridges/collaboration/test_bridge_no_agents_notice.py
index 19d4f50ad..d681b37f7 100644
--- a/core/tests/switch_core/bridges/collaboration/test_bridge_no_agents_notice.py
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_no_agents_notice.py
@@ -55,7 +55,9 @@ def _fake_bridge(*, agent_ids: list[str], slash_hint: str | None = None): # noq
) -> list[str]:
return agent_ids
- def add_room_mapping(room_id: str, matrix_room_id: str, channel_id: str) -> None:
+ def add_room_mapping(
+ room_id: str, matrix_room_id: str, channel_id: str, tenant_id: str
+ ) -> None:
pass
async def _adopt_existing_room(channel_id: str) -> tuple[str, str] | None:
diff --git a/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py b/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py
index b8b405ed5..517b67b37 100644
--- a/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py
+++ b/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py
@@ -11,7 +11,13 @@ from switch_core.bridges.collaboration.lifecycle_service import (
CollaborationBridgeLifecycleService,
_bridge_client_localpart,
)
-from switch_core.db.models import Client, CollaborationBridge, ExternalUser, Room
+from switch_core.db.models import (
+ TENANT_ZERO_ID,
+ Client,
+ CollaborationBridge,
+ ExternalUser,
+ Room,
+)
from switch_core.db.stores.client_store import ClientStore
from switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStore
from switch_core.db.stores.external_user_store import ExternalUserStore
@@ -246,9 +252,9 @@ async def test_a_starting_bridge_is_recorded_in_the_rooms_it_carries(
elsewhere_id = await _make_bridged_room(session, bridge_id=other_bridge_id)
await session.commit()
- await service._record_bridge_memberships(bridge_id, client_id)
+ await service._record_bridge_memberships(bridge_id, TENANT_ZERO_ID, client_id)
# Again, because a bridge starts more than once.
- await service._record_bridge_memberships(bridge_id, client_id)
+ await service._record_bridge_memberships(bridge_id, TENANT_ZERO_ID, client_id)
async with session_factory() as session:
assert await RoomStore().get_client_ids(session, room_id) == [client_id]
diff --git a/core/tests/switch_core/bridges/collaboration/test_lifecycle_tenant_binding.py b/core/tests/switch_core/bridges/collaboration/test_lifecycle_tenant_binding.py
index 55ff174b9..70e204091 100644
--- a/core/tests/switch_core/bridges/collaboration/test_lifecycle_tenant_binding.py
+++ b/core/tests/switch_core/bridges/collaboration/test_lifecycle_tenant_binding.py
@@ -1,31 +1,39 @@
-"""`CollaborationBridgeLifecycleService.start_all` (CHOO-2623): starting every
-bridge at boot has no request behind it, and it fans out across every
-tenant's bridges in one pass — so the read that finds them has to be
-unscoped, and each bridge's own tenant is what gets bound, not the whole
-sweep. `start` spawns the bridge's long-lived task while that binding is
-still active, so the task keeps it for its own life (an asyncio task
-snapshots the context it was created under).
-
-This does not exercise a real bridge — `start` here is stubbed to record what
-tenant was bound when it was called, which is the only thing `start_all`
-itself is responsible for getting right.
+"""A bridge runs under its own tenant, whoever started it (CHOO-2623).
+
+The rule these pin: **nothing is ambient.** A bridge is started from two
+places — boot, with no tenant bound, and an HTTP request that edited its
+config, with the *requesting operator's* tenant bound — and an `asyncio.Task`
+snapshots the contextvars of whoever created it. So the tenant a bridge acts
+under must never be the one that happened to be bound when its task was made.
+
+`start` reads the bridge's own row unscoped to learn its tenant, hands that
+value to the task, and the task unbinds before doing anything. Each unit of
+work then binds the tenant it derived from a row: the bridge's for the
+bridge's own startup, the room's for anything room-scoped. `start_all` binds
+nothing at all, because there is nothing left for it to bind.
"""
from __future__ import annotations
+import asyncio
import uuid
+from typing import Any
from unittest.mock import MagicMock
+import pytest
+from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from switch_core.bridges.collaboration.adapter import CollaborationAdapter
from switch_core.bridges.collaboration.lifecycle_service import (
CollaborationBridgeLifecycleService,
)
-from switch_core.db.models import Client, CollaborationBridge, Tenant
+from switch_core.bridges.collaboration.models import BridgeConnectionConfig
+from switch_core.db.models import Client, ClientRoom, CollaborationBridge, Room, Tenant
from switch_core.db.stores.client_store import ClientStore
from switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStore
from switch_core.db.stores.room_store import RoomStore
-from switch_core.tenant_context import current_tenant_id
+from switch_core.tenant_context import current_tenant_id, tenant_scope
def _service(
@@ -47,12 +55,40 @@ def _service(
)
+class _StubAdapter(CollaborationAdapter):
+ """Concrete only so `start` can build one; no platform call is made."""
+
+ def __init__(self, *, config: Any) -> None:
+ self._config = config
+
+ async def start(self, *a: Any, **k: Any) -> Any: ...
+ async def stop(self, *a: Any, **k: Any) -> Any: ...
+ async def send_message(self, *a: Any, **k: Any) -> Any: ...
+ async def send_typing(self, *a: Any, **k: Any) -> Any: ...
+ async def update_message(self, *a: Any, **k: Any) -> Any: ...
+ async def delete_message(self, *a: Any, **k: Any) -> Any: ...
+ async def create_channel(self, *a: Any, **k: Any) -> Any: ...
+ async def get_channel_type(self, *a: Any, **k: Any) -> Any: ...
+ async def get_channel_agent_names(self, *a: Any, **k: Any) -> Any: ...
+ async def add_agents_to_channel(self, *a: Any, **k: Any) -> Any: ...
+ async def add_users_to_channel(self, *a: Any, **k: Any) -> Any: ...
+ async def create_agent_identity(self, *a: Any, **k: Any) -> Any: ...
+ async def remove_agent_identity(self, *a: Any, **k: Any) -> Any: ...
+ def translate_inbound(self, *a: Any, **k: Any) -> Any: ...
+ def translate_outbound(self, *a: Any, **k: Any) -> Any: ...
+
+
+class _StubConfig(BridgeConnectionConfig):
+ pass
+
+
async def _make_tenant(session: AsyncSession, tenant_id: str) -> None:
session.add(Tenant(id=tenant_id, slug=tenant_id, name=tenant_id))
await session.flush()
-async def _make_bridge(session: AsyncSession, *, tenant_id: str) -> str:
+async def _make_bridge(session: AsyncSession, *, tenant_id: str) -> tuple[str, str]:
+ """A bridge row and its client, in `tenant_id`. Returns (bridge, client)."""
client = Client(
tenant_id=tenant_id,
matrix_user_id=f"@bridge-{uuid.uuid4().hex[:8]}:test",
@@ -70,19 +106,22 @@ async def _make_bridge(session: AsyncSession, *, tenant_id: str) -> str:
)
session.add(bridge)
await session.flush()
- return bridge.id
+ return bridge.id, client.id
-async def test_start_all_binds_each_bridge_s_own_tenant_and_does_not_leak(
+async def test_start_all_binds_nothing_around_starting_a_bridge(
session_factory: async_sessionmaker[AsyncSession],
) -> None:
+ """The enumeration is unscoped and stays that way. Binding a tenant here
+ would only choose what each bridge's task snapshots, which is exactly the
+ dependency the design removed — `start` derives the tenant from the row."""
tenant_a = f"tenant-{uuid.uuid4().hex[:8]}"
tenant_b = f"tenant-{uuid.uuid4().hex[:8]}"
async with session_factory() as session:
await _make_tenant(session, tenant_a)
await _make_tenant(session, tenant_b)
- bridge_a = await _make_bridge(session, tenant_id=tenant_a)
- bridge_b = await _make_bridge(session, tenant_id=tenant_b)
+ bridge_a, _ = await _make_bridge(session, tenant_id=tenant_a)
+ bridge_b, _ = await _make_bridge(session, tenant_id=tenant_b)
await session.commit()
service = _service(session_factory)
@@ -93,28 +132,25 @@ async def test_start_all_binds_each_bridge_s_own_tenant_and_does_not_leak(
service.start = _fake_start # type: ignore[method-assign]
- # Nothing bound going in, and nothing bound coming out: start_all is
- # itself reached with no request behind it.
assert current_tenant_id() is None
await service.start_all()
assert current_tenant_id() is None
- assert seen == {bridge_a: tenant_a, bridge_b: tenant_b}
+ assert seen == {bridge_a: None, bridge_b: None}
-async def test_a_failing_bridge_still_releases_its_tenant_for_the_next_one(
+async def test_a_failing_bridge_leaves_nothing_bound_for_the_next_one(
session_factory: async_sessionmaker[AsyncSession],
) -> None:
- """start_all logs and continues past a bridge that fails to start
- (bridge_core.py's own behaviour); the tenant binding must not survive
- the exception either, or the next bridge in the loop inherits it."""
+ """start_all logs and continues past a bridge that fails to start; that
+ must not leave the loop in a different state than it began in."""
tenant_a = f"tenant-{uuid.uuid4().hex[:8]}"
tenant_b = f"tenant-{uuid.uuid4().hex[:8]}"
async with session_factory() as session:
await _make_tenant(session, tenant_a)
await _make_tenant(session, tenant_b)
- bridge_a = await _make_bridge(session, tenant_id=tenant_a)
- bridge_b = await _make_bridge(session, tenant_id=tenant_b)
+ bridge_a, _ = await _make_bridge(session, tenant_id=tenant_a)
+ bridge_b, _ = await _make_bridge(session, tenant_id=tenant_b)
await session.commit()
service = _service(session_factory)
@@ -129,5 +165,186 @@ async def test_a_failing_bridge_still_releases_its_tenant_for_the_next_one(
await service.start_all()
- assert seen == {bridge_a: tenant_a, bridge_b: tenant_b}
+ assert seen == {bridge_a: None, bridge_b: None}
assert current_tenant_id() is None
+
+
+async def test_start_hands_the_task_the_bridges_tenant_not_the_callers(
+ session_factory: async_sessionmaker[AsyncSession],
+) -> None:
+ """The restart path (`gateway/collaborations.py` edits a connection and
+ calls `restart`) reaches `start` with the requesting operator's tenant
+ bound. The tenant the bridge is then run under has to come off the bridge
+ row, not out of the request."""
+ bridge_tenant = f"tenant-{uuid.uuid4().hex[:8]}"
+ caller_tenant = f"tenant-{uuid.uuid4().hex[:8]}"
+ async with session_factory() as session:
+ await _make_tenant(session, bridge_tenant)
+ await _make_tenant(session, caller_tenant)
+ bridge_id, _ = await _make_bridge(session, tenant_id=bridge_tenant)
+ await session.commit()
+
+ service = _service(session_factory)
+ service.register_adapter("mattermost", _StubAdapter, _StubConfig)
+ handed: list[str] = []
+
+ async def _fake_run(bridge_id: str, tenant_id: str, *_: object) -> None:
+ handed.append(tenant_id)
+
+ service._run_bridge = _fake_run # type: ignore[method-assign]
+
+ with tenant_scope(caller_tenant):
+ await service.start(bridge_id)
+ # `start` spawns the task and returns; let it reach its first line.
+ await asyncio.sleep(0)
+
+ await service.stop(bridge_id)
+
+ assert handed == [bridge_tenant]
+
+
+async def test_the_bridge_task_unbinds_and_then_binds_per_unit_of_work(
+ session_factory: async_sessionmaker[AsyncSession],
+) -> None:
+ """The task body itself, created from a foreign tenant's context.
+
+ Three things at once, because they are one rule: the membership rows the
+ bridge records land in the bridge's tenant (not the creator's, which the
+ composite foreign keys would reject outright); the bridge's own startup
+ sees nothing bound, so anything it does has to bind for itself; and the
+ client loop that runs until shutdown sees nothing bound either, leaving
+ each delivery to bind the room it is for.
+ """
+ bridge_tenant = f"tenant-{uuid.uuid4().hex[:8]}"
+ caller_tenant = f"tenant-{uuid.uuid4().hex[:8]}"
+ async with session_factory() as session:
+ await _make_tenant(session, bridge_tenant)
+ await _make_tenant(session, caller_tenant)
+ bridge_id, client_id = await _make_bridge(session, tenant_id=bridge_tenant)
+ room = Room(
+ tenant_id=bridge_tenant,
+ matrix_room_id=f"!room-{uuid.uuid4().hex[:8]}:test",
+ name="a bridged room",
+ description="",
+ bridge_id=bridge_id,
+ external_channel_id="C1",
+ )
+ session.add(room)
+ await session.commit()
+ room_id = room.id
+
+ service = _service(session_factory)
+ seen: dict[str, str | None] = {}
+
+ class _Core:
+ async def start(self) -> None:
+ seen["core"] = current_tenant_id()
+
+ class _Client:
+ client_id = ""
+
+ async def start(self) -> None:
+ seen["client"] = current_tenant_id()
+
+ bridge_client = _Client()
+ bridge_client.client_id = client_id
+
+ leaked: list[str | None] = []
+ with tenant_scope(caller_tenant):
+ await service._run_bridge(
+ bridge_id,
+ bridge_tenant,
+ _Core(), # type: ignore[arg-type]
+ bridge_client, # type: ignore[arg-type]
+ )
+ leaked.append(current_tenant_id())
+
+ async with session_factory() as session:
+ rows = (
+ (
+ await session.execute(
+ select(ClientRoom.tenant_id).where(ClientRoom.room_id == room_id)
+ )
+ )
+ .scalars()
+ .all()
+ )
+
+ assert rows == [bridge_tenant], (
+ "the bridge recorded its membership under the tenant of whoever "
+ "started it rather than its own"
+ )
+ assert seen == {"core": None, "client": None}
+ assert leaked == [caller_tenant], (
+ "the task's unbinding escaped it and cleared its creator's context"
+ )
+
+
+async def test_a_host_resource_conflict_is_looked_for_across_every_tenant(
+ session_factory: async_sessionmaker[AsyncSession],
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Two tenants cannot share a Teams listen port or a Slack workspace: the
+ resource belongs to the host and the platform, not to a tenant. So the
+ check that refuses the second claimant has to see the first even when it
+ belongs to someone else — narrowing it to the caller's tenant would make
+ it miss precisely the case it exists for.
+
+ The conflict itself is asserted, and so is the tenant bound over the read
+ that finds it. Both, because today nothing filters by tenant: no policy
+ has landed, so a scoped read would still return every row and the
+ conflict alone would pass either way. The binding is the part that will
+ decide the answer once the policies bite.
+ """
+ incumbent_tenant = f"tenant-{uuid.uuid4().hex[:8]}"
+ newcomer_tenant = f"tenant-{uuid.uuid4().hex[:8]}"
+ async with session_factory() as session:
+ await _make_tenant(session, incumbent_tenant)
+ await _make_tenant(session, newcomer_tenant)
+ client = Client(
+ tenant_id=incumbent_tenant,
+ matrix_user_id=f"@bridge-{uuid.uuid4().hex[:8]}:test",
+ display_name="bridge client",
+ type="bridge",
+ )
+ session.add(client)
+ await session.flush()
+ session.add(
+ CollaborationBridge(
+ tenant_id=incumbent_tenant,
+ type="teams",
+ display_name="Their Teams",
+ client_id=client.id,
+ status="active",
+ connection_config={"listen_port": 3979},
+ )
+ )
+ await session.commit()
+
+ class _PortHoldingAdapter(_StubAdapter):
+ @staticmethod
+ def exclusive_resource(config: dict[str, Any]) -> str | None:
+ port = config.get("listen_port")
+ return f"port:{port}" if port else None
+
+ seen: list[str | None] = []
+ original = CollaborationBridgeStore.get_all
+
+ async def _spy(self, session): # type: ignore[no-untyped-def]
+ seen.append(current_tenant_id())
+ return await original(self, session)
+
+ monkeypatch.setattr(CollaborationBridgeStore, "get_all", _spy)
+
+ service = _service(session_factory)
+ service.register_adapter("teams", _PortHoldingAdapter, _StubConfig)
+
+ with tenant_scope(newcomer_tenant):
+ with pytest.raises(ValueError, match="already uses port:3979"):
+ await service._reject_resource_conflict("teams", {"listen_port": 3979})
+
+ assert seen == [None], (
+ "the conflict check read the stored bridges under the caller's "
+ "tenant; under row-level security it would not have seen the "
+ "incumbent and would have let both claim the port"
+ )
diff --git a/core/tests/switch_core/db/test_session_scope.py b/core/tests/switch_core/db/test_session_scope.py
index d8b038d5c..dd710ae6f 100644
--- a/core/tests/switch_core/db/test_session_scope.py
+++ b/core/tests/switch_core/db/test_session_scope.py
@@ -5,17 +5,21 @@ named ways background code may open a session with no request behind it.
session, so what these tests pin is the composition — bound inside the block,
released on the way out, even on an exception — rather than the binding
mechanics themselves, which `test_tenant_session_hook.py` already covers.
-`unscoped_session` does nothing at all beyond calling the factory; it is
-tested here for what it does *not* do — bind anything — and its callers are
-pinned separately, in `test_unscoped_session_allowlist.py`.
+`unscoped_session` is tested here for the one thing its name promises and its
+callers depend on: that a session opened through it has no tenant set, no
+matter what the caller had bound. Its callers are pinned separately, in
+`test_unscoped_session_allowlist.py`.
"""
from __future__ import annotations
+import uuid
+
import pytest
-from sqlalchemy import text
+from sqlalchemy import select, text
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from switch_core.db.models import Room, Tenant
from switch_core.db.session_scope import tenant_session, unscoped_session
from switch_core.tenant_context import current_tenant_id, tenant_scope
@@ -87,18 +91,31 @@ class TestUnscopedSession:
assert current_tenant_id() is None
assert await _current_setting(session) is None
- async def test_it_neither_binds_nor_clears_an_outer_tenant(
+ async def test_it_unbinds_an_outer_tenant_for_the_duration(
self, session_factory: async_sessionmaker[AsyncSession]
) -> None:
- """It is not a "no tenant" guarantee, only a "no new binding" one —
- the docstring is explicit that this is not force-unscoped. A caller
- already inside a bound context keeps seeing that context's tenant."""
+ """The whole contract. A caller already inside a bound context — a
+ request, an outer `tenant_scope`, a task that inherited one — still
+ gets a session with nothing set, because otherwise "unscoped" would
+ mean "scoped to whoever happened to call me" and the allowlist that
+ pins these call sites would be certifying a cross-tenant read that
+ never happens."""
with tenant_scope(TENANT_A):
async with unscoped_session(session_factory) as session:
- assert current_tenant_id() == TENANT_A
- assert await _current_setting(session) == TENANT_A
+ assert current_tenant_id() is None
+ assert await _current_setting(session) is None
+ assert current_tenant_id() == TENANT_A
assert current_tenant_id() is None
+ async def test_an_exception_still_restores_the_outer_tenant(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ with tenant_scope(TENANT_A):
+ with pytest.raises(RuntimeError, match="boom"):
+ async with unscoped_session(session_factory):
+ raise RuntimeError("boom")
+ assert current_tenant_id() == TENANT_A
+
async def test_current_tenant_id_is_unchanged_after_the_block(
self, session_factory: async_sessionmaker[AsyncSession]
) -> None:
@@ -106,3 +123,38 @@ class TestUnscopedSession:
async with unscoped_session(session_factory):
pass
assert current_tenant_id() is None
+
+ async def test_it_reads_rows_from_two_tenants_with_one_of_them_bound(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """What the callers actually rely on, stated in rows rather than in
+ contextvars: a sweep or an enumeration reached from inside a bound
+ context still sees the whole deployment.
+
+ Today no policy filters anything, so the `set_config` assertion is
+ what carries the weight — it is the value the policies will read once
+ they land. Both are asserted so this test keeps meaning the same thing
+ on either side of that change.
+ """
+ tenant_a = f"tenant-{uuid.uuid4().hex[:8]}"
+ tenant_b = f"tenant-{uuid.uuid4().hex[:8]}"
+ async with session_factory() as session:
+ for tenant_id in (tenant_a, tenant_b):
+ session.add(Tenant(id=tenant_id, slug=tenant_id, name=tenant_id))
+ await session.flush()
+ for tenant_id in (tenant_a, tenant_b):
+ session.add(
+ Room(
+ tenant_id=tenant_id,
+ matrix_room_id=f"!{tenant_id}:test",
+ name=tenant_id,
+ description="",
+ )
+ )
+ await session.commit()
+
+ with tenant_scope(tenant_a):
+ async with unscoped_session(session_factory) as session:
+ assert await _current_setting(session) is None
+ rows = (await session.execute(select(Room.tenant_id))).scalars().all()
+ assert {tenant_a, tenant_b} <= set(rows)
diff --git a/core/tests/switch_core/db/test_unscoped_session_allowlist.py b/core/tests/switch_core/db/test_unscoped_session_allowlist.py
index 865c94181..8f4329d0a 100644
--- a/core/tests/switch_core/db/test_unscoped_session_allowlist.py
+++ b/core/tests/switch_core/db/test_unscoped_session_allowlist.py
@@ -1,18 +1,25 @@
-"""`unscoped_session` (`db/session_scope.py`) is the fail-open hatch: a session
-with no tenant bound at all, for the handful of things that are legitimately
-cross-tenant — a sweep or lifecycle enumeration reading every row before
-fanning out per-row work, and startup seeding that runs before any tenant can
-be said to exist.
-
-Nothing stops a query on a session it opens from reading across every tenant
-there is, so its callers are the audit surface for that risk. This test pins
-them to an explicit allowlist, derived from the source tree rather than
-imports, so a module that only calls it conditionally or inside a string is
-still caught. A new module failing here is not a bug in the test: it means
-someone reached for the cross-tenant escape hatch, and either that is a
-deliberate, reviewable choice — in which case add the module to
-`_ALLOWED_MODULES` in the same change, saying why in the commit — or it is
-not, in which case use `tenant_session` instead.
+"""What may open a database session without a tenant, and who is allowed to.
+
+Two audit surfaces, and the second is the bigger one.
+
+**`unscoped_session`** (`db/session_scope.py`) is the declared fail-open hatch:
+it unbinds for the duration of the block, so a query on it reads across every
+tenant whether or not the caller had one bound. Its callers are named here.
+
+**A raw `session_factory()` call** is the undeclared one. It inherits whatever
+is ambient — the request's tenant on the request path, and *nothing at all* in
+background code, since the long-lived tasks deliberately unbind (see
+`tenant_context.no_tenant`). So a raw call in background code is unscoped in
+fact while saying nothing about it, which is strictly worse than the hatch
+that announces itself. There are ~197 of them across the modules below; that
+is the number this design has to work down, and pinning the module list is how
+a new one becomes a decision rather than a default.
+
+A module failing either check is not a bug in the test. It means someone
+opened a session without saying which tenant it is for, and either that is
+deliberate and reviewable — add the module below, saying why in the commit —
+or it is not, in which case use `tenant_session` and bind the tenant of the
+row the work is acting on.
"""
from __future__ import annotations
@@ -23,29 +30,81 @@ from pathlib import Path
import switch_core
# Every module allowed to call `unscoped_session`. Keep this short: it is the
-# whole list of places in the process that may read across every tenant.
+# whole list of places in the process that read across every tenant on purpose.
_ALLOWED_MODULES = {
# Startup seeding: the admin user and the agent-registration bootstrap
# owner/key are created before any tenant can be said to exist.
"switch_core.main",
# Reconciling every room's client membership at startup fans out across
- # every tenant's rooms; each room's own tenant is bound for its own work.
+ # every tenant's rooms; and `_load_room` is the bootstrap read that says
+ # which tenant a room is in before that tenant is bound.
"switch_core.room_service",
- # The runtime-state sweep reads every tenant's stale rows in one pass;
- # each row's own tenant is bound before anything is done with it.
+ # The runtime-state sweep reads every tenant's stale rows in one pass, and
+ # `register_agent_with_token` resolves a credential by its globally unique
+ # hash — the read that produces a tenant rather than one that uses it.
+ "switch_core.bridges.agent.protocol.service",
+ # Starting a bridge reads its own row to learn its tenant, from boot (with
+ # nothing bound) and from a request (with the wrong one bound); and
+ # `_reject_resource_conflict` must span tenants by definition, since two
+ # tenants claiming one Slack workspace is the collision it exists to catch.
+ "switch_core.bridges.collaboration.lifecycle_service",
+ # `_room_tenant`'s fallback: which tenant is this room in, asked when the
+ # answer is not already cached alongside the channel mapping.
+ "switch_core.bridges.collaboration.bridge_core",
+ # Same as the bridge lifecycle, for server-side connectors.
+ "switch_core.bridges.agent.server_connectors.lifecycle",
+ # Enumerating every tenant's clients at boot.
+ "switch_core.clients.client_lifecycle_service",
+ # A client's own task binds nothing, so resolving which agent it is — by
+ # globally unique client id — cannot be scoped to a guess.
+ "switch_core.clients.agent_client",
+ # `joined_rooms` (which rooms is this client in) and `_resolve_room_and_
+ # tenant` (which room, and so which tenant, is this transport id) are both
+ # lookups that produce a tenant rather than consume one.
+ "switch_core.transport.postgres",
+}
+
+# Every module allowed to open a session straight from the factory. Unlike the
+# list above this one is not short, and is not meant to be permanent: it is an
+# inventory of what has not been converted yet, plus the request-path modules
+# where inheriting the authenticated request's tenant is the correct answer.
+_RAW_SESSION_FACTORY_MODULES = {
+ # ── Request path: the session inherits the authenticated caller's tenant,
+ # bound by the auth dependency before the endpoint body runs. Correct as
+ # it stands; these are not to-dos.
+ "switch_core.gateway.auth",
+ "switch_core.gateway.dependencies",
+ "switch_core.bridges.agent.auth",
+ "switch_core.bridges.agent.dependencies",
+ "switch_core.bridges.agent.operations.context",
+ "switch_core.bridges.agent.operations.definitions",
+ "switch_core.bridges.agent.mediation",
+ # ── Reached only from inside a unit of work that has already bound the
+ # tenant of the row it is acting on — an inbound bridge event, a delivery,
+ # a sweep row, an authenticated agent operation.
"switch_core.bridges.agent.protocol.service",
- # Starting every collaboration bridge at boot reads every tenant's rows in
- # one pass; each bridge's own tenant is bound before it is started.
+ "switch_core.bridges.agent.commands",
+ "switch_core.bridges.collaboration.bridge_core",
"switch_core.bridges.collaboration.lifecycle_service",
- # Same as above, for server-side connectors.
"switch_core.bridges.agent.server_connectors.lifecycle",
- # Same as above, for the generic client registry (agent and admin
- # clients) started at boot.
+ "switch_core.clients.agent_client",
+ "switch_core.clients.admin_client",
"switch_core.clients.client_lifecycle_service",
+ "switch_core.provisioning.postgres",
+ "switch_core.room_service",
+ "switch_core.transport.postgres",
+ # ── Deployment-level startup, with no tenant to inherit and none bound.
+ # Rows these write land in tenant zero via the model default. Correct
+ # while one tenant exists; both need revisiting before a second.
+ "switch_core.main",
+ "switch_core.rooms_yaml",
}
_PACKAGE_ROOT = Path(switch_core.__file__).resolve().parent
+# The module that defines the helpers, not a caller of them.
+_DEFINITION = _PACKAGE_ROOT / "db" / "session_scope.py"
+
def _module_name(path: Path) -> str:
relative = path.relative_to(_PACKAGE_ROOT.parent)
@@ -55,41 +114,89 @@ def _module_name(path: Path) -> str:
return ".".join(parts)
-def _calls_unscoped_session(path: Path) -> bool:
- """Whether `path` contains a call to a function literally named
- `unscoped_session`, anywhere — a call, an alias, a re-export."""
- tree = ast.parse(path.read_text(), filename=str(path))
+def _local_names_for(tree: ast.AST, imported: str) -> set[str]:
+ """Every local name `imported` is reachable under in this module.
+
+ Its own name, plus any alias it was imported as. Without this the
+ detectors match a spelling rather than a function, and one `import … as`
+ walks straight past them.
+ """
+ names = {imported}
+ for node in ast.walk(tree):
+ if isinstance(node, ast.ImportFrom):
+ for alias in node.names:
+ if alias.name == imported and alias.asname:
+ names.add(alias.asname)
+ return names
+
+
+def _called_names(tree: ast.AST) -> set[str]:
+ """The name of every function called anywhere, attribute access included.
+
+ `foo()` yields "foo"; `self._session_factory()` yields "_session_factory";
+ `_state["session_factory"]()` yields "session_factory". Chains collapse to
+ their last element, which is what both detectors key on — a session
+ factory is reached through something far more often than as a bare name,
+ and the gateway reaches it through a module-level dict, which a
+ name-and-attribute-only walk misses entirely.
+ """
+ called = set()
for node in ast.walk(tree):
if not isinstance(node, ast.Call):
continue
func = node.func
- name = func.id if isinstance(func, ast.Name) else getattr(func, "attr", None)
- if name == "unscoped_session":
- return True
- return False
+ if isinstance(func, ast.Name):
+ called.add(func.id)
+ elif isinstance(func, ast.Attribute):
+ called.add(func.attr)
+ elif isinstance(func, ast.Subscript) and isinstance(func.slice, ast.Constant):
+ if isinstance(func.slice.value, str):
+ called.add(func.slice.value)
+ return called
-def _modules_calling_unscoped_session() -> set[str]:
+def _calls_unscoped_session(path: Path) -> bool:
+ """Whether `path` calls `unscoped_session`, under any local name."""
+ tree = ast.parse(path.read_text(), filename=str(path))
+ return bool(_called_names(tree) & _local_names_for(tree, "unscoped_session"))
+
+
+def _calls_session_factory(path: Path) -> bool:
+ """Whether `path` opens a session straight from a factory.
+
+ Matches any call whose name ends in `session_factory`, which is how every
+ such call in this tree is spelled — `session_factory()`,
+ `self._session_factory()`, `self.session_factory()`. `create_session_
+ factory` is excluded: it builds a factory rather than opening a session.
+ """
+ tree = ast.parse(path.read_text(), filename=str(path))
+ return any(
+ name.endswith("session_factory") and name != "create_session_factory"
+ for name in _called_names(tree)
+ )
+
+
+def _modules_where(predicate: object) -> set[str]:
found = set()
for path in _PACKAGE_ROOT.rglob("*.py"):
- if path.name == "session_scope.py" and path.parent.name == "db":
- continue # the definition itself, not a caller
- if _calls_unscoped_session(path):
+ if path == _DEFINITION:
+ continue
+ if predicate(path): # type: ignore[operator]
found.add(_module_name(path))
return found
def test_only_the_allowed_modules_call_unscoped_session() -> None:
- found = _modules_calling_unscoped_session()
+ found = _modules_where(_calls_unscoped_session)
unexpected = found - _ALLOWED_MODULES
assert not unexpected, (
f"{sorted(unexpected)} call unscoped_session but are not in "
- "_ALLOWED_MODULES in this test. That helper is the fail-open hatch "
- "for cross-tenant work (db/session_scope.py) — if this new call site "
- "is genuinely cross-tenant (a sweep, an enumeration, startup "
- "seeding), add its module to _ALLOWED_MODULES and say why in the "
- "commit; otherwise use tenant_session and bind the tenant the work "
- "is actually for."
+ "_ALLOWED_MODULES in this test. That helper unbinds the tenant for "
+ "the whole block (db/session_scope.py) — if this new call site is "
+ "genuinely cross-tenant (a sweep, an enumeration, a lookup that "
+ "answers *which* tenant something is in, startup seeding), add its "
+ "module to _ALLOWED_MODULES and say why in the commit; otherwise use "
+ "tenant_session and bind the tenant the work is actually for."
)
@@ -97,18 +204,46 @@ def test_the_allowlist_names_no_stale_module() -> None:
"""The other direction: every allowed module still actually uses it,
so the list stays the audit surface it claims to be rather than growing
entries nobody needs."""
- found = _modules_calling_unscoped_session()
+ found = _modules_where(_calls_unscoped_session)
stale = _ALLOWED_MODULES - found
assert not stale, f"{sorted(stale)} no longer call unscoped_session; remove them"
-class TestDetectionCatchesANewCaller:
- """The two tests above only prove today's tree is clean. This exercises
- the detector itself against a file that is not in the real source tree
- at all, so it stands on its own even if every real call site above is
- later removed."""
+def test_only_the_approved_modules_open_a_raw_session() -> None:
+ """The surface that actually matters, and the one this design is working
+ down. A raw factory call takes whatever tenant is ambient — which in
+ background code, now that the long-lived tasks unbind, is none."""
+ found = _modules_where(_calls_session_factory)
+ unexpected = found - _RAW_SESSION_FACTORY_MODULES
+ assert not unexpected, (
+ f"{sorted(unexpected)} open a session straight from the factory but "
+ "are not in _RAW_SESSION_FACTORY_MODULES in this test. Such a session "
+ "inherits whatever tenant is bound, which in background code is "
+ "nothing at all. Say which you mean: tenant_session(factory, "
+ "<the row's tenant>) for work that acts on one tenant's rows, "
+ "unscoped_session(factory) for work that genuinely spans them. If "
+ "the call really is reached only from an authenticated request, add "
+ "the module below and say so in the commit."
+ )
+
- def test_a_plain_call_is_detected(self, tmp_path: Path) -> None:
+def test_the_raw_session_list_names_no_stale_module() -> None:
+ found = _modules_where(_calls_session_factory)
+ stale = _RAW_SESSION_FACTORY_MODULES - found
+ assert not stale, (
+ f"{sorted(stale)} no longer open a raw session — remove them from "
+ "_RAW_SESSION_FACTORY_MODULES. Shrinking this list is the point; "
+ "leaving converted modules in it hides the progress."
+ )
+
+
+class TestTheDetectorsCatchANewCaller:
+ """The four tests above only prove today's tree is clean. These exercise
+ the detectors against files that are not in the real source tree at all,
+ so they stand on their own even if every real call site is later
+ removed."""
+
+ def test_a_plain_unscoped_call_is_detected(self, tmp_path: Path) -> None:
new_caller = tmp_path / "a_new_background_job.py"
new_caller.write_text(
"async def sweep(session_factory):\n"
@@ -117,7 +252,10 @@ class TestDetectionCatchesANewCaller:
)
assert _calls_unscoped_session(new_caller)
- def test_an_aliased_import_is_still_detected(self, tmp_path: Path) -> None:
+ def test_an_aliased_import_is_detected(self, tmp_path: Path) -> None:
+ """`import … as` must not walk past the check. The detector resolves
+ the local name the helper was bound to rather than matching the
+ spelling `unscoped_session`."""
new_caller = tmp_path / "a_new_background_job.py"
new_caller.write_text(
"from switch_core.db.session_scope import unscoped_session as us\n"
@@ -125,21 +263,57 @@ class TestDetectionCatchesANewCaller:
" async with us(session_factory) as session:\n"
" ...\n"
)
- assert not _calls_unscoped_session(new_caller), (
- "an aliased import is a known gap: the detector matches the "
- "literal name unscoped_session, not what it resolves to"
- )
+ assert _calls_unscoped_session(new_caller)
def test_a_module_with_no_call_is_not_flagged(self, tmp_path: Path) -> None:
clean = tmp_path / "an_unrelated_module.py"
- clean.write_text("async def do_work(session_factory):\n ...\n")
+ clean.write_text("async def do_work(session):\n ...\n")
assert not _calls_unscoped_session(clean)
+ assert not _calls_session_factory(clean)
+
+ def test_a_bare_factory_call_is_detected(self, tmp_path: Path) -> None:
+ new_caller = tmp_path / "a_new_background_job.py"
+ new_caller.write_text(
+ "async def sweep(session_factory):\n"
+ " async with session_factory() as session:\n"
+ " ...\n"
+ )
+ assert _calls_session_factory(new_caller)
+
+ def test_a_factory_reached_through_self_is_detected(self, tmp_path: Path) -> None:
+ new_caller = tmp_path / "a_new_service.py"
+ new_caller.write_text(
+ "class Service:\n"
+ " async def run(self):\n"
+ " async with self._session_factory() as session:\n"
+ " ...\n"
+ )
+ assert _calls_session_factory(new_caller)
+
+ def test_a_factory_reached_through_a_dict_is_detected(self, tmp_path: Path) -> None:
+ """How the gateway holds its factory. Worth its own case: a walk over
+ names and attributes alone reports this module as clean."""
+ new_caller = tmp_path / "a_new_dependency.py"
+ new_caller.write_text(
+ "_state = {}\n"
+ "async def get_session():\n"
+ ' async with _state["session_factory"]() as session:\n'
+ " yield session\n"
+ )
+ assert _calls_session_factory(new_caller)
+
+ def test_building_a_factory_is_not_opening_a_session(self, tmp_path: Path) -> None:
+ clean = tmp_path / "wiring.py"
+ clean.write_text(
+ "def wire(engine):\n return create_session_factory(engine)\n"
+ )
+ assert not _calls_session_factory(clean)
def test_the_allowlist_check_would_fail_for_a_hypothetical_new_caller(self) -> None:
"""Simulates what `test_only_the_allowed_modules_call_unscoped_session`
does, against a found-set that includes a module nobody added to
`_ALLOWED_MODULES` — pinning that the check actually fails rather
than, say, silently ignoring an unknown module."""
- found = _modules_calling_unscoped_session() | {"switch_core.a_new_sweep"}
+ found = _modules_where(_calls_unscoped_session) | {"switch_core.a_new_sweep"}
unexpected = found - _ALLOWED_MODULES
assert unexpected == {"switch_core.a_new_sweep"}
diff --git a/core/tests/switch_core/test_room_service_change_bridge.py b/core/tests/switch_core/test_room_service_change_bridge.py
index f4262e501..7e077fee4 100644
--- a/core/tests/switch_core/test_room_service_change_bridge.py
+++ b/core/tests/switch_core/test_room_service_change_bridge.py
@@ -100,7 +100,11 @@ class _FakeBridgeCore:
self.adapter = _FakeAdapter(events, new_channel_id)
def add_room_mapping(
- self, room_id: str, matrix_room_id: str, external_channel_id: str
+ self,
+ room_id: str,
+ matrix_room_id: str,
+ external_channel_id: str,
+ tenant_id: str,
) -> None:
self._events.append(("add_room_mapping", room_id, external_channel_id))
diff --git a/core/tests/switch_core/transport/test_postgres_transport.py b/core/tests/switch_core/transport/test_postgres_transport.py
index fb745d2c6..ea0b86e2e 100644
--- a/core/tests/switch_core/transport/test_postgres_transport.py
+++ b/core/tests/switch_core/transport/test_postgres_transport.py
@@ -17,13 +17,14 @@ import uuid
from collections.abc import Iterator
import pytest
+from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
-from switch_core.db.models import Client, Room, Tenant
+from switch_core.db.models import Client, ClientRoom, Message, Room, Tenant
from switch_core.db.stores.media_store import MediaStore
from switch_core.db.stores.message_store import MessageStore
from switch_core.db.stores.room_store import RoomStore
-from switch_core.tenant_context import current_tenant_id
+from switch_core.tenant_context import current_tenant_id, tenant_scope
from switch_core.transport import (
InboundCustomEvent,
InboundMedia,
@@ -931,3 +932,239 @@ class TestDeliveryBindsTheRoomsTenant:
assert all(tenant == tenant_id for tenant in seen)
# Bound only for the read itself, not left dangling on the process.
assert current_tenant_id() is None
+
+
+class TestATransportOwnsNoTenantOfItsOwn:
+ """A transport is not a single-tenant actor, and CHOO-2623 stops it
+ behaving like one.
+
+ Its task binds nothing: `ClientLifecycleService` unbinds before running a
+ client, so anything the transport does under an inherited tenant would be
+ doing it under the tenant of whoever happened to create the task — boot,
+ a gateway request, or the inbound bridge message that minted a puppet
+ mid-conversation. Two consequences are pinned here: the lookup that says
+ which rooms this client is in runs with nothing bound, and each delivery
+ binds the tenant of the room it is for.
+ """
+
+ @pytest.fixture(autouse=True)
+ def _cleanup(self) -> Iterator[None]:
+ self._tasks: list[asyncio.Task] = []
+ yield
+ for task in self._tasks:
+ task.cancel()
+
+ async def test_the_room_list_is_read_with_no_tenant_bound(
+ self,
+ session_factory: async_sessionmaker[AsyncSession],
+ monkeypatch: pytest.MonkeyPatch,
+ ) -> None:
+ """`joined_rooms` decides, once, what this client will ever hear. A
+ tenant bound over that read narrows it to a subset with no error to
+ say so — the client is simply deaf everywhere else, forever. So it
+ must run unscoped even when reached from a bound context."""
+ tenant_id = f"tenant-{uuid.uuid4().hex[:8]}"
+ async with session_factory() as session:
+ session.add(Tenant(id=tenant_id, slug=tenant_id, name=tenant_id))
+ await session.flush()
+ suffix = uuid.uuid4().hex[:8]
+ client = Client(
+ tenant_id=tenant_id,
+ matrix_user_id=f"@sys-{suffix}:test",
+ display_name="admin",
+ type="admin",
+ )
+ session.add(client)
+ room = Room(
+ tenant_id=tenant_id,
+ matrix_room_id=f"!room-{suffix}:test",
+ name="a room",
+ description="",
+ )
+ session.add(room)
+ await session.flush()
+ session.add(
+ ClientRoom(tenant_id=tenant_id, client_id=client.id, room_id=room.id)
+ )
+ await session.commit()
+ client_id, user_id = client.id, client.matrix_user_id
+ transport_room_id = room.matrix_room_id
+
+ seen: list[str | None] = []
+ original = RoomStore.get_for_client
+
+ async def _spy(self, session, client_id): # type: ignore[no-untyped-def]
+ seen.append(current_tenant_id())
+ return await original(self, session, client_id)
+
+ monkeypatch.setattr(RoomStore, "get_for_client", _spy)
+
+ transport = _transport(session_factory, client_id=client_id, user_id=user_id)
+ # Stands in for a task that inherited a tenant it has no business
+ # acting under — a bridge restart, a puppet minted mid-conversation.
+ with tenant_scope("some-other-tenant"):
+ rooms = await transport.joined_rooms()
+
+ assert rooms == [transport_room_id]
+ assert seen == [None], (
+ "joined_rooms inherited a tenant; under row-level security it "
+ "would have returned a subset of this client's rooms and gone "
+ "silent in the rest"
+ )
+
+ async def test_each_room_is_delivered_under_its_own_tenant(
+ self,
+ session_factory: async_sessionmaker[AsyncSession],
+ monkeypatch: pytest.MonkeyPatch,
+ ) -> None:
+ """One transport, two rooms, two tenants — the shape a reused puppet
+ takes. The client whose transport this is belongs to one of the two
+ tenants, and that must not decide how the other room is read.
+
+ Membership is only recorded for the room in the transport's own
+ tenant, because `client_rooms` carries composite foreign keys to both
+ `clients` and `rooms` and so cannot join a client to a room in another
+ tenant at all — see
+ `test_the_schema_forbids_a_client_row_in_another_tenants_room`. The
+ watch and the delivery do not go through membership, which is what
+ makes the two-tenant case reachable here.
+ """
+ tenant_a = f"tenant-{uuid.uuid4().hex[:8]}"
+ tenant_b = f"tenant-{uuid.uuid4().hex[:8]}"
+ suffix = uuid.uuid4().hex[:8]
+ async with session_factory() as session:
+ for tenant_id in (tenant_a, tenant_b):
+ session.add(Tenant(id=tenant_id, slug=tenant_id, name=tenant_id))
+ await session.flush()
+ puppet = Client(
+ tenant_id=tenant_a,
+ matrix_user_id=f"@puppet-{suffix}:test",
+ display_name="puppet",
+ type="user",
+ )
+ speaker_b = Client(
+ tenant_id=tenant_b,
+ matrix_user_id=f"@speaker-{suffix}:test",
+ display_name="someone",
+ type="agent",
+ )
+ session.add_all([puppet, speaker_b])
+ room_a = Room(
+ tenant_id=tenant_a,
+ matrix_room_id=f"!a-{suffix}:test",
+ name="room a",
+ description="",
+ )
+ room_b = Room(
+ tenant_id=tenant_b,
+ matrix_room_id=f"!b-{suffix}:test",
+ name="room b",
+ description="",
+ )
+ session.add_all([room_a, room_b])
+ await session.commit()
+ ids = {
+ room_a.id: tenant_a,
+ room_b.id: tenant_b,
+ }
+ mxid_a, mxid_b = room_a.matrix_room_id, room_b.matrix_room_id
+ room_b_id = room_b.id
+ speaker_b_id, speaker_b_mxid = speaker_b.id, speaker_b.matrix_user_id
+ client_id, user_id = puppet.id, puppet.matrix_user_id
+
+ seen: dict[str, list[str | None]] = {}
+ original = MessageStore.list_for_room
+
+ async def _spy(self, session, room_id, **kwargs): # type: ignore[no-untyped-def]
+ seen.setdefault(room_id, []).append(current_tenant_id())
+ return await original(self, session, room_id, **kwargs)
+
+ monkeypatch.setattr(MessageStore, "list_for_room", _spy)
+
+ listener = _FakeListener()
+ received = _Received()
+ transport = _transport(
+ session_factory, client_id=client_id, user_id=user_id, listener=listener
+ )
+ transport.register_handlers(received.handlers())
+ await transport.join_room(mxid_a)
+ self._tasks.append(asyncio.create_task(transport.receive_forever()))
+ await _watched_room(transport)
+ await transport._watch(mxid_b)
+
+ await transport.send_message(mxid_a, "in a", sender_name="puppet")
+ # Written as a client of tenant B: a message in room B carries room
+ # B's tenant, and the composite key to `clients` will not let a
+ # tenant-A client be its sender.
+ async with session_factory() as session:
+ await MessageStore().create(
+ session,
+ Message(
+ tenant_id=tenant_b,
+ room_id=room_b_id,
+ transport_event_id=f"sw_{uuid.uuid4().hex}",
+ sender_id=speaker_b_mxid,
+ sender_client_id=speaker_b_id,
+ sender_name="someone",
+ event_type="m.room.message",
+ msgtype="m.text",
+ body="in b",
+ formatted_body=None,
+ thread_root_event_id=None,
+ content={"body": "in b", "msgtype": "m.text"},
+ ),
+ [],
+ )
+ await session.commit()
+
+ for room_id in ids:
+ await listener.announce(room_id)
+
+ assert {getattr(e, "body", None) for e in received.events} == {"in a", "in b"}
+ assert set(seen) == set(ids), "a room was never read"
+ for room_id, tenants in seen.items():
+ assert tenants and all(t == ids[room_id] for t in tenants), (
+ f"room {room_id} was read under {tenants}, not {ids[room_id]}"
+ )
+ assert current_tenant_id() is None
+
+
+async def test_the_schema_forbids_a_client_row_in_another_tenants_room(
+ session_factory: async_sessionmaker[AsyncSession],
+) -> None:
+ """Why "one system client, a member of every tenant's rooms" is not a
+ state this deployment can reach, and so not a case the transport has to
+ handle: `client_rooms` keys to both `clients` and `rooms` on `tenant_id`,
+ so membership cannot cross a tenant boundary. The system client is one
+ row per tenant, which is what the Phase 1 design says it becomes.
+
+ Pinned as a test rather than argued in a comment, because everything the
+ transport does about its room list rests on it.
+ """
+ tenant_a = f"tenant-{uuid.uuid4().hex[:8]}"
+ tenant_b = f"tenant-{uuid.uuid4().hex[:8]}"
+ suffix = uuid.uuid4().hex[:8]
+ async with session_factory() as session:
+ for tenant_id in (tenant_a, tenant_b):
+ session.add(Tenant(id=tenant_id, slug=tenant_id, name=tenant_id))
+ await session.flush()
+ client = Client(
+ tenant_id=tenant_a,
+ matrix_user_id=f"@sys-{suffix}:test",
+ display_name="admin",
+ type="admin",
+ )
+ session.add(client)
+ room = Room(
+ tenant_id=tenant_b,
+ matrix_room_id=f"!b-{suffix}:test",
+ name="room b",
+ description="",
+ )
+ session.add(room)
+ await session.flush()
+ session.add(
+ ClientRoom(tenant_id=tenant_a, client_id=client.id, room_id=room.id)
+ )
+ with pytest.raises(IntegrityError):
+ await session.commit()
diff --git a/docs/old/multi-tenancy-phase1-db.md b/docs/old/multi-tenancy-phase1-db.md
index 3a17e9ce4..7ddd1d223 100644
--- a/docs/old/multi-tenancy-phase1-db.md
+++ b/docs/old/multi-tenancy-phase1-db.md
@@ -16,8 +16,12 @@ when" were all split out into a later change.
what was actually implemented, which differs from what it originally proposed —
an event hook rather than a dependency at every call site, for reasons given
there. **The background half of it has since been built too** — the roughly
-206 session sites outside the request path now bind a tenant, described where
-"Setting the tenant" talks about background work below. Read the remaining
+197 session sites outside the request path now bind a tenant at each unit of
+work, described where "Setting the tenant" talks about background work below.
+That section also records the model that was tried first, of binding once per
+long-lived task, and the four ways it leaked; it is written up rather than
+deleted because the reasoning that made it look right is easy to arrive at
+twice. Read the remaining
sections as the design those later changes implement rather than as a
description of what is running today; "What Phase 1 does not close" says which
gaps are this migration's and which belong to the deferred work — row-level
@@ -356,41 +360,105 @@ silently discarded a password change. Resolution needs the subject id, not a
the session the endpoint actually commits.
**Background work is not a short list, and it has since been closed.** There
-were roughly 206 places that opened a session from the factory directly, with
-no request behind them. They fall into three shapes, each handled differently
-rather than by one helper covering all of them:
-
-- **Acting for a room** — the delivery loop (`transport/postgres.py`), most of
- `room_service.py`, the collaboration bridges' inbound and outbound handling
- (`bridges/collaboration/bridge_core.py`). Each derives the tenant from the
- room the unit of work is actually for — one delivery, one inbound event, one
- membership change — rather than caching it, because a client or a bridge is
- not guaranteed to act for only one tenant over its life. Resolving which
- room (and so which tenant) a unit of work is for is itself unscoped by
- necessity, the same bootstrap as resolving a principal below; each of these
- files caches the answer per room id once resolved, since a room's tenant
- cannot change, the same way each already cached the room's own id.
-- **Acting for a bridge or connector** — `bridges/collaboration/lifecycle_service.py`
- and `bridges/agent/server_connectors/lifecycle.py` bind the bridge's or
- connector's own tenant once, around starting its long-lived task; the task
- keeps it for its life because an `asyncio.Task` snapshots the contextvar
- state it was created under.
-- **Acting for the deployment** — startup seeding (`main.py`), the
- runtime-state sweep (`ProtocolService.sweep_runtime_states`), and the
- lifecycle enumerations that read every row before fanning out
- (`start_all` on both lifecycle services above, and on
- `ClientLifecycleService`). These read cross-tenant by nature; where they
- then act per row, they bind that row's own tenant rather than the tenant of
- the whole pass.
+are roughly 197 places that open a session from the factory directly, with no
+request behind them. One rule covers all of them:
+
+> **Nothing is ambient. Every unit of background work binds the tenant of the
+> row it is acting on, at the point it acts. Long-lived tasks bind nothing for
+> their lifetime. A lookup that must span tenants uses a helper that genuinely
+> unbinds.**
+
+**The first attempt at this had a different rule, and it was wrong.** It said a
+long-lived task "acts for exactly one bridge, so it can bind once for the
+task's lifetime", and leaned on an `asyncio.Task` snapshotting the contextvars
+of whoever created it. Four things went wrong, and they are one thing:
+
+- **Who creates the task is not who owns it.** A bridge is started at boot,
+ with nothing bound, *and* from an HTTP request that edited its connection
+ (`gateway/collaborations.py` calls `restart`), with the requesting
+ operator's tenant bound. Bind-at-creation makes the bridge spend its entire
+ life acting as whoever last restarted it.
+- **A long-lived object is not a single-tenant actor.** A client's transport
+ reads which rooms it is in — a lookup keyed by a globally unique client id —
+ and then works one room at a time. A puppet minted for one person on a
+ bridge is reused for every room they ever speak in. A boot-time tenant on
+ either is a value that happens to be right until it is not, with no error
+ when it turns.
+- **A cache that is only filled at startup is empty for everything created
+ after startup.** The bridge's room→tenant map was loaded at boot and not
+ written by `add_room_mapping`, so every room created later missed it and
+ fell back to a database read under whatever was ambient — which on the
+ inbound path is the very thing being asked.
+- **Not every task inherits anything.** Mattermost's websocket runs on an OS
+ thread and dispatches with `asyncio.run_coroutine_threadsafe`, which starts
+ the coroutine in an *empty* context. Under bind-at-creation, an auto-created
+ room landed in tenant zero on Mattermost and in the bridge's tenant
+ everywhere else — the platform decided the tenant. Binding at the inbound
+ choke point instead makes the platform irrelevant, which is the property
+ worth having.
+
+So what is built now is:
+
+- **Long-lived tasks unbind first.** `CollaborationBridgeLifecycleService._run_bridge`,
+ `ClientLifecycleService._run_client`, `BridgeCore._run_agent_identities` and
+ the connectors' per-agent poll loop each enter `tenant_context.no_tenant()`
+ as their first act. Nothing inside them can read a tenant it did not derive,
+ and once the policies land, a unit of work that forgot to bind reads nothing
+ rather than reading someone else's rows.
+- **Each unit of work binds the row it is acting on.** A delivery binds the
+ room's tenant (`transport/postgres.py`); an inbound platform event binds the
+ room's, or — when the handler is about to auto-create the room — the
+ bridge's, at the single choke point every handler passes through
+ (`BridgeCore._traced`); a membership change binds the room's
+ (`room_service.py`); a sweep row binds its own, for the *whole* of that
+ row's work including the event emitted at the end
+ (`ProtocolService.sweep_runtime_states`); one poll and the events it
+ returns bind the connector's (`server_connectors/core.py`).
+- **An object may know its tenant without binding it.** `BridgeCore` holds
+ `bridge_tenant_id` and `ConnectorCore` holds `connector_tenant_id`, read
+ once from the row they are the runtime for. Knowing is not binding: the
+ value is bound around a piece of work and released, never held open. Rooms
+ cannot disagree with their bridge in any case — `rooms` carries a composite
+ foreign key to `collaboration_bridges` on `tenant_id` — but room-scoped work
+ still binds the room's own tenant rather than relying on that.
+- **The lookups that produce a tenant are unscoped, not scoped to a guess.**
+ Which room is this transport id? Which rooms is this client in? Which agent
+ is this client? Which tenant is this bridge in? Each is asked before the
+ answer is known, so binding one first is either a tautology or, under
+ policies, a false "not found". These use `unscoped_session`, the same as the
+ credential lookups in the bootstrap section below.
Two named helpers carry this: `tenant_session` (`db/session_scope.py`) binds a
-given tenant and opens a session; `unscoped_session` opens one with nothing
-bound at all — the fail-open hatch, named so a reader can tell at the call site
-which one is meant, and used only by the "acting for the deployment" sites
-above. `tests/switch_core/db/test_unscoped_session_allowlist.py` pins the
-modules allowed to call it, deriving the list from the source tree rather than
-from imports, so a new caller is a deliberate, reviewed act rather than an
-accident.
+given tenant and opens a session; `unscoped_session` **unbinds** for the
+duration of the block and opens one with nothing set, restoring the caller's
+binding on the way out. The unbinding is the point and was the second thing
+the first attempt got wrong: a helper that only *named* the intent while
+inheriting whatever was ambient has the hook stamp the caller's tenant onto
+the transaction, so the cross-tenant read the call site asked for is silently
+a single-tenant one — and the allowlist pinning it certifies a lie.
+
+`tests/switch_core/db/test_unscoped_session_allowlist.py` pins two lists,
+derived from the source tree rather than from imports and resolving aliased
+imports rather than matching a spelling. The first is who may call
+`unscoped_session`. The second is the one that matters more: **which modules
+may open a session straight from the factory at all.** A raw call inherits
+whatever is ambient, which in background code is now nothing — so it is
+unscoped in fact while declaring nothing, strictly worse than the hatch that
+announces itself. Those ~197 call sites across nineteen modules are the
+inventory this design has to work down; pinning the module list makes a new
+one a decision rather than a default.
+
+**Cost, stated rather than hidden.** The hook adds one `SELECT set_config(…)`
+round trip per transaction, which on the delivery path is roughly per message
+once a handler writes. Measured against the test container (Postgres 16 over
+a colima socket, 400 single-statement transactions per arm, two runs): mean
+0.95–1.20 ms unbound against 1.30–1.41 ms bound, a delta of **0.20–0.36 ms per
+transaction**. That environment's round trip is slower than a deployed one's,
+so read it as an upper bound on the shape rather than a production figure —
+but it is one extra round trip per transaction, and on a chatty room that is
+one extra round trip per message. If it ever matters, the fix is to widen the
+unit of work rather than to skip the hook: fewer, larger transactions pay it
+fewer times, and skipping it is how the prior-art bugs happened.
**Writes fill the column automatically.** `tenant_id` gets a Python-side
default reading the request's tenant, so ordinary ORM inserts need no change
@@ -435,6 +503,19 @@ discovered it, so a handler's own downstream session opens (posting to a
bridge, gating a command) are covered too — they run in the same task, and the
binding is a contextvar, not something tied to one session object.
+One thing the transport deliberately does *not* do is treat its client as
+belonging to a tenant. `joined_rooms` is unscoped, because it runs once and
+decides what that client will ever hear: a tenant over that read returns a
+subset with no error to say so, and the client is then silently deaf in every
+room it did not see, forever. The client id it reads by is globally unique, so
+there is nothing for a tenant to disambiguate. (A client cannot in fact be a
+member of another tenant's room — `client_rooms` carries composite foreign
+keys to both `clients` and `rooms`, so the system client is one row per tenant
+rather than one row in every tenant's rooms. The transport does not lean on
+that; it is pinned by a test in
+`tests/switch_core/transport/test_postgres_transport.py` because the shape of
+the room list rests on it.)
+
Two exceptions to the uniform rule, in full:
1. **`api_keys.key_hash` stays globally unique**, because authentication