service_state

service_state

Service state types for database persistence.

Pure data containers representing rows in the service_state table. These live in the models layer because they have zero I/O, zero package dependencies, and are used by both bigbrotr.core.brotr and bigbrotr.services.

All validation happens in __post_init__ so invalid instances never escape the constructor. Database parameter containers use NamedTuple and are cached in __post_init__ to avoid repeated conversions.

See Also

bigbrotr.core.brotr: The database facade that consumes ServiceState via upsert_service_state(), get_service_state(), and delete_service_state() methods. bigbrotr.services: Services that persist and restore processing cursors using these types.

Classes

ServiceStateType

Bases: StrEnum

Service state type identifiers for the service_state table.

Used as the state_type discriminator in ServiceState rows to distinguish between different kinds of persisted state.

Attributes:

• CHECKPOINT –

  A timestamp marker recording when an action was last performed (e.g., API fetch, relay health check, candidate validation attempt).

• CURSOR –

  A processing cursor marking the last-processed position in an ordered data source (e.g., event timestamp, relay index).

See Also

ServiceState: The row model that carries this type.

ServiceStateDbParams

Bases: NamedTuple

Database parameter container for the service_state table.

Column order matches the service_state_upsert stored procedure signature: (service_names TEXT[], state_types TEXT[], state_keys TEXT[], state_values JSONB[]).

The state_value field is pre-serialized to a JSON string, consistent with how EventDbParams.tags and MetadataDbParams.data handle JSONB columns. This allows asyncpg's registered JSONB codec to pass the value through without needing explicit ::jsonb[] casts.

See Also

ServiceState.to_db_params: Returns a cached instance of this tuple.

ServiceState dataclass

ServiceState(
    service_name: ServiceName,
    state_type: ServiceStateType,
    state_key: str,
    state_value: Mapping[str, Any],
)

A single row in the service_state table.

Used as input to Brotr.upsert_service_state() and as return type from Brotr.get_service_state().

Attributes:

• service_name (ServiceName) –

  Owning service (validated against ServiceName).

• state_type (ServiceStateType) –

  Discriminator (validated against ServiceStateType).

• state_key (str) –

  Application-defined key within the service and type (e.g., a relay URL for cursor state).

• state_value (Mapping[str, Any]) –

  Arbitrary JSON-compatible dictionary with service-specific data. Each state type stores its own business timestamp inside this dict (e.g. {"timestamp": 1700000000} for checkpoints).

Examples:

state = ServiceState(
    service_name=ServiceName.SYNCHRONIZER,
    state_type=ServiceStateType.CURSOR,
    state_key="wss://relay.damus.io",
    state_value={"timestamp": 1700000000},
)
state.to_db_params()  # ServiceStateDbParams(...)

Note

Uses object.__setattr__ in __post_init__ to set computed fields on frozen dataclasses. This is the standard workaround for frozen dataclass initialization and is safe because __post_init__ runs during __init__ before the instance is exposed to external code.

See Also

ServiceStateType: Enum of valid state_type values. ServiceStateDbParams: Database parameter container returned by to_db_params().

Functions

to_db_params

to_db_params() -> ServiceStateDbParams

Return cached database parameters.

Returns:

• ServiceStateDbParams –

  ServiceStateDbParams

• ServiceStateDbParams –

  with fields in stored procedure column order.

Source code in src/bigbrotr/models/service_state.py

def to_db_params(self) -> ServiceStateDbParams:
    """Return cached database parameters.

    Returns:
        [ServiceStateDbParams][bigbrotr.models.service_state.ServiceStateDbParams]
        with fields in stored procedure column order.
    """
    return self._db_params

Functions