Module adcp.reporting.outbox.status_support

Explicit optional C scheduling and per-account advertisement proof.

Functions

async def validate_status_claims(response: dict[str, Any],
*,
support: ReportingStatusSupport | None,
handler: ADCPHandler[Any] | None = None) ‑> None
Expand source code
async def validate_status_claims(
    response: dict[str, Any],
    *,
    support: ReportingStatusSupport | None,
    handler: ADCPHandler[Any] | None = None,
) -> None:
    claim = response.get("media_buy", {}).get("reporting_delivery", {}).get("status_notification")
    if claim is None:
        return
    block = response.get("media_buy", {}).get("reporting_delivery", {})
    if (
        claim != "reporting.status_changed"
        or support is None
        or block.get("status_task") != "get_reporting_status"
        or (handler is not None and support.handler is not handler)
    ):
        raise ReportingNotificationError("status_capability_requires_durable_reporting")
    if not await support.durable():
        raise ReportingNotificationError("status_capability_requires_durable_reporting")
    from adcp.server.mcp_tools import get_tools_for_handler

    assert support.handler is not None
    mounted = {t["name"] for t in get_tools_for_handler(support.handler, _include_schemas=False)}
    for field, task in block.items():
        if field.endswith("_task") and isinstance(task, str) and task not in mounted:
            raise ReportingNotificationError("reporting_capability_requires_mounted_task")

Classes

class ReportingStatusAccountSurface (*,
account_ids: tuple[str, ...],
account_surface_complete: bool,
readiness_subscriptions: tuple[ReportingNotificationSubscription, ...])
Expand source code
@dataclass(frozen=True, kw_only=True)
class ReportingStatusAccountSurface:
    account_ids: tuple[str, ...]
    account_surface_complete: bool
    readiness_subscriptions: tuple[ReportingNotificationSubscription, ...]

    def __post_init__(self) -> None:
        object.__setattr__(self, "account_ids", tuple(self.account_ids))
        object.__setattr__(self, "readiness_subscriptions", tuple(self.readiness_subscriptions))

ReportingStatusAccountSurface(*, account_ids: 'tuple[str, …]', account_surface_complete: 'bool', readiness_subscriptions: 'tuple[ReportingNotificationSubscription, …]')

Instance variables

var account_ids : tuple[str, ...]
var account_surface_complete : bool
var readiness_subscriptions : tuple[ReportingNotificationSubscription, ...]
class ReportingStatusAccountSurfaceResolver (*args, **kwargs)
Expand source code
class ReportingStatusAccountSurfaceResolver(Protocol):
    async def __call__(self) -> ReportingStatusAccountSurface:
        pass

Base class for protocol classes.

Protocol classes are defined as::

class Proto(Protocol):
    def meth(self) -> int:
        ...

Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing).

For example::

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as::

class GenProto(Protocol[T]):
    def meth(self) -> T:
        ...

Ancestors

  • typing.Protocol
  • typing.Generic
