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="trust200902"> 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>[email protected]</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>[email protected]</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 318Field (offset) (value) 319Magic (0) : 0x81 320Opcode (1) : 0x00 321Key length (2,3) : 0x0000 322Extra length (4) : 0x00 323Data type (5) : 0x00 324Status (6,7) : 0x0001 325Total body (8-11) : 0x00000009 326Opaque (12-15): 0x00000000 327CAS (16-23): 0x0000000000000000 328Extras : None 329Key : None 330Value (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 Response (if found): 350 </t> 351 <t> 352 <list style="empty"> 353 <t>MUST have extras.</t> 354 <t>MAY have key.</t> 355 <t>MAY have value.</t> 356 </list> 357 </t> 358 359 <t> 360 <list style="symbols"> 361 <t>4 byte flags</t> 362 </list> 363 </t> 364 365 <t> 366 <figure> 367 <preamble>Extra data for the get commands:</preamble> 368 <artwork> 369 Byte/ 0 | 1 | 2 | 3 | 370 / | | | | 371 |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| 372 +---------------+---------------+---------------+---------------+ 373 0| Flags | 374 +---------------+---------------+---------------+---------------+ 375 376 Total 4 bytes 377 </artwork> 378 </figure> 379 </t> 380 381 <t> 382 The get command gets a single key. The getq command is both mum 383 on cache miss and quiet, holding its response until a non-quiet 384 command is issued. Getk and getkq differs from get and getq by 385 adding the key into the response packet. 386 </t> 387 388 <t> 389 You're not guaranteed a response to a getq/getkq cache hit until 390 you send a non-getq/getkq command later, which uncorks the 391 server and bundles up IOs to send to the client in one go. 392 </t> 393 394 <t> 395 Clients should implement multi-get (still important for 396 reducing network roundtrips!) as n pipelined requests, the 397 first n-1 being getq/getkq, the last being a regular 398 get/getk. That way you're guaranteed to get a response, and 399 you know when the server's done. You can also do the naive 400 thing and send n pipelined get/getks, but then you could potentially 401 get back a lot of "NOT_FOUND" error code packets. 402 Alternatively, you can send 'n' getq/getkqs, followed by a 403 'noop' command. 404 </t> 405 406 <section anchor="command-get-example" title="Example"> 407 <t> 408 To request the data associated with the key "Hello" the 409 following fields must be specified in the packet. 410 </t> 411 <figure> 412 <preamble>get request:</preamble> 413 <artwork> 414 Byte/ 0 | 1 | 2 | 3 | 415 / | | | | 416 |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| 417 +---------------+---------------+---------------+---------------+ 418 0| 0x80 | 0x00 | 0x00 | 0x05 | 419 +---------------+---------------+---------------+---------------+ 420 4| 0x00 | 0x00 | 0x00 | 0x00 | 421 +---------------+---------------+---------------+---------------+ 422 8| 0x00 | 0x00 | 0x00 | 0x05 | 423 +---------------+---------------+---------------+---------------+ 424 12| 0x00 | 0x00 | 0x00 | 0x00 | 425 +---------------+---------------+---------------+---------------+ 426 16| 0x00 | 0x00 | 0x00 | 0x00 | 427 +---------------+---------------+---------------+---------------+ 428 20| 0x00 | 0x00 | 0x00 | 0x00 | 429 +---------------+---------------+---------------+---------------+ 430 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 431 +---------------+---------------+---------------+---------------+ 432 28| 0x6f ('o') | 433 +---------------+ 434 435 Total 29 bytes (24 byte header, and 5 bytes key) 436 437Field (offset) (value) 438Magic (0) : 0x80 439Opcode (1) : 0x00 440Key length (2,3) : 0x0005 441Extra length (4) : 0x00 442Data type (5) : 0x00 443Reserved (6,7) : 0x0000 444Total body (8-11) : 0x00000005 445Opaque (12-15): 0x00000000 446CAS (16-23): 0x0000000000000000 447Extras : None 448Key (24-29): The textual string: "Hello" 449Value : None 450 </artwork> 451 </figure> 452 <t>If the item exist on the server the following packet is returned, 453 otherwise a packet with status code != 0 will be returned (see 454 <xref target="command-introduction">Introduction</xref>) 455 </t> 456 <figure> 457 <preamble>get/getq response:</preamble> 458 <artwork> 459 460 Byte/ 0 | 1 | 2 | 3 | 461 / | | | | 462 |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| 463 +---------------+---------------+---------------+---------------+ 464 0| 0x81 | 0x00 | 0x00 | 0x00 | 465 +---------------+---------------+---------------+---------------+ 466 4| 0x04 | 0x00 | 0x00 | 0x00 | 467 +---------------+---------------+---------------+---------------+ 468 8| 0x00 | 0x00 | 0x00 | 0x09 | 469 +---------------+---------------+---------------+---------------+ 470 12| 0x00 | 0x00 | 0x00 | 0x00 | 471 +---------------+---------------+---------------+---------------+ 472 16| 0x00 | 0x00 | 0x00 | 0x00 | 473 +---------------+---------------+---------------+---------------+ 474 20| 0x00 | 0x00 | 0x00 | 0x01 | 475 +---------------+---------------+---------------+---------------+ 476 24| 0xde | 0xad | 0xbe | 0xef | 477 +---------------+---------------+---------------+---------------+ 478 28| 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 0x6c ('l') | 479 +---------------+---------------+---------------+---------------+ 480 32| 0x64 ('d') | 481 +---------------+ 482 483 Total 33 bytes (24 byte header, 4 byte extras and 5 byte value) 484 485Field (offset) (value) 486Magic (0) : 0x81 487Opcode (1) : 0x00 488Key length (2,3) : 0x0000 489Extra length (4) : 0x04 490Data type (5) : 0x00 491Status (6,7) : 0x0000 492Total body (8-11) : 0x00000009 493Opaque (12-15): 0x00000000 494CAS (16-23): 0x0000000000000001 495Extras : 496 Flags (24-27): 0xdeadbeef 497Key : None 498Value (28-32): The textual string "World" 499 </artwork> 500 </figure> 501 <figure> 502 <preamble>getk/getkq response:</preamble> 503 <artwork> 504 505 Byte/ 0 | 1 | 2 | 3 | 506 / | | | | 507 |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| 508 +---------------+---------------+---------------+---------------+ 509 0| 0x81 | 0x00 | 0x00 | 0x05 | 510 +---------------+---------------+---------------+---------------+ 511 4| 0x04 | 0x00 | 0x00 | 0x00 | 512 +---------------+---------------+---------------+---------------+ 513 8| 0x00 | 0x00 | 0x00 | 0x09 | 514 +---------------+---------------+---------------+---------------+ 515 12| 0x00 | 0x00 | 0x00 | 0x00 | 516 +---------------+---------------+---------------+---------------+ 517 16| 0x00 | 0x00 | 0x00 | 0x00 | 518 +---------------+---------------+---------------+---------------+ 519 20| 0x00 | 0x00 | 0x00 | 0x01 | 520 +---------------+---------------+---------------+---------------+ 521 24| 0xde | 0xad | 0xbe | 0xef | 522 +---------------+---------------+---------------+---------------+ 523 28| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 524 +---------------+---------------+---------------+---------------+ 525 32| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 526 +---------------+---------------+---------------+---------------+ 527 36| 0x6c ('l') | 0x64 ('d') | 528 +---------------+---------------+ 529 530 Total 38 bytes (24 byte header, 4 byte extras, 5 byte key 531 and 5 byte value) 532 533Field (offset) (value) 534Magic (0) : 0x81 535Opcode (1) : 0x00 536Key length (2,3) : 0x0005 537Extra length (4) : 0x04 538Data type (5) : 0x00 539Status (6,7) : 0x0000 540Total body (8-11) : 0x0000000E 541Opaque (12-15): 0x00000000 542CAS (16-23): 0x0000000000000001 543Extras : 544 Flags (24-27): 0xdeadbeef 545Key (28-32): The textual string: "Hello" 546Value (33-37): The textual string: "World" 547 </artwork> 548 </figure> 549 </section> 550 </section> 551 552 <section anchor="command-set" title="Set, Add, Replace"> 553 <t> 554 <list style="empty"> 555 <t>MUST have extras.</t> 556 <t>MUST have key.</t> 557 <t>MUST have value.</t> 558 </list> 559 </t> 560 561 <t> 562 <list style="symbols"> 563 <t>4 byte flags</t> 564 <t>4 byte expiration time</t> 565 </list> 566 </t> 567 568 <figure> 569 <preamble>Extra data for set/add/replace:</preamble> 570 <artwork> 571 Byte/ 0 | 1 | 2 | 3 | 572 / | | | | 573 |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| 574 +---------------+---------------+---------------+---------------+ 575 0| Flags | 576 +---------------+---------------+---------------+---------------+ 577 4| Expiration | 578 +---------------+---------------+---------------+---------------+ 579 Total 8 bytes 580 </artwork> 581 </figure> 582 583 <t> 584 If the Data Version Check (CAS) is nonzero, the requested 585 operation MUST only succeed if the item exists and has a CAS value 586 identical to the provided value. 587 </t> 588 589 <t> 590 Add MUST fail if the item already exist. 591 </t> 592 593 <t> 594 Replace MUST fail if the item doesn't exist. 595 </t> 596 597 <t> 598 Set should store the data unconditionally if the item exists 599 or not. 600 </t> 601 602 <t> 603 Quiet mutations only return responses on failure. Success 604 is considered the general case and is suppressed when in 605 quiet mode, but errors should not be allowed to go 606 unnoticed. 607 </t> 608 609 <section anchor="command-set-example" title="Example"> 610 <t>The following figure shows an add-command for 611 <list style="empty"> 612 <t>Key: "Hello"</t> 613 <t>Value: "World"</t> 614 <t>Flags: 0xdeadbeef</t> 615 <t>Expiry: in two hours</t> 616 </list> 617 </t> 618 <figure> 619 <preamble>Add request:</preamble> 620 <artwork> 621 622 Byte/ 0 | 1 | 2 | 3 | 623 / | | | | 624 |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| 625 +---------------+---------------+---------------+---------------+ 626 0| 0x80 | 0x02 | 0x00 | 0x05 | 627 +---------------+---------------+---------------+---------------+ 628 4| 0x08 | 0x00 | 0x00 | 0x00 | 629 +---------------+---------------+---------------+---------------+ 630 8| 0x00 | 0x00 | 0x00 | 0x12 | 631 +---------------+---------------+---------------+---------------+ 632 12| 0x00 | 0x00 | 0x00 | 0x00 | 633 +---------------+---------------+---------------+---------------+ 634 16| 0x00 | 0x00 | 0x00 | 0x00 | 635 +---------------+---------------+---------------+---------------+ 636 20| 0x00 | 0x00 | 0x00 | 0x00 | 637 +---------------+---------------+---------------+---------------+ 638 24| 0xde | 0xad | 0xbe | 0xef | 639 +---------------+---------------+---------------+---------------+ 640 28| 0x00 | 0x00 | 0x1c | 0x20 | 641 +---------------+---------------+---------------+---------------+ 642 32| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 643 +---------------+---------------+---------------+---------------+ 644 36| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 645 +---------------+---------------+---------------+---------------+ 646 40| 0x6c ('l') | 0x64 ('d') | 647 +---------------+---------------+ 648 649 Total 42 bytes (24 byte header, 8 byte extras, 5 byte key and 650 5 byte value) 651 652Field (offset) (value) 653Magic (0) : 0x80 654Opcode (1) : 0x02 655Key length (2,3) : 0x0005 656Extra length (4) : 0x08 657Data type (5) : 0x00 658Reserved (6,7) : 0x0000 659Total body (8-11) : 0x00000012 660Opaque (12-15): 0x00000000 661CAS (16-23): 0x0000000000000000 662Extras : 663 Flags (24-27): 0xdeadbeef 664 Expiry (28-31): 0x00001c20 665Key (32-36): The textual string "Hello" 666Value (37-41): The textual string "World" 667 </artwork> 668 </figure> 669 <t> 670 The response-packet contains no extra data, and the result of the 671 operation is signaled through the status code. If the command 672 succeeds, the CAS value for the item is returned in the CAS-field 673 of the packet. 674 </t> 675 <figure> 676 <preamble>Successful add response:</preamble> 677 <artwork> 678 679 Byte/ 0 | 1 | 2 | 3 | 680 / | | | | 681 |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| 682 +---------------+---------------+---------------+---------------+ 683 0| 0x81 | 0x02 | 0x00 | 0x00 | 684 +---------------+---------------+---------------+---------------+ 685 4| 0x00 | 0x00 | 0x00 | 0x00 | 686 +---------------+---------------+---------------+---------------+ 687 8| 0x00 | 0x00 | 0x00 | 0x00 | 688 +---------------+---------------+---------------+---------------+ 689 12| 0x00 | 0x00 | 0x00 | 0x00 | 690 +---------------+---------------+---------------+---------------+ 691 16| 0x00 | 0x00 | 0x00 | 0x00 | 692 +---------------+---------------+---------------+---------------+ 693 20| 0x00 | 0x00 | 0x00 | 0x01 | 694 +---------------+---------------+---------------+---------------+ 695 696 Total 24 bytes 697 698Field (offset) (value) 699Magic (0) : 0x81 700Opcode (1) : 0x02 701Key length (2,3) : 0x0000 702Extra length (4) : 0x00 703Data type (5) : 0x00 704Status (6,7) : 0x0000 705Total body (8-11) : 0x00000000 706Opaque (12-15): 0x00000000 707CAS (16-23): 0x0000000000000001 708Extras : None 709Key : None 710Value : None 711 </artwork> 712 </figure> 713 </section> 714 </section> 715 716 <section anchor="command-delete" title="Delete"> 717 <t> 718 <list style="empty"> 719 <t>MUST NOT have extras.</t> 720 <t>MUST have key.</t> 721 <t>MUST NOT have value.</t> 722 </list> 723 </t> 724 725 <t> 726 Delete the item with the specific key. 727 </t> 728 729 <section anchor="command-delete-example" title="Example"> 730 <t>The following figure shows a delete message for the 731 item "Hello".</t> 732 <figure> 733 <preamble>Delete request:</preamble> 734 <artwork> 735 Byte/ 0 | 1 | 2 | 3 | 736 / | | | | 737 |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| 738 +---------------+---------------+---------------+---------------+ 739 0| 0x80 | 0x04 | 0x00 | 0x05 | 740 +---------------+---------------+---------------+---------------+ 741 4| 0x00 | 0x00 | 0x00 | 0x00 | 742 +---------------+---------------+---------------+---------------+ 743 8| 0x00 | 0x00 | 0x00 | 0x05 | 744 +---------------+---------------+---------------+---------------+ 745 12| 0x00 | 0x00 | 0x00 | 0x00 | 746 +---------------+---------------+---------------+---------------+ 747 16| 0x00 | 0x00 | 0x00 | 0x00 | 748 +---------------+---------------+---------------+---------------+ 749 20| 0x00 | 0x00 | 0x00 | 0x00 | 750 +---------------+---------------+---------------+---------------+ 751 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 752 +---------------+---------------+---------------+---------------+ 753 28| 0x6f ('o') | 754 +---------------+ 755 756 Total 29 bytes (24 byte header, 5 byte value) 757 758Field (offset) (value) 759Magic (0) : 0x80 760Opcode (1) : 0x04 761Key length (2,3) : 0x0005 762Extra length (4) : 0x00 763Data type (5) : 0x00 764Reserved (6,7) : 0x0000 765Total body (8-11) : 0x00000005 766Opaque (12-15): 0x00000000 767CAS (16-23): 0x0000000000000000 768Extras : None 769Key : The textual string "Hello" 770Value : None 771 </artwork> 772 </figure> 773 <t> 774 The response-packet contains no extra data, and the result of the 775 operation is signaled through the status code. 776 </t> 777 </section> 778 </section> 779 780 <section anchor="command-incr" title="Increment, Decrement"> 781 <t> 782 <list style="empty"> 783 <t>MUST have extras.</t> 784 <t>MUST have key.</t> 785 <t>MUST NOT have value.</t> 786 </list> 787 </t> 788 789 <t> 790 <list style="symbols"> 791 <t>8 byte value to add / subtract</t> 792 <t>8 byte initial value (unsigned)</t> 793 <t>4 byte expiration time</t> 794 </list> 795 </t> 796 <figure> 797 <preamble>Extra data for incr/decr:</preamble> 798 <artwork> 799 Byte/ 0 | 1 | 2 | 3 | 800 / | | | | 801 |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| 802 +---------------+---------------+---------------+---------------+ 803 0| Amount to add | 804 | | 805 +---------------+---------------+---------------+---------------+ 806 8| Initial value | 807 | | 808 +---------------+---------------+---------------+---------------+ 809 16| Expiration | 810 +---------------+---------------+---------------+---------------+ 811 Total 20 bytes 812 </artwork> 813 </figure> 814 815 <t> 816 These commands will either add or remove the specified 817 amount to the requested counter. 818 </t> 819 <t> 820 If the counter does not exist, one of two things may happen: 821 </t> 822 <t> 823 <list style="numbers"> 824 <t>If the expiration value is all one-bits (0xffffffff), the 825 operation will fail with NOT_FOUND.</t> 826 <t>For all other expiration values, the operation will succeed 827 by seeding the value for this key with the provided initial 828 value to expire with the provided expiration time. The flags 829 will be set to zero.</t> 830 </list> 831 </t> 832 <figure> 833 <preamble>incr/decr response body:</preamble> 834 <artwork> 835 Byte/ 0 | 1 | 2 | 3 | 836 / | | | | 837 |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| 838 +---------------+---------------+---------------+---------------+ 839 0| 64-bit unsigned response. | 840 | | 841 +---------------+---------------+---------------+---------------+ 842 Total 8 bytes 843 </artwork> 844 </figure> 845 <section anchor="command-incr-example" title="Example"> 846 <t>The following figure shows an incr-command for 847 <list style="empty"> 848 <t>Key: "counter"</t> 849 <t>Delta: 0x01</t> 850 <t>Initial: 0x00</t> 851 <t>Expiry: in two hours</t> 852 </list> 853 </t> 854 <figure> 855 <preamble>Increment request:</preamble> 856 <artwork> 857 858 Byte/ 0 | 1 | 2 | 3 | 859 / | | | | 860 |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| 861 +---------------+---------------+---------------+---------------+ 862 0| 0x80 | 0x05 | 0x00 | 0x07 | 863 +---------------+---------------+---------------+---------------+ 864 4| 0x14 | 0x00 | 0x00 | 0x00 | 865 +---------------+---------------+---------------+---------------+ 866 8| 0x00 | 0x00 | 0x00 | 0x1b | 867 +---------------+---------------+---------------+---------------+ 868 12| 0x00 | 0x00 | 0x00 | 0x00 | 869 +---------------+---------------+---------------+---------------+ 870 16| 0x00 | 0x00 | 0x00 | 0x00 | 871 +---------------+---------------+---------------+---------------+ 872 20| 0x00 | 0x00 | 0x00 | 0x00 | 873 +---------------+---------------+---------------+---------------+ 874 24| 0x00 | 0x00 | 0x00 | 0x00 | 875 +---------------+---------------+---------------+---------------+ 876 28| 0x00 | 0x00 | 0x00 | 0x01 | 877 +---------------+---------------+---------------+---------------+ 878 32| 0x00 | 0x00 | 0x00 | 0x00 | 879 +---------------+---------------+---------------+---------------+ 880 36| 0x00 | 0x00 | 0x00 | 0x00 | 881 +---------------+---------------+---------------+---------------+ 882 40| 0x00 | 0x00 | 0x1c | 0x20 | 883 +---------------+---------------+---------------+---------------+ 884 44| 0x63 ('c') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | 885 +---------------+---------------+---------------+---------------+ 886 48| 0x74 ('t') | 0x65 ('e') | 0x72 ('r') | 887 +---------------+---------------+---------------+ 888 Total 51 bytes (24 byte header, 20 byte extras, 7 byte key) 889 890Field (offset) (value) 891Magic (0) : 0x80 892Opcode (1) : 0x05 893Key length (2,3) : 0x0007 894Extra length (4) : 0x14 895Data type (5) : 0x00 896Reserved (6,7) : 0x0000 897Total body (8-11) : 0x0000001b 898Opaque (12-15): 0x00000000 899CAS (16-23): 0x0000000000000000 900Extras : 901 delta (24-31): 0x0000000000000001 902 initial (32-39): 0x0000000000000000 903 expiration (40-43): 0x00001c20 904Key : Textual string "counter" 905Value : None 906 </artwork> 907 </figure> 908 <t> 909 If the key doesn't exist, the server will respond with the 910 initial value. If not the incremented value will be returned. 911 Let's assume that the key didn't exist, so the initial value 912 is returned. 913 </t> 914 <figure> 915 <preamble>Increment response:</preamble> 916 <artwork> 917 Byte/ 0 | 1 | 2 | 3 | 918 / | | | | 919 |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| 920 +---------------+---------------+---------------+---------------+ 921 0| 0x81 | 0x05 | 0x00 | 0x00 | 922 +---------------+---------------+---------------+---------------+ 923 4| 0x00 | 0x00 | 0x00 | 0x00 | 924 +---------------+---------------+---------------+---------------+ 925 8| 0x00 | 0x00 | 0x00 | 0x08 | 926 +---------------+---------------+---------------+---------------+ 927 12| 0x00 | 0x00 | 0x00 | 0x00 | 928 +---------------+---------------+---------------+---------------+ 929 16| 0x00 | 0x00 | 0x00 | 0x00 | 930 +---------------+---------------+---------------+---------------+ 931 20| 0x00 | 0x00 | 0x00 | 0x05 | 932 +---------------+---------------+---------------+---------------+ 933 24| 0x00 | 0x00 | 0x00 | 0x00 | 934 +---------------+---------------+---------------+---------------+ 935 28| 0x00 | 0x00 | 0x00 | 0x00 | 936 +---------------+---------------+---------------+---------------+ 937 Total 32 bytes (24 byte header, 8 byte value) 938 939Field (offset) (value) 940Magic (0) : 0x81 941Opcode (1) : 0x05 942Key length (2,3) : 0x0000 943Extra length (4) : 0x00 944Data type (5) : 0x00 945Status (6,7) : 0x0000 946Total body (8-11) : 0x00000008 947Opaque (12-15): 0x00000000 948CAS (16-23): 0x0000000000000005 949Extras : None 950Key : None 951Value : 0x0000000000000000 952 </artwork> 953 </figure> 954 </section> 955 </section> 956 957 <section anchor="command-quit" title="quit"> 958 <t> 959 <list style="empty"> 960 <t>MUST NOT have extras.</t> 961 <t>MUST NOT have key.</t> 962 <t>MUST NOT have value.</t> 963 </list> 964 </t> 965 966 <t> 967 Close the connection to the server. 968 </t> 969 970 <section anchor="command-quit-example" title="Example"> 971 <figure> 972 <preamble>Quit request:</preamble> 973 <artwork> 974 Byte/ 0 | 1 | 2 | 3 | 975 / | | | | 976 |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| 977 +---------------+---------------+---------------+---------------+ 978 0| 0x80 | 0x07 | 0x00 | 0x00 | 979 +---------------+---------------+---------------+---------------+ 980 4| 0x00 | 0x00 | 0x00 | 0x00 | 981 +---------------+---------------+---------------+---------------+ 982 8| 0x00 | 0x00 | 0x00 | 0x00 | 983 +---------------+---------------+---------------+---------------+ 984 12| 0x00 | 0x00 | 0x00 | 0x00 | 985 +---------------+---------------+---------------+---------------+ 986 16| 0x00 | 0x00 | 0x00 | 0x00 | 987 +---------------+---------------+---------------+---------------+ 988 20| 0x00 | 0x00 | 0x00 | 0x00 | 989 +---------------+---------------+---------------+---------------+ 990 Total 24 bytes 991 992Field (offset) (value) 993Magic (0) : 0x80 994Opcode (1) : 0x07 995Key length (2,3) : 0x0000 996Extra length (4) : 0x00 997Data type (5) : 0x00 998Reserved (6,7) : 0x0000 999Total body (8-11) : 0x00000000 1000Opaque (12-15): 0x00000000 1001CAS (16-23): 0x0000000000000000 1002Extras : None 1003Key : None 1004Value : None 1005 </artwork> 1006 </figure> 1007 <t> 1008 The response-packet contains no extra data, and the result of the 1009 operation is signaled through the status code. The server will 1010 then close the connection. 1011 </t> 1012 </section> 1013 </section> 1014 1015 <section anchor="command-flush" title="Flush"> 1016 <t> 1017 <list style="empty"> 1018 <t>MAY have extras.</t> 1019 <t>MUST NOT have key.</t> 1020 <t>MUST NOT have value.</t> 1021 </list> 1022 </t> 1023 1024 <t> 1025 <list style="symbols"> 1026 <t>4 byte expiration time</t> 1027 </list> 1028 </t> 1029 <figure> 1030 <preamble>Extra data for flush:</preamble> 1031 <artwork> 1032 Byte/ 0 | 1 | 2 | 3 | 1033 / | | | | 1034 |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| 1035 +---------------+---------------+---------------+---------------+ 1036 0| Expiration | 1037 +---------------+---------------+---------------+---------------+ 1038 Total 4 bytes 1039 </artwork> 1040 </figure> 1041 <t> 1042 Flush the items in the cache now or some time in the future as 1043 specified by the expiration field. See the documentation of the 1044 textual protocol for the full description on how to specify the 1045 expiration time. 1046 </t> 1047 <section anchor="command-flush-example" title="Example"> 1048 <t> 1049 To flush the cache (delete all items) in two hours, the set 1050 the following values in the request 1051 </t> 1052 <figure> 1053 <preamble>Flush request:</preamble> 1054 <artwork> 1055 Byte/ 0 | 1 | 2 | 3 | 1056 / | | | | 1057 |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| 1058 +---------------+---------------+---------------+---------------+ 1059 0| 0x80 | 0x08 | 0x00 | 0x00 | 1060 +---------------+---------------+---------------+---------------+ 1061 4| 0x04 | 0x00 | 0x00 | 0x00 | 1062 +---------------+---------------+---------------+---------------+ 1063 8| 0x00 | 0x00 | 0x00 | 0x04 | 1064 +---------------+---------------+---------------+---------------+ 1065 12| 0x00 | 0x00 | 0x00 | 0x00 | 1066 +---------------+---------------+---------------+---------------+ 1067 16| 0x00 | 0x00 | 0x00 | 0x00 | 1068 +---------------+---------------+---------------+---------------+ 1069 20| 0x00 | 0x00 | 0x00 | 0x00 | 1070 +---------------+---------------+---------------+---------------+ 1071 24| 0x00 | 0x00 | 0x1c | 0x20 | 1072 +---------------+---------------+---------------+---------------+ 1073 Total 28 bytes (24 byte header, 4 byte body) 1074 1075Field (offset) (value) 1076Magic (0) : 0x80 1077Opcode (1) : 0x08 1078Key length (2,3) : 0x0000 1079Extra length (4) : 0x04 1080Data type (5) : 0x00 1081Reserved (6,7) : 0x0000 1082Total body (8-11) : 0x00000004 1083Opaque (12-15): 0x00000000 1084CAS (16-23): 0x0000000000000000 1085Extras : 1086 Expiry (24-27): 0x00001c20 1087Key : None 1088Value : None 1089 </artwork> 1090 </figure> 1091 <t> 1092 The response-packet contains no extra data, and the result of the 1093 operation is signaled through the status code. 1094 </t> 1095 </section> 1096 </section> 1097 <section anchor="command-noop" title="noop"> 1098 <t> 1099 <list style="empty"> 1100 <t>MUST NOT have extras.</t> 1101 <t>MUST NOT have key.</t> 1102 <t>MUST NOT have value.</t> 1103 </list> 1104 </t> 1105 1106 <t> 1107 Used as a keep alive. Flushes outstanding getq/getkq's. 1108 </t> 1109 <section anchor="command-noop-example" title="Example"> 1110 <figure> 1111 <preamble>Noop request:</preamble> 1112 <artwork> 1113 Byte/ 0 | 1 | 2 | 3 | 1114 / | | | | 1115 |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| 1116 +---------------+---------------+---------------+---------------+ 1117 0| 0x80 | 0x0a | 0x00 | 0x00 | 1118 +---------------+---------------+---------------+---------------+ 1119 4| 0x00 | 0x00 | 0x00 | 0x00 | 1120 +---------------+---------------+---------------+---------------+ 1121 8| 0x00 | 0x00 | 0x00 | 0x00 | 1122 +---------------+---------------+---------------+---------------+ 1123 12| 0x00 | 0x00 | 0x00 | 0x00 | 1124 +---------------+---------------+---------------+---------------+ 1125 16| 0x00 | 0x00 | 0x00 | 0x00 | 1126 +---------------+---------------+---------------+---------------+ 1127 20| 0x00 | 0x00 | 0x00 | 0x00 | 1128 +---------------+---------------+---------------+---------------+ 1129 Total 24 bytes 1130 1131Field (offset) (value) 1132Magic (0) : 0x80 1133Opcode (1) : 0x0a 1134Key length (2,3) : 0x0000 1135Extra length (4) : 0x00 1136Data type (5) : 0x00 1137Reserved (6,7) : 0x0000 1138Total body (8-11) : 0x00000000 1139Opaque (12-15): 0x00000000 1140CAS (16-23): 0x0000000000000000 1141Extras : None 1142Key : None 1143Value : None 1144 </artwork> 1145 </figure> 1146 <t> 1147 The response-packet contains no extra data, and the result of the 1148 operation is signaled through the status code. 1149 </t> 1150 </section> 1151 </section> 1152 1153 <section anchor="command-version" title="version"> 1154 <t> 1155 <list style="empty"> 1156 <t>MUST NOT have extras.</t> 1157 <t>MUST NOT have key.</t> 1158 <t>MUST NOT have value.</t> 1159 </list> 1160 </t> 1161 1162 <t> 1163 Request the server version. 1164 </t> 1165 <t> 1166 The server responds with a packet containing the version string 1167 in the body with the following format: "x.y.z" 1168 </t> 1169 <section anchor="command-version-example" title="Example"> 1170 <figure> 1171 <preamble>Version request:</preamble> 1172 <artwork> 1173 Byte/ 0 | 1 | 2 | 3 | 1174 / | | | | 1175 |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| 1176 +---------------+---------------+---------------+---------------+ 1177 0| 0x80 | 0x0b | 0x00 | 0x00 | 1178 +---------------+---------------+---------------+---------------+ 1179 4| 0x00 | 0x00 | 0x00 | 0x00 | 1180 +---------------+---------------+---------------+---------------+ 1181 8| 0x00 | 0x00 | 0x00 | 0x00 | 1182 +---------------+---------------+---------------+---------------+ 1183 12| 0x00 | 0x00 | 0x00 | 0x00 | 1184 +---------------+---------------+---------------+---------------+ 1185 16| 0x00 | 0x00 | 0x00 | 0x00 | 1186 +---------------+---------------+---------------+---------------+ 1187 20| 0x00 | 0x00 | 0x00 | 0x00 | 1188 +---------------+---------------+---------------+---------------+ 1189 Total 24 bytes 1190 1191Field (offset) (value) 1192Magic (0) : 0x80 1193Opcode (1) : 0x0b 1194Key length (2,3) : 0x0000 1195Extra length (4) : 0x00 1196Data type (5) : 0x00 1197Reserved (6,7) : 0x0000 1198Total body (8-11) : 0x00000000 1199Opaque (12-15): 0x00000000 1200CAS (16-23): 0x0000000000000000 1201Extras : None 1202 </artwork> 1203 </figure> 1204 <figure> 1205 <preamble>Version response:</preamble> 1206 <artwork> 1207 Byte/ 0 | 1 | 2 | 3 | 1208 / | | | | 1209 |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| 1210 +---------------+---------------+---------------+---------------+ 1211 0| 0x81 | 0x0b | 0x00 | 0x00 | 1212 +---------------+---------------+---------------+---------------+ 1213 4| 0x00 | 0x00 | 0x00 | 0x00 | 1214 +---------------+---------------+---------------+---------------+ 1215 8| 0x00 | 0x00 | 0x00 | 0x05 | 1216 +---------------+---------------+---------------+---------------+ 1217 12| 0x00 | 0x00 | 0x00 | 0x00 | 1218 +---------------+---------------+---------------+---------------+ 1219 16| 0x00 | 0x00 | 0x00 | 0x00 | 1220 +---------------+---------------+---------------+---------------+ 1221 20| 0x00 | 0x00 | 0x00 | 0x00 | 1222 +---------------+---------------+---------------+---------------+ 1223 24| 0x31 ('1') | 0x2e ('.') | 0x33 ('3') | 0x2e ('.') | 1224 +---------------+---------------+---------------+---------------+ 1225 28| 0x31 ('1') | 1226 +---------------+ 1227 Total 29 bytes (24 byte header, 5 byte body) 1228 1229Field (offset) (value) 1230Magic (0) : 0x81 1231Opcode (1) : 0x0b 1232Key length (2,3) : 0x0000 1233Extra length (4) : 0x00 1234Data type (5) : 0x00 1235Status (6,7) : 0x0000 1236Total body (8-11) : 0x00000005 1237Opaque (12-15): 0x00000000 1238CAS (16-23): 0x0000000000000000 1239Extras : None 1240Key : None 1241Value : Textual string "1.3.1" 1242 </artwork> 1243 </figure> 1244 </section> 1245 </section> 1246 1247 <section anchor="command-append" title="Append, Prepend"> 1248 <t> 1249 <list style="empty"> 1250 <t>MUST NOT have extras.</t> 1251 <t>MUST have key.</t> 1252 <t>MUST have value.</t> 1253 </list> 1254 </t> 1255 1256 <t> 1257 These commands will either append or prepend the specified 1258 value to the requested key. 1259 </t> 1260 1261 <section anchor="command-append-example" title="Example"> 1262 <t>The following example appends '!' to the 'Hello' key.</t> 1263 <figure> 1264 <preamble>Append request:</preamble> 1265 <artwork> 1266 Byte/ 0 | 1 | 2 | 3 | 1267 / | | | | 1268 |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| 1269 +---------------+---------------+---------------+---------------+ 1270 0| 0x80 | 0x0e | 0x00 | 0x05 | 1271 +---------------+---------------+---------------+---------------+ 1272 4| 0x00 | 0x00 | 0x00 | 0x00 | 1273 +---------------+---------------+---------------+---------------+ 1274 8| 0x00 | 0x00 | 0x00 | 0x06 | 1275 +---------------+---------------+---------------+---------------+ 1276 12| 0x00 | 0x00 | 0x00 | 0x00 | 1277 +---------------+---------------+---------------+---------------+ 1278 16| 0x00 | 0x00 | 0x00 | 0x00 | 1279 +---------------+---------------+---------------+---------------+ 1280 20| 0x00 | 0x00 | 0x00 | 0x00 | 1281 +---------------+---------------+---------------+---------------+ 1282 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 1283 +---------------+---------------+---------------+---------------+ 1284 28| 0x6f ('o') | 0x21 ('!') | 1285 +---------------+---------------+ 1286 Total 30 bytes (24 byte header, 5 byte key, 1 byte value) 1287 1288Field (offset) (value) 1289Magic (0) : 0x80 1290Opcode (1) : 0x0e 1291Key length (2,3) : 0x0005 1292Extra length (4) : 0x00 1293Data type (5) : 0x00 1294Reserved (6,7) : 0x0000 1295Total body (8-11) : 0x00000006 1296Opaque (12-15): 0x00000000 1297CAS (16-23): 0x0000000000000000 1298Extras : None 1299Key (24-28): The textual string "Hello" 1300Value (29) : "!" 1301 </artwork> 1302 </figure> 1303 <t> 1304 The response-packet contains no extra data, and the result of the 1305 operation is signaled through the status code. 1306 </t> 1307 </section> 1308 </section> 1309 1310 <section anchor="command-stat" title="Stat"> 1311 <t> 1312 <list style="empty"> 1313 <t>MUST NOT have extras.</t> 1314 <t>MAY have key.</t> 1315 <t>MUST NOT have value.</t> 1316 </list> 1317 </t> 1318 1319 <t> 1320 Request server statistics. Without a key specified the server will 1321 respond with a "default" set of statistics information. Each piece 1322 of statistical information is returned in its own packet (key 1323 contains the name of the statistical item and the body contains the 1324 value in ASCII format). The sequence of return packets is terminated 1325 with a packet that contains no key and no value. 1326 </t> 1327 <section anchor="command-stat-example" title="Example"> 1328 <t>The following example requests all statistics from the server</t> 1329 <figure> 1330 <preamble>Stat request:</preamble> 1331 <artwork> 1332 Byte/ 0 | 1 | 2 | 3 | 1333 / | | | | 1334 |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| 1335 +---------------+---------------+---------------+---------------+ 1336 0| 0x80 | 0x10 | 0x00 | 0x00 | 1337 +---------------+---------------+---------------+---------------+ 1338 4| 0x00 | 0x00 | 0x00 | 0x00 | 1339 +---------------+---------------+---------------+---------------+ 1340 8| 0x00 | 0x00 | 0x00 | 0x00 | 1341 +---------------+---------------+---------------+---------------+ 1342 12| 0x00 | 0x00 | 0x00 | 0x00 | 1343 +---------------+---------------+---------------+---------------+ 1344 16| 0x00 | 0x00 | 0x00 | 0x00 | 1345 +---------------+---------------+---------------+---------------+ 1346 20| 0x00 | 0x00 | 0x00 | 0x00 | 1347 +---------------+---------------+---------------+---------------+ 1348 Total 24 bytes 1349 1350Field (offset) (value) 1351Magic (0) : 0x80 1352Opcode (1) : 0x10 1353Key length (2,3) : 0x0000 1354Extra length (4) : 0x00 1355Data type (5) : 0x00 1356Reserved (6,7) : 0x0000 1357Total body (8-11) : 0x00000000 1358Opaque (12-15): 0x00000000 1359CAS (16-23): 0x0000000000000000 1360Extras : None 1361Key : None 1362Value : None 1363 </artwork> 1364 </figure> 1365 <t> 1366 The server will send each value in a separate packet with 1367 an "empty" packet (no key / no value) to terminate the sequence. 1368 Each of the response packets look like the following example: 1369 </t> 1370 <figure> 1371 <preamble>Stat response:</preamble> 1372 <artwork> 1373 Byte/ 0 | 1 | 2 | 3 | 1374 / | | | | 1375 |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| 1376 +---------------+---------------+---------------+---------------+ 1377 0| 0x81 | 0x10 | 0x00 | 0x03 | 1378 +---------------+---------------+---------------+---------------+ 1379 4| 0x00 | 0x00 | 0x00 | 0x00 | 1380 +---------------+---------------+---------------+---------------+ 1381 8| 0x00 | 0x00 | 0x00 | 0x07 | 1382 +---------------+---------------+---------------+---------------+ 1383 12| 0x00 | 0x00 | 0x00 | 0x00 | 1384 +---------------+---------------+---------------+---------------+ 1385 16| 0x00 | 0x00 | 0x00 | 0x00 | 1386 +---------------+---------------+---------------+---------------+ 1387 20| 0x00 | 0x00 | 0x00 | 0x00 | 1388 +---------------+---------------+---------------+---------------+ 1389 24| 0x70 ('p') | 0x69 ('i') | 0x64 ('d') | 0x33 ('3') | 1390 +---------------+---------------+---------------+---------------+ 1391 28| 0x30 ('0') | 0x37 ('7') | 0x38 ('8') | 1392 +---------------+---------------+---------------+ 1393 Total 31 bytes (24 byte header, 3 byte key, 4 byte body) 1394 1395Field (offset) (value) 1396Magic (0) : 0x81 1397Opcode (1) : 0x10 1398Key length (2,3) : 0x0003 1399Extra length (4) : 0x00 1400Data type (5) : 0x00 1401Status (6,7) : 0x0000 1402Total body (8-11) : 0x00000007 1403Opaque (12-15): 0x00000000 1404CAS (16-23): 0x0000000000000000 1405Extras : None 1406Key : The textual string "pid" 1407Value : The textual string "3078" 1408 </artwork> 1409 </figure> 1410 </section> 1411 </section> 1412 </section> 1413 <section anchor="security" title="Security Considerations"> 1414 <t> 1415 Memcache has few authentication and no security layers whatsoever. It is 1416 RECOMMENDED that memcache be deployed strictly on closed, protected, 1417 back-end networks within a single data center, within a single cluster of 1418 servers, or even on a single host, providing shared caching for multiple 1419 applications. Memcache MUST NOT be made available on a public network. 1420 </t> 1421 1422 <t> 1423 SASL is supported as an authentication mechanism. See the wiki for more 1424 information. 1425 </t> 1426 </section> 1427 1428 </middle> 1429 1430 <back> 1431 <references title="Normative References"> 1432 <reference anchor="LJ"> 1433 <front> 1434 <title>LJ NEEDS MOAR SPEED</title> 1435 <author fullname="Brad Fitzpatrick"> 1436 <organization>Danga Interactive</organization> 1437 </author> 1438 <date day="5" month="10" year="1999" /> 1439 <abstract> 1440 <t>http://www.livejournal.com/</t> 1441 </abstract> 1442 </front> 1443 </reference> 1444 <dwdrfc-ref anchor="KEYWORDS" src='reference.RFC.2119.xml'/> 1445 </references> 1446 1447 <section anchor="acknowledgments" title="Acknowledgments"> 1448 <t> 1449 Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin 1450 Sallings, for their work on the memcached server. 1451 </t> 1452 1453 <t> 1454 Thanks to Sean Chittenden, Jonathan Steinert, Brian Aker, Evan Martin, 1455 Nathan Neulinger, Eric Hodel, Michael Johnson, Paul Querna, Jamie 1456 McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg, Robin H. 1457 Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean-Francois 1458 Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris Goffinet, Tomash 1459 Brechko, and others for their work reporting bugs and maintaining 1460 memcached client libraries and bindings in many languages. 1461 </t> 1462 </section> 1463 </back> 1464 1465</rfc> 1466 1467