Detailed Description

These routines contain functionality for parsing a cluster topology configuration and mapping keys to cluster nodes appropriately.

Function Documentation

◆ lcbvb_create()

lcbvb_CONFIG * lcbvb_create ( void )

Allocate a new config This can be used to create new config object and load it with a JSON config, optionally retrieving the error code.

Stability

Uncommitted

lcbvb_CONFIG *cfg = lcbvb_create();
if (0 != lcbvb_load_json(cfg, json)) {
  printf("Got error!", lcbvb_get_error(cfg));
  lcbvb_destroy(cfg);
}

◆ lcbvb_parse_json()

lcbvb_CONFIG * lcbvb_parse_json ( const char * data )

Stability

Uncommitted: Parse the configuration string in data and return a new config object

Parameters

data

Returns: A new config object, or NULL on error.

◆ lcbvb_load_json()

int lcbvb_load_json	(	lcbvb_CONFIG *	vbc,
		const char *	data )

Stability

Committed: Load a JSON-based configuration string into a configuration object

Parameters

vbc	Object to populate
data	NUL-terminated string to parse
source	hostname of the node, which emitted configuration. Pointer to NULL will disable heuristic when network argument is pointer to NULL string.
network	pointer to string, which specified key in alternative addresses dict. Use pointer NULL string to trigger heuristic, in this case, the function will try to match configuration source address to the list of addresses to determine best network.

Returns: 0 on success, nonzero on failure

Note: it is recommended to use this function rather than lcbvb_parse_json() as this will contain the error string in the configuration in case of parse failures.

◆ lcbvb_load_json_ex()

int lcbvb_load_json_ex	(	lcbvb_CONFIG *	vbc,
		const char *	data,
		const char *	source,
		char **	network )

Stability

Uncommitted

◆ lcbvb_save_json()

char * lcbvb_save_json ( lcbvb_CONFIG * vbc )

Serialize the current config as a JSON string.

Stability

Volatile: Serialize the current configuration as a JSON string. The string returned is NUL-terminated and should be freed using the free() function.

◆ lcbvb_get_error()

const char * lcbvb_get_error ( const lcbvb_CONFIG * vbc )

Return a string indicating why parsing the configuration failed.

Stability

Committed

Returns: An error string. Do not free this string

◆ lcbvb_replace_host()

void lcbvb_replace_host	(	lcbvb_CONFIG *	cfg,
		const char *	hostname )

Replace hostname placeholders with specific host string This function shall replace hostname placeholists with the actual host string specified in hoststr.

Stability

Volatile

Parameters

cfg	the configuration
hostname	the actual hostname to use.

Use this immediately after a successful parsing of the configuration file.

◆ lcbvb_destroy()

void lcbvb_destroy ( lcbvb_CONFIG * conf )

Stability

Committed: Destroy the configuration object

Parameters

conf

◆ lcbvb_vbmaster()

int lcbvb_vbmaster	(	lcbvb_CONFIG *	cfg,
		int	vbid )

Stability

Committed

Gets the master node index for the given vbucket

Parameters

cfg	The configuration
vbid	The vbucket to query

Returns: The master index. -1 if offline

Warning: This function does no bounds checking for vbid. Ensure it is within range of 0 < vbid < cfg->nvbs

◆ lcbvb_vbreplica()

int lcbvb_vbreplica	(	lcbvb_CONFIG *	cfg,
		int	vbid,
		unsigned	ix )

Stability

Committed

Return the 0-based replica index for the given vbucket.

Parameters

cfg	The configuration object
vbid	The vbucket to query
ix	the replica index to retrieve. This is a number ranging from 0 to vbc->nrepl exclusive.

Returns: The replica index, or -1 if offline

Warning: This function does no bounds checking for vbix or ix. Ensure that 0 < vbid < cfg->nvbs and -1 < ix < cfg->nrepl

◆ lcbvb_nmv_remap_ex()

int lcbvb_nmv_remap_ex	(	lcbvb_CONFIG *	cfg,
		int	vbid,
		int	bad,
		int	use_heuristics )

