Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

28.6 KB
Raw Blame
import asyncio
from collections.abc import Callable
from typing import Any

import pytest
from unittest.mock import AsyncMock, MagicMock, patch

from django.test import override_settings

import aiohttp
from parameterized import parameterized
from prometheus_client import REGISTRY

from posthog.egress.harmonic.limiter import HARMONIC_WINDOW_SECONDS
from posthog.egress.harmonic.transport import HarmonicEgressBudgetExhausted
from posthog.egress.limiter.policies import Priority

from ee.billing.salesforce_enrichment.constants import (
    HARMONIC_ACCOUNT_ENRICHMENT_QUERY,
    HARMONIC_COMPANY_ENRICHMENT_QUERY,
)
from ee.billing.salesforce_enrichment.harmonic_client import (
    _ENRICH_MAX_ATTEMPTS,
    _ENRICH_MAX_CONCURRENT_LOOKUPS,
    AsyncHarmonicClient,
)

HARMONIC_REQUEST = "ee.billing.salesforce_enrichment.harmonic_client.harmonic_request"
PACE_SECONDS_HARMONIC = "ee.billing.salesforce_enrichment.harmonic_client.pace_seconds_harmonic"
ASYNCIO_SLEEP = "ee.billing.salesforce_enrichment.harmonic_client.asyncio.sleep"
ASYNCIO_TO_THREAD = "ee.billing.salesforce_enrichment.harmonic_client.asyncio.to_thread"
ADMISSION_INTERVAL_HARMONIC = "ee.billing.salesforce_enrichment.harmonic_client.admission_interval_harmonic"
MONOTONIC = "ee.billing.salesforce_enrichment.harmonic_client.time.monotonic"

# Captured at import time, before any test patches asyncio.sleep, so the fake sleeps below always
# yield to the real event loop rather than recursing into whichever mock is active when they run.
_REAL_SLEEP = asyncio.sleep


# Bypasses the real thread pool so pacing stays single-threaded and deterministic under test.
async def _fake_to_thread(func: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
    return func(*args, **kwargs)


def _response(*, json_data=None, raise_status=None, status=200):
    resp = MagicMock()
    resp.status = status
    resp.raise_for_status = MagicMock(side_effect=raise_status)
    resp.json = AsyncMock(return_value=json_data)
    return resp


def _client(*, priority=Priority.NORMAL):
    client = AsyncHarmonicClient.__new__(AsyncHarmonicClient)
    client.api_key = "test-key"
    client.priority = priority
    client.source = "test"
    client.query = HARMONIC_COMPANY_ENRICHMENT_QUERY
    client.session = MagicMock()
    return client


def _not_found(urn=None):
    return _response(json_data={"data": {"enrichCompanyByIdentifiers": {"companyFound": False, "enrichmentUrn": urn}}})


def _found(company, urn=None):
    return _response(
        json_data={
            "data": {"enrichCompanyByIdentifiers": {"companyFound": True, "company": company, "enrichmentUrn": urn}}
        }
    )


def _missing_company_found_key():
    return _response(json_data={"data": {"enrichCompanyByIdentifiers": {}}})


def _graphql_errors():
    return _response(json_data={"errors": [{"message": "internal error"}]})


def _http_500():
    error = aiohttp.ClientResponseError(request_info=MagicMock(), history=(), status=500, message="Server Error")
    return _response(raise_status=error)


@pytest.mark.asyncio
async def test_strict_returns_none_when_not_found():
    # Both domain variations return a clean companyFound=false.
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=[_not_found(), _not_found()])):
        result = await _client().enrich_company_by_domain_strict("unknown.example")
    assert result.company is None


@pytest.mark.asyncio
async def test_strict_reraises_on_http_error():
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=[_http_500(), _http_500()])):
        with pytest.raises(aiohttp.ClientResponseError):
            await _client().enrich_company_by_domain_strict("posthog.com")


@pytest.mark.asyncio
async def test_strict_falls_back_to_second_variation_after_error():
    # First variation errors, second returns a company: the successful variation wins.
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=[_http_500(), _found({"name": "PostHog"})])):
        result = await _client().enrich_company_by_domain_strict("posthog.com")
    assert result.company == {"name": "PostHog"}


