relay

Documentation

Index

• Variables
• type Lists
  • func (l *Lists) FollowedFollows() (pks [][]byte)
  • func (l *Lists) LenFollowedFollows() (ll int)
  • func (l *Lists) LenOwnersFollowed() (ll int)
  • func (l *Lists) LenOwnersMuted() (ll int)
  • func (l *Lists) LenOwnersPubkeys() (ll int)
  • func (l *Lists) OwnersFollowed() (pks [][]byte)
  • func (l *Lists) OwnersMuted() (pks [][]byte)
  • func (l *Lists) OwnersPubkeys() (pks [][]byte)
  • func (l *Lists) SetFollowedFollows(pks [][]byte)
  • func (l *Lists) SetOwnersFollowed(pks [][]byte)
  • func (l *Lists) SetOwnersMuted(pks [][]byte)
  • func (l *Lists) SetOwnersPubkeys(pks [][]byte)
• type Server
  • func NewServer(sp *ServerParams, opts ...options.O) (s *Server, err error)
  • func (s *Server) AcceptEvent(c context.T, ev *event.E, hr *http.Request, authedPubkey []byte, remote string) (accept bool, notice string, afterSave func())
  • func (s *Server) AcceptReq(c context.T, hr *http.Request, ff *filters.T, authedPubkey []byte, ...) (allowed *filters.T, accept bool, modified bool)
  • func (s *Server) AddEvent(c context.T, rl relay.I, ev *event.E, hr *http.Request, origin string) (accepted bool, message []byte)
  • func (s *Server) AuthRequired() bool
  • func (s *Server) Context() context.T
  • func (s *Server) HandleRelayInfo(w http.ResponseWriter, r *http.Request)
  • func (s *Server) PublicReadable() bool
  • func (s *Server) Publish(c context.T, evt *event.E) (err error)
  • func (s *Server) Publisher() *publish.S
  • func (s *Server) Relay() relay.I
  • func (s *Server) Router() (router *http.ServeMux)
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) ServiceURL(req *http.Request) (st string)
  • func (s *Server) Shutdown()
  • func (s *Server) Spider(noFetch ...bool) (err error)
  • func (s *Server) SpiderFetch(k *kinds.T, noFetch, noExtract bool, pubkeys ...[]byte) (pks [][]byte, err error)
  • func (s *Server) Start(host string, port int, started ...chan bool) (err error)
  • func (s *Server) Storage() store.I
• type ServerParams

Variables

var (
	NIP20prefixmatcher = regexp.MustCompile(`^\w+: `)
)

Types

type Lists

type Lists struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Lists manages lists of pubkeys, followed users, follows, and muted users with concurrency safety via a mutex.

This list is designed primarily for owner-follow-list in mind, but with an explicit allowlist/blocklist set up, ownersFollowed corresponds to the allowed users, and ownersMuted corresponds to the blocked users, and all filtering logic will work the same way.

Currently, there is no explicit purpose for the followedFollows list being separate from the ownersFollowed list, but there could be reasons for this distinction, such as rate limiting applying to the former and not the latter.

func (*Lists) FollowedFollows

func (l *Lists) FollowedFollows() (pks [][]byte)

func (*Lists) LenFollowedFollows

func (l *Lists) LenFollowedFollows() (ll int)

func (*Lists) LenOwnersFollowed

func (l *Lists) LenOwnersFollowed() (ll int)

func (*Lists) LenOwnersMuted

func (l *Lists) LenOwnersMuted() (ll int)

func (*Lists) LenOwnersPubkeys

func (l *Lists) LenOwnersPubkeys() (ll int)

func (*Lists) OwnersFollowed

func (l *Lists) OwnersFollowed() (pks [][]byte)

func (*Lists) OwnersMuted

func (l *Lists) OwnersMuted() (pks [][]byte)

func (*Lists) OwnersPubkeys

func (l *Lists) OwnersPubkeys() (pks [][]byte)

func (*Lists) SetFollowedFollows

func (l *Lists) SetFollowedFollows(pks [][]byte)

func (*Lists) SetOwnersFollowed

func (l *Lists) SetOwnersFollowed(pks [][]byte)

func (*Lists) SetOwnersMuted

func (l *Lists) SetOwnersMuted(pks [][]byte)

