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

• Constants
• func AddEvent(ctx context.Context, relay Relay, evt *nostr.Event) (accepted bool, message string)
• func GetAuthStatus(ctx context.Context) (pubkey string, ok bool)
• func GetListeningFilters() nostr.Filters
• type AdvancedDeleter
• type AdvancedSaver
• type Auther
• type CustomWebSocketHandler
• type EventCounter
• type Informationer
• type Injector
• type Listener
• type Logger
• type Notice
• type Option
  • func WithPerConnectionLimiter(rps rate.Limit, burst int) Option
• type Options
  • func DefaultOptions() *Options
• type Relay
• type ReqAccepter
• type Server
  • func NewServer(relay Relay, opts ...Option) (*Server, error)
  • func (s *Server) HandleNIP11(w http.ResponseWriter, r *http.Request)
  • func (s *Server) HandleWebsocket(w http.ResponseWriter, r *http.Request)
  • func (s *Server) Router() *http.ServeMux
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) Shutdown(ctx context.Context)
  • func (s *Server) Start(host string, port int, started ...chan bool) error
• type ShutdownAware
• type WebSocket
  • func (ws *WebSocket) WriteJSON(any interface{}) error
  • func (ws *WebSocket) WriteMessage(t int, b []byte) error

Constants

const AUTH_CONTEXT_KEY = iota

Functions

func AddEvent

func AddEvent(ctx context.Context, relay Relay, evt *nostr.Event) (accepted bool, message string)

AddEvent has a business rule to add an event to the relayer

func GetAuthStatus

func GetAuthStatus(ctx context.Context) (pubkey string, ok bool)

func GetListeningFilters

func GetListeningFilters() nostr.Filters

Types

type AdvancedDeleter

type AdvancedDeleter interface {
	BeforeDelete(ctx context.Context, id string, pubkey string)
	AfterDelete(id string, pubkey string)
}

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

type AdvancedSaver

type AdvancedSaver interface {
	BeforeSave(context.Context, *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 EventCounter

type EventCounter interface {
	CountEvents(ctx context.Context, filter *nostr.Filter) (int64, error)
}

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 Option

type Option func(*Options)

func WithPerConnectionLimiter

func WithPerConnectionLimiter(rps rate.Limit, burst int) Option

type Options

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

func DefaultOptions

func DefaultOptions() *Options

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 [eventstore.Store.Init].
	Init() error
	// 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(context.Context, *nostr.Event) bool
	// Storage returns the relay storage implementation.
	Storage(context.Context) eventstore.Store
}

Relay is the main interface for implementing a nostr relay.

type ReqAccepter

type ReqAccepter interface {
	// AcceptReq is called for every nostr request filters received by the
	// server. If the returned value is true, the filtres is passed on to
	// [Storage.QueryEvent].
	AcceptReq(ctx context.Context, id string, filters nostr.Filters, authedPubkey string) bool
}

ReqAccepter 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

	// in case you call Server.Start
	Addr string
	// 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(relay Relay, opts ...Option) (*Server, error)

NewServer initializes the relay and its storage using their respective Init methods, returning any non-nil errors, and returns a Server ready to listen for HTTP requests.

func (*Server) HandleNIP11

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

func (*Server) HandleWebsocket

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

func (*Server) Router

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

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)

Shutdown sends 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(host string, port int, started ...chan bool) error

type ShutdownAware

type ShutdownAware interface {
	OnShutdown(context.Context)
}

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

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