@pytest.mark.asyncio
async def test_strict_clean_not_found_is_authoritative_when_the_other_variation_errored():
    # One variation errored, the other returned a clean companyFound=false: that clean answer
    # is an authoritative not-found. Raising here made a deterministically-failing variation
    # exhaust the caller's retries and leave the org with no archive row at all.
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=[_http_500(), _not_found()])):
        result = await _client().enrich_company_by_domain_strict("posthog.com")
    assert result.company is None


@pytest.mark.asyncio
async def test_strict_clean_not_found_first_then_error_is_also_not_found():
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=[_not_found(), _http_500()])):
        result = await _client().enrich_company_by_domain_strict("posthog.com")
    assert result.company is None


@pytest.mark.asyncio
async def test_strict_raises_when_companyfound_key_missing_and_sibling_errored():
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=[_http_500(), _missing_company_found_key()])):
        with pytest.raises(aiohttp.ClientResponseError):
            await _client().enrich_company_by_domain_strict("posthog.com")


@pytest.mark.asyncio
async def test_strict_never_swallows_a_shed_variation_into_a_not_found_clean_first():
    # A sibling's clean not-found is authoritative for a genuine network error (see the test
    # above), but not for a shed: a shed means Harmonic was never asked, so the sibling's answer
    # says nothing about it. Swallowing this would write a false not-found the re-enrichment
    # sweep would not revisit for up to 90 days, purely because our own budget was tight.
    side_effect = [_not_found(), HarmonicEgressBudgetExhausted("degrading")]
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=side_effect)):
        with pytest.raises(HarmonicEgressBudgetExhausted):
            await _client(priority=Priority.BATCH).enrich_company_by_domain_strict("posthog.com")


@pytest.mark.asyncio
async def test_strict_never_swallows_a_shed_variation_into_a_not_found_shed_first():
    side_effect = [HarmonicEgressBudgetExhausted("degrading"), _not_found()]
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=side_effect)):
        with pytest.raises(HarmonicEgressBudgetExhausted):
            await _client(priority=Priority.BATCH).enrich_company_by_domain_strict("posthog.com")


@pytest.mark.asyncio
async def test_strict_graphql_error_with_clean_not_found_sibling_returns_none():
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=[_graphql_errors(), _not_found()])):
        result = await _client().enrich_company_by_domain_strict("posthog.com")
    assert result.company is None


@pytest.mark.asyncio
@patch("ee.billing.salesforce_enrichment.harmonic_client.capture_exception")
async def test_strict_captures_swallowed_error_on_mixed_path(mock_capture_exception):
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=[_graphql_errors(), _not_found()])):
        result = await _client().enrich_company_by_domain_strict("posthog.com")
    assert result.company is None
    mock_capture_exception.assert_called_once()


@pytest.mark.asyncio
async def test_strict_not_found_surfaces_the_tracking_urn():
    responses = [_not_found(urn="urn:harmonic:enrichment:abc"), _not_found(urn="urn:harmonic:enrichment:abc")]
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=responses)):
        result = await _client().enrich_company_by_domain_strict("unknown.example")
    assert result.company is None
    assert result.enrichment_urn == "urn:harmonic:enrichment:abc"


@parameterized.expand(
    [
        ("no_pending_refresh", None),
        ("pending_refresh", "urn:harmonic:enrichment:refresh"),
    ]
)
@pytest.mark.asyncio
async def test_strict_found_surfaces_the_refresh_urn(_name, urn):
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=[_found({"name": "PostHog"}, urn=urn)])):
        result = await _client().enrich_company_by_domain_strict("posthog.com")
    assert result.company == {"name": "PostHog"}
    assert result.enrichment_urn == urn


@pytest.mark.asyncio
async def test_strict_sends_api_key_as_header_not_in_url_or_params_and_uses_client_priority_and_source():
    client = _client(priority=Priority.BATCH)
    client.source = "billing_bulk"
    mock_request = AsyncMock(side_effect=[_found({"name": "PostHog"})])
    with patch(HARMONIC_REQUEST, new=mock_request):
        await client.enrich_company_by_domain_strict("posthog.com")

    mock_request.assert_called_once()
    call = mock_request.call_args
    assert call.args[0] is client.session
    assert call.args[1] == "POST"
    url = call.args[2]

    assert call.kwargs["headers"]["apikey"] == "test-key"
    assert "test-key" not in url
    assert call.kwargs.get("params") is None
    assert call.kwargs["priority"] is Priority.BATCH
    assert call.kwargs["source"] == "billing_bulk"


