event_relay

event_relay

Junction model linking an Event to the Relay where it was observed.

Maps to the event_relay table in the database, recording which relay an event was received from and when it was first seen there. The database uses the event_relay_insert_cascade stored procedure to atomically insert the relay, event, and junction record in a single call.

See Also

bigbrotr.models.event: The Event model wrapped by this junction. bigbrotr.models.relay: The Relay model wrapped by this junction. bigbrotr.models.relay_metadata: Analogous junction model linking a Relay to a Metadata record.

Classes

EventRelayDbParams

Bases: NamedTuple

Positional parameters for the event-relay junction insert procedure.

Combines fields from the Event, Relay, and the junction timestamp into a single flat tuple for the event_relay_insert_cascade stored procedure.

Attributes:

• event_id (bytes) –

  Event ID as 32-byte binary (from EventDbParams).

• pubkey (bytes) –

  Author public key as 32-byte binary.

• created_at (int) –

  Unix timestamp of event creation.

• kind (int) –

  Integer event kind.

• tags (str) –

  JSON-encoded array of tag arrays.

• content (str) –

  Raw event content string.

• sig (bytes) –

  Schnorr signature as 64-byte binary.

• relay_url (str) –

  Fully normalized relay WebSocket URL (from RelayDbParams).

• relay_network (str) –

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

• relay_discovered_at (int) –

  Unix timestamp of relay discovery.

• seen_at (int) –

  Unix timestamp when the event was first observed on this relay.

See Also

EventRelay: The model that produces these parameters. EventDbParams: Source of the event fields. RelayDbParams: Source of the relay fields.

EventRelay dataclass

EventRelay(
    event: Event,
    relay: Relay,
    seen_at: int = (lambda: int(time()))(),
)

Immutable record of an Event observed on a specific Relay.

Attributes:

• event (Event) –

  The Nostr Event that was observed.

• relay (Relay) –

  The Relay where the event was seen.

• seen_at (int) –

  Unix timestamp of when the event was first seen (defaults to now).

Examples:

event_relay = EventRelay(event=event, relay=relay)
event_relay.seen_at       # Auto-set to current time
params = event_relay.to_db_params()
params.relay_url          # 'wss://relay.damus.io'
params.event_id           # Binary event ID (bytes)

Note

The flat EventRelayDbParams tuple is designed for the event_relay_insert_cascade stored procedure, which atomically inserts the relay, event, and junction record. This avoids multiple round-trips and ensures referential integrity.

See Also

Event: The event half of this junction. Relay: The relay half of this junction. EventRelayDbParams: Database parameter container produced by to_db_params(). RelayMetadata: Analogous junction model for relay-to-metadata associations.

Functions

to_db_params

to_db_params() -> EventRelayDbParams

Return cached database parameters computed during initialization.

Returns:

• EventRelayDbParams –

  EventRelayDbParams

• EventRelayDbParams –

  combining event, relay, and junction fields.

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

def to_db_params(self) -> EventRelayDbParams:
    """Return cached database parameters computed during initialization.

    Returns:
        [EventRelayDbParams][bigbrotr.models.event_relay.EventRelayDbParams]
        combining event, relay, and junction fields.
    """
    return self._db_params

from_db_params classmethod

from_db_params(params: EventRelayDbParams) -> EventRelay

Reconstruct an EventRelay from database parameters.

Splits the flat parameter tuple back into separate Event and Relay instances via their respective from_db_params() methods.

Parameters:

• params (EventRelayDbParams) –

  Database row values previously produced by to_db_params().

Returns:

• EventRelay –

  A new EventRelay instance.

Note

Both the Event and Relay are fully re-validated during reconstruction. See Relay.from_db_params() for details on the re-parsing behavior.

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

@classmethod
def from_db_params(cls, params: EventRelayDbParams) -> EventRelay:
    """Reconstruct an ``EventRelay`` from database parameters.

    Splits the flat parameter tuple back into separate
    [Event][bigbrotr.models.event.Event] and
    [Relay][bigbrotr.models.relay.Relay] instances via their respective
    [from_db_params()][bigbrotr.models.event.Event.from_db_params] methods.

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

    Returns:
        A new [EventRelay][bigbrotr.models.event_relay.EventRelay] instance.

    Note:
        Both the [Event][bigbrotr.models.event.Event] and
        [Relay][bigbrotr.models.relay.Relay] are fully re-validated during
        reconstruction. See
        [Relay.from_db_params()][bigbrotr.models.relay.Relay.from_db_params]
        for details on the re-parsing behavior.
    """
    event_params = EventDbParams(
        id=params.event_id,
        pubkey=params.pubkey,
        created_at=params.created_at,
        kind=params.kind,
        tags=params.tags,
        content=params.content,
        sig=params.sig,
    )
    relay_params = RelayDbParams(
        url=params.relay_url,
        network=params.relay_network,
        discovered_at=params.relay_discovered_at,
    )
    event = Event.from_db_params(event_params)
    relay = Relay.from_db_params(relay_params)
    return cls(event, relay, params.seen_at)

Functions