govalin

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 13, 2023 License: Apache-2.0 Imports: 24 Imported by: 0

README

govalin

Unit tests

A simple way of creating efficient HTTP APIs in golang using conventions over configuration.

Installation

To install govalin run:

go get -u github.com/pkkummermo/govalin

Hello World

func main() {
	govalin.New().
		Get("/test", func(call *govalin.Call) {
			call.Text("Hello world")
		}).
		Start(7070)
}

Motivation

I love how fast and efficient go is. What I don't like, is how it doesn't create an easy way of creating HTTP APIs. Govalin focuses on pleasing those who want to create APIs without too much hassle, with a lean simple API.

Inspired by simple libraries and frameworks such as Javalin, I wanted to see if we could port the simplicity to golang.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AfterFunc 

type AfterFunc func(call *Call)

type App 

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

func New 

func New(config ...ConfigFunc) *App

New creates a new Govalin App instance.

func (*App) After 

func (server *App) After(path string, afterFunc AfterFunc)

Add an after handler to given path

Add an after handler that will run after any endpoint handler which matches the same request.

func (*App) Before 

func (server *App) Before(path string, beforeFunc BeforeFunc)

Add a before handler to given path

Add a before handler that will run before any endpoint handler which matches the same request. If the before handler returns false, the request will be short circuited.

func (*App) Delete added in v0.0.6 

func (server *App) Delete(path string, handler HandlerFunc) *App

Add a DELETE handler

Add a DELETE handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Get 

func (server *App) Get(path string, handler HandlerFunc) *App

Add a GET handler

Add a GET handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Head 

func (server *App) Head(path string, handler HandlerFunc) *App

Add a HEAD handler

Add a HEAD handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Options 

func (server *App) Options(path string, handler HandlerFunc) *App

Add a OPTIONS handler

Add a OPTIONS handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Patch 

func (server *App) Patch(path string, handler HandlerFunc) *App

Add a PATCH handler

Add a PATCH handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Post 

func (server *App) Post(path string, handler HandlerFunc) *App

Add a POST handler

Add a POST handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Put 

func (server *App) Put(path string, handler HandlerFunc) *App

Add a PUT handler

Add a PUT handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Route 

func (server *App) Route(path string, scopeFunc func()) *App

Add a route to the given path

Add a route which provides a scoped route function for which you can add methods or even more routes into. This allows for hierarchical building of routes and methods.

func (*App) Shutdown 

func (server *App) Shutdown() error

Shutdown the govalin server

Start a graceful shutdown of the govalin instance.

func (*App) Start 

func (server *App) Start(port ...uint16) error

Start the server

Start the server based on given configuration.

func (*App) Static added in v0.2.1 

func (server *App) Static(path string, staticHandlerFunc StaticHandlerFunc) *App

Add a Static endpoint

Add a static endpoint which will serve static files from the given path or bundled FS.

func (*App) Ws added in v0.2.1 

func (server *App) Ws(path string, handlerFunc WsHandlerFunc) *App

Ws registers a websocket handler for the given path.

type BeforeFunc 

type BeforeFunc func(call *Call) bool

type Call 

type Call struct {
	Raw raw // Raw contains the raw request and response
	// contains filtered or unexported fields
}

Call is used to interact with the request and response object

It exposes several convenience methods for handling both path, query as well as body for the request. It follows simple conventions for getting and setting values and uses the same method for getting values from the request and setting values on the response by having optional values.

func (*Call) Authorization added in v0.1.2 

func (call *Call) Authorization() string

Authorization returns the Authorization header if available.

func (*Call) BodyAs 

func (call *Call) BodyAs(obj any) error

Get body as given struct

BodyAs takes a pointer as input and tries to deserialize the body into the object expecting the body to be JSON. Returns an error on failed unmarshalling or non-pointer.

func (*Call) Cookie added in v0.1.2 

func (call *Call) Cookie(name string, cookies ...*http.Cookie) (*http.Cookie, error)

Get or set a Cookie by name and value

Get a Cookie based on given Cookie name request or set a Cookie on the response by providing a value.