@parameterized.expand(
    [
        ("default_query", {}, HARMONIC_COMPANY_ENRICHMENT_QUERY, False),
        ("query_argument", {"query": HARMONIC_ACCOUNT_ENRICHMENT_QUERY}, HARMONIC_ACCOUNT_ENRICHMENT_QUERY, True),
    ]
)
@pytest.mark.asyncio
async def test_strict_sends_the_query_the_client_was_built_with(
    _name: str, kwargs: dict[str, Any], expected_query: str, fetches_socials: bool
) -> None:
    with override_settings(HARMONIC_API_KEY="test-key"):
        client = AsyncHarmonicClient(**kwargs)
    client.session = MagicMock()
    mock_request = AsyncMock(side_effect=[_found({"name": "Example Corp"})])
    with patch(HARMONIC_REQUEST, new=mock_request):
        await client.enrich_company_by_domain_strict("example.com")

    sent_query = mock_request.call_args.kwargs["json"]["query"]
    assert sent_query == expected_query
    assert ("socials" in sent_query) is fetches_socials


@pytest.mark.asyncio
async def test_non_strict_sends_api_key_as_header_not_in_url_or_params():
    mock_request = AsyncMock(side_effect=[_found({"name": "PostHog"})])
    with patch(HARMONIC_REQUEST, new=mock_request):
        await _client().enrich_company_by_domain("posthog.com")

    call = mock_request.call_args
    url = call.args[2]

    assert call.kwargs["headers"]["apikey"] == "test-key"
    assert "test-key" not in url
    assert call.kwargs.get("params") is None


@pytest.mark.asyncio
async def test_non_strict_returns_none_when_every_variation_is_rate_limited():
    # A limiter denial is swallowed by the same per-variation except block as a network error,
    # but must not be reported as one: the limiter already records it as a metric, and paging on
    # our own throttling working as designed would be noise.
    mock_request = AsyncMock(side_effect=HarmonicEgressBudgetExhausted("degrading"))
    with (
        patch(HARMONIC_REQUEST, new=mock_request),
        patch("ee.billing.salesforce_enrichment.harmonic_client.capture_exception") as mock_capture,
    ):
        result = await _client(priority=Priority.BATCH).enrich_company_by_domain("posthog.com")
    assert result is None
    mock_capture.assert_not_called()


@pytest.mark.asyncio
async def test_get_company_by_urn_returns_parsed_json():
    response = _response(json_data={"name": "Salesforce", "website": {"domain": "salesforce.com"}})
    client = _client()
    mock_request = AsyncMock(return_value=response)
    with patch(HARMONIC_REQUEST, new=mock_request):
        result = await client.get_company_by_urn("urn:harmonic:company:9801263")
    assert result == {"name": "Salesforce", "website": {"domain": "salesforce.com"}}
    mock_request.assert_called_once_with(
        client.session,
        "GET",
        "https://api.harmonic.ai/companies/9801263",
        source="test",
        priority=Priority.NORMAL,
        endpoint="/companies/{id}",
        headers={"apikey": "test-key"},
        timeout=aiohttp.ClientTimeout(total=10),
    )


@pytest.mark.asyncio
async def test_get_company_by_urn_returns_none_on_not_found():
    with patch(HARMONIC_REQUEST, new=AsyncMock(return_value=_response(status=404))):
        assert await _client().get_company_by_urn("urn:harmonic:company:999999999") is None


@pytest.mark.asyncio
async def test_get_company_by_urn_reraises_on_http_error():
    with patch(HARMONIC_REQUEST, new=AsyncMock(return_value=_http_500())):
        with pytest.raises(aiohttp.ClientResponseError):
            await _client().get_company_by_urn("urn:harmonic:company:9801263")


@pytest.mark.asyncio
async def test_get_company_by_urn_raises_when_rate_limited():
    # No swallowing here: parent-company resolution is optional, and the caller decides whether
    # to catch this, same as any other operational failure from this method.
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=HarmonicEgressBudgetExhausted("degrading"))):
        with pytest.raises(HarmonicEgressBudgetExhausted):
            await _client(priority=Priority.BATCH).get_company_by_urn("urn:harmonic:company:9801263")