Stability

Uncommitted

Using various guesswork and heuristics, attempt to locate an alternate node for the master of a given vbucket. This should be used if the master index is -1 or if the master index is deemed incorrect by some other means.

Parameters

cfg	the configuration object
vbid	the vbucket index to loop up
bad	the index known to be bad. Passing this parameter allows the handler to safely call this function and be sure that a previous call's applied heuristics will not affect the modified map.
use_heuristics	whether additional heuristics should be used. If heuristics is off, only the fast-forward map is employed.

◆ lcbvb_map_key()

int lcbvb_map_key	(	lcbvb_CONFIG *	cfg,
		const void *	key,
		lcb_SIZE	n,
		int *	vbid,
		int *	srvix )

Stability

Committed

Map a given string to a vbucket and server

Parameters

	cfg	The configuration object
	key	Key to map
	n	Length of key
[out]	vbid	Will contain the vBucket
[out]	srvix	Will contain the server index

Returns: 0 for now

◆ lcbvb_k2vb()

int lcbvb_k2vb	(	lcbvb_CONFIG *	cfg,
		const void *	key,
		lcb_SIZE	n )

Stability

Committed

Maps a key to a vBucket ID

Parameters

cfg	The configuration
key	The key to retrieve
n	The size of the key

Returns: the vBucket for the key

◆ lcbvb_has_vbucket()

int lcbvb_has_vbucket	(	lcbvb_CONFIG *	vbc,
		int	vbid,
		int	ix )

Stability

Uncommitted: Determines if a given server index is either a master or a replica for a vbucket

Parameters

vbc	the configuration
vbid	the vbucket number
ix	the server index to check against

Returns: nonzero if the server ix is either a master or a replica for the vbucket vbid. Returns 0 otherwise.

◆ lcbvb_get_nservers()

unsigned lcbvb_get_nservers ( const lcbvb_CONFIG * cfg )

Get the number of servers in the bucket. Note that not all servers may actually be available.

Stability

Committed

Parameters

cfg	The configuration

Returns: The number of servers

◆ lcbvb_get_nreplicas()

unsigned lcbvb_get_nreplicas ( const lcbvb_CONFIG * cfg )

Get the number of replicas the bucket is configured with Note that not all replicas may necessarily be online or available.

Stability

Committed

Parameters

cfg	the configuration

Returns: the number of configured replicas

◆ lcbvb_get_nvbuckets()

unsigned lcbvb_get_nvbuckets ( const lcbvb_CONFIG * cfg )

Get the number of vbuckets the bucket is configured with.

Stability

Committed

Returns: the number of vbuckets, or zero if not applicable

◆ lcbvb_get_distmode()

lcbvb_DISTMODE lcbvb_get_distmode ( const lcbvb_CONFIG * cfg )

Get the distribution mode (AKA bucket type) of the bucket.

Stability

Committed

Parameters

cfg	the configuration

Returns: the distribution mode

◆ lcbvb_get_revision()

int lcbvb_get_revision ( const lcbvb_CONFIG * cfg )

Get the revision for this configuration.

Stability

Committed

The revision is an integer which is increased each time the cluster generates a new configuration. This feature is available only on configurations generated by nodes of Couchbase Server v2.5 or later.

Parameters

cfg	the configuration

Returns: The revision ID, or -1 if the config does not have a revision

◆ lcbvb_get_port()

unsigned lcbvb_get_port	(	lcbvb_CONFIG *	cfg,
		unsigned	ix,
		lcbvb_SVCTYPE	type,
		lcbvb_SVCMODE	mode )

Gets the port associated with a given service of a given mode on a given server.

Stability

Committed

Parameters

cfg	the config object
ix	the index of the server to query
type	the type of service being provided
mode	the mode of transport being used (e.g. plain, ssl)

Returns: a number greater than zero if the port exists, 0 otherwise

◆ lcbvb_get_hostport()

