You are viewing an old version of this page. View the current version.
Compare with Current |
View Page History
The XDCR binary protocol involves several memcached binary commands to
replicate data and metadata...
- get meta
- add with meta
- set with meta
- delete with meta
- TAP mutation
- TAP delete
There are other REST/CAPI protocol commands, too, involved in XDCR but they are not detailed in this document.
For the relevant memcached binary commands, their binary format is detailed below.
Status
Status of this document: in review (2012/07/14)
CHANGES
- 2012-07-13 - The nru field was added to the XXX-WITH-META meta
field. Additionally, compared to some unreleased developer-interim
builds, the newCAS and seqNo fields have been reversed, where newCAS
now comes before seqNo.
Set With Meta / Add With Meta / Delete With Meta
These commands (the so-called "XXX-WITH-META" commands) all follow the same layout.
High level layout...
XXX-WITH-META := header + body. header := the usual 24 byte memcached binary request header, including a header-CAS field. body := extras + key + value. extras := flag + expiration + newCAS + meta. meta := seqno + nru. flag := 32-bits. expiration := 32-bits. newCAS := 64-bits. seqno := 64-bits. nru := 8-bits.
The header-CAS field follows the usual CAS semantics. That is, the
server will successfully process an XXX-WITH-META request only if the
header-CAS matches the item's current CAS value or if the header-CAS
value is 0.
The newCAS field, in contrast, is the CAS value that the server will
accept as the item's new CAS value if the request succeeds, allowing
the client to force a server begin using a given CAS value.
When the command is DELETE-WITH-META, the flag should be 0, the
expiration should be 0, and the value should be 0 length.
The meta field is the same meta field that's also provided by the
TAP_MUTATION command. The meta field is placed at the end of the
extras field so that any new meta information in future versions can
be easily handled by existing protocol users by just treating the meta
field as a variable length field.
Example...
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 | 0xa2 | 0x00 | 0x05 |
+---------------+---------------+---------------+---------------+
4| 0x19 | 0x00 | 0x00 | 0x00 |
+---------------+---------------+---------------+---------------+
8| 0x00 | 0x00 | 0x00 | 0x25 |
+---------------+---------------+---------------+---------------+
12| 0xde | 0xad | 0xbe | 0xef |
+---------------+---------------+---------------+---------------+
16| 0x00 | 0x00 | 0x00 | 0x00 |
+---------------+---------------+---------------+---------------+
20| 0x00 | 0x00 | 0x00 | 0x00 |
+---------------+---------------+---------------+---------------+
24| 0x00 | 0x00 | 0x00 | 0x01 |
+---------------+---------------+---------------+---------------+
28| 0x00 | 0x00 | 0x00 | 0x0a |
+---------------+---------------+---------------+---------------+
32| 0xca | 0xfe | 0xba | 0xbe |
+---------------+---------------+---------------+---------------+
36| 0xde | 0xad | 0xbe | 0xef |
+---------------+---------------+---------------+---------------+
40| 0xbe | 0xef | 0xca | 0xfe |
+---------------+---------------+---------------+---------------+
44| 0xde | 0xad | 0xba | 0xbe |
+---------------+---------------+---------------+---------------+
48| 0x00 | 0x6d ('m') | 0x79 ('y') | 0x6b ('k') |
+---------------+---------------+---------------+---------------+
52| 0x65 ('e') | 0x79 ('y') | 0x6d ('m') | 0x79 ('y') |
+---------------+---------------+---------------+---------------+
56| 0x76 ('v') | 0x61 ('a') | 0x6c ('l') | 0x75 ('u') |
+---------------+---------------+---------------+---------------+
60| 0x65 ('e') |
+---------------+
set with meta command
Field (offset) (value)
Magic (0) : 0x80
Opcode (1) : 0xa2
Key length (2,3) : 0x0005
Extra length (4) : 0x19 == 25 = 4 + 4 + 8 + 8 + 1
Data type (5) : 0x00
Vbucket (6,7) : 0x0000
Total body (8-11) : 0x00000025 == 0x19 + 5 + 7 == 25 + 5 + 7
Opaque (12-15): 0xdeadbeef
CAS (16-23): 0x0000000000000000
Flags (24-27): 0x00000001
Expiration (28-31): 0x0000000a
New CAS (32-39): 0xcafebabedeadbeef
Seqno (40-47): 0xbeefcafedeadbabe
NRU (48) : 0x00
Key (49-53): mykey
Value (54-60): myvalue
The "quiet" versions of these commands have the same protocol layout.
Command Opcodes
- CMD_SET_WITH_META = 0xa2
- CMD_SETQ_WITH_META = 0xa3
- CMD_ADD_WITH_META = 0xa4
- CMD_ADDQ_WITH_META = 0xa5
- CMD_DELETE_WITH_META = 0xa8
- CMD_DELETEQ_WITH_META = 0xa9
TAP_MUTATION engine-specific / meta field.
The TAP_MUTATION binary protocol command has an engine-specific field
(also called "engine private field"). See...
http://www.couchbase.com/wiki/display/couchbase/TAP+Protocol
In 1.8, the engine private field is 0 bytes length.
In 2.0, the engine private field is equal to the meta field.
A TAP client can forward the meta field bytes from a TAP stream to
another server by using the XXX-WITH-META commaand.