Module adcp.reporting.feed
Frozen authorized reporting feeds; the PostgreSQL store is in adcp_reporting_storage.
Sub-modules
adcp.reporting.feed.errors-
Closed errors for authorized frozen reporting reads.
adcp.reporting.feed.memory-
Reference feed participant sharing the approved memory rollback boundary.
adcp.reporting.feed.projection-
Capture version 1 from committed inputs, with exact graph closure and no I/O.
adcp.reporting.feed.request-
Normalize the complete semantic request, independently of transport models.
adcp.reporting.feed.snapshot-
Immutable wire membership and versioned private inputs for one complete walk …
adcp.reporting.feed.store-
Optional feed participant. All legacy required protocols remain unchanged.
Classes
class InMemoryReportingFeedStore (**kwargs: Any)-
Expand source code
class InMemoryReportingFeedStore(InMemoryReportingReceiptStore): """Persisted for this store's lifetime; production uses PgReportingFeedStore.""" _reporting_feed_snapshots: dict[str, tuple[bytes, str, bytes]] def _feed_projection_options(self, caller: ReportingDeliveryPrincipal) -> dict[str, Any]: return {} def _feed_snapshot( self, snapshot_id: str, caller: ReportingDeliveryPrincipal ) -> StoredFeedSnapshot | None: value = getattr(self, "_reporting_feed_snapshots", {}).get(snapshot_id) if value is None: return None document, digest, key = value if hashlib.sha256(document).hexdigest() != digest or len(key) != 32: raise ReportingFeedError("REPORTING_FEED_HISTORY_CORRUPT") snapshot = decode_snapshot(json.loads(document)) if snapshot.snapshot_id != snapshot_id: raise ReportingFeedError("REPORTING_FEED_HISTORY_CORRUPT") if snapshot.caller != caller: return None return StoredFeedSnapshot(snapshot, key) def _save_feed_snapshot(self, stored: StoredFeedSnapshot) -> None: document = canonical_json_utf8_v1(stored.snapshot.to_storage()) decode_snapshot(json.loads(document)) if not hasattr(self, "_reporting_feed_snapshots"): self._reporting_feed_snapshots = {} if stored.snapshot.snapshot_id in self._reporting_feed_snapshots: raise ReportingFeedError("REPORTING_FEED_STORAGE_UNAVAILABLE") self._reporting_feed_snapshots[stored.snapshot.snapshot_id] = ( document, hashlib.sha256(document).hexdigest(), stored.signing_key, ) def _capture_feed( self, caller: ReportingDeliveryPrincipal, request: FeedRequest, after: tuple[int, int], consumer_status_enabled: bool, ) -> ReportingFeedSnapshot: owned = tuple( (seq, who, record) for seq, who, record in getattr(self, "_delivery_records", ()) if who == caller or principal(record) == caller ) if any(who != caller or principal(record) != caller for _, who, record in owned): raise ReportingFeedError("REPORTING_FEED_HISTORY_CORRUPT") changes = tuple(ReportingReconciliationChange(seq, record) for seq, _, record in owned) return capture_feed( memory_snapshot(self, caller.account_id), changes, caller=caller, request=request, after=after, consumer_status_enabled=consumer_status_enabled, materializer_boundaries=tuple( b for b in getattr(self, "_materializer_boundaries", ()) if b.caller == caller ), receipt_boundaries=tuple( b for b in getattr(self, "_receipt_boundaries", ()) if b.caller == caller ), **self._feed_projection_options(caller), ) @storage_errors async def read_reporting_feed( self, request: dict[str, Any], *, caller: ReportingDeliveryPrincipal, consumer_status_enabled: bool = False, reauthorize: Callable[[], Awaitable[None]] | None = None, ) -> dict[str, Any]: parsed = FeedRequest.parse(request) try: async with self._mutation(): stored = None offset = 0 if parsed.cursor is not None: stored = self._feed_snapshot(token_position(parsed.cursor)[2], caller) if stored is None: raise ReportingFeedError("INVALID_CHECKPOINT") offset = stored.check(parsed.cursor, "cursor", parsed, caller) after = (0, 0) if parsed.changes_after is not None: previous = self._feed_snapshot(token_position(parsed.changes_after)[2], caller) if previous is None: raise ReportingFeedError("INVALID_CHECKPOINT") previous.check(parsed.changes_after, "checkpoint", parsed, caller) after = previous.snapshot.through if stored is not None and stored.snapshot.after != after: raise ReportingFeedError("INVALID_CHECKPOINT") if stored is None: stored = StoredFeedSnapshot( self._capture_feed(caller, parsed, after, consumer_status_enabled), secrets.token_bytes(32), ) if reauthorize is not None: await reauthorize() self._save_feed_snapshot(stored) elif reauthorize is not None: await reauthorize() return inject_context(request, stored.page(offset, parsed.limit)) except LedgerConflictError: raise ReportingFeedError("REPORTING_FEED_HISTORY_CORRUPT") from None @storage_errors async def read_reporting_feed_snapshot( self, snapshot_id: str, *, caller: ReportingDeliveryPrincipal ) -> ReportingFeedSnapshot | None: async with self._lock: stored = self._feed_snapshot(snapshot_id, caller) return stored.snapshot if stored else None async def reporting_feed_ready(self) -> bool: return TruePersisted for this store's lifetime; production uses PgReportingFeedStore.
Ancestors
- InMemoryReportingReceiptStore
- InMemoryReportingMaterializerStore
- InMemoryReportingReconciliationStore
- InMemoryReportingLedgerStore
- adcp.reporting.ledger.delivery._ReconciliationOperations
Subclasses
Methods
async def read_reporting_feed(self,
request: dict[str, Any],
*,
caller: ReportingDeliveryPrincipal,
consumer_status_enabled: bool = False,
reauthorize: Callable[[], Awaitable[None]] | None = None) ‑> dict[str, typing.Any]-
Expand source code
@storage_errors async def read_reporting_feed( self, request: dict[str, Any], *, caller: ReportingDeliveryPrincipal, consumer_status_enabled: bool = False, reauthorize: Callable[[], Awaitable[None]] | None = None, ) -> dict[str, Any]: parsed = FeedRequest.parse(request) try: async with self._mutation(): stored = None offset = 0 if parsed.cursor is not None: stored = self._feed_snapshot(token_position(parsed.cursor)[2], caller) if stored is None: raise ReportingFeedError("INVALID_CHECKPOINT") offset = stored.check(parsed.cursor, "cursor", parsed, caller) after = (0, 0) if parsed.changes_after is not None: previous = self._feed_snapshot(token_position(parsed.changes_after)[2], caller) if previous is None: raise ReportingFeedError("INVALID_CHECKPOINT") previous.check(parsed.changes_after, "checkpoint", parsed, caller) after = previous.snapshot.through if stored is not None and stored.snapshot.after != after: raise ReportingFeedError("INVALID_CHECKPOINT") if stored is None: stored = StoredFeedSnapshot( self._capture_feed(caller, parsed, after, consumer_status_enabled), secrets.token_bytes(32), ) if reauthorize is not None: await reauthorize() self._save_feed_snapshot(stored) elif reauthorize is not None: await reauthorize() return inject_context(request, stored.page(offset, parsed.limit)) except LedgerConflictError: raise ReportingFeedError("REPORTING_FEED_HISTORY_CORRUPT") from None async def read_reporting_feed_snapshot(self, snapshot_id: str, *, caller: ReportingDeliveryPrincipal) ‑> ReportingFeedSnapshot | None-
Expand source code
@storage_errors async def read_reporting_feed_snapshot( self, snapshot_id: str, *, caller: ReportingDeliveryPrincipal ) -> ReportingFeedSnapshot | None: async with self._lock: stored = self._feed_snapshot(snapshot_id, caller) return stored.snapshot if stored else None async def reporting_feed_ready(self) ‑> bool-
Expand source code
async def reporting_feed_ready(self) -> bool: return True
Inherited members
class ReportingFeedError (code: FeedErrorCode)-
Expand source code
class ReportingFeedError(RuntimeError): def __init__(self, code: FeedErrorCode) -> None: self.code = code super().__init__(_MESSAGES[code])Unspecified run-time error.
Ancestors
- builtins.RuntimeError
- builtins.Exception
- builtins.BaseException
class ReportingFeedRecord (kind: FeedKind, record_id: str, key: GlobalKey, wire_json: bytes)-
Expand source code
@dataclass(frozen=True) class ReportingFeedRecord: kind: FeedKind record_id: str key: GlobalKey wire_json: bytes = field(repr=False) def to_storage(self) -> dict[str, Any]: return { "kind": self.kind, "id": self.record_id, "key": list(self.key), "wire": json.loads(self.wire_json), }ReportingFeedRecord(kind: 'FeedKind', record_id: 'str', key: 'GlobalKey', wire_json: 'bytes')
Instance variables
var key : tuple[int, int, str, str]var kind : Literal['obligation', 'revision', 'adjustment', 'consumer_status', 'materialization', 'revision_receipt', 'adjustment_receipt']var record_id : strvar wire_json : bytes
Methods
def to_storage(self) ‑> dict[str, typing.Any]-
Expand source code
def to_storage(self) -> dict[str, Any]: return { "kind": self.kind, "id": self.record_id, "key": list(self.key), "wire": json.loads(self.wire_json), }
class ReportingFeedSnapshot (caller: ReportingDeliveryPrincipal,
snapshot_id: str,
as_of: datetime,
after: tuple[int, int],
through: tuple[int, int],
filters_json: bytes,
common_json: bytes,
records: tuple[ReportingFeedRecord, ...],
inputs_json: bytes,
representation_version: int = 1,
ownership_mode: "Literal['absent', 'bindings']" = 'absent')-
Expand source code
@dataclass(frozen=True) class ReportingFeedSnapshot: caller: ReportingDeliveryPrincipal snapshot_id: str as_of: datetime after: tuple[int, int] through: tuple[int, int] filters_json: bytes = field(repr=False) common_json: bytes = field(repr=False) records: tuple[ReportingFeedRecord, ...] = field(repr=False) inputs_json: bytes = field(repr=False) representation_version: int = 1 ownership_mode: Literal["absent", "bindings"] = "absent" @property def total_count(self) -> int: return len(self.records) @property def inputs(self) -> dict[str, Any]: """A detached PRIVATE copy. Never serialize this into a response/ext.""" return dict(json.loads(self.inputs_json)) def to_storage(self) -> dict[str, Any]: return { "version": 1, "representation_version": self.representation_version, "ownership_mode": self.ownership_mode, "account_id": self.caller.account_id, "consumer_id": self.caller.consumer_id, "snapshot_id": self.snapshot_id, "as_of": self.as_of.isoformat(), "after": list(self.after), "through": list(self.through), # Filters use ordinary JSON; keep their exact versioned bytes inside # the restricted canonical financial-history document as a string. "filters": self.filters_json.decode("ascii"), "common": json.loads(self.common_json), "total_count": self.total_count, "records": [r.to_storage() for r in self.records], "inputs": self.inputs, } @property def binding(self) -> str: # Includes the complete frozen projection and every private dependency, # not merely maxima followed by mutable reads. Principal lengths never # increase token size because the binding is a fixed SHA-256 digest. return _digest(self.to_storage())ReportingFeedSnapshot(caller: 'ReportingDeliveryPrincipal', snapshot_id: 'str', as_of: 'datetime', after: 'tuple[int, int]', through: 'tuple[int, int]', filters_json: 'bytes', common_json: 'bytes', records: 'tuple[ReportingFeedRecord, …]', inputs_json: 'bytes', representation_version: 'int' = 1, ownership_mode: "Literal['absent', 'bindings']" = 'absent')
Instance variables
var after : tuple[int, int]var as_of : datetime.datetimeprop binding : str-
Expand source code
@property def binding(self) -> str: # Includes the complete frozen projection and every private dependency, # not merely maxima followed by mutable reads. Principal lengths never # increase token size because the binding is a fixed SHA-256 digest. return _digest(self.to_storage()) var caller : ReportingDeliveryPrincipalvar common_json : bytesvar filters_json : bytesprop inputs : dict[str, Any]-
Expand source code
@property def inputs(self) -> dict[str, Any]: """A detached PRIVATE copy. Never serialize this into a response/ext.""" return dict(json.loads(self.inputs_json))A detached PRIVATE copy. Never serialize this into a response/ext.
var inputs_json : bytesvar ownership_mode : Literal['absent', 'bindings']var records : tuple[ReportingFeedRecord, ...]var representation_version : intvar snapshot_id : strvar through : tuple[int, int]prop total_count : int-
Expand source code
@property def total_count(self) -> int: return len(self.records)
Methods
def to_storage(self) ‑> dict[str, typing.Any]-
Expand source code
def to_storage(self) -> dict[str, Any]: return { "version": 1, "representation_version": self.representation_version, "ownership_mode": self.ownership_mode, "account_id": self.caller.account_id, "consumer_id": self.caller.consumer_id, "snapshot_id": self.snapshot_id, "as_of": self.as_of.isoformat(), "after": list(self.after), "through": list(self.through), # Filters use ordinary JSON; keep their exact versioned bytes inside # the restricted canonical financial-history document as a string. "filters": self.filters_json.decode("ascii"), "common": json.loads(self.common_json), "total_count": self.total_count, "records": [r.to_storage() for r in self.records], "inputs": self.inputs, }
class ReportingFeedStore (*args, **kwargs)-
Expand source code
@runtime_checkable class ReportingFeedStore(Protocol): """Trusted caller seam. The mounted handler reauthorizes every request. The request-local callback rechecks the same canonical principal before publishing a prepared snapshot or returning a continuation. It is never retained in a store, snapshot, or shared handler state. """ async def read_reporting_feed( self, request: dict[str, Any], *, caller: ReportingDeliveryPrincipal, consumer_status_enabled: bool = False, reauthorize: Callable[[], Awaitable[None]] | None = None, ) -> dict[str, Any]: ... async def read_reporting_feed_snapshot( self, snapshot_id: str, *, caller: ReportingDeliveryPrincipal, ) -> ReportingFeedSnapshot | None: ... async def reporting_feed_ready(self) -> bool: ...Trusted caller seam. The mounted handler reauthorizes every request.
The request-local callback rechecks the same canonical principal before publishing a prepared snapshot or returning a continuation. It is never retained in a store, snapshot, or shared handler state.
Ancestors
- typing.Protocol
- typing.Generic
Subclasses
Methods
async def read_reporting_feed(self,
request: dict[str, Any],
*,
caller: ReportingDeliveryPrincipal,
consumer_status_enabled: bool = False,
reauthorize: Callable[[], Awaitable[None]] | None = None) ‑> dict[str, typing.Any]-
Expand source code
async def read_reporting_feed( self, request: dict[str, Any], *, caller: ReportingDeliveryPrincipal, consumer_status_enabled: bool = False, reauthorize: Callable[[], Awaitable[None]] | None = None, ) -> dict[str, Any]: ... async def read_reporting_feed_snapshot(self, snapshot_id: str, *, caller: ReportingDeliveryPrincipal) ‑> ReportingFeedSnapshot | None-
Expand source code
async def read_reporting_feed_snapshot( self, snapshot_id: str, *, caller: ReportingDeliveryPrincipal, ) -> ReportingFeedSnapshot | None: ... async def reporting_feed_ready(self) ‑> bool-
Expand source code
async def reporting_feed_ready(self) -> bool: ...