const char * lcbvb_get_hostport	(	lcbvb_CONFIG *	cfg,
		unsigned	ix,
		lcbvb_SVCTYPE	type,
		lcbvb_SVCMODE	mode )

Return a string for the given service This is like lcbvb_get_port but returns a string in the form of host:port rather than the numeric port.

Stability

Committed

Parameters

cfg
ix
type
mode

Returns: A string if the service is found, NULL otherwise. The storage duration of the string is valid until the configuration object is destroyed.

◆ lcbvb_get_hostname()

const char * lcbvb_get_hostname	(	const lcbvb_CONFIG *	cfg,
		unsigned	ix )

Get the hostname of a given server index. This may be used if all nodes reside on different hostnames, and can be used to answer the question of "which node does this index belong to" without having to perform additional string processing on the port of the string.

Stability

Committed

Parameters

cfg	the configuration
ix	the index of the server to look up

Returns: a hostname without a port, or NULL if the index is out of bounds

◆ lcbvb_get_resturl()

const char * lcbvb_get_resturl	(	lcbvb_CONFIG *	cfg,
		unsigned	ix,
		lcbvb_SVCTYPE	type,
		lcbvb_SVCMODE	mode )

Function to return the URL prefix for a REST service.

Returns a string suitable for being passed as a URL. This is only valid for LCBVB_SVCTYPE_VIEWS and LCBVB_SVCTYPE_QUERY.

This function is different from lcbvb_get_hostport() – it is mainly a convenience, but does cache the string. Also, theoretically the cluster is free to choose a different URL prefix for a given service. Using this function will guarantee the URL prefix is correct.

◆ lcbvb_get_randhost()

int lcbvb_get_randhost	(	const lcbvb_CONFIG *	cfg,
		lcbvb_SVCTYPE	type,
		lcbvb_SVCMODE	mode )

Convenience function to select a random node for a service.

Returns: 0 or greater if a node was found; a negative number if no node contains a service with the given criteria.

◆ lcbvb_get_randhost_ex()

int lcbvb_get_randhost_ex	(	const lcbvb_CONFIG *	cfg,
		lcbvb_SVCTYPE	type,
		lcbvb_SVCMODE	mode,
		int *	used )

Get random node, excluding nodes already tried.

Parameters

cfg	the config
type	type of service
mode	transport mode
used	an array of integers representing server indexes (should be of size LCBVB_NSERVERS). Servers whose indexes in the `used` array are nonzero will be skipped.

Returns: a server index, or -1 if no server remains (either because no server has the service, or because all available servers are in the exclude list)

◆ lcbvb_compare()

lcbvb_CONFIGDIFF * lcbvb_compare	(	lcbvb_CONFIG *	from,
		lcbvb_CONFIG *	to )

Compare two configurations and return information on the changes.

Stability

Volatile

Parameters

from	the original configuration to use as the base
to	the new configuration

Returns: an object which may be inspected, or NULL on allocation failure. The returned object should be freed with lcbvb_free_diff()

See also: lcbvb_get_changetype()

◆ lcbvb_get_changetype()

lcbvb_CHANGETYPE lcbvb_get_changetype ( lcbvb_CONFIGDIFF * diff )

Get a quick summary of the changes in the passed object.

Parameters

diff	the diff returned from lcbvb_compare()

◆ lcbvb_genconfig_ex()

int lcbvb_genconfig_ex	(	lcbvb_CONFIG *	vb,
		const char *	name,
		const char *	uuid,
		const lcbvb_SERVER *	servers,
		unsigned	nservers,
		unsigned	nreplica,
		unsigned	nvbuckets )

Generate a sample configuration.

Stability

Volatile

Parameters

vb	a new configuration object returned via lcbvb_create()
name	the name of the bucket
uuid	UUID for the bucket
servers	an array of server objects which will serve as the basis for the server list within the configuration. The memory pointed to by servers may be released after this function has completed
nservers	number of servers in the array
nreplica	how many replicas for the bucket
nvbuckets	how many vbuckets for the bucket

◆ lcbvb_genconfig()

