The recommendations here are under development and may change before implementation.

Overview

The intent of the OBSERVE operation, as implemented by Couchbase client libraries, is to give developers the ability to observe the status of a key with respect to a specific change.  For example, a developer may want to somehow mutate a document behind the key identified by the string "foo".  Given that a Couchbase cluster is distributed and concurrent and acknowledges the request before the given document, there are situations where the application developer may want to observe whether the specific mutation they made is either:

1. safely replicated to one or more nodes within the cluster
2. persisted to the master, or persisted to one or more nodes within the cluster
3. has been taken into consideration in any indexes

Client API

Java

The Java client library, and it's dependencies, will require changes to return the CAS value through the OperationStatus object.

OperationFuture<Boolean> setResult = cbc.set("foo", 0, "bar");

if (setResult.get()) { 
  Observer watchit = new Observer(setResult.getStatus());
else {
// do something because the set failed
}

// now that the observer knows what to observe...
watchit.blockForReplication(1); // this will block

Recommended Implementation

These recommendations are preliminary, and have not been reviewed.

Given that the item being mutated may be changed at any time by another actor in a deployment, the key idea here is for the client to use the CAS value returned from the mutation operation.  Since the client library knows at all times (though, asynchronously) which node is responsible for the vbucket for a given key, and knows which nodes are slaves for that key, the client library can use stats key as a method of determining what has happened with a key on this given node.

Implementation Constraints

OBSERVE is a binary protocol only operation. It could be implemented in ASCII, but that would currently be complicated by the fact that mutation operations do not return the new CAS value in ASCII protocol. Since Couchbase Server uses binary protocol exclusively, we do not