func (*Call) Error 

func (call *Call) Error(err error)

Handle an error

Write a response based on given error. If the error is recognized as a govalin error the error is handled specific according to the error.

func (*Call) File added in v0.1.0 

func (call *Call) File(key string) (*multipart.FileHeader, error)

File returns a FileHeader for given file name in the request body.

func (*Call) Files added in v0.1.0 

func (call *Call) Files(key string) ([]*multipart.FileHeader, error)

Files returns an array for the given file name in the request body.

func (*Call) FormParam 

func (call *Call) FormParam(key string) (string, error)

Get the value of given form param key

Parses the body as a www-form-urlencoded body. If the content type is not correct a warning is given and an empty string is returned.

func (*Call) FormParamOrDefault 

func (call *Call) FormParamOrDefault(key string, def string) string

Get form param value by key, if empty, use default

Get a form param value based on given key from the request, or use the given default value if the value is an empty string.

func (*Call) FormParams added in v0.1.0 

func (call *Call) FormParams() (url.Values, error)

FormParams returns all form parameters available in the request body.

func (*Call) HTML 

func (call *Call) HTML(text string)

Send text as HTML to response

HTML will set the content-type of the response as text/html and write it to the response. If no other status has been given the response, it will write a 200 OK to the response.

func (*Call) Header 

func (call *Call) Header(key string, value ...string) string

Get or set header by given key and value

Get a header value based on given header key from the request or set header value on the response by providing a value.

func (*Call) HeaderOrDefault 

func (call *Call) HeaderOrDefault(key string, def string) string

Get header value by key, if empty, use default

Get a header value based on given header key from the request, or use the given default value if the value is an empty string.

func (*Call) Host added in v0.1.2 

func (call *Call) Host() string

Host returns the host of the current request.

func (*Call) ID added in v0.1.2 

func (call *Call) ID() string

ID gives an UUIDv4 string that's unique to the call.

func (*Call) JSON 

func (call *Call) JSON(obj interface{})

Send obj as JSON to response

JSON will set the content-type of the response as application/json and serializes the given object as JSON, and writes it to the response. If no other status has been given the response, it will write a 200 OK to the response.

func (*Call) Method added in v0.1.2 

func (call *Call) Method() string

Method returns the method for the current request.

func (*Call) PathParam 

func (call *Call) PathParam(key string) string

Get path param based on key.

func (*Call) PathParams 

func (call *Call) PathParams() map[string]string

Get all path params as a map

Returns a map populated with the values based on the configuration of the path URL as a map[string]string.

func (*Call) QueryParam 

func (call *Call) QueryParam(key string) string

Get query param for given key

Returns the query param value as string.

func (*Call) QueryParamOrDefault 

func (call *Call) QueryParamOrDefault(key string, def string) string

Get query param by key, if empty, use default

Returns the query param value as string or use the given default value if the value is an empty string.

func (*Call) Redirect added in v0.2.0 

func (call *Call) Redirect(url string, permanent ...bool)

Redirect redirects the request to the given URL

Redirect will set the status code to 302 or 301 (if permenant) and set the location header to the given URL.

func (*Call) Referer added in v0.1.2 

func (call *Call) Referer() string

Referer returns the requests referer header if available. Also handles the edge case if the name of the header names spelling is correct (referrer).

func (*Call) SessionAttr added in v0.2.0 

func (call *Call) SessionAttr(key string, value ...any) (any, error)

Get or set a session attribute by key and value

Get or set a session attribute based on given key from the request. The session attribute will be stored in the session store and will be available for the next request. If no value is given, it will return the value of the session attribute. If the session attribute is not found, an error will be returned.

func (*Call) SessionAttrOrDefault added in v0.2.0 

func (call *Call) SessionAttrOrDefault(key string, def any) any

Get a session attribute by key or default value

Get a session attribute based on given key from the request. The session attribute is stored in the session store and will be available for the next request. If the session attribute is not found, the default value will be returned.

func (*Call) Status 

func (call *Call) Status(statusCode ...int) int

