relayer

README

Nostr Relay Framework -- use it to implement your own custom relay.

There is an example/reference implementation at basic. Binaries for that are also available under Releases.

Documentation

Index

• func AddEvent(relay Relay, evt nostr.Event) (accepted bool, message string)
• func GetListeningFilters() nostr.Filters
• func Start(relay Relay) error
• func StartConf(s Settings, relay Relay) error
• type AdvancedDeleter
• type AdvancedQuerier
• type AdvancedSaver
• type Auther
• type CustomWebSocketHandler
• type Informationer
• type Injector
• type Listener
• type Logger
• type Notice
• type Relay
• type Server
  • func NewServer(addr string, relay Relay) *Server
  • func (s *Server) Addr() string
  • func (s *Server) Router() *mux.Router
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) Shutdown(ctx context.Context) error
  • func (s *Server) Start() error
• type Settings
• type ShutdownAware
• type Storage
• type WebSocket
  • func (ws *WebSocket) WriteJSON(any interface{}) error
  • func (ws *WebSocket) WriteMessage(t int, b []byte) error

Functions

func AddEvent

func AddEvent(relay Relay, evt nostr.Event) (accepted bool, message string)

func GetListeningFilters

func GetListeningFilters() nostr.Filters

func Start

func Start(relay Relay) error

Start calls StartConf with Settings parsed from the process environment.

func StartConf

func StartConf(s Settings, relay Relay) error

StartConf creates a new Server, passing it host:port for the address, and starts serving propagating any error returned from Server.Start.

Types

type AdvancedDeleter

type AdvancedDeleter interface {
	BeforeDelete(id string, pubkey string)
	AfterDelete(id string, pubkey string)
}

AdvancedDeleter methods are called before and after [Storage.DeleteEvent].

type AdvancedQuerier

type AdvancedQuerier interface {
	BeforeQuery(*nostr.Filter)
	AfterQuery([]nostr.Event, *nostr.Filter)
}

AdvancedQuerier methods are called before and after [Storage.QueryEvents].

type AdvancedSaver

type AdvancedSaver interface {
	BeforeSave(*nostr.Event)
	AfterSave(*nostr.Event)
}

AdvancedSaver methods are called before and after [Storage.SaveEvent].

type Auther

type Auther interface {
	ServiceURL() string
}

Auther is the interface for implementing NIP-42. ServiceURL() returns the URL used to verify the "AUTH" event from clients.

type CustomWebSocketHandler

type CustomWebSocketHandler interface {
	HandleUnknownType(ws *WebSocket, typ string, request []json.RawMessage)
}

CustomWebSocketHandler, if implemented, is passed nostr message types unrecognized by the server. The server handles "EVENT", "REQ" and "CLOSE" messages, as described in NIP-01.

type Informationer

type Informationer interface {
	GetNIP11InformationDocument() nip11.RelayInformationDocument
}

Informationer is called to compose NIP-11 response to an HTTP request with application/nostr+json mime type. See also [Relay.Name].

type Injector

type Injector interface {
	InjectEvents() chan nostr.Event
}

type Listener

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

type Logger

type Logger interface {
	Infof(format string, v ...any)
	Warningf(format string, v ...any)
	Errorf(format string, v ...any)
}

Logger is what Server uses to log messages.

type Notice

type Notice struct {
	Kind    string `json:"kind"`
	Message string `json:"message"`
}

type Relay

type Relay interface {
	// Name is used as the "name" field in NIP-11 and as a prefix in default Server logging.
	// For other NIP-11 fields, see [Informationer].
	Name() string
	// Init is called at the very beginning by [Server.Start], allowing a relay
	// to initialize its internal resources.
	// Also see [Storage.Init].
	Init() error
	// OnInitialized is called by [Server.Start] right before starting to serve HTTP requests.
	// It is passed the server to allow callers make final adjustments, such as custom routing.
	OnInitialized(*Server)
	// AcceptEvent is called for every nostr event received by the server.
	// If the returned value is true, the event is passed on to [Storage.SaveEvent].
	// Otherwise, the server responds with a negative and "blocked" message as described
	// in NIP-20.
	AcceptEvent(*nostr.Event) bool
	// Storage returns the relay storage implementation.
	Storage() Storage
}

