rest

package
v0.0.0-...-90deddd Latest Latest
Warning

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

 Go to latest Published: Oct 18, 2023 License: Apache-2.0 Imports: 15 Imported by: 7

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

Constants

This section is empty.

Variables

This section is empty.

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.