@pytest.mark.asyncio
async def test_get_enrichment_status_builds_repeated_urns_query_and_maps_by_entity_urn():
    entries = [
        {"entity_urn": "urn:harmonic:enrichment:aaa", "status": "COMPLETE", "enriched_entity_urn": "urn:x:1"},
        {"entity_urn": "urn:harmonic:enrichment:bbb", "status": "QUEUED", "enriched_entity_urn": None},
    ]
    client = _client()
    mock_request = AsyncMock(return_value=_response(json_data=entries))
    with patch(HARMONIC_REQUEST, new=mock_request):
        result = await client.get_enrichment_status(["urn:harmonic:enrichment:aaa", "urn:harmonic:enrichment:bbb"])

    assert result == {
        "urn:harmonic:enrichment:aaa": entries[0],
        "urn:harmonic:enrichment:bbb": entries[1],
    }
    mock_request.assert_called_once()
    call = mock_request.call_args
    assert call.args[0] is client.session
    assert call.args[1] == "GET"
    assert call.args[2] == "https://api.harmonic.ai/enrichment_status"
    assert call.kwargs["params"] == [
        ("urns", "urn:harmonic:enrichment:aaa"),
        ("urns", "urn:harmonic:enrichment:bbb"),
    ]
    assert call.kwargs["headers"]["apikey"] == "test-key"
    assert "test-key" not in call.args[2]


@pytest.mark.asyncio
async def test_get_enrichment_status_raises_on_non_list_body():
    with patch(HARMONIC_REQUEST, new=AsyncMock(return_value=_response(json_data={"error": "not a list"}))):
        with pytest.raises(ValueError):
            await _client().get_enrichment_status(["urn:harmonic:enrichment:aaa"])


@pytest.mark.asyncio
async def test_get_enrichment_status_reraises_on_http_error():
    with patch(HARMONIC_REQUEST, new=AsyncMock(return_value=_http_500())):
        with pytest.raises(aiohttp.ClientResponseError):
            await _client().get_enrichment_status(["urn:harmonic:enrichment:aaa"])


@pytest.mark.asyncio
@patch(PACE_SECONDS_HARMONIC, return_value=0.0)
@patch(ADMISSION_INTERVAL_HARMONIC, new=lambda priority: 0.0)
@patch(ASYNCIO_SLEEP, new_callable=AsyncMock)
@patch(ASYNCIO_TO_THREAD, new=_fake_to_thread)
async def test_enrich_companies_batch_paces_once_per_request(mock_sleep, mock_pace):
    # A single pace for the whole batch lets a later request burst past a budget an earlier one
    # already drew down, so this asserts a pace per request against live limiter state.
    domains = ["a.com", "b.com", "c.com"]
    client = _client(priority=Priority.NORMAL)
    mock_request = AsyncMock(side_effect=[_found({"name": d}) for d in domains])
    with patch(HARMONIC_REQUEST, new=mock_request):
        results = await client.enrich_companies_batch(domains)

    assert results == [{"name": d} for d in domains]
    assert mock_pace.call_count == 3
    mock_sleep.assert_not_awaited()


@pytest.mark.asyncio
@patch(PACE_SECONDS_HARMONIC, return_value=0.0)
@patch(ADMISSION_INTERVAL_HARMONIC, new=lambda priority: 0.25)
@patch(MONOTONIC, new=lambda: 1000.0)
@patch(ASYNCIO_SLEEP, new_callable=AsyncMock)
@patch(ASYNCIO_TO_THREAD, new=_fake_to_thread)
async def test_enrich_companies_batch_spaces_admissions_by_the_lane_interval_despite_headroom(mock_sleep, mock_pace):
    # pace_seconds reads the window, which does not yet hold the calls this batch admitted but has
    # not consumed, so headroom alone would let several admissions through at once.
    domains = ["a.com", "b.com", "c.com"]
    client = _client(priority=Priority.BATCH)
    mock_request = AsyncMock(side_effect=[_found({"name": d}) for d in domains])
    wait_labels = {"source": "other", "priority": "batch"}
    wait_before = REGISTRY.get_sample_value("harmonic_api_admission_wait_seconds_sum", wait_labels) or 0.0
    with patch(HARMONIC_REQUEST, new=mock_request):
        results = await client.enrich_companies_batch(domains)

    assert results == [{"name": d} for d in domains]
    assert [call.args[0] for call in mock_sleep.await_args_list] == [0.25, 0.25]
    wait_after = REGISTRY.get_sample_value("harmonic_api_admission_wait_seconds_sum", wait_labels) or 0.0
    assert wait_after - wait_before == pytest.approx(0.5)


