ws

package
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 15, 2025 License: Unlicense Imports: 37 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {
	URL string

	Connection    *Connection
	Subscriptions *xsync.MapOf[string, *Subscription]

	ConnectionError 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
}

Client represents a connection to a Nostr relay.

func NewRelay 

func NewRelay(ctx context.Context, url string, opts ...RelayOption) *Client

NewRelay returns a new relay. It takes a context that, when canceled, will close the relay connection.

func RelayConnect 

func RelayConnect(ctx context.Context, url string, opts ...RelayOption) (
	*Client, error,
)

RelayConnect returns a relay object connected to url.

The given subscription is only used during the connection phase. Once successfully connected, cancelling ctx has no effect.

The ongoing relay connection uses a background context. To close the connection, call r.Close(). If you need fine grained long-term connection contexts, use NewRelay() instead.

func (*Client) Auth 

func (r *Client) Auth(
	ctx context.Context, sign signer.I,
) (err error)

Auth sends an "AUTH" command client->relay as in NIP-42 and waits for an OK response.

You don't have to build the AUTH event yourself, this function takes a function to which the event that must be signed will be passed, so it's only necessary to sign that.

func (*Client) Close 

func (r *Client) Close() error

Close closes the relay connection.

func (*Client) CloseWithReason added in v0.4.9 

func (r *Client) CloseWithReason(reason error) error

CloseWithReason closes the relay connection with a specific reason that will be stored as the context cancel cause.

func (*Client) Connect 

func (r *Client) Connect(ctx context.Context) 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 given context here is only used during the connection phase. The long-living relay connection will be based on the context given to NewRelay().

func (*Client) ConnectWithTLS 

func (r *Client) ConnectWithTLS(
	ctx context.Context, tlsConfig *tls.Config,
) error

ConnectWithTLS is like Connect(), but takes a special tls.Config if you need that.

func (*Client) ConnectionCause added in v0.4.9 

func (r *Client) ConnectionCause() error

ConnectionCause returns the cancel cause for the relay connection context.

func (*Client) Context 

func (r *Client) Context() context.Context

Context retrieves the context that is associated with this relay connection. It will be closed when the relay is disconnected.

func (*Client) IsConnected 

func (r *Client) IsConnected() bool

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

func (*Client) LastError added in v0.4.9 

func (r *Client) LastError() error

LastError returns the last connection error observed by the reader loop.

func (*Client) PrepareSubscription 

func (r *Client) PrepareSubscription(
	ctx context.Context, ff *filter.S, opts ...SubscriptionOption,
) (sub *Subscription)

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

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

func (*Client) Publish 

func (r *Client) Publish(ctx context.Context, ev *event.E) error

Publish sends an "EVENT" command to the relay r as in NIP-01 and waits for an OK response.

func (*Client) QueryEvents 

func (r *Client) QueryEvents(
	ctx context.Context, f *filter.F, opts ...SubscriptionOption,
) (
	evc event.C, err error,
)

QueryEvents subscribes to events matching the given filter and returns a channel of events.

In most cases it's better to use SimplePool instead of this method.

func (*Client) QuerySync 

func (r *Client) QuerySync(
	ctx context.Context, ff *filter.F, opts ...SubscriptionOption,
) (
	[]*event.E, error,
)

QuerySync subscribes to events matching the given filter and returns a slice of events. This method blocks until all events are received or the context is canceled.

In most cases it's better to use SimplePool instead of this method.

func (*Client) String 

func (r *Client) String() string

String just returns the relay URL.

func (*Client) Subscribe 

func (r *Client) Subscribe(
	ctx context.Context, ff *filter.S, opts ...SubscriptionOption,
) (*Subscription, 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.Context` will be canceled at some point. Failure to do that will result in a huge number of halted goroutines being created.

func (*Client) Write 

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

Write queues an arbitrary message to be sent to the relay.

type Connection 

type Connection struct {
	// contains filtered or unexported fields
}

Connection represents a websocket connection to a Nostr relay.

func NewConnection 

func NewConnection(
	ctx context.Context, url string, reqHeader http.Header,
	tlsConfig *tls.Config,
) (c *Connection, err error)

NewConnection creates a new websocket connection to a Nostr relay.

func (*Connection) Close 

func (c *Connection) Close() error

Close closes the websocket connection.

func (*Connection) Ping 

func (c *Connection) Ping(ctx context.Context) error

Ping sends a ping message to the websocket connection.

func (*Connection) ReadMessage 

func (c *Connection) ReadMessage(
	ctx context.Context, buf io.Writer,
) (err error)

ReadMessage reads arbitrary bytes from the websocket connection into the provided buffer.

func (*Connection) WriteMessage 

func (c *Connection) WriteMessage(
	ctx context.Context, data []byte,
) (err error)

WriteMessage writes arbitrary bytes to the websocket connection.

type RelayOption 

type RelayOption interface {
	ApplyRelayOption(*Client)
}

RelayOption is the type of the argument passed when instantiating relay connections.

type ReplaceableKey 

type ReplaceableKey struct {
	PubKey string
	D      string
}

type Subscription 

type Subscription struct {
	Client  *Client
	Filters *filter.S

	// the Events channel emits all EVENTs that come in a Subscription
	// will be closed when the subscription ends
	Events chan *event.E

	// the EndOfStoredEvents channel gets closed when an EOSE comes for that subscription
	EndOfStoredEvents chan struct{}

	// the ClosedReason channel emits the reason when a CLOSED message is received
	ClosedReason chan string

	// Context will be .Done() when the subscription ends
	Context context.Context
	// contains filtered or unexported fields
}

Subscription represents a subscription to a relay.

func (*Subscription) Close 

func (sub *Subscription) Close()

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

func (*Subscription) Fire 

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

Fire sends the "REQ" command to the relay.

func (*Subscription) GetID 

func (sub *Subscription) GetID() string

GetID returns the subscription ID.

func (*Subscription) Sub 

func (sub *Subscription) Sub(_ context.Context, ff *filter.S)

Sub sets sub.Filters 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 when instantiating relay connections. Some examples are WithLabel.

type WithCheckDuplicate 

type WithCheckDuplicate func(id, relay string) bool

WithCheckDuplicate sets checkDuplicate on the subscription

func (WithCheckDuplicate) IsSubscriptionOption 

func (_ WithCheckDuplicate) IsSubscriptionOption()

type WithCheckDuplicateReplaceable 

type WithCheckDuplicateReplaceable func(rk ReplaceableKey, ts *timestamp.T) bool

WithCheckDuplicateReplaceable sets checkDuplicateReplaceable on the subscription

func (WithCheckDuplicateReplaceable) IsSubscriptionOption 

func (_ WithCheckDuplicateReplaceable) IsSubscriptionOption()

type WithCustomHandler 

type WithCustomHandler func(data string)

WithCustomHandler must be a function that handles any relay message that couldn't be parsed as a standard envelope.

func (WithCustomHandler) ApplyRelayOption 

func (ch WithCustomHandler) ApplyRelayOption(r *Client)

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 WithRequestHeader 

type WithRequestHeader http.Header

WithRequestHeader sets the HTTP request header of the websocket preflight request.

func (WithRequestHeader) ApplyRelayOption 

func (ch WithRequestHeader) ApplyRelayOption(r *Client)

Source Files

  • client.go
  • connection.go
  • connection_options.go
  • subscription.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.