markin-couchbase/deps/lcb/RELEASE_NOTES.markdown

Markin Fork of Couchbase Node.js Client Library.

# Release Notes

## 2.5.0 (May 12 2015)

This change in the major version number signals the addition of new features
for Couchbase Server 4.0; most of the actual new functionality for Couchbase
4.0 has already been included (incrementally) in prior 2.4.x versions. The
new 2.5 version is built on the 2.4.x codebase.

* Add `cbc-n1qlback` - a simple benchmark for N1QL queries. This functions
  by executing a line-delimited file containing query bodies using multiple
  threads if possible.
  * Priority: Major
  * Issues: [CCBC-604](http://issues.couchbase.com/browse/CCBC-604)

* `TCP_NODELAY` functionality has now been placed into effect. This
  functionality was nominally present in prior versions, but would not work
  because of a typo.
  * Priority: Minor

* Add 'tick' or 'pump' mode for I/O
  As an alternative to `lcb_wait()`, applications may call `lcb_tick_nowait()`
  to incrementally perform (non-blocking) I/O. This may provide a performance
  boost when batching/scheduling many operations. `lcb_wait()` itself must be
  called to guarantee completion of all operations, and the `lcb_tick_nowait()`
  functionality is only available on some I/O plugins. See the API docs for
  more information.
  * Priority: Major
  * Issues: [CCBC-598](http://issues.couchbase.com/browse/CCBC-598)

* Allow "console logger" to log to a file
  As a convenience, it is now possible to direct the library to write to
  a log file rather than standard error. This is possible using the
  `LCB_CNTL_CONLOGGER_FP` (to programmatically set a `FILE*` value via
  `lcb_cntl()`) or `console_log_file` to set the path of the file (which
  will be overwritten) via `lcb_cntl_string()` or the connection string.

* Make `lcb_N1QLPARAMS` repeatable/debuggable
  This allows the `lcb_n1p_mkcmd()` call to be invoked multiple times without
  actually modifying internal state. Previously calling this function twice
  would result in corruption of the internal parameter state. In this version,
  a new function, `lcb_n1p_encode()` has been added (which `lcb_n1p_mkcmd()`
  wraps) which may be used to inspect the encoded form of the query.

## 2.4.9 (April 14 2015)

* Disable HTTP provider when any CCCP config is received.
  This makes the assumption that CCCP will always be available if even a
  single node provides an HTTP configuration. This change may break some
  corner-case upgrade scenarios from version 2.2 to 2.5 where a newly added
  2.5 node is subsequently removed.
  * Priority: Major
  * Issues: [CCBC-526](http://issues.couchbase.com/browse/CCBC-526),
    [CCBC-589](http://issues.couchbase.com/browse/CCBC-589)

* Fix additional missing defines for UV's `EAI_*` symbols
  This was not entirely fixed in 2.4.8, since some undefined macros still
  remained.
  * Priority: Major
  * Issues: [CCBC-596](http://issues.couchbase.com/browse/CCBC-596)

* Make connection string timeout parameters (e.g. `operation_timeout`) always
  specify seconds; this will no longer require the decimal point to be used,
  but will break any prior usages of this value for microseconds.
  * Priority: Minor
  * Issues: [CCBC-597](http://issues.couchbase.com/browse/CCBC-597)

* Add `cbc n1ql` subcommand, which executes N1QL queries.
  This subcommand is still a bit rough around the edges, mainly because of
  server-side support for "pretty=false" (which makes the rows display rather
  weirdly).
  * Priority: Major
  * Issues: [CCBC-595](http://issues.couchbase.com/browse/CCBC-595)

* Allow usage of `-D` option in `cbc` and `cbc-pillowfight` tools.
  This flag allows specifying connection string options in a more
  concise form on the commandline. The `-D` option may be specified
  multiple times in the form of `-Doption=value`.
  * Priority: Minor

* Interpret `couchbase://host:8091` connection string as `couchbase://host`
  Previously the library would treat `8091` as a memcached port. While technically
  correct according to the connection string semantics, would often be a
  source of confusion for users migrating from older versions of the library
  (or other SDKs) when using the form `http://host:8091`. A special provision
  is thus made for such a cas.
  * Priority: Major
  * Issues: [CCBC-599](http://issues.couchbase.com/browse/CCBC-599)

* Implement enhanced durability using sequence numbers.
  This feature is available in Couchbase 4.0, and uses sequence numbers
  (optionally specified in the response packet of each mutation).
  sequence-based durability constraints help resolve some ambiguity in
  the case of checking the durability of items which have since been
  mutated, or in the case of a cluster failover. Using this functionality
  requires the `LCB_CNTL_FETCH_SYNCTOKENS` (or `fetch_synctokens`) and the
  `LCB_CNTL_DURABILITY_SYNCTOKENS` (or `dur_synctokens`)
  settings to be enabled (using `lcb_cntl()` or `lcb_cntl_string()`, or
  in the connection string). Enabling `LCB_CNTL_FETCH_SYNCTOKENS` will
  cause mutation response packets from the server to return an additional
  16 bytes of sequence data, and enabling `LCB_CNTL_DURABILITY_SYNCTOKENS`
  will cause `lcb_durability_poll()` to transparently use this information
  (rather than the CAS) to check for persistence/replication.
  **Only available in Couchbase 4.0**. As a result of this feature, much
  of the durability subsystem itself has been rewritten, making durability
  overall more performant, even for CAS-based durability.
  * Priority: Major
  * Issues: [CCBC-569](http://issues.couchbase.com/browse/CCBC-569)

* Add `lcb_version_g` extern symbol as alternative to `lcb_get_version()`.
  This symbol is an extern global which allows simple runtime checking of
  the library version. This is more convenient than `lcb_get_version()` as
  it avoids the requirement to create a temporary variable on the stack
  (`lcb_get_version()` returns a string, and requires an `lcb_U32` pointer
  as its first argument to get the actual numeric version).
  * Priority: Minor


## 2.4.8 (Mar. 8 2015)

* Retry next nodes on initial bootstrap, even if first node says bucket does
  not exist (or auth error), as this might be a recently removed node
  * Priority: Major
  * Issues: [CCBC-577](http://issues.couchbase.com/browse/CCBC-577)

* The `cbc` and `cbc-pillowfight` binaries on Windows are now distributed
  in both _release_ and _debug_ variants. Previously they would be clobbered
  by one or the other depending on the build host. This fixes some issues in
  performance and dependency resolution when using these libraries.
  * Priority: Minor
  * Issues: [CCBC-581](http://issues.couchbase.com/browse/CCBC-581)

* Provide Read-Only config cache mode. In this mode the configuration cache
  file is read but never updated. Additionally, a missing file in this mode
  results in a hard error.
  * Priority: Major
  * Issues: [CCBC-584](http://issues.couchbase.com/browse/CCBC-584)

* Keep vBucket heuristic guesses for limited periods of time.
  This will allow previously-learned vBucket master locations to persist
  over a configuration change, providing these changes were discovered
  recently. This allows the reduction of not-my-vbucket responses while
  allowing new configs to overwrite our heuristic info, if the heuristic is
  too old.
  * Priority: Major

* Fix potential crashes in get-with-replica (`lcb_rget3`, `lcb_get_replica`)
  when there are no replicas available, or if there is an error in retrieving
  from one of the replicas.
  * Priority: Major
  * Issues: [CCBC-586](http://issues.couchbase.com/browse/CCBC-586)

* Do not wait between not-my-vbucket retries
  This behavior restores the pre 2.4.0 behavior of retrying not-my-vbucket
  responses, with a more intelligent retry/rotation algorithm (see the
  release note about "vbucket map heuristics"). Previously a wait-time
  was introduced because of potential busy loops in retrying to the same
  node. The `LCB_CNTL_RETRY_NMV_IMM` setting can be used to disable this
  functionality (by disabling it, i.e. setting it to 0). This may also be
  disabled in the connection string via `retry_nmv_imm=0`.
  * Priority: Major
  * Issues: [CCBC-588](http://issues.couchbase.com/browse/CCBC-588)

* Fix compilation error with UV when `EAI_BADHINTS` is not defined in the
  system. This is primarily an issue with newer UV versions and some versions
  of Linux
  * Priority: Major
  * Issues: [CCBC-590](http://issues.couchbase.com/browse/CCBC-590)

* Allow means to disable C++ behavior on public library structures, allowing
  them to be initialized via C-style static initializers.
  This allows the zeroing of structures such as `lcb_get_cmd_t cmd = { 0 }`,
  which would ordinarily fail under C++ compilation because of that structure
  having a defined C++ constructor. Applications can take advantage of this
  feature by defining the `LCB_NO_DEPR_CXX_CTORS` preprocessor macro when
  compiling.
  * Priority: Major
  * Issues: [CCBC-591](http://issues.couchbase.com/browse/CCBC-591)

* Fix some bugs in timing behavior (`lcb_enable_timings`). Timings between
  1000-2000ms are now reported accurately. Additionally for more common
  handling, second timing ranges (between 1-9s) are reported in ms range
  (i.e. timings of 4 seconds are reported as 3000-4000ms ).
  * Priority: Minor
  * Issues: [CCBC-582](http://issues.couchbase.com/browse/CCBC-582)


## 2.4.7 (Feb. 17 2015)

* Fix SSL connection failures with `SSL_UNDEFINED_CONST_FUNCTION`.
  This would sometimes cause failures during early connection/negotiation
  stages.
  * Priority: Major
  * Issues: [CCBC-571](http://issues.couchbase.com/browse/CCBC-571)

* Add _experimental_ support for N1QL queries.
  This adds support for contacting N1QL endpoints and retrieving their
  result sets. The support at both the client and server components is
  still a work in progress.
  The API is similar to the view api (see `lcb_view_query()`) added in
  version 2.4.6. See details in `<libcouchbase/n1ql.h>`
  * Priority: Major
  * Issues: [CCBC-572](http://issues.couchbase.com/browse/CCBC-572)

* Add _experimental_ support for geospatial view queries.
  GeoSpatial views are available as an experimental feature in the
  current releases of the server. This will soon be offered as a
  stable feature in future releases.
  Applications may now use the `lcb_RESPVIEWQUERY::geometry` field
  and the `LCB_CMDVIEWQUERY_F_SPATIAL` to utilize geospatial views.
  * Priority: Major
  * Issues: [CCBC-573](http://issues.couchbase.com/browse/CCBC-573)

* Fix memory leak for retried commands.
  In cases where a given command needs to be retried more than once, a
  memory leak was fixed in which the previous instance of the pacekt was
  not properly freed.
  * Priority: Major
  * Issues: [CCBC-574](http://issues.couchbase.com/browse/CCBC-574)

## 2.4.6 (January 20 2015)

* Fix floating point exception on OS X.
  A floating point exception would sometimes be thrown on OS X sytems due
  to bad time structure initialization. The installation provided with
  homebrew for 2.4.5 fixed this issue. This is completely fixed in 2.4.6
  Priority: Major

* Improve warning messages when using deprecated options in `cbc`.
  This provides less ambiguous help messages when using deprecated options,
  showing a full and complete example for proper usage (when possible).
  * Priority: Minor
  * Issues: [CCBC-562](http://issues.couchbase.com/browse/CCBC-562)

* Add patch/micro version to DLL information on Windows.
  This lets the user see the exact version of the library on windows (via
  right clicking on the DLL and inspecting the details). Previously this
  information contained only the major and minor versions.
  * Priority: Minor
  * Issues: [CCBC-563](http://issues.couchbase.com/browse/CCBC-563)

* Provide _pkgconfig_ (`.pc`) file with installation.
  This may help third party applications and libraries link against libcouchbase
  in some environments.

* Provide one-off `unsafe_optimize` option for connection string/`lcb_cntl`.
  This provides a shorter way to enable some potentially unsafe optimizations
  which may make the client perform better in some scenarios.
  * Priority: Minor

* Allow prompting for password in `cbc`.
  The `cbc` and `cbc-pillowfight` utilities will now securely prompt for the
  password if the password specified on the commandline is a hyphen (`-`).
  * Priority: Minor
  * Issues: [CCBC-565](http://issues.couchbase.com/browse/CCBC-565)

* Fix timeouts in some durability when not all replicas are online.
  The library will now fail the operation with `LCB_DURABILITY_ETOOMANY`
  rather than allowing the operation to timeout.
  * Priority: Major
  * Issues: [CCBC-560](http://issues.couchbase.com/browse/CCBC-560)

* Add high level row-based view functionality.
  This adds a new API (currently considered _volatile_) which allows
  intelligently querying views. This builds atop the basic HTTP
  interface, and exposes a row-based callback API based upon
  streaming JSON parsing. The new API is defined in `<libcouchbase/views.h>`.
  This API will become more stable over time.
  * Priority: Major
  * Issues: [CCBC-100](http://issues.couchbase.com/browse/CCBC-100)

* Parse configuration service locations for experimental services
  This exposes the N1QL and indexing services via the _lcbvb_ API. See
  `libcouchbase/vbucket.h` for more information.

## 2.4.5 (December 17 2014)

* Fix `pillowfight` ignoring `set-ratio` values above 50
  The program would ignore these values and act as if 100 was specified,
  thus never issuing any GET operations
  * Priority: Minor
  * Issues: [CCBC-550](http://couchbase.com/issues/browse/CCBC-550)

* Building with autotools is no longer supported.
  If building the library from source, you _must_ use
  [CMake](http://cmake.org/download) version 2.8.9 or greater. If unfamiliar
  with CMake, the README describes the process. Included also is a top-level
  script called `configure.pl` which functions with an autoconf-like interface.
  * Priority: Major

* Fix customized IOPS crashes in some usage cases
  This fixes scenarios where applications assume that the built-in IOPS version
  is 0, and attempt to "Subclass" the IOPS structure. The internal version of
  the library structure is now 3, with some extra heuristics in place to ensure
  that the older code will still function.
  This issue was most visible in the Python SDK when using the gevent or Twisted
  plugins.
  This issue was first introduced with version 2.4.4
  * Priority: Critical
  * Issues: [CCBC-557](http://couchbase.com/issues/browse/CCBC-557)

* Allow raw `certpath` to be passed without need for percent-encoding (in most cases)
  This allows for a common pattern fo passing `certpath` in the connection string as
  a raw, unencoded path. This allows a user to do
  `couchbases://host/bucket?certpath=/foo/bar/baz`.

* Fix missing installation UV plugin headers and source
  In 2.4.4 this was accidentally left out, and would only be installed if the plugin
  itself was built and installed. This affected building the Node.JS SDK using an
  existing libcouchbase install.
  * Priority: Major
  * Issues: [CCBC-558](http://couchbase.com/issues/browse/CCBC-558)

## 2.4.4 (Nov. 19 2014)

* Detect disconnected pooled sockets
  This allows the connection pool to detect dead sockets which were closed
  by a server when they were idle. Sometimes servers will close connections
  to open idle sockets to save resources, or because of bugs in their
  implementations.
  This will fix some issues experienced with views where queries would
  randomly fail with `LCB_NETWORK_ERROR` or `LCB_ESOCKSHUTDOWN`, by first
  checking if the socket is alive before returning it back to the library's
  core.
  Note that the `libuv` plugin does not implement this functionality yet.
  * Priority: Critical
  * Issues: [CCBC-546](http://couchbase.com/issues/browse/CCBC-546)

* Fix _pillowfight_ `--min-size` bug
  This fixes a bug where pillowfight would sometimes compare the `min-size`
  option to an uninitialized `max-size` option and round it down to that
  value; then would set the `max-size` option.
  * Priority: Major
  * Issues: [CCBC-542](http://couchbase.com/issues/browse/CCBC-542)

* Don't ignore `LCB_CNTL_DURABILITY_INTERVAL`
  Fix a bug where this interval would be ignored, if modified by the user; always
  reverting to 100ms.
  * Priority: Major
  * Issues: [CCBC-543](http://couchbase.com/issues/browse/CCBC-543)

* Fix memory leak with HTTP requests using a request body
  Requests (such as `PUT`, `POST`, etc) which contained a request body
  would cause a memory leak as the library forgot to free them when the
  request object was destroyed.
  * Priority: Major
  * Issues: [CCBC-538](http://couchbase.com/issues/browse/CCBC-538)

* Fix errneous `LCB_SUCCESS` return when passed duplicate keys to
  `lcb_durability_poll()`. This would cause applications to mistakenly wait
  for a callback to arrive, when in fact the command had failed.
  * Priority: Major
  * Issues: [CCBC-536](http://couchbase.com/issues/browse/CCBC-535)

* Add option to preserve vbucket ownership heuristics across config updates
  This allows the learned configuration settings to persist between configuration
  updates. The default behavior (up to, and including this change) is to
  discard any "learned" configuration in favor of the explicitly new config
  passed to the server. This new option allows this information to be persisted
  when a new configuration update is received. This behavior is considered
  experimental, and is primarily intended to reduce the time it takes for the
  client to relearn the current node (which is typically under 1-2 seconds).
  * Priority: Minor
  * Issues: [CCBC-530](http://couchbase.com/issues/browse/CCBC-530)

* Relocate memcached packets on topology changes for memcached buckets
  This enhances the behavior of the client when operating with a memcached
  bucket during a topology change. Previously the library would not relocate
  packets to new servers, resulting in errors for items which were now
  mapped to wrong nodes. The new behavior remaps the key to the new server
  using the updated ketama hashing. Note that as a current restriction, the
  remapping will be performed based on the key of the item, not any `hashkey`
  parameter being employed.
  * Priority: Major
  * Issues: [CCBC-331](http://couchbase.com/issues/browse/CCBC-331)

* Return error if ignored/conflicting options are found
  This changes the behavior of the library to throw an error if a specific
  option field was filled in which did not make sense for a given command, for
  example, specifying a `cas` value using a `LCB_ADD` operation with `lcb_store`.
  * Priority: Major
  * Issues: [CCBC-529](http://couchbase.com/issues/browse/CCBC-529)

* Fix issue when sending out large _OBSERVE_ command.
  This would cause a partial command to be sent out if the size of the output
  packet was greater than 512 bytes. This has been fixed by dynamically growing
  the output buffer for _OBSERVE_
  * Priority: Minor
  * Issues: [CCBC-528](http://couchbase.com/issues/browse/CCBC-528)

* Fix spurious timeouts when using `lcb_durability_poll`
  This fixes an issue where sometimes the durability poll operation would
  prematurely time out.
  * Priority: Major
  * Issues: [CCBC-527](http://couchbase.com/issues/browse/CCBC-527)

## 2.4.3 (Oct. 21 2014)

* Disable support for SSLv3
  This works around the _POODLE_ SSLv3 vulnerability by disabling support for
  anything below TLSv1.

  * Priority: Critical
  * Issues: [CCBC-523](http://couchbase.com/issues/browse/CCBC-523)

* Pillowfight enhancements
  Several behavior changes were made to pillowfight in this version. These are:
  * The `-l` or `-c -1` option is in effect by default. This means that by
    default `pillowfight` will run an infinite number of cycles. The previous
    behavior was to default to a single cycle, requiring an explicit `--loop`
    to ensure the workload ran for a considerable amount of time.

  * When multiple threads are used, the workload is divided among the threads,
    thus making it that each thread only operates on a subset of the data.

  * A `--sequential` option has been added to allow the workload to operate
    in _sequence_ on the total number of items. This is useful when wishing to
    load a bucket with many items.

  * A `--start-at` option has been added to allow the workload to specify an
    alternate range of keys; effectively allowing resumption of a previous
    run. The `--start-at` flag allows to specify the lower bound number which
    will be used to generate keys. Thus a `--num-items=20000` and a
    `--start-at=10000` will generate keys from 10000 through 30000.

  * The _population_ phase has now been merged with the general workload
    implementation. This means that all worker threads will participate in
    the population phase. The previous behavior limited the populate phase to
    a single thread.

  * If `stdout` is detected to be a terminal, a simple "OPS/SEC" meter will
    periodically write the estimated throughput to the screen.

* Fix memory leak when using large read buffers
  In the case where large read buffers are used (and the `iovec` elements
  becomes sizable, the library may end up incorrectly caching some memory
  blocks for future use. This fix makes the blocks be cached at the allocator
  level, so that they are properly (re) utilized.

  * Priority: Major
  * Issues: [CCBC-519](http://couchbase.com/issue/browse/CCBC-519)

* Use forward map (and other heuristics) to get a next node for an item after
  a not-my-vbucket reply. Since the server (see bug attached) does not always
  guarantee that a given config is the most _correct_, the client must do some
  guesswork in order to properly map a node when it gets a not-my-vbucket;
  especially if the config says that the node is the correct one.

  * Priority: Major
  * Issues: [MB-12268](http://couchbase.com/issues/browse/MB-12268)

## 2.4.2 (Sep. 23 2014)

* Mark the `hashkey` fields as being _volatile_.
  Usage of this field is not supported in many cluster systems and is thus not
  supported functionality. It exists primarily as a legacy from an older API
  * Priority: Major
  * Issues: [CCBC-508](http://couchbase.com/issues/browse/CCBC-508)

* Add "key stats" mode to `lcb_CMDDSTATS`.
  This adds an additional key stats mode to the `lcb_stats3()` API
  which interprets the `key` field as being a document ID for which
  information (such as expiry, status) should be retrieved, rather
  than a system statistics key. Similar functionality already exists
  in the Java client library as `getKeyStats()`. In addition to this
  feature, a `cbc stats --keystats` option is also provided to employ
  this functionality from the command line.
  * Priority: Major
  * Issues: [CCBC-318](http://couchbase.com/issues/CCBC-318)

* Add more details about replica nodes in the `cbc hash` command.
  * Priority: Minor
  * Issues: [CCBC-504](http://couchbase.com/issues/browse/CCBC-504)

* Add `lcb_cntl()` setting to retrieve bucket name.
  Previously the library did not have a means by which the bucket name
  could be retrieved. Using the `LCB_CNTL_BUCKETNAME` setting, the bucket
  name will now be returned.
  * Priority: Major
  * Issues: [CCBC-502](http://couchbase.com/issues/CCBC-502)

## 2.4.1


* Implement `mcflush` subcommand for `cbc`. This was removed in the cbc
  rewrite as the previous `flush` command.
  * Priority: Minor
  * Issues: [CCBC-486](http://couchbase.com/issues/browse/CCBC-486)


* Requests issued to an invalid replica via `lcb_get_replica()` should fail
  with the `LCB_NO_MATCHING_SERVER_CODE`. Previously this sometimes went
  through due to an incorrect bounds checking in the `lcbvb_vbreplica()`
  function.
  * Priority: Major
  * Issues: [CCBC-488](http://couchbase.com/issues/browse/CCBC-488)


* Fixed a memory leak in `lcb_get_replica()` when the operation would fail.
  * Priority: Major
  * Issues: [CCBC-489](http://couchbase.com/issues/browse/CCBC-489)
    [CCBC-490](http://couchbase.com/issues/browse/CCBC-490)



* Fix memory leak in `lcb_sched_fail()` when extended commands are in the
  pipeline
  * Priority: Major
  * Issues: [CCBC-474](http://couchbase.com/issues/browse/CCBC-474)



* Provide `lcb_dump()` function call to dump state information about
  a client handle. The function call itself is currently marked as
  volatile and the output format is very much likely to change.
  * Priority: Minor
  * Issues: [CCBC-491](http://couchbase.com/issues/browse/CCBC-490)


* Fix `ratio` argument in `cbc-pillowfight`. This ensures that the
  `ratio` argument will truly determine the ratio of gets to sets.
  * Priority: Minor

* Fix crash when HTTP request is retried. This may take place during topology
  changes
  * Priority: Major
  * Issues: [CCBC-497](http://couchbase.com/issues/browse/CCBC-497)

* Allow simple host-port string in connection string, giving it an implicit
  `http://` scheme. This allows easier backwards compatibility with some
  application
  * Priority: Minor
  * Issues: [CCBC-500](http://couchbase.com/issues/browse/CCBC-500)

* Update some SSL options to better reflect server 3.0 functionality
  The old `capath` option has been renamed to `certpath` to indicate that the
  path is not to the signing authority, but to the self-signed server certificate
  generated by the server itself. Additionally the `no_verify` option has been
  hidden.
  * Priority: Major
  * Issues: [CCBC-501](http://couchbase.com/issues/browse/CCBC-501)

## 2.4.0 GA

* [major] Attempt to retry items that are mapped to a non-existent node in
  a degraded cluster. Rather than returning `LCB_NO_MATCHING_SERVER` the
  behavior should be to wait for the item to succeed and attempt to fetch
  a new cluster configuration.

  In order to control how such 'orphaned' commands are handled, a new value
  has been added to the `lcb_RETRYMODEOPTS` called `LCB_RETRY_ON_MISSINGNODE`
  which dictates how commands should be rescheduled if the associated vbucket
  has no master. The default is to retry the command until it times out, but
  by setting this value to `0` (See `LCB_CNTL_RETRYMODE`) it may only be
  attempted once, causing 'fail fast' behavior in such a case.

* [major] Don't throttle config requests based on initial file-based config.
  This allows the client to quickly recover from a stale config cache without
  waiting for the `LCB_CNTL_CONFDELAY_THRESH` interval to elapse. Prior to this
  fix, a client would appear to "not recover" if bootstrapping from a stale cache.
  In reality the client would eventually recover but was waiting for the delay
  threshold to elapse.

* [major] Ignore `NOT_MY_VBUCKET` config payloads if CCCP provider is disabled.
  This allows the client to circumvent any possible bugs in the CCCP response
  payload and rely entirely on the HTTP config. It also allows 'rewriting'
  proxies like confsed to function.

## 2.4.0-beta

* [major] Better error reporting for SSL failures.
  This adds new error codes (`LCB_SSL_ERROR`, `LCB_SSL_CANTVERIFY`)
  which are returned on initialization and verification failures
  respectively.

* [minor] Communication via legacy memcached servers is possible
  by using the `memcached://` scheme in the connection string.

* [minor] Environment variables understood by the library are now
  documented in their own section.

* [major] Add `lcb_get_node()` function to retrieve addresses for
  various nodes in the cluster. This deprecates the `lcb_get_host()`,
  `lcb_get_port()` and `lcb_get_server_list()` functions as they are
  constrained to only return information about the administrative API.
  The new function is configurable to return information about various
  ports.

* [major] The `dsn` field in the `lcb_create_st` structure has been
  renamed to `connstr`.

* [major] An HTTP request which has followed redirects will cause the
  `lcb_wait()` function to never return. This bug was introduced in
  2.4.0-DP1 and has now been fixed.

* [minor] `lcb_get_server_list()` function now returns updated information
  from the current cluster configuration. Previously this would only return
  a node from the list specified during initial creation.

* [minor] Provide additional error classifiers. Two error classifiers have
  been added, they are:

  * `LCB_ERRTYPE_SRVLOAD` which indicates that the server is likely under high load.
  * `LCB_ERRTYPE_SRVGEN` which indicates that the error is a direct reply from the
    server. This code can help distinguish between client and server generated
    return codes.

* [major] Provide HTTP keepalive and connection pooling for HTTP requests.
  This allows the client to reuse an HTTP connection for multiple requests
  rather than creating a new connection and closing it for each operation.

  The functionality may be controlled via the `LCB_CNTL_HTTP_POOLSIZE` setting
  which limits how many open connections (per server) to maintain inside the
  client. Setting this value to `0` will disable pooling and restore old
  behavior.

* [major] Properly schedule next invocations for retry queue. A bug was introduced
  in 2.4.0-dp1 which would cause the next tick callback to be invoked in what is
  effectively a busy loop. This would be reflected in higher CPU load and less
  throughput during topology changes.

* [major] Return error if empty key is passed to an operation. Empty keys will
  cause the server to drop the connection.
  The error code returned is the newly added `LCB_EMPTY_KEY`

* [minor] Provide setting to disable refreshing the configuration when an HTTP
  API error is encountered (from one of the HTTP callback functions). This
  adds the `LCB_CNTL_HTTP_REFRESH_CONFIG_ON_ERROR` setting.

* [major] Fix bug where the CCCP provider may prematurely fail, activating the
  HTTP provider


## 2.4.0-dp1 (2014-06-18)


**Changes affecting older APIs**

* [minor] Make `run_event_loop` and `stop_event_loop` private.
  These functions may no longer be used from within an application to
  start/stop the event loop. `lcb_wait()` and `lcb_wait3()` should be
  used instead.

* [major] Deprecate the `lcb_set_XXX` functions. `lcb_set_timeout`
  and some other calls have been deprecated in favor of the `lcb_cntl()`
  interface. These functions will still work but will cause the compiler
  to print a deprecation warning.

* [minor] `lcb_socket_t` is typedefed to a `DWORD` on windows. In
  previous versions this was an `int`.

* [minor] Connecting to a standalone memcached instance is currently no longer
  supported.

* [major] `lcb_set_error_callback()` has been deprecated. Applications should
  use the new `lcb_set_bootstrap_callback()` and/or operation callbacks
  to determine success/failure status.

* [major] `lcb_get_last_error()` has been deprecated. Error information is always
  returned in the operation callback

* [major] Disable the sending of `GETQ` packets. The format of this command
  is cumbersome to deal with and in most uses cases is actually slightly
  _less_ efficient on the network. Note that this does not change the API
  of the actual `lcb_get()` call, but simply changes the format of the
  packets sent over the wire.

* [major] The IOPS API has been changed. This is considered volatile interface
  and may subsequently change in the future as well.

**New APIs added in 2.4.0 extending existing functionality**

These changes extend existing features with enhanced APIs

* [major] Additional APIs for `lcb_cntl()`. These consist of helper functions
  to make it easier to use simple types or strings rather than pointers, if
  possible. These functions are `lcb_cntl_string()`, `lcb_cntl_setu32()` and
  `lcb_cntl_getu32()`

* [minor] Provide extended version of `lcb_wait()`.
  A new function called `lcb_wait3()` has been added which offers additional
  options with respect to running the event loop. Specifically it offers to
  bypass the check for pending operations which `lcb_wait()` executes. This
  is both more performant and allows us to wait for operations which are
  not explicitly scheduled.

* [major] Provide API to request a configuration refresh.
  Sometimes it is necessary to force the client to request a new configuration,
  for example in certain failover conditions. A new API called `lcb_config_refresh()`
  has been added, and should be used in conjunction with `lcb_wait3()`.

* [major] Provide bootstrapping notification callback
  This provides an explicit `lcb_set_bootstrap_callback()` to definitively
  determine whether the client has received its initial configuration (and
  thus may now start performing operations) or whether it failed (and thus
  must be reinitialized). This deprecates the common use case of
  `lcb_set_error_callback()`.

* [major] New vBucket interface/API. This API is used internally and exposed
  as _volatile_ inside the public header files. It provides extended features,
  a more concise API, and is compatible with the upcoming Couchbase 3.0 config
  format. Note that file-based configuration caches written by this version of
  the library are incompatible with previous versions, however this version may
  read caches generated by previous versions. This is because this version generates
  a stripped-down version of the "terse" configuration style.

* [major] Extended detailed error codes.
  These error codes expose more detail about the `NETWORK_ERROR` and
  `CONNECT_ERROR` codes returned by previous versions of the library. The extended
  codes are not returned by default and must be explicitly enabled in order to
  retain backwards compatibility with applications which rely on the older
  error codes.


**New Features in 2.4.0**

* [major] Connection Strings (aka "dsn") feature for instance creation. This adds a new
  version of the `lcb_create_st` structure which is passed a URI-like string
  rather than a semicolon-delimited list of hosts. This string is used to
  provide options and the list of hosts that the library should connect to.
  For example, `couchbase://default/localhost&compression=off`

* [major] SSL transport support for Couchbase 3.0 Enterprise.
  Couchbase 3.0 enterprise features the ability to encrypt communications
  between the client and the server using the SSL protocol. SSL protocol
  support in _libcouchbase_.

* [major] Retry queue for failed operations. The retry queue is used
  as a place to place operations which have failed internally and which
  should be retried within a certain amount of time. This also provides
  options on which commands should be retried.

* [minor] Compression/JSON flag (aka Datatype) support
  This adds support for a future feature of Couchbase server which will
  feature transparent compression. This feature also allows the server
  to signal to the library if a document is JSON or not. The compression
  feature may be disabled at compile-time, and may also be modified at
  runtime by setting `compression=off` in either the connection string
  or via `lcb_cntl_setstring(instance, "compression", "off")`

* [major] Experimental _scheduling_ API. This API replaces most of the older
  operation APIs with a scheduling API. These APIs are called with one
  command at a time and insert the resultant packet into a pipeline. The
  user may "schedule" the commands or "fail" the pipeline if a certain
  request has failed to be scheduled.

  This API also provides a common ABI header for commands so that they may
  easily be used via type-punning, or wrapped as a class hierarchy in C++.

  This API is currently considered volatile but will be the basis of the
  upcoming libcouchbase 3.0 API. The header file is `<libcouchbase/api3.h>`

* [major] Raw memcached packets may be sent to the library and have a callback
  invoked when their responses have been received.
  This adds an `lcb_pktfwd3()` API. This requires the new scheduling API.


**Bug Fixes in 2.4.0**

* [major] _select_ plugin may endlessly loop in some cases
  The plugin may loop if there was a long timeout from the
  future .

* [major] Do not break TCP connections on topology changes unless ejected from
  cluster. This ensures that nodes which are still part of the cluster have their
  TCP connections remain in tact despite being shifted in their server index values.
  Packets which have been sent to the wrong vBucket are silently ignored and
  rescheduled to their appropriate destination. This decreases load significantly
  on the client, network, and cluster during topology changes.

* [major] Use new-style "Terse" URI format when requesting a configuration over HTTP.
  This uses the HTTP configuration format over the new `/pools/default/bs/default`
  rather than the older `/pools/default/bucketsStreaming/default` form. The former
  form is much more efficient on the cluster side. If the new URI form is not
  supported (i.e. the server responds with an HTTP 404) the older form will be
  used instead. You may modify this behavior by setting the `LCB_CNTL_HTCONFIG_URLTYPE`
  setting via `lcb_cntl()`.

* [minor] The `cmake/configure` script now accepts the `LDFLAGS`, `CPPFLAGS`, `CFLAGS`,
  `CXXFLAGS`, `CC`, and `CXX` settings both within the environment _and_ the
  commandline, so the forms of `CC=clang ./cmake/configure` and
  `./cmake/configure CC=clang` are equivalent.

* [minor] The `pillowfight` tool will now print latencies between 1-10ms in resolutions
  of 100us.


**Metadata and Packaging Changes in 2.4.0**

* [major] Use Doxygen for API documentation.
  This replaces the _manpages_ for API documentation with Doxygen. Doxygen
  is a free and portable documentation system which may be obtained from your
  distribution or at [](http://doxygen.org). To generate the documentation
  from the source tree, simply run `doxygen` from the source root directory.
  To generate internal documentation, run `./docs/gen_internal_apidoc.sh`.

* [major] Add interface attributes to all API calls
  This properly documents all API calls with a certain API stability level
  such as _committed_ (for stable APIs), _uncomitted_ for APIs which may, but
  are not likely to change, and _volatile_ for APIs which are likely to be
  changed or removed.

* [major] Public header files have been reorganized
  This changes the layout of the header files from previous versions. This should
  not affect applications as applications should only ever include the main
  `<libcouchbase/couchbase.h>` file.

  the following files have been _removed_ from the
  `<libcouchbase/*>` header directory:

    * `types.h` - Merged into other header files
    * `arguments.h` - now a part of `couchbase.h`
    * `callbacks.h` - now a part of `couchbase.h`
    * `debug.h` - unused and obsolete
    * `durability.h` - now a part of `couchbase.h`
    * `behavior.h` - Merged into `deprecated.h`
    * `sanitycheck.h` - Merged into `deprecated.h`
    * `timings.h` - Part of `couchbase.h`
    * `compat.h` - Part of `deprecated.h`

  The following files have been _added_ into the `<libcouchbase/*>` directory.
  Unless otherwise noted, these files are included by `<libcouchbase/couchbase.h>`:

    * `api3.h` - Volatile proposed 3.0 API. **Not included by default**
    * `cxxwrap.h` - Contains the implementation for the deprecated C++ wrappers
    * `deprecated.h` - Contains deprecated APIs
    * `iops.h` - Contains the IO integration APIs
    * `pktfwd.h` - Contains the packet forwarding API. **Not included by default**
    * `vbucket.h` - Contains the vBucket mapping API. **Not included by default**

* OpenSSL is now a base dependency for the library. This may be disabled at configure
  time via `--enable-ssl=no`. See `./configure --help`.

* Snappy compression library is bundled and optionally compiled. This is left out by
  default as the configure script will search for a system installed `libsnappy`.
  Snappy provides the compression feature needed for compressing and inflating data
  between client and server. It may be disabled at compile-time via `--enable-snappy=no`

* [minor] _libvbucket_ has been fully integrated into libcouchbase from the forked
  _libvbucket_ package and, lives fully as part of the
  library. The public vBucket API may be found in `<libcouchbase/vbucket.h>`.

* [minor] As an alternative to the cross-platform `lcb_uintNN_t` typedefs, a shorter
  (and more standards compliant) alternative `lcb_UNN` typedefs are provided, thus
  instead of `lcb_uint32_t` you may use `lcb_U32`. The full listing of cross platform
  typdefs may be found inside `<libcouchbase/sysdefs.h>`



## 2.3.1 (2014-05-08)

* [major] CCBC-404: Segfault in `connmgr_invoke_request`
  Occasionally a segmentation fault would happen when a connection was being
  released as a result of a connection failure. This was because of invalid
  list tracking.

* [major] CCBC-395: Add `lcb_cntl()` interface for configuration cache
  Configuration cache options may be set after instantiation using `lcb_cntl()`
  with the new `LCB_CNTL_CONFIGCACHE` operation. The old-style `lcb_create_compat`
  creation path is deprecated.

* [major] CCBC-394: Get-with-replica occasionally crashes on Windows and UV
  during topology changes. This was due to not allocating a buffer if one did
  not exist.

* [major] CCBC-392: ABI compatibility broken between 2.x and 2.3 for
  `lcb_create_compat`. This has been fixed by symbol aliasing between versions.
  Developers are recommended to use the `lcb_cntl()` API to set the
  configuration cache, as specified in CCBC-395

* [major] CCBC-385: Failed assertion on get-with-replica when connection fails.
  If a connection fails with a `CMD_GET_REPLICA` command still in the queue an
  assertion failure will crash the library. This has been fixed by handling the
  opcode in the `failout_single_request` function.

* [major] CCBC-384: Unknown Winsock error codes crash application. This was fixed
  by providing proper handlers for Winsock codes which were not explicitly
  converted into their POSIX equivalents.

* [major] CCBC-376: Fix memory leak in configuration parsing. A leak was
  introduced in version 2.3.0 by not freeing the JSON pool structure. This has
  been fixed in 2.3.1

* [minor] CCBC-370: `lcb_get_host` and `lcb_get_port` may return host-port
  combinations from different servers. If multiple servers are listening on
  different ports this may result in yielding an invalid endpoint by combining
  the output from those two functions. This has been fixed in 2.3.1 by returning
  the host and port from the first host, in lieu of a currently-connected REST
  endpoint.

* [minor] CCBC-368: Initial bootstrapping failure may mask `LCB_BUCKET_ENOENT`
  calls with `LCB_ETIMEDOUT`. This has been fixed by not retrying configuration
  retrieval if an explicit HTTP 404 code is received. Note that when using
  bootstrap over memcached, a missing bucket may still be manifest as
  `LCB_AUTH_ERROR`.

* [minor] CCBC-367: Ensure `lcb_get_host` does not return `NULL` when the
  associated `lcb_t` is of `LCB_TYPE_CLUSTER`. This would cause crashes in some
  applications which relied on this function to not return `NULL`.

* [major] CCBC-389: Fixed Spurious timeouts being delivered in asynchronous
  use cases.
  In applications which do not use `lcb_wait()` the library will potentially
  time out commands internally triggering an erroneous configuration refresh.
  While this issue would not end up failing operations it will cause unnecessary
  network traffic for retrieving configurations. Applications using `lcb_wait()`
  are not affected as that function resets the timeout handler.

* [major] CCBC-332, CCBC-364: Compare configuration revision information
  for memcached cluster bootstrap. Previously we would refresh the
  configuration upon receipt
  of any new configuration update from memcached. This is fixed in 2.3.1 where
  the configuration will only be applied if it is deemed to be newer than the
  current configuration. With memcached bootstrap this is only true if the
  configuration's `rev` field is higher than the current one.


## 2.3.0 GA (2014-04-07)

* [major] CCBC-152: Provide a master-only observe option. This adds a new
  struct version to the `lcb_observe_cmd_t` which allows to select only the
  master node. One can use this to efficiently check if the key exists (without
  retrieving it). It also allows one to get the CAS of the item without fetching
  it.

* [major] CCBC-281: Fix partial scheduling during multi operations. Previously
  the library would deliver spurious callbacks  if multiple operations were
  scheduled with a single command and one of the operations could not be mapped
  to a server. This fixes this behavior and ensures that callbacks are only
  invoked for items if the entire API call succeeded.

* [major] CCBC-150: Multi-packet commands will no longer deliver spurious
  callbacks on failure. Previously these commands would be relocated to the
  same server during a configuration change, resulting in multiple callbacks
  for the same command. In this case the client would think all the commands
  had been completed, and when the next response arrived it would incorrectly
  map it to a different request.

* [minor] CCBC-327: Fix assumption of `vbucket_compare()` only returning if
  a diff exists. This function actually returns a non-NULL pointer always
  unless it cannot allocate more memory. This bug was introduced with the
  _DP1_ release.

* [minor] CCBC-326: Memcached buckets should use streaming config. This was
  left unchecked in the _DP1_ release and has now been fixed.

* [major] CCBC-351: Enhance performance for configuration parsing. In previous
  versions receiving multiple configurations at once would cause CPU spikes on
  slower systems. The configuration parser code has been optimized to alleviate
  this issue.

* [minor] CCBC-350: Provide `lcb_cntl()` API to retrieve the SCM changeset used
  by the currently loaded binary. This is a more effective way to get the
  revision as it does not depend on the specific headers the library was
  compiled with.

* [major] CCBC-340: Correctly parse `""`, `"0"` and `"1"` for environment
  variables. In previous versions having the entry set to an empty string
  or `0` would still be treated by the library as a true value for various
  environment variables. This has been fixed so that clear "False" values
  such as the empty string or 0 are treated as such.


## 2.3.0-dp1 (2014-02-04)

* [major] CCBC-234: Implementation of
  [Cluster Configuration Carrier Publication][cccp-wiki]. This is the new and
  more efficient way to bootstrap from a cluster using the native memcached
  protocol and is quicker than the previous HTTP bootstrap mechanism, dramatically
  improving startup times and reducing load on the server. This feature is
  available in server verions 2.5 and greater. The existing HTTP configuration is
  still supported and will be employed as a fallback in the event that `CCCP`
  is not supported.

  In conjunction with this, a new struct version has been added to the
  `lcb_create_st` parameters structure for use with `lcb_create`. This allows
  you to get more control over how the client is initialized:

    lcb_t instance;
    struct lcb_create_st options;
    lcb_config_transport_t enabled_transports = {
        LCB_CONFIG_TRANSPORT_CCCP,
        LCB_CONFIG_TRANSPORT_LIST_END
    };

    memset(&options, 0, sizeof(options));
    options.version = 2;
    options.v.v2.mchosts = "example.com:11210";
    options.v.v2.transports = enabled_transports;

    lcb_error_t rc = lcb_create(&instance, &options);
    if (rc != LCB_SUCCESS) {
        fprintf(stderr, "Failed to create instance: %s\n", lcb_strerror(instance, rc));
    }

  The above snippet will configure a client to _always_ use the `CCCP` protocol
  and never attempt to fall back on HTTP

  The CCCP implementation required a significant rewrite in how sockets were
  created and re-used. Particularly, a connection pooling feature was implemented.

  Additionally, the `cbc` command now has an additional `-C` option which accepts
  the preferred configuration mechanism to use.

* [major] CCBC-305: Implement logging hooks.

  This improvements adds various levels of diagnostic logging with the library
  itself. It may be utilized via the environment (by setting the `LCB_LOGLEVEL`
  environment variable to a positive integer -- the higher the number the more
  verbose the logging).

  Integrators may also use the logging API specified in `<libcouchbase/types.h>`
  to proxy the library's logging messages into your own application.

  Current events logged include connection initialization, destruction, connection
  pool management, configuration changes, and timeouts.

  By default the library is silent.

* [major] CCBC-316: Allow per-node bootstrap/config timeouts.
  This change allows more finer grained control over how long to wait per-node
  to receive updated configuration info. This setting helps adjust the initial
  and subsequent bootstrap processes to help ensure each node gets a slice of
  time.

* [major] CCBC-297: Handle spurious EWOULDBLOCK on UV/Win32
  This issue caused odd errors on Windows when large amounts of data
  would be received on the socket.

## 2.2.0 (2013-10-05)

* [major] CCBC-169 Handle 302 redirects in HTTP (views, administrative
  requests). By default the library will follow up to three redirects.
  Once the limit reached the request will be terminated with code
  `LCB_TOO_MANY_REDIRECTS`. Limit is configurable through
  `LCB_CNTL_MAX_REDIRECTS`. If set to -1, it will disable redirect
  limit.

      int new_value = 5;
      lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_MAX_REDIRECTS, &new_value);

* [major] CCBC-243 Replace isasl with cbsasl, the latter has
  implemented both PLAIN and CRAM-MD5 authentication mechanisms.

  * `LCB_CNTL_MEMDNODE_INFO` command updated to include effective
    SASL mechanism:

        cb_cntl_server_t node;
        node.versi