LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows
Python ai-agentsdata-engineeringdocument-aigenerative-aiidpjson-extractionllmmcp-serverocrpdf-extractionprompt-engineeringstructured-output
"""Tests for the fairness-key plumbing (PG Queue Phase 5.1)."""
from __future__ import annotations
import ast
import json
from dataclasses import FrozenInstanceError
from unittest.mock import patch
import pytest
from celery import Celery
from queue_backend import FairnessKey, dispatch
from queue_backend.routing import QueueBackend
from queue_backend.fairness import (
DEFAULT_PRIORITY,
FAIRNESS_HEADER_NAME,
MAX_PRIORITY,
MIN_PRIORITY,
WorkloadType,
)
from .canary_helpers import (
DEFAULT_SKIP_TOP_DIRS,
WORKERS_ROOT,
iter_production_trees,
)
# Promote ``UserWarning`` from ``iter_production_trees`` (emitted on
# unparseable production files) to a test failure. An unparseable
# file silently dropped from the audited tree would let every canary
# below pass vacuously — exactly the failure mode the helper claims
# to prevent.
pytestmark = pytest.mark.filterwarnings("error::UserWarning")
# Fairness-canary helpers also skip the seam module itself (it
# legitimately defines and exports the fairness constants).
_SKIP_TOP_DIRS = DEFAULT_SKIP_TOP_DIRS | frozenset({"queue_backend"})
def _trees():
return iter_production_trees(skip_top_dirs=_SKIP_TOP_DIRS)
def _aliased_dispatch_imports(tree: ast.AST) -> list[tuple[int, str]]:
hits: list[tuple[int, str]] = []
for node in ast.walk(tree):
if not (isinstance(node, ast.ImportFrom) and node.module == "queue_backend"):
continue
for alias in node.names:
if alias.name == "dispatch" and alias.asname not in (None, "dispatch"):
hits.append((node.lineno, alias.asname))
return hits
def _dispatch_calls_missing_fairness(tree: ast.AST) -> list[int]:
# Only matches the bare name ``dispatch`` — ``dispatcher.dispatch(...)``
# is ExecutionDispatcher (executor RPC), a different concept.
hits: list[int] = []
for node in ast.walk(tree):
if not isinstance(node, ast.Call):
continue
callee = node.func
if not (isinstance(callee, ast.Name) and callee.id == "dispatch"):
continue
if not any(kw.arg == "fairness" for kw in node.keywords):
hits.append(node.lineno)
return hits
class TestFairnessKey:
def test_minimal_construction(self):
key = FairnessKey(org_id="org-123", workload_type=WorkloadType.API)
assert key.org_id == "org-123"
assert key.workload_type == "api"
assert key.pipeline_priority == DEFAULT_PRIORITY # default 5
def test_org_id_can_be_none(self):
key = FairnessKey(org_id=None, workload_type=WorkloadType.API)
assert key.org_id is None
def test_workload_type_non_api(self):
key = FairnessKey(org_id="x", workload_type=WorkloadType.NON_API)
assert key.workload_type == "non_api"
assert key.workload_type == WorkloadType.NON_API
def test_pipeline_priority_override(self):
key = FairnessKey(org_id="x", workload_type=WorkloadType.API, pipeline_priority=9)
assert key.pipeline_priority == 9
def test_is_frozen(self):
key = FairnessKey(org_id="x", workload_type=WorkloadType.API)
with pytest.raises(FrozenInstanceError):
key.org_id = "y" # type: ignore[misc]
def test_priority_below_range_rejected(self):
with pytest.raises(ValueError, match="pipeline_priority out of range"):
FairnessKey(
org_id="x", workload_type=WorkloadType.API, pipeline_priority=MIN_PRIORITY - 1
)
def test_priority_above_range_rejected(self):
with pytest.raises(ValueError, match="pipeline_priority out of range"):
FairnessKey(
org_id="x", workload_type=WorkloadType.API, pipeline_priority=MAX_PRIORITY + 1
)
def test_priority_boundaries_accepted(self):
FairnessKey(org_id="x", workload_type=WorkloadType.API, pipeline_priority=MIN_PRIORITY)
FairnessKey(org_id="x", workload_type=WorkloadType.API, pipeline_priority=MAX_PRIORITY)
def test_typo_in_field_name_raises(self):
with pytest.raises(TypeError, match="pipeline_prio"):
FairnessKey(
org_id="x",
workload_type=WorkloadType.API,
pipeline_prio=9, # type: ignore[call-arg]
)
def test_to_dict_shape(self):
key = FairnessKey(
org_id="org-1", workload_type=WorkloadType.NON_API, pipeline_priority=9
)
assert key.to_dict() == {
"org_id": "org-1",
"workload_type": "non_api",
"pipeline_priority": 9,
}
def test_to_dict_uses_plain_string_not_enum_member(self):
# Downstream consumers shouldn't need to import WorkloadType.
key = FairnessKey(org_id="x", workload_type=WorkloadType.API)
wt = key.to_dict()["workload_type"]
assert type(wt) is str
assert wt == "api"
def test_to_dict_is_json_safe(self):
key = FairnessKey(
org_id="org-1", workload_type=WorkloadType.API, pipeline_priority=7
)
round_tripped = json.loads(json.dumps(key.to_dict()))
assert round_tripped == key.to_dict()
def test_orgless_key_round_trips(self):
key = FairnessKey(org_id=None, workload_type=WorkloadType.API)
round_tripped = json.loads(json.dumps(key.to_dict()))
assert round_tripped == {
"org_id": None,
"workload_type": "api",
"pipeline_priority": DEFAULT_PRIORITY,
}
# --- dispatch() integration ---
class TestDispatchAttachesFairness:
"""UN-4046: these assert the PG path, which is the only one dispatch takes.
They used to patch ``current_app`` and read ``send_task.call_args`` — the
Celery branch. ``select_backend`` returns PG unconditionally now, so that
branch is unreachable without an explicit ``backend=`` override and the
assertions failed on a mock that was never called. The property under test is
unchanged: fairness must reach the transport WITHOUT being folded into the
business kwargs, since tasks without ``**kwargs`` would break. On PG that
means the ``fairness`` payload slot plus the ``org_id``/``priority`` columns
the dequeue orders by.
"""
def test_omitted_fairness_writes_neutral_defaults(self):
with patch("queue_backend.dispatch._get_pg_client") as mock_client:
dispatch("any_task", kwargs={"foo": "bar"})
_, payload = mock_client.return_value.send.call_args.args
send_kwargs = mock_client.return_value.send.call_args.kwargs
assert payload["fairness"] is None
assert payload["kwargs"] == {"foo": "bar"}
assert send_kwargs["org_id"] is None
assert send_kwargs["priority"] == DEFAULT_PRIORITY
def test_explicit_fairness_none_writes_neutral_defaults(self):
# Documented opt-out for non-workflow dispatches.
with patch("queue_backend.dispatch._get_pg_client") as mock_client:
dispatch("send_webhook_notification", kwargs={"x": 1}, fairness=None)
_, payload = mock_client.return_value.send.call_args.args
assert payload["fairness"] is None
assert payload["kwargs"] == {"x": 1}
def test_provided_fairness_rides_the_payload_and_the_columns(self):
with patch("queue_backend.dispatch._get_pg_client") as mock_client:
dispatch(
"any_task",
kwargs={"foo": "bar"},
fairness=FairnessKey(
org_id="org-1", workload_type=WorkloadType.API, pipeline_priority=9
),
)
_, payload = mock_client.return_value.send.call_args.args
send_kwargs = mock_client.return_value.send.call_args.kwargs
assert payload["fairness"] == {
"org_id": "org-1",
"workload_type": "api",
"pipeline_priority": 9,
}
# org_id + priority are separate COLUMNS, not just payload keys: the
# dequeue orders by them, so a payload-only fairness would be inert.
assert send_kwargs["org_id"] == "org-1"
assert send_kwargs["priority"] == 9
# Business kwargs must NOT contain the fairness slot — tasks
# without **kwargs would break.
assert payload["kwargs"] == {"foo": "bar"}
assert FAIRNESS_HEADER_NAME not in payload["kwargs"]
def test_fairness_with_no_business_kwargs(self):
with patch("queue_backend.dispatch._get_pg_client") as mock_client:
dispatch(
"any_task",
fairness=FairnessKey(org_id=None, workload_type=WorkloadType.NON_API),
)
_, payload = mock_client.return_value.send.call_args.args
send_kwargs = mock_client.return_value.send.call_args.kwargs
assert payload["kwargs"] == {}
assert payload["fairness"] == {
"org_id": None,
"workload_type": "non_api",
"pipeline_priority": DEFAULT_PRIORITY,
}
assert send_kwargs["org_id"] is None
assert send_kwargs["priority"] == DEFAULT_PRIORITY
def test_caller_kwargs_not_mutated_in_place(self):
caller_kwargs = {"foo": "bar"}
with patch("queue_backend.dispatch._get_pg_client"):
dispatch(
"any_task",
kwargs=caller_kwargs,
fairness=FairnessKey(org_id="org-1", workload_type=WorkloadType.API),
)
assert caller_kwargs == {"foo": "bar"}
assert FAIRNESS_HEADER_NAME not in caller_kwargs
def test_explicit_celery_override_still_attaches_the_header(self):
"""The Celery branch survives only as a ``backend=`` override target.
Nothing selects it — ``select_backend`` returns PG unconditionally — and
it is slated for deletion with the rest of the Celery transport. Until
then it must not rot silently: an override is the one way to reach it.
"""
with patch("queue_backend.dispatch.current_app") as mock_app:
dispatch(
"any_task",
kwargs={"foo": "bar"},
fairness=FairnessKey(
org_id="org-1", workload_type=WorkloadType.API, pipeline_priority=9
),
backend=QueueBackend.CELERY,
)
call_kwargs = mock_app.send_task.call_args.kwargs
assert call_kwargs["headers"] == {
FAIRNESS_HEADER_NAME: {
"org_id": "org-1",
"workload_type": "api",
"pipeline_priority": 9,
}
}
assert call_kwargs["kwargs"] == {"foo": "bar"}
class TestDispatchCallSitesPassFairness:
"""AST audit: every production ``dispatch(...)`` declares fairness."""
def test_dispatch_must_be_imported_unaliased(self):
# Alias imports would defeat the bare-name canary below.
aliased = [
f"{rel}:{lineno} (as {alias})"
for rel, tree in _trees()
for lineno, alias in _aliased_dispatch_imports(tree)
]
assert aliased == [], (
"``queue_backend.dispatch`` must be imported under its real "
"name — alias imports defeat the fairness inventory canary. "
"Found:\n " + "\n ".join(aliased)
)
def test_every_production_dispatch_passes_fairness(self):
offenders = [
f"{rel}:{lineno}"
for rel, tree in _trees()
for lineno in _dispatch_calls_missing_fairness(tree)
]
assert offenders == [], (
"Production dispatch(...) call site(s) missing fairness=. "
"Every production dispatch must declare its fairness — pass "
"``fairness=FairnessKey(org_id=..., workload_type=WorkloadType...)`` "
"for a workflow-execution dispatch, or ``fairness=None`` "
"for a worker-internal task that doesn't start a workflow "
"execution. Found:\n " + "\n ".join(offenders)
)
class TestNoConsumerYet:
"""Additive-only invariant — no production code reads the slot yet."""
def test_no_consumer_reads_fairness_header(self):
forbidden_tokens = ("x-fairness-key", "FAIRNESS_HEADER_NAME")
readers: list[str] = []
for py in WORKERS_ROOT.rglob("*.py"):
rel = py.relative_to(WORKERS_ROOT)
if rel.parts and rel.parts[0] in _SKIP_TOP_DIRS:
continue
for line_no, line in enumerate(py.read_text().splitlines(), start=1):
if any(token in line for token in forbidden_tokens):
readers.append(f"{rel}:{line_no}")
assert readers == [], (
"Found reader(s) of the fairness slot before Phase 8. "
"Phase 5.1 is additive-only — no consumer should exist yet. "
"Found:\n " + "\n ".join(readers)
)
class TestHeaderSurvivesCeleryPipeline:
"""End-to-end: header survives Celery's real send_task code path.
Reached via an explicit ``backend=`` override since UN-4046 — see
``test_explicit_celery_override_still_attaches_the_header``. Kept as long as
the Celery branch exists, and deleted with it.
"""
def test_header_present_on_outbound_message(self):
app = Celery(
"test_fairness_e2e", broker="memory://", backend="cache+memory://"
)
with patch("queue_backend.dispatch.current_app", app), patch.object(
app, "send_task", wraps=app.send_task
) as wrapped_send:
dispatch(
"qb.e2e.echo",
fairness=FairnessKey(
org_id="org-1",
workload_type=WorkloadType.NON_API,
pipeline_priority=9,
),
backend=QueueBackend.CELERY,
)
call_headers = wrapped_send.call_args.kwargs["headers"]
assert call_headers == {
FAIRNESS_HEADER_NAME: {
"org_id": "org-1",
"workload_type": "non_api",
"pipeline_priority": 9,
}
}