Enterprise agent platform for building, deploying, and operating AI teammates.
import ast
import importlib
import inspect
from datetime import datetime
from types import SimpleNamespace
from unittest.mock import MagicMock, call, patch
import pytest
from fastapi import HTTPException
from pydantic import ValidationError
from sqlalchemy import create_engine, event
from sqlalchemy.orm import Session, sessionmaker
from xagent.web.api.custom_api import (
CustomApiCreate,
CustomApiResponse,
CustomApiUpdate,
_process_env_vars,
create_custom_api,
delete_custom_api,
get_custom_api,
list_custom_apis,
update_custom_api,
)
from xagent.web.models.custom_api import CustomApi, UserCustomApi
from xagent.web.models.database import Base
from xagent.web.models.user import User
from xagent.web.services.connector_team_scope import (
ConnectorDeleteDecision,
set_connector_team_hooks,
)
_SEAM_MODULE = "xagent.web.api.custom_api"
# Every top-level function in this module that can reach an installed
# connector team hook. Written out so the discovery below cannot pass by
# finding nothing.
_SEAM_REACHING_FUNCTIONS = {
"_resolve_custom_api_for_request",
"_recheck_team_access_under_definition_lock",
"get_custom_api",
"update_custom_api",
"delete_custom_api",
}
def _functions_reaching_the_connector_seam() -> dict[str, ast.AST]:
"""Every top-level function in this module that can reach an installed
connector team hook.
Seeded on the functions that import ``connector_team_scope`` in their own
body, which is how every call site in this module reaches the seam, then
closed transitively over plain-name calls, because one route reaches it
only through a helper (``get_custom_api`` through
``_resolve_custom_api_for_request``). A seed-only check would miss exactly
the route this test exists for.
"""
module = importlib.import_module(_SEAM_MODULE)
tree = ast.parse(inspect.getsource(module))
functions = {
node.name: node
for node in tree.body
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
}
reaching = {
name
for name, node in functions.items()
if any(
isinstance(child, ast.ImportFrom)
and child.module is not None
and child.module.endswith("connector_team_scope")
for child in ast.walk(node)
)
}
changed = True
while changed:
changed = False
for name, node in functions.items():
if name in reaching:
continue
called = {
child.func.id
for child in ast.walk(node)
if isinstance(child, ast.Call) and isinstance(child.func, ast.Name)
}
if called & reaching:
reaching.add(name)
changed = True
return {name: functions[name] for name in reaching}
def test_the_discovery_of_seam_reaching_functions_is_not_vacuous():
"""Pins the enumeration itself, so the assertion below cannot pass by
finding nothing."""
assert set(_functions_reaching_the_connector_seam()) == _SEAM_REACHING_FUNCTIONS
def test_no_function_that_reaches_the_connector_seam_is_a_coroutine():
"""An installed connector team hook may be slow -- the seam is designed on
the assumption that the installing application answers from its own
tables. FastAPI runs a coroutine route on the event loop thread itself, so
a slow hook call inside an ``async def`` stalls every other request the
process is serving, not just this one; a plain ``def`` goes to the
threadpool instead, where a slow call occupies one worker.
Enumerated by reachability rather than by a hand-written list of routes:
an earlier fix for this same risk class swept siblings along the "takes a
row lock" axis and therefore missed a route that calls a hook without
taking one.
"""
offenders = [
name
for name, node in _functions_reaching_the_connector_seam().items()
if isinstance(node, ast.AsyncFunctionDef)
]
assert offenders == [], (
"these functions can reach an installed connector team hook while "
f"running on the event loop thread: {sorted(offenders)}"
)
def test_custom_api_models_env_validation():
# Valid creation
api = CustomApiCreate(name="test", env={"key": "val"})
assert api.env == {"key": "val"}
# Missing env is allowed (handled by database default or just none)
api = CustomApiCreate(name="test")
assert api.env is None
# Empty env dict is allowed to clear secrets
api_empty = CustomApiCreate(name="test", env={})
assert api_empty.env == {}
# Same for update
api_update = CustomApiUpdate(name="test", env={})
assert api_update.env == {}
runtime_api = CustomApiCreate(
name="runtime",
runtime_input_schema={"context": {"account_id": {"type": "string"}}},
runtime_bindings=[
{
"source": {"input_type": "context", "key": "account_id"},
"target": {"target_type": "headers", "key": "X-Account-ID"},
}
],
)
assert runtime_api.runtime_input_schema == {
"context": {"account_id": {"type": "string"}}
}
assert runtime_api.runtime_bindings is not None
def test_custom_api_response_requires_runtime_projection_fields():
"""Custom API response mappers must project every persisted runtime field."""
response_data = {
"id": 1,
"user_id": 1,
"name": "runtime",
"description": None,
"url": None,
"method": "GET",
"headers": None,
"body": None,
"env": None,
"is_active": True,
"is_default": False,
"created_at": "2026-07-14T00:00:00",
"updated_at": "2026-07-14T00:00:00",
}
with pytest.raises(ValidationError) as exc_info:
CustomApiResponse(**response_data)
missing_fields = {error["loc"] for error in exc_info.value.errors()}
assert missing_fields == {
("runtime_input_schema",),
("runtime_bindings",),
("allow_delegated_authorization",),
}
def test_process_env_vars():
with patch(
"xagent.web.api.custom_api.encrypt_value", side_effect=lambda x: f"enc_{x}"
):
# Test None
assert _process_env_vars(None) is None
# Test encrypting new values
env = {"key1": "val1", "key2": "val2"}
res = _process_env_vars(env)
assert res == {"key1": "enc_val1", "key2": "enc_val2"}
# Test keeping masked values
env_with_mask = {"key1": "********", "key3": "val3"}
existing = {"key1": "enc_old1", "key2": "enc_old2"}
res_masked = _process_env_vars(env_with_mask, existing)
assert res_masked == {"key1": "enc_old1", "key3": "enc_val3"}
# A mask cannot be moved to a new key identity.
with pytest.raises(ValueError, match="new_key"):
_process_env_vars({"new_key": "********"}, existing)
@pytest.mark.asyncio
async def test_list_custom_apis():
db = MagicMock(spec=Session)
user = User(id=1)
mock_api = CustomApi(
id=10, name="test_api", created_at=datetime.now(), updated_at=datetime.now()
)
mock_user_api = UserCustomApi(
user_id=1,
custom_api_id=10,
is_active=True,
is_default=False,
custom_api=mock_api,
)
db.query().filter().all.return_value = [mock_user_api]
res = await list_custom_apis(current_user=user, db=db)
assert len(res) == 1
assert res[0].name == "test_api"
assert res[0].id == 10
@pytest.mark.asyncio
async def test_create_custom_api():
db = MagicMock(spec=Session)
user = User(id=1)
api_data = CustomApiCreate(
name="new_api",
description="desc",
env={"k1": "v1"},
runtime_input_schema={"context": {"account_id": {"type": "string"}}},
runtime_bindings=[
{
"source": {"input_type": "context", "key": "account_id"},
"target": {"target_type": "headers", "key": "X-Account-ID"},
}
],
is_active=True,
)
# Mock no existing api
db.query().filter().first.return_value = None
# Create mock CustomApi object with datetimes so isoformat() doesn't fail
CustomApi(
id=1, name="new_api", created_at=datetime.now(), updated_at=datetime.now()
)
# Create mock UserCustomApi object to pair with our custom api mock
UserCustomApi(
user_id=1, custom_api_id=1, is_owner=True, is_active=True, is_default=False
)
# Update db.add to populate created_at/updated_at fields on our mock
def mock_add(obj):
if isinstance(obj, CustomApi):
obj.id = 1
obj.created_at = datetime.now()
obj.updated_at = datetime.now()
elif isinstance(obj, UserCustomApi):
obj.user_id = 1
obj.custom_api_id = 1
obj.is_active = True
obj.is_default = False
db.add.side_effect = mock_add
with patch(
"xagent.web.api.custom_api.encrypt_value", side_effect=lambda x: f"enc_{x}"
):
res = await create_custom_api(api_data, current_user=user, db=db)
assert res.name == "new_api"
assert res.env == {"k1": "********"} # Response should mask env
assert res.runtime_input_schema == {
"context": {"account_id": {"type": "string"}}
}
assert res.runtime_bindings == [
{
"source": {"input_type": "context", "key": "account_id"},
"target": {"target_type": "headers", "key": "X-Account-ID"},
}
]
db.add.assert_called()
db.commit.assert_called()
@pytest.mark.asyncio
async def test_create_custom_api_duplicate_name():
db = MagicMock(spec=Session)
user = User(id=1)
api_data = CustomApiCreate(name="existing_api")
# Mock existing api
db.query().filter().first.return_value = CustomApi(name="existing_api")
with pytest.raises(HTTPException) as exc_info:
await create_custom_api(api_data, current_user=user, db=db)
assert exc_info.value.status_code == 400
@pytest.mark.asyncio
async def test_create_custom_api_rejects_runtime_static_header_conflict():
db = MagicMock(spec=Session)
user = User(id=1)
api_data = CustomApiCreate(
name="runtime_api",
headers={"X-Account-ID": "static"},
runtime_input_schema={"context": {"account_id": {"type": "string"}}},
runtime_bindings=[
{
"source": {"input_type": "context", "key": "account_id"},
"target": {"target_type": "headers", "key": "X-Account-ID"},
}
],
)
db.query().filter().first.return_value = None
with pytest.raises(HTTPException) as exc_info:
await create_custom_api(api_data, current_user=user, db=db)
assert exc_info.value.status_code == 400
assert "Invalid runtime configuration" in str(exc_info.value.detail)
def test_get_custom_api():
db = MagicMock(spec=Session)
user = User(id=1)
mock_api = CustomApi(
id=10, name="test_api", created_at=datetime.now(), updated_at=datetime.now()
)
mock_user_api = UserCustomApi(
user_id=1,
custom_api_id=10,
is_active=True,
is_default=False,
custom_api=mock_api,
)
db.query().filter().first.return_value = mock_user_api
res = get_custom_api(10, current_user=user, db=db)
assert res.id == 10
assert res.name == "test_api"
def test_get_custom_api_not_found():
db = MagicMock(spec=Session)
user = User(id=1)
db.query().filter().first.return_value = None
with pytest.raises(HTTPException) as exc_info:
get_custom_api(99, current_user=user, db=db)
assert exc_info.value.status_code == 404
@pytest.mark.asyncio
async def test_update_custom_api():
db = MagicMock(spec=Session)
user = User(id=1)
mock_api = CustomApi(
id=10,
name="old_name",
env={"k1": "enc_old1"},
runtime_input_schema={"context": {"account_id": {"type": "string"}}},
runtime_bindings=[],
created_at=datetime.now(),
updated_at=datetime.now(),
)
mock_user_api = UserCustomApi(
user_id=1,
custom_api_id=10,
can_edit=True,
is_active=True,
is_default=False,
custom_api=mock_api,
)
# Return user api on first query
# Return None for the exact-name check, the catalog-name check, then for
# the folded-name check's MCP server and Custom API queries
db.query().filter().first.side_effect = [mock_user_api, None, None, None, None]
# The row lock's own fresh query is a separate mock chain
# (.populate_existing().with_for_update() sits between .filter() and
# .first()), so it needs its own return value rather than sharing the
# side_effect list above.
db.query().filter().populate_existing().with_for_update().first.return_value = (
mock_api
)
# The post-lock re-read of the link row is a third mock chain, distinct
# from both of the above: unrevoked, it must return the same
# still-``can_edit`` link the access gate saw, or the route's
# unstubbed ``MagicMock`` default -- truthy for any attribute access,
# including ``.can_edit`` -- would make the permission check below a
# no-op no matter what it is actually asked to verify.
db.query().filter().populate_existing().first.return_value = mock_user_api
api_data = CustomApiUpdate(
name="new_name",
env={"k1": "********", "k2": "v2"},
runtime_bindings=[
{
"source": {"input_type": "context", "key": "account_id"},
"target": {"target_type": "headers", "key": "X-Account-ID"},
}
],
)
with patch(
"xagent.web.api.custom_api.encrypt_value", side_effect=lambda x: f"enc_{x}"
):
update_custom_api(10, api_data, current_user=user, db=db)
assert mock_api.name == "new_name"
assert mock_api.env == {"k1": "enc_old1", "k2": "enc_v2"}
assert mock_api.runtime_input_schema == {
"context": {"account_id": {"type": "string"}}
}
assert mock_api.runtime_bindings == [
{
"source": {"input_type": "context", "key": "account_id"},
"target": {"target_type": "headers", "key": "X-Account-ID"},
}
]
db.commit.assert_called()
@pytest.mark.asyncio
async def test_update_custom_api_env_replacement_deletes_only_the_omitted_secret():
db = MagicMock(spec=Session)
user = User(id=1)
mock_api = CustomApi(
id=10,
name="records",
env={"BEARER_TOKEN": "enc_bearer", "TENANT": "enc_tenant"},
created_at=datetime.now(),
updated_at=datetime.now(),
)
mock_user_api = UserCustomApi(
user_id=1,
custom_api_id=10,
can_edit=True,
is_active=True,
is_default=False,
custom_api=mock_api,
)
db.query().filter().first.return_value = mock_user_api
# The row lock's own fresh query is a separate mock chain -- see the
# comment in test_update_custom_api.
db.query().filter().populate_existing().with_for_update().first.return_value = (
mock_api
)
# The post-lock re-read of the link row -- see the comment in
# test_update_custom_api.
db.query().filter().populate_existing().first.return_value = mock_user_api
with patch(
"xagent.web.api.custom_api.encrypt_value", side_effect=lambda x: f"enc_{x}"
):
update_custom_api(
10,
CustomApiUpdate(env={"TENANT": "********"}),
current_user=user,
db=db,
)
assert mock_api.env == {"TENANT": "enc_tenant"}
@pytest.mark.asyncio
async def test_update_custom_api_rejects_renamed_masked_secret():
db = MagicMock(spec=Session)
user = User(id=1)
mock_api = CustomApi(
id=10,
name="records",
env={"TOKEN": "encrypted-token"},
created_at=datetime.now(),
updated_at=datetime.now(),
)
mock_user_api = UserCustomApi(
user_id=1,
custom_api_id=10,
can_edit=True,
is_active=True,
is_default=False,
custom_api=mock_api,
)
db.query().filter().first.return_value = mock_user_api
# The row lock's own fresh query is a separate mock chain -- see the
# comment in test_update_custom_api.
db.query().filter().populate_existing().with_for_update().first.return_value = (
mock_api
)
# The post-lock re-read of the link row -- see the comment in
# test_update_custom_api.
db.query().filter().populate_existing().first.return_value = mock_user_api
with pytest.raises(HTTPException) as exc_info:
update_custom_api(
10,
CustomApiUpdate(env={"RENAMED_TOKEN": "********"}),
current_user=user,
db=db,
)
assert exc_info.value.status_code == 400
assert mock_api.env == {"TOKEN": "encrypted-token"}
db.commit.assert_not_called()
@pytest.mark.asyncio
async def test_update_custom_api_explicit_null_clears_runtime_config():
db = MagicMock(spec=Session)
user = User(id=1)
mock_api = CustomApi(
id=10,
name="old_name",
runtime_input_schema={"context": {"account_id": {"type": "string"}}},
runtime_bindings=[
{
"source": {"input_type": "context", "key": "account_id"},
"target": {"target_type": "headers", "key": "X-Account-ID"},
}
],
allow_delegated_authorization=True,
created_at=datetime.now(),
updated_at=datetime.now(),
)
mock_user_api = UserCustomApi(
user_id=1,
custom_api_id=10,
can_edit=True,
is_active=True,
is_default=False,
custom_api=mock_api,
)
db.query().filter().first.return_value = mock_user_api
# The row lock's own fresh query is a separate mock chain -- see the
# comment in test_update_custom_api.
db.query().filter().populate_existing().with_for_update().first.return_value = (
mock_api
)
# The post-lock re-read of the link row -- see the comment in
# test_update_custom_api.
db.query().filter().populate_existing().first.return_value = mock_user_api
api_data = CustomApiUpdate(
runtime_input_schema=None,
runtime_bindings=None,
allow_delegated_authorization=False,
)
update_custom_api(10, api_data, current_user=user, db=db)
assert mock_api.runtime_input_schema is None
assert mock_api.runtime_bindings is None
assert mock_api.allow_delegated_authorization is False
db.commit.assert_called()
@pytest.mark.asyncio
async def test_delete_custom_api():
db = MagicMock(spec=Session)
user = User(id=1)
mock_api = CustomApi(id=10)
mock_user_api = UserCustomApi(
user_id=1, custom_api_id=10, can_delete=True, custom_api=mock_api
)
db.query().filter().first.return_value = mock_user_api
db.query().filter().populate_existing().with_for_update().first.return_value = (
mock_api
)
# The post-lock re-read of the link row -- see the comment in
# test_update_custom_api.
db.query().filter().populate_existing().first.return_value = mock_user_api
delete_custom_api(10, current_user=user, db=db)
db.delete.assert_called_once_with(mock_api)
db.commit.assert_called()
@pytest.mark.asyncio
async def test_delete_team_custom_api_flushes_only_current_user_link():
db = MagicMock(spec=Session)
user = User(id=1)
mock_api = CustomApi(id=10)
mock_user_api = UserCustomApi(
user_id=1, custom_api_id=10, can_delete=True, custom_api=mock_api
)
db.query().filter().first.side_effect = [mock_user_api, None]
db.query().filter().populate_existing().with_for_update().first.return_value = (
mock_api
)
# The lock-order re-read of the link row is a third mock chain, distinct
# from the access gate's plain ``.filter().first()`` above: unrevoked,
# it must return the same still-``can_delete`` link the gate saw.
db.query().filter().populate_existing().first.return_value = mock_user_api
decision = ConnectorDeleteDecision(
team_owned=True,
authorized=True,
delete_definition=True,
)
with patch(
"xagent.web.services.connector_team_scope.delete_team_connector",
return_value=decision,
):
delete_custom_api(10, current_user=user, db=db)
db.flush.assert_called_once_with([mock_user_api])
assert db.no_autoflush.__enter__.called
assert db.delete.call_args_list == [call(mock_user_api), call(mock_api)]
db.commit.assert_called_once()
def test_the_locking_routes_are_sync_defs_so_a_lock_wait_never_holds_the_event_loop():
"""``update_custom_api`` can run a ``SELECT ... FOR UPDATE`` that waits
indefinitely on a concurrent writer holding the same definition row;
``delete_custom_api`` always does. FastAPI runs a coroutine route on the
event loop thread itself, so such a wait inside an ``async def`` route
stalls every other request the process is serving, not just this one.
Declaring them as plain ``def`` puts them in the threadpool instead,
where the wait occupies one worker.
"""
from xagent.web.api import custom_api as custom_api_api
assert not inspect.iscoroutinefunction(custom_api_api.update_custom_api)
assert not inspect.iscoroutinefunction(custom_api_api.delete_custom_api)
def _lock_order_session_factory():
engine = create_engine("sqlite:///:memory:")
Base.metadata.create_all(engine)
return sessionmaker(autocommit=False, autoflush=False, bind=engine), engine
def _seed_owned_api_for_lock_order(
session_factory, *, name: str, description: str | None = None
) -> tuple[int, int]:
db = session_factory()
owner = User(username=f"user-{name}", password_hash="x", is_admin=False)
db.add(owner)
db.flush()
api = CustomApi(
name=name, url="https://example.test/api", method="GET", description=description
)
db.add(api)
db.flush()
db.add(
UserCustomApi(
user_id=owner.id,
custom_api_id=api.id,
is_owner=True,
can_edit=True,
can_delete=True,
is_active=True,
)
)
db.commit()
owner_id, api_id = int(owner.id), int(api.id)
db.close()
return owner_id, api_id
def _count_custom_apis_selects_before_first_delete(statements: list[str]) -> int:
"""How many ``SELECT``s against ``custom_apis`` land before the first
``DELETE`` of either table.
The route's own not-found guard (``not user_api or not
user_api.custom_api``) always lazy-loads the ``custom_api`` relationship,
which is one such ``SELECT`` on its own -- with or without the lock
statement this test exists to pin. So *presence* of a ``custom_apis``
``SELECT`` before the delete is true either way and proves nothing; the
*count* is what distinguishes them -- one without the lock statement,
two with it, because the lock statement is its own separate ``Query``
execution against the database, issued in addition to the relationship
load above rather than instead of it. ``populate_existing()`` does not
decide whether that second statement is sent; it decides which column
values end up on the already-identity-mapped row once it is: with it,
the lock statement's freshly-read columns overwrite what the
relationship load put there, rather than being discarded in favor of
it.
"""
count = 0
for statement in statements:
upper = statement.strip().upper()
if upper.startswith("DELETE"):
break
if upper.startswith("SELECT") and "FROM CUSTOM_APIS" in upper:
count += 1
return count
def _updated_table_names(statements: list[str]) -> list[str]:
"""The table name out of each recorded ``UPDATE`` statement, in order.
Matched off the second token rather than a substring check: SQLite
renders ``UPDATE user_custom_apis SET ...``, and a plain ``"CUSTOM_APIS"
in statement`` check would also match that table's own name, since it
contains the shorter table name as a substring.
"""
tables = []
for statement in statements:
tokens = statement.strip().split()
if tokens and tokens[0].upper() == "UPDATE":
tables.append(tokens[1].strip('"').upper())
return tables
def _assert_is_active_edit_writes_link_row_only(
*,
seed_name: str,
payload_kwargs: dict,
expected_description,
seed_description: str | None = None,
) -> None:
"""Shared body for the two ``is_active``-plus-sibling-field tests
below: run the edit, assert the response and the persisted link row,
then assert that no ``UPDATE`` reached ``custom_apis`` while exactly
one reached ``user_custom_apis``.
"""
session_factory, engine = _lock_order_session_factory()
owner_id, api_id = _seed_owned_api_for_lock_order(
session_factory, name=seed_name, description=seed_description
)
db = session_factory()
current_user = SimpleNamespace(id=owner_id, is_admin=False)
statements: list[str] = []
def record_query(conn, cursor, statement, parameters, context, executemany):
del conn, cursor, parameters, context, executemany
statements.append(statement)
event.listen(engine, "before_cursor_execute", record_query)
try:
response = update_custom_api(
api_id,
CustomApiUpdate(is_active=False, **payload_kwargs),
current_user=current_user,
db=db,
)
finally:
event.remove(engine, "before_cursor_execute", record_query)
db.close()
assert isinstance(response, CustomApiResponse)
assert response.is_active is False
with session_factory() as fresh:
link = (
fresh.query(UserCustomApi)
.filter(
UserCustomApi.custom_api_id == api_id,
UserCustomApi.user_id == owner_id,
)
.one()
)
assert link.is_active is False
api = fresh.query(CustomApi).filter(CustomApi.id == api_id).one()
assert api.name == seed_name
assert api.description == expected_description
updated_tables = _updated_table_names(statements)
assert updated_tables.count("CUSTOM_APIS") == 0, (
f"an is_active edit for {seed_name!r} must not write the "
f"definition row -- saw UPDATEs against {updated_tables!r}"
)
assert updated_tables.count("USER_CUSTOM_APIS") == 1
def test_an_is_active_edit_with_an_explicit_null_description_writes_no_definition_field():
"""``model_fields_set`` decides ``writes_definition_row``, not the
values -- so a payload pairing ``is_active`` with an explicit-null
``description`` still counts ``description`` into that set and takes
the lock, even though the write below it is skipped by its own
``is not None`` guard. Despite taking the lock, only the caller's own
link row may see an ``UPDATE``.
The seed's own description is non-``None`` (``"seed-desc"``): if the
guard were ever bypassed, assigning the payload's ``None`` over that
would be an observable change, not a same-value no-op silently skipped
by SQLAlchemy's own dirty-tracking.
"""
_assert_is_active_edit_writes_link_row_only(
seed_name="is-active-null-description",
seed_description="seed-desc",
payload_kwargs={"description": None},
expected_description="seed-desc",
)
def test_an_is_active_edit_repeating_the_current_name_writes_no_definition_field():
"""Same shape as the explicit-null-description case above, with
``name`` as the sibling field: it counts into ``fields_set`` and takes
the lock, but the name-change guard (``api_data.name != api.name``) is
false, so the definition row must still see no ``UPDATE``.
"""
_assert_is_active_edit_writes_link_row_only(
seed_name="is-active-repeated-name",
payload_kwargs={"name": "is-active-repeated-name"},
expected_description=None,
)
class TestDeleteLockOrderMatchesThePutsLockOrder:
"""An ``update_custom_api`` call that writes the definition row locks
it first, calls ``rename_team_connector`` after that lock, and writes
the ``UserCustomApi`` link row after that. For the two routes to share one
lock order, ``delete_custom_api`` must take the same definition-row
lock before it calls ``delete_team_connector`` and before it deletes
the link row, in both of its branches. The hook boundary matters as
much as the two tables do: a hook that locks rows of its own sees both
routes arrive holding the definition row, so the two cannot be inside
the hook at the same time on the same connector.
SQLite silently drops ``FOR UPDATE`` (it is a no-op on this dialect), so
nothing here demonstrates that the lock actually blocks a second writer
-- that proof lives in test_custom_api_edit_lock_postgresql.py, against
a real server. What this proves instead is statement *order*, which is
dialect-independent and exercisable without one.
"""
def _run(self, *, team_owned: bool) -> list[str]:
session_factory, engine = _lock_order_session_factory()
owner_id, api_id = _seed_owned_api_for_lock_order(
session_factory,
name="lock-order-team" if team_owned else "lock-order-cascade",
)
db = session_factory()
current_user = SimpleNamespace(id=owner_id, is_admin=False)
statements: list[str] = []
def record_query(conn, cursor, statement, parameters, context, executemany):
del conn, cursor, parameters, context, executemany
statements.append(statement)
event.listen(engine, "before_cursor_execute", record_query)
try:
if team_owned:
def deleted_hook(_db, _user_id, _connector_type, _connector_id):
return ConnectorDeleteDecision(
team_owned=True, authorized=True, delete_definition=True
)
set_connector_team_hooks(deleted=deleted_hook)
try:
delete_custom_api(api_id, current_user=current_user, db=db)
finally:
set_connector_team_hooks()
else:
delete_custom_api(api_id, current_user=current_user, db=db)
finally:
event.remove(engine, "before_cursor_execute", record_query)
db.close()
return statements
def test_lock_order_team_owned_branch(self):
statements = self._run(team_owned=True)
assert _count_custom_apis_selects_before_first_delete(statements) == 2, (
"expected the not-found guard's relationship load AND the new "
"lock statement's own SELECT against custom_apis, both before "
"the first DELETE"
)
def test_lock_order_cascade_branch(self):
statements = self._run(team_owned=False)
assert _count_custom_apis_selects_before_first_delete(statements) == 2, (
"expected the not-found guard's relationship load AND the new "
"lock statement's own SELECT against custom_apis, both before "
"the first DELETE"
)
def test_the_lock_is_taken_before_the_delete_hook_is_called(self):
"""``delete_team_connector`` runs with the definition row already
held. That is what puts this route in the same direction as
``update_custom_api``, which calls ``rename_team_connector`` after
its own definition-row lock, on the path that takes one -- and is
therefore what stops the two from forming a cycle through rows the
hook locks. The hook counts the
``custom_apis`` ``SELECT``s issued so far: the not-found guard's
relationship load, plus the lock's own query.
"""
session_factory, engine = _lock_order_session_factory()
owner_id, api_id = _seed_owned_api_for_lock_order(
session_factory, name="lock-order-before-hook"
)
db = session_factory()
current_user = SimpleNamespace(id=owner_id, is_admin=False)
statements: list[str] = []
selects_seen_by_the_hook: list[int] = []
def record_query(conn, cursor, statement, parameters, context, executemany):
del conn, cursor, parameters, context, executemany
statements.append(statement)
def deleted_hook(_db, _user_id, _connector_type, _connector_id):
selects_seen_by_the_hook.append(
sum(
1
for statement in statements
if statement.strip().upper().startswith("SELECT")
and "FROM CUSTOM_APIS" in statement.strip().upper()
)
)
return ConnectorDeleteDecision()
event.listen(engine, "before_cursor_execute", record_query)
set_connector_team_hooks(deleted=deleted_hook)
try:
delete_custom_api(api_id, current_user=current_user, db=db)
finally:
set_connector_team_hooks()
event.remove(engine, "before_cursor_execute", record_query)
db.close()
assert selects_seen_by_the_hook == [2], (
"expected the delete hook to be called once, with both the "
"not-found guard's relationship load and the lock statement's "
"own SELECT against custom_apis already issued"
)
def _with_for_update_lines(fn: "ast.FunctionDef") -> list[int]:
"""Line numbers of every ``with_for_update(...)`` call inside ``fn``."""
return [
node.lineno
for node in ast.walk(fn)
if isinstance(node, ast.Call)
and isinstance(node.func, ast.Attribute)
and node.func.attr == "with_for_update"
]
def _call_lines_by_name(fn: "ast.FunctionDef", name: str) -> list[int]:
"""Line numbers of every plain ``name(...)`` call inside ``fn``."""
return [
node.lineno
for node in ast.walk(fn)
if isinstance(node, ast.Call)
and isinstance(node.func, ast.Name)
and node.func.id == name
]
def _route_ast(name: str) -> "ast.FunctionDef":
from xagent.web.api import custom_api as custom_api_api
tree = ast.parse(inspect.getsource(custom_api_api))
for node in ast.walk(tree):
if isinstance(node, ast.FunctionDef) and node.name == name:
return node
raise AssertionError(f"{name} not found in xagent.web.api.custom_api")
@pytest.mark.parametrize(
("route", "hook"),
[
("update_custom_api", "rename_team_connector"),
("delete_custom_api", "delete_team_connector"),
],
)
def test_the_definition_row_lock_statement_precedes_the_team_hook_call(route, hook):
"""``delete_custom_api`` always takes the definition-row lock before it
calls into a connector team hook; ``update_custom_api`` takes that lock
only for a payload that writes the definition row, and takes it before
the hook when it does.
Statement position is the thing under test, so it is read off the
source rather than off executed SQL: SQLAlchemy renders no locking
clause at all on SQLite, so a run against the suite's own engine
cannot tell this lock statement from a plain read. That the clause
really blocks a second
writer is proved against a real server in
test_custom_api_edit_lock_postgresql.py; what is proved here is the
order the two routes share, which is what keeps a concurrent edit and
delete of one connector from waiting on each other in opposite
directions across the hook boundary.
"""
fn = _route_ast(route)
lock_lines = _with_for_update_lines(fn)
assert len(lock_lines) == 1, (
f"expected exactly one with_for_update call in {route}, found {len(lock_lines)}"
)
hook_lines = _call_lines_by_name(fn, hook)
assert len(hook_lines) == 1, (
f"expected exactly one {hook} call in {route}, found {len(hook_lines)}"
)
assert lock_lines[0] < hook_lines[0], (
f"{route} must take the definition-row lock before it calls {hook}"
)