class ReportingStatusSupport (store: StatusNotificationStore,
worker: ReportingNotificationWorker,
projector: ReportingStatusProjector | None = None,
sweeper: ReportingStatusSweeper | None = None,
scheduled: bool = False,
account_ids: tuple[str, ...] = (),
account_surface_complete: bool = False,
handler: ADCPHandler[Any] | None = None,
readiness_subscriptions: tuple[ReportingNotificationSubscription, ...] = (),
account_surface_resolver: ReportingStatusAccountSurfaceResolver | None = None)
Expand source code
@dataclass(frozen=True)
class ReportingStatusSupport:
    """Mount only while the adopter schedules projector, sweep and HTTP turns.

    ``account_ids`` is the server's explicit supported account set, not an
    account-listing service or request-body identity. Global static claims
    require every one to be baselined. The protocol capability request has no
    account selector: callers must declare this enumeration complete for the
    authenticated or deployment surface, never select it from request context.
    """

    store: StatusNotificationStore
    worker: ReportingNotificationWorker
    projector: ReportingStatusProjector | None = None
    sweeper: ReportingStatusSweeper | None = None
    scheduled: bool = False
    account_ids: tuple[str, ...] = ()
    account_surface_complete: bool = False
    handler: ADCPHandler[Any] | None = None
    readiness_subscriptions: tuple[ReportingNotificationSubscription, ...] = ()
    account_surface_resolver: ReportingStatusAccountSurfaceResolver | None = None

    def _bind_handler(self, handler: ADCPHandler[Any]) -> None:
        if self.handler is not None and self.handler is not handler:
            raise ReportingNotificationError("status_handler_mismatch")
        object.__setattr__(self, "handler", handler)

    async def resolve_account_surface(self) -> ReportingStatusAccountSurface:
        if self.account_surface_resolver is None:
            return ReportingStatusAccountSurface(
                account_ids=self.account_ids,
                account_surface_complete=self.account_surface_complete,
                readiness_subscriptions=self.readiness_subscriptions,
            )
        try:
            surface = await self.account_surface_resolver()
            if not isinstance(surface, ReportingStatusAccountSurface):
                raise TypeError("status_account_surface_invalid")
        except Exception as exc:
            logger.warning("status_account_surface_unavailable")
            raise ReportingNotificationError("status_account_surface_unavailable") from exc
        return surface

    async def queue_durable(self) -> bool:
        from adcp.reporting.outbox.status_memory import InMemoryStatusNotificationStore

        if (
            not self.scheduled
            or self.projector is None
            or self.sweeper is None
            or type(self.worker) is not ReportingNotificationWorker
            or type(self.worker.cipher) is not ReportingEnvelopeCipher
            or type(self.projector) is not ReportingStatusProjector
            or type(self.sweeper) is not ReportingStatusSweeper
            or self.projector.store is not self.store
            or self.sweeper.store is not self.store
        ):
            return False
        if type(self.store) is InMemoryStatusNotificationStore:
            return False
        # A durable store proves its own queue, storage and installed schema.
        if not isinstance(self.store, ReportingDurableStatusStore):
            return False
        return await self.store.status_queue_durable(self.worker)

    async def account_ready(self, *, account_id: str) -> bool:
        surface = await self.resolve_account_surface()
        return await self._account_ready(account_id=account_id, surface=surface)

    async def _account_ready(
        self, *, account_id: str, surface: ReportingStatusAccountSurface
    ) -> bool:
        if not await self.queue_durable() or not await self.store.baseline_ready(
            account_id=account_id
        ):
            return False
        assert isinstance(self.store, ReportingDurableStatusStore)
        if await self.store.managed_delivery_recorded(account_id=account_id):
            return False  # Managed expiry/reconciliation health ships with D.
        subscriptions = await self.worker.subscriptions.list_active(
            account_id=account_id, notification_type="reporting.status_changed"
        )
        probes = tuple(s for s in surface.readiness_subscriptions if s.account_id == account_id)
        if not probes:
            return False
        identities: set[str] = set()
        for subscription in subscriptions:
            if (
                type(subscription) is not ReportingNotificationSubscription
                or subscription.account_id != account_id
                or subscription.subscriber_id in identities
                or "reporting.status_changed" not in subscription.event_types
                or not (
                    subscription.active and subscription.authorized and subscription.proof_valid
                )
            ):
                raise ReportingNotificationError("status_subscription_unready")
            ReportingNotificationSubscription.__post_init__(subscription)
            identities.add(subscription.subscriber_id)
            sender = await self.worker._sender(subscription)
            await sender.aclose()
        for subscription in probes:
            if (
                type(subscription) is not ReportingNotificationSubscription
                or "reporting.status_changed" not in subscription.event_types
                or not (
                    subscription.active and subscription.authorized and subscription.proof_valid
                )
            ):
                raise ReportingNotificationError("status_subscription_unready")
            ReportingNotificationSubscription.__post_init__(subscription)
            sender = await self.worker._sender(subscription)
            await sender.aclose()
        return True

    async def durable(self) -> bool:
        from adcp.server.mcp_tools import get_tools_for_handler

        try:
            surface = await self.resolve_account_surface()
        except ReportingNotificationError as exc:
            if str(exc) != "status_account_surface_unavailable":
                raise
            return False
        if (
            not surface.account_surface_complete
            or not surface.account_ids
            or any(not account_id for account_id in surface.account_ids)
            or not surface.readiness_subscriptions
            or self.handler is None
        ):
            return False
        projection = getattr(self.handler, "reporting_status_handler", None)
        if (
            type(projection) is not ReportingStatusHandler
            or projection._store is not getattr(self.store, "ledger", None)
            or projection._escalation != getattr(self.store, "escalation", None)
            or not projection._consumer_status_enabled
            or "get_reporting_status"
            not in {t["name"] for t in get_tools_for_handler(self.handler, _include_schemas=False)}
        ):
            return False
        return all(
            [
                await self._account_ready(account_id=a, surface=surface)
                for a in sorted(set(surface.account_ids))
            ]
        )

    async def advertised_notifications(self) -> dict[str, str]:
        """An explicit global claim, after checking the entire trusted surface."""
        return (
            {
                "status_task": "get_reporting_status",
                "status_notification": "reporting.status_changed",
            }
            if await self.durable()
            else {}
        )

