webservice

Documentation

Overview

Package webservice implements an API server that works with HTTP requests in JSON and form-request format.

Index

• Constants
• func Handler(f ContextFunc) http.HandlerFunc
• type Context
  • func (c *Context) Decode(obj interface{}) error
  • func (c *Context) EarlyResponse() error
  • func (c *Context) Empty() error
  • func (c *Context) Error(code int, err string, message interface{}) error
  • func (c *Context) File(name string) (f multipart.File, fh *multipart.FileHeader, err error)
  • func (c *Context) Param(name string) string
  • func (c *Context) Query() url.Values
  • func (c *Context) Raw() ([]byte, error)
  • func (c *Context) RealIP() string
  • func (c *Context) Respond(body interface{}) error
  • func (c *Context) ServeFile(fname, ct string) error
  • func (c *Context) StandardError(err error) error
  • func (c *Context) StartResponse()
  • func (c *Context) Text(body interface{}) error
  • func (c *Context) Writer(ct string) (WebWriter, error)
• type ContextFunc
• type EncoderFunc
• type HTTPError
  • func (he HTTPError) Error() string
• type HandlerFunc
• type JSONEncoder
  • func (JSONEncoder) ContentType() string
  • func (JSONEncoder) Encode(w io.Writer, obj interface{}) error
• type MsgpackEncoder
  • func (MsgpackEncoder) ContentType() string
  • func (MsgpackEncoder) Encode(w io.Writer, obj interface{}) error
• type ResponseEncoder
• type Router
• type Server
  • func New() *Server
  • func (s *Server) Run(bind string) error
  • func (s *Server) Shutdown(ctx context.Context) error
• type WebWriter

Constants

const DefaultMaxDecodeSize = 1 << 19 // 512kB

Functions

func Handler

func Handler(f ContextFunc) http.HandlerFunc

Handler turns an ContextFunc into a HandlerFunc.

Types

type Context

type Context struct {
	MaxDecodeSize int64
	Encoder       ResponseEncoder

	Wr   http.ResponseWriter
	Req  *http.Request
	Code int
	// contains filtered or unexported fields
}

Context contains context for JSON and form requests.

func (*Context) Decode

func (c *Context) Decode(obj interface{}) error

func (*Context) EarlyResponse

func (c *Context) EarlyResponse() error

func (*Context) Empty

func (c *Context) Empty() error

func (*Context) Error

func (c *Context) Error(code int, err string, message interface{}) error

func (*Context) File

func (c *Context) File(name string) (f multipart.File, fh *multipart.FileHeader, err error)

func (*Context) Param

func (c *Context) Param(name string) string

func (*Context) Query

func (c *Context) Query() url.Values

func (*Context) Raw

func (c *Context) Raw() ([]byte, error)

func (*Context) RealIP

func (c *Context) RealIP() string

RealIP returns the actual IP of the remote caller. It assumes the webserver is not exposed to an untrusted network directly (i.e., X-Forwarded-For cannot be spoofed.)

func (*Context) Respond

func (c *Context) Respond(body interface{}) error

func (*Context) ServeFile

func (c *Context) ServeFile(fname, ct string) error

func (*Context) StandardError

func (c *Context) StandardError(err error) error

func (*Context) StartResponse

func (c *Context) StartResponse()

func (*Context) Text

func (c *Context) Text(body interface{}) error

func (*Context) Writer

func (c *Context) Writer(ct string) (WebWriter, error)

type ContextFunc

type ContextFunc func(*Context) error

An ContextFunc handles a single request.

type EncoderFunc

type EncoderFunc func(interface{}) error

type HTTPError

type HTTPError struct {
	Code    int    `json:"code"`
	Const   string `json:"error"`
	Message string `json:"message,omitempty"`
}

HTTPError is a generic error with an associated HTTP status code.

func (HTTPError) Error

func (he HTTPError) Error() string

type HandlerFunc

type HandlerFunc = http.HandlerFunc

type JSONEncoder

type JSONEncoder struct{}

func (JSONEncoder) ContentType

func (JSONEncoder) ContentType() string

func (JSONEncoder) Encode

func (JSONEncoder) Encode(w io.Writer, obj interface{}) error

type MsgpackEncoder

type MsgpackEncoder struct{}

func (MsgpackEncoder) ContentType

func (MsgpackEncoder) ContentType() string

func (MsgpackEncoder) Encode

func (MsgpackEncoder) Encode(w io.Writer, obj interface{}) error

type ResponseEncoder

type ResponseEncoder interface {
	ContentType() string
	Encode(w io.Writer, obj interface{}) error
}

type Router

type Router = mux.Router

type Server

type Server struct {
	Router *mux.Router
	H1     *http.Server
	H2     *http2.Server
}

Server is a convenience wrapper with a router, HTTP/1 and HTTP/2 server implementation.

func New

func New() *Server

func (*Server) Run

func (s *Server) Run(bind string) error

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully terminates the server.

type WebWriter

type WebWriter interface {
	Write([]byte) (int, error)
	Flush()
}