@pytest.mark.asyncio
async def test_enrich_companies_batch_keeps_lookup_when_wait_recording_fails() -> None:
    client = _client(priority=Priority.BATCH)
    with (
        patch(PACE_SECONDS_HARMONIC, return_value=0.0),
        patch(ADMISSION_INTERVAL_HARMONIC, return_value=0.0),
        patch(ASYNCIO_TO_THREAD, new=_fake_to_thread),
        patch(HARMONIC_REQUEST, new=AsyncMock(return_value=_found({"name": "a.com"}))),
        patch(
            "ee.billing.salesforce_enrichment.harmonic_client.record_harmonic_admission_wait",
            side_effect=RuntimeError("metric"),
        ),
    ):
        results = await client.enrich_companies_batch(["a.com"])

    assert results == [{"name": "a.com"}]


@pytest.mark.asyncio
@patch(PACE_SECONDS_HARMONIC, return_value=0.0)
@patch(ADMISSION_INTERVAL_HARMONIC, new=lambda priority: 0.0)
@patch(ASYNCIO_SLEEP, new_callable=AsyncMock)
@patch(ASYNCIO_TO_THREAD, new=_fake_to_thread)
async def test_enrich_companies_batch_backs_off_a_full_window_after_a_shed_before_retrying(mock_sleep, mock_pace):
    # A shed domain must wait out a full budget window before its retry, not just the pace (which
    # this test sets to 0). Otherwise every attempt fits inside the same instant and none of them
    # land after the budget actually frees.
    shed = HarmonicEgressBudgetExhausted("degrading")
    mock_request = AsyncMock(side_effect=[shed, shed, _found({"name": "a.com"})])
    client = _client(priority=Priority.BATCH)
    with patch(HARMONIC_REQUEST, new=mock_request):
        results = await client.enrich_companies_batch(["a.com"])

    assert results == [{"name": "a.com"}]
    mock_sleep.assert_awaited_once_with(HARMONIC_WINDOW_SECONDS)


@pytest.mark.asyncio
@patch(PACE_SECONDS_HARMONIC, return_value=0.0)
@patch(ADMISSION_INTERVAL_HARMONIC, new=lambda priority: 0.0)
@patch(ASYNCIO_TO_THREAD, new=_fake_to_thread)
async def test_enrich_companies_batch_starts_the_next_lookup_as_soon_as_any_slot_frees(mock_pace):
    # With one more domain than the in-flight cap, the extra lookup must start once any slot
    # frees, without waiting on the slowest of the first _ENRICH_MAX_CONCURRENT_LOOKUPS.
    first_started = asyncio.Event()
    release_first = asyncio.Event()
    started_domains: list[str] = []

    domains = [f"d{i}.com" for i in range(_ENRICH_MAX_CONCURRENT_LOOKUPS + 1)]

    async def request(
        session: Any,
        method: str,
        url: str,
        *,
        source: str,
        priority: Priority,
        endpoint: str,
        headers: dict[str, str],
        json: dict[str, Any],
        **kwargs: Any,
    ) -> MagicMock:
        website_url = json["variables"]["identifiers"]["websiteUrl"]
        bare_domain = website_url.removeprefix("https://").removeprefix("www.")
        started_domains.append(bare_domain)
        if bare_domain == "d0.com":
            first_started.set()
            await release_first.wait()
        return _found({"name": bare_domain})

    client = _client(priority=Priority.BATCH)
    with patch(HARMONIC_REQUEST, new=request):
        task = asyncio.create_task(client.enrich_companies_batch(domains))
        await first_started.wait()
        for _ in range(100):
            if "d10.com" in started_domains:
                break
            await _REAL_SLEEP(0)

        assert "d10.com" in started_domains

        release_first.set()
        results = await task

    assert results == [{"name": d} for d in domains]