Mount only while the adopter schedules projector, sweep and HTTP turns.

account_ids is the server's explicit supported account set, not an account-listing service or request-body identity. Global static claims require every one to be baselined. The protocol capability request has no account selector: callers must declare this enumeration complete for the authenticated or deployment surface, never select it from request context.

Instance variables

var account_ids : tuple[str, ...]
var account_surface_complete : bool
var account_surface_resolver : ReportingStatusAccountSurfaceResolver | None
var handler : ADCPHandler[typing.Any] | None
var projector : ReportingStatusProjector | None
var readiness_subscriptions : tuple[ReportingNotificationSubscription, ...]
var scheduled : bool
var store : StatusNotificationStore
var sweeper : ReportingStatusSweeper | None
var worker : ReportingNotificationWorker

Methods

async def account_ready(self, *, account_id: str) ‑> bool
Expand source code
async def account_ready(self, *, account_id: str) -> bool:
    surface = await self.resolve_account_surface()
    return await self._account_ready(account_id=account_id, surface=surface)
async def advertised_notifications(self) ‑> dict[str, str]
Expand source code
async def advertised_notifications(self) -> dict[str, str]:
    """An explicit global claim, after checking the entire trusted surface."""
    return (
        {
            "status_task": "get_reporting_status",
            "status_notification": "reporting.status_changed",
        }
        if await self.durable()
        else {}
    )

An explicit global claim, after checking the entire trusted surface.

async def durable(self) ‑> bool
Expand source code
async def durable(self) -> bool:
    from adcp.server.mcp_tools import get_tools_for_handler

    try:
        surface = await self.resolve_account_surface()
    except ReportingNotificationError as exc:
        if str(exc) != "status_account_surface_unavailable":
            raise
        return False
    if (
        not surface.account_surface_complete
        or not surface.account_ids
        or any(not account_id for account_id in surface.account_ids)
        or not surface.readiness_subscriptions
        or self.handler is None
    ):
        return False
    projection = getattr(self.handler, "reporting_status_handler", None)
    if (
        type(projection) is not ReportingStatusHandler
        or projection._store is not getattr(self.store, "ledger", None)
        or projection._escalation != getattr(self.store, "escalation", None)
        or not projection._consumer_status_enabled
        or "get_reporting_status"
        not in {t["name"] for t in get_tools_for_handler(self.handler, _include_schemas=False)}
    ):
        return False
    return all(
        [
            await self._account_ready(account_id=a, surface=surface)
            for a in sorted(set(surface.account_ids))
        ]
    )
async def queue_durable(self) ‑> bool
Expand source code
async def queue_durable(self) -> bool:
    from adcp.reporting.outbox.status_memory import InMemoryStatusNotificationStore

    if (
        not self.scheduled
        or self.projector is None
        or self.sweeper is None
        or type(self.worker) is not ReportingNotificationWorker
        or type(self.worker.cipher) is not ReportingEnvelopeCipher
        or type(self.projector) is not ReportingStatusProjector
        or type(self.sweeper) is not ReportingStatusSweeper
        or self.projector.store is not self.store
        or self.sweeper.store is not self.store
    ):
        return False
    if type(self.store) is InMemoryStatusNotificationStore:
        return False
    # A durable store proves its own queue, storage and installed schema.
    if not isinstance(self.store, ReportingDurableStatusStore):
        return False
    return await self.store.status_queue_durable(self.worker)
async def resolve_account_surface(self) ‑> ReportingStatusAccountSurface
Expand source code
async def resolve_account_surface(self) -> ReportingStatusAccountSurface:
    if self.account_surface_resolver is None:
        return ReportingStatusAccountSurface(
            account_ids=self.account_ids,
            account_surface_complete=self.account_surface_complete,
            readiness_subscriptions=self.readiness_subscriptions,
        )
    try:
        surface = await self.account_surface_resolver()
        if not isinstance(surface, ReportingStatusAccountSurface):
            raise TypeError("status_account_surface_invalid")
    except Exception as exc:
        logger.warning("status_account_surface_unavailable")
        raise ReportingNotificationError("status_account_surface_unavailable") from exc
    return surface