apiserver

Documentation

Overview

Package apiserver contains the code that provides a RESTful api service

Index

• func Handle(storage map[string]RESTStorage, codec Codec, prefix string) http.Handler
• func InstallSupport(mux mux)
• func IsAlreadyExists(err error) bool
• func IsConflict(err error) bool
• func IsInvalid(err error) bool
• func IsNotFound(err error) bool
• func MakeAsync(fn WorkFunc) <-chan interface{}
• func NewAlreadyExistsErr(kind, name string) error
• func NewConflictErr(kind, name string, err error) error
• func NewInvalidErr(kind, name string, errs errors.ErrorList) error
• func NewNotFoundErr(kind, name string) error
• func RecoverPanics(handler http.Handler) http.Handler
• type APIGroup
  • func NewAPIGroup(storage map[string]RESTStorage, codec Codec) *APIGroup
  • func (g *APIGroup) InstallREST(mux mux, paths ...string)
• type Codec
• type Operation
  • func (op *Operation) StatusOrResult() (description interface{}, finished bool)
  • func (op *Operation) WaitFor(timeout time.Duration)
• type OperationHandler
  • func (h *OperationHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type Operations
  • func NewOperations() *Operations
  • func (ops *Operations) Get(id string) *Operation
  • func (ops *Operations) List() api.ServerOpList
  • func (ops *Operations) NewOperation(from <-chan interface{}) *Operation
• type RESTHandler
  • func (h *RESTHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type RESTStorage
• type RedirectHandler
  • func (r *RedirectHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type Redirector
• type ResourceWatcher
• type WatchHandler
  • func (h *WatchHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type WatchServer
  • func (w *WatchServer) HandleWS(ws *websocket.Conn)
  • func (self *WatchServer) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type WorkFunc

Functions

func Handle

func Handle(storage map[string]RESTStorage, codec Codec, prefix string) http.Handler

Handle returns a Handler function that expose the provided storage interfaces as RESTful resources at prefix, serialized by codec, and also includes the support http resources.

func InstallSupport

func InstallSupport(mux mux)

InstallSupport registers the APIServer support functions into a mux.

func IsAlreadyExists

func IsAlreadyExists(err error) bool

IsAlreadyExists determines if the err is an error which indicates that a specified resource already exists.

func IsConflict

func IsConflict(err error) bool

IsConflict determines if the err is an error which indicates the provided update conflicts

func IsInvalid

func IsInvalid(err error) bool

IsInvalid determines if the err is an error which indicates the provided resource is not valid

func IsNotFound

func IsNotFound(err error) bool

IsNotFound returns true if the specified error was created by NewNotFoundErr

func MakeAsync

func MakeAsync(fn WorkFunc) <-chan interface{}

MakeAsync takes a function and executes it, delivering the result in the way required by RESTStorage's Update, Delete, and Create methods.

func NewAlreadyExistsErr

func NewAlreadyExistsErr(kind, name string) error

NewAlreadyExistsErr returns an error indicating the item requested exists by that identifier

func NewConflictErr

func NewConflictErr(kind, name string, err error) error

NewConflictErr returns an error indicating the item can't be updated as provided.

func NewInvalidErr

func NewInvalidErr(kind, name string, errs errors.ErrorList) error

NewInvalidError returns an error indicating the item is invalid and cannot be processed.

func NewNotFoundErr

func NewNotFoundErr(kind, name string) error

NewNotFoundErr returns a new error which indicates that the resource of the kind and the name was not found.

func RecoverPanics

func RecoverPanics(handler http.Handler) http.Handler

RecoverPanics wraps an http Handler to recover and log panics

Types

type APIGroup

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

APIGroup is a http.Handler that exposes multiple RESTStorage objects It handles URLs of the form: /${storage_key}[/${object_name}] Where 'storage_key' points to a RESTStorage object stored in storage.

TODO: consider migrating this to go-restful which is a more full-featured version of the same thing.

func NewAPIGroup

func NewAPIGroup(storage map[string]RESTStorage, codec Codec) *APIGroup

NewAPIGroup returns an object that will serve a set of REST resources and their associated operations. The provided codec controls serialization and deserialization. This is a helper method for registering multiple sets of REST handlers under different prefixes onto a server. TODO: add multitype codec serialization

func (*APIGroup) InstallREST

func (g *APIGroup) InstallREST(mux mux, paths ...string)

InstallREST registers the REST handlers (storage, watch, and operations) into a mux. It is expected that the provided prefix will serve all operations. Path MUST NOT end in a slash.

type Codec

type Codec interface {
	Encode(obj interface{}) (data []byte, err error)
	Decode(data []byte) (interface{}, error)
	DecodeInto(data []byte, obj interface{}) error
}

Codec defines methods for serializing and deserializing API objects.

type Operation

type Operation struct {
	ID string
	// contains filtered or unexported fields
}

Operation represents an ongoing action which the server is performing.

func (*Operation) StatusOrResult

func (op *Operation) StatusOrResult() (description interface{}, finished bool)

StatusOrResult returns status information or the result of the operation if it is complete, with a bool indicating true in the latter case.

func (*Operation) WaitFor

func (op *Operation) WaitFor(timeout time.Duration)

WaitFor waits for the specified duration, or until the operation finishes, whichever happens first.

type OperationHandler

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

func (*OperationHandler) ServeHTTP

func (h *OperationHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)

type Operations

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

Operations tracks all the ongoing operations.

func NewOperations

func NewOperations() *Operations

NewOperations returns a new Operations repository.

func (*Operations) Get

func (ops *Operations) Get(id string) *Operation

Get returns the operation with the given ID, or nil

func (*Operations) List

func (ops *Operations) List() api.ServerOpList

List operations for an API client.

func (*Operations) NewOperation

func (ops *Operations) NewOperation(from <-chan interface{}) *Operation

NewOperation adds a new operation. It is lock-free.

type RESTHandler

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

func (*RESTHandler) ServeHTTP

func (h *RESTHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP handles requests to all RESTStorage objects.

type RESTStorage

type RESTStorage interface {
	// New returns an empty object that can be used with Create and Update after request data has been put into it.
	// This object must be a pointer type for use with Codec.DecodeInto([]byte, interface{})
	New() interface{}

	// List selects resources in the storage which match to the selector.
	// TODO: add field selector in addition to label selector.
	List(labels.Selector) (interface{}, error)

	// Get finds a resource in the storage by id and returns it.
	// Although it can return an arbitrary error value, IsNotFound(err) is true for the
	// returned error value err when the specified resource is not found.
	Get(id string) (interface{}, error)

	// Delete finds a resource in the storage and deletes it.
	// Although it can return an arbitrary error value, IsNotFound(err) is true for the
	// returned error value err when the specified resource is not found.
	Delete(id string) (<-chan interface{}, error)

	Create(interface{}) (<-chan interface{}, error)
	Update(interface{}) (<-chan interface{}, error)
}

RESTStorage is a generic interface for RESTful storage services Resources which are exported to the RESTful API of apiserver need to implement this interface.

type RedirectHandler

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

func (*RedirectHandler) ServeHTTP

func (r *RedirectHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)

type Redirector

type Redirector interface {
	// ResourceLocation should return the remote location of the given resource, or an error.
	ResourceLocation(id string) (remoteLocation string, err error)
}

Redirectors know how to return a remote resource's location.

type ResourceWatcher

type ResourceWatcher interface {
	// 'label' selects on labels; 'field' selects on the object's fields. Not all fields
	// are supported; an error should be returned if 'field' tries to select on a field that
	// isn't supported. 'resourceVersion' allows for continuing/starting a watch at a
	// particular version.
	Watch(label, field labels.Selector, resourceVersion uint64) (watch.Interface, error)
}

ResourceWatcher should be implemented by all RESTStorage objects that want to offer the ability to watch for changes through the watch api.

type WatchHandler

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

func (*WatchHandler) ServeHTTP

func (h *WatchHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)

handleWatch processes a watch request

type WatchServer

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

WatchServer serves a watch.Interface over a websocket or vanilla HTTP.

func (*WatchServer) HandleWS

func (w *WatchServer) HandleWS(ws *websocket.Conn)

HandleWS implements a websocket handler.

func (*WatchServer) ServeHTTP

func (self *WatchServer) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP serves a series of JSON encoded events via straight HTTP with Transfer-Encoding: chunked.

type WorkFunc

type WorkFunc func() (result interface{}, err error)

WorkFunc is used to perform any time consuming work for an api call, after the input has been validated. Pass one of these to MakeAsync to create an appropriate return value for the Update, Delete, and Create methods.