@pytest.mark.asyncio
async def test_enrich_companies_batch_fills_the_request_budget_while_responses_are_delayed() -> None:
    domains = [f"d{i}.example.com" for i in range(20)]
    release_responses = asyncio.Event()
    first_ten_started = asyncio.Event()
    all_requests_started = asyncio.Event()
    started_count = 0
    clock = 0.0

    def current_time() -> float:
        return clock

    async def advance_clock(seconds: float) -> None:
        nonlocal clock
        clock += seconds
        await _REAL_SLEEP(0)

    async def request(*args: Any, **kwargs: Any) -> MagicMock:
        nonlocal started_count
        started_count += 1
        if started_count == 10:
            first_ten_started.set()
        if started_count == len(domains):
            all_requests_started.set()
        await release_responses.wait()
        domain = kwargs["json"]["variables"]["identifiers"]["websiteUrl"].removeprefix("https://")
        return _found({"name": domain})

    client = _client(priority=Priority.BATCH)
    with (
        patch(PACE_SECONDS_HARMONIC, return_value=0.0),
        patch(ADMISSION_INTERVAL_HARMONIC, return_value=0.1),
        patch(MONOTONIC, new=current_time),
        patch(ASYNCIO_SLEEP, new=advance_clock),
        patch(ASYNCIO_TO_THREAD, new=_fake_to_thread),
        patch(HARMONIC_REQUEST, new=request),
        patch("ee.billing.salesforce_enrichment.harmonic_client.record_harmonic_admission_wait") as wait_record,
    ):
        task = asyncio.create_task(client.enrich_companies_batch(domains))
        try:
            await asyncio.wait_for(first_ten_started.wait(), timeout=5.0)
            for _ in range(100):
                if all_requests_started.is_set():
                    break
                await _REAL_SLEEP(0)
            assert all_requests_started.is_set()
        finally:
            release_responses.set()
            results = await task

    assert results == [{"name": domain} for domain in domains]
    assert max(call.args[0] for call in wait_record.call_args_list) >= 1.0


@pytest.mark.asyncio
@patch(PACE_SECONDS_HARMONIC, return_value=0.0)
@patch(ADMISSION_INTERVAL_HARMONIC, new=lambda priority: 0.0)
@patch(ASYNCIO_SLEEP, new_callable=AsyncMock)
@patch(ASYNCIO_TO_THREAD, new=_fake_to_thread)
async def test_enrich_companies_batch_retries_a_denied_domain_in_a_later_attempt(mock_sleep, mock_pace):
    deny_count = {"c.com": 0}

    async def request(
        session: Any,
        method: str,
        url: str,
        *,
        source: str,
        priority: Priority,
        endpoint: str,
        headers: dict[str, str],
        json: dict[str, Any],
        **kwargs: Any,
    ) -> MagicMock:
        website_url = json["variables"]["identifiers"]["websiteUrl"]
        bare_domain = website_url.removeprefix("https://").removeprefix("www.")
        if bare_domain == "c.com" and deny_count["c.com"] < 2:
            deny_count["c.com"] += 1
            raise HarmonicEgressBudgetExhausted("degrading")
        return _found({"name": bare_domain})

    domains = ["a.com", "b.com", "c.com"]
    client = _client(priority=Priority.BATCH)
    with patch(HARMONIC_REQUEST, new=request):
        results = await client.enrich_companies_batch(domains)

    # c.com was shed on attempt 1 and must come back with a result once it is retried, not
    # silently become the same None a genuine miss returns.
    assert results == [{"name": "a.com"}, {"name": "b.com"}, {"name": "c.com"}]
    mock_sleep.assert_awaited_once_with(HARMONIC_WINDOW_SECONDS)


@pytest.mark.asyncio
@patch(PACE_SECONDS_HARMONIC, return_value=0.0)
@patch(ADMISSION_INTERVAL_HARMONIC, new=lambda priority: 0.0)
@patch(ASYNCIO_SLEEP, new_callable=AsyncMock)
@patch(ASYNCIO_TO_THREAD, new=_fake_to_thread)
@patch("ee.billing.salesforce_enrichment.harmonic_client.capture_exception")
async def test_enrich_companies_batch_reports_denied_forever_distinctly_from_a_not_found(
    mock_capture, mock_sleep, mock_pace
):
    async def request(
        session: Any,
        method: str,
        url: str,
        *,
        source: str,
        priority: Priority,
        endpoint: str,
        headers: dict[str, str],
        json: dict[str, Any],
        **kwargs: Any,
    ) -> MagicMock:
        website_url = json["variables"]["identifiers"]["websiteUrl"]
        bare_domain = website_url.removeprefix("https://").removeprefix("www.")
        if bare_domain == "denied.com":
            raise HarmonicEgressBudgetExhausted("degrading")
        return _not_found()

    domains = ["denied.com", "miss.com"]
    client = _client(priority=Priority.BATCH)
    with patch(HARMONIC_REQUEST, new=request):
        results = await client.enrich_companies_batch(domains)

    # Both look the same in the return value, since enrich_companies_batch keeps its list
    # compatible with callers that zip it against the input domains, but only the denied one gets
    # captured to error tracking.
    assert results == [None, None]
    captured_domains = [call.args[1]["domain"] for call in mock_capture.call_args_list]
    assert captured_domains == ["denied.com"]
    assert isinstance(mock_capture.call_args_list[0].args[0], HarmonicEgressBudgetExhausted)
    # Only the gaps between attempts wait a window; a domain that is out of attempts is reported at once.
    assert mock_sleep.await_count == _ENRICH_MAX_ATTEMPTS - 1


