web

package
v4.10.1+incompatible Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2016 License: BSD-3-Clause Imports: 22 Imported by: 0

Documentation

Overview

The Tideland Go Library web package provides a framework for a component based web development, especially following the principles of REST. Internally it uses the standard http, template, json and xml packages. The business logic has to be implemented in components that fullfill the individual handler interfaces. They work on a context with some helpers but also have got access to the original Request and ResponseWriter arguments.

Index

Constants

View Source
const (
	ContentTypePlain = "text/plain"
	ContentTypeHTML  = "text/html"
	ContentTypeXML   = "application/xml"
	ContentTypeJSON  = "application/json"
	ContentTypeGOB   = "application/vnd.tideland.gob"
)
View Source
const (
	ErrDuplicateHandler = iota + 1
	ErrInitHandler
	ErrIllegalRequest
	ErrNoHandler
	ErrNoGetHandler
	ErrNoHeadHandler
	ErrNoPutHandler
	ErrNoPostHandler
	ErrNoDeleteHandler
	ErrNoOptionsHandler
	ErrMethodNotSupported
	ErrInvalidContentType
	ErrNoCachedTemplate
	ErrSceneManagement
	ErrUploadingFile
)

Variables

This section is empty.

Functions

func PackageVersion

func PackageVersion() version.Version

PackageVersion returns the version of the version package.

func SceneID

func SceneID(resp *http.Response) (string, bool)

SceneID takes a response of a HTTP request and returns a scene ID it received as cookie. It can be used to establish session when doing client calls.

Types

type Context

type Context interface {
	fmt.Stringer

	// BasePath returns the configured base path.
	BasePath() string

	// DefaultDomain returns the configured default domain.
	DefaultDomain() string

	// DefaultResource returns the configured default resource.
	DefaultResource() string

	// Request returns the used Go HTTP request.
	Request() *http.Request

	// ResponseWriter returns the used Go HTTP response writer.
	ResponseWriter() http.ResponseWriter

	// Domain returns the requests domain.
	Domain() string

	// Resource returns the requests resource.
	Resource() string

	// ResourceID return the requests resource ID.
	ResourceID() string

	// Scene returns the current scene.
	Scene() scene.Scene

	// AcceptsContentType checks if the requestor accepts a given content type.
	AcceptsContentType(contentType string) bool

	// HasContentType checks if the sent content has the given content type.
	HasContentType(contentType string) bool

	// Languages returns the accepted language with the quality values.
	Languages() Languages

	// InternalPath builds an internal path out of the passed parts.
	InternalPath(domain, resource, resourceID string, query ...KeyValue) string

	// Redirect to a domain, resource and resource ID (optional).
	Redirect(domain, resource, resourceID string)

	// RenderTemplate renders a template with the passed data to the response writer.
	RenderTemplate(templateID string, data interface{})

	// WriteGOB encodes the passed data to GOB and writes it to the response writer.
	WriteGOB(data interface{})

	// ReadGOB checks if the request content type is GOB, reads its body
	// and decodes it to the value pointed to by data.
	ReadGOB(data interface{}) error

	// WriteJSON marshals the passed data to JSON and writes it to the response writer.
	// The HTML flag controls the data encoding.
	WriteJSON(data interface{}, html bool)

	// PositiveJSONFeedback produces a positive feedback envelope
	// encoded in JSON.
	PositiveJSONFeedback(msg string, p interface{}, args ...interface{})

	// NegativeJSONFeedback produces a negative feedback envelope
	// encoded in JSON.
	NegativeJSONFeedback(msg string, args ...interface{})

	// ReadJSON checks if the request content type is JSON, reads its body
	// and unmarshals it to the value pointed to by data.
	ReadJSON(data interface{}) error

	// ReadGenericJSON works like ReadJSON but can be used if the transmitted
	// type is unknown or has no Go representation. It will a mapping according to
	// http://golang.org/pkg/json/#Unmarshal.
	ReadGenericJSON() (map[string]interface{}, error)

	// WriteXML marshals the passed data to XML and writes it to the response writer.
	WriteXML(data interface{})

	// ReadXML checks if the request content type is XML, reads its body
	// and unmarshals it to the value pointed to by data.
	ReadXML(data interface{}) error
}

