relay

Documentation

Index

• type EventMessage
• type Option
• type Relay
  • func New(c context.T, url string, opts ...Option) (r *Relay)
  • func RelayConnect(c context.T, url string, opts ...Option) (r *Relay, e error)
  • func (r *Relay) Auth(c context.T, event *event.T) (s Status, e error)
  • func (r *Relay) Close() (e error)
  • func (r *Relay) Connect(c context.T) (e error)
  • func (r *Relay) Context() context.T
  • func (r *Relay) Count(c context.T, filters filters.T, opts ...SubscriptionOption) (cnt int64, e error)
  • func (r *Relay) IsConnected() bool
  • func (r *Relay) PrepareSubscription(c context.T, filters filters.T, opts ...SubscriptionOption) (s *Subscription)
  • func (r *Relay) Publish(c context.T, evt *event.T) (s Status, e error)
  • func (r *Relay) QuerySync(c context.T, f *filter.T, opts ...SubscriptionOption) (evs []*event.T, e error)
  • func (r *Relay) String() string
  • func (r *Relay) Subscribe(c context.T, filters filters.T, opts ...SubscriptionOption) (s *Subscription, e error)
  • func (r *Relay) Write(msg []byte) <-chan error
• type Status
  • func (s Status) String() string
• type Subscription
  • func (sub *Subscription) Close()
  • func (sub *Subscription) DispatchEose()
  • func (sub *Subscription) DispatchEvent(evt *event.T)
  • func (sub *Subscription) Fire() (e error)
  • func (sub *Subscription) GetID() string
  • func (sub *Subscription) Start()
  • func (sub *Subscription) Sub(_ context.T, filters filters.T)
  • func (sub *Subscription) Unsub()
• type SubscriptionOption
• type WithAuthHandler
  • func (_ WithAuthHandler) IsRelayOption()
• type WithLabel
  • func (_ WithLabel) IsSubscriptionOption()
• type WithNoticeHandler
  • func (_ WithNoticeHandler) IsRelayOption()
• type WriteRequest

Types

type EventMessage

type EventMessage struct {
	Event event.T
	Relay string
}

type Option

type Option interface {
	IsRelayOption()
}

Option is the type of the argument passed for that. Some examples of this are WithNoticeHandler and WithAuthHandler.

type Relay

type Relay struct {
	URL           string
	RequestHeader http.Header // e.g. for origin header
	Connection    *connect.Connection
	Subscriptions *xsync.MapOf[string, *Subscription]
	Err           error

	// custom things that aren't often used
	//
	AssumeValid bool // this will skip verifying signatures for events received from this relay
	// contains filtered or unexported fields
}

func New

func New(c context.T, url string, opts ...Option) (r *Relay)

New returns a new relay. The relay connection will be closed when the context is canceled.

func RelayConnect

func RelayConnect(c context.T, url string,
	opts ...Option) (r *Relay, e error)

RelayConnect returns a relay object connected to url. Once successfully connected, cancelling ctx has no effect. To close the connection, call r.Close().

func (*Relay) Auth

func (r *Relay) Auth(c context.T, event *event.T) (s Status, e error)

Auth sends an "AUTH" command client -> relay as in NIP-42.

Status can be: success, failed, or sent (no response from relay before ctx times out).

func (*Relay) Close

func (r *Relay) Close() (e error)

func (*Relay) Connect

func (r *Relay) Connect(c context.T) (e error)

Connect tries to establish a websocket connection to r.URL. If the context expires before the connection is complete, an error is returned. Once successfully connected, context expiration has no effect: call r.Close to close the connection.

The underlying relay connection will use a background context. If you want to pass a custom context to the underlying relay connection, use New() and then Relay.Connect().

func (*Relay) Context

func (r *Relay) Context() context.T

Context retrieves the context that is associated with this relay connection.

func (*Relay) Count

func (r *Relay) Count(c context.T, filters filters.T,
	opts ...SubscriptionOption) (cnt int64, e error)

func (*Relay) IsConnected

func (r *Relay) IsConnected() bool

IsConnected returns true if the connection to this relay seems to be active.

func (*Relay) PrepareSubscription

func (r *Relay) PrepareSubscription(c context.T, filters filters.T,
	opts ...SubscriptionOption) (s *Subscription)

PrepareSubscription creates a subscription, but doesn't fire it.

Remember to Cancel subscriptions, either by calling `.Unsub()` on them or ensuring their `context.T` will be canceled at some point. Failure to do that will result in a huge number of halted goroutines being created.

