rest

Documentation

Overview

Package rest provides a framework for serving and accessing hierarchical resource-based APIs. A REST server exports a node tree. The tree is explored in the manner of a filesystem: we walk a tree along a path, and, when our destination is reached, an operation is invoked on it.

This structure encourages good "proper" REST implementations--each node represents a resource, and also promotes good separation of concerns: for example, the existence of an object is checked while walking the path.

The REST client is not (yet) so fully committed to this idea; instead it provides a convenient API to access REST services.

Package rest uses the reflow errors package in order to unify error handling.

Index

• func DoFuncHandler(node DoFunc, log *log.Logger) http.Handler
• func DoProxyHandler(url string, log *log.Logger) http.Handler
• func Handler(root Node, log *log.Logger) http.Handler
• type Call
  • func (c *Call) Allow(methods ...string) bool
  • func (c *Call) Body() io.Reader
  • func (c *Call) Done() bool
  • func (c *Call) Err() error
  • func (c *Call) Error(err error)
  • func (c *Call) GetQueryParam(k string) string
  • func (c *Call) Header() http.Header
  • func (c *Call) Method() string
  • func (c *Call) Reply(code int, reply interface{})
  • func (c *Call) ReplyHeader() http.Header
  • func (c *Call) Replyf(code int, format string, args ...interface{})
  • func (c *Call) String() string
  • func (c *Call) URL() *url.URL
  • func (c *Call) Unmarshal(v interface{}) error
  • func (c *Call) UnmarshalFileset(fs *reflow.Fileset) error
  • func (c *Call) Write(code int, r io.Reader) error
• type Client
  • func NewClient(client *http.Client, u *url.URL, log *log.Logger) *Client
  • func (c *Client) Call(method, format string, args ...interface{}) *ClientCall
  • func (c *Client) URL() *url.URL
  • func (c *Client) Walk(format string, args ...interface{}) (*Client, error)
• type ClientCall
  • func (c *ClientCall) Body() io.ReadCloser
  • func (c *ClientCall) Close() error
  • func (c *ClientCall) ContentLength() int64
  • func (c *ClientCall) Do(ctx context.Context, body io.Reader) (int, error)
  • func (c *ClientCall) DoFileset(ctx context.Context, fs reflow.Fileset) (int, error)
  • func (c *ClientCall) DoJSON(ctx context.Context, req interface{}) (int, error)
  • func (c *ClientCall) Err() error
  • func (c *ClientCall) Error() *errors.Error
  • func (c *ClientCall) Message() (string, error)
  • func (c *ClientCall) Read(p []byte) (n int, err error)
  • func (c *ClientCall) SetQueryParam(k, v string)
  • func (c *ClientCall) String() string
  • func (c *ClientCall) Unmarshal(reply interface{}) error
• type DoFunc
  • func (f DoFunc) Do(ctx context.Context, call *Call)
  • func (f DoFunc) Walk(ctx context.Context, call *Call, path string) Node
• type Mux
  • func (m Mux) Do(ctx context.Context, call *Call)
  • func (m Mux) Walk(ctx context.Context, call *Call, path string) Node
• type Node
• type StreamingCall
  • func (c *StreamingCall) Write(p []byte) (n int, err error)
• type WalkFunc
  • func (f WalkFunc) Do(ctx context.Context, call *Call)
  • func (f WalkFunc) Walk(ctx context.Context, call *Call, path string) Node

Functions

func DoFuncHandler

func DoFuncHandler(node DoFunc, log *log.Logger) http.Handler

DoFuncHandler creates a http.Handler from a DoFunc. The returned handler serves requests by simply invoking the node's Do method. This handler should be registered directly on a leaf path.

func DoProxyHandler

func DoProxyHandler(url string, log *log.Logger) http.Handler

DoProxyHandler creates an http.Handler from a url. The returned handler serves requests by returning the result of a GET request to this URL.

func Handler

func Handler(root Node, log *log.Logger) http.Handler

Handler creates a http.Handler from a root node. The returned handler serves requests by walking the URL's path starting from the root node, constructing a Call, and invoking the node's Do method. It returns http.StatusNotFound if there is no node corresponding to the given path.

Types

type Call

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

Call represents an incoming call to be serviced. Calls encapsulate the complete lifecycle of a REST transaction, including error handling.

func (*Call) Allow

func (c *Call) Allow(methods ...string) bool

Allow admits a set of methods to this call. If the call's method is not among the ones passed in, Allow returns false and fails the call with a http.StatusMethodNotAllowed error.

func (*Call) Body

func (c *Call) Body() io.Reader

Body returns an io.Reader containing the request body of the call.

func (*Call) Done

func (c *Call) Done() bool

Done tells if the call is done--whether it is replied to or has failed.

func (*Call) Err

func (c *Call) Err() error

Err returns the error of this call, if any.

func (*Call) Error

func (c *Call) Error(err error)

Error sets an error for this call.

func (*Call) GetQueryParam

func (c *Call) GetQueryParam(k string) string

GetQueryParam returns the query parameter string for key k on the call request.

func (*Call) Header

func (c *Call) Header() http.Header

Header returns the HTTP headers set by the client.

func (*Call) Method

func (c *Call) Method() string

Method returns the method used in this call.

func (*Call) Reply

func (c *Call) Reply(code int, reply interface{})

Reply replies to the call with the given code and reply. The reply is marshalled using Go's JSON encoder.

func (*Call) ReplyHeader

func (c *Call) ReplyHeader() http.Header

ReplyHeader returns the HTTP headers used in the call's reply.