Set HTTP status that will be used on JSON/Text/HTML calls

If the status has already been set, a warning will be printed. The status will not be written to the response until a JSON/Text/HTML-call is made.

func (*Call) Text 

func (call *Call) Text(text string)

Send text as pure text to response

Text will set the content-type of the response as text/plain and write it to the response. If no other status has been given the response, it will write a 200 OK to the response.

func (*Call) URL added in v0.1.2 

func (call *Call) URL() *url.URL

URL returns the requested URI.

func (*Call) UserAgent added in v0.1.2 

func (call *Call) UserAgent() string

UserAgent returns the request UserAgent if available.

type Config added in v0.1.0 

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

Config contains configuration for a Govalin instance.

func (*Config) EnableAccessLog added in v0.2.1 

func (config *Config) EnableAccessLog(enabled bool) *Config

EnableAccessLog enables access logging for the server. Default is enabled.

func (*Config) EnableSessions added in v0.2.0 

func (config *Config) EnableSessions(confFunc ...SessionConfigFunc) *Config

EnableSessions configures govalin to use sessions for all requests.

func (*Config) EnableStartupLog added in v0.2.1 

func (config *Config) EnableStartupLog(enabled bool) *Config

func (*Config) Plugin added in v0.1.0 

func (config *Config) Plugin(plugin Plugin) *Config

Plugin lets you to provide a Plugin that can interact on the Govalin instance.

func (*Config) Port added in v0.1.0 

func (config *Config) Port(port uint16) *Config

Port sets the default port of the Govalin instance.

func (*Config) ServerMaxBodyReadSize added in v0.1.0 

func (config *Config) ServerMaxBodyReadSize(maxReadSize int64) *Config

ServerMaxBodyReadSize sets the max read size to accept from POST requests.

The server will error if the body size is too big and refuse to handle the request further. This is to control DDoS attacks using big body sizes.

func (*Config) ServerMaxReadTimeout added in v0.1.0 

func (config *Config) ServerMaxReadTimeout(timeout int64) *Config

ServerMaxReadTimeout sets the max read timeout for requests towards the Govalin server.

func (*Config) ServerShutdownTimeout added in v0.1.0 

func (config *Config) ServerShutdownTimeout(timeout int64) *Config

ServerShutdownTimeout sets the max timeout for before forcefully shutting the server down.

type ConfigFunc added in v0.1.0 

type ConfigFunc func(config *Config)

ConfigFunc gives a config function that will generate a Config for the Govalin object.

type HandlerFunc 

type HandlerFunc func(call *Call)

type Plugin added in v0.1.0 

type Plugin interface {
	// Name should return the name of the plugin for logging and debugging
	// purposes
	Name() string

	// OnInit supplies the configuraiton will be run before any handlers are
	// added
	OnInit(*Config)

	// Apply will provide the Plugin with the Govalin app instance so it can
	// add new routes or act upon the Govalin instance in other plugin'y ways.
	Apply(app *App)
}

Plugin is a way of interacting on a Govalin instance.

type SessionConfigFunc added in v0.2.0 

type SessionConfigFunc func(sessionConfig *SessionConfiguration)

type SessionConfiguration added in v0.2.0 

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

func (*SessionConfiguration) SessionExpireTime added in v0.2.0 

func (config *SessionConfiguration) SessionExpireTime(expireTime time.Duration) *SessionConfiguration

SessionExpireTime sets the expire time for sessions.

func (*SessionConfiguration) SessionStore added in v0.2.0 

func (config *SessionConfiguration) SessionStore(store session.Store) *SessionConfiguration

SessionStore sets the session store to use.

type StaticConfig added in v0.2.1 

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

StaticConfig contains configuration for a static handler.

func (*StaticConfig) EnableSPAMode added in v0.2.1 

func (config *StaticConfig) EnableSPAMode(spaMode bool) *StaticConfig

EnableSPAMode enables SPA mode for the static handler.

SPA mode will serve the index.html file for all requests that doesn't match a static file.

func (*StaticConfig) HostPath added in v0.2.1 

