relayer

package module
v1.7.3 Latest Latest
Warning

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

Go to latest
Published: Mar 31, 2023 License: Unlicense Imports: 21 Imported by: 9

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.

GoDoc

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddEvent added in v1.5.2

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 added in v1.6.0

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 added in v1.5.0

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

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

type AdvancedQuerier added in v1.5.0

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

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

type AdvancedSaver added in v1.5.0

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

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

type Auther added in v1.7.0

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 added in v1.5.2

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 added in v1.5.0

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 added in v1.6.0

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 added in v1.6.0

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 added in v1.6.0

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 added in v1.6.0

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 added in v1.6.0

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 added in v1.6.0

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

ServeHTTP implements http.Handler interface.

func (*Server) Shutdown added in v1.6.0

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 added in v1.6.0

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 added in v1.6.0

type ShutdownAware interface {
	OnShutdown(context.Context)
}

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

type Storage added in v1.5.0

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 added in v1.2.0

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

func (*WebSocket) WriteJSON added in v1.2.0

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

func (*WebSocket) WriteMessage added in v1.2.0

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

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL