socket

Documentation

Overview

Package socket provides common implementations for local APIs that use HTTP over Unix domain sockets.

Index

• func AuthMiddleware(token string, errorLogf func(f string, v ...any)) func(http.Handler) http.Handler
• func Available() bool
• func GenerateToken(len int) (string, error)
• func HeadersMiddleware(headers http.Header) func(http.Handler) http.Handler
• func LoggerMiddleware(prefix string, logf func(f string, v ...any)) func(http.Handler) http.Handler
• func WriteError(w http.ResponseWriter, err any, code int) error
• type APIErr
  • func (e APIErr) Error() string
• type Client
  • func NewClient(ctx context.Context, path, token string) (*Client, error)
  • func (c *Client) Do(ctx context.Context, method, url string, req, resp any) error
• type ErrorResponse
• type Server
  • func NewServer(socketPath string, handler http.Handler) (*Server, error)
  • func (s *Server) Close() error
  • func (s *Server) Shutdown(ctx context.Context) error
  • func (s *Server) Start() error

Functions

func AuthMiddleware

func AuthMiddleware(token string, errorLogf func(f string, v ...any)) func(http.Handler) http.Handler

AuthMiddleware is a middleware that checks the Authorization header of an incoming request for a Bearer token and checks that that token is the correct one. If there is an error while responding with an auth failure, it is logged with errorLogf.

func Available

func Available() bool

func GenerateToken

func GenerateToken(len int) (string, error)

GenerateToken generates a new random token that contains approximately 8*len bits of entropy.

func HeadersMiddleware

func HeadersMiddleware(headers http.Header) func(http.Handler) http.Handler

HeadersMiddleware is a middleware that sets common headers for all responses.

func LoggerMiddleware

func LoggerMiddleware(prefix string, logf func(f string, v ...any)) func(http.Handler) http.Handler

LoggerMiddleware logs all requests (method, URL, and handle time) with the formatted logging function (logf).

func WriteError

func WriteError(w http.ResponseWriter, err any, code int) error

WriteError writes an error as an ErrorResponse (JSON-encoded). The err value is converted to a string with fmt.Sprint.

Types

type APIErr

type APIErr struct {
	Msg        string
	StatusCode int
}

APIErr is an error type used for API error responses (the API returned a well-formed JSON ErrorResponse and a non-200 status code).

func (APIErr) Error

func (e APIErr) Error() string

type Client

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

Client is a client for a HTTP-over-Unix Domain Socket API.

func NewClient

func NewClient(ctx context.Context, path, token string) (*Client, error)

NewClient creates a new Client. The context is used for an internal check that the socket can be dialled.

func (*Client) Do

func (c *Client) Do(ctx context.Context, method, url string, req, resp any) error

Do implements the common bits of an API call. req is serialised to JSON and passed as the request body if not nil. The method is called, with the token added in the Authorization header. The response is deserialised, either into the object passed into resp if the status is 200 OK, otherwise into an error.

type ErrorResponse

type ErrorResponse struct {
	Error string `json:"error"`
}

Error response is the response body for any errors that occur

type Server

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

Server hosts a HTTP server on a Unix domain socket.

func NewServer

func NewServer(socketPath string, handler http.Handler) (*Server, error)

NewServer creates a server that, when started, will listen on a socket at the given path.

func (*Server) Close

func (s *Server) Close() error

Close immediately closes down the server. Prefer Shutdown for ordinary use.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown calls Shutdown on the inner HTTP server, which closes the socket. Shutdown performs a graceful shutdown, and is preferred over Close.

func (*Server) Start

func (s *Server) Start() error

Start starts the server.