http

Documentation

Overview

Package http is an extra layer on to of the standard go net/http package.

This package does most of the heavy lifting for common http APIs, such as:

• Routing
• Request parsing
• Response rendering
• Graceful shutdown
• Basic security
• Logging
• Stats
• Tracing

Index

• Constants
• type Action
• type CallFunc
• type Context
  • func (c *Context) Head(code int) Renderer
  • func (c *Context) JSON(code int, data interface{}) Renderer
  • func (c *Context) Redirect(url string) Renderer
• type Handler
  • func NewHandler() *Handler
  • func (h *Handler) Append(m Middleware)
  • func (h *Handler) Drain()
  • func (h *Handler) Handle(path, method string, a Action)
  • func (h *Handler) Serve(addr string, ctx app.Ctx) error
  • func (h *Handler) Static(path, dir string)
• type Middleware
• type ParseJSON
  • func (d *ParseJSON) Parse(v interface{}) error
  • func (d *ParseJSON) Type() string
• type ParseNull
  • func (d *ParseNull) Parse(v interface{}) error
  • func (d *ParseNull) Type() string
• type Parser
  • func PickParser(ctx journey.Ctx, req *http.Request) Parser
• type RenderHead
  • func (r *RenderHead) Encode(ctx *Context) error
  • func (r *RenderHead) Status() int
• type RenderJSON
  • func (r *RenderJSON) Encode(ctx *Context) error
  • func (r *RenderJSON) Status() int
• type RenderRedirect
  • func (r *RenderRedirect) Encode(ctx *Context) error
  • func (r *RenderRedirect) Status() int
• type Renderer
• type Route

Constants

const (
	StatusContinue           = 100
	StatusSwitchingProtocols = 101

	StatusOK                   = 200
	StatusCreated              = 201
	StatusAccepted             = 202
	StatusNonAuthoritativeInfo = 203
	StatusNoContent            = 204
	StatusResetContent         = 205
	StatusPartialContent       = 206

	StatusMultipleChoices   = 300
	StatusMovedPermanently  = 301
	StatusFound             = 302
	StatusSeeOther          = 303
	StatusNotModified       = 304
	StatusUseProxy          = 305
	StatusTemporaryRedirect = 307

	StatusBadRequest                   = 400
	StatusUnauthorized                 = 401
	StatusPaymentRequired              = 402
	StatusForbidden                    = 403
	StatusNotFound                     = 404
	StatusMethodNotAllowed             = 405
	StatusNotAcceptable                = 406
	StatusProxyAuthRequired            = 407
	StatusRequestTimeout               = 408
	StatusConflict                     = 409
	StatusGone                         = 410
	StatusLengthRequired               = 411
	StatusPreconditionFailed           = 412
	StatusRequestEntityTooLarge        = 413
	StatusRequestURITooLong            = 414
	StatusUnsupportedMediaType         = 415
	StatusRequestedRangeNotSatisfiable = 416
	StatusExpectationFailed            = 417
	StatusTeapot                       = 418

	StatusInternalServerError     = 500
	StatusNotImplemented          = 501
	StatusBadGateway              = 502
	StatusServiceUnavailable      = 503
	StatusGatewayTimeout          = 504
	StatusHTTPVersionNotSupported = 505
)

HTTP status codes, defined in RFC 2616.

const (
	OPTIONS = "OPTIONS"
	GET     = "GET"
	POST    = "POST"
	PUT     = "PUT"
	DELETE  = "DELETE"
)

Types

type Action

type Action interface {
	Call(c *Context) Renderer
}

Action is an endpoint that handles incoming HTTP requests for a specific route. An action is stateless, self contained and should not share its context with other actions.

type CallFunc

type CallFunc func(c *Context) Renderer

CallFunc is the contract required to be callable on the call chain

type Context

type Context struct {
	Ctx     journey.Ctx
	Res     http.ResponseWriter
	Req     *http.Request
	Parser  Parser
	Params  map[string]string
	StartAt time.Time
	// contains filtered or unexported fields
}

Context holds the request context that is injected into an action

func (*Context) Head

func (c *Context) Head(code int) Renderer

Head returns a body-less response

func (*Context) JSON

func (c *Context) JSON(code int, data interface{}) Renderer

JSON encodes the given data to JSON

func (*Context) Redirect

func (c *Context) Redirect(url string) Renderer

Redirect returns an HTTP redirection response

type Handler

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

Handler is a lego handler for the HTTP protocol

func NewHandler

func NewHandler() *Handler

NewHandler creates a new metal handler

func (*Handler) Append

func (h *Handler) Append(m Middleware)

Append appends the given middleware to the call chain

func (*Handler) Drain

func (h *Handler) Drain()

Drain puts the handler into drain mode. All new requests will be blocked with a 503 and it will block this call until all in-flight requests have been completed

func (*Handler) Handle

func (h *Handler) Handle(path, method string, a Action)

Handle registers a new action on the given path and method

func (*Handler) Serve

func (h *Handler) Serve(addr string, ctx app.Ctx) error

Serve starts serving HTTP requests (blocking call)

func (*Handler) Static

func (h *Handler) Static(path, dir string)

Static registers a new route with path prefix to serve static files from the provided root directory.

type Middleware

type Middleware func(CallFunc) CallFunc

Middleware is a function called on the HTTP stack before an action

type ParseJSON

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

ParseJSON Parses JSON

func (*ParseJSON) Parse

func (d *ParseJSON) Parse(v interface{}) error

Parse unmarshal the request payload into the given structure

func (*ParseJSON) Type

func (d *ParseJSON) Type() string

Type returns the mime type

type ParseNull

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

ParseNull is a null-object that is used when no other Parsers have been found

func (*ParseNull) Parse

func (d *ParseNull) Parse(v interface{}) error

Parse returns an error because this Parser has nothing to Parse

func (*ParseNull) Type

func (d *ParseNull) Type() string

Type returns the mime type

type Parser

type Parser interface {
	Type() string
	Parse(v interface{}) error
}

Parser is a request data Parser

func PickParser

func PickParser(ctx journey.Ctx, req *http.Request) Parser

PickParser selects a Parser for the request content-type

type RenderHead

type RenderHead struct {
	Code int
}

RenderHead is a renderer that returns a body-less response

func (*RenderHead) Encode

func (r *RenderHead) Encode(ctx *Context) error

func (*RenderHead) Status

func (r *RenderHead) Status() int

type RenderJSON

type RenderJSON struct {
	Code int
	V    interface{}
}

RenderJSON is a renderer that marshal responses in JSON

func (*RenderJSON) Encode

func (r *RenderJSON) Encode(ctx *Context) error

func (*RenderJSON) Status

func (r *RenderJSON) Status() int

type RenderRedirect

type RenderRedirect struct {
	URL string
}

RenderRedirect is a renderer that returns a redirection

func (*RenderRedirect) Encode

func (r *RenderRedirect) Encode(ctx *Context) error

func (*RenderRedirect) Status

func (r *RenderRedirect) Status() int

type Renderer

type Renderer interface {
	// Status returns the HTTP response status code
	Status() int
	// Encode marshals the response
	Encode(*Context) error
}

Renderer is a response returned by an action

type Route

type Route struct {
	Path   string
	Method string
	Action Action
}

Route is an action attached to a given HTTP endpoint (method + path)