func (config *StaticConfig) HostPath(hostPath string) *StaticConfig

HostPath sets the host path for the static handler. This is trimmed from the URL before serving the static files.

func (*StaticConfig) WithFS added in v0.2.1 

func (config *StaticConfig) WithFS(fsContent fs.FS) *StaticConfig

WithFS sets the bundled FS to serve static files from.

func (*StaticConfig) WithStaticPath added in v0.2.1 

func (config *StaticConfig) WithStaticPath(staticPath string) *StaticConfig

WithStaticPath sets the path to a directory containing static files.

The directory will be served at the given path, relative to where the server is started.

type StaticHandlerFunc added in v0.2.1 

type StaticHandlerFunc func(call *Call, staticConfig *StaticConfig)

type WsConfig added in v0.2.1 

type WsConfig struct {
	// OnUpgrade is called when a websocket connection is upgraded.
	OnUpgrade WsOnUpgradeFunc
	// OnOpen is called when a websocket connection is opened.
	OnOpen WsOnOpenFunc
	// OnMessage is called when a message is received from the client.
	OnMessage WsOnMessageFunc
	// OnClose is called when a websocket connection is closed.
	OnClose WsOnCloseFunc
	// OnError is called when an error occurs.
	OnError WsOnErrorFunc
}

WsConfig contains configuration for a websocket handler.

type WsConnection added in v0.2.1 

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

WsConnection is a connection to a websocket.

func (*WsConnection) Close added in v0.2.1 

func (wsConnection *WsConnection) Close() error

Close closes the websocket connection.

func (*WsConnection) Send added in v0.2.1 

func (wsConnection *WsConnection) Send(json interface{}) error

Send sends a JSON message to the client.

func (*WsConnection) SendBytes added in v0.2.1 

func (wsConnection *WsConnection) SendBytes(bytes []byte) error

SendBytes sends a binary message to the client.

func (*WsConnection) SendText added in v0.2.1 

func (wsConnection *WsConnection) SendText(text string) error

SendText sends a text message to the client.

type WsHandlerFunc added in v0.2.1 

type WsHandlerFunc func(wsConfig *WsConfig)

type WsMessage added in v0.2.1 

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

WsMessage is a message received from a websocket.

func (*WsMessage) As added in v0.2.1 

func (message *WsMessage) As(jsonStruct interface{}) error

As unmarshals the message into the given jsonStruct.

func (*WsMessage) AsBytes added in v0.2.1 

func (message *WsMessage) AsBytes() []byte

AsBytes returns the message as a byte array.

func (*WsMessage) AsText added in v0.2.1 

func (message *WsMessage) AsText() string

AsText returns the message as a string.

func (*WsMessage) Reply added in v0.2.1 

func (message *WsMessage) Reply(json interface{}) error

Reply sends a JSON reply to the client of the message.

func (*WsMessage) ReplyBytes added in v0.2.1 

func (message *WsMessage) ReplyBytes(bytes []byte) error

ReplyBytes sends a reply to the client of the message.

func (*WsMessage) ReplyText added in v0.2.1 

func (message *WsMessage) ReplyText(text string) error

ReplyText sends a reply to the client of the message.

type WsOnCloseFunc added in v0.2.1 

type WsOnCloseFunc func(closeCode int, closeReason string)

type WsOnErrorFunc added in v0.2.1 

type WsOnErrorFunc func(err error)

type WsOnMessageFunc added in v0.2.1 

type WsOnMessageFunc func(wsMessage *WsMessage)

type WsOnOpenFunc added in v0.2.1 

type WsOnOpenFunc func(wsConnection *WsConnection)

type WsOnUpgradeFunc added in v0.2.1 

type WsOnUpgradeFunc func(call *Call) (*WsConnection, error)

Source Files

View all Source files

Directories

Path Synopsis
internal
govalintesting
http/charsets
http/contenttypes
http/headers
input
routing
session
Package session provides an interface for managing user sessions.
 Package session provides an interface for managing user sessions.
util
validation
plugins
cors
logging
routing
session/internal
session/sqlitesession

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.