View Source

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

h1. Overview

The intent of the {{REPLICA READ}} (also known as {{CMD_GET_REPLICA}} in the server) operation is to allow a client to perform retrieval operations only against one or more replicas. This would be an inconsistent read. While it could be used for nearly any purpose, the only common use case is expected to be in the event of failures when a known inconsistent read is okay.


h1. Client API


h2. Java


Note: Not correct, needs updating

{code}
GetFuture resf;
boolean isReplicaRead;

try {
resf = cbc.asyncGet("foo");
isReplicaRead = false;
} catch (TimeoutException ex) {
// uhoh, something went wrong, server isn't there!
resf = cbc.asyncReplicaGet("foo");
isReplicaRead = true;
} finally {

// do something useful
}

{code}

h2. .NET

h2. PHP

h2. Ruby

{code:none}
res = nil
is_replica_read = false

begin
res = cbc.get("foo")
rescue Couchbase::Error::Timeout => ex
res = cbc.get("foo", :replica => true)
is_replica_read = true
ensure
# do something useful
end
{code}

h1. Recommended Implementation
{note}These recommendations are preliminary.{note}

When a client library is processing a request on behalf of the end user, it should generally walk the list of current replicas for the vbucket to which the given key matches.

The conversation then is something along these lines.

* Application tries to retrieve item, client library cannot service this and thus replies with an error or a timeout.
* Application then requests a replica read through a similar API as listed above.
* Client library retrieves from the current configuration a map of all nodes for the item requested. Over the course of handling this function invocation by the application, it will continue to use this sequence of primary locations and replica locations even though the map may change.
** Optionally, the client may provide a function which retrieves an array/map or other structure which contains the given item and the CAS (and optionally, the expiration) from all replicas it can contact. This would be provided as a way of allowing applications to determine what the most up-to-date version of an item may be since we are not guaranteed the replication is in the order it is present in the configuration.
* The client library will then attempt to retrieve the item from each replica in the configuration, in the specified order in the configuration until the item has been retrieved or until the list of replicas has been exhausted. Upon receiving a response from a given replica, it will then return that value to the calling application.



h2. Implementation Constraints

{{REPLICA READ}} is a binary protocol only operation. It could be implemented in ASCII, but that would require changes in moxi and additional clients.

h1. Protocol level details

See authoritative protocol documentation. This section serves only as a reference.

h2. Request

{code:none}
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0| 0x80 | 0x83 | 0x00 | 0x05 |
+----------- +----------- +----------- +----------- +
4| 0x04 | 0x00 | 0x00 | 0x00 |
+----------- +----------- +----------- +----------- +
8| 0x00 | 0x00 | 0x00 | 0x09 |
+----------- +----------- +----------- +----------- +
12| 0x00 | 0x00 | 0x00 | 0x00 |
+----------- +----------- +----------- +----------- +
16| 0x00 | 0x00 | 0x00 | 0x00 |
+----------- +----------- +----------- +----------- +
20| 0x00 | 0x00 | 0x00 | 0x00 |
+---------------+---------------+---------------+---------------+
24| 0x66 ('f') | 0x6f ('o') | 0x6f ('o') |
+---------------+---------------+---------------+

Field (offset) (value)
Magic (0) : 0x80 (PROTOCOL_BINARY_REQ)
Opcode (1) : 0x83
Key length (2,3) : 0x0003 (3)
Extra length (0) : 0x00
Data type (5) : 0x00
vbucket (6,7) : 0x0000 (0)
Total body (8-11) : 0x00000003 (3)
Opaque (12-15): 0x00000000
CAS (16-23): 0x0000000000000000
Key (24-26): The textual string "foo"

{code}

h2. Response

{code:none}
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0| 0x81 | 0x83 | 0x00 | 0x00 |
+---------------+---------------+---------------+---------------+
4| 0x04 | 0x00 | 0x00 | 0x00 |
+---------------+---------------+---------------+---------------+
8| 0x00 | 0x00 | 0x00 | 0x09 |
+---------------+---------------+---------------+---------------+
12| 0x00 | 0x00 | 0x00 | 0x00 |
+---------------+---------------+---------------+---------------+
16| 0x00 | 0x00 | 0x00 | 0x00 |
+---------------+---------------+---------------+---------------+
20| 0x00 | 0x00 | 0x00 | 0x01 |
+---------------+---------------+---------------+---------------+
24| 0xde | 0xad | 0xbe | 0xef |
+---------------+---------------+---------------+---------------+
28| 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 0x6c ('l') |
+---------------+---------------+---------------+---------------+
32| 0x64 ('d') |
+---------------+


Field (offset) (value)
Magic (0) : 0x81 (PROTOCOL_BINARY_RES)
Opcode (1) : 0x83
Key length (2,3) : 0x0000
Extra length (4) : 0x04
Data type (5) : 0x00
Status (6,7) : 0x0000
Total body (8-11) : 0x00000009
Opaque (12-15): 0x00000000
CAS (16-23): 0x0000000000000001
Extras :
Flags (24-27): 0xdeadbeef
Key : None
Value (28-32): The textual string "World"

{code}