func (*Relay) Publish

func (r *Relay) Publish(c context.T, evt *event.T) (s Status, e error)

Publish sends an "EVENT" command to the relay r as in NIP-01. Status can be: success, failed, or sent (no response from relay before ctx times out).

func (*Relay) QuerySync

func (r *Relay) QuerySync(c context.T, f *filter.T,
	opts ...SubscriptionOption) (evs []*event.T, e error)

func (*Relay) String

func (r *Relay) String() string

String just returns the relay URL.

func (*Relay) Subscribe

func (r *Relay) Subscribe(c context.T, filters filters.T,
	opts ...SubscriptionOption) (s *Subscription, e error)

Subscribe sends a "REQ" command to the relay r as in NIP-01. Events are returned through the channel sub.Events. The subscription is closed when context ctx is cancelled ("CLOSE" in NIP-01).

Remember to Cancel subscriptions, either by calling `.Unsub()` on them or ensuring their `context.T` will be canceled at some point. Failure to do that will result in a huge number of halted goroutines being created.

func (*Relay) Write

func (r *Relay) Write(msg []byte) <-chan error

Write queues a message to be sent to the relay.

type Status

type Status int

const (
	PublishStatusSent      Status = 0
	PublishStatusFailed    Status = -1
	PublishStatusSucceeded Status = 1
)

func (Status) String

func (s Status) String() string

type Subscription

type Subscription struct {
	Label   string
	Counter int
	Relay   *Relay
	Filters filters.T
	// for this to be treated as a COUNT and not a REQ this must be set
	CountResult chan int64
	// the Events channel emits all EVENTs that come in a Subscription will be
	// closed when the subscription ends
	Events chan *event.T

	// the EndOfStoredEvents channel gets closed when an EOSE comes for that subscription
	EndOfStoredEvents chan struct{}
	// Context will be .Done() when the subscription ends
	Context context.T
	Live    atomic.Bool
	Eosed   atomic.Bool
	Cancel  context.F
	// this keeps track of the events we've received before the EOSE that we
	// must dispatch before closing the EndOfStoredEvents channel
	Storedwg sync.WaitGroup
	// contains filtered or unexported fields
}

func (*Subscription) Close

func (sub *Subscription) Close()

Close just sends a CLOSE message. You probably want Unsub() instead.

func (*Subscription) DispatchEose

func (sub *Subscription) DispatchEose()

func (*Subscription) DispatchEvent

func (sub *Subscription) DispatchEvent(evt *event.T)

func (*Subscription) Fire

func (sub *Subscription) Fire() (e error)

Fire sends the "REQ" command to the relay.

func (*Subscription) GetID

func (sub *Subscription) GetID() string

GetID return the Nostr subscription ID as given to the Relay it is a concatenation of the label and a serial number.

func (*Subscription) Start

func (sub *Subscription) Start()

func (*Subscription) Sub

func (sub *Subscription) Sub(_ context.T, filters filters.T)

Sub sets sub.T and then calls sub.Fire(ctx). The subscription will be closed if the context expires.

func (*Subscription) Unsub

func (sub *Subscription) Unsub()

Unsub closes the subscription, sending "CLOSE" to relay as in NIP-01. Unsub() also closes the channel sub.Events and makes a new one.

type SubscriptionOption

type SubscriptionOption interface {
	IsSubscriptionOption()
}

SubscriptionOption is the type of the argument passed for that. Some examples are WithLabel.

type WithAuthHandler

type WithAuthHandler func(c context.T, authEvent *event.T) (ok bool)

WithAuthHandler takes an auth event and expects it to be signed. when not given, AUTH messages from relays are ignored.

func (WithAuthHandler) IsRelayOption

func (_ WithAuthHandler) IsRelayOption()

type WithLabel

type WithLabel string

WithLabel puts a label on the subscription (it is prepended to the automatic id) that is sent to relays.

func (WithLabel) IsSubscriptionOption

func (_ WithLabel) IsSubscriptionOption()

type WithNoticeHandler

type WithNoticeHandler func(notice string)

WithNoticeHandler just takes notices and is expected to do something with them. when not given, defaults to logging the notices.

func (WithNoticeHandler) IsRelayOption

func (_ WithNoticeHandler) IsRelayOption()

type WriteRequest

type WriteRequest struct {
	Msg    []byte
	Answer chan error
}