framework

Documentation

Overview

Package framework is a minimal web framework.

Index

• Constants
• func Decode(r *http.Request, val any) error
• func GetParam(ctx context.Context, param string) *string
• func GetQueryValue(r *http.Request, param string) *string
• func IsShutdown(err error) bool
• func NewRequestError(err error, statusCode int) error
• func NewRequestErrorMsg(errMsg string, statusCode int) error
• func NewShutdownError(message string) error
• func PeekRequestBody(r *http.Request) (string, error)
• func Respond(ctx context.Context, w http.ResponseWriter, data any, statusCode int) error
• func RespondError(ctx context.Context, w http.ResponseWriter, err error) error
• func RouteParams(r *http.Request) map[string]string
• func ValidateRequest(request any) error
• type ErrorResponse
• type FieldError
• type Handler
  • func WrapMiddleware(mw []Middleware, handler Handler) Handler
• type Middleware
• type RequestState
• type SafeError
  • func (err *SafeError) Error() string
• type Server
  • func NewHTTPServer(config config.ServerConfig, shutdown chan os.Signal, mw ...Middleware) *Server
  • func (s *Server) Handle(method string, path string, handler Handler, mw ...Middleware)
  • func (s *Server) SignalShutdown()

Constants

const (
	KeyRequestState ctxKey = 1
)

Functions

func Decode

func Decode(r *http.Request, val any) error

Decode reads an HTTP request body looking for a JSON document. The body is decoded into the value provided.

The provided value is checked for validation tags if it's a struct.

func GetParam

func GetParam(ctx context.Context, param string) *string

GetParam is a utility to get a path parameter from context, nil if not found

func GetQueryValue

func GetQueryValue(r *http.Request, param string) *string

GetQueryValue is a utility to get a parameter value from the query string, nil if not found

func IsShutdown

func IsShutdown(err error) bool

IsShutdown checks to see if the shutdown error is contained in the specified error value.

func NewRequestError

func NewRequestError(err error, statusCode int) error

NewRequestError wraps a provided error with an HTTP status code. This function should be used when router encounter expected errors.

func NewRequestErrorMsg

func NewRequestErrorMsg(errMsg string, statusCode int) error

NewRequestErrorMsg turns a provided string into an error with an HTTP status code. This function should be used when router encounter expected errors.

func NewShutdownError

func NewShutdownError(message string) error

NewShutdownError returns an error that causes the framework to signal. a graceful shutdown

func PeekRequestBody

func PeekRequestBody(r *http.Request) (string, error)

PeekRequestBody reads a request's body without emptying the buffer

func Respond

func Respond(ctx context.Context, w http.ResponseWriter, data any, statusCode int) error

Respond convert a Go value to JSON and sends it to the client.

func RespondError

func RespondError(ctx context.Context, w http.ResponseWriter, err error) error

TODO: add documentation

func RouteParams

func RouteParams(r *http.Request) map[string]string

RouteParams returns a map of route params and their respective values. e.g. route: /users/:id request: /users/1 map: :id -> 1

func ValidateRequest

func ValidateRequest(request any) error

Types

type ErrorResponse

type ErrorResponse struct {
	Error  string       `json:"error"`
	Fields []FieldError `json:"fields,omitempty"`
}

ErrorResponse is the structure of response error payloads sent back to the requester when validation of a request payload fails.

type FieldError

type FieldError struct {
	Field string `json:"field"`
	Error string `json:"error"`
}

FieldError is used to indicate an error with a field in a request payload.

type Handler

type Handler func(ctx context.Context, w http.ResponseWriter, r *http.Request) error

A Handler is a type that handles a http request within our own little mini framework.

func WrapMiddleware

func WrapMiddleware(mw []Middleware, handler Handler) Handler

WrapMiddleware returns a new handler that is the result of wrapping all provided middlewares around the provided handler. Think of it like an onion. Middlewares will execute in the order they are provided

type Middleware

type Middleware func(handler Handler) Handler

Middleware is a function that provides the ability to run some code before and/or after a Handler. The motivation behind writing middleware functions is to remove repeated or boilerplate code that is either not the direct concern of a given handler OR code that seems to be repeated across many router.

type RequestState

type RequestState struct {
	TraceID    string
	Now        time.Time
	StatusCode int
}

type SafeError

type SafeError struct {
	Err        error
	StatusCode int
	Fields     []FieldError
}

SafeError is used to pass an error during the request through the server with web specific context. 'Safe' here means that the error messages do not include any sensitive information and can be sent straight back to the requester

func (*SafeError) Error

func (err *SafeError) Error() string

SafeError implements the `error` interface. It uses the default message of the wrapped error. This is what will be shown in a server's logs

type Server

type Server struct {
	*httptreemux.ContextMux
	// contains filtered or unexported fields
}

Server is the entrypoint into our application and what configures our context object for each of our http router. Feel free to add any configuration data/logic on this Server struct.

func NewHTTPServer

func NewHTTPServer(config config.ServerConfig, shutdown chan os.Signal, mw ...Middleware) *Server

NewHTTPServer creates a Server that handles a set of routes for the application.

func (*Server) Handle

func (s *Server) Handle(method string, path string, handler Handler, mw ...Middleware)

Handle sets a handler function for a given HTTP method and path pair to the server mux.

func (*Server) SignalShutdown

func (s *Server) SignalShutdown()

SignalShutdown is used to gracefully shut down the server when an integrity issue is identified.