Context encapsulates all the needed information for handling a request.

type DeleteResourceHandler

type DeleteResourceHandler interface {
	Delete(ctx Context) (bool, error)
}

DeleteResourceHandler is the additional interface for handlers understanding the verb DELETE.

type Envelope

type Envelope struct {
	Success bool
	Message string
	Payload interface{}
}

Envelope is a helper to give a qualified feedback in RESTful requests. It contains wether the request has been successful, in case of an error an additional message and the payload.

type FileServeHandler

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

FileServeHandler serves files identified by the resource ID part out of the configured local directory.

func NewFileServeHandler

func NewFileServeHandler(id, dir string) *FileServeHandler

NewFileServeHandler creates a new handler with a directory.

func (*FileServeHandler) Get

func (h *FileServeHandler) Get(ctx Context) (bool, error)

Get is specified on the GetResourceHandler interface.

func (*FileServeHandler) ID

func (h *FileServeHandler) ID() string

ID is specified on the ResourceHandler interface.

func (*FileServeHandler) Init

func (h *FileServeHandler) Init(mux Multiplexer, domain, resource string) error

Init is specified on the ResourceHandler interface.

type FileUploadHandler

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

FileUploadHandler handles uploading POST requests.

func NewFileUploadHandler

func NewFileUploadHandler(id string, processor FileUploadProcessor) *FileUploadHandler

NewFileUploadHandler creates a new handler for the uploading of files.

func (*FileUploadHandler) ID

func (h *FileUploadHandler) ID() string

Init is specified on the ResourceHandler interface.

func (*FileUploadHandler) Init

func (h *FileUploadHandler) Init(mux Multiplexer, domain, resource string) error

ID is specified on the ResourceHandler interface.

func (*FileUploadHandler) Post

func (h *FileUploadHandler) Post(ctx Context) (bool, error)

Post is specified on the PostResourceHandler interface.

type FileUploadProcessor

type FileUploadProcessor func(ctx Context, header *multipart.FileHeader, file multipart.File) error

FileUploadProcessor defines the function used for the processing of the uploaded file. It has to be specified by the user of the handler and e.g. persists the received data in the file system or a database.

type GetResourceHandler

type GetResourceHandler interface {
	Get(ctx Context) (bool, error)
}

GetResourceHandler is the additional interface for handlers understanding the verb GET.

type HeadResourceHandler

type HeadResourceHandler interface {
	Head(ctx Context) (bool, error)
}

HeadResourceHandler is the additional interface for handlers understanding the verb HEAD.

type KeyValue

type KeyValue struct {
	Key   string
	Value interface{}
}

KeyValue assigns a value to a key.

func (KeyValue) String

func (kv KeyValue) String() string

String prints the encoded form key=value for URLs.

type KeyValues

type KeyValues []KeyValue

KeyValues is a number of key/value pairs.

func (KeyValues) String

func (kvs KeyValues) String() string

String prints the encoded form key=value joind by & for URLs.

type Language

type Language struct {
	Locale string
	Value  float64
}

Language is the valued language a request accepts as response.

type Languages

type Languages []Language

Languages is the ordered set of accepted languages.

func (Languages) Len

func (ls Languages) Len() int

Len returns the number of languages to fulfill the sort interface.

func (Languages) Less

func (ls Languages) Less(i, j int) bool

Less returns if the language with the index i has a smaller value than the one with index j to fulfill the sort interface.

func (Languages) Swap

func (ls Languages) Swap(i, j int)

Swap swaps the languages with the indexes i and j.

type Multiplexer

type Multiplexer interface {
	http.Handler

	// ParseTemplate parses a raw template into the cache.
	ParseTemplate(templateID, template, contentType string)

	// Register adds a resource handler for a given domain and resource.
	Register(domain, resource string, handler ResourceHandler) error

	// RegisterAll allows to register multiple handler in one run.
	RegisterAll(registrations Registrations) error

	// Deregister removes a resource handler for a given domain and resource.
	Deregister(domain, resource, id string)
}

