types

types

Shared domain types for BigBrotr services.

Lightweight dataclasses produced by query functions and consumed by services. Keeping them in their own module avoids circular imports between queries and individual service packages.

Each ServiceStateType has a corresponding typed class:

• CHECKPOINT → Checkpoint (with subclasses ApiCheckpoint, MonitorCheckpoint, PublishCheckpoint, CandidateCheckpoint)
• CURSOR → Cursor (with subclasses SyncCursor, FinderCursor)

Classes

Checkpoint dataclass

Checkpoint(key: str, timestamp: int = 0)

Timestamp-based progress marker stored in service_state.

Represents a CHECKPOINT record: a named key with a Unix timestamp tracking when the associated entity was last processed.

Subclass per usage to enable type-level disambiguation:

• ApiCheckpoint
• MonitorCheckpoint
• PublishCheckpoint
• CandidateCheckpoint

Attributes:

• key (str) –

  State key identifying the entity (relay URL, API source URL, or a named marker like "last_announcement").

• timestamp (int) –

  Unix timestamp of the last processing event (defaults to 0).

ApiCheckpoint dataclass

ApiCheckpoint(key: str, timestamp: int = 0)

Bases: Checkpoint

Checkpoint for API source polling (Finder).

Tracks when an external API endpoint was last queried for relay discovery. The key is the API source URL.

MonitorCheckpoint dataclass

MonitorCheckpoint(key: str, timestamp: int = 0)

Bases: Checkpoint

Checkpoint for relay health monitoring (Monitor).

Tracks when a relay was last health-checked. The key is the relay URL.

PublishCheckpoint dataclass

PublishCheckpoint(key: str, timestamp: int = 0)

Bases: Checkpoint

Checkpoint for Nostr event publishing (Monitor).

Tracks when a periodic event (announcement, profile) was last published. The key is a named marker (e.g. "last_announcement").

CandidateCheckpoint dataclass

CandidateCheckpoint(
    key: str,
    timestamp: int = 0,
    *,
    network: NetworkType,
    failures: int = 0,
)

Bases: Checkpoint

Checkpoint for relay validation candidates (Validator).

Tracks candidate relay URLs with a failure counter and network type. The key is the relay URL, timestamp is the insertion time (for new candidates) or last validation attempt time (for retries).

Created by insert_relays_as_candidates and fetched by fetch_candidates.

Attributes:

• key (str) –

  Relay URL (inherited from Checkpoint).

• timestamp (int) –

  Unix timestamp of creation or last attempt (inherited).

• network (NetworkType) –

  NetworkType of the candidate relay.

• failures (int) –

  Number of failed validation attempts (0 for new candidates).

Cursor dataclass

Cursor(key: str, timestamp: int = 0, id: str = '0' * 64)

Composite pagination cursor stored in service_state.

Tracks a position within an ordered stream using a (timestamp, id) pair for deterministic tie-breaking. Both fields default to sentinel values (0 and "0" * 64) representing "scan from beginning".

Subclass per usage to enable type-level disambiguation:

• SyncCursor
• FinderCursor

Attributes:

• key (str) –

  State key identifying the entity (typically a relay URL).

• timestamp (int) –

  Unix timestamp of the last processed record (default 0).

• id (str) –

  Hex-encoded 64-char event ID for deterministic tie-breaking (default "0" * 64).

SyncCursor dataclass

SyncCursor(
    key: str, timestamp: int = 0, id: str = "0" * 64
)

Bases: Cursor

Per-relay cursor for event synchronization (Synchronizer).

Tracks how far event fetching has progressed for a given relay. timestamp is the event created_at, id is the event ID.

FinderCursor dataclass

FinderCursor(
    key: str, timestamp: int = 0, id: str = "0" * 64
)

Bases: Cursor

Per-relay cursor for event scanning pagination (Finder).

Tracks how far local event scanning has progressed for a given relay. timestamp is the seen_at from the event_relay junction, id is the event ID for tie-breaking.