int lcbvb_genconfig	(	lcbvb_CONFIG *	vb,
		unsigned	nservers,
		unsigned	nreplica,
		unsigned	nvbuckets )

Generate a sample configuration used for testing.

Stability

Volatile

Parameters

vb	a new configuration object returned via lcbvb_create()
nservers	how many nodes to place into the configuration
nreplica	how many replicas should be assigned to the bucket
nvbuckets	how many vbuckets to create

Returns: 0 on success, nonzero on error

Note: The base port for the lcbvb_SERVICES::data starts at 1000; the base port for lcbvb_SERVICES::views starts at 2000 and the base port for lcbvb_SERVICES::mgmt starts at 3000. The port number is incremented for each additional node.

◆ lcbvb_genffmap()

void lcbvb_genffmap ( lcbvb_CONFIG * vb )

Stability

Volatile: Generate a fast-forward vBucket map for the configuration. This simply provides alternate indices.

◆ lcbvb_make_ketama()

void lcbvb_make_ketama ( lcbvb_CONFIG * vb )

Stability

Volatile: Convert the configuration to a ketama one.

Parameters

vb	The configuration object.

◆ lcbvb_get_capibase()

const char * lcbvb_get_capibase	(	lcbvb_CONFIG *	cfg,
		unsigned	ix,
		lcbvb_SVCMODE	mode )

Stability

Committed

Get the views URL base.

Parameters

cfg	The configuration
ix	The index of the server to fetch
mode	The mode, either plain or ssl

Returns: A string reprenting the URL, or NULL if not available.

Data Structure Documentation

◆ lcbvb_SERVICES

struct lcbvb_SERVICES

Services which may be provided by a node.

Stability

Volatile: . ABI/API compatibility not guaranteed between versions

Data Fields
lcb_U16	data	Data port for key-value operations (memcached protocol)
lcb_U16	mgmt	Port for adminsitrative operations (HTTP)
lcb_U16	views	Port for view queries (HTTP)
lcb_U16	ixquery	Indexing query port.
lcb_U16	ixadmin	Indexing admin port (HTTP)
lcb_U16	n1ql	Query port.
lcb_U16	fts	CBFT.
lcb_U16	cbas	CBAS (Analytics)
lcb_U16	eventing	Eventing Management.
char *	views_base_	Views base URL.
char *	query_base_	N1QL base URL.
char *	fts_base_
char *	cbas_base_
char *	eventing_base_
char *	hoststrs[LCBVB_SVCTYPE__MAX]

◆ lcbvb_SERVER

struct lcbvb_SERVER

Node in the cluster This structure represents a node in the cluster. The node has a hostname (hostname), and various services.

Stability

Volatile: . ABI/API compatibility not guaranteed between versions.

Data Fields
lcbvb_SERVICES	svc	Plain services.
lcbvb_SERVICES	svc_ssl	SSL Services.
char *	authority	host:dataport for comparison
char *	hostname	Hostname for the node.
char *	viewpath	Path prefix for view queries.
char *	querypath	Path prefix for n1ql queries.
char *	ftspath	Path prefix for fulltext queries.
char *	cbaspath	Path prefix for analytics queries.
char *	eventingpath	Path prefix for eventing service.
unsigned	nvbs	Total number of vbuckets the server has assigned.
char *	alt_hostname	selected alternative hostname for the node
lcbvb_SERVICES	alt_svc	selected alternative plain services
lcbvb_SERVICES	alt_svc_ssl	selected alternative SSL Services
char *	server_group	the group name or NULL

◆ lcbvb_VBUCKET

struct lcbvb_VBUCKET

Stability

Volatile: . ABI/API compatibility not guaranteed between versions

Data Fields
int	servers[4]

◆ lcbvb_CONTINUUM

struct lcbvb_CONTINUUM

Stability

Volatile

Data Fields
lcb_U32	index
lcb_U32	point

◆ lcbvb_CONFIG

struct lcbvb_CONFIG

Structure containing the configuration.

Stability

