chttp

package
v4.3.3 Latest Latest
Warning

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

 Go to latest Published: Dec 5, 2024 License: Apache-2.0 Imports: 22 Imported by: 1

Documentation

Overview

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

Index

Constants

View Source 
const (
	HeaderDestination    = "Destination"
	HeaderIdempotencyKey = "X-Idempotency-Key"
)

Standard headers used by CouchDB.

Variables

This section is empty.

Functions

func BasicAuth 

func BasicAuth(username, password string) kivik.Option

BasicAuth provides HTTP Basic Auth for a client. Pass this option to New to use Basic Authentication.

func BodyEncoder 

func BodyEncoder(i interface{}) func() (io.ReadCloser, error)

BodyEncoder returns a function which returns the encoded body. It is meant to be used as a http.Request.GetBody value.

func CloseBody 

func CloseBody(body io.ReadCloser)

CloseBody consumes the rest of the request body, then closes it, discarding any errors.

func CookieAuth 

func CookieAuth(username, password string) kivik.Option

CookieAuth provides CouchDB Cookie auth. Cookie Auth is the default authentication method if credentials are included in the connection URL passed to New. You may also pass this option as an argument to the same function, if you need to provide your auth credentials outside of the URL.

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 ETag 

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

ETag returns the unquoted ETag value, and a bool indicating whether it was found.

func EncodeBody 

func EncodeBody(i interface{}) io.ReadCloser

EncodeBody JSON encodes i to an io.ReadCloser. If an encoding error occurs, it will be returned on the next read.

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, except that spaces are converted to %20. See https://github.com/apache/couchdb/issues/3565 for an explanation.

func ExtractRev 

func ExtractRev(rc io.ReadCloser) (io.ReadCloser, string, error)

ExtractRev extracts the _rev field from r, while reading into a buffer, then returns a re-assembled ReadCloser, containing the buffer plus any unread bytes still on the network, along with the document revision.

When the ETag header is missing, which can happen, for example, when doing a request with revs_info=true. This means we need to look through the body of the request for the revision. Fortunately, CouchDB tends to send the _id and _rev fields first, so we shouldn't need to parse the entire body. The important thing is that resp.Body must be restored, so that the normal document scanning can take place as usual.

func GetRev 

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

GetRev extracts the revision from the response's Etag header, if found. If not, it falls back to reading the revision from the _rev field of the document itself, then restores resp.Body for re-reading.

func JWTAuth 

func JWTAuth(token string) kivik.Option

JWTAuth provides JWT based auth for a client. Pass this option to New to use JWT authentication

func OptionFullCommit 

func OptionFullCommit() kivik.Option

OptionFullCommit is the option key used to set the `X-Couch-Full-Commit` header in the request when set to true.

func OptionIfNoneMatch 

func OptionIfNoneMatch(value string) kivik.Option

OptionIfNoneMatch is an option key to set the `If-None-Match` header on the request.

func OptionNoRequestCompression 

func OptionNoRequestCompression() kivik.Option

OptionNoRequestCompression instructs the CouchDB client not to use gzip compression for request bodies sent to the server. Only honored when passed to github.com/go-kivik/kivik/v4.New or New.

func OptionUserAgent 

func OptionUserAgent(ua string) kivik.Option

OptionUserAgent may be passed as an option when creating a client object, to append to the default User-Agent header sent on all requests.

func ProxyAuth 

func ProxyAuth(username, secret string, roles []string, headers ...map[string]string) kivik.Option

ProxyAuth provides support for CouchDB's [proxy authentication]. Pass this option to New to use proxy authentication.

func ResponseError 

func ResponseError(resp *http.Response) error

ResponseError returns an error from an *http.Response if the status code indicates an error.

func WithClientTrace 

func WithClientTrace(ctx context.Context, trace *ClientTrace) context.Context

WithClientTrace returns a new context based on the provided parent ctx. HTTP client requests made with the returned context will use the provided trace hooks, in addition to any previous hooks registered with ctx. Any hooks defined in the provided trace will be called first.

Types

type Client 

type Client struct {
	// UserAgents is appended to set the User-Agent header. Typically it should
	// contain pairs of product name and version.
	UserAgents []string

	*http.Client
	// contains filtered or unexported fields
}

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

func New 

func New(client *http.Client, dsn string, options driver.Options) (*Client, error)

New returns a connection to a remote CouchDB server. If credentials are included in the URL, requests will be authenticated using Cookie Auth. To use HTTP BasicAuth or some other authentication mechanism, do not specify credentials in the URL, and instead call the [Client.Auth] method later.

options must not be nil.

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{}) error

DoJSON combines Client.DoReq, [Client.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) NewRequest 

func (c *Client) NewRequest(ctx context.Context, method, path string, body io.Reader, opts *Options) (*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 ClientTrace 

type ClientTrace struct {
	// HTTPResponse returns a cloe of the *http.Response received from the
	// server, with the body set to nil. If you need the body, use the more
	// expensive HTTPResponseBody.
	HTTPResponse func(*http.Response)

	// HTTPResponseBody returns a clone of the *http.Response received from the
	// server, with the body cloned. This can be expensive for responses
	// with large bodies.
	HTTPResponseBody func(*http.Response)

	// HTTPRequest returns a clone of the *http.Request sent to the server, with
	// the body set to nil. If you need the body, use the more expensive
	// HTTPRequestBody.
	HTTPRequest func(*http.Request)

	// HTTPRequestBody returns a clone of the *http.Request sent to the server,
	// with the body cloned, if it is set. This can be expensive for requests
	// with large bodies.
	HTTPRequestBody func(*http.Request)
}

ClientTrace is a set of hooks to run at various stages of an outgoing HTTP request. Any particular hook may be nil. Functions may be called concurrently from different goroutines and some may be called after the request has completed or failed.

func ContextClientTrace 

func ContextClientTrace(ctx context.Context) *ClientTrace

ContextClientTrace returns the ClientTrace associated with the provided context. If none, it returns nil.

type HTTPError 

type HTTPError struct {
	// Response is the HTTP response received by the client.  The response body
	// should already be closed, but the response and request headers and other
	// metadata will typically be in tact for debugging purposes.
	Response *http.Response `json:"-"`

	// Reason is the server-supplied error reason.
	Reason string `json:"reason"`
}

HTTPError is an error that represents an HTTP transport error.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

func (*HTTPError) HTTPStatus 

func (e *HTTPError) HTTPStatus() int

HTTPStatus 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

	// ContentLength, if set, sets the ContentLength of the request
	ContentLength int64

	// Body sets the body of the request.
	Body io.ReadCloser

	// GetBody is a function to set the body, and can be used on retries. If
	// set, Body is ignored.
	GetBody func() (io.ReadCloser, error)

	// 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{}

	// FullCommit adds the X-Couch-Full-Commit: true header to requests
	FullCommit bool

	// IfNoneMatch adds the If-None-Match header. The value will be quoted if
	// it is not already.
	IfNoneMatch string

	// Query is appended to the exiting url, if present. If the passed url
	// already contains query parameters, the values in Query are appended.
	// No merging takes place.
	Query url.Values

	// Header is a list of default headers to be set on the request.
	Header http.Header

	// NoGzip disables gzip compression on the request body.
	NoGzip bool
}

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

func NewOptions 

func NewOptions(options driver.Options) *Options

NewOptions converts a kivik options map into

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.

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.