func (*Lists) SetOwnersPubkeys

func (l *Lists) SetOwnersPubkeys(pks [][]byte)

type Server

type Server struct {
	Ctx    context.T
	Cancel context.F

	Addr string

	*config.C
	*Lists
	// contains filtered or unexported fields
}

Server represents the core structure for running a nostr relay. It encapsulates various components such as context, cancel function, options, relay interface, address, HTTP server, and configuration settings.

func NewServer

func NewServer(sp *ServerParams, opts ...options.O) (s *Server, err error)

NewServer initializes and returns a new Server instance based on the provided ServerParams and optional settings. It sets up storage, initializes the relay, and configures necessary components for server operation.

Parameters

- sp (*ServerParams): The configuration parameters for initializing the server.

- opts (...options.O): Optional settings that modify the server's behavior.

Return Values

- s (*Server): The newly created Server instance.

- err (error): An error if any step fails during initialization.

Expected Behaviour

- Initializes storage with the provided database path.

- Configures the server's options using the default settings and applies any optional settings provided.

- Sets up a ServeMux for handling HTTP requests.

- Initializes the relay, starting its operation in a separate goroutine.

func (*Server) AcceptEvent

func (s *Server) AcceptEvent(
	c context.T, ev *event.E, hr *http.Request, authedPubkey []byte,
	remote string,
) (accept bool, notice string, afterSave func())

AcceptEvent determines whether an incoming event should be accepted for processing based on authentication requirements.

Parameters

• c: the context of the request

• ev: pointer to the event structure

• hr: HTTP request related to the event (if any)

• authedPubkey: public key of the authenticated user (if any)

• remote: remote address from where the event was received

Return Values

• accept: boolean indicating whether the event should be accepted

• notice: string providing a message or error notice

• afterSave: function to execute after saving the event (if applicable)

Expected Behaviour:

- If authentication is required and no public key is provided, reject the event.

- Otherwise, accept the event for processing.

func (*Server) AcceptReq

func (s *Server) AcceptReq(
	c context.T, hr *http.Request, ff *filters.T,
	authedPubkey []byte, remote string,
) (allowed *filters.T, accept bool, modified bool)

AcceptReq determines whether a request should be accepted based on authentication and public readability settings.

Parameters

• c: context for the request handling

• hr: HTTP request received

• f: filters to apply

• authedPubkey: authenticated public key (if any)

• remote: remote address of the request

Return Values

• allowed: filters that are allowed after processing

• accept: boolean indicating whether the request should be accepted

• modified: boolean indicating if the request has been modified during processing

Expected Behaviour:

- If authentication is required and there's no authenticated public key, reject the request.

- Otherwise, accept the request.

func (*Server) AddEvent

func (s *Server) AddEvent(
	c context.T, rl relay.I, ev *event.E, hr *http.Request, origin string,
) (accepted bool, message []byte)

AddEvent processes an incoming event, saves it if valid, and delivers it to subscribers.

Parameters

• c: context for request handling

• rl: relay interface

• ev: the event to be added

• hr: HTTP request related to the event (if any)

• origin: origin of the event (if any)

• authedPubkey: public key of the authenticated user (if any)

Return Values

• accepted: true if the event was successfully processed, false otherwise

• message: additional information or error message related to the processing

Expected Behaviour:

- Validates the incoming event.

- Saves the event using the Publish method if it is not ephemeral.

- Handles duplicate events by returning an appropriate error message.

- Delivers the event to subscribers via the listeners' Deliver method.

- Returns a boolean indicating whether the event was accepted and any relevant message.

func (*Server) AuthRequired

func (s *Server) AuthRequired() bool

func (*Server) Context

func (s *Server) Context() context.T

func (*Server) HandleRelayInfo

func (s *Server) HandleRelayInfo(w http.ResponseWriter, r *http.Request)

HandleRelayInfo generates and returns a relay information document in JSON format based on the server's configuration and supported NIPs.

Parameters

• w: HTTP response writer used to send the generated document.

• r: HTTP request object containing incoming client request data.

Expected Behaviour

The function constructs a relay information document using either the Informer interface implementation or predefined server configuration. It returns this document as a JSON response to the client.

func (*Server) PublicReadable

