"""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