seatbelt

README

Seatbelt

A library for building web apps that speak HTML.

The API and documentation are still a work in progress.

Documentation

Index

• Variables
• type App
  • func New(opts ...Option) *App
  • func (a *App) Delete(path string, handle func(c Context) error)
  • func (a *App) ErrorHandler(c Context, err error)
  • func (a *App) FileServer(path string, dir string)
  • func (a *App) Get(path string, handle func(c Context) error)
  • func (a *App) Head(path string, handle func(c Context) error)
  • func (a *App) Options(path string, handle func(c Context) error)
  • func (a *App) Patch(path string, handle func(c Context) error)
  • func (a *App) Post(path string, handle func(c Context) error)
  • func (a *App) Put(path string, handle func(c Context) error)
  • func (a *App) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (a *App) SetErrorHandler(fn func(c Context, err error))
  • func (a *App) Start(addr string) error
  • func (a *App) Use(middleware ...MiddlewareFunc)
  • func (a *App) UseStd(middleware ...func(http.Handler) http.Handler)
• type Context
• type MiddlewareFunc
• type Option
• type RenderOption
• type Renderer
  • func NewRenderer(dir string, reload bool, funcs ...template.FuncMap) *Renderer
  • func (r *Renderer) HTML(w io.Writer, req *http.Request, name string, data interface{}, ...) error
  • func (r *Renderer) Text(name string, data interface{}, opts ...RenderOption) (string, error)
• type Session
• type TestContext
  • func NewTestContext(w http.ResponseWriter, r *http.Request, params ...map[string]string) *TestContext
  • func (tc *TestContext) AddRenderer(dir string, funcs template.FuncMap)
  • func (c TestContext) FormValue(name string) string
  • func (c TestContext) JSON(code int, v interface{}) error
  • func (c TestContext) NoContent() error
  • func (c TestContext) Params(v interface{}) error
  • func (c TestContext) PathParam(name string) string
  • func (c TestContext) QueryParam(name string) string
  • func (c TestContext) Redirect(url string) error
  • func (c TestContext) Render(name string, data interface{}, opts ...RenderOption) error
  • func (c TestContext) Request() *http.Request
  • func (c TestContext) Response() http.ResponseWriter
  • func (tc *TestContext) Session() Session
  • func (c TestContext) String(code int, s string) error

Variables

var ErrKeyNotFound = errors.New("value not found for key in session")

ErrKeyNotFound occurs when trying to access a value for a key that doesn't exist in the session map.

Types

type App

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

An App contains the data necessary to start and run an application.

An App acts as a router. You must provide your own HTTP server in order to start it the application, ie,

app := seatbelt.New()
http.ListenAndServe(":3000", app)

Or,

app := seatbelt.New()
srv := &http.Server{
	Handler: app,
}
srv.ListenAndServe()

func New

func New(opts ...Option) *App

New returns a new instance of a Seatbelt application.

func (*App) Delete

func (a *App) Delete(path string, handle func(c Context) error)

Delete routes DELETE requests to the given path.

func (*App) ErrorHandler

func (a *App) ErrorHandler(c Context, err error)

ErrorHandler is the globally registered error handler.

You can override this function using `SetErrorHandler`.

func (*App) FileServer

func (a *App) FileServer(path string, dir string)

FileServer serves the contents of the given directory at the given path.

func (*App) Get

func (a *App) Get(path string, handle func(c Context) error)

Get routes GET requests to the given path.

func (*App) Head

func (a *App) Head(path string, handle func(c Context) error)

Head routes HEAD requests to the given path.

func (*App) Options

func (a *App) Options(path string, handle func(c Context) error)

Options routes OPTIONS requests to the given path.

func (*App) Patch

func (a *App) Patch(path string, handle func(c Context) error)

Patch routes PATCH requests to the given path.

func (*App) Post

func (a *App) Post(path string, handle func(c Context) error)

Post routes POST requests to the given path.

func (*App) Put

func (a *App) Put(path string, handle func(c Context) error)

Put routes PUT requests to the given path.

func (*App) ServeHTTP

func (a *App) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP makes the Seatbelt application implement the http.Handler interface.

func (*App) SetErrorHandler

func (a *App) SetErrorHandler(fn func(c Context, err error))

SetErrorHandler allows you to set a custom error handler that runs when an error is returned from an HTTP handler.

func (*App) Start

func (a *App) Start(addr string) error

Start is a convenience method for starting the application server with a default *http.Server.

Start should not be used in production, as the standard library's default HTTP server is not suitable for production use due to a lack of timeouts, etc.

Production applications should create their own *http.Server, and pass the *seatbelt.App to that *http.Server's `Handler`.

func (*App) Use

func (a *App) Use(middleware ...MiddlewareFunc)

Use registers Seatbelt HTTP middleware on the application.

func (*App) UseStd

func (a *App) UseStd(middleware ...func(http.Handler) http.Handler)

UseStd registers standard HTTP middleware on the application.

type Context