func (s *Server) PublicReadable() bool

func (*Server) Publish

func (s *Server) Publish(c context.T, evt *event.E) (err error)

Publish processes and stores an event in the server's storage. It handles different types of events: ephemeral, replaceable, and parameterized replaceable.

Parameters

- c (context.Context): The context for the operation.

- evt (*event.E): The event to be published.

Return Values

- err (error): An error if any step fails during the publishing process.

Expected Behaviour

- For ephemeral events, the method doesn't store them and returns immediately.

- For replaceable events, it first queries for existing similar events, deletes older ones, and then stores the new event.

- For parameterized replaceable events, it performs a similar process but uses additional tags to identify duplicates.

func (*Server) Publisher

func (s *Server) Publisher() *publish.S

func (*Server) Relay

func (s *Server) Relay() relay.I

func (*Server) Router

func (s *Server) Router() (router *http.ServeMux)

Router retrieves and returns the HTTP ServeMux associated with the server.

Return Values

- router (*http.ServeMux): The ServeMux instance used for routing HTTP requests.

Expected Behaviour

- Returns the ServeMux that handles incoming HTTP requests to the server.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP handles incoming HTTP requests according to the standard Nostr protocol. It specifically processes WebSocket upgrades and "application/nostr+json" Accept headers.

Parameters

- w (http.ResponseWriter): The response writer for sending responses.

- r (*http.Request): The request object containing client's details and data.

Expected Behaviour

- Checks if the request URL path is "/".

- For WebSocket upgrades, calls handleWebsocket method.

- If "Accept" header is "application/nostr+json", calls HandleRelayInfo method.

- Logs the HTTP request details for non-standard requests.

- For all other paths, delegates to the internal mux's ServeHTTP method.

func (*Server) ServiceURL

func (s *Server) ServiceURL(req *http.Request) (st string)

ServiceURL constructs the service URL based on the incoming HTTP request. It checks for authentication requirements and determines the protocol (ws or wss) based on headers like X-Forwarded-Host, X-Forwarded-Proto, and the host itself.

Parameters

- req: A pointer to an http.Request object representing the incoming request.

Return Values

- st: A string representing the constructed service URL.

Expected Behaviour:

- Checks if authentication is required.

- Retrieves the host from X-Forwarded-Host or falls back to req.Host.

- Determines the protocol (ws or wss) based on various conditions including headers and host details.

- Returns the constructed URL string.

func (*Server) Shutdown

func (s *Server) Shutdown()

Shutdown gracefully shuts down the server and its components. It ensures that all resources are properly released.

Expected Behaviour

- Logs shutting down message.

- Cancels the context to stop ongoing operations.

- Closes the event store, logging the action and checking for errors.

- Shuts down the HTTP server, logging the action and checking for errors.

- If the relay implements ShutdownAware, it calls OnShutdown with the context.

func (*Server) Spider

func (s *Server) Spider(noFetch ...bool) (err error)

func (*Server) SpiderFetch

func (s *Server) SpiderFetch(
	k *kinds.T, noFetch, noExtract bool, pubkeys ...[]byte,
) (pks [][]byte, err error)

func (*Server) Start

func (s *Server) Start(
	host string, port int, started ...chan bool,
) (err error)

Start initializes the server by setting up a TCP listener and serving HTTP requests.

Parameters

- host (string): The hostname or IP address to listen on.

- port (int): The port number to bind to.

- started (...chan bool): Optional channels that are closed after the server starts successfully.

Return Values

- err (error): An error if any step fails during the server startup process.

Expected Behaviour

- Joins the host and port into a full address string.

- Logs the intention to start the relay listener at the specified address.

- Listens for TCP connections on the specified address.

- Configures an HTTP server with CORS middleware, sets timeouts, and binds it to the listener.

- If any started channels are provided, closes them upon successful startup.

- Starts serving requests using the configured HTTP server.

func (*Server) Storage

func (s *Server) Storage() store.I

type ServerParams

type ServerParams struct {
	Ctx      context.T
	Cancel   context.F
	Rl       relay.I
	DbPath   string
	MaxLimit int
	*config.C
}

ServerParams represents the configuration parameters for initializing a server. It encapsulates various components such as context, cancel function, relay interface, database path, maximum limit, and configuration settings.