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 CustomWebSocketHandler
- type Informationer
- type Injector
- type Listener
- type Logger
- type Notice
- type Relay
- type Server
- type Settings
- type ShutdownAware
- type Storage
- type WebSocket
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetListeningFilters ¶
func GetListeningFilters() nostr.Filters
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 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 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 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 ¶
NewServer creates a relay server with sensible defaults. The provided address is used to listen and respond to HTTP requests.
func (*Server) Addr ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.