Standard headers used by CouchDB.
const (
HeaderDestination = "Destination"
HeaderIdempotencyKey = "X-Idempotency-Key"
)
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(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(body io.ReadCloser)
CloseBody consumes the rest of the request body, then closes it, discarding any errors.
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(r *http.Response, i interface{}) error
DecodeJSON unmarshals the response body into i. This method consumes and closes the response body.
func ETag(resp *http.Response) (string, bool)
ETag returns the unquoted ETag value, and a bool indicating whether it was found.
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(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(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(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(token string) kivik.Option
JWTAuth provides JWT based auth for a client. Pass this option to New to use JWT authentication
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(value string) kivik.Option
OptionIfNoneMatch is an option key to set the `If-None-Match` header on the request.
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(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(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(resp *http.Response) error
ResponseError returns an error from an *http.Response if the status code indicates an error.
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.
Client represents a client connection. It embeds an *http.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
}
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 (c *Client) DSN() string
DSN returns the unparsed DSN used to connect.
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 (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 (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 (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.
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.
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)
}
func ContextClientTrace(ctx context.Context) *ClientTrace
ContextClientTrace returns the ClientTrace associated with the provided context. If none, it returns nil.
HTTPError is an error that represents an HTTP transport error.
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"`
}
func (e *HTTPError) Error() string
func (e *HTTPError) HTTPStatus() int
HTTPStatus returns the embedded status code.
Options are optional parameters which may be sent with a request.
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
}
func NewOptions(options driver.Options) *Options
NewOptions converts a kivik options map into
Response represents a response from a CouchDB server.
type Response struct {
*http.Response
// ContentType is the base content type, parsed from the response headers.
ContentType string
}