Multiplexer maps the domain and resource parts of a URL to their registered handlers. It implements the http.Handler interface.

func NewMultiplexer

func NewMultiplexer(options ...Option) (Multiplexer, error)

NewMultiplexer creates a new HTTP multiplexer.

type Option

type Option func(mux Multiplexer) error

Option defines a function setting an option for a system like the server or the multiplexer.

func BasePath

func BasePath(basePath string) Option

BasePath sets the path thats used as prefix before domain and resource.

func DefaultDomainResource

func DefaultDomainResource(defaultDomain, defaultResource string) Option

DefaultDomainResource sets the default domain and resource.

func Handlers

func Handlers(registrations Registrations) Option

Handlers allows to register multiple handlers direct at creation of the server.

func Scenes

func Scenes(sm SceneManager) Option

Scenes sets the scene manager of the multiplexer.

type OptionsResourceHandler

type OptionsResourceHandler interface {
	Options(ctx Context) (bool, error)
}

OptionsResourceHandler is the additional interface for handlers understanding the verb OPTION.

type PostResourceHandler

type PostResourceHandler interface {
	Post(ctx Context) (bool, error)
}

PostResourceHandler is the additional interface for handlers understanding the verb POST.

type PutResourceHandler

type PutResourceHandler interface {
	Put(ctx Context) (bool, error)
}

PutResourceHandler is the additional interface for handlers understanding the verb PUT.

type Registration

type Registration struct {
	Domain   string
	Resource string
	Handler  ResourceHandler
}

Registration encapsulates one handler registration.

type Registrations

type Registrations []Registration

Registrations is a number handler registratons.

type ResourceHandler

type ResourceHandler interface {
	// ID returns the deployment ID of the handler.
	ID() string

	// Init initializes the resource handler after registrations.
	Init(mux Multiplexer, domain, resource string) error
}

ResourceHandler is the base interface for all resource handlers understanding the REST verbs. It allows the initialization and returns an id that should be unique for the combination of domain and resource. So it can later be removed again.

type SceneManager

type SceneManager interface {
	// Scene returns the matching scene for the passed context.
	Scene(ctx Context) (scene.Scene, error)

	// Stop tells the scene manager to stop working.
	Stop() error
}

SceneManager can be configured to retrieve or create a scene based on formation inside the context, e.g. a scene ID as part of a request.

func NewCookieSceneManager

func NewCookieSceneManager(timeout time.Duration) SceneManager

NewCookieSceneManager creates a scene manager using the cookie "sceneID" to identify and manage the scene of a client session.

type WrapperHandler

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

WrapperHandler wraps existing handler functions for a usage inside the web package.

func NewWrapperHandler

func NewWrapperHandler(id string, hf http.HandlerFunc) *WrapperHandler

NewWrapperHandler creates a new wrapper around a handler function.

func (*WrapperHandler) Delete

func (h *WrapperHandler) Delete(ctx Context) (bool, error)

Delete is specified on the DeleteResourceHandler interface.

func (*WrapperHandler) Get

func (h *WrapperHandler) Get(ctx Context) (bool, error)

Get is specified on the GetResourceHandler interface.

func (*WrapperHandler) Head

func (h *WrapperHandler) Head(ctx Context) (bool, error)

Head is specified on the HeadResourceHandler interface.

func (*WrapperHandler) ID

func (h *WrapperHandler) ID() string

ID is specified on the ResourceHandler interface.

func (*WrapperHandler) Init

func (h *WrapperHandler) Init(mux Multiplexer, domain, resource string) error

Init is specified on the ResourceHandler interface.

func (*WrapperHandler) Options

func (h *WrapperHandler) Options(ctx Context) (bool, error)

Options is specified on the OptionsResourceHandler interface.

func (*WrapperHandler) Post

func (h *WrapperHandler) Post(ctx Context) (bool, error)

Post is specified on the PostResourceHandler interface.

func (*WrapperHandler) Put

func (h *WrapperHandler) Put(ctx Context) (bool, error)

Put is specified on the PutResourceHandler interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL