waggy

README

Waggy

The dead simple, easy-to-use library for writing HTTP handlers and routers in Go that can be used in standard HTTP server environments or in WAGI (Web Assembly Gateway Interface) environments

What problems do Waggy solve?

With WAGI (Web Assembly Gateway Interface), HTTP requests are routed to specific handlers as defined in a modules.toml file (more information can be found here) to specific functions in a WASM module or WAT file. It accomplishes this by passing in the HTTP request information via os.Stdin and os.Args, and returning HTTP responses via os.Stdout. To remove considerable amounts of boilerplate code and to provide a familiar API for handling these WAGI HTTP requests, Waggy was created. It provides path parameter access functionality that will feel very reminiscent to those who have used gorilla/mux. Additionally, you can also map multiple handlers to a specific route based on the specific HTTP method that was used in the incoming request. Waggy also allows users to compile an entire server's worth of routes into a single WASM module and bypass setting up their routes via a modules.toml file if they so choose by handling mapping the route to the correct entry point (handler). But don't worry, you can also compile individual routes into their own WASM modules, too, so you can use the conventional modules.toml file for routing.

v0.5.0 improvements:

• Restricting Methods: With v0.5.0, you have the ability to restrict HTTP methods on your handlers to make sure your endpoints are more secure

• No Matched Routes: Another added feature in v0.5.0 is handling cases where no routes are matches to the route of the incoming request with generic 405 responses, as well as the ability to set custom handlers for the same edge case

How do I use Waggy?

Installing

To install Waggy in a repo, simply run

$ go get github.com/syke99/waggy

Then you can import the package in any go file you'd like

import "github.com/syke99/waggy"

Basic usage

Examples of using both Routers and Handlers for compiling WASM modules for WAGI can be found in the examples repo.

!!NOTE!!

To learn more about configuring, routing, compiling, and deploying WAGI routes, as well as the limitations of WAGI routes, please consult the WAGI docs and the TinyGo WASM docs

Who?

This library was developed by Quinn Millican (@syke99)

License

This repo is under the BSD 3 license, see LICENSE for details.

Documentation

Index

• Variables
• func ListenAndServe[W WaggyEntryPoint](addr string, entryPoint W) error
• func Serve[W WaggyEntryPoint](entryPoint W) error
• func ServeFile(w http.ResponseWriter, contentType string, filePath string)
• func Vars(r *http.Request) map[string]string
• func WriteDefaultErrorResponse(w http.ResponseWriter, r *http.Request)
• func WriteDefaultResponse(w http.ResponseWriter, r *http.Request)
• type FullServer
• type Handler
  • func NewHandler(cgi *FullServer) *Handler
  • func NewHandlerWithRoute(route string, cgi *FullServer) *Handler
  • func (wh *Handler) Handler(method string) http.HandlerFunc
  • func (wh *Handler) Logger() *Logger
  • func (wh *Handler) Methods() []string
  • func (wh *Handler) Middleware() []middleware.MiddleWare
  • func (wh *Handler) RestrictMethods(methods ...string) *Handler
  • func (wh *Handler) Route() string
  • func (wh *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (wh *Handler) UpdateRoute(route string)
  • func (wh *Handler) Use(middleWare ...middleware.MiddleWare)
  • func (wh *Handler) WithDefaultErrorResponse(err WaggyError, statusCode int) *Handler
  • func (wh *Handler) WithDefaultLogger() *Handler
  • func (wh *Handler) WithDefaultResponse(contentType string, body []byte) *Handler
  • func (wh *Handler) WithLogger(logger *Logger, parentOverride ParentLoggerOverrider) *Handler
  • func (wh *Handler) WithMethodHandler(method string, handler http.HandlerFunc) *Handler
  • func (wh *Handler) WithRestrictedMethodHandler(fn http.HandlerFunc) *Handler
• type LogLevel
• type Logger
  • func Log(r *http.Request) *Logger
  • func NewLogger(logLevel LogLevel, log *os.File) *Logger
  • func (l *Logger) Err(err error) *Logger
  • func (l *Logger) Level(level LogLevel) *Logger
  • func (l *Logger) Msg(key string, msg string) (int, error)
  • func (l *Logger) SetLogFile(log *os.File) error
  • func (l *Logger) Val(key string, val any) *Logger
• type ParentLoggerOverrider
  • func OverrideParentLogger() ParentLoggerOverrider
• type QueryParams
  • func Query(r *http.Request) *QueryParams
  • func (q *QueryParams) Add(key string, val string)
  • func (q *QueryParams) Del(key string)
  • func (q *QueryParams) Get(key string) string
  • func (q *QueryParams) Set(key string, val string)
  • func (q *QueryParams) Values(key string) []string
• type Router
  • func NewRouter(cgi *FullServer) *Router
  • func (wr *Router) Handle(route string, handler *Handler) *Router
  • func (wr *Router) Logger() *Logger
  • func (wr *Router) Middleware() []middleware.MiddleWare
  • func (wr *Router) Routes() []string
  • func (wr *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (wr *Router) Use(middleWare ...middleware.MiddleWare)
  • func (wr *Router) Walk(walkFunc func(method string, route string) error) error
  • func (wr *Router) WithDefaultLogger() *Router
  • func (wr *Router) WithLogger(logger *Logger) *Router
  • func (wr *Router) WithNoRouteHandler(fn http.HandlerFunc) *Router
• type WaggyEntryPoint
• type WaggyError

Variables

var AllHTTPMethods = func() string {
	return "ALL"
}

AllHTTPMethods allows you to easily set a handler all HTTP Methods

Functions

func ListenAndServe

func ListenAndServe[W WaggyEntryPoint](addr string, entryPoint W) error

ListenAndServe wraps a call to http.ListenAndServe and also uses a type constraint of WaggyEntryPoint so that only a *waggy.Router or *waggy.Handler can be used

func Serve

func Serve[W WaggyEntryPoint](entryPoint W) error

Serve wraps a call to cgi.serve and also uses a type constraint of WaggyEntryPoint so that only a *Router or *Handler can be used in the call to Serve and not accidentally allow calling a bare http.Handler

func ServeFile

func ServeFile(w http.ResponseWriter, contentType string, filePath string)

ServeFile is a convenience function for serving the file at the given filePath to the given http.ResponseWriter (w). If Waggy cannot find a file at the given path (if it doesn't exist or the volume was incorrectly mounted), this function will return a status 404. If any other error occurs, this function will return a 500. If no contentType is given, this function will set the Content-Type header to "application/octet-stream"

func Vars

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

Vars returns the values matching any path parameters if they exist, otherwise returns nil

func WriteDefaultErrorResponse

func WriteDefaultErrorResponse(w http.ResponseWriter, r *http.Request)

WriteDefaultErrorResponse returns the result of writing the set default error response inside the handler it is being used inside of. If no default error response has been set, this function will return an error.

func WriteDefaultResponse

func WriteDefaultResponse(w http.ResponseWriter, r *http.Request)

WriteDefaultResponse returns the result (number of bytes written and a nil value, or the error of that write) of writing the set default response inside the handler it is being used inside of. If no default response has been set, this function will return an error.

Types

type FullServer

type FullServer string

type Handler

type Handler struct {
	FullServer bool
	// contains filtered or unexported fields
}

Handler is used to handling various http.HandlerFuncs mapped by HTTP methods for an individual route

func NewHandler

func NewHandler(cgi *FullServer) *Handler

NewHandler initialized a new Handler and returns a pointer to it

func NewHandlerWithRoute

func NewHandlerWithRoute(route string, cgi *FullServer) *Handler

NewHandlerWithRoute initialized a new Handler with the provided route and returns a pointer to it. It is intended to be used whenever only compiling an individual *Handler instead of a full *Router

func (*Handler) Handler

func (wh *Handler) Handler(method string) http.HandlerFunc

func (*Handler) Logger

func (wh *Handler) Logger() *Logger

Logger returns the Handler's Logger. If no parent logger is inherited from a Router, or you provided a OverrideParentLogger whenever adding a Logger to the Handler, then the Handler's Logger will be returned. If no logger has been set, then this method will return nil

func (*Handler) Methods

func (wh *Handler) Methods() []string

Methods returns all HTTP methods that currently have a handler set

func (*Handler) Middleware

func (wh *Handler) Middleware() []middleware.MiddleWare

func (*Handler) RestrictMethods

func (wh *Handler) RestrictMethods(methods ...string) *Handler

RestrictMethods is a variadic function for restricting a handler from being able to be executed on the given methods

func (*Handler) Route

func (wh *Handler) Route() string

Route returns the route currently set for wh. It is a convenience function that greatly eases looping over Handlers and adding them to a Router

func (*Handler) ServeHTTP

func (wh *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves the route

func (*Handler) UpdateRoute

func (wh *Handler) UpdateRoute(route string)

UpdateRoute allows you to update the Handler's route

func (*Handler) Use

func (wh *Handler) Use(middleWare ...middleware.MiddleWare)

Use allows you to set inline Middleware http.Handlers for a specific *Handler

func (*Handler) WithDefaultErrorResponse

func (wh *Handler) WithDefaultErrorResponse(err WaggyError, statusCode int) *Handler

WithDefaultErrorResponse allows you to set a default error response for individual handlers

func (*Handler) WithDefaultLogger

func (wh *Handler) WithDefaultLogger() *Handler

WithDefaultLogger sets wh's logger to the default Logger

func (*Handler) WithDefaultResponse

func (wh *Handler) WithDefaultResponse(contentType string, body []byte) *Handler

WithDefaultResponse allows you to set a default response for individual handlers

func (*Handler) WithLogger

func (wh *Handler) WithLogger(logger *Logger, parentOverride ParentLoggerOverrider) *Handler

WithLogger allows you to set a logger for wh

func (*Handler) WithMethodHandler

func (wh *Handler) WithMethodHandler(method string, handler http.HandlerFunc) *Handler

WithMethodHandler allows you to map a different handler to each HTTP Method for a single route.

func (*Handler) WithRestrictedMethodHandler

func (wh *Handler) WithRestrictedMethodHandler(fn http.HandlerFunc) *Handler

WithRestrictedMethodHandler allows you to set an http.HandlerFunc to be used whenever a request with a restricted HTTP Method is hit. Whenever ServeHTTP is called, if this method has not been called and a restricted method has been set and is hit by the incoming request, it will return a generic 405 error, instead

type LogLevel

type LogLevel int

LogLevel allows you to set the level to be used in a *Logger

const (
	Info LogLevel = iota
	Debug
	Warning
	Fatal
	Error
	Warn
	All
	Off
)

type Logger

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

Logger is used for writing to a log

func Log

func Log(r *http.Request) *Logger

Log returns the *Logger for the current request handler to log a message to the set *os.File (defautls to os.Stderr) if one exists, otherwise nil

func NewLogger

func NewLogger(logLevel LogLevel, log *os.File) *Logger

NewLogger returns a new *Logger with the provided log file (if log is not nil) and the provided logLevel.

func (*Logger) Err

func (l *Logger) Err(err error) *Logger

Err provide an error to the *Logger to be logged

func (*Logger) Level

func (l *Logger) Level(level LogLevel) *Logger

Level update the level of a *Logger

func (*Logger) Msg

func (l *Logger) Msg(key string, msg string) (int, error)

Msg provide a message with a key to be logged and then logs the constructed log messed to the set *os.File (or default to os.Stderr)

func (*Logger) SetLogFile

func (l *Logger) SetLogFile(log *os.File) error

SetLogFile set a specific file for the logger to Write to. You must mount the volume that this file resides in whenever you configure your WAGI server via your modules.toml file for a *Logger to be able to write to the provided file

func (*Logger) Val

func (l *Logger) Val(key string, val any) *Logger

Val add a value with the corresponding key to be logged by the *Logger

type ParentLoggerOverrider

type ParentLoggerOverrider = func() bool

ParentLoggerOverrider overrides the parent *Logger in a Handler

func OverrideParentLogger

func OverrideParentLogger() ParentLoggerOverrider

OverrideParentLogger

type QueryParams

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

QueryParams contains a map containing all the query params from the provided *http.Request

func Query

func Query(r *http.Request) *QueryParams

Query returns QueryParams from the provided *http.Request

func (*QueryParams) Add

func (q *QueryParams) Add(key string, val string)

Add either appends the provided val at the provided key stored in q, or, if no value is currently stored at the provided key, then a new slice will be stored at the provided key and the provided val appended to it

func (*QueryParams) Del

func (q *QueryParams) Del(key string)

Del deletes the value(s) stored in q at the provided key

func (*QueryParams) Get

func (q *QueryParams) Get(key string) string

Get returns the first value stored in q with the provided key

func (*QueryParams) Set

func (q *QueryParams) Set(key string, val string)

Set sets the provided val in q with the provided key. If an existing value/set of values is already stored at the provided key, then Set will override that value

func (*QueryParams) Values

func (q *QueryParams) Values(key string) []string

Values returns a slice of all values stored in q with the provided key

type Router

type Router struct {
	FullServer bool
	// contains filtered or unexported fields
}

Router is used for routing incoming HTTP requests to specific *Handlers by the route provided whenever you call Handle on the return router and provide a route for the *Handler you provide

func NewRouter

func NewRouter(cgi *FullServer) *Router

NewRouter initializes a new Router and returns a pointer to it

func (*Router) Handle

func (wr *Router) Handle(route string, handler *Handler) *Router

Handle allows you to map a *Handler for a specific route. Just in the popular gorilla/mux router, you can specify path parameters by wrapping them with {} and they can later be accessed by calling Vars(r)

func (*Router) Logger

func (wr *Router) Logger() *Logger

Logger returns the Router's logger

func (*Router) Middleware

func (wr *Router) Middleware() []middleware.MiddleWare

func (*Router) Routes

func (wr *Router) Routes() []string

Routes returns all the routes that a *Router has *Handlers set for in the order that they were added

func (*Router) ServeHTTP

func (wr *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP satisfies the http.Handler interface and calls the stored handler at the route of the incoming HTTP request

func (*Router) Use

func (wr *Router) Use(middleWare ...middleware.MiddleWare)

Use allows you to set Middleware http.Handlers for a *Router

func (*Router) Walk

func (wr *Router) Walk(walkFunc func(method string, route string) error) error

Walk accepts a *Router and a walkFunc to execute on each route that has been added to the *Router. It walks the *Router in the order that each *Handler was added to the *Router with *Router.Handle(). It returns the first error encountered

func (*Router) WithDefaultLogger

func (wr *Router) WithDefaultLogger() *Router

WithDefaultLogger sets wr's logger to the default Logger

func (*Router) WithLogger

func (wr *Router) WithLogger(logger *Logger) *Router

WithLogger allows you to set a Logger for the entire router. Whenever Handle is called, this logger will be passed to the *Handler being handled for the given route.

func (*Router) WithNoRouteHandler

func (wr *Router) WithNoRouteHandler(fn http.HandlerFunc) *Router

WithNoRouteHandler allows you to set an http.HandlerFunc to be used whenever no route is found. If this method is not called and the ServeHTTP method has been called, then it will return a generic 404 response, instead

type WaggyEntryPoint

type WaggyEntryPoint interface {
	*Router | *Handler
	ServeHTTP(w http.ResponseWriter, r *http.Request)
	Middleware() []middleware.MiddleWare
}

WaggyEntryPoint is used as a type constraint whenever calling Serve so that only a *Router or *Handler can be used and not a bare http.Handler

type WaggyError

type WaggyError struct {
	Type     string `json:"type"`
	Title    string `json:"title"`
	Detail   string `json:"detail"`
	Status   int    `json:"status"`
	Instance string `json:"instance"`
	Field    string `json:"field"`
}

WaggyError is provided to help simplify composing the body of an HTTP error response