Documentation ¶
Index ¶
- Constants
- Variables
- func IsEndpointNotFound(err error) bool
- func IsServiceNotAvailable(err error) bool
- func NewTestHandler(t *testing.T, status int, body []byte) http.HandlerFunc
- func NewTestHandlerWithEOF(t *testing.T) http.HandlerFunc
- func NewTestHandlerWithHijack(t *testing.T) http.HandlerFunc
- func NewTestHandlerWithRetries(t *testing.T, numRetries, retryStatus, successStatus int, after string, ...) http.HandlerFunc
- func NewTestHandlerWithStream(t *testing.T, responses int, body []byte) http.HandlerFunc
- func NewTestHandlerWithStreamHijack(t *testing.T) http.HandlerFunc
- func NewTestHandlerWithValue(t *testing.T, status int, body []byte, value any) http.HandlerFunc
- type AlternateAddresses
- type AuthProvider
- func (a *AuthProvider) GetAllServiceHosts(service Service) ([]string, error)
- func (a *AuthProvider) GetCredentials(host string) (string, string)
- func (a *AuthProvider) GetServiceHost(service Service, offset int) (string, error)
- func (a *AuthProvider) GetUserAgent() string
- func (a *AuthProvider) SetClusterConfig(host string, config *ClusterConfig) error
- func (a *AuthProvider) UpdateResolvedAddress()
- type AuthProviderOptions
- type AuthenticationError
- type AuthorizationError
- type BootstrapFailureError
- type Client
- func (c *Client) AltAddr() bool
- func (c *Client) Close()
- func (c *Client) ClusterUUID() string
- func (c *Client) DeveloperPreview() bool
- func (c *Client) Do(ctx context.Context, request *Request) (*http.Response, error)
- func (c *Client) EnterpriseCluster() bool
- func (c *Client) Execute(request *Request) (*Response, error)
- func (c *Client) ExecuteStream(request *Request) (<-chan StreamingResponse, error)
- func (c *Client) ExecuteStreamWithContext(ctx context.Context, request *Request) (<-chan StreamingResponse, error)
- func (c *Client) ExecuteWithContext(ctx context.Context, request *Request) (*Response, error)
- func (c *Client) GetAllServiceHosts(service Service) ([]string, error)
- func (c *Client) GetServiceHost(service Service) (string, error)
- func (c *Client) Nodes() Nodes
- func (c *Client) Poll(poll func(attempt int) (bool, error)) (bool, error)
- func (c *Client) PollTimeout() time.Duration
- func (c *Client) PollWithContext(ctx context.Context, poll func(attempt int) (bool, error)) (bool, error)
- func (c *Client) RequestRetries() int
- func (c *Client) TLS() bool
- type ClientOptions
- type ClusterConfig
- type ClusterConfigManager
- type ConnectionMode
- type ContentType
- type Endpoint
- type EndpointNotFoundError
- type External
- type Header
- type InternalServerError
- type Method
- type Node
- type Nodes
- type OldClusterConfigError
- type PollFunc
- type Request
- type Response
- type RetriesExhaustedError
- type Service
- type ServiceNotAvailableError
- type Services
- type SocketClosedInFlightError
- type StreamingResponse
- type TestBucket
- type TestBuckets
- type TestCluster
- func (t *TestCluster) Address() string
- func (t *TestCluster) Bucket(name string) func(writer http.ResponseWriter, request *http.Request)
- func (t *TestCluster) BucketManifest(name string) func(writer http.ResponseWriter, request *http.Request)
- func (t *TestCluster) Buckets(writer http.ResponseWriter, _ *http.Request)
- func (t *TestCluster) Certificate() *x509.Certificate
- func (t *TestCluster) Close()
- func (t *TestCluster) Handler(writer http.ResponseWriter, request *http.Request)
- func (t *TestCluster) Hostname() string
- func (t *TestCluster) NodeServices(writer http.ResponseWriter, _ *http.Request)
- func (t *TestCluster) Nodes() Nodes
- func (t *TestCluster) Pools(writer http.ResponseWriter, _ *http.Request)
- func (t *TestCluster) PoolsDefault(writer http.ResponseWriter, _ *http.Request)
- func (t *TestCluster) Port() uint16
- func (t *TestCluster) URL() string
- type TestClusterOptions
- type TestHandlers
- type TestNode
- type TestNodes
- type UnexpectedEndOfBodyError
- type UnexpectedStatusCodeError
- type UnknownAuthorityError
- type UnknownX509Error
Constants ¶
const ( // DefaultClientTimeout is the timeout for client connection/single operations i.e. this doesn't include retries. DefaultClientTimeout = time.Minute // DefaultRequestTimeout is the default timeout for REST requests, note that this includes retries. DefaultRequestTimeout = time.Minute // DefaultDialerTimeout is the default net.Dialer Timeout value for transport of the HTTP client. DefaultDialerTimeout = 30 * time.Second // DefaultDialerKeepAlive is the default net.Dialer KeepAlive value for transport of the HTTP client. DefaultDialerKeepAlive = 30 * time.Second // DefaultTransportIdleConnTimeout is the default IdleConnTimeout value for transport of the HTTP client. DefaultTransportIdleConnTimeout = 90 * time.Second // DefaultTransportContinueTimeout is the default ContinueTimeout value for transport of the HTTP client. DefaultTransportContinueTimeout = 0 * time.Second // DefaultResponseHeaderTimeout is the default ResponseHeaderTimeout value for transport of the HTTP client. DefaultResponseHeaderTimeout = 0 * time.Second // DefaultTLSHandshakeTimeout is the default TLSHandshakeTimeout value for transport of the HTTP client. DefaultTLSHandshakeTimeout = 10 * time.Second // DefaultRequestRetries is the number of times to attempt a REST request for known failure scenarios. When sending // a new request the overall request timeout is not reset, however, the connection/client level timeout is. DefaultRequestRetries = 3 // DefaultPollTimeout is the default timeout for polling operations e.g. waiting for a bucket to report as // 'healthy'. DefaultPollTimeout = 5 * time.Minute // TimeoutsEnvVar is the environment variable that should be used to supply configurable timeouts for a REST HTTP // client. If it is not provided then the default values are used. TimeoutsEnvVar = "CB_REST_HTTP_TIMEOUTS" )
const DefaultCCMaxAge = 15 * time.Second
DefaultCCMaxAge is the maximum amount of time a cluster config will be in use before the client begins to try to update the cluster config. This is around the same time used by the SDKS +/- 5 seconds.
Variables ¶
var ( // ErrNodeUninitialized is returned if the user attempts to interact with a node which has not been initialized. ErrNodeUninitialized = errors.New("attempted to connect to an uninitialized node") // ErrNotBootstrapped is returned when attempting to retrieve hosts from an auth provider which has not been // bootstrapped; this error shouldn't be returned when using the 'Client' since the constructor performs // bootstrapping. ErrNotBootstrapped = errors.New("auth provider not bootstrapped") // ErrExhaustedClusterNodes is returned if we've failed to update the clients cluster config and have run out of // nodes. ErrExhaustedClusterNodes = errors.New("exhausted cluster nodes") // ErrThisNodeOnlyExpectsASingleAddress is returned if the user attempts to connect to a single node, but provides // more than one node in the connection string. ErrThisNodeOnlyExpectsASingleAddress = errors.New("when using 'ThisNodeOnly', a connection string with a single " + "address should be supplied") // ErrConnectionModeRequiresNonTLS is returned if the user attempts to connect using TLS when the connection mode // requires non-TLS communication. ErrConnectionModeRequiresNonTLS = errors.New("connection mode requires non-TLS communication") // ErrStreamWithTimeout is returned if the user attempts to execute a stream with a non-zero timeout. ErrStreamWithTimeout = errors.New("using a timeout when executing a streaming request is unsupported") // ErrInvalidNetwork is returned if the user supplies an invalid value for the 'network' query parameter. ErrInvalidNetwork = errors.New("invalid use of 'network' query parameter, expected 'default' or 'external'") )
var SupportedConnectionModes = []ConnectionMode{ ConnectionModeDefault, ConnectionModeThisNodeOnly, ConnectionModeLoopback, }
SupportedConnectionModes is a slice of the supported connection modes, this should be considered as read only.
Functions ¶
func IsEndpointNotFound ¶
IsEndpointNotFound returns a boolean indicating whether the given error is an 'EndpointNotFoundError'.
func IsServiceNotAvailable ¶
IsServiceNotAvailable returns a boolean indicating whether the given error is a 'ServiceNotAvailableError'.
func NewTestHandler ¶
NewTestHandler creates the most basic type of handler which will respond with the provided status/body.
func NewTestHandlerWithEOF ¶
func NewTestHandlerWithEOF(t *testing.T) http.HandlerFunc
NewTestHandlerWithEOF creates a handler which will cause an EOF error when attempting to read the body.
func NewTestHandlerWithHijack ¶
func NewTestHandlerWithHijack(t *testing.T) http.HandlerFunc
NewTestHandlerWithHijack creates a handler which will hijack the connection an immediately close it; this is simulating a socket closed in flight error.
func NewTestHandlerWithRetries ¶
func NewTestHandlerWithRetries(t *testing.T, numRetries, retryStatus, successStatus int, after string, body []byte, ) http.HandlerFunc
NewTestHandlerWithRetries builds upon the basic handler by simulating a flaky/busy endpoint which forces retries a configurable number of times before providing a valid response.
func NewTestHandlerWithStream ¶
NewTestHandlerWithStream creates a handler which will respond with a streaming response writing the provided body a given number of times.
func NewTestHandlerWithStreamHijack ¶
func NewTestHandlerWithStreamHijack(t *testing.T) http.HandlerFunc
NewTestHandlerWithStreamHijack creates a handler which will respond with a streaming response which will be immediately closed.
func NewTestHandlerWithValue ¶
NewTestHandlerWithValue creates a handler which reads and stores the request body in the provided interface. This should be used to validate that a requests body was the expected value.
Types ¶
type AlternateAddresses ¶
type AlternateAddresses struct {
External *External `json:"external"`
}
AlternateAddresses represents the 'alternateAddresses' payload sent the 'nodeServices' endpoint.
type AuthProvider ¶
type AuthProvider struct {
// contains filtered or unexported fields
}
AuthProvider is the auth provider for the REST client which handles providing credentials/hosts required to execute REST requests. This handles providing alternative addresses and SSL ports all of which should be completely transparent to the REST client itself.
func NewAuthProvider ¶
func NewAuthProvider(options AuthProviderOptions) *AuthProvider
NewAuthProvider creates a new 'AuthProvider' using the provided credentials.
func (*AuthProvider) GetAllServiceHosts ¶
func (a *AuthProvider) GetAllServiceHosts(service Service) ([]string, error)
GetAllServiceHosts gets all the possible hosts for a given service type.
NOTE: The returned strings are fully qualified hostnames with schemes and ports.
func (*AuthProvider) GetCredentials ¶
func (a *AuthProvider) GetCredentials(host string) (string, string)
GetCredentials returns the username/password credentials needed to authenticate against the given host.
func (*AuthProvider) GetServiceHost ¶
func (a *AuthProvider) GetServiceHost(service Service, offset int) (string, error)
GetServiceHost gets the host required to execute a REST request. A service may be provided to indicate that this request needs to be sent to a specific service.
Supplying an offest will (where possible) "shift" the node index so that we dispatch the request to a different node; this may help in certain cases where a node is currently being removed from the cluster.
NOTE: The returned string is a fully qualified hostname with scheme and port.
func (*AuthProvider) GetUserAgent ¶
func (a *AuthProvider) GetUserAgent() string
GetUserAgent returns a string which should be used as the 'User-Agent' header of any REST requests.
func (*AuthProvider) SetClusterConfig ¶
func (a *AuthProvider) SetClusterConfig(host string, config *ClusterConfig) error
SetClusterConfig updates the auth providers cluster config in a thread safe fashion. Returns an error if the provided config is older than the current config; this ensures that we don't use the config from a node which have been removed from the cluster.
func (*AuthProvider) UpdateResolvedAddress ¶
func (a *AuthProvider) UpdateResolvedAddress()
updateResolvedAddress updates the resolved connection string for AuthProvider to contain all node addresses.
type AuthProviderOptions ¶
type AuthProviderOptions struct {
// contains filtered or unexported fields
}
AuthProviderOptions encapsulates the options for creating a new REST AuthProvider.
type AuthenticationError ¶
type AuthenticationError struct {
// contains filtered or unexported fields
}
AuthenticationError is returned if we received a 401 status code from the cluster i.e. the users credentials are incorrect.
func (*AuthenticationError) Error ¶
func (e *AuthenticationError) Error() string
type AuthorizationError ¶
type AuthorizationError struct {
// contains filtered or unexported fields
}
AuthorizationError is returned if we receive a 403 status code from the cluster which means the credentials are correct but they don't have the needed permissions.
func (*AuthorizationError) Error ¶
func (e *AuthorizationError) Error() string
type BootstrapFailureError ¶
BootstrapFailureError is returned to the user if we've failed to bootstrap the REST client.
NOTE: The error message varies depending on whether we received at least one 401 when attempting to bootstrap.
func (*BootstrapFailureError) Error ¶
func (e *BootstrapFailureError) Error() string
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a REST client used to retrieve/send information to/from a Couchbase Cluster.
func NewClient ¶
func NewClient(options ClientOptions) (*Client, error)
NewClient creates a new REST client which will connection to the provided cluster using the given credentials.
NOTE: The returned client may (depending on the provided options) acquire resources which must be cleaned up using the clients 'Close' function. For example, the 'Close' function must be called to cleanup the cluster config polling goroutine.
func (*Client) AltAddr ¶
AltAddr returns a boolean indicating whether alternate addressing is currently enabled.
func (*Client) Close ¶
func (c *Client) Close()
Close releases any resources that are actively being consumed/used by the client.
func (*Client) ClusterUUID ¶
ClusterUUID returns the cluster uuid.
NOTE: This function may return stale data, for the most up-to-date information, use 'GetClusterMetaData'
func (*Client) DeveloperPreview ¶
DeveloperPreview returns a boolean indicating whether this cluster is in Developer Preview mode.
NOTE: This function may return stale data, for the most up-to-date information, use 'GetClusterMetaData'.
func (*Client) Do ¶
Do converts and executes the provided request returning the raw HTTP response. In general users should prefer to use the 'Execute' function which handles closing resources and returns more informative errors.
NOTE: If the returned error is nil, the Response will contain a non-nil Body which the caller is expected to close.
func (*Client) EnterpriseCluster ¶
EnterpriseCluster returns a boolean indicating whether this is an enterprise cluster.
NOTE: This function may return stale data, for the most up-to-date information, use 'GetClusterMetaData'.
func (*Client) Execute ¶
Execute the given request to completion reading the entire response body whilst honoring request level retries/timeout.
func (*Client) ExecuteStream ¶
func (c *Client) ExecuteStream(request *Request) (<-chan StreamingResponse, error)
ExecuteStream executes the given request, returning a read only channel which can be used to read updates from a streaming endpoint.
NOTE: The returned channel will be close when the remote connection closes the socket, in this case no error will be returned.
func (*Client) ExecuteStreamWithContext ¶
func (c *Client) ExecuteStreamWithContext(ctx context.Context, request *Request) (<-chan StreamingResponse, error)
ExecuteStreamWithContext executes the given request using the provided context, returning a read only channel which can be used to read updates from a streaming endpoint.
The returned channel will be close when either: 1. The remote connection closes the socket, in this case no error will be returned 2. The given context is cancelled, again no error will be returned
func (*Client) ExecuteWithContext ¶
ExecuteWithContext the given request to completion, using the provided context, reading the entire response body whilst honoring request level retries/timeout.
func (*Client) GetAllServiceHosts ¶
GetAllServiceHosts retrieves a list of all the nodes in the cluster that are running the provided service.
func (*Client) GetServiceHost ¶
GetServiceHost retrieves the address for a single node in the cluster which is running the provided service.
func (*Client) Nodes ¶
Nodes returns a copy of the slice of all the nodes in the cluster.
NOTE: This function returns a copy because this is the same data structure the client uses to dispatch REST requests.
func (*Client) Poll ¶
Poll runs the given polling function until we either reach a timeout, or the polling function returns true. Returns a boolean indicating whether we timed out waiting for the polling function to return true.
func (*Client) PollTimeout ¶
PollTimeout returns the poll timeout used by the current client.
func (*Client) PollWithContext ¶
func (c *Client) PollWithContext(ctx context.Context, poll func(attempt int) (bool, error)) (bool, error)
PollWithContext runs the given polling function until we either reach a timeout, or the polling function returns true. Returns a boolean indicating whether we timed out waiting for the polling function to return true.
NOTE: Returns true in the event that the provided context is cancelled.
func (*Client) RequestRetries ¶
RequestRetries returns the number of times a request will be retried for known failure cases.
type ClientOptions ¶
type ClientOptions struct { ConnectionString string Provider aprov.Provider TLSConfig *tls.Config // DisableCCP stops the client from periodically updating the cluster config. This should only be used if you know // what you're doing and you're only using a client for a short period of time, otherwise, it's possible for some // client functions to return stale data/attempt to address missing nodes. DisableCCP bool // ConnectionMode is the connection mode to use when connecting to the cluster, this may be used to limit how/where // REST requests are dispatched. ConnectionMode ConnectionMode // ReqResLogLevel is the level at which to the dispatching and receiving of requests/responses. ReqResLogLevel log.Level // Logger is the passed Logger struct that implements the Log method for logger the user wants to use. Logger log.Logger }
ClientOptions encapsulates the options for creating a new REST client.
type ClusterConfig ¶
ClusterConfig represents the payload sent by 'ns_server' when hitting the '/pools/default/nodeServices' endpoint.
func (*ClusterConfig) BootstrapNode ¶
func (c *ClusterConfig) BootstrapNode() *Node
BootstrapNode returns the node which we bootstrapped against.
func (*ClusterConfig) FilterOtherNodes ¶
func (c *ClusterConfig) FilterOtherNodes()
FilterOtherNodes filters out all nodes which aren't the bootstrap node; this has the effect of forcing all communication via the bootstrap node.
type ClusterConfigManager ¶
type ClusterConfigManager struct {
// contains filtered or unexported fields
}
ClusterConfigManager is a utility wrapper around the current cluster config which provides utility functions required when periodically updating the REST clients cluster config.
func NewClusterConfigManager ¶
func NewClusterConfigManager(logger log.Logger) *ClusterConfigManager
NewClusterConfigManager returns a new cluster config manager which will not immediately trigger a cluster config update.
func (*ClusterConfigManager) GetClusterConfig ¶
func (c *ClusterConfigManager) GetClusterConfig() *ClusterConfig
GetClusterConfig returns a copy of the current cluster config. This method should be preferred over manually accessing the cluster config to avoid unexpected modifications.
func (*ClusterConfigManager) Update ¶
func (c *ClusterConfigManager) Update(config *ClusterConfig) error
Update attempts to update the cluster config using the one provided, note that it may be rejected depending on the revision id.
func (*ClusterConfigManager) WaitUntilExpired ¶
func (c *ClusterConfigManager) WaitUntilExpired(ctx context.Context)
WaitUntilExpired blocks the calling goroutine until the current config has expired and the client should update the cluster config.
func (*ClusterConfigManager) WaitUntilUpdated ¶
func (c *ClusterConfigManager) WaitUntilUpdated(ctx context.Context)
WaitUntilUpdated triggers a config update and then blocks the calling goroutine until the update is complete.
type ConnectionMode ¶
type ConnectionMode int
ConnectionMode is a connection mode which slightly changes the behavior of the REST client.
const ( // ConnectionModeDefault is the standard connection mode, connections use HTTP/HTTPS depending on the given // connection string, and REST requests may be dispatched to any node in the cluster. ConnectionModeDefault ConnectionMode = iota // ConnectionModeThisNodeOnly means connections use HTTP/HTTPS depending on the given connection string, and REST // requests will only be dispatched to the given node. // // NOTE: An error will be raised if this connection mode is used where the connection string contains more than one // node. ConnectionModeThisNodeOnly // ConnectionModeLoopback is equivalent to 'ConnectionModeThisNodeOnly with the added requirement that all requests // are sent unencrypted, via loopback (127.0.0.1). // // NOTE: An error will be raised if this connection mode is used where the connection string contains more than one // node, or would create a TLS connection. ConnectionModeLoopback )
func (ConnectionMode) AllowTLS ¶
func (c ConnectionMode) AllowTLS() bool
AllowTLS returns a boolean indicating whether users can supply https/couchbases in the connection string.
func (ConnectionMode) ThisNodeOnly ¶
func (c ConnectionMode) ThisNodeOnly() bool
ThisNodeOnly returns a boolean indicating whether we're expecting to only communicate with a single node; the one provided in the connection string.
type ContentType ¶
type ContentType string
ContentType - Convenience wrapper around the content type of a request. Currently only JSON/form encoded are supported.
const ( // ContentTypeURLEncoded - Indicates that the body of this request is url encoded. ContentTypeURLEncoded ContentType = "application/x-www-form-urlencoded" // ContentTypeJSON - Indicates that the body of this request is json encoded. ContentTypeJSON ContentType = "application/json" )
type Endpoint ¶
type Endpoint string
Endpoint represents a single REST endpoint. Requests should only be dispatched to endpoints which exist in this file i.e. they shouldn't be created on the fly.
NOTE: Endpoints should not include query parameters, they may be supplied as raw 'url.Values' via the 'Request' data structure and will be encoded and postfixed to the request URL accordingly.
const ( // EndpointPools is the root of the 'ns_server' REST API. Used to fetch version information from the cluster. EndpointPools Endpoint = "/pools" // EndpointPoolsDefault represents the default cluster (i.e. 'self'). Used for extracting information about the // cluster itself. EndpointPoolsDefault Endpoint = "/pools/default" // EndpointBuckets represents the 'ns_server' endpoint used to interact with the buckets on the cluster. EndpointBuckets Endpoint = "/pools/default/buckets" // EndpointBucket represents the endpoint for interacting with a specific named bucket. EndpointBucket Endpoint = "/pools/default/buckets/%s" // EndpointBucketManifest represents the bucket collections manifest endpoint, can be used to get/update the // collection manifest for a bucket. EndpointBucketManifest Endpoint = "/pools/default/buckets/%s/scopes" // EndpointNodesServices is used during the bootstrapping process to fetch a list of all the nodes in the cluster. EndpointNodesServices Endpoint = "/pools/default/nodeServices" )
func (Endpoint) Format ¶
Format returns a new endpoint using 'fmt.Sprintf' to fill in any missing/required elements of the endpoint using the given arguments. All arguments will automatically be path escaped before being inserted into the endpoint.
NOTE: No validation takes place to ensure the correct number of arguments are supplied, that's down to you...
type EndpointNotFoundError ¶
type EndpointNotFoundError struct {
// contains filtered or unexported fields
}
EndpointNotFoundError is returned if we received a 404 status code from the cluster.
func (*EndpointNotFoundError) Error ¶
func (e *EndpointNotFoundError) Error() string
type External ¶
External is similar to the 'Node' structure but encapsulates all the alternative addressing information.
type Header ¶
Header is a readability wrapper around key/value pairs which will be set in the REST request header.
type InternalServerError ¶
type InternalServerError struct {
// contains filtered or unexported fields
}
InternalServerError is returned if we received a 500 status code from the cluster.
func (*InternalServerError) Error ¶
func (e *InternalServerError) Error() string
type Method ¶
type Method string
Method is a readability wrapper around the method for a given REST request; only the methods defined in the 'http' module should be used.
type Node ¶
type Node struct { Hostname string `json:"hostname"` Services *Services `json:"services"` AlternateAddresses AlternateAddresses `json:"alternateAddresses"` BootstrapNode bool `json:"thisNode"` }
Node encapsulates the addressing information for a single node in a Couchbase Cluster.
func (*Node) GetHostname ¶
GetHostname returns the hostname which can be used to address this node whilst honoring alternative addressing.
NOTE: Will return an empty string if this node doesn't have alternative addressing enabled.
func (*Node) GetPort ¶
GetPort returns the port which will be used to address this node whilst honoring whether to use ssl and alternative addressing.
NOTE: Will return a zero value port if no valid port can be found.
func (*Node) GetQualifiedHostname ¶
GetQualifiedHostname returns the fully qualified hostname to this node whilst honoring whether to use ssl or alternative addressing.
NOTE: Will return an empty string if there are no valid ports/addresses that we can use against this node.
type Nodes ¶
type Nodes []*Node
Nodes is a wrapper around a slice of nodes which allows custom unmarshalling.
type OldClusterConfigError ¶
type OldClusterConfigError struct {
// contains filtered or unexported fields
}
OldClusterConfigError is returned when the client attempts to bootstrap against a node which returns a cluster config which is older than the one we already have.
func (*OldClusterConfigError) Error ¶
func (e *OldClusterConfigError) Error() string
type PollFunc ¶
PollFunc is a readbility wrapper around the function which will be polled by the built in polling functionaility. If an error is return from this function, polling will immediately stop and the error will be bubbled up to the calling function.
NOTE: This function is called synchronously, therefore, blocking for extended periods of time could cause the controlling function to overrun the expected timeout.
type Request ¶
type Request struct { // Host overrides the host to which the request is dispatched to, when omitted, a host is chosen based on the // service the request is to be dispatched to. If this attribute is provided, 'Service' is ignored. // // NOTE: Here be dragons, it's far more robust to use the 'Service' attribute to determine which host a request // should be dispatched to. Host string // Method is the method used for this REST request. Should be one of the constants defined in the 'http' module. Method Method // Header is additional key/value pairs which will be set in the REST request header. Header Header // ContentType indicates what type of value we are sending to the cluster node. ContentType ContentType // Body is the request body itself. This attribute is not always required. Body []byte // Endpoint is the REST endpoint to hit, all endpoints should be of type 'Endpoint' so that urls are correctly // escaped. Endpoint Endpoint // QueryParameters are additional values which will be encoded and postfixed to the request URL. QueryParameters url.Values // Service indicates that this request should be sent to a node which is running a specific service. If 'Host' is // provided, this attribute is ignored. Service Service // ExpectedStatusCode indicates that when this REST request is successful, we will get this specific status code. ExpectedStatusCode int // Timeout overrides the default client timeout. If not set the client timeout will be used instead. // // NOTE: A value of -1 indicates that the timeout should be disabled. Timeout time.Duration // Idempotent indicates whether this request is idempotent and can be retried. // // The following attributes (RetryOnStatusCodes and NoRetryOnStatusCodes) may be used to configure retry // behavior for the request. // // NOTE: This only needs to be set for certain methods, as by default some should be idempotent as defined in // https://developer.mozilla.org/en-US/docs/Glossary/Idempotent. Idempotent bool // RetryOnStatusCodes is a list of status codes which will be used to indicate that we should retry the request. RetryOnStatusCodes []int // NoRetryOnStatusCodes is a list of status codes which will explicitly not be retried. NoRetryOnStatusCodes []int }
Request encapsulates the parameters/options which are required when sending a REST request.
func (*Request) IsIdempotent ¶
IsIdempotent returns a boolean indicating whether this request is idempotent and may be retried.
type RetriesExhaustedError ¶
type RetriesExhaustedError struct {
// contains filtered or unexported fields
}
RetriesExhaustedError is returned if the REST request was retried the maximum number of times.
NOTE: The number of times retried is configurable at runtime via an environment variable. See the 'Client' constructor for more information.
func (*RetriesExhaustedError) Error ¶
func (e *RetriesExhaustedError) Error() string
func (*RetriesExhaustedError) Unwrap ¶
func (e *RetriesExhaustedError) Unwrap() error
type Service ¶
type Service string
Service represents a service which can be running on a Couchbase node.
const ( // ServiceManagement represents 'ns_server' e.g. port 8091/18091. ServiceManagement Service = "Management" // ServiceAnalytics represents the Analytics Service. ServiceAnalytics Service = "Analytics" // ServiceData represents the KV/Data Service. ServiceData Service = "Data" // ServiceEventing represents the cluster level Eventing Service. ServiceEventing Service = "Eventing" // ServiceGSI represents the Indexing Service. ServiceGSI Service = "Indexing" // ServiceQuery represents the Query Service e.g. nodes running N1QL. ServiceQuery Service = "Query" // ServiceSearch represents the Search/Full Text Search Service. ServiceSearch Service = "Search" // ServiceViews represents hosts accepting requests for Views. ServiceViews Service = "Views" // ServiceBackup represents hosts accepting requests for the Backup Service. ServiceBackup Service = "Backup" )
type ServiceNotAvailableError ¶
type ServiceNotAvailableError struct {
// contains filtered or unexported fields
}
ServiceNotAvailableError is returned if the requested service is is unavailable i.e. there are no nodes in the cluster running that service.
func (*ServiceNotAvailableError) Error ¶
func (e *ServiceNotAvailableError) Error() string
type Services ¶
type Services struct { CAPI uint16 `json:"capi"` CAPISSL uint16 `json:"capiSSL"` KV uint16 `json:"kv"` KVSSL uint16 `json:"kvSSL"` Management uint16 `json:"mgmt"` ManagementSSL uint16 `json:"mgmtSSL"` FullText uint16 `json:"fts"` FullTextSSL uint16 `json:"ftsSSL"` SecondaryIndex uint16 `json:"indexHttp"` SecondaryIndexSSL uint16 `json:"indexHttps"` N1QL uint16 `json:"n1ql"` N1QLSSL uint16 `json:"n1qlSSL"` Eventing uint16 `json:"eventingAdminPort"` EventingSSL uint16 `json:"eventingSSL"` CBAS uint16 `json:"cbas"` CBASSSL uint16 `json:"cbasSSL"` Backup uint16 `json:"backupAPI"` BackupSSL uint16 `json:"backupAPIHTTPS"` }
Services encapsulates the ports that are active on this cluster node.
type SocketClosedInFlightError ¶
type SocketClosedInFlightError struct {
// contains filtered or unexported fields
}
SocketClosedInFlightError is returned if the client socket was closed during an active request. This is usually due to socket being closed by the remote host in the event of a fatal error.
func (*SocketClosedInFlightError) Error ¶
func (e *SocketClosedInFlightError) Error() string
type StreamingResponse ¶
type StreamingResponse struct { // Payload is the raw payload received from a streaming endpoint. Payload []byte // Error is an error received during streaming, after the first error, the stream will be terminated. Error error }
StreamingResponse encapsulates a single streaming response payload/error.
type TestBucket ¶
type TestBucket struct { UUID string NumVBuckets uint16 // Manifest should be a '*collections.Manifest' from 'backup'. Manifest json.Marshaler }
TestBucket represents a bucket that will exist in the test cluster. These attributes will configure the values returned by REST requests to the cluster.
type TestBuckets ¶
type TestBuckets map[string]*TestBucket
TestBuckets is a readbility alias around a map of buckets.
type TestCluster ¶
type TestCluster struct {
// contains filtered or unexported fields
}
TestCluster is a mock Couchbase cluster used for unit testing functionaility which relies on the REST client.
func NewTestCluster ¶
func NewTestCluster(t *testing.T, options TestClusterOptions) *TestCluster
NewTestCluster creates a new test cluster using the provided options.
NOTE: By default, the /pools, /pools/default and /pools/default/nodeServices endpoints are implemented and their return values can be manipulated via the cluster options. These endpoints can be overridden if required, however, note that they will still be required to return valid data which can be used to bootstrap the client.
func (*TestCluster) Address ¶
func (t *TestCluster) Address() string
Address returns the address of the cluster, for the time being should always be "127.0.0.1".
func (*TestCluster) Bucket ¶
func (t *TestCluster) Bucket(name string) func(writer http.ResponseWriter, request *http.Request)
Bucket implements the /pools/default/buckets/<bucket> endpoint, values can be modified by modifying the buckets in the cluster using the cluster options.
func (*TestCluster) BucketManifest ¶
func (t *TestCluster) BucketManifest(name string) func(writer http.ResponseWriter, request *http.Request)
BucketManifest implements the /pools/default/buckets/<bucket>/scopes endpoint. The returned manifest may be set using the cluster options.
func (*TestCluster) Buckets ¶
func (t *TestCluster) Buckets(writer http.ResponseWriter, _ *http.Request)
Buckets implements the /pools/default/buckets endpoint, values can be modified by modifying the buckets in the cluster using the cluster options.
func (*TestCluster) Certificate ¶
func (t *TestCluster) Certificate() *x509.Certificate
Certificate returns the certificate which can be used to authenticate the cluster.
NOTE: This will be <nil> if the cluster is not running with TLS enabled.
func (*TestCluster) Close ¶
func (t *TestCluster) Close()
Close stops the server releasing any held resources.
func (*TestCluster) Handler ¶
func (t *TestCluster) Handler(writer http.ResponseWriter, request *http.Request)
Handler is the base handler function for requests, additional endpoint handlers may be added using the 'Handlers' attribute of the cluster options.
NOTE: The current test will fatally terminate if no valid handler is found.
func (*TestCluster) Hostname ¶
func (t *TestCluster) Hostname() string
Hostname returns the cluster hostname, for the time being this will always be "localhost".
func (*TestCluster) NodeServices ¶
func (t *TestCluster) NodeServices(writer http.ResponseWriter, _ *http.Request)
NodeServices implements the /pools/default/nodeServices endpoint, values can be modified by modifying the nodes in the cluster using the cluster options.
func (*TestCluster) Nodes ¶
func (t *TestCluster) Nodes() Nodes
Nodes returns the list of nodes in the cluster, generated using the test nodes provided in the cluster options.
func (*TestCluster) Pools ¶
func (t *TestCluster) Pools(writer http.ResponseWriter, _ *http.Request)
Pools implements the /pools endpoint, the return values can be modified using the cluster options.
func (*TestCluster) PoolsDefault ¶
func (t *TestCluster) PoolsDefault(writer http.ResponseWriter, _ *http.Request)
PoolsDefault implements the /pools/default endpoint, values can be modified by modifying the nodes in the cluster using the cluster options.
func (*TestCluster) Port ¶
func (t *TestCluster) Port() uint16
Port returns the port which requests should be sent to; this will be the same port for all services.
NOTE: This port is randomly selected at runtime and will therefore vary.
func (*TestCluster) URL ¶
func (t *TestCluster) URL() string
URL returns the fully qualified URL which can be used to connect to the cluster.
type TestClusterOptions ¶
type TestClusterOptions struct { // Used for the /pools endpoint Enterprise bool UUID string DeveloperPreview bool // Used for both the /pools/default and the /pools/default/nodeServices endpoint Nodes TestNodes // Used for the /pools/default/buckets endpoint Buckets TestBuckets // Additional handler functions which are run to handle a REST request dispatched to the cluster Handlers TestHandlers // A non-nil TLS config indicates that the cluster should use TLS TLSConfig *tls.Config }
TestClusterOptions encapsulates the options which can be passed when creating a new test cluster. These options configure the behavior/setup of the cluster.
type TestHandlers ¶
type TestHandlers map[string]http.HandlerFunc
TestHandlers is a readbility wrapper around the endpoint handlers for a test cluster.
func (TestHandlers) Add ¶
func (e TestHandlers) Add(method, endpoint string, handler http.HandlerFunc)
Add a new handler to the endpoint handlers, note that the method is required to ensure unique handlers for each endpoint.
func (TestHandlers) Handle ¶
func (e TestHandlers) Handle(writer http.ResponseWriter, request *http.Request) bool
Handle utility function which handles the provided request returning a boolen indicating whether a handler was found.
type TestNode ¶
type TestNode struct { Version cbvalue.Version Status string Services []Service SSL bool AltAddress bool }
TestNode encapsulates the options which can be used to configure a single node in a test cluster.
type TestNodes ¶
type TestNodes []*TestNode
TestNodes is a readbility wrapper around a slice of test nodes.
type UnexpectedEndOfBodyError ¶
type UnexpectedEndOfBodyError struct {
// contains filtered or unexported fields
}
UnexpectedEndOfBodyError is returned if the length of the request body does not match the expected length. This may happen in the event that the 'Content-Length' header value is incorrectly set.
func (*UnexpectedEndOfBodyError) Error ¶
func (e *UnexpectedEndOfBodyError) Error() string
type UnexpectedStatusCodeError ¶
type UnexpectedStatusCodeError struct { Status int // contains filtered or unexported fields }
UnexpectedStatusCodeError returned if a request was executed successfully, however, we received a response status code which was unexpected.
NOTE: During development its possible to hit this error in the event that the expected status code is set incorrectly and the successful response does not return a body so is therefore something to watch out for.
func (*UnexpectedStatusCodeError) Error ¶
func (e *UnexpectedStatusCodeError) Error() string
type UnknownAuthorityError ¶
type UnknownAuthorityError struct {
// contains filtered or unexported fields
}
UnknownAuthorityError is returned when the dispatched REST request receives an 'UnknownAuthorityError'.
func (*UnknownAuthorityError) Error ¶
func (e *UnknownAuthorityError) Error() string
type UnknownX509Error ¶
type UnknownX509Error struct {
// contains filtered or unexported fields
}
UnknownX509Error is returned when the dispatched REST request receives a generic (unhandled) x509 error.
func (*UnknownX509Error) Error ¶
func (e *UnknownX509Error) Error() string
func (*UnknownX509Error) Unwrap ¶
func (e *UnknownX509Error) Unwrap() error