func (*Call) Replyf

func (c *Call) Replyf(code int, format string, args ...interface{})

Replyf formats a string and uses it to reply to the call.

func (*Call) String

func (c *Call) String() string

func (*Call) URL

func (c *Call) URL() *url.URL

URL returns the url of this call.

func (*Call) Unmarshal

func (c *Call) Unmarshal(v interface{}) error

Unmarshal unmarshal's the call's request body into v using Go's JSON decoder. If unmarshalling fails, Unmarshal returns an error and also fails the call with a http.StatusBadRequest error.

func (*Call) UnmarshalFileset

func (c *Call) UnmarshalFileset(fs *reflow.Fileset) error

func (*Call) Write

func (c *Call) Write(code int, r io.Reader) error

Write sets the call's status code and replies with the contents of the passed-in io.Reader.

type Client

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

Client is a REST client.

func NewClient

func NewClient(client *http.Client, u *url.URL, log *log.Logger) *Client

NewClient returns a new REST client given an HTTP client and root URL.

func (*Client) Call

func (c *Client) Call(method, format string, args ...interface{}) *ClientCall

Call constructs a ClientCall with the given method and path (relative to the client's root URL).

func (*Client) URL

func (c *Client) URL() *url.URL

URL returns the client's root URL.

func (*Client) Walk

func (c *Client) Walk(format string, args ...interface{}) (*Client, error)

Walk constructs a new client based on client c with a root URL based on resolving the URL's relative reference vis-a-vis the formatted string.

type ClientCall

type ClientCall struct {
	*Client
	Header http.Header
	// contains filtered or unexported fields
}

ClientCall represents a single call. It handles the entire call lifecycle. ClientCalls must be closed in order to relinquish resources. Typically, client code will invoke Close with a defer statement:

call := client.Call(...)
defer call.Close()

ClientCall is also an io.ReadCloser for the reply body.

func (*ClientCall) Body

func (c *ClientCall) Body() io.ReadCloser

Body returns the reader for the call's reply body.

func (*ClientCall) Close

func (c *ClientCall) Close() error

Close relinquishes resources associated with the call.

func (*ClientCall) ContentLength

func (c *ClientCall) ContentLength() int64

ContentLength returns the content length of the reply. Unless the request's method is HEAD, this is the number of bytes that may be read from the call.

func (*ClientCall) Do

func (c *ClientCall) Do(ctx context.Context, body io.Reader) (int, error)

Do performs a call with the given context and body. It returns the HTTP status code for the reply, or a non-nil error if one occurred.

func (*ClientCall) DoFileset

func (c *ClientCall) DoFileset(ctx context.Context, fs reflow.Fileset) (int, error)

func (*ClientCall) DoJSON

func (c *ClientCall) DoJSON(ctx context.Context, req interface{}) (int, error)

DoJSON is like Do, except the request req is marshalled using Go's JSON encoder.

func (*ClientCall) Err

func (c *ClientCall) Err() error

Err returns the call's error, if any.

func (*ClientCall) Error

func (c *ClientCall) Error() *errors.Error

Error unmarshals a reflow error from the call's reply.

func (*ClientCall) Message

func (c *ClientCall) Message() (string, error)

Message unmarshals a string message from the client.

func (*ClientCall) Read

func (c *ClientCall) Read(p []byte) (n int, err error)

Read implements io.Reader for the call's reply body.

func (*ClientCall) SetQueryParam

func (c *ClientCall) SetQueryParam(k, v string)

SetQueryParam adds or overwrites a query parameter on the call.

func (*ClientCall) String

func (c *ClientCall) String() string

func (*ClientCall) Unmarshal

func (c *ClientCall) Unmarshal(reply interface{}) error

Unmarshal unmarshals the call's reply using Go's JSON decoder.

type DoFunc

type DoFunc func(context.Context, *Call)

DoFunc is an adapter that allows the use of ordinary functions as call nodes.

func (DoFunc) Do

func (f DoFunc) Do(ctx context.Context, call *Call)

Do invokes DoFunc.

func (DoFunc) Walk

func (f DoFunc) Walk(ctx context.Context, call *Call, path string) Node

Walk returns nil.

type Mux

type Mux map[string]Node

Mux is a node multiplexer.

func (Mux) Do

func (m Mux) Do(ctx context.Context, call *Call)

Do replies to the call with http.StatusNotFound.

func (Mux) Walk

func (m Mux) Walk(ctx context.Context, call *Call, path string) Node

Walk returns the entry path in Mux.

type Node

type Node interface {
	// Walk returns the child node named path while servicing the given
	// call. Walk returns nil when no such child exist.
	Walk(ctx context.Context, call *Call, path string) Node

	// Do services a call on this node. The call must be serviced by the
	// time Do returns.
	Do(ctx context.Context, call *Call)
}

Node is a node in a REST resource tree.

type StreamingCall

type StreamingCall struct {
	*Call
}

StreamingCall implements the writer interface to write a chunk of bytes to the response writer and flush.

func (*StreamingCall) Write

func (c *StreamingCall) Write(p []byte) (n int, err error)

Write writes the data to the response writer and flushes it.

type WalkFunc

type WalkFunc func(string) Node

WalkFunc is an adapter that allows the use of ordinary functions as multiplexer nodes.

func (WalkFunc) Do

func (f WalkFunc) Do(ctx context.Context, call *Call)

Do replies to the call with http.StatusNotFound

func (WalkFunc) Walk

func (f WalkFunc) Walk(ctx context.Context, call *Call, path string) Node

Walk invokes the function WalkFunc