type Context interface {
	// Request returns the *http.Request for the current Context.
	Request() *http.Request

	// Response returns the http.ResponseWriter for the current Context.
	Response() http.ResponseWriter

	// Session returns the session object for the current context.
	Session() Session

	// Params mass-assigns query, path, and form parameters to the given struct or
	// map.
	Params(v interface{}) error

	// FormValue returns the form value with the given name.
	FormValue(name string) string

	// PathParam returns the path parameter with the given name.
	PathParam(name string) string

	// QueryParam returns the URL query parameter with the given name.
	QueryParam(name string) string

	// String sends a string response with the given status code.
	String(code int, s string) error

	// JSON sends a JSON response with the given status code.
	JSON(code int, v interface{}) error

	// Render renders an HTML template.
	Render(name string, data interface{}, opts ...RenderOption) error

	// NoContent sends a 204 No Content HTTP response. The returned error will
	// always be nil.
	NoContent() error

	// Redirect redirects the to the given url. The returned error will always
	// be nil.
	Redirect(url string) error
}

Context contains values present during the lifetime of an HTTP request/response cycle.

type MiddlewareFunc

type MiddlewareFunc func(fn func(ctx Context) error) func(Context) error

MiddlewareFunc is the type alias for Seatbelt middleware.

type Option

type Option struct {
	TemplateDir string           // The directory where the templates reside.
	SigningKey  string           // The signing key for the cookie session store.
	Reload      bool             // Whether or not to reload templates on each request.
	Funcs       template.FuncMap // HTML functions.
}

An Option is used to configure a Seatbelt application.

type RenderOption

type RenderOption struct {
	// The Layout to use when rendering the template. The default is
	// `application`.
	Layout string

	// Status is the HTTP status code to send when rendering a template. The
	// default is 200.
	Status int
}

RenderOption contains the optional options for rendering templates.

type Renderer

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

Renderer is an instance of a template renderer.

func NewRenderer

func NewRenderer(dir string, reload bool, funcs ...template.FuncMap) *Renderer

NewRenderer returns a new instance of a renderer.

func (*Renderer) HTML

func (r *Renderer) HTML(w io.Writer, req *http.Request, name string, data interface{}, opts ...RenderOption) error

HTML writes an HTML template to a buffer.

The name of the layout does **not** require the "layouts/" prefix, unlike other templates.

func (*Renderer) Text

func (r *Renderer) Text(name string, data interface{}, opts ...RenderOption) (string, error)

Text renders the template with the given name to a string. It will render templates that end in .txt.

This should be used when rendering a template outside the context of an HTTP request, ie, rendering an email template, or a plain text template.

type Session

type Session interface {
	// Get returns the value for the given key, if one exists.
	Get(key string) interface{}

	// Put writes a key value pair to the session.
	Put(key string, value interface{})

	// Del deletes the value with the given key, if one exists.
	Del(key string)

	// Reset clears and deletes the session.
	Reset()

	// Flash sets a flash message with the given key.
	Flash(key string, value interface{})

	// GetFlash returns the flash message with the given key.
	GetFlash(key string) (interface{}, bool)

	// Flashes returns all flash messages.
	Flashes() map[string]interface{}
}

A Session is a cookie-backed browser session store.

type TestContext

type TestContext struct {
	ResponseRecorder *httptest.ResponseRecorder
	Req              *http.Request
	// contains filtered or unexported fields
}

A TestContext is used for unit testing Seatbelt handlers.

A TestContext must be created with `NewTestContext` in order to properly initialize the underlying context instance.

func NewTestContext

func NewTestContext(w http.ResponseWriter, r *http.Request, params ...map[string]string) *TestContext

NewTestContext created a new instance of a context suitable for unit testing.

func (*TestContext) AddRenderer

func (tc *TestContext) AddRenderer(dir string, funcs template.FuncMap)

AddRenderer adds an instance of a template renderer to a test context instance.

func (TestContext) FormValue

func (c TestContext) FormValue(name string) string

FormValue returns the form value with the given name.

func (TestContext) JSON

func (c TestContext) JSON(code int, v interface{}) error

JSON sends a JSON response with the given status code.

func (TestContext) NoContent

func (c TestContext) NoContent() error

NoContent sends a 204 No Content HTTP response. It will always return a nil error.

func (TestContext) Params

func (c TestContext) Params(v interface{}) error

Params mass-assigns query, path, and form parameters to the given struct or map.

v must be a pointer to a struct or a map.

The precedence is as follows:

1. Path params (highest).
2. Body params.
3. Query params.

For POST, PUT, and PATCH requests, the body will be read. For any other request, it will not.

func (TestContext) PathParam

func (c TestContext) PathParam(name string) string

PathParam returns the path param with the given name.

func (TestContext) QueryParam

func (c TestContext) QueryParam(name string) string

QueryParam returns the URL query parameter with the given name.

func (TestContext) Redirect

func (c TestContext) Redirect(url string) error

Redirect redirects the to the given url. It will never return an error.

func (TestContext) Render

func (c TestContext) Render(name string, data interface{}, opts ...RenderOption) error

Render renders an HTML template.

func (TestContext) Request

func (c TestContext) Request() *http.Request

Request returns the *http.Request for the current Context.

func (TestContext) Response

func (c TestContext) Response() http.ResponseWriter

Response returns the http.ResponseWriter for the current Context.

func (*TestContext) Session

func (tc *TestContext) Session() Session

Session returns a mock session instance, to be used for unit testing.

This overrides the underlying context's session storage.

func (TestContext) String

func (c TestContext) String(code int, s string) error

String sends a string response with the given status code.