Source code for fleetmesh_node.protocols.atproto.repo

"""AT Protocol Repository implementation.

Standard library only. Manages:
- Commit chain (version 3) signed with secp256k1 ECDSA.
- Monotonic Timestamp Identifiers (TID) per ATProto specification.
- Merkle Search Tree (MST) record index.
- CAR v1 archive export and import.
- Content-addressed blob storage unified with Blossom BlobStore.
"""
from __future__ import annotations

import random
import time
from typing import Any, Mapping, Optional, Union

from fleetmesh_core.conformance.errors import FleetmeshError
from fleetmesh_core.identity.atproto import ecdsa_sign
from fleetmesh_core.identity.cid import CIDLink, cid_to_sha256
from fleetmesh_core.storage.car import read_car, write_car
from fleetmesh_core.storage.mst import MST
from fleetmesh_core.wire.cbor import dag_cbor_decode, dag_cbor_encode

__all__ = [
    'RepoError',
    'tid_now',
    'Repo',
]

_TID_ALPHABET = '234567abcdefghijklmnopqrstuvwxyz'
_CLOCK_ID = random.randint(0, 1023)
_LAST_TID_MICROS = 0


[docs]class RepoError(FleetmeshError): """Base error for ATProto repository operations."""
[docs]def tid_now() -> str: """Generate a monotonic 13-character Crockford Base32 TID.""" global _LAST_TID_MICROS micros = int(time.time() * 1_000_000) if micros <= _LAST_TID_MICROS: micros = _LAST_TID_MICROS + 1 _LAST_TID_MICROS = micros val = (micros << 10) | (_CLOCK_ID & 0x3ff) chars = [] for _ in range(13): chars.append(_TID_ALPHABET[val & 0x1f]) val >>= 5 return ''.join(reversed(chars))
[docs]class Repo: """An ATProto account repository."""
[docs] def __init__( self, did: str, signing_key_hex: Optional[str] = None, blockstore: Optional[dict[CIDLink, bytes]] = None, blob_store: Optional[Any] = None, ): self.did = did self.signing_key_hex = signing_key_hex self.blockstore = blockstore if blockstore is not None else {} self.blob_store = blob_store self.head_commit_cid: Optional[CIDLink] = None self.mst = MST(blockstore=self.blockstore)
[docs] @classmethod def create( cls, did: str, signing_key_hex: str, blockstore: Optional[dict[CIDLink, bytes]] = None, blob_store: Optional[Any] = None, ) -> Repo: """Initialize a new, empty repository with an initial genesis commit.""" repo = cls(did=did, signing_key_hex=signing_key_hex, blockstore=blockstore, blob_store=blob_store) repo._create_commit(prev=None) return repo
def _create_commit(self, prev: Optional[CIDLink]) -> CIDLink: """Generate and sign a new repository commit.""" rev = tid_now() mst_root = self.mst.root_cid unsigned_commit = { 'did': self.did, 'version': 3, 'data': mst_root, 'rev': rev, 'prev': prev, } commit_bytes = dag_cbor_encode(unsigned_commit) if self.signing_key_hex is not None: sig = ecdsa_sign(commit_bytes, self.signing_key_hex) else: sig = bytes(64) signed_commit = { 'did': self.did, 'version': 3, 'data': mst_root, 'rev': rev, 'prev': prev, 'sig': sig, } signed_bytes = dag_cbor_encode(signed_commit) commit_cid = CIDLink.from_dag_cbor(signed_bytes) self.blockstore[commit_cid] = signed_bytes self.head_commit_cid = commit_cid return commit_cid
[docs] def put_record( self, collection: str, record: Mapping[str, Any], rkey: Optional[str] = None, ) -> tuple[str, CIDLink, CIDLink]: """Insert or update a record in this repository. Returns (rkey, record_cid, new_commit_cid). """ if not rkey: rkey = tid_now() key = f"{collection}/{rkey}" rec_bytes = dag_cbor_encode(record) rec_cid = CIDLink.from_dag_cbor(rec_bytes) self.blockstore[rec_cid] = rec_bytes self.mst.put(key, rec_cid) commit_cid = self._create_commit(prev=self.head_commit_cid) return rkey, rec_cid, commit_cid
[docs] def get_record(self, collection: str, rkey: str) -> Optional[tuple[CIDLink, Mapping[str, Any]]]: """Fetch a record from the repository by collection and rkey.""" key = f"{collection}/{rkey}" cid = self.mst.get(key) if cid is None: return None if cid not in self.blockstore: raise RepoError(f"missing record block: {cid}") data = dag_cbor_decode(self.blockstore[cid]) return cid, data
[docs] def delete_record(self, collection: str, rkey: str) -> CIDLink: """Remove a record and commit the updated MST. Returns new commit CID.""" key = f"{collection}/{rkey}" self.mst.delete(key) return self._create_commit(prev=self.head_commit_cid)
[docs] def list_records( self, collection: str = "", ) -> list[tuple[str, str, CIDLink, Mapping[str, Any]]]: """List all records in the repository, optionally filtered by collection. Returns list of (collection, rkey, cid, record_dict). """ prefix = f"{collection}/" if collection else "" items = self.mst.items(prefix=prefix) out: list[tuple[str, str, CIDLink, Mapping[str, Any]]] = [] for key, cid in items: parts = key.split('/', 1) col = parts[0] rk = parts[1] if len(parts) > 1 else "" if cid in self.blockstore: try: doc = dag_cbor_decode(self.blockstore[cid]) out.append((col, rk, cid, doc)) except Exception: continue return out
[docs] def put_blob(self, data: bytes, mime_type: str = "application/octet-stream") -> Mapping[str, Any]: """Store a binary blob, utilizing Blossom BlobStore if attached. Returns standard ATProto blob JSON descriptor with $link CID. """ cid = CIDLink.from_raw_blob(data) self.blockstore[cid] = data if self.blob_store is not None: try: # If Blossom BlobStore is attached, store directly if hasattr(self.blob_store, 'put'): self.blob_store.put(data) except Exception: pass return { '$type': 'blob', 'ref': {'$link': cid.cid_str}, 'mimeType': mime_type, 'size': len(data), }
[docs] def get_blob(self, cid_or_str: Union[str, CIDLink]) -> Optional[bytes]: """Retrieve binary blob data.""" cid = cid_or_str if isinstance(cid_or_str, CIDLink) else CIDLink.from_str(cid_or_str) if cid in self.blockstore: return self.blockstore[cid] if self.blob_store is not None: try: sha256_hex = cid_to_sha256(cid.cid_str) if hasattr(self.blob_store, 'get'): return self.blob_store.get(sha256_hex) except Exception: pass return None
[docs] def export_car(self) -> bytes: """Export the entire repository state into a CAR v1 archive.""" if self.head_commit_cid is None: raise RepoError("cannot export repository with no commits") return write_car(self.head_commit_cid, self.blockstore)
[docs] @classmethod def from_car( cls, car_bytes: bytes, signing_key_hex: Optional[str] = None, blob_store: Optional[Any] = None, ) -> Repo: """Reconstruct a repository from a CAR v1 archive.""" roots, blocks = read_car(car_bytes) if not roots: raise RepoError("CAR archive has no roots") head_cid = roots[0] if head_cid not in blocks: raise RepoError(f"CAR archive missing head commit block: {head_cid}") commit_doc = dag_cbor_decode(blocks[head_cid]) if not isinstance(commit_doc, dict) or 'did' not in commit_doc: raise RepoError("root block is not a valid ATProto commit") did = commit_doc['did'] mst_root = commit_doc.get('data') if not isinstance(mst_root, CIDLink): mst_root = CIDLink.from_str(str(mst_root)) repo = cls(did=did, signing_key_hex=signing_key_hex, blockstore=blocks, blob_store=blob_store) repo.head_commit_cid = head_cid repo.mst = MST(root_cid=mst_root, blocks=blocks) return repo