chttp

Documentation

Overview

Package chttp helps setup a http server with routing, middlewares, and more.

Index

• Variables
• func NewHandler(p NewHandlerParams) http.Handler
• func RawRoutePath(r *http.Request) string
• type Config
  • func LoadConfig(appConfig cconfig.Loader) (Config, error)
• type EmptyFS
  • func (fs *EmptyFS) Open(string) (fs.File, error)
• type HTMLDir
• type HTMLRenderFunc
• type HTMLRenderer
  • func NewHTMLRenderer(p NewHTMLRendererParams) (*HTMLRenderer, error)
• type HTMLRouter
  • func NewHTMLRouter(p NewHTMLRouterParams) (*HTMLRouter, error)
  • func (ro *HTMLRouter) HandleIndexPage(w http.ResponseWriter, r *http.Request)
  • func (ro *HTMLRouter) HandleStaticFile(w http.ResponseWriter, r *http.Request)
  • func (ro *HTMLRouter) Routes() []Route
• type Middleware
  • func HandleMiddleware(fn MiddlewareFunc) Middleware
• type MiddlewareFunc
• type NewHTMLRendererParams
• type NewHTMLRouterParams
• type NewHandlerParams
• type NewServerParams
• type ReaderWriter
  • func NewReaderWriter(html *HTMLRenderer, config Config, logger clogger.Logger) *ReaderWriter
  • func (rw *ReaderWriter) ReadJSON(w http.ResponseWriter, req *http.Request, body interface{}) bool
  • func (rw *ReaderWriter) WriteHTML(w http.ResponseWriter, r *http.Request, p WriteHTMLParams)
  • func (rw *ReaderWriter) WriteHTMLError(w http.ResponseWriter, r *http.Request, err error)
  • func (rw *ReaderWriter) WriteJSON(w http.ResponseWriter, p WriteJSONParams)
• type RequestLoggerMiddleware
  • func NewRequestLoggerMiddleware(logger clogger.Logger) *RequestLoggerMiddleware
  • func (mw *RequestLoggerMiddleware) Handle(next http.Handler) http.Handler
• type Route
• type Router
• type Server
  • func NewServer(p NewServerParams) *Server
  • func (s *Server) Run() error
• type StaticDir
• type WriteHTMLParams
• type WriteJSONParams

Variables

var URLParams = mux.Vars

URLParams returns the route variables for the current request, if any

var WireModule = wire.NewSet(
	LoadConfig,
	NewReaderWriter,
	NewRequestLoggerMiddleware,
	wire.Struct(new(NewServerParams), "*"),
	NewServer,
	wire.Struct(new(NewHTMLRouterParams), "*"),
	NewHTMLRouter,
	wire.Struct(new(NewHTMLRendererParams), "*"),
	NewHTMLRenderer,
)

WireModule can be used as part of google/wire setup.

var WireModuleEmptyHTML = wire.NewSet(
	wire.InterfaceValue(new(HTMLDir), &EmptyFS{}),
	wire.InterfaceValue(new(StaticDir), &EmptyFS{}),
	wire.Value([]HTMLRenderFunc{}),
)

WireModuleEmptyHTML provides empty/default values for html and static dirs. This can be used to satisfy wire when the project does not use/need html rendering.

Functions

func NewHandler

func NewHandler(p NewHandlerParams) http.Handler

NewHandler creates a http.Handler with the given routes and middlewares. The handler can be used with a http.Server or as an argument to StartServer.

func RawRoutePath

func RawRoutePath(r *http.Request) string

RawRoutePath returns the route path that matched for the given http.Request. This path includes the raw URL variables. For example, a route path "/foo/{id}" will be returned as-is (i.e. {id} will NOT be replaced with the actual url path)

Types

type Config

type Config struct {
	Port                    uint `default:"7501"`
	UseLocalHTML            bool `toml:"use_local_html"`
	RenderHTMLError         bool `toml:"render_html_error"`
	EnableSinglePageRouting bool `toml:"enable_single_page_routing"`
	ReadTimeoutSeconds      uint `toml:"read_timeout_seconds" default:"10"`
}

Config holds the params needed to configure Server

func LoadConfig

func LoadConfig(appConfig cconfig.Loader) (Config, error)

LoadConfig loads Config from app's config

type EmptyFS

type EmptyFS struct{}

EmptyFS is a simple implementation of fs.FS interface that only returns an error. This implementation emulates an empty directory.

func (*EmptyFS) Open

func (fs *EmptyFS) Open(string) (fs.File, error)

Open returns an error since this fs is empty.

type HTMLDir

type HTMLDir fs.FS

HTMLDir is a directory that can be embedded or found on the host system. It should contain sub-directories and files to support the WriteHTML function in ReaderWriter.

type HTMLRenderFunc

type HTMLRenderFunc struct {
	// Name for the function that can be invoked in a template
	Name string

	// Func should return a function that takes in any number of params and returns either a single return value,
	// or two return values of which the second has type error.
	Func func(r *http.Request) interface{}
}

HTMLRenderFunc can be used to register new template functions

type HTMLRenderer

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

HTMLRenderer provides functionality in rendering templatized HTML along with HTML components

func NewHTMLRenderer

func NewHTMLRenderer(p NewHTMLRendererParams) (*HTMLRenderer, error)

NewHTMLRenderer creates a new HTMLRenderer with HTML templates stored in dir and registers the provided HTML components

type HTMLRouter

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

HTMLRouter provides routes to serve (1) static assets (2) index page for an SPA

func NewHTMLRouter

func NewHTMLRouter(p NewHTMLRouterParams) (*HTMLRouter, error)