Relay is the main interface for implementing a nostr relay.

type Server

type Server struct {
	// Default logger, as set by NewServer, is a stdlib logger prefixed with [Relay.Name],
	// outputting to stderr.
	Log Logger
	// contains filtered or unexported fields
}

Server is a base for package users to implement nostr relays. It can serve HTTP requests and websockets, passing control over to a relay implementation.

To implement a relay, it is enough to satisfy Relay interface. Other interfaces are Informationer, CustomWebSocketHandler, ShutdownAware and AdvancedXxx types. See their respective doc comments.

The basic usage is to call Start or StartConf, which starts serving immediately. For a more fine-grained control, use NewServer. See basic/main.go, whitelisted/main.go, expensive/main.go and rss-bridge/main.go for example implementations.

The following resource is a good starting point for details on what nostr protocol is and how it works: https://github.com/nostr-protocol/nostr

func NewServer

func NewServer(addr string, relay Relay) *Server

NewServer creates a relay server with sensible defaults. The provided address is used to listen and respond to HTTP requests.

func (*Server) Addr

func (s *Server) Addr() string

Addr returns Server's HTTP listener address in host:port form. If the initial port value provided in NewServer is 0, the actual port value is picked at random and available by the time [Relay.OnInitialized] is called.

func (*Server) Router

func (s *Server) Router() *mux.Router

Router returns an http.Handler used to handle server's in-flight HTTP requests. By default, the router is setup to handle websocket upgrade and NIP-11 requests.

In a larger system, where the relay server is not the only HTTP handler, prefer using s as http.Handler instead of the returned router.

func (*Server) ServeHTTP

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

ServeHTTP implements http.Handler interface.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown stops serving HTTP requests and send a websocket close control message to all connected clients.

If the relay is ShutdownAware, Shutdown calls its OnShutdown, passing the context as is. Note that the HTTP server make some time to shutdown and so the context deadline, if any, may have been shortened by the time OnShutdown is called.

func (*Server) Start

func (s *Server) Start() error

Start initializes the relay and its storage using their respective Init methods, returning any non-nil errors, and starts listening for HTTP requests on the address provided to NewServer.

Just before starting to serve HTTP requests, Start calls Relay.OnInitialized allowing package users to make last adjustments, such as setting up custom HTTP handlers using s.Router.

Start never returns until termination of the underlying http.Server, forwarding any but http.ErrServerClosed error from the server's ListenAndServe. To terminate the server, call Shutdown.

type Settings

type Settings struct {
	Host string `envconfig:"HOST" default:"0.0.0.0"`
	Port string `envconfig:"PORT" default:"7447"`
}

Settings specify initial startup parameters for Start and StartConf.

type ShutdownAware

type ShutdownAware interface {
	OnShutdown(context.Context)
}

ShutdownAware is called during the server shutdown. See Server.Shutdown for details.

type Storage

type Storage interface {
	// Init is called at the very beginning by [Server.Start], after [Relay.Init],
	// allowing a storage to initialize its internal resources.
	Init() error

	// QueryEvents is invoked upon a client's REQ as described in NIP-01.
	QueryEvents(filter *nostr.Filter) (events []nostr.Event, err error)
	// DeleteEvent is used to handle deletion events, as per NIP-09.
	DeleteEvent(id string, pubkey string) error
	// SaveEvent is called once Relay.AcceptEvent reports true.
	SaveEvent(event *nostr.Event) error
}

Storage is a persistence layer for nostr events handled by a relay.

type WebSocket

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

func (*WebSocket) WriteJSON

func (ws *WebSocket) WriteJSON(any interface{}) error

func (*WebSocket) WriteMessage

func (ws *WebSocket) WriteMessage(t int, b []byte) error