@pytest.mark.asyncio
@patch(PACE_SECONDS_HARMONIC, return_value=5.0)
async def test_enrich_companies_batch_propagates_cancellation_during_pacing_sleep(mock_pace):
    sleep_started = asyncio.Event()

    async def blocking_sleep(seconds: float) -> None:
        sleep_started.set()
        await _REAL_SLEEP(3600)  # the test cancels well before this would ever return

    domains = ["a.com", "b.com"]
    client = _client(priority=Priority.BATCH)
    mock_request = AsyncMock(side_effect=[_found({"name": "A"}), _found({"name": "B"})])
    with patch(HARMONIC_REQUEST, new=mock_request), patch(ASYNCIO_SLEEP, new=blocking_sleep):
        task = asyncio.create_task(client.enrich_companies_batch(domains))
        await sleep_started.wait()
        task.cancel()
        with pytest.raises(asyncio.CancelledError):
            await task


@pytest.mark.asyncio
@patch(PACE_SECONDS_HARMONIC)
@patch(ASYNCIO_SLEEP, new_callable=AsyncMock)
async def test_enrich_companies_batch_skips_pacing_for_critical_priority(mock_sleep, mock_pace):
    # CRITICAL is never shed by the transport (_raise_if_denied never raises on it), so pacing it
    # would only add latency to an interactive caller for no admission benefit.
    client = _client(priority=Priority.CRITICAL)
    mock_request = AsyncMock(side_effect=[_found({"name": "A"}), _found({"name": "B"})])
    with patch(HARMONIC_REQUEST, new=mock_request):
        results = await client.enrich_companies_batch(["a.com", "b.com"])

    assert results == [{"name": "A"}, {"name": "B"}]
    mock_pace.assert_not_called()
    mock_sleep.assert_not_awaited()


@pytest.mark.asyncio
@patch(PACE_SECONDS_HARMONIC, return_value=0.0)
@patch(ADMISSION_INTERVAL_HARMONIC, new=lambda priority: 0.0)
@patch(ASYNCIO_SLEEP, new_callable=AsyncMock)
@patch("ee.billing.salesforce_enrichment.harmonic_client.capture_exception")
async def test_enrich_companies_batch_names_the_domain_of_an_operational_failure(mock_capture, mock_sleep, mock_pace):
    async def request(session: Any, method: str, url: str, *, json: dict[str, Any], **kwargs: Any) -> MagicMock:
        website_url = json["variables"]["identifiers"]["websiteUrl"]
        if "broken.com" in website_url:
            return _graphql_errors()
        return _found({"name": "ok"})

    client = _client(priority=Priority.BATCH)
    with patch(HARMONIC_REQUEST, new=AsyncMock(side_effect=request)):
        results = await client.enrich_companies_batch(["ok.com", "broken.com"])

    assert results == [{"name": "ok"}, None]
    mock_capture.assert_called_once()
    assert mock_capture.call_args.args[1:] == ({"domain": "broken.com"},)


@pytest.mark.asyncio
@patch(PACE_SECONDS_HARMONIC, return_value=0.0)
@patch(ADMISSION_INTERVAL_HARMONIC, new=lambda priority: 0.0)
@patch(ASYNCIO_SLEEP, new_callable=AsyncMock)
async def test_enrich_companies_batch_with_a_single_domain(mock_sleep, mock_pace):
    # _enrich_specific_domain_debug calls enrich_companies_batch with exactly one domain; the
    # concurrency and retry machinery must not misbehave at that boundary.
    client = _client(priority=Priority.BATCH)
    mock_request = AsyncMock(side_effect=[_found({"name": "PostHog"})])
    with patch(HARMONIC_REQUEST, new=mock_request):
        results = await client.enrich_companies_batch(["posthog.com"])
    assert results == [{"name": "PostHog"}]