NewHTMLRouter instantiates a new Router

func (*HTMLRouter) HandleIndexPage

func (ro *HTMLRouter) HandleIndexPage(w http.ResponseWriter, r *http.Request)

HandleIndexPage renders the index.html page

func (*HTMLRouter) HandleStaticFile

func (ro *HTMLRouter) HandleStaticFile(w http.ResponseWriter, r *http.Request)

HandleStaticFile serves the requested static file as found in the web/public directory. In non-dev env, the static files are embedded in the binary.

func (*HTMLRouter) Routes

func (ro *HTMLRouter) Routes() []Route

Routes defines the HTTP routes for this router

type Middleware

type Middleware interface {
	Handle(next http.Handler) http.Handler
}

Middleware defines the interface with a Handle func which is of the MiddlewareFunc type. Implementations of Middleware can be used with NewHandler for global middlewares or Route for route-specific middlewares.

func HandleMiddleware

func HandleMiddleware(fn MiddlewareFunc) Middleware

HandleMiddleware returns an implementation of Middleware that runs the provided func.

type MiddlewareFunc

type MiddlewareFunc func(next http.Handler) http.Handler

MiddlewareFunc is a function that takes in a http.Handler and returns one as well. It allows you to execute code before or after calling the handler.

type NewHTMLRendererParams

type NewHTMLRendererParams struct {
	HTMLDir     HTMLDir
	StaticDir   StaticDir
	RenderFuncs []HTMLRenderFunc
	Config      Config
	Logger      clogger.Logger
}

NewHTMLRendererParams holds the params needed to create HTMLRenderer

type NewHTMLRouterParams

type NewHTMLRouterParams struct {
	StaticDir StaticDir
	RW        *ReaderWriter
	Config    Config
}

NewHTMLRouterParams holds the params needed to instantiate a new Router

type NewHandlerParams

type NewHandlerParams struct {
	Routers           []Router
	GlobalMiddlewares []Middleware
	Logger            clogger.Logger
}

NewHandlerParams holds the params needed for NewHandler.

type NewServerParams

type NewServerParams struct {
	Handler   http.Handler
	Lifecycle *clifecycle.Lifecycle
	Config    Config
	Logger    clogger.Logger
}

NewServerParams holds the params needed to create a server.

type ReaderWriter

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

ReaderWriter provides functions to read data from HTTP requests and write response bodies in various formats

func NewReaderWriter

func NewReaderWriter(html *HTMLRenderer, config Config, logger clogger.Logger) *ReaderWriter

NewReaderWriter instantiates a new ReaderWriter with its dependencies

func (*ReaderWriter) ReadJSON

func (rw *ReaderWriter) ReadJSON(w http.ResponseWriter, req *http.Request, body interface{}) bool

ReadJSON reads JSON from the http.Request into the body var. If the body struct has validate tags on it, the struct is also validated. If the validation fails, a BadRequest response is sent back and the function returns false.

func (*ReaderWriter) WriteHTML

func (rw *ReaderWriter) WriteHTML(w http.ResponseWriter, r *http.Request, p WriteHTMLParams)

WriteHTML writes an HTML response to the provided http.ResponseWriter. Using the given WriteHTMLParams, the HTML is generated with a layout, page, and component templates.

func (*ReaderWriter) WriteHTMLError

func (rw *ReaderWriter) WriteHTMLError(w http.ResponseWriter, r *http.Request, err error)

WriteHTMLError handles the given error. In render_error is configured to true, it writes an HTML page with the error. Errors are always logged.

func (*ReaderWriter) WriteJSON

func (rw *ReaderWriter) WriteJSON(w http.ResponseWriter, p WriteJSONParams)

WriteJSON writes a JSON response to the http.ResponseWriter. It can be configured with status code and data using WriteJSONParams.

type RequestLoggerMiddleware

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

RequestLoggerMiddleware logs each request's HTTP method, path, and status code along with user uuid (from basic auth) if any.

func NewRequestLoggerMiddleware

func NewRequestLoggerMiddleware(logger clogger.Logger) *RequestLoggerMiddleware

NewRequestLoggerMiddleware creates a new RequestLoggerMiddleware.

func (*RequestLoggerMiddleware) Handle

func (mw *RequestLoggerMiddleware) Handle(next http.Handler) http.Handler

Handle wraps the current request with a request/response recorder. It records the method path and the return status code. It logs this with the given logger.

type Route

type Route struct {
	Middlewares []Middleware
	Path        string
	Methods     []string
	Handler     http.HandlerFunc
}

Route represents a single HTTP route (ex. /api/profile) that can be configured with middlewares, path, HTTP methods, and a handler.

type Router

type Router interface {
	Routes() []Route
}

Router is used to group routes together that are returned by the Routes method.

type Server

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

Server represents a configurable HTTP server that supports graceful shutdown.

func NewServer

func NewServer(p NewServerParams) *Server

NewServer creates a new server.

func (*Server) Run

func (s *Server) Run() error

Run configures an HTTP server using the provided app config and starts it.

type StaticDir

type StaticDir fs.FS

StaticDir represents a directory that holds static resources (JS, CSS, images, etc.)

type WriteHTMLParams

type WriteHTMLParams struct {
	StatusCode     int
	Error          error
	Data           interface{}
	PageTemplate   string
	LayoutTemplate string
}

WriteHTMLParams holds the params for the WriteHTML function in ReaderWriter

type WriteJSONParams

type WriteJSONParams struct {
	StatusCode int
	Data       interface{}
}

WriteJSONParams holds the params for the WriteJSON function in ReaderWriter