Volatile: . ABI/API compatibility not guaranteed between versions.

Data Fields
lcbvb_DISTMODE	dtype	Type of bucket/distribution.
unsigned	nvb	Number of vbuckets.
unsigned	ndatasrv	Number of data (memcached) servers.
unsigned	nsrv
unsigned	nrepl	Number of servers. Number of replicas
unsigned	ncontinuum
unsigned	is3x
int64_t	revepoch
int64_t	revid
char *	buuid
char *	bname
size_t	bname_len
const char *	errstr
lcbvb_SERVER *	servers
lcbvb_VBUCKET *	vbuckets
lcbvb_VBUCKET *	ffvbuckets
lcbvb_CONTINUUM *	continuum
int *	randbuf
uint64_t	caps	Bucket capabilities.
uint64_t	ccaps	Cluster capabilities.

◆ lcbvb_CONFIGDIFF

struct lcbvb_CONFIGDIFF

Structure representing changes between two configurations.

Data Fields
char **	servers_added	List of strings of servers added (via `host:data_port`)
char **	servers_removed	List of strings of servers removed (via `host:data_port`)
int	n_vb_changes	How many vBuckets have had an ownership change.
int	sequence_changed	Whether the ordering of the nodes has changed as well.
int	n_repl_changed	Whether the number of the replicas has changed.

Macro Definition Documentation

◆ lcbvb_vbserver

#define lcbvb_vbserver	(	cfg,
		vbid,
		ix )

Stability

Volatile: This allows to get the given index for a vbucket server. If the index is 0 then this returns the master index, if the index is greater then it returns the replica index

◆ lcbvb_nmv_remap

#define lcbvb_nmv_remap	(	cfg,
		vbid,
		bad )

uncommitted Equivalent to

lcbvb_nmv_remap_ex(cfg, vbid, bad, 0);

lcbvb_nmv_remap_ex

int lcbvb_nmv_remap_ex(lcbvb_CONFIG *cfg, int vbid, int bad, int use_heuristics)

Enumeration Type Documentation

◆ lcbvb_SVCTYPE

enum lcbvb_SVCTYPE

This enum functions as a 'key' to indicate a specific service offered by a node.

Enumerator
LCBVB_SVCTYPE_DATA	memcached/Data port
LCBVB_SVCTYPE_VIEWS	Views/CAPI port.
LCBVB_SVCTYPE_MGMT	Administrative/'REST' UI.
LCBVB_SVCTYPE_IXQUERY	Index query.
LCBVB_SVCTYPE_IXADMIN	Index administration.
LCBVB_SVCTYPE_QUERY	N1QL Query.
LCBVB_SVCTYPE_SEARCH	Fulltext.
LCBVB_SVCTYPE_ANALYTICS	Analytics Query.
LCBVB_SVCTYPE_EVENTING	Eventing Management.

◆ lcbvb_SVCMODE

enum lcbvb_SVCMODE

This enum functions to indicate the 'mode' of the service.

Currently this is to distinguish between SSL and plain transports

Enumerator
LCBVB_SVCMODE_PLAIN	Plain transport.
LCBVB_SVCMODE_SSL	SSL Transport.

◆ lcbvb_DISTMODE

enum lcbvb_DISTMODE

Type of algorithm used to distribute keys.

This also indicates the type of bucket

Enumerator
LCBVB_DIST_VBUCKET	vBucket hashing ("couchbase") bucket
LCBVB_DIST_KETAMA	Ketama hashing ("memcached") bucket.
LCBVB_DIST_UNKNOWN	Unknown distribution (cluster config)

◆ lcbvb_CHANGETYPE

enum lcbvb_CHANGETYPE

Convenience enum to determine the mode of change.

Enumerator
LCBVB_NO_CHANGES	No changes between configs.
LCBVB_SERVERS_MODIFIED	Servers have been added or removed.
LCBVB_MAP_MODIFIED	vBuckets have been transferred
LCBVB_REPLICAS_MODIFIED	number of replicas has been modified