Source code for fleetmesh_node.protocols.atproto.firehose

"""AT Protocol Firehose WebSocket stream (`com.atproto.sync.subscribeRepos`).

Standard library only. Manages:
- Event Stream binary framing: back-to-back DAG-CBOR (Header + Body).
- Monotonic sequence numbering and subscribers.
- Frame encoder and decoder for commit and error events.
- WebSocket subscription lifecycle.
"""
from __future__ import annotations

import datetime
from typing import Any, Mapping, Optional, Sequence

from fleetmesh_core.conformance.errors import FleetmeshError
from fleetmesh_core.identity.cid import CIDLink
from fleetmesh_core.wire.cbor import cbor_decode, dag_cbor_encode

__all__ = [
    'FirehoseError',
    'encode_firehose_frame',
    'decode_firehose_frame',
    'FirehoseBroadcaster',
]


[docs]class FirehoseError(FleetmeshError): """Base error for Firehose event stream operations."""
[docs]def encode_firehose_frame(header: Mapping[str, Any], body: Mapping[str, Any]) -> bytes: """Encode an ATProto event stream frame into two concatenated DAG-CBOR objects.""" hdr_bytes = dag_cbor_encode(header) body_bytes = dag_cbor_encode(body) return hdr_bytes + body_bytes
[docs]def decode_firehose_frame(data: bytes) -> tuple[Mapping[str, Any], Mapping[str, Any]]: """Decode an ATProto event stream frame into (header, body).""" if not data: raise FirehoseError("empty firehose frame") hdr, consumed = cbor_decode(data) if not isinstance(hdr, dict): raise FirehoseError(f"invalid firehose frame header: {type(hdr)}") body, consumed_body = cbor_decode(data[consumed:]) if not isinstance(body, dict): raise FirehoseError(f"invalid firehose frame body: {type(body)}") if consumed + consumed_body != len(data): raise FirehoseError(f"unconsumed trailing bytes in firehose frame: {len(data) - (consumed + consumed_body)}") return hdr, body
[docs]class FirehoseBroadcaster: """Maintains active subscribers and broadcasts commit frames."""
[docs] def __init__(self, initial_seq: int = 1): self._seq = initial_seq self._subscribers: set[Any] = set()
@property def current_seq(self) -> int: return self._seq @property def subscriber_count(self) -> int: return len(self._subscribers)
[docs] def subscribe(self, subscriber: Any, cursor: Optional[int] = None) -> None: """Register a subscriber (e.g. WebSocket connection object).""" self._subscribers.add(subscriber)
[docs] def unsubscribe(self, subscriber: Any) -> None: """Remove a subscriber.""" self._subscribers.discard(subscriber)
[docs] def broadcast_commit( self, repo_did: str, commit_cid: CIDLink, prev_cid: Optional[CIDLink], rev: str, ops: Sequence[Mapping[str, Any]], blocks: bytes = b"", since: Optional[str] = None, ) -> tuple[int, bytes]: """Format and broadcast a #commit frame to all subscribers. Returns (seq_number, frame_bytes). """ seq = self._seq self._seq += 1 now_iso = datetime.datetime.now(datetime.timezone.utc).strftime('%Y-%m-%dT%H:%M:%S.%fZ') header = {'op': 1, 't': '#commit'} body = { 'seq': seq, 'rebase': False, 'tooBig': False, 'repo': repo_did, 'commit': commit_cid, 'prev': prev_cid, 'rev': rev, 'since': since, 'blocks': blocks, 'ops': ops, 'time': now_iso, } frame = encode_firehose_frame(header, body) # Broadcast to active subscribers dead_subs = [] for sub in self._subscribers: try: if hasattr(sub, 'send_bytes'): sub.send_bytes(frame) elif hasattr(sub, 'send_binary'): sub.send_binary(frame) elif callable(sub): sub(frame) except Exception: dead_subs.append(sub) for dead in dead_subs: self._subscribers.discard(dead) return seq, frame