relay_metadata

relay_metadata

Junction model linking a Relay to a Metadata record.

Maps to the relay_metadata table, representing a time-series snapshot that associates a relay with a specific metadata record. Metadata records are deduplicated via content-addressed hashing (SHA-256 computed in Python). The database uses the relay_metadata_insert_cascade stored procedure to atomically insert the relay, metadata, and junction record in a single call.

See Also

bigbrotr.models.relay: The Relay model wrapped by this junction. bigbrotr.models.metadata: The Metadata model wrapped by this junction. bigbrotr.models.event_relay: Analogous junction model linking a Relay to an Event.

Classes

RelayMetadataDbParams

Bases: NamedTuple

Positional parameters for the relay-metadata junction insert procedure.

Produced by RelayMetadata.to_db_params() and consumed by the relay_metadata_insert_cascade stored procedure in PostgreSQL.

Attributes:

• relay_url (str) –

  Relay WebSocket URL (from RelayDbParams).

• relay_network (str) –

  Network type string (e.g., "clearnet", "tor").

• relay_discovered_at (int) –

  Unix timestamp of relay discovery.

• metadata_id (bytes) –

  SHA-256 content hash (32 bytes, from MetadataDbParams).

• metadata_type (MetadataType) –

  MetadataType discriminator.

• metadata_data (str) –

  Canonical JSON string for JSONB storage.

• generated_at (int) –

  Unix timestamp when the metadata was collected.

See Also

RelayMetadata: The model that produces these parameters. RelayDbParams: Source of the relay fields. MetadataDbParams: Source of the metadata fields.

RelayMetadata dataclass

RelayMetadata(
    relay: Relay,
    metadata: Metadata,
    generated_at: int = (lambda: int(time()))(),
)

Immutable junction linking a Relay to a Metadata record.

The MetadataType is carried by the Metadata object and stored on both the metadata table (as part of the composite PK) and the relay_metadata junction table (as part of the compound FK) for type-filtered queries.

Attributes:

• relay (Relay) –

  The Relay this metadata belongs to.

• metadata (Metadata) –

  The Metadata record (with type and content hash).

• generated_at (int) –

  Unix timestamp when the metadata was collected (defaults to now).

Examples:

relay = Relay("wss://relay.damus.io")
meta = Metadata(type=MetadataType.NIP11_INFO, data={"name": "Damus"})
rm = RelayMetadata(relay=relay, metadata=meta)
rm.generated_at       # Auto-set to current time
params = rm.to_db_params()
params.relay_url      # 'wss://relay.damus.io'
params.metadata_type  # MetadataType.NIP11_INFO

Note

The metadata_type exists on both the metadata table (composite PK (id, metadata_type)) and the relay_metadata junction table (compound FK (metadata_id, metadata_type)). This enforces referential integrity at the type level and enables efficient type-filtered queries (e.g., "latest NIP-11 info for all relays") without joining through the metadata table.

See Also

Relay: The relay half of this junction. Metadata: The metadata half of this junction. MetadataType: Enum of metadata classifications used for filtering. RelayMetadataDbParams: Database parameter container produced by to_db_params(). EventRelay: Analogous junction model for event-to-relay associations.

Functions

to_db_params

to_db_params() -> RelayMetadataDbParams

Return cached positional parameters for the cascade insert procedure.

Returns:

• RelayMetadataDbParams –

  RelayMetadataDbParams

• RelayMetadataDbParams –

  combining relay, metadata, and junction fields.

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

def to_db_params(self) -> RelayMetadataDbParams:
    """Return cached positional parameters for the cascade insert procedure.

    Returns:
        [RelayMetadataDbParams][bigbrotr.models.relay_metadata.RelayMetadataDbParams]
        combining relay, metadata, and junction fields.
    """
    return self._db_params

from_db_params classmethod

from_db_params(
    params: RelayMetadataDbParams,
) -> RelayMetadata

Reconstruct a RelayMetadata from database parameters.

Parameters:

• params (RelayMetadataDbParams) –

  Database row values previously produced by to_db_params().

Returns:

• RelayMetadata –

  A new RelayMetadata instance.

Raises:

• ValueError –

  If the metadata content hash does not match (integrity check performed by Metadata.from_db_params()).

Note

Both the Relay and Metadata are fully re-validated during reconstruction. The relay URL is re-parsed and the metadata hash is recomputed and verified against the stored value.

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

@classmethod
def from_db_params(cls, params: RelayMetadataDbParams) -> RelayMetadata:
    """Reconstruct a ``RelayMetadata`` from database parameters.

    Args:
        params: Database row values previously produced by
            [to_db_params()][bigbrotr.models.relay_metadata.RelayMetadata.to_db_params].

    Returns:
        A new [RelayMetadata][bigbrotr.models.relay_metadata.RelayMetadata] instance.

    Raises:
        ValueError: If the metadata content hash does not match (integrity
            check performed by
            [Metadata.from_db_params()][bigbrotr.models.metadata.Metadata.from_db_params]).

    Note:
        Both the [Relay][bigbrotr.models.relay.Relay] and
        [Metadata][bigbrotr.models.metadata.Metadata] are fully re-validated
        during reconstruction. The relay URL is re-parsed and the metadata
        hash is recomputed and verified against the stored value.
    """
    relay_params = RelayDbParams(
        url=params.relay_url,
        network=params.relay_network,
        discovered_at=params.relay_discovered_at,
    )
    metadata_params = MetadataDbParams(
        id=params.metadata_id,
        data=params.metadata_data,
        type=params.metadata_type,
    )
    relay = Relay.from_db_params(relay_params)
    metadata = Metadata.from_db_params(metadata_params)
    return cls(
        relay=relay,
        metadata=metadata,
        generated_at=params.generated_at,
    )

Functions