server

Documentation

Index

• type Config
• type Handler
• type Server
  • func New(c *Config) (*Server, error)
  • func (s *Server) Quit()
  • func (s *Server) Register(name string, r Handler) error

Types

type Config

type Config struct {
	// Addr is the IP+port of the socket, e.g."127.0.0.1:9090"
	// or "[::1]:9090".
	Addr string

	// TLS is a crypto/tls configuration struct. If it is present,
	// then the server will be TLS-enabled.
	TLS *tls.Config

	// Logger is the logging instance which will be used to handle
	// messages. The default is a slog.TextHandler that writes to
	// stdout, with a logging level of Debug
	Logger *slog.Logger

	// Timeout is the number of milliseconds the Server will wait
	// when performing network ops before timing out. Default
	// (zero) is no timeout. Each connection to the server is
	// handled in a separate goroutine, however, so one blocked
	// connection does not affect any others (unless you run out of
	// file descriptors for new conns).
	Timeout int64

	// Xferlim is the maximum number of bytes in a single read
	// from the network. If a request exceeds this limit, the
	// connection will be dropped. Use this to prevent memory
	// exhaustion by arbitrarily long network reads. The default
	// (0) is unlimited. The message header counts toward the
	// limit, so very small limits or payloads that bump up
	// against the limit may cause unexpected failures.
	Xferlim uint32

	// HMACKey is the secret key used to generate MACs for signing
	// and verifying messages. Default (nil) means MACs will not
	// be generated for messages sent, or expected for messages
	// received. Enabling message authentication adds significant
	// overhead for each message sent and received, so use this
	// when security outweighs performance.
	HMACKey []byte

	// Buffer sets how many instances of Msg may be queued in
	// Server.Msgr. Non-Fatal Msgs which arrive while the buffer
	// is full are dropped on the floor to prevent the Server from
	// blocking. Defaults to 64.
	Buffer int
}

Config holds values to be passed to server constuctors.

type Handler

type Handler func([]byte) (uint16, []byte, error)

Handler is the type which functions passed to Server.Register must match: taking a slice of bytes as an argument; and returning a uint16 (indicating status), a slice of bytes (the response), and an error.

Petrel reserves the status range 1-2048 for internal use. Applications may use codes in this range, but the system will interpret them according to their defined meanings (e.g. it is standard to return '200' for success with no additional context). Applications are free define the remaining codes, up to 65535, as they see fit.

type Server

type Server struct {
	// Msgr is the internal-facing channel which receives
	// notifications from connections.
	Msgr chan *p.Msg
	// Shutdown is the external-facing channel which notifies
	// applications that a Server instance is shutting down
	Shutdown chan error
	// contains filtered or unexported fields
}

Server is a Petrel server instance.

func New

func New(c *Config) (*Server, error)

New returns a new Server, ready to have handlers added.

func (*Server) Quit

func (s *Server) Quit()

Quit handles shutdown and cleanup, including waiting for any connections to terminate. When it returns, all connections are fully shut down and no more work will be done.

func (*Server) Register

func (s *Server) Register(name string, r Handler) error

Register adds a Handler function to a Server.

'name' is the command you wish this function to be the responder for.

'r' is the name of the Handler function which will be called on dispatch.