README
¶
siesta 
Siesta is a framework for writing composable HTTP handlers in Go. It supports typed URL parameters, middleware chains, and context passing.
Getting started
Siesta offers a Service type, which is a collection of middleware chains and handlers rooted at a base URI. There is no distinction between a middleware function and a handler function; they are all considered to be handlers and have access to the same arguments.
Siesta accepts many types of handlers. Refer to the GoDoc documentation for Service.Route for more information.
Here is the simple program in the examples directory. It demonstrates the use of a Service, routing, middleware, and a Context.
package main
import (
"fmt"
"log"
"net/http"
"time"
"github.com/VividCortex/siesta"
)
func main() {
// Create a new Service rooted at "/"
service := siesta.NewService("/")
// Route accepts normal http.Handlers.
// The arguments are the method, path, description,
// and the handler.
service.Route("GET", "/", "Sends 'Hello, world!'",
func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, "Hello, world!")
})
// Let's create some simple "middleware."
// This handler will accept a Context argument and will add the current
// time to it.
timestamper := func(c siesta.Context, w http.ResponseWriter, r *http.Request) {
c.Set("start", time.Now())
}
// This is the handler that will actually send data back to the client.
// It also takes a Context argument so it can get the timestamp from the
// previous handler.
timeHandler := func(c siesta.Context, w http.ResponseWriter, r *http.Request) {
start := c.Get("start").(time.Time)
delta := time.Now().Sub(start)
fmt.Fprintf(w, "That took %v.\n", delta)
}
// We can compose these handlers together.
timeHandlers := siesta.Compose(timestamper, timeHandler)
// Finally, we'll add the new handler we created using composition to a new route.
service.Route("GET", "/time", "Sends how long it took to send a message", timeHandlers)
// service is an http.Handler, so we can pass it directly to ListenAndServe.
log.Fatal(http.ListenAndServe(":8080", service))
}
Siesta also provides utilities to manage URL parameters similar to the flag package. Refer to the params example for a demonstration.
Contributing
We only accept pull requests for minor fixes or improvements. This includes:
- Small bug fixes
- Typos
- Documentation or comments
Please open issues to discuss new features. Pull requests for new features will be rejected, so we recommend forking the repository and making changes in your fork for your use case.
License
Siesta is licensed under the MIT license. The router, which is adapted from httprouter, is licensed separately.
Documentation
¶
Index ¶
- Constants
- Variables
- func Compose(stack ...interface{}) contextHandler
- func NewSiestaContext() *siestaContext
- type Context
- type Params
- func (rp *Params) Bool(name string, value bool, usage string) *bool
- func (rp *Params) Duration(name string, value time.Duration, usage string) *time.Duration
- func (rp *Params) Float64(name string, value float64, usage string) *float64
- func (rp *Params) Int(name string, value int, usage string) *int
- func (rp *Params) Int64(name string, value int64, usage string) *int64
- func (rp *Params) Parse(args url.Values) error
- func (rp *Params) SliceBool(name string, value bool, usage string) *SBool
- func (rp *Params) SliceDuration(name string, value time.Duration, usage string) *SDuration
- func (rp *Params) SliceFloat64(name string, value float64, usage string) *SFloat64
- func (rp *Params) SliceInt(name string, value int, usage string) *SInt
- func (rp *Params) SliceInt64(name string, value int64, usage string) *SInt64
- func (rp *Params) SliceString(name string, value string, usage string) *SString
- func (rp *Params) SliceUint(name string, value uint, usage string) *SUint
- func (rp *Params) SliceUint64(name string, value uint64, usage string) *SUint64
- func (rp *Params) String(name string, value string, usage string) *string
- func (rp *Params) Uint(name string, value uint, usage string) *uint
- func (rp *Params) Uint64(name string, value uint64, usage string) *uint64
- func (rp *Params) Usage() map[string][3]string
- type SBool
- type SDuration
- type SFloat64
- type SInt
- type SInt64
- type SString
- type SUint
- type SUint64
- type Service
- func (s *Service) AddPost(f interface{})
- func (s *Service) AddPre(f interface{})
- func (s *Service) DisableTrimSlash()
- func (s *Service) Register()
- func (s *Service) Route(verb, uriPath, usage string, f interface{})
- func (s *Service) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (s *Service) ServeHTTPInContext(c Context, w http.ResponseWriter, r *http.Request)
- func (s *Service) SetNotFound(f interface{})
Constants ¶
const UsageContextKey = nullByteStr + "usage"
UsageContextKey is a special context key to get the route usage information within a handler.
Variables ¶
var ErrUnsupportedHandler = errors.New("siesta: unsupported handler")
Functions ¶
func Compose ¶
func Compose(stack ...interface{}) contextHandler
Compose composes multiple contextHandlers into a single contextHandler.
func NewSiestaContext ¶
func NewSiestaContext() *siestaContext
Types ¶
type Params ¶
type Params struct {
// contains filtered or unexported fields
}
Params represents a set of URL parameters from a request's query string. The interface is similar to a flag.FlagSet, but a) there is no usage string, b) there are no custom Var()s, and c) there are SliceXXX types. Sliced types support two ways of generating a multi-valued parameter: setting the parameter multiple times, and using a comma-delimited string. This adds the limitation that you can't have a value with a comma if in a Sliced type. Under the covers, Params uses flag.FlagSet.
func (*Params) Bool ¶
Bool defines a bool param with specified name and default value. The return value is the address of a bool variable that stores the value of the param.
func (*Params) Duration ¶
Duration defines a time.Duration param with specified name and default value. The return value is the address of a time.Duration variable that stores the value of the param.
func (*Params) Float64 ¶
Float64 defines a float64 param with specified name and default value. The return value is the address of a float64 variable that stores the value of the param.
func (*Params) Int ¶
Int defines an int param with specified name and default value. The return value is the address of an int variable that stores the value of the param.
func (*Params) Int64 ¶
Int64 defines an int64 param with specified name and default value. The return value is the address of an int64 variable that stores the value of the param.
func (*Params) Parse ¶
Parse parses URL parameters from a http.Request.URL.Query(), which is a url.Values, which is just a map[string][string].
func (*Params) SliceBool ¶
SliceBool defines a multi-value bool param with specified name and default value. The return value is the address of a SBool variable that stores the values of the param.
func (*Params) SliceDuration ¶
SliceDuration defines a multi-value time.Duration param with specified name and default value. The return value is the address of a SDuration variable that stores the values of the param.
func (*Params) SliceFloat64 ¶
SliceFloat64 defines a multi-value float64 param with specified name and default value. The return value is the address of a SFloat64 variable that stores the values of the param.
func (*Params) SliceInt ¶
SliceInt defines a multi-value int param with specified name and default value. The return value is the address of a SInt variable that stores the values of the param.
func (*Params) SliceInt64 ¶
SliceInt64 defines a multi-value int64 param with specified name and default value. The return value is the address of a SInt64 variable that stores the values of the param.
func (*Params) SliceString ¶
SliceString defines a multi-value string param with specified name and default value. The return value is the address of a SString variable that stores the values of the param.
func (*Params) SliceUint ¶
SliceUint defines a multi-value uint param with specified name and default value. The return value is the address of a SUint variable that stores the values of the param.
func (*Params) SliceUint64 ¶
SliceUint64 defines a multi-value uint64 param with specified name and default value. The return value is the address of a SUint64 variable that stores the values of the param.
func (*Params) String ¶
String defines a string param with specified name and default value. The return value is the address of a string variable that stores the value of the param.
func (*Params) Uint ¶
Uint defines a uint param with specified name and default value. The return value is the address of a uint variable that stores the value of the param.
type SBool ¶
type SBool []bool
SBool is a slice of bool.
type SDuration ¶
SDuration is a slice of time.Duration.
type SFloat64 ¶
type SFloat64 []float64
SFloat64 is a slice of float64.
type SInt ¶
type SInt []int
SInt is a slice of int.
type SInt64 ¶
type SInt64 []int64
SInt64 is a slice of int64.
type SString ¶
type SString []string
SString is a slice of string.
type SUint ¶
type SUint []uint
SUint is a slice of uint.
type SUint64 ¶
type SUint64 []uint64
SUint64 is a slice of uint64.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
A Service is a container for routes with a common base URI. It also has two middleware chains, named "pre" and "post".
The "pre" chain is run before the main handler. The first handler in the "pre" chain is guaranteed to run, but execution may quit anywhere else in the chain.
If the "pre" chain executes completely, the main handler is executed. It is skipped otherwise.
The "post" chain runs after the main handler, whether it is skipped or not. The first handler in the "post" chain is guaranteed to run, but execution may quit anywhere else in the chain if the quit function is called.
func NewService ¶
NewService returns a new Service with the given base URI or panics if the base URI has already been registered.
func (*Service) AddPost ¶
func (s *Service) AddPost(f interface{})
AddPost adds f to the end of the "post" chain. It panics if f cannot be converted to a contextHandler (see Service.Route).
func (*Service) AddPre ¶
func (s *Service) AddPre(f interface{})
AddPre adds f to the end of the "pre" chain. It panics if f cannot be converted to a contextHandler (see Service.Route).
func (*Service) DisableTrimSlash ¶
func (s *Service) DisableTrimSlash()
DisableTrimSlash disables the removal of trailing slashes before route matching.
func (*Service) Register ¶
func (s *Service) Register()
Register registers s by adding it as a handler to the DefaultServeMux in the net/http package.
func (*Service) Route ¶
Route adds a new route to the Service. f must be a function with one of the following signatures:
func(http.ResponseWriter, *http.Request) func(http.ResponseWriter, *http.Request, func()) func(Context, http.ResponseWriter, *http.Request) func(Context, http.ResponseWriter, *http.Request, func())
Note that Context is an interface type defined in this package. The last argument is a function which is called to signal the quitting of the current execution sequence.
func (*Service) ServeHTTP ¶
func (s *Service) ServeHTTP(w http.ResponseWriter, r *http.Request)
Service satisfies the http.Handler interface.
func (*Service) ServeHTTPInContext ¶
ServiceHTTPInContext serves an HTTP request within the Context c. A Service will run through both of its internal chains, quitting when requested.
func (*Service) SetNotFound ¶
func (s *Service) SetNotFound(f interface{})
SetNotFound sets the handler for all paths that do not match any existing routes. It accepts the same function signatures that Route does with the addition of `nil`.
Source Files
Directories