chttp

Documentation

Overview

Package chttp provides a minimal HTTP driver backend for communicating with CouchDB servers.

Index

• func DecodeJSON(r *http.Response, i interface{}) error
• func EncodeBody(i interface{}, cancel context.CancelFunc) (r io.Reader, errFunc func() error)
• func EncodeDocID(docID string) string
• func GetRev(resp *http.Response) (rev string, err error)
• func ResponseError(resp *http.Response) error
• func ValidateAuth(ctx context.Context, username string, client *Client) error
• type Authenticator
• type BasicAuth
  • func (a *BasicAuth) Authenticate(ctx context.Context, c *Client) error
  • func (a *BasicAuth) Logout(_ context.Context, c *Client) error
  • func (a *BasicAuth) RoundTrip(req *http.Request) (*http.Response, error)
• type Client
  • func New(ctx context.Context, dsn string) (*Client, error)
  • func (c *Client) Auth(ctx context.Context, a Authenticator) error
  • func (c *Client) DSN() string
  • func (c *Client) DoError(ctx context.Context, method, path string, opts *Options) (*http.Response, error)
  • func (c *Client) DoJSON(ctx context.Context, method, path string, opts *Options, i interface{}) (*http.Response, error)
  • func (c *Client) DoReq(ctx context.Context, method, path string, opts *Options) (*http.Response, error)
  • func (c *Client) Logout(ctx context.Context) error
  • func (c *Client) NewRequest(ctx context.Context, method, path string, body io.Reader) (*http.Request, error)
• type CookieAuth
  • func (a *CookieAuth) Authenticate(ctx context.Context, c *Client) error
  • func (a *CookieAuth) Logout(ctx context.Context, c *Client) error
• type HTTPError
  • func (e *HTTPError) Error() string
  • func (e *HTTPError) StatusCode() int
• type Options
• type Response

Functions

func DecodeJSON

func DecodeJSON(r *http.Response, i interface{}) error

DecodeJSON unmarshals the response body into i. This method consumes and closes the response body.

func EncodeBody

func EncodeBody(i interface{}, cancel context.CancelFunc) (r io.Reader, errFunc func() error)

EncodeBody JSON encodes i to r. A call to errFunc will block until encoding has completed, then return the errur status of the encoding job. If an encoding error occurs, cancel() called.

func EncodeDocID

func EncodeDocID(docID string) string

EncodeDocID encodes a document ID according to CouchDB's path encoding rules.

In particular:

• '_design/' and '_local/' prefixes are unaltered.
• The rest of the docID is Query-URL encoded (despite being part of the path)

func GetRev

func GetRev(resp *http.Response) (rev string, err error)

GetRev extracts the revision from the response's Etag header

func ResponseError

func ResponseError(resp *http.Response) error

ResponseError returns an error from an *http.Response.

func ValidateAuth

func ValidateAuth(ctx context.Context, username string, client *Client) error

ValidateAuth validates that the requested username is authenticated.

Types

type Authenticator

type Authenticator interface {
	Authenticate(context.Context, *Client) error
	Logout(context.Context, *Client) error
}

Authenticator is an interface that provides authentication to a server.

type BasicAuth

type BasicAuth struct {
	Username string
	Password string
	// contains filtered or unexported fields
}

BasicAuth provides HTTP Basic Auth for a client.

func (*BasicAuth) Authenticate

func (a *BasicAuth) Authenticate(ctx context.Context, c *Client) error

Authenticate sets HTTP Basic Auth headers for the client.

func (*BasicAuth) Logout

func (a *BasicAuth) Logout(_ context.Context, c *Client) error

Logout unsets BasicAuthentication

func (*BasicAuth) RoundTrip

func (a *BasicAuth) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip fulfills the http.RoundTripper interface. It sets HTTP Basic Auth on outbound requests.

type Client

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

Client represents a client connection. It embeds an *http.Client

func New

func New(ctx context.Context, dsn string) (*Client, error)

New returns a connection to a remote CouchDB server. If credentials are included in the URL, CookieAuth is attempted first, with BasicAuth used as a fallback. If both fail, an error is returned. If you wish to use some other authentication mechanism, do not specify credentials in the URL, and instead call the Auth() method later.

func (*Client) Auth

func (c *Client) Auth(ctx context.Context, a Authenticator) error

Auth authenticates using the provided Authenticator.

func (*Client) DSN

func (c *Client) DSN() string

DSN returns the unparsed DSN used to connect.

func (*Client) DoError

func (c *Client) DoError(ctx context.Context, method, path string, opts *Options) (*http.Response, error)

DoError is the same as DoReq(), followed by checking the response error. This method is meant for cases where the only information you need from the response is the status code. It unconditionally closes the response body.

func (*Client) DoJSON

func (c *Client) DoJSON(ctx context.Context, method, path string, opts *Options, i interface{}) (*http.Response, error)

DoJSON combines DoReq() and, ResponseError(), and (*Response).DecodeJSON(), and closes the response body.

func (*Client) DoReq

func (c *Client) DoReq(ctx context.Context, method, path string, opts *Options) (*http.Response, error)

DoReq does an HTTP request. An error is returned only if there was an error processing the request. In particular, an error status code, such as 400 or 500, does _not_ cause an error to be returned.

func (*Client) Logout

func (c *Client) Logout(ctx context.Context) error

Logout logs out after authentication.

func (*Client) NewRequest

func (c *Client) NewRequest(ctx context.Context, method, path string, body io.Reader) (*http.Request, error)

NewRequest returns a new *http.Request to the CouchDB server, and the specified path. The host, schema, etc, of the specified path are ignored.

type CookieAuth

type CookieAuth struct {
	Username string `json:"name"`
	Password string `json:"password"`
	// contains filtered or unexported fields
}

CookieAuth provides CouchDB Cookie auth services as described at http://docs.couchdb.org/en/2.0.0/api/server/authn.html#cookie-authentication

func (*CookieAuth) Authenticate

func (a *CookieAuth) Authenticate(ctx context.Context, c *Client) error

Authenticate initiates a session with the CouchDB server.

func (*CookieAuth) Logout

func (a *CookieAuth) Logout(ctx context.Context, c *Client) error

Logout deletes the remote session.

type HTTPError

type HTTPError struct {
	Code   int
	Reason string `json:"reason"`
}

HTTPError is an error that represents an HTTP transport error.

func (*HTTPError) Error

func (e *HTTPError) Error() string

func (*HTTPError) StatusCode

func (e *HTTPError) StatusCode() int

StatusCode returns the embedded status code.

type Options

type Options struct {
	// Accept sets the request's Accept header. Defaults to "application/json".
	// To specify any, use "*/*".
	Accept string
	// ContentType sets the requests's Content-Type header. Defaults to "application/json".
	ContentType string
	// Body sets the body of the request.
	Body io.Reader
	// JSON is an arbitrary data type which is marshaled to the request's body.
	// It an error to set both Body and JSON on the same request. When this is
	// set, ContentType is unconditionally set to 'application/json'. Note that
	// for large JSON payloads, it can be beneficial to do your own JSON stream
	// encoding, so that the request can be live on the wire during JSON
	// encoding.
	JSON interface{}
	// ForceCommit adds the X-Couch-Full-Commit: true header to requests
	ForceCommit bool
	// Destination is the target ID for COPY
	Destination string
}

Options are optional parameters which may be sent with a request.

type Response

type Response struct {
	*http.Response

	// ContentType is the base content type, parsed from the response headers.
	ContentType string
}

Response represents a response from a CouchDB server.