comms

Documentation

Index

• Constants
• func NextID() uint64
• func UseLogger(logger dex.Logger)
• type HTTPHandler
• type Link
• type MsgHandler
• type RPCConfig
• type Server
  • func NewServer(cfg *RPCConfig) (*Server, error)
  • func (s *Server) Broadcast(msg *msgjson.Message)
  • func (s *Server) EnableDataAPI(yes bool)
  • func (s *Server) LimitRate(next http.Handler) http.Handler
  • func (s *Server) Mux() *chi.Mux
  • func (s *Server) NewRouteHandler(route string) func(w http.ResponseWriter, r *http.Request)
  • func (s *Server) RegisterHTTP(route string, handler HTTPHandler)
  • func (s *Server) Route(route string, handler MsgHandler)
  • func (s *Server) Run(ctx context.Context)

Constants

const (
	CtxThing contextKey = iota
)

These are the keys for different types of values stored in a request context.

Functions

func NextID

func NextID() uint64

NextID returns a unique ID to identify a request-type message.

func UseLogger

func UseLogger(logger dex.Logger)

UseLogger uses a specified Logger to output package logging info.

Types

type HTTPHandler

type HTTPHandler func(thing any) (any, error)

HTTPHandler describes a handler for an HTTP route.

type Link

type Link interface {
	// Done returns a channel that is closed when the link goes down.
	Done() <-chan struct{}
	// ID returns a unique ID by which this connection can be identified.
	ID() uint64
	// Addr returns the string-encoded IP address.
	Addr() string
	// Send sends the msgjson.Message to the peer.
	Send(msg *msgjson.Message) error
	// SendRaw sends the raw bytes which is assumed to be a marshalled
	// msgjson.Message to the peer. Can be used to avoid marshalling the
	// same message multiple times.
	SendRaw(b []byte) error
	// SendError sends the msgjson.Error to the peer, with reference to a
	// request message ID.
	SendError(id uint64, rpcErr *msgjson.Error)
	// Request sends the Request-type msgjson.Message to the client and registers
	// a handler for the response.
	Request(msg *msgjson.Message, f func(Link, *msgjson.Message), expireTime time.Duration, expire func()) error
	RequestRaw(msgID uint64, rawMsg []byte, f func(Link, *msgjson.Message), expireTime time.Duration, expire func()) error
	// Banish closes the link and quarantines the client.
	Banish()
	// Disconnect closes the link.
	Disconnect()
	// Authorized should be called from a request handler when the connection
	// becomes authorized. Request handlers must be run synchronous with other
	// reads or it will be a data race with the link's input loop.
	Authorized()
	// SetCustomID
	SetCustomID(string)
	// CustomID
	CustomID() string
}

Link is an interface for a communication channel with an API client. The reference implementation of a Link-satisfying type is the wsLink, which passes messages over a websocket connection.

type MsgHandler

type MsgHandler func(Link, *msgjson.Message) *msgjson.Error

MsgHandler describes a handler for a specific message route.

type RPCConfig

type RPCConfig struct {
	// HiddenServiceAddr is the local address to which connections from the
	// local hidden service will connect, e.g. 127.0.0.1:7252. This is not the
	// .onion address of the hidden service. The TLS key pairs do not apply to
	// these connections since TLS is not used on the hidden service's listener.
	// This corresponds to the last component of a HiddenServicePort line in a
	// torrc config file. e.g. HiddenServicePort 7232 127.0.0.1:7252. Clients
	// would specify the port preceding this address in the above statement.
	HiddenServiceAddr string
	// ListenAddrs are the addresses on which the server will listen.
	ListenAddrs []string
	// The location of the TLS keypair files. If they are not already at the
	// specified location, a keypair with a self-signed certificate will be
	// generated and saved to these locations.
	RPCKey  string
	RPCCert string
	NoTLS   bool
	// AltDNSNames specifies allowable request addresses for an auto-generated
	// TLS keypair. Changing AltDNSNames does not force the keypair to be
	// regenerated. To regenerate, delete or move the old files.
	AltDNSNames []string
	// DisableDataAPI will disable all traffic to the HTTP data API routes.
	DisableDataAPI bool
}

The RPCConfig is the server configuration settings and the only argument to the server's constructor.

type Server

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

Server is a low-level communications hub. It supports websocket clients and an HTTP API.

func NewServer

func NewServer(cfg *RPCConfig) (*Server, error)

NewServer constructs a Server that should be started with Run. The server is TLS-only, and will generate a key pair with a self-signed certificate if one is not provided as part of the RPCConfig. The server also maintains a IP-based quarantine to short-circuit to an error response for misbehaving clients, if necessary.

func (*Server) Broadcast

func (s *Server) Broadcast(msg *msgjson.Message)

Broadcast sends a message to all connected clients. The message should be a notification. See msgjson.NewNotification.

func (*Server) EnableDataAPI

func (s *Server) EnableDataAPI(yes bool)

EnableDataAPI enables or disables the HTTP data API endpoints.

func (*Server) LimitRate

func (s *Server) LimitRate(next http.Handler) http.Handler

LimitRate is rate-limiting middleware that checks whether a request can be fulfilled. This is intended for the /api HTTP endpoints.

func (*Server) Mux

func (s *Server) Mux() *chi.Mux

func (*Server) NewRouteHandler

func (s *Server) NewRouteHandler(route string) func(w http.ResponseWriter, r *http.Request)

NewRouteHandler creates a HandlerFunc for a route. Middleware should have already processed the request and added the request struct to the Context.

func (*Server) RegisterHTTP

func (s *Server) RegisterHTTP(route string, handler HTTPHandler)

func (*Server) Route

func (s *Server) Route(route string, handler MsgHandler)

Route registers a handler for a specified route. The handler map is global and has no mutex protection. All calls to Route should be done before the Server is started.

func (*Server) Run

func (s *Server) Run(ctx context.Context)

Run starts the server. Run should be called only after all routes are registered.