« back to all changes in this revision
Viewing changes to doc/protocol-binary.xml
- browse files at revision 8
- compare with another revision
- download diff
- download tarball
- view history from revision 8
- Committer: Bazaar Package Importer
- Author(s): David Martínez Moreno
- Date: 2009-10-16 15:09:43 UTC
- mfrom: (1.1.6 upstream) (3.1.7 sid)
- Revision ID: james.westby@ubuntu.com-20091016150943-0rhh8x206ebgwzeu
Tags: 1.4.2-1
* New upstream release, primarily bugfixes, some of them critical, hence
the urgency:
- Reject keys larger than 250 bytes in the binary protocol.
- Bounds checking on stats cachedump.
- Binary protocol set+cas wasn't returning a new cas ID.
- Binary quitq didn't actually close the connection
- Slab boundary checking cleanup (bad logic in unreachable code)
- Get hit memory optimizations
- Disallow -t options that cause the server to not work
- Killed off incomplete slab rebalance feature.
* debian/patches:
- 01_init_script_compliant_with_LSB.patch: Remade as upstream applied a
whitespace cleanup script that broke the patch.
- 02_manpage_additions.patch: Added missing parameters to the memcached
manpage.
* Removed TODO from debian/docs.
the urgency:
- Reject keys larger than 250 bytes in the binary protocol.
- Bounds checking on stats cachedump.
- Binary protocol set+cas wasn't returning a new cas ID.
- Binary quitq didn't actually close the connection
- Slab boundary checking cleanup (bad logic in unreachable code)
- Get hit memory optimizations
- Disallow -t options that cause the server to not work
- Killed off incomplete slab rebalance feature.
* debian/patches:
- 01_init_script_compliant_with_LSB.patch: Remade as upstream applied a
whitespace cleanup script that broke the patch.
- 02_manpage_additions.patch: Added missing parameters to the memcached
manpage.
* Removed TODO from debian/docs.
added
removed
doc/protocol-binary.xml
1
<?xml version="1.0" encoding="US-ASCII"?>
2
<!DOCTYPE rfc SYSTEM "xml2rfc/rfc2629.dtd">
3
<?xml-stylesheet type='text/xsl' href='xml2rfc/rfc2629.xslt'?>
4
<?rfc toc="yes"?>
5
<?rfc strict="yes"?>
6
<?rfc symrefs="yes"?>
7
<?rfc sortrefs="yes" ?>
8
<?rfc compact="yes" ?>
9
<?rfc subcompact="yes" ?>
10
<rfc category="info" docName="draft-stone-memcache-binary-01" ipr="none">
11
<front>
12
<title> Memcache Binary Protocol </title>
13
14
<author fullname="Aaron Stone" surname="Stone" role="editor">
15
<organization>Six Apart, Ltd.</organization>
16
<address>
17
<postal>
18
<street>548 4th Street</street>
19
<city>San Francisco</city>
20
<region>CA</region>
21
<code>94107</code>
22
<country>USA</country>
23
</postal>
24
<email>aaron@serendipity.palo-alto.ca.us</email>
25
</address>
26
</author>
27
<author fullname="Trond Norbye" surname="Norbye" role="editor">
28
<organization>Sun Microsystems, INC</organization>
29
<address>
30
<postal>
31
<street>Haakon VII g. 7B</street>
32
<city>Trondheim</city>
33
<code>NO-7485 Trondheim</code>
34
<country>Norway</country>
35
</postal>
36
<email>trond.norbye@sun.com</email>
37
</address>
38
</author>
39
<date day="28" month="August" year="2008" />
40
<area>Applications</area>
41
<keyword>memcache memcached cache</keyword>
42
<abstract>
43
<t>
44
This memo explains the memcache binary protocol for informational
45
purposes.
46
</t>
47
<t>
48
Memcache is a high performance key-value cache. It is intentionally a
49
dumb cache, optimized for speed only. Applications using memcache do
50
not rely on it for data -- a persistent database with guaranteed
51
reliability is strongly recommended -- but applications can run much
52
faster when cached data is available in memcache.
53
</t>
54
</abstract>
55
</front>
56
57
<middle>
58
<section anchor="introduction" title="Introduction">
59
<t>
60
Memcache is a high performance key-value cache. It is intentionally a
61
dumb cache, optimized for speed only. Applications using memcache should
62
not rely on it for data -- a persistent database with guaranteed
63
reliability is strongly recommended -- but applications can run much
64
faster when cached data is available in memcache.
65
</t>
66
<t>
67
Memcache was originally written to make
68
<xref target="LJ">LiveJournal</xref> faster. It now powers all of
69
the fastest web sites that you love.
70
</t>
71
<section anchor="conventions" title="Conventions Used In This Document">
72
<t>
73
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
74
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
75
document are to be interpreted as described in
76
<xref target="KEYWORDS"/>.
77
</t>
78
</section>
79
</section>
80
81
<section anchor="packet" title="Packet Structure">
82
<figure>
83
<preamble>General format of a packet:</preamble>
84
<artwork>
85
Byte/ 0 | 1 | 2 | 3 |
86
/ | | | |
87
|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|
88
+---------------+---------------+---------------+---------------+
89
0/ HEADER /
90
/ /
91
/ /
92
/ /
93
+---------------+---------------+---------------+---------------+
94
24/ COMMAND-SPECIFIC EXTRAS (as needed) /
95
+/ (note length in the extras length header field) /
96
+---------------+---------------+---------------+---------------+
97
m/ Key (as needed) /
98
+/ (note length in key length header field) /
99
+---------------+---------------+---------------+---------------+
100
n/ Value (as needed) /
101
+/ (note length is total body length header field, minus /
102
+/ sum of the extras and key length body fields) /
103
+---------------+---------------+---------------+---------------+
104
Total 24 bytes
105
</artwork>
106
</figure>
107
108
<figure>
109
<preamble>Request header:</preamble>
110
<artwork>
111
Byte/ 0 | 1 | 2 | 3 |
112
/ | | | |
113
|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|
114
+---------------+---------------+---------------+---------------+
115
0| Magic | Opcode | Key length |
116
+---------------+---------------+---------------+---------------+
117
4| Extras length | Data type | Reserved |
118
+---------------+---------------+---------------+---------------+
119
8| Total body length |
120
+---------------+---------------+---------------+---------------+
121
12| Opaque |
122
+---------------+---------------+---------------+---------------+
123
16| CAS |
124
| |
125
+---------------+---------------+---------------+---------------+
126
Total 24 bytes
127
</artwork>
128
</figure>
129
130
<figure>
131
<preamble>Response header:</preamble>
132
<artwork>
133
Byte/ 0 | 1 | 2 | 3 |
134
/ | | | |
135
|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|
136
+---------------+---------------+---------------+---------------+
137
0| Magic | Opcode | Key Length |
138
+---------------+---------------+---------------+---------------+
139
4| Extras length | Data type | Status |
140
+---------------+---------------+---------------+---------------+
141
8| Total body length |
142
+---------------+---------------+---------------+---------------+
143
12| Opaque |
144
+---------------+---------------+---------------+---------------+
145
16| CAS |
146
| |
147
+---------------+---------------+---------------+---------------+
148
Total 24 bytes
149
</artwork>
150
</figure>
151
152
<t>
153
Header fields:
154
<list hangIndent="20" style="hanging">
155
<t hangText="Magic">Magic number.</t>
156
<t hangText="Opcode">Command code.</t>
157
<t hangText="Key length">Length in bytes of the text key that follows the command extras.</t>
158
<t hangText="Status">Status of the response (non-zero on error).</t>
159
<t hangText="Extras length">Length in bytes of the command extras.</t>
160
<t hangText="Data type">Reserved for future use (Sean is using this soon).</t>
161
<t hangText="Reserved">Really reserved for future use (up for grabs).</t>
162
<t hangText="Total body length">Length in bytes of extra + key + value.</t>
163
<t hangText="Opaque">Will be copied back to you in the response.</t>
164
<t hangText="CAS">Data version check.</t>
165
</list>
166
</t>
167
</section>
168
169
<section anchor="values" title="Defined Values">
170
<section anchor="value-magic" title="Magic Byte">
171
<t>
172
<list hangIndent="8" style="hanging">
173
<t hangText="0x80">Request packet for this protocol version</t>
174
<t hangText="0x81">Response packet for this protocol version</t>
175
</list>
176
</t>
177
178
<t>
179
Magic byte / version. For each version of the protocol, we'll use a
180
different request/response value pair. This is useful for protocol
181
analyzers to distinguish the nature of the packet from the direction
182
which it is moving. Note, it is common to run a memcached instance on
183
a host that also runs an application server. Such a host will both
184
send and receive memcache packets.
185
</t>
186
187
<t>
188
The version should hopefully correspond only to different meanings of
189
the command byte. In an ideal world, we will not change the header
190
format. As reserved bytes are given defined meaning, the protocol
191
version / magic byte values should be incremented.
192
</t>
193
194
<t>
195
Traffic analysis tools are encouraged to identify memcache packets
196
and provide detailed interpretation if the magic bytes are recognized
197
and otherwise to provide a generic breakdown of the packet. Note, that
198
the key and value positions can always be identified even if the magic
199
byte or command opcode are not recognized.
200
</t>
201
</section>
202
203
<section anchor="value-status" title="Response Status">
204
<t>
205
Possible values of this two-byte field:
206
<list hangIndent="8" style="hanging">
207
<t hangText="0x0000">No error</t>
208
<t hangText="0x0001">Key not found</t>
209
<t hangText="0x0002">Key exists</t>
210
<t hangText="0x0003">Value too large</t>
211
<t hangText="0x0004">Invalid arguments</t>
212
<t hangText="0x0005">Item not stored</t>
213
<t hangText="0x0006">Incr/Decr on non-numeric value.</t>
214
<t hangText="0x0081">Unknown command</t>
215
<t hangText="0x0082">Out of memory</t>
216
</list>
217
</t>
218
</section>
219
220
<section anchor="value-opcodes" title="Command Opcodes">
221
<t>
222
Possible values of the one-byte field:
223
<list hangIndent="8" style="hanging">
224
<t hangText="0x00">Get</t>
225
<t hangText="0x01">Set</t>
226
<t hangText="0x02">Add</t>
227
<t hangText="0x03">Replace</t>
228
<t hangText="0x04">Delete</t>
229
<t hangText="0x05">Increment</t>
230
<t hangText="0x06">Decrement</t>
231
<t hangText="0x07">Quit</t>
232
<t hangText="0x08">Flush</t>
233
<t hangText="0x09">GetQ</t>
234
<t hangText="0x0A">No-op</t>
235
<t hangText="0x0B">Version</t>
236
<t hangText="0x0C">GetK</t>
237
<t hangText="0x0D">GetKQ</t>
238
<t hangText="0x0E">Append</t>
239
<t hangText="0x0F">Prepend</t>
240
<t hangText="0x10">Stat</t>
241
<t hangText="0x11">SetQ</t>
242
<t hangText="0x12">AddQ</t>
243
<t hangText="0x13">ReplaceQ</t>
244
<t hangText="0x14">DeleteQ</t>
245
<t hangText="0x15">IncrementQ</t>
246
<t hangText="0x16">DecrementQ</t>
247
<t hangText="0x17">QuitQ</t>
248
<t hangText="0x18">FlushQ</t>
249
<t hangText="0x19">AppendQ</t>
250
<t hangText="0x1A">PrependQ</t>
251
</list>
252
</t>
253
<t>
254
As a convention all of the commands ending with "Q" for
255
Quiet. A quiet version of a command will omit responses
256
that are considered uninteresting. Whether a given response
257
is interesting is dependent upon the command. See the
258
descriptions of the
259
<xref target="command-get">set commands</xref>
260
and <xref target="command-set">set commands</xref> for
261
examples of commands that include quiet variants.
262
</t>
263
</section>
264
265
<section anchor="value-types" title="Data Types">
266
<t>
267
Possible values of the one-byte field:
268
<list hangIndent="8" style="hanging">
269
<t hangText="0x00">Raw bytes</t>
270
</list>
271
</t>
272
</section>
273
</section>
274
275
<section title="Commands">
276
<section anchor="command-introduction" title="Introduction">
277
<t>
278
All communication is initiated by a request from the client,
279
and the server will respond to each request with zero or
280
multiple packets for each request. If the status code of a response
281
packet is non-nil, the body of the packet will contain a textual error
282
message. If the status code is nil, the command opcode will define the
283
layout of the body of the message.
284
</t>
285
<section anchor="command-introduction-example" title="Example">
286
<t>
287
The following figure illustrates the packet layout for
288
a packet with an error message.
289
</t>
290
<figure>
291
<preamble>Packet layout:</preamble>
292
<artwork>
293
294
Byte/ 0 | 1 | 2 | 3 |
295
/ | | | |
296
|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|
297
+---------------+---------------+---------------+---------------+
298
0| 0x81 | 0x00 | 0x00 | 0x00 |
299
+---------------+---------------+---------------+---------------+
300
4| 0x00 | 0x00 | 0x00 | 0x01 |
301
+---------------+---------------+---------------+---------------+
302
8| 0x00 | 0x00 | 0x00 | 0x09 |
303
+---------------+---------------+---------------+---------------+
304
12| 0x00 | 0x00 | 0x00 | 0x00 |
305
+---------------+---------------+---------------+---------------+
306
16| 0x00 | 0x00 | 0x00 | 0x00 |
307
+---------------+---------------+---------------+---------------+
308
20| 0x00 | 0x00 | 0x00 | 0x00 |
309
+---------------+---------------+---------------+---------------+
310
24| 0x4e ('N') | 0x6f ('o') | 0x74 ('t') | 0x20 (' ') |
311
+---------------+---------------+---------------+---------------+
312
28| 0x66 ('f') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') |
313
+---------------+---------------+---------------+---------------+
314
32| 0x64 ('d') |
315
+---------------+
316
Total 33 bytes (24 byte header, and 9 bytes value)
317
318
Field (offset) (value)
319
Magic (0) : 0x81
320
Opcode (1) : 0x00
321
Key length (2,3) : 0x0000
322
Extra length (4) : 0x00
323
Data type (5) : 0x00
324
Status (6,7) : 0x0001
325
Total body (8-11) : 0x00000009
326
Opaque (12-15): 0x00000000
327
CAS (16-23): 0x0000000000000000
328
Extras : None
329
Key : None
330
Value (24-32): The textual string "Not found"
331
</artwork>
332
</figure>
333
</section>
334
</section>
335
336
<section anchor="command-get" title="Get, Get Quietly, Get Key, Get Key Quietly">
337
<t>
338
Request:
339
</t>
340
<t>
341
<list style="empty">
342
<t>MUST NOT have extras.</t>
343
<t>MUST have key.</t>
344
<t>MUST NOT have value.</t>
345
</list>
346
</t>
347
348
<t>
349
<list style="symbols">
350
<t>4 byte flags</t>
351
</list>
352
</t>
353
354
<t>
355
Response (if found):
356
</t>
357
<t>
358
<list style="empty">
359
<t>MUST have extras.</t>
360
<t>MAY have key.</t>
361
<t>MAY have value.</t>
362
</list>
363
</t>
364
365
<t>
366
<list style="symbols">
367
<t>4 byte flags</t>
368
</list>
369
</t>
370
371
<t>
372
<figure>
373
<preamble>Extra data for the get commands:</preamble>
374
<artwork>
375
Byte/ 0 | 1 | 2 | 3 |
376
/ | | | |
377
|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|
378
+---------------+---------------+---------------+---------------+
379
0| Flags |
380
+---------------+---------------+---------------+---------------+
381
382
Total 4 bytes
383
</artwork>
384
</figure>
385
</t>
386
387
<t>
388
The get command gets a single key. The getq command is both mum
389
on cache miss and quiet, holding its response until a non-quiet
390
command is issued. Getk and getkq differs from get and getq by
391
adding the key into the response packet.
392
</t>
393
394
<t>
395
You're not guaranteed a response to a getq/getkq cache hit until
396
you send a non-getq/getkq command later, which uncorks the
397
server and bundles up IOs to send to the client in one go.
398
</t>
399
400
<t>
401
Clients should implement multi-get (still important for
402
reducing network roundtrips!) as n pipelined requests, the
403
first n-1 being getq/getkq, the last being a regular
404
get/getk. That way you're guaranteed to get a response, and
405
you know when the server's done. You can also do the naive
406
thing and send n pipelined get/getks, but then you could potentially
407
get back a lot of "NOT_FOUND" error code packets.
408
Alternatively, you can send 'n' getq/getkqs, followed by a
409
'noop' command.
410
</t>
411
412
<section anchor="command-get-example" title="Example">
413
<t>
414
To request the data associated with the key "Hello" the
415
following fields must be specified in the packet.
416
</t>
417
<figure>
418
<preamble>get request:</preamble>
419
<artwork>
420
Byte/ 0 | 1 | 2 | 3 |
421
/ | | | |
422
|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|
423
+---------------+---------------+---------------+---------------+
424
0| 0x80 | 0x00 | 0x00 | 0x05 |
425
+---------------+---------------+---------------+---------------+
426
4| 0x00 | 0x00 | 0x00 | 0x00 |
427
+---------------+---------------+---------------+---------------+
428
8| 0x00 | 0x00 | 0x00 | 0x05 |
429
+---------------+---------------+---------------+---------------+
430
12| 0x00 | 0x00 | 0x00 | 0x00 |
431
+---------------+---------------+---------------+---------------+
432
16| 0x00 | 0x00 | 0x00 | 0x00 |
433
+---------------+---------------+---------------+---------------+
434
20| 0x00 | 0x00 | 0x00 | 0x00 |
435
+---------------+---------------+---------------+---------------+
436
24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') |
437
+---------------+---------------+---------------+---------------+
438
28| 0x6f ('o') |
439
+---------------+
440
441
Total 29 bytes (24 byte header, and 5 bytes key)
442
443
Field (offset) (value)
444
Magic (0) : 0x80
445
Opcode (1) : 0x00
446
Key length (2,3) : 0x0005
447
Extra length (4) : 0x00
448
Data type (5) : 0x00
449
Reserved (6,7) : 0x0000
450
Total body (8-11) : 0x00000005
451
Opaque (12-15): 0x00000000
452
CAS (16-23): 0x0000000000000000
453
Extras : None
454
Key (24-29): The textual string: "Hello"
455
Value : None
456
</artwork>
457
</figure>
458
<t>If the item exist on the server the following packet is returned,
459
otherwise a packet with status code != 0 will be returned (see
460
<xref target="command-introduction">Introduction</xref>)
461
</t>
462
<figure>
463
<preamble>get/getq response:</preamble>
464
<artwork>
465
466
Byte/ 0 | 1 | 2 | 3 |
467
/ | | | |
468
|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|
469
+---------------+---------------+---------------+---------------+
470
0| 0x81 | 0x00 | 0x00 | 0x00 |
471
+---------------+---------------+---------------+---------------+
472
4| 0x04 | 0x00 | 0x00 | 0x00 |
473
+---------------+---------------+---------------+---------------+
474
8| 0x00 | 0x00 | 0x00 | 0x09 |
475
+---------------+---------------+---------------+---------------+
476
12| 0x00 | 0x00 | 0x00 | 0x00 |
477
+---------------+---------------+---------------+---------------+
478
16| 0x00 | 0x00 | 0x00 | 0x00 |
479
+---------------+---------------+---------------+---------------+
480
20| 0x00 | 0x00 | 0x00 | 0x01 |
481
+---------------+---------------+---------------+---------------+
482
24| 0xde | 0xad | 0xbe | 0xef |
483
+---------------+---------------+---------------+---------------+
484
28| 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 0x6c ('l') |
485
+---------------+---------------+---------------+---------------+
486
32| 0x64 ('d') |
487
+---------------+
488
489
Total 33 bytes (24 byte header, 4 byte extras and 5 byte value)
490
491
Field (offset) (value)
492
Magic (0) : 0x81
493
Opcode (1) : 0x00
494
Key length (2,3) : 0x0000
495
Extra length (4) : 0x04
496
Data type (5) : 0x00
497
Status (6,7) : 0x0000
498
Total body (8-11) : 0x00000009
499
Opaque (12-15): 0x00000000
500
CAS (16-23): 0x0000000000000001
501
Extras :
502
Flags (24-27): 0xdeadbeef
503
Key : None
504
Value (28-32): The textual string "World"
505
</artwork>
506
</figure>
507
<figure>
508
<preamble>getk/getkq response:</preamble>
509
<artwork>
510
511
Byte/ 0 | 1 | 2 | 3 |
512
/ | | | |
513
|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|
514
+---------------+---------------+---------------+---------------+
515
0| 0x81 | 0x00 | 0x00 | 0x05 |
516
+---------------+---------------+---------------+---------------+
517
4| 0x04 | 0x00 | 0x00 | 0x00 |
518
+---------------+---------------+---------------+---------------+
519
8| 0x00 | 0x00 | 0x00 | 0x09 |
520
+---------------+---------------+---------------+---------------+
521
12| 0x00 | 0x00 | 0x00 | 0x00 |
522
+---------------+---------------+---------------+---------------+
523
16| 0x00 | 0x00 | 0x00 | 0x00 |
524
+---------------+---------------+---------------+---------------+
525
20| 0x00 | 0x00 | 0x00 | 0x01 |
526
+---------------+---------------+---------------+---------------+
527
24| 0xde | 0xad | 0xbe | 0xef |
528
+---------------+---------------+---------------+---------------+
529
28| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') |
530
+---------------+---------------+---------------+---------------+
531
32| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') |
532
+---------------+---------------+---------------+---------------+
533
36| 0x6c ('l') | 0x64 ('d') |
534
+---------------+---------------+
535
536
Total 38 bytes (24 byte header, 4 byte extras, 5 byte key
537
and 5 byte value)
538
539
Field (offset) (value)
540
Magic (0) : 0x81
541
Opcode (1) : 0x00
542
Key length (2,3) : 0x0005
543
Extra length (4) : 0x04
544
Data type (5) : 0x00
545
Status (6,7) : 0x0000
546
Total body (8-11) : 0x00000009
547
Opaque (12-15): 0x00000000
548
CAS (16-23): 0x0000000000000001
549
Extras :
550
Flags (24-27): 0xdeadbeef
551
Key (28-32): The textual string: "Hello"
552
Value (33-37): The textual string: "World"
553
</artwork>
554
</figure>
555
</section>
556
</section>
557
558
<section anchor="command-set" title="Set, Add, Replace">
559
<t>
560
<list style="empty">
561
<t>MUST have extras.</t>
562
<t>MUST have key.</t>
563
<t>MUST have value.</t>
564
</list>
565
</t>
566
567
<t>
568
<list style="symbols">
569
<t>4 byte flags</t>
570
<t>4 byte expiration time</t>
571
</list>
572
</t>
573
574
<figure>
575
<preamble>Extra data for set/add/replace:</preamble>
576
<artwork>
577
Byte/ 0 | 1 | 2 | 3 |
578
/ | | | |
579
|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|
580
+---------------+---------------+---------------+---------------+
581
0| Flags |
582
+---------------+---------------+---------------+---------------+
583
4| Expiration |
584
+---------------+---------------+---------------+---------------+
585
Total 8 bytes
586
</artwork>
587
</figure>
588
589
<t>
590
If the Data Version Check (CAS) is nonzero, the requested
591
operation MUST only succeed if the item exists and has a CAS value
592
identical to the provided value.
593
</t>
594
595
<t>
596
Add MUST fail if the item already exist.
597
</t>
598
599
<t>
600
Replace MUST fail if the item doesn't exist.
601
</t>
602
603
<t>
604
Set should store the data unconditionally if the item exists
605
or not.
606
</t>
607
608
<t>
609
Quiet mutations only return responses on failure. Success
610
is considered the general case and is suppressed when in
611
quiet mode, but errors should not be allowed to go
612
unnoticed.
613
</t>
614
615
<section anchor="command-set-example" title="Example">
616
<t>The following figure shows an add-command for
617
<list style="empty">
618
<t>Key: "Hello"</t>
619
<t>Value: "World"</t>
620
<t>Flags: 0xdeadbeef</t>
621
<t>Expiry: in two hours</t>
622
</list>
623
</t>
624
<figure>
625
<preamble>Add request:</preamble>
626
<artwork>
627
628
Byte/ 0 | 1 | 2 | 3 |
629
/ | | | |
630
|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|
631
+---------------+---------------+---------------+---------------+
632
0| 0x80 | 0x02 | 0x00 | 0x05 |
633
+---------------+---------------+---------------+---------------+
634
4| 0x08 | 0x00 | 0x00 | 0x00 |
635
+---------------+---------------+---------------+---------------+
636
8| 0x00 | 0x00 | 0x00 | 0x12 |
637
+---------------+---------------+---------------+---------------+
638
12| 0x00 | 0x00 | 0x00 | 0x00 |
639
+---------------+---------------+---------------+---------------+
640
16| 0x00 | 0x00 | 0x00 | 0x00 |
641
+---------------+---------------+---------------+---------------+
642
20| 0x00 | 0x00 | 0x00 | 0x00 |
643
+---------------+---------------+---------------+---------------+
644
24| 0xde | 0xad | 0xbe | 0xef |
645
+---------------+---------------+---------------+---------------+
646
28| 0x00 | 0x00 | 0x0e | 0x10 |
647
+---------------+---------------+---------------+---------------+
648
32| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') |
649
+---------------+---------------+---------------+---------------+
650
36| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') |
651
+---------------+---------------+---------------+---------------+
652
40| 0x6c ('l') | 0x64 ('d') |
653
+---------------+---------------+
654
655
Total 42 bytes (24 byte header, 8 byte extras, 5 byte key and
656
5 byte value)
657
658
Field (offset) (value)
659
Magic (0) : 0x80
660
Opcode (1) : 0x02
661
Key length (2,3) : 0x0005
662
Extra length (4) : 0x08
663
Data type (5) : 0x00
664
Reserved (6,7) : 0x0000
665
Total body (8-11) : 0x00000012
666
Opaque (12-15): 0x00000000
667
CAS (16-23): 0x0000000000000000
668
Extras :
669
Flags (24-27): 0xdeadbeef
670
Expiry (28-31): 0x00000e10
671
Key (32-36): The textual string "Hello"
672
Value (37-41): The textual string "World"
673
</artwork>
674
</figure>
675
<t>
676
The response-packet contains no extra data, and the result of the
677
operation is signaled through the status code. If the command
678
succeeds, the CAS value for the item is returned in the CAS-field
679
of the packet.
680
</t>
681
<figure>
682
<preamble>Successful add response:</preamble>
683
<artwork>
684
685
Byte/ 0 | 1 | 2 | 3 |
686
/ | | | |
687
|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|
688
+---------------+---------------+---------------+---------------+
689
0| 0x81 | 0x02 | 0x00 | 0x00 |
690
+---------------+---------------+---------------+---------------+
691
4| 0x00 | 0x00 | 0x00 | 0x00 |
692
+---------------+---------------+---------------+---------------+
693
8| 0x00 | 0x00 | 0x00 | 0x00 |
694
+---------------+---------------+---------------+---------------+
695
12| 0x00 | 0x00 | 0x00 | 0x00 |
696
+---------------+---------------+---------------+---------------+
697
16| 0x00 | 0x00 | 0x00 | 0x00 |
698
+---------------+---------------+---------------+---------------+
699
20| 0x00 | 0x00 | 0x00 | 0x01 |
700
+---------------+---------------+---------------+---------------+
701
702
Total 24 bytes
703
704
Field (offset) (value)
705
Magic (0) : 0x81
706
Opcode (1) : 0x02
707
Key length (2,3) : 0x0000
708
Extra length (4) : 0x00
709
Data type (5) : 0x00
710
Status (6,7) : 0x0000
711
Total body (8-11) : 0x00000000
712
Opaque (12-15): 0x00000000
713
CAS (16-23): 0x0000000000000001
714
Extras : None
715
Key : None
716
Value : None
717
</artwork>
718
</figure>
719
</section>
720
</section>
721
722
<section anchor="command-delete" title="Delete">
723
<t>
724
<list style="empty">
725
<t>MUST NOT have extras.</t>
726
<t>MUST have key.</t>
727
<t>MUST NOT have value.</t>
728
</list>
729
</t>
730
731
<t>
732
Delete the item with the specific key.
733
</t>
734
735
<section anchor="command-delete-example" title="Example">
736
<t>The following figure shows a delete message for the
737
item "Hello".</t>
738
<figure>
739
<preamble>Delete request:</preamble>
740
<artwork>
741
Byte/ 0 | 1 | 2 | 3 |
742
/ | | | |
743
|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|
744
+---------------+---------------+---------------+---------------+
745
0| 0x80 | 0x04 | 0x00 | 0x05 |
746
+---------------+---------------+---------------+---------------+
747
4| 0x00 | 0x00 | 0x00 | 0x00 |
748
+---------------+---------------+---------------+---------------+
749
8| 0x00 | 0x00 | 0x00 | 0x05 |
750
+---------------+---------------+---------------+---------------+
751
12| 0x00 | 0x00 | 0x00 | 0x00 |
752
+---------------+---------------+---------------+---------------+
753
16| 0x00 | 0x00 | 0x00 | 0x00 |
754
+---------------+---------------+---------------+---------------+
755
20| 0x00 | 0x00 | 0x00 | 0x00 |
756
+---------------+---------------+---------------+---------------+
757
24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') |
758
+---------------+---------------+---------------+---------------+
759
28| 0x6f ('o') |
760
+---------------+
761
762
Total 29 bytes (24 byte header, 5 byte value)
763
764
Field (offset) (value)
765
Magic (0) : 0x80
766
Opcode (1) : 0x04
767
Key length (2,3) : 0x0005
768
Extra length (4) : 0x00
769
Data type (5) : 0x00
770
Reserved (6,7) : 0x0000
771
Total body (8-11) : 0x00000005
772
Opaque (12-15): 0x00000000
773
CAS (16-23): 0x0000000000000000
774
Extras : None
775
Key : The textual string "Hello"
776
Value : None
777
</artwork>
778
</figure>
779
<t>
780
The response-packet contains no extra data, and the result of the
781
operation is signaled through the status code.
782
</t>
783
</section>
784
</section>
785
786
<section anchor="command-incr" title="Increment, Decrement">
787
<t>
788
<list style="empty">
789
<t>MUST have extras.</t>
790
<t>MUST have key.</t>
791
<t>MUST NOT have value.</t>
792
</list>
793
</t>
794
795
<t>
796
<list style="symbols">
797
<t>8 byte value to add / subtract</t>
798
<t>8 byte initial value (unsigned)</t>
799
<t>4 byte expiration time</t>
800
</list>
801
</t>
802
<figure>
803
<preamble>Extra data for incr/decr:</preamble>
804
<artwork>
805
Byte/ 0 | 1 | 2 | 3 |
806
/ | | | |
807
|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|
808
+---------------+---------------+---------------+---------------+
809
0| Amount to add |
810
| |
811
+---------------+---------------+---------------+---------------+
812
8| Initial value |
813
| |
814
+---------------+---------------+---------------+---------------+
815
16| Expiration |
816
+---------------+---------------+---------------+---------------+
817
Total 20 bytes
818
</artwork>
819
</figure>
820
821
<t>
822
These commands will either add or remove the specified
823
amount to the requested counter.
824
</t>
825
<t>
826
If the counter does not exist, one of two things may happen:
827
</t>
828
<t>
829
<list style="numbers">
830
<t>If the expiration value is all one-bits (0xffffffff), the
831
operation will fail with NOT_FOUND.</t>
832
<t>For all other expiration values, the operation will succeed
833
by seeding the value for this key with the provided initial
834
value to expire with the provided expiration time. The flags
835
will be set to zero.</t>
836
</list>
837
</t>
838
<figure>
839
<preamble>incr/decr response body:</preamble>
840
<artwork>
841
Byte/ 0 | 1 | 2 | 3 |
842
/ | | | |
843
|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|
844
+---------------+---------------+---------------+---------------+
845
0| 64-bit unsigned response. |
846
| |
847
+---------------+---------------+---------------+---------------+
848
Total 8 bytes
849
</artwork>
850
</figure>
851
<section anchor="command-incr-example" title="Example">
852
<t>The following figure shows an incr-command for
853
<list style="empty">
854
<t>Key: "counter"</t>
855
<t>Delta: 0x01</t>
856
<t>Initial: 0x00</t>
857
<t>Expiry: in two hours</t>
858
</list>
859
</t>
860
<figure>
861
<preamble>Increment request:</preamble>
862
<artwork>
863
864
Byte/ 0 | 1 | 2 | 3 |
865
/ | | | |
866
|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|
867
+---------------+---------------+---------------+---------------+
868
0| 0x80 | 0x05 | 0x00 | 0x07 |
869
+---------------+---------------+---------------+---------------+
870
4| 0x14 | 0x00 | 0x00 | 0x00 |
871
+---------------+---------------+---------------+---------------+
872
8| 0x00 | 0x00 | 0x00 | 0x1b |
873
+---------------+---------------+---------------+---------------+
874
12| 0x00 | 0x00 | 0x00 | 0x00 |
875
+---------------+---------------+---------------+---------------+
876
16| 0x00 | 0x00 | 0x00 | 0x00 |
877
+---------------+---------------+---------------+---------------+
878
20| 0x00 | 0x00 | 0x00 | 0x00 |
879
+---------------+---------------+---------------+---------------+
880
24| 0x00 | 0x00 | 0x00 | 0x00 |
881
+---------------+---------------+---------------+---------------+
882
28| 0x00 | 0x00 | 0x00 | 0x01 |
883
+---------------+---------------+---------------+---------------+
884
32| 0x00 | 0x00 | 0x00 | 0x00 |
885
+---------------+---------------+---------------+---------------+
886
36| 0x00 | 0x00 | 0x00 | 0x00 |
887
+---------------+---------------+---------------+---------------+
888
40| 0x00 | 0x00 | 0x0e | 0x10 |
889
+---------------+---------------+---------------+---------------+
890
44| 0x63 ('c') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') |
891
+---------------+---------------+---------------+---------------+
892
48| 0x74 ('t') | 0x65 ('e') | 0x72 ('r') |
893
+---------------+---------------+---------------+
894
Total 51 bytes (24 byte header, 20 byte extras, 7 byte key)
895
896
Field (offset) (value)
897
Magic (0) : 0x80
898
Opcode (1) : 0x05
899
Key length (2,3) : 0x0007
900
Extra length (4) : 0x14
901
Data type (5) : 0x00
902
Reserved (6,7) : 0x0000
903
Total body (8-11) : 0x0000001b
904
Opaque (12-15): 0x00000000
905
CAS (16-23): 0x0000000000000000
906
Extras :
907
delta (24-31): 0x0000000000000001
908
initial (32-39): 0x0000000000000000
909
exipration (40-43): 0x00000e10
910
Key : Textual string "counter"
911
Value : None
912
</artwork>
913
</figure>
914
<t>
915
If the key doesn't exist, the server will respond with the
916
initial value. If not the incremented value will be returned.
917
Let's assume that the key didn't exist, so the initial value
918
is returned.
919
</t>
920
<figure>
921
<preamble>Increment response:</preamble>
922
<artwork>
923
Byte/ 0 | 1 | 2 | 3 |
924
/ | | | |
925
|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|
926
+---------------+---------------+---------------+---------------+
927
0| 0x81 | 0x05 | 0x00 | 0x00 |
928
+---------------+---------------+---------------+---------------+
929
4| 0x00 | 0x00 | 0x00 | 0x00 |
930
+---------------+---------------+---------------+---------------+
931
8| 0x00 | 0x00 | 0x00 | 0x08 |
932
+---------------+---------------+---------------+---------------+
933
12| 0x00 | 0x00 | 0x00 | 0x00 |
934
+---------------+---------------+---------------+---------------+
935
16| 0x00 | 0x00 | 0x00 | 0x00 |
936
+---------------+---------------+---------------+---------------+
937
20| 0x00 | 0x00 | 0x00 | 0x05 |
938
+---------------+---------------+---------------+---------------+
939
24| 0x00 | 0x00 | 0x00 | 0x00 |
940
+---------------+---------------+---------------+---------------+
941
28| 0x00 | 0x00 | 0x00 | 0x00 |
942
+---------------+---------------+---------------+---------------+
943
Total 32 bytes (24 byte header, 8 byte value)
944
945
Field (offset) (value)
946
Magic (0) : 0x81
947
Opcode (1) : 0x05
948
Key length (2,3) : 0x0000
949
Extra length (4) : 0x00
950
Data type (5) : 0x00
951
Status (6,7) : 0x0000
952
Total body (8-11) : 0x00000008
953
Opaque (12-15): 0x00000000
954
CAS (16-23): 0x0000000000000005
955
Extras : None
956
Key : None
957
Value : 0x0000000000000000
958
</artwork>
959
</figure>
960
</section>
961
</section>
962
963
<section anchor="command-quit" title="quit">
964
<t>
965
<list style="empty">
966
<t>MUST NOT have extras.</t>
967
<t>MUST NOT have key.</t>
968
<t>MUST NOT have value.</t>
969
</list>
970
</t>
971
972
<t>
973
Close the connection to the server.
974
</t>
975
976
<section anchor="command-quit-example" title="Example">
977
<figure>
978
<preamble>Quit request:</preamble>
979
<artwork>
980
Byte/ 0 | 1 | 2 | 3 |
981
/ | | | |
982
|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|
983
+---------------+---------------+---------------+---------------+
984
0| 0x80 | 0x07 | 0x00 | 0x00 |
985
+---------------+---------------+---------------+---------------+
986
4| 0x00 | 0x00 | 0x00 | 0x00 |
987
+---------------+---------------+---------------+---------------+
988
8| 0x00 | 0x00 | 0x00 | 0x00 |
989
+---------------+---------------+---------------+---------------+
990
12| 0x00 | 0x00 | 0x00 | 0x00 |
991
+---------------+---------------+---------------+---------------+
992
16| 0x00 | 0x00 | 0x00 | 0x00 |
993
+---------------+---------------+---------------+---------------+
994
20| 0x00 | 0x00 | 0x00 | 0x00 |
995
+---------------+---------------+---------------+---------------+
996
Total 24 bytes
997
998
Field (offset) (value)
999
Magic (0) : 0x80
1000
Opcode (1) : 0x07
1001
Key length (2,3) : 0x0000
1002
Extra length (4) : 0x00
1003
Data type (5) : 0x00
1004
Reserved (6,7) : 0x0000
1005
Total body (8-11) : 0x00000000
1006
Opaque (12-15): 0x00000000
1007
CAS (16-23): 0x0000000000000000
1008
Extras : None
1009
Key : None
1010
Value : None
1011
</artwork>
1012
</figure>
1013
<t>
1014
The response-packet contains no extra data, and the result of the
1015
operation is signaled through the status code. The server will
1016
then close the connection.
1017
</t>
1018
</section>
1019
</section>
1020
1021
<section anchor="command-flush" title="Flush">
1022
<t>
1023
<list style="empty">
1024
<t>MAY have extras.</t>
1025
<t>MUST NOT have key.</t>
1026
<t>MUST NOT have value.</t>
1027
</list>
1028
</t>
1029
1030
<t>
1031
<list style="symbols">
1032
<t>4 byte expiration time</t>
1033
</list>
1034
</t>
1035
<figure>
1036
<preamble>Extra data for flush:</preamble>
1037
<artwork>
1038
Byte/ 0 | 1 | 2 | 3 |
1039
/ | | | |
1040
|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|
1041
+---------------+---------------+---------------+---------------+
1042
0| Expiration |
1043
+---------------+---------------+---------------+---------------+
1044
Total 4 bytes
1045
</artwork>
1046
</figure>
1047
<t>
1048
Flush the items in the cache now or some time in the future as
1049
specified by the expiration field. See the documentation of the
1050
textual protocol for the full description on how to specify the
1051
expiration time.
1052
</t>
1053
<section anchor="command-flush-example" title="Example">
1054
<t>
1055
To flush the cache (delete all items) in two hours, the set
1056
the following values in the request
1057
</t>
1058
<figure>
1059
<preamble>Flush request:</preamble>
1060
<artwork>
1061
Byte/ 0 | 1 | 2 | 3 |
1062
/ | | | |
1063
|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|
1064
+---------------+---------------+---------------+---------------+
1065
0| 0x80 | 0x08 | 0x00 | 0x00 |
1066
+---------------+---------------+---------------+---------------+
1067
4| 0x04 | 0x00 | 0x00 | 0x00 |
1068
+---------------+---------------+---------------+---------------+
1069
8| 0x00 | 0x00 | 0x00 | 0x04 |
1070
+---------------+---------------+---------------+---------------+
1071
12| 0x00 | 0x00 | 0x00 | 0x00 |
1072
+---------------+---------------+---------------+---------------+
1073
16| 0x00 | 0x00 | 0x00 | 0x00 |
1074
+---------------+---------------+---------------+---------------+
1075
20| 0x00 | 0x00 | 0x00 | 0x00 |
1076
+---------------+---------------+---------------+---------------+
1077
24| 0x00 | 0x00 | 0x0e | 0x10 |
1078
+---------------+---------------+---------------+---------------+
1079
Total 28 bytes (24 byte header, 4 byte body)
1080
1081
Field (offset) (value)
1082
Magic (0) : 0x80
1083
Opcode (1) : 0x08
1084
Key length (2,3) : 0x0000
1085
Extra length (4) : 0x04
1086
Data type (5) : 0x00
1087
Reserved (6,7) : 0x0000
1088
Total body (8-11) : 0x00000004
1089
Opaque (12-15): 0x00000000
1090
CAS (16-23): 0x0000000000000000
1091
Extras :
1092
Expiry (24-27): 0x000e10
1093
Key : None
1094
Value : None
1095
</artwork>
1096
</figure>
1097
<t>
1098
The response-packet contains no extra data, and the result of the
1099
operation is signaled through the status code.
1100
</t>
1101
</section>
1102
</section>
1103
<section anchor="command-noop" title="noop">
1104
<t>
1105
<list style="empty">
1106
<t>MUST NOT have extras.</t>
1107
<t>MUST NOT have key.</t>
1108
<t>MUST NOT have value.</t>
1109
</list>
1110
</t>
1111
1112
<t>
1113
Used as a keep alive. Flushes outstanding getq/getkq's.
1114
</t>
1115
<section anchor="command-noop-example" title="Example">
1116
<figure>
1117
<preamble>Noop request:</preamble>
1118
<artwork>
1119
Byte/ 0 | 1 | 2 | 3 |
1120
/ | | | |
1121
|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|
1122
+---------------+---------------+---------------+---------------+
1123
0| 0x80 | 0x0a | 0x00 | 0x00 |
1124
+---------------+---------------+---------------+---------------+
1125
4| 0x00 | 0x00 | 0x00 | 0x00 |
1126
+---------------+---------------+---------------+---------------+
1127
8| 0x00 | 0x00 | 0x00 | 0x00 |
1128
+---------------+---------------+---------------+---------------+
1129
12| 0x00 | 0x00 | 0x00 | 0x00 |
1130
+---------------+---------------+---------------+---------------+
1131
16| 0x00 | 0x00 | 0x00 | 0x00 |
1132
+---------------+---------------+---------------+---------------+
1133
20| 0x00 | 0x00 | 0x00 | 0x00 |
1134
+---------------+---------------+---------------+---------------+
1135
Total 24 bytes
1136
1137
Field (offset) (value)
1138
Magic (0) : 0x80
1139
Opcode (1) : 0x0a
1140
Key length (2,3) : 0x0000
1141
Extra length (4) : 0x00
1142
Data type (5) : 0x00
1143
Reserved (6,7) : 0x0000
1144
Total body (8-11) : 0x00000000
1145
Opaque (12-15): 0x00000000
1146
CAS (16-23): 0x0000000000000000
1147
Extras : None
1148
Key : None
1149
Value : None
1150
</artwork>
1151
</figure>
1152
<t>
1153
The response-packet contains no extra data, and the result of the
1154
operation is signaled through the status code.
1155
</t>
1156
</section>
1157
</section>
1158
1159
<section anchor="command-version" title="version">
1160
<t>
1161
<list style="empty">
1162
<t>MUST NOT have extras.</t>
1163
<t>MUST NOT have key.</t>
1164
<t>MUST NOT have value.</t>
1165
</list>
1166
</t>
1167
1168
<t>
1169
Request the server version.
1170
</t>
1171
<t>
1172
The server responds with a packet containing the version string
1173
in the body with the following format: "x.y.z"
1174
</t>
1175
<section anchor="command-version-example" title="Example">
1176
<figure>
1177
<preamble>Version request:</preamble>
1178
<artwork>
1179
Byte/ 0 | 1 | 2 | 3 |
1180
/ | | | |
1181
|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|
1182
+---------------+---------------+---------------+---------------+
1183
0| 0x80 | 0x0b | 0x00 | 0x00 |
1184
+---------------+---------------+---------------+---------------+
1185
4| 0x00 | 0x00 | 0x00 | 0x00 |
1186
+---------------+---------------+---------------+---------------+
1187
8| 0x00 | 0x00 | 0x00 | 0x00 |
1188
+---------------+---------------+---------------+---------------+
1189
12| 0x00 | 0x00 | 0x00 | 0x00 |
1190
+---------------+---------------+---------------+---------------+
1191
16| 0x00 | 0x00 | 0x00 | 0x00 |
1192
+---------------+---------------+---------------+---------------+
1193
20| 0x00 | 0x00 | 0x00 | 0x00 |
1194
+---------------+---------------+---------------+---------------+
1195
Total 24 bytes
1196
1197
Field (offset) (value)
1198
Magic (0) : 0x80
1199
Opcode (1) : 0x0b
1200
Key length (2,3) : 0x0000
1201
Extra length (4) : 0x00
1202
Data type (5) : 0x00
1203
Reserved (6,7) : 0x0000
1204
Total body (8-11) : 0x00000000
1205
Opaque (12-15): 0x00000000
1206
CAS (16-23): 0x0000000000000000
1207
Extras : None
1208
</artwork>
1209
</figure>
1210
<figure>
1211
<preamble>Version response:</preamble>
1212
<artwork>
1213
Byte/ 0 | 1 | 2 | 3 |
1214
/ | | | |
1215
|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|
1216
+---------------+---------------+---------------+---------------+
1217
0| 0x81 | 0x0b | 0x00 | 0x00 |
1218
+---------------+---------------+---------------+---------------+
1219
4| 0x00 | 0x00 | 0x00 | 0x00 |
1220
+---------------+---------------+---------------+---------------+
1221
8| 0x00 | 0x00 | 0x00 | 0x05 |
1222
+---------------+---------------+---------------+---------------+
1223
12| 0x00 | 0x00 | 0x00 | 0x00 |
1224
+---------------+---------------+---------------+---------------+
1225
16| 0x00 | 0x00 | 0x00 | 0x00 |
1226
+---------------+---------------+---------------+---------------+
1227
20| 0x00 | 0x00 | 0x00 | 0x00 |
1228
+---------------+---------------+---------------+---------------+
1229
24| 0x31 ('1') | 0x2e ('.') | 0x33 ('3') | 0x2e ('.') |
1230
+---------------+---------------+---------------+---------------+
1231
28| 0x31 ('1') |
1232
+---------------+
1233
Total 29 bytes (24 byte header, 5 byte body)
1234
1235
Field (offset) (value)
1236
Magic (0) : 0x81
1237
Opcode (1) : 0x0b
1238
Key length (2,3) : 0x0000
1239
Extra length (4) : 0x00
1240
Data type (5) : 0x00
1241
Status (6,7) : 0x0000
1242
Total body (8-11) : 0x00000005
1243
Opaque (12-15): 0x00000000
1244
CAS (16-23): 0x0000000000000000
1245
Extras : None
1246
Key : None
1247
Value : Textual string "1.3.1"
1248
</artwork>
1249
</figure>
1250
</section>
1251
</section>
1252
1253
<section anchor="command-append" title="Append, Prepend">
1254
<t>
1255
<list style="empty">
1256
<t>MUST NOT have extras.</t>
1257
<t>MUST have key.</t>
1258
<t>MUST have value.</t>
1259
</list>
1260
</t>
1261
1262
<t>
1263
These commands will either append or prepend the specified
1264
value to the requested key.
1265
</t>
1266
1267
<section anchor="command-append-example" title="Example">
1268
<t>The following example appends '!' to the 'Hello' key.</t>
1269
<figure>
1270
<preamble>Append request:</preamble>
1271
<artwork>
1272
Byte/ 0 | 1 | 2 | 3 |
1273
/ | | | |
1274
|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|
1275
+---------------+---------------+---------------+---------------+
1276
0| 0x80 | 0x0e | 0x00 | 0x05 |
1277
+---------------+---------------+---------------+---------------+
1278
4| 0x00 | 0x00 | 0x00 | 0x00 |
1279
+---------------+---------------+---------------+---------------+
1280
8| 0x00 | 0x00 | 0x00 | 0x06 |
1281
+---------------+---------------+---------------+---------------+
1282
12| 0x00 | 0x00 | 0x00 | 0x00 |
1283
+---------------+---------------+---------------+---------------+
1284
16| 0x00 | 0x00 | 0x00 | 0x00 |
1285
+---------------+---------------+---------------+---------------+
1286
20| 0x00 | 0x00 | 0x00 | 0x00 |
1287
+---------------+---------------+---------------+---------------+
1288
24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') |
1289
+---------------+---------------+---------------+---------------+
1290
28| 0x6f ('o') | 0x21 ('!') |
1291
+---------------+---------------+
1292
Total 30 bytes (24 byte header, 5 byte key, 1 byte value)
1293
1294
Field (offset) (value)
1295
Magic (0) : 0x80
1296
Opcode (1) : 0x0e
1297
Key length (2,3) : 0x0005
1298
Extra length (4) : 0x00
1299
Data type (5) : 0x00
1300
Reserved (6,7) : 0x0000
1301
Total body (8-11) : 0x00000006
1302
Opaque (12-15): 0x00000000
1303
CAS (16-23): 0x0000000000000000
1304
Extras : None
1305
Key (24-28): The textual string "Hello"
1306
Value (29) : "!"
1307
</artwork>
1308
</figure>
1309
<t>
1310
The response-packet contains no extra data, and the result of the
1311
operation is signaled through the status code.
1312
</t>
1313
</section>
1314
</section>
1315
1316
<section anchor="command-stat" title="Stat">
1317
<t>
1318
<list style="empty">
1319
<t>MUST NOT have extras.</t>
1320
<t>MAY have key.</t>
1321
<t>MUST NOT have value.</t>
1322
</list>
1323
</t>
1324
1325
<t>
1326
Request server statistics. Without a key specified the server will
1327
respond with a "default" set of statistics information. Each piece
1328
of statistical information is returned in its own packet (key
1329
contains the name of the statistical item and the body contains the
1330
value in ASCII format). The sequence of return packets is terminated
1331
with a packet that contains no key and no value.
1332
</t>
1333
<section anchor="command-stat-example" title="Example">
1334
<t>The following example requests all statistics from the server</t>
1335
<figure>
1336
<preamble>Stat request:</preamble>
1337
<artwork>
1338
Byte/ 0 | 1 | 2 | 3 |
1339
/ | | | |
1340
|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|
1341
+---------------+---------------+---------------+---------------+
1342
0| 0x80 | 0x10 | 0x00 | 0x00 |
1343
+---------------+---------------+---------------+---------------+
1344
4| 0x00 | 0x00 | 0x00 | 0x00 |
1345
+---------------+---------------+---------------+---------------+
1346
8| 0x00 | 0x00 | 0x00 | 0x00 |
1347
+---------------+---------------+---------------+---------------+
1348
12| 0x00 | 0x00 | 0x00 | 0x00 |
1349
+---------------+---------------+---------------+---------------+
1350
16| 0x00 | 0x00 | 0x00 | 0x00 |
1351
+---------------+---------------+---------------+---------------+
1352
20| 0x00 | 0x00 | 0x00 | 0x00 |
1353
+---------------+---------------+---------------+---------------+
1354
Total 24 bytes
1355
1356
Field (offset) (value)
1357
Magic (0) : 0x80
1358
Opcode (1) : 0x10
1359
Key length (2,3) : 0x0000
1360
Extra length (4) : 0x00
1361
Data type (5) : 0x00
1362
Reserved (6,7) : 0x0000
1363
Total body (8-11) : 0x00000000
1364
Opaque (12-15): 0x00000000
1365
CAS (16-23): 0x0000000000000000
1366
Extras : None
1367
Key : None
1368
Value : None
1369
</artwork>
1370
</figure>
1371
<t>
1372
The server will send each value in a separate packet with
1373
an "empty" packet (no key / no value) to terminate the sequence.
1374
Each of the response packets look like the following example:
1375
</t>
1376
<figure>
1377
<preamble>Stat response:</preamble>
1378
<artwork>
1379
Byte/ 0 | 1 | 2 | 3 |
1380
/ | | | |
1381
|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|
1382
+---------------+---------------+---------------+---------------+
1383
0| 0x81 | 0x10 | 0x00 | 0x03 |
1384
+---------------+---------------+---------------+---------------+
1385
4| 0x00 | 0x00 | 0x00 | 0x00 |
1386
+---------------+---------------+---------------+---------------+
1387
8| 0x00 | 0x00 | 0x00 | 0x07 |
1388
+---------------+---------------+---------------+---------------+
1389
12| 0x00 | 0x00 | 0x00 | 0x00 |
1390
+---------------+---------------+---------------+---------------+
1391
16| 0x00 | 0x00 | 0x00 | 0x00 |
1392
+---------------+---------------+---------------+---------------+
1393
20| 0x00 | 0x00 | 0x00 | 0x00 |
1394
+---------------+---------------+---------------+---------------+
1395
24| 0x70 ('p') | 0x69 ('i') | 0x64 ('d') | 0x33 ('3') |
1396
+---------------+---------------+---------------+---------------+
1397
28| 0x30 ('0') | 0x37 ('7') | 0x38 ('8') |
1398
+---------------+---------------+---------------+
1399
Total 31 bytes (24 byte header, 3 byte key, 4 byte body)
1400
1401
Field (offset) (value)
1402
Magic (0) : 0x81
1403
Opcode (1) : 0x10
1404
Key length (2,3) : 0x0003
1405
Extra length (4) : 0x00
1406
Data type (5) : 0x00
1407
Status (6,7) : 0x0000
1408
Total body (8-11) : 0x00000007
1409
Opaque (12-15): 0x00000000
1410
CAS (16-23): 0x0000000000000000
1411
Exstras : None
1412
Key : The textual string "pid"
1413
Value : The textual string "3078"
1414
</artwork>
1415
</figure>
1416
</section>
1417
</section>
1418
</section>
1419
<section anchor="security" title="Security Considerations">
1420
<t>
1421
Memcache has no authentication or security layers whatsoever. It is
1422
RECOMMENDED that memcache be deployed strictly on closed, protected,
1423
back-end networks within a single data center, within a single cluster of
1424
servers, or even on a single host, providing shared caching for multiple
1425
applications. Memcache MUST NOT be made available on a public network.
1426
</t>
1427
</section>
1428
1429
</middle>
1430
1431
<back>
1432
<references title="Normative References">
1433
<reference anchor="LJ">
1434
<front>
1435
<title>LJ NEEDS MOAR SPEED</title>
1436
<author fullname="Brad Fitzpatrick">
1437
<organization>Danga Interactive</organization>
1438
</author>
1439
<date day="5" month="10" year="1999" />
1440
<abstract>
1441
<t>http://www.livejournal.com/</t>
1442
</abstract>
1443
</front>
1444
</reference>
1445
<dwdrfc-ref anchor="KEYWORDS" src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/>
1446
</references>
1447
1448
<section anchor="acknowledgments" title="Acknowledgments">
1449
<t>
1450
Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin
1451
Sallings, for their work on the memcached server.
1452
</t>
1453
1454
<t>
1455
Thanks to Sean Chittenden, Jonathan Steinert, Brian Aker, Evan Martin,
1456
Nathan Neulinger, Eric Hodel, Michael Johnson, Paul Querna, Jamie
1457
McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg, Robin H.
1458
Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean-Francois
1459
Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris Goffinet, Tomash
1460
Brechko, and others for their work reporting bugs and maintaining
1461
memcached client libraries and bindings in many languages.
1462
</t>
1463
</section>
1464
</back>
1465
1466
</rfc>
1467
Loggerhead is a web-based interface for Breezy
Version: 2.0.1