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 12 <front> 13 14 <title> Memcache Binary Protocol </title> 15 16 <author fullname="Aaron Stone" surname="Aaron Stone" role="editor"> 17 <organization>Six Apart, Ltd.</organization> 18 <address> 19 <postal> 20 <street>548 4th Street</street> 21 <city>San Francisco</city> 22 <region>CA</region> 23 <code>94107</code> 24 <country>USA</country> 25 </postal> 26 <email>[email protected]</email> 27 </address> 28 </author> 29 30 <date day="14" month="December" year="2007" /> 31 32 <area>Applications</area> 33 34 <keyword>memcache memcached cache</keyword> 35 36 <abstract> 37 <t> 38 This memo explains the memcache binary protocol for informational purposes. 39 </t> 40 41 <t> 42 Memcache is a high performance key-value cache. It is intentionally a 43 dumb cache, optimized for speed only. Applications using memcache do 44 not rely on it for data -- a persistent database with guaranteed reliability 45 is strongly recommended -- but applications can run much faster when 46 cached data is available in memcache. 47 </t> 48 </abstract> 49 </front> 50 51 <middle> 52 <section anchor="introduction" title="Introduction"> 53 <t> 54 Memcache is a high performance key-value cache. It is intentionally a 55 dumb cache, optimized for speed only. Applications using memcache do 56 not rely on it for data -- a persistent database with guaranteed reliability 57 is strongly recommended -- but applications can run much faster when 58 cached data is available in memcache. 59 </t> 60 <t> 61 Memcache was originally written to make <xref target="LJ">LiveJournal</xref> go faster. 62 It now powers all of the fastest web sites that you love. 63 </t> 64 <section anchor="conventions" title="Conventions Used In This Document"> 65 <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 66 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 67 document are to be interpreted as described in <xref target="KEYWORDS"/>. 68 </t> 69 </section> 70 </section> 71 72 <section anchor="packet" title="Packet Structure"> 73 <t> 74 <figure> 75 <preamble>General format of a packet:</preamble> 76 <artwork> 77 Byte/ 0 | 1 | 2 | 3 | 78 / | | | | 79 |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| 80 +---------------+---------------+---------------+---------------+ 81 0/ HEADER / 82 / / 83 / / 84 / / 85 +---------------+---------------+---------------+---------------+ 86 24/ COMMAND-SPECIFIC EXTRAS (as needed) / 87 +/ (note length in th extras length header field) / 88 +---------------+---------------+---------------+---------------+ 89 m/ Key (as needed) / 90 +/ (note length in key length header field) / 91 +---------------+---------------+---------------+---------------+ 92 n/ Value (as needed) / 93 +/ (note length is total body length header field, minus / 94 +/ sum of the extras and key length body fields) / 95 +---------------+---------------+---------------+---------------+ 96 Total 24 bytes 97 </artwork></figure> 98 </t> 99 100 <t> 101 <figure> 102 <preamble>Request header:</preamble> 103 <artwork> 104 Byte/ 0 | 1 | 2 | 3 | 105 / | | | | 106 |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| 107 +---------------+---------------+---------------+---------------+ 108 0| Magic | Opcode | Key length | 109 +---------------+---------------+---------------+---------------+ 110 4| Extras length | Data type | Reserved | 111 +---------------+---------------+---------------+---------------+ 112 8| Total body length | 113 +---------------+---------------+---------------+---------------+ 114 12| Opaque | 115 +---------------+---------------+---------------+---------------+ 116 16| CAS | 117 | | 118 +---------------+---------------+---------------+---------------+ 119 Total 24 bytes 120 </artwork></figure> 121 </t> 122 123 <t> 124 <figure> 125 <preamble>Response header:</preamble> 126 <artwork> 127 Byte/ 0 | 1 | 2 | 3 | 128 / | | | | 129 |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| 130 +---------------+---------------+---------------+---------------+ 131 0| Magic | Opcode | Key Length | 132 +---------------+---------------+---------------+---------------+ 133 4| Extras length | Data type | Status | 134 +---------------+---------------+---------------+---------------+ 135 8| Total body length | 136 +---------------+---------------+---------------+---------------+ 137 12| Opaque | 138 +---------------+---------------+---------------+---------------+ 139 16| CAS | 140 | | 141 +---------------+---------------+---------------+---------------+ 142 Total 24 bytes 143 </artwork></figure> 144 </t> 145 146 <t> 147 Header fields: 148 <list hangIndent="20" style="hanging"> 149 <t hangText="Magic">Magic number.</t> 150 <t hangText="Opcode">Command code.</t> 151 <t hangText="Key length">Length in bytes of the text key that follows the command extras.</t> 152 <t hangText="Status">Status of the response (non-zero on error).</t> 153 <t hangText="Extras length">Length in bytes of the command extras.</t> 154 <t hangText="Data type">Reserved for future use (Sean is using this soon).</t> 155 <t hangText="Reserved">Really reserved for future use (up for grabs).</t> 156 <t hangText="Total body length">Length in bytes of extra + key + value.</t> 157 <t hangText="Opaque">Will be copied back to you in the response. 158 FIXME: Can this be used to organize <xref target="UDP"/> packets?</t> 159 <t hangText="CAS">Data version check</t> 160 </list> 161 </t> 162 </section> 163 164 <section anchor="values" title="Defined Values"> 165 <section anchor="value-magic" title="Magic Byte"> 166 <t> 167 <list hangIndent="8" style="hanging"> 168 <t hangText="0x80">Request packet for this protocol version</t> 169 <t hangText="0x81">Response packet for this protocol version</t> 170 </list> 171 </t> 172 173 <t> 174 Magic byte / version. For each version of the protocol, we'll use a 175 different request/reponse value pair. This is useful for protocol 176 analyzers to know what a packet is in isolation from which direction 177 it is moving. Note that it is common to run a memcached instance on a 178 host that also runs an application server. Such a host will both send 179 and receive memcache packets. 180 </t> 181 182 <t> 183 The version should hopefully correspond only to different meanings of 184 the command byte. In an ideal world, we will not change the header 185 format. As reserved bytes are given defined meaning, the protocol 186 version / magic byte values should be incremented. 187 </t> 188 189 <t> 190 Traffic analysis tools are encouraged to identify memcache packets 191 and provide detailed interpretation if the magic bytes are recognized 192 and otherwise to provide a generic breakdown of the packet. Note that 193 the key and value positions can always be identified even if the magic 194 byte or command opcode are not recognized. 195 </t> 196 </section> 197 198 <section anchor="value-status" title="Response Status"> 199 <t> 200 Possible values of this two-byte field: 201 <list hangIndent="8" style="hanging"> 202 <t hangText="0x0000">No error</t> 203 <t hangText="0x0001">Key not found</t> 204 <t hangText="0x0002">Key exists</t> 205 <t hangText="0x0003">Value too big</t> 206 <t hangText="0x0004">Invalid arguments</t> 207 <t hangText="0x0005">Item not stored</t> 208 <t hangText="0x0081">Unknown command</t> 209 <t hangText="0x0082">Out of memory</t> 210 </list> 211 </t> 212 </section> 213 214 <section anchor="value-opcodes" title="Command Opcodes"> 215 <t> 216 Possible values of the one-byte field: 217 <list hangIndent="8" style="hanging"> 218 <t hangText="0x00">Get</t> 219 <t hangText="0x01">Set</t> 220 <t hangText="0x02">Add</t> 221 <t hangText="0x03">Replace</t> 222 <t hangText="0x04">Delete</t> 223 <t hangText="0x05">Increment</t> 224 <t hangText="0x06">Decrement</t> 225 <t hangText="0x07">Quit</t> 226 <t hangText="0x08">Flush</t> 227 <t hangText="0x09">GetQ</t> 228 <t hangText="0x0A">No-op</t> 229 <t hangText="0x0B">Version</t> 230 <t hangText="0x0C">GetK</t> 231 <t hangText="0x0D">GetKQ</t> 232 <t hangText="0x0E">Append</t> 233 <t hangText="0x0F">Prepend</t> 234 </list> 235 </t> 236 </section> 237 238 <section anchor="value-types" title="Data Types"> 239 <t> 240 Possible values of the one-byte field: 241 <list hangIndent="8" style="hanging"> 242 <t hangText="0x00">Raw bytes</t> 243 </list> 244 </t> 245 </section> 246 </section> 247 248 <section title="Commands"> 249 <section anchor="command-get" title="Get, Get Quietly, Get Key, Get Key Quietly"> 250 <t> 251 Request: 252 </t> 253 <t> 254 <list style="empty"> 255 <t>MUST NOT have extras.</t> 256 <t>MUST have key.</t> 257 <t>MUST NOT have value.</t> 258 </list> 259 </t> 260 261 <t> 262 <list style="symbols"> 263 <t>4 byte flags</t> 264 </list> 265 </t> 266 267 <t> 268 Response (if found): 269 </t> 270 <t> 271 <list style="empty"> 272 <t>MUST have extras.</t> 273 <t>MAY have key.</t> 274 <t>MAY have value.</t> 275 </list> 276 </t> 277 278 <t> 279 <list style="symbols"> 280 <t>4 byte flags</t> 281 </list> 282 </t> 283 284 <t> 285 <figure> 286 <preamble>Extra data for the get commands:</preamble> 287 <artwork> 288 Byte/ 0 | 1 | 2 | 3 | 289 / | | | | 290 |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| 291 +---------------+---------------+---------------+---------------+ 292 0| Flags | 293 +---------------+---------------+---------------+---------------+ 294 Total 4 bytes 295 </artwork></figure> 296 </t> 297 298 <t> 299 The get command gets a single key. The getq command is both mum 300 on cache miss and quiet, holding its response until a non-quiet 301 command is issued. Getk and getkq differs from get and getq by 302 adding the key into the resonse packet. 303 </t> 304 305 <t> 306 You're not guaranteed a response to a getq/getkq cache hit until 307 you send a non-getq/getkq command later, which uncorks the 308 server which bundles up IOs to send to the client in one go. 309 </t> 310 311 <t> 312 Clients should implement multi-get (still important for 313 reducing network roundtrips!) as n pipelined requests, the 314 first n-1 being getq/getkq, the last being a regular 315 get/getk. that way you're guaranteed to get a response, and 316 you know when the server's done. you can also do the naive 317 thing and send n pipelined get/getks, but then you could potentially 318 get back a lot of "NOT_FOUND!" error code packets. 319 alternatively, you can send 'n' getq/getkqs, followed by an 'echo' 320 or 'noop' command. 321 </t> 322 323 </section> 324 325 <section anchor="command-delete" title="Delete"> 326 <t> 327 <list style="empty"> 328 <t>MAY have extras</t> 329 <t>MUST have key.</t> 330 <t>MUST NOT have value.</t> 331 </list> 332 </t> 333 334 <t> 335 <list style="symbols"> 336 <t>4 byte expiration time</t> 337 </list> 338 </t> 339 340 <t> 341 <figure> 342 <preamble>Extra data for delete:</preamble> 343 <artwork> 344 Byte/ 0 | 1 | 2 | 3 | 345 / | | | | 346 |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| 347 +---------------+---------------+---------------+---------------+ 348 0| Expiration | 349 +---------------+---------------+---------------+---------------+ 350 Total 4 bytes 351 </artwork></figure> 352 </t> 353 354 <t> 355 When allows you to 'reserve' a key. When 'when' is set 356 for, say, ten seconds in the future, the 'add' and 'replace' operations will fail for that key 357 until ten seconds from now. The 'set' operation will succeed regardless of any reserved deletes. 358 FIXME: Is the reservation also cancelled? Say there's a delete with a 10 second hold. Two seconds 359 later, an 'add' is received. It fails. Two second later, a 'set' is received. Is succeeds unconditionally. 360 What if another 'add' is received two more seconds later (a total of six seconds since the original 361 10 second delete-hold, thus still within its purview). 362 </t> 363 364 </section> 365 366 <section anchor="command-flush" title="Flush"> 367 <t> 368 <list style="empty"> 369 <t>MAY have extras</t> 370 <t>MUST NOT have key.</t> 371 <t>MUST NOT have value.</t> 372 </list> 373 </t> 374 375 <t> 376 <list style="symbols"> 377 <t>4 byte expiration time</t> 378 </list> 379 </t> 380 381 <t> 382 <figure> 383 <preamble>Extra data for flush:</preamble> 384 <artwork> 385 Byte/ 0 | 1 | 2 | 3 | 386 / | | | | 387 |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| 388 +---------------+---------------+---------------+---------------+ 389 0| Expiration | 390 +---------------+---------------+---------------+---------------+ 391 Total 4 bytes 392 </artwork></figure> 393 </t> 394 395 <t> 396 Flush the items in the cache now or sometime in the future 397 specified by the expiration field. See the documentation of the 398 textual protocol for the full description on how to specify the 399 expiration time. 400 </t> 401 402 </section> 403 404 <section anchor="command-set" title="Set, Add, Replace"> 405 <t> 406 <list style="empty"> 407 <t>MUST have extras.</t> 408 <t>MUST have key.</t> 409 <t>MUST have value.</t> 410 </list> 411 </t> 412 413 <t> 414 <list style="symbols"> 415 <t>4 byte flags</t> 416 <t>4 byte expiration time</t> 417 </list> 418 </t> 419 420 <t> 421 <figure> 422 <preamble>Extra data for set/add/replace:</preamble> 423 <artwork> 424 Byte/ 0 | 1 | 2 | 3 | 425 / | | | | 426 |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| 427 +---------------+---------------+---------------+---------------+ 428 0| Flags | 429 +---------------+---------------+---------------+---------------+ 430 4| Expiration | 431 +---------------+---------------+---------------+---------------+ 432 Total 8 bytes 433 </artwork></figure> 434 </t> 435 436 <t> 437 If the Data Version Check is present and nonzero, the set MUST succeed if the 438 key exists and has a version identifier identical to the provided value, and 439 MUST NOT succeed if the key does not exist or has a different version identifier. 440 The set response packet will include the same values in all three fields. 441 </t> 442 443 <t> 444 If the CAS field in the header is zero, the set MUST succeed unconditionally. 445 The set response packet will include idential values for flags and expiration, 446 and a new value for Data Version Check, which the client SHOULD keep track of. 447 </t> 448 449 <t> 450 The key MAY be reserved according to <xref target="command-delete"/>, 451 causing the set to fail. 452 </t> 453 </section> 454 455 <section anchor="command-noop" title="noop"> 456 <t> 457 <list style="empty"> 458 <t>MUST NOT have extras.</t> 459 <t>MUST NOT have key.</t> 460 <t>MUST NOT have value.</t> 461 </list> 462 </t> 463 464 <t> 465 Used as a keep alive. Flushes outstanding getq/getkq's. 466 </t> 467 </section> 468 469 <section anchor="command-incr" title="Increment, Decrement"> 470 <t> 471 <list style="empty"> 472 <t>MUST have extras.</t> 473 <t>MUST have key.</t> 474 <t>MUST NOT have value.</t> 475 </list> 476 </t> 477 478 <t> 479 <list style="symbols"> 480 <t>8 byte value to add / subtract (FIXME: Is this unsigned?)</t> 481 <t>8 byte initial value (unsigned)</t> 482 <t>4 byte expiration time</t> 483 </list> 484 </t> 485 486 <t> 487 <figure> 488 <preamble>Extra data for incr/decr:</preamble> 489 <artwork> 490 Byte/ 0 | 1 | 2 | 3 | 491 / | | | | 492 |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| 493 +---------------+---------------+---------------+---------------+ 494 0| Amount to add | 495 | | 496 +---------------+---------------+---------------+---------------+ 497 8| Initial value | 498 | | 499 +---------------+---------------+---------------+---------------+ 500 16| Expiration | 501 +---------------+---------------+---------------+---------------+ 502 Total 20 bytes 503 </artwork></figure> 504 </t> 505 506 <t> 507 <figure> 508 <preamble>incr/decr response body:</preamble> 509 <artwork> 510 Byte/ 0 | 1 | 2 | 3 | 511 / | | | | 512 |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| 513 +---------------+---------------+---------------+---------------+ 514 0| 64-bit unsigned response. | 515 | | 516 +---------------+---------------+---------------+---------------+ 517 Total 8 bytes 518 </artwork></figure> 519 </t> 520 521 <t> 522 These commands will either add or remove the specified 523 amount to the requested counter. 524 525 If the counter does not exist, one of two things may happen: 526 527 <list style="numbers"> 528 <t>If the expiration value is all one-bits (0xffffffff), the 529 operation will fail with NOT_FOUND.</t> 530 <t>For all other expiration values, the operation will succeed 531 by seeding the value for this key with the provided initial 532 value to expire with the provided expiration time.</t> 533 </list> 534 </t> 535 536 <t> 537 Note that in the creation case, flags will be set to zero 538 (FIXME: Should they be provided here as well?) 539 </t> 540 </section> 541 542 <section anchor="command-quit" title="quit"> 543 <t> 544 <list style="empty"> 545 <t>MUST NOT have extras.</t> 546 <t>MUST NOT have key.</t> 547 <t>MUST NOT have value.</t> 548 </list> 549 </t> 550 551 <t> 552 Close the connection to the server. 553 </t> 554 </section> 555 556 <section anchor="command-append" title="Append, Prepend"> 557 <t> 558 <list style="empty"> 559 <t>MUST NOT have extras.</t> 560 <t>MUST have key.</t> 561 <t>MUST have value.</t> 562 </list> 563 </t> 564 565 <t> 566 These commands will either append or prepend the specified 567 value to the requested key. 568 </t> 569 <t> 570 Please note that the CAS field in the header must match the 571 CAS version of the requested item. 572 </t> 573 </section> 574 </section> 575 576 <section title="Example Session"> 577 <t> 578 We start up our application, and asks for the value associated 579 with the 'Hello' key. To send the get request, the following values 580 must be inserted in the header (in network byte order): 581 582Field (offset) (value) 583Magic (0) : 0x80 584Opcode (1) : 0x00 585Key length (2,3) : 0x0005 586Extra length (4) : 0x00 587Data type (5) : 0x00 588Reserved (6,7) : 0x0000 589Total body (8-11) : 0x00000005 590Opaque (12-15): 0x00000000 591CAS (16-23): 0x0000000000000000 592Extras : None 593Key (24-29): The textual string: "Hello" 594Value : None 595 596The packet looks like: 597 598 <figure> 599 <preamble>Get request:</preamble> 600 <artwork> 601 602 Byte/ 0 | 1 | 2 | 3 | 603 / | | | | 604 |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| 605 +---------------+---------------+---------------+---------------+ 606 0| 0x80 | 0x00 | 0x00 | 0x05 | 607 +---------------+---------------+---------------+---------------+ 608 4| 0x00 | 0x00 | 0x00 | 0x00 | 609 +---------------+---------------+---------------+---------------+ 610 8| 0x00 | 0x00 | 0x00 | 0x05 | 611 +---------------+---------------+---------------+---------------+ 612 12| 0x00 | 0x00 | 0x00 | 0x00 | 613 +---------------+---------------+---------------+---------------+ 614 16| 0x00 | 0x00 | 0x00 | 0x00 | 615 +---------------+---------------+---------------+---------------+ 616 20| 0x00 | 0x00 | 0x00 | 0x00 | 617 +---------------+---------------+---------------+---------------+ 618 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 619 +---------------+---------------+---------------+---------------+ 620 28| 0x6f ('o') | 621 +---------------+ 622 623 Total 29 bytes (24 byte header, and 5 bytes key) 624 </artwork></figure> 625 </t> 626 627 <t> 628 Since nobody has set this key yet, it returns "Not found". 629 630 <figure> 631 <preamble>Get response:</preamble> 632 <artwork> 633 634 Byte/ 0 | 1 | 2 | 3 | 635 / | | | | 636 |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| 637 +---------------+---------------+---------------+---------------+ 638 0| 0x81 | 0x00 | 0x00 | 0x00 | 639 +---------------+---------------+---------------+---------------+ 640 4| 0x00 | 0x00 | 0x00 | 0x01 | 641 +---------------+---------------+---------------+---------------+ 642 8| 0x00 | 0x00 | 0x00 | 0x09 | 643 +---------------+---------------+---------------+---------------+ 644 12| 0x00 | 0x00 | 0x00 | 0x00 | 645 +---------------+---------------+---------------+---------------+ 646 16| 0x00 | 0x00 | 0x00 | 0x00 | 647 +---------------+---------------+---------------+---------------+ 648 20| 0x00 | 0x00 | 0x00 | 0x00 | 649 +---------------+---------------+---------------+---------------+ 650 24| 0x4e ('N') | 0x6f ('o') | 0x74 ('t') | 0x20 (' ') | 651 +---------------+---------------+---------------+---------------+ 652 28| 0x66 ('f') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | 653 +---------------+---------------+---------------+---------------+ 654 32| 0x64 ('d') | 655 +---------------+ 656 657 Total 33 bytes (24 byte header, and 9 bytes value) 658 </artwork></figure> 659 660 The above packet is interpreted as: 661 662Field (offset) (value) 663Magic (0) : 0x81 664Opcode (1) : 0x00 665Key length (2,3) : 0x0000 666Extra length (4) : 0x00 667Data type (5) : 0x00 668Status (6,7) : 0x0001 669Total body (8-11) : 0x00000009 670Opaque (12-15): 0x00000000 671CAS (16-23): 0x0000000000000000 672Extras : None 673Key : None 674Value (24-32): The textual string "Not found" 675 </t> 676 677 <t> 678 Well, looks like we need to add the key! Let's set it to "World" with 679 0xdeadbeef as flags and to expire in two hours. The following values 680 should be inserted into the header: 681 682Field (offset) (value) 683Magic (0) : 0x80 684Opcode (1) : 0x02 685Key length (2,3) : 0x0005 686Extra length (4) : 0x08 687Data type (5) : 0x00 688Reserved (6,7) : 0x0000 689Total body (8-11) : 0x00000012 690Opaque (12-15): 0x00000000 691CAS (16-23): 0x0000000000000000 692Extras : 693 Flags (24-27): 0xdeadbeef 694 Expiry (28-31): 0x00000e10 695Key (32-36): The textual string "Hello" 696Value (37-41): The textual string "World" 697 698The packet looks like: 699 700 <figure> 701 <preamble>Add request:</preamble> 702 <artwork> 703 704 Byte/ 0 | 1 | 2 | 3 | 705 / | | | | 706 |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| 707 +---------------+---------------+---------------+---------------+ 708 0| 0x80 | 0x02 | 0x00 | 0x05 | 709 +---------------+---------------+---------------+---------------+ 710 4| 0x08 | 0x00 | 0x00 | 0x00 | 711 +---------------+---------------+---------------+---------------+ 712 8| 0x00 | 0x00 | 0x00 | 0x12 | 713 +---------------+---------------+---------------+---------------+ 714 12| 0x00 | 0x00 | 0x00 | 0x00 | 715 +---------------+---------------+---------------+---------------+ 716 16| 0x00 | 0x00 | 0x00 | 0x00 | 717 +---------------+---------------+---------------+---------------+ 718 20| 0x00 | 0x00 | 0x00 | 0x00 | 719 +---------------+---------------+---------------+---------------+ 720 24| 0xde | 0xad | 0xbe | 0xef | 721 +---------------+---------------+---------------+---------------+ 722 28| 0x00 | 0x00 | 0x0e | 0x10 | 723 +---------------+---------------+---------------+---------------+ 724 32| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 725 +---------------+---------------+---------------+---------------+ 726 36| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 727 +---------------+---------------+---------------+---------------+ 728 40| 0x6c ('l') | 0x64 ('d') | 729 +---------------+---------------+ 730 731 Total 42 bytes (24 byte header, 8 byte extras, 5 byte key and 5 byte value) 732 </artwork></figure> 733 </t> 734 735 <t> 736 The add succeeds and the following packet is returned: 737 <figure> 738 <preamble>Add response:</preamble> 739 <artwork> 740 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| 0x81 | 0x02 | 0x00 | 0x00 | 746 +---------------+---------------+---------------+---------------+ 747 4| 0x00 | 0x00 | 0x00 | 0x00 | 748 +---------------+---------------+---------------+---------------+ 749 8| 0x00 | 0x00 | 0x00 | 0x00 | 750 +---------------+---------------+---------------+---------------+ 751 12| 0x00 | 0x00 | 0x00 | 0x00 | 752 +---------------+---------------+---------------+---------------+ 753 16| 0x00 | 0x00 | 0x00 | 0x00 | 754 +---------------+---------------+---------------+---------------+ 755 20| 0x00 | 0x00 | 0x00 | 0x01 | 756 +---------------+---------------+---------------+---------------+ 757 758 Total 24 bytes 759 </artwork></figure> 760 761 The above packet is interpreted as: 762 763Field (offset) (value) 764Magic (0) : 0x81 765Opcode (1) : 0x02 766Key length (2,3) : 0x0000 767Extra length (4) : 0x00 768Data type (5) : 0x00 769Status (6,7) : 0x0000 770Total body (8-11) : 0x00000000 771Opaque (12-15): 0x00000000 772CAS (16-23): 0x0000000000000001 773Extras : None 774Key : None 775Value : None 776 777 </t> 778 779 <t> 780 If the original get request is sent again, the key would be found and 781 the following packet is returned. 782 783 <figure> 784 <preamble>Get response:</preamble> 785 <artwork> 786 787 Byte/ 0 | 1 | 2 | 3 | 788 / | | | | 789 |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| 790 +---------------+---------------+---------------+---------------+ 791 0| 0x81 | 0x00 | 0x00 | 0x00 | 792 +---------------+---------------+---------------+---------------+ 793 4| 0x04 | 0x00 | 0x00 | 0x00 | 794 +---------------+---------------+---------------+---------------+ 795 8| 0x00 | 0x00 | 0x00 | 0x09 | 796 +---------------+---------------+---------------+---------------+ 797 12| 0x00 | 0x00 | 0x00 | 0x00 | 798 +---------------+---------------+---------------+---------------+ 799 16| 0x00 | 0x00 | 0x00 | 0x00 | 800 +---------------+---------------+---------------+---------------+ 801 20| 0x00 | 0x00 | 0x00 | 0x01 | 802 +---------------+---------------+---------------+---------------+ 803 24| 0xde | 0xad | 0xbe | 0xef | 804 +---------------+---------------+---------------+---------------+ 805 28| 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 0x6c ('l') | 806 +---------------+---------------+---------------+---------------+ 807 32| 0x64 ('d') | 808 +---------------+ 809 810 Total 33 bytes (24 byte header, 4 byte extras and 5 byte value) 811 </artwork></figure> 812 813 The above packet is interpreted as: 814 815Field (offset) (value) 816Magic (0) : 0x81 817Opcode (1) : 0x00 818Key length (2,3) : 0x0000 819Extra length (4) : 0x04 820Data type (5) : 0x00 821Status (6,7) : 0x0000 822Total body (8-11) : 0x00000009 823Opaque (12-15): 0x00000000 824CAS (16-23): 0x0000000000000001 825Extras : None 826 Flags (24-27): 0xdeadbeef 827Key : None 828Value (28-32): The textual string "World" 829 830 </t> 831 <t> 832 If we send the add request one more time the add will fail, and the 833 following packet is returned: 834 835 <figure> 836 <preamble>Get response:</preamble> 837 <artwork> 838 839 Byte/ 0 | 1 | 2 | 3 | 840 / | | | | 841 |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| 842 +---------------+---------------+---------------+---------------+ 843 0| 0x81 | 0x02 | 0x00 | 0x00 | 844 +---------------+---------------+---------------+---------------+ 845 4| 0x00 | 0x00 | 0x00 | 0x02 | 846 +---------------+---------------+---------------+---------------+ 847 8| 0x00 | 0x00 | 0x00 | 0x14 | 848 +---------------+---------------+---------------+---------------+ 849 12| 0x00 | 0x00 | 0x00 | 0x00 | 850 +---------------+---------------+---------------+---------------+ 851 16| 0x00 | 0x00 | 0x00 | 0x00 | 852 +---------------+---------------+---------------+---------------+ 853 20| 0x00 | 0x00 | 0x00 | 0x00 | 854 +---------------+---------------+---------------+---------------+ 855 24| 0x44 ('D') | 0x61 ('a') | 0x74 ('t') | 0x61 ('a') | 856 +---------------+---------------+---------------+---------------+ 857 28| 0x20 (' ') | 0x65 ('e') | 0x78 ('x') | 0x69 ('i') | 858 +---------------+---------------+---------------+---------------+ 859 32| 0x73 ('s') | 0x74 ('t') | 0x73 ('s') | 0x20 (' ') | 860 +---------------+---------------+---------------+---------------+ 861 36| 0x66 ('f') | 0x6f ('o') | 0x72 ('r') | 0x20 (' ') | 862 +---------------+---------------+---------------+---------------+ 863 40| 0x6b ('k') | 0x65 ('e') | 0x79 ('y') | 0x2e ('.') | 864 +---------------+---------------+---------------+---------------+ 865 866 Total 44 bytes (24 byte header, 24 byte value) 867 </artwork></figure> 868 869 The above packet is interpreted as: 870 871Field (offset) (value) 872Magic (0) : 0x81 873Opcode (1) : 0x02 874Key length (2,3) : 0x0000 875Extra length (4) : 0x00 876Data type (5) : 0x00 877Status (6,7) : 0x0002 878Total body (8-11) : 0x00000014 879Opaque (12-15): 0x00000000 880CAS (16-23): 0x0000000000000000 881Extras : None 882Key : None 883Value (24-43): The textual string "Data exists for key." 884 </t> 885 <t> 886 To send a "noop" command, insert the following values in the request: 887 888Field (offset) (value) 889Magic (0) : 0x80 890Opcode (1) : 0x0a 891Key length (2,3) : 0x0000 892Extra length (4) : 0x00 893Data type (5) : 0x00 894Reserved (6,7) : 0x0000 895Total body (8-11) : 0x00000000 896Opaque (12-15): 0x00000000 897CAS (16-23): 0x0000000000000000 898Extras : None 899Key : None 900Value : None 901 902The packet looks like: 903 904 <figure> 905 <preamble>Noop request:</preamble> 906 <artwork> 907 908 Byte/ 0 | 1 | 2 | 3 | 909 / | | | | 910 |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| 911 +---------------+---------------+---------------+---------------+ 912 0| 0x80 | 0x0a | 0x00 | 0x00 | 913 +---------------+---------------+---------------+---------------+ 914 4| 0x00 | 0x00 | 0x00 | 0x00 | 915 +---------------+---------------+---------------+---------------+ 916 8| 0x00 | 0x00 | 0x00 | 0x00 | 917 +---------------+---------------+---------------+---------------+ 918 12| 0x00 | 0x00 | 0x00 | 0x00 | 919 +---------------+---------------+---------------+---------------+ 920 16| 0x00 | 0x00 | 0x00 | 0x00 | 921 +---------------+---------------+---------------+---------------+ 922 20| 0x00 | 0x00 | 0x00 | 0x00 | 923 +---------------+---------------+---------------+---------------+ 924 925 Total 24 bytes 926 </artwork></figure> 927 </t> 928 <t> 929 The server will respond with the following packet: 930 931 <figure> 932 <preamble>Noop response:</preamble> 933 <artwork> 934 935 Byte/ 0 | 1 | 2 | 3 | 936 / | | | | 937 |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| 938 +---------------+---------------+---------------+---------------+ 939 0| 0x81 | 0x0a | 0x00 | 0x00 | 940 +---------------+---------------+---------------+---------------+ 941 4| 0x00 | 0x00 | 0x00 | 0x00 | 942 +---------------+---------------+---------------+---------------+ 943 8| 0x00 | 0x00 | 0x00 | 0x00 | 944 +---------------+---------------+---------------+---------------+ 945 12| 0x00 | 0x00 | 0x00 | 0x00 | 946 +---------------+---------------+---------------+---------------+ 947 16| 0x00 | 0x00 | 0x00 | 0x00 | 948 +---------------+---------------+---------------+---------------+ 949 20| 0x00 | 0x00 | 0x00 | 0x00 | 950 +---------------+---------------+---------------+---------------+ 951 952 Total 24 bytes 953 </artwork></figure> 954 955 The above packet is interpreted as: 956 957Field (offset) (value) 958Magic (0) : 0x81 959Opcode (1) : 0x0a 960Key length (2,3) : 0x0000 961Extra length (4) : 0x00 962Data type (5) : 0x00 963Status (6,7) : 0x0000 964Total body (8-11) : 0x00000000 965Opaque (12-15): 0x00000000 966CAS (16-23): 0x0000000000000000 967Extras : None 968Key : None 969Value : None 970 </t> 971 <t> 972 So lets go ahead and append '!' to the 'Hello' key. To do so, 973 insert the following in the packet: 974 975Field (offset) (value) 976Magic (0) : 0x80 977Opcode (1) : 0x0e 978Key length (2,3) : 0x0005 979Extra length (4) : 0x00 980Data type (5) : 0x00 981Reserved (6,7) : 0x0000 982Total body (8-11) : 0x00000006 983Opaque (12-15): 0x00000000 984CAS (16-23): 0x0000000000000000 985Extras : None 986Key (24-28): The textual string "Hello" 987Value (29) : None 988 989The packet looks like: 990 991 <figure> 992 <preamble>Append request:</preamble> 993 <artwork> 994 995 Byte/ 0 | 1 | 2 | 3 | 996 / | | | | 997 |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| 998 +---------------+---------------+---------------+---------------+ 999 0| 0x80 | 0x0e | 0x00 | 0x05 | 1000 +---------------+---------------+---------------+---------------+ 1001 4| 0x00 | 0x00 | 0x00 | 0x00 | 1002 +---------------+---------------+---------------+---------------+ 1003 8| 0x00 | 0x00 | 0x00 | 0x06 | 1004 +---------------+---------------+---------------+---------------+ 1005 12| 0x00 | 0x00 | 0x00 | 0x00 | 1006 +---------------+---------------+---------------+---------------+ 1007 16| 0x00 | 0x00 | 0x00 | 0x00 | 1008 +---------------+---------------+---------------+---------------+ 1009 20| 0x00 | 0x00 | 0x00 | 0x00 | 1010 +---------------+---------------+---------------+---------------+ 1011 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 1012 +---------------+---------------+---------------+---------------+ 1013 28| 0x6f ('o') | 0x21 ('!') | 1014 +---------------+---------------+ 1015 1016 Total 30 bytes (24 byte header, 5 byte key, 1 byte value) 1017 </artwork></figure> 1018 </t> 1019 <t> 1020 The server will respond with the following packet 1021 <figure> 1022 <preamble>Append response:</preamble> 1023 <artwork> 1024 1025 Byte/ 0 | 1 | 2 | 3 | 1026 / | | | | 1027 |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| 1028 +---------------+---------------+---------------+---------------+ 1029 0| 0x81 | 0x0e | 0x00 | 0x00 | 1030 +---------------+---------------+---------------+---------------+ 1031 4| 0x00 | 0x00 | 0x00 | 0x00 | 1032 +---------------+---------------+---------------+---------------+ 1033 8| 0x00 | 0x00 | 0x00 | 0x00 | 1034 +---------------+---------------+---------------+---------------+ 1035 12| 0x00 | 0x00 | 0x00 | 0x00 | 1036 +---------------+---------------+---------------+---------------+ 1037 16| 0x00 | 0x00 | 0x00 | 0x00 | 1038 +---------------+---------------+---------------+---------------+ 1039 20| 0x00 | 0x00 | 0x00 | 0x02 | 1040 +---------------+---------------+---------------+---------------+ 1041 1042 Total 24 bytes 1043 </artwork></figure> 1044 1045 The above packet is interpreted as: 1046 1047Field (offset) (value) 1048Magic (0) : 0x81 1049Opcode (1) : 0x0e 1050Key length (2,3) : 0x0000 1051Extra length (4) : 0x00 1052Data type (5) : 0x00 1053Status (6,7) : 0x0000 1054Total body (8-11) : 0x00000000 1055Opaque (12-15): 0x00000000 1056CAS (16-23): 0x0000000000000002 1057Extras : None 1058Key : None 1059Value : None 1060 1061 </t> 1062 <t> 1063 Lets prepend '!' to the 'Hello' key. To do so, insert the following in 1064 the packet: 1065 1066Field (offset) (value) 1067Magic (0) : 0x80 1068Opcode (1) : 0x0f 1069Key length (2,3) : 0x0005 1070Extra length (4) : 0x00 1071Data type (5) : 0x00 1072Reserved (6,7) : 0x0000 1073Total body (8-11) : 0x00000006 1074Opaque (12-15): 0x00000000 1075CAS (16-23): 0x0000000000000002 1076Extras : None 1077Key (24-28): The textual string "Hello" 1078Value (29) : The textual string "!" 1079 1080The packet looks like: 1081 1082 <figure> 1083 <preamble>Prepend request:</preamble> 1084 <artwork> 1085 1086 Byte/ 0 | 1 | 2 | 3 | 1087 / | | | | 1088 |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| 1089 +---------------+---------------+---------------+---------------+ 1090 0| 0x80 | 0x0f | 0x00 | 0x05 | 1091 +---------------+---------------+---------------+---------------+ 1092 4| 0x00 | 0x00 | 0x00 | 0x00 | 1093 +---------------+---------------+---------------+---------------+ 1094 8| 0x00 | 0x00 | 0x00 | 0x06 | 1095 +---------------+---------------+---------------+---------------+ 1096 12| 0x00 | 0x00 | 0x00 | 0x00 | 1097 +---------------+---------------+---------------+---------------+ 1098 16| 0x00 | 0x00 | 0x00 | 0x00 | 1099 +---------------+---------------+---------------+---------------+ 1100 20| 0x00 | 0x00 | 0x00 | 0x02 | 1101 +---------------+---------------+---------------+---------------+ 1102 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 1103 +---------------+---------------+---------------+---------------+ 1104 28| 0x6f ('o') | 0x21 ('!') | 1105 +---------------+---------------+ 1106 1107 Total 30 bytes (24 bytes header, 5 byte key, 1 byte value) 1108 </artwork></figure> 1109 </t> 1110 <t> 1111 The server will respond with the following packet: 1112 1113 <figure> 1114 <preamble>Prepend response:</preamble> 1115 <artwork> 1116 1117 Byte/ 0 | 1 | 2 | 3 | 1118 / | | | | 1119 |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| 1120 +---------------+---------------+---------------+---------------+ 1121 0| 0x81 | 0x0f | 0x00 | 0x00 | 1122 +---------------+---------------+---------------+---------------+ 1123 4| 0x00 | 0x00 | 0x00 | 0x00 | 1124 +---------------+---------------+---------------+---------------+ 1125 8| 0x00 | 0x00 | 0x00 | 0x00 | 1126 +---------------+---------------+---------------+---------------+ 1127 12| 0x00 | 0x00 | 0x00 | 0x00 | 1128 +---------------+---------------+---------------+---------------+ 1129 16| 0x00 | 0x00 | 0x00 | 0x00 | 1130 +---------------+---------------+---------------+---------------+ 1131 20| 0x00 | 0x00 | 0x00 | 0x03 | 1132 +---------------+---------------+---------------+---------------+ 1133 1134 Total 24 bytes 1135 </artwork></figure> 1136 1137 The above packet is interpreted as: 1138 1139Field (offset) (value) 1140Magic (0) : 0x81 1141Opcode (1) : 0x0f 1142Key length (2,3) : 0x0000 1143Extra length (4) : 0x00 1144Data type (5) : 0x00 1145Status (6,7) : 0x0000 1146Total body (8-11) : 0x00000000 1147Opaque (12-15): 0x00000000 1148CAS (16-23): 0x0000000000000003 1149Extras : None 1150Key : None 1151Value : None 1152 1153 </t> 1154 <t> 1155 Let's just replace the content of the 'Hello' key with 'World' 1156 (with 0xdeadbeef as flags, 2 hour expiry time). The packet should 1157 have the following content: 1158 1159Field (offset) (value) 1160Magic (0) : 0x80 1161Opcode (1) : 0x03 1162Key length (2,3) : 0x0005 1163Extra length (4) : 0x08 1164Data type (5) : 0x00 1165Reserved (6,7) : 0x0000 1166Total body (8-11) : 0x00000012 1167Opaque (12-15): 0x00000000 1168CAS (16-23): 0x0000000000000000 1169Extras : 1170 Flags (24-27): 0xdeadbeef 1171 Expiry (28-31): 0x00000e10 1172Key (32-36): The textual string "Hello" 1173Value (37-41): The textual string "World" 1174 1175The packet looks like: 1176 1177 <figure> 1178 <preamble>Replace request:</preamble> 1179 <artwork> 1180 1181 Byte/ 0 | 1 | 2 | 3 | 1182 / | | | | 1183 |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| 1184 +---------------+---------------+---------------+---------------+ 1185 0| 0x80 | 0x03 | 0x00 | 0x05 | 1186 +---------------+---------------+---------------+---------------+ 1187 4| 0x08 | 0x00 | 0x00 | 0x00 | 1188 +---------------+---------------+---------------+---------------+ 1189 8| 0x00 | 0x00 | 0x00 | 0x12 | 1190 +---------------+---------------+---------------+---------------+ 1191 12| 0x00 | 0x00 | 0x00 | 0x00 | 1192 +---------------+---------------+---------------+---------------+ 1193 16| 0x00 | 0x00 | 0x00 | 0x00 | 1194 +---------------+---------------+---------------+---------------+ 1195 20| 0x00 | 0x00 | 0x00 | 0x00 | 1196 +---------------+---------------+---------------+---------------+ 1197 24| 0xde | 0xad | 0xbe | 0xef | 1198 +---------------+---------------+---------------+---------------+ 1199 28| 0x00 | 0x00 | 0x0e | 0x10 | 1200 +---------------+---------------+---------------+---------------+ 1201 32| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 1202 +---------------+---------------+---------------+---------------+ 1203 36| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 1204 +---------------+---------------+---------------+---------------+ 1205 40| 0x6c ('l') | 0x64 ('d') | 1206 +---------------+---------------+ 1207 1208 Total 42 byes (24 byte header, 8 byte extras, 5 byte key and 5 byte value) 1209 </artwork></figure></t> 1210 1211 <t> 1212 The server will respond with the following packet 1213 1214 <figure> 1215 <preamble>Replace response:</preamble> 1216 <artwork> 1217 1218 Byte/ 0 | 1 | 2 | 3 | 1219 / | | | | 1220 |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| 1221 +---------------+---------------+---------------+---------------+ 1222 0| 0x81 | 0x03 | 0x00 | 0x00 | 1223 +---------------+---------------+---------------+---------------+ 1224 4| 0x00 | 0x00 | 0x00 | 0x00 | 1225 +---------------+---------------+---------------+---------------+ 1226 8| 0x00 | 0x00 | 0x00 | 0x00 | 1227 +---------------+---------------+---------------+---------------+ 1228 12| 0x00 | 0x00 | 0x00 | 0x00 | 1229 +---------------+---------------+---------------+---------------+ 1230 16| 0x00 | 0x00 | 0x00 | 0x00 | 1231 +---------------+---------------+---------------+---------------+ 1232 20| 0x00 | 0x00 | 0x00 | 0x04 | 1233 +---------------+---------------+---------------+---------------+ 1234 1235 Total 24 bytes 1236 </artwork></figure> 1237 1238 The above packet is interpreted as: 1239 1240Field (offset) (value) 1241Magic (0) : 0x81 1242Opcode (1) : 0x03 1243Key length (2,3) : 0x0000 1244Extra length (4) : 0x00 1245Data type (5) : 0x00 1246Status (6,7) : 0x0000 1247Total body (8-11) : 0x00000000 1248Opaque (12-15): 0x00000000 1249CAS (16-23): 0x0000000000000004 1250Extras : None 1251Key : None 1252Value : None 1253 1254 </t> 1255 <t> 1256 To delete the "Hello" key, set the following fields in the request: 1257 1258Field (offset) (value) 1259Magic (0) : 0x80 1260Opcode (1) : 0x04 1261Key length (2,3) : 0x0005 1262Extra length (4) : 0x00 1263Data type (5) : 0x00 1264Reserved (6,7) : 0x0000 1265Total body (8-11) : 0x00000005 1266Opaque (12-15): 0x00000000 1267CAS (16-23): 0x0000000000000000 1268Extras : None 1269Key : The textual string "Hello" 1270Value : None 1271 1272The packet looks like: 1273 1274 <figure> 1275 <preamble>Delete request:</preamble> 1276 <artwork> 1277 1278 Byte/ 0 | 1 | 2 | 3 | 1279 / | | | | 1280 |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| 1281 +---------------+---------------+---------------+---------------+ 1282 0| 0x80 | 0x04 | 0x00 | 0x05 | 1283 +---------------+---------------+---------------+---------------+ 1284 4| 0x00 | 0x00 | 0x00 | 0x00 | 1285 +---------------+---------------+---------------+---------------+ 1286 8| 0x00 | 0x00 | 0x00 | 0x05 | 1287 +---------------+---------------+---------------+---------------+ 1288 12| 0x00 | 0x00 | 0x00 | 0x00 | 1289 +---------------+---------------+---------------+---------------+ 1290 16| 0x00 | 0x00 | 0x00 | 0x00 | 1291 +---------------+---------------+---------------+---------------+ 1292 20| 0x00 | 0x00 | 0x00 | 0x00 | 1293 +---------------+---------------+---------------+---------------+ 1294 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 1295 +---------------+---------------+---------------+---------------+ 1296 28| 0x6f ('o') | 1297 +---------------+ 1298 1299 Total 29 bytes (24 byte header, 5 byte value) 1300 </artwork></figure> 1301 </t> 1302 <t> 1303 The server will respond with the following package: 1304 <figure> 1305 <preamble>Delete response:</preamble> 1306 <artwork> 1307 1308 Byte/ 0 | 1 | 2 | 3 | 1309 / | | | | 1310 |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| 1311 +---------------+---------------+---------------+---------------+ 1312 0| 0x81 | 0x04 | 0x00 | 0x00 | 1313 +---------------+---------------+---------------+---------------+ 1314 4| 0x00 | 0x00 | 0x00 | 0x00 | 1315 +---------------+---------------+---------------+---------------+ 1316 8| 0x00 | 0x00 | 0x00 | 0x00 | 1317 +---------------+---------------+---------------+---------------+ 1318 12| 0x00 | 0x00 | 0x00 | 0x00 | 1319 +---------------+---------------+---------------+---------------+ 1320 16| 0x00 | 0x00 | 0x00 | 0x00 | 1321 +---------------+---------------+---------------+---------------+ 1322 20| 0x00 | 0x00 | 0x00 | 0x00 | 1323 +---------------+---------------+---------------+---------------+ 1324 1325 Total 24 bytes 1326 </artwork></figure> 1327 1328 The above packet is interpreted as: 1329 1330Field (offset) (value) 1331Magic (0) : 0x81 1332Opcode (1) : 0x04 1333Key length (2,3) : 0x0000 1334Extra length (4) : 0x00 1335Data type (5) : 0x00 1336Status (6,7) : 0x0000 1337Total body (8-11) : 0x00000000 1338Opaque (12-15): 0x00000000 1339CAS (16-23): 0x0000000000000000 1340Extras : None 1341Key : None 1342Value : None 1343 </t> 1344 1345 <t> 1346 To flush the cache (delete all items), the set the following values 1347 in the request: 1348 1349Field (offset) (value) 1350Magic (0) : 0x80 1351Opcode (1) : 0x08 1352Key length (2,3) : 0x0000 1353Extra length (4) : 0x00 1354Data type (5) : 0x00 1355Reserved (6,7) : 0x0000 1356Total body (8-11) : 0x00000000 1357Opaque (12-15): 0x00000000 1358CAS (16-23): 0x0000000000000000 1359Extras : None 1360Key : None 1361Value : None 1362 1363The packet looks like: 1364 1365 <figure> 1366 <preamble>Flush request:</preamble> 1367 <artwork> 1368 1369 Byte/ 0 | 1 | 2 | 3 | 1370 / | | | | 1371 |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| 1372 +---------------+---------------+---------------+---------------+ 1373 0| 0x80 | 0x08 | 0x00 | 0x00 | 1374 +---------------+---------------+---------------+---------------+ 1375 4| 0x00 | 0x00 | 0x00 | 0x00 | 1376 +---------------+---------------+---------------+---------------+ 1377 8| 0x00 | 0x00 | 0x00 | 0x00 | 1378 +---------------+---------------+---------------+---------------+ 1379 12| 0x00 | 0x00 | 0x00 | 0x00 | 1380 +---------------+---------------+---------------+---------------+ 1381 16| 0x00 | 0x00 | 0x00 | 0x00 | 1382 +---------------+---------------+---------------+---------------+ 1383 20| 0x00 | 0x00 | 0x00 | 0x00 | 1384 +---------------+---------------+---------------+---------------+ 1385 1386 Total 24 bytes 1387 </artwork></figure></t> 1388 1389 <t> 1390 The server responds with: 1391 <figure> 1392 <preamble>Flush response:</preamble> 1393 <artwork> 1394 1395 Byte/ 0 | 1 | 2 | 3 | 1396 / | | | | 1397 |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| 1398 +---------------+---------------+---------------+---------------+ 1399 0| 0x81 | 0x08 | 0x00 | 0x00 | 1400 +---------------+---------------+---------------+---------------+ 1401 4| 0x00 | 0x00 | 0x00 | 0x00 | 1402 +---------------+---------------+---------------+---------------+ 1403 8| 0x00 | 0x00 | 0x00 | 0x00 | 1404 +---------------+---------------+---------------+---------------+ 1405 12| 0x00 | 0x00 | 0x00 | 0x00 | 1406 +---------------+---------------+---------------+---------------+ 1407 16| 0x00 | 0x00 | 0x00 | 0x00 | 1408 +---------------+---------------+---------------+---------------+ 1409 20| 0x00 | 0x00 | 0x00 | 0x00 | 1410 +---------------+---------------+---------------+---------------+ 1411 1412 Total 24 bytes 1413 </artwork></figure> 1414 1415 The above packet is interpreted as: 1416 1417Field (offset) (value) 1418Magic (0) : 0x81 1419Opcode (1) : 0x08 1420Key length (2,3) : 0x0000 1421Extra length (4) : 0x00 1422Data type (5) : 0x00 1423Status (6,7) : 0x0000 1424Total body (8-11) : 0x00000000 1425Opaque (12-15): 0x00000000 1426CAS (16-23): 0x0000000000000000 1427Extras : None 1428Key : None 1429Value : None 1430 </t> 1431 1432 <t> 1433 Lets use the increment function to increment a 64-bit variable stored 1434 as the key "counter". We specify 0 as the initial value, and set it to 1435 expire after 2 hours. To do so, the following values must be set in 1436 the request: 1437 1438Field (offset) (value) 1439Magic (0) : 0x80 1440Opcode (1) : 0x05 1441Key length (2,3) : 0x0007 1442Extra length (4) : 0x14 1443Data type (5) : 0x00 1444Reserved (6,7) : 0x0000 1445Total body (8-11) : 0x0000001b 1446Opaque (12-15): 0x00000000 1447CAS (16-23): 0x0000000000000000 1448Extras : 1449 delta (24-31): 0x0000000000000001 1450 initial (32-39): 0x0000000000000000 1451 exipration (40-43): 0x00000e10 1452Key : Textual string "counter" 1453Value : None 1454 1455The packet looks like: 1456 1457 <figure> 1458 <preamble>Increment request:</preamble> 1459 <artwork> 1460 1461 Byte/ 0 | 1 | 2 | 3 | 1462 / | | | | 1463 |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| 1464 +---------------+---------------+---------------+---------------+ 1465 0| 0x80 | 0x05 | 0x00 | 0x07 | 1466 +---------------+---------------+---------------+---------------+ 1467 4| 0x14 | 0x00 | 0x00 | 0x00 | 1468 +---------------+---------------+---------------+---------------+ 1469 8| 0x00 | 0x00 | 0x00 | 0x1b | 1470 +---------------+---------------+---------------+---------------+ 1471 12| 0x00 | 0x00 | 0x00 | 0x00 | 1472 +---------------+---------------+---------------+---------------+ 1473 16| 0x00 | 0x00 | 0x00 | 0x00 | 1474 +---------------+---------------+---------------+---------------+ 1475 20| 0x00 | 0x00 | 0x00 | 0x00 | 1476 +---------------+---------------+---------------+---------------+ 1477 24| 0x00 | 0x00 | 0x00 | 0x00 | 1478 +---------------+---------------+---------------+---------------+ 1479 28| 0x00 | 0x00 | 0x00 | 0x01 | 1480 +---------------+---------------+---------------+---------------+ 1481 32| 0x00 | 0x00 | 0x00 | 0x00 | 1482 +---------------+---------------+---------------+---------------+ 1483 36| 0x00 | 0x00 | 0x00 | 0x00 | 1484 +---------------+---------------+---------------+---------------+ 1485 40| 0x00 | 0x00 | 0x0e | 0x10 | 1486 +---------------+---------------+---------------+---------------+ 1487 44| 0x63 ('c') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | 1488 +---------------+---------------+---------------+---------------+ 1489 48| 0x74 ('t') | 0x65 ('e') | 0x72 ('r') | 1490 +---------------+---------------+---------------+ 1491 1492 Total 51 bytes (24 byte header, 20 byte extras, 7 byte key) 1493 </artwork></figure></t> 1494 1495 <t> 1496 Since the key doesn't exist, the server will respond with the 1497 initial value: 1498 1499 <figure> 1500 <preamble>Increment response:</preamble> 1501 <artwork> 1502 1503 Byte/ 0 | 1 | 2 | 3 | 1504 / | | | | 1505 |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| 1506 +---------------+---------------+---------------+---------------+ 1507 0| 0x81 | 0x05 | 0x00 | 0x00 | 1508 +---------------+---------------+---------------+---------------+ 1509 4| 0x00 | 0x00 | 0x00 | 0x00 | 1510 +---------------+---------------+---------------+---------------+ 1511 8| 0x00 | 0x00 | 0x00 | 0x08 | 1512 +---------------+---------------+---------------+---------------+ 1513 12| 0x00 | 0x00 | 0x00 | 0x00 | 1514 +---------------+---------------+---------------+---------------+ 1515 16| 0x00 | 0x00 | 0x00 | 0x00 | 1516 +---------------+---------------+---------------+---------------+ 1517 20| 0x00 | 0x00 | 0x00 | 0x05 | 1518 +---------------+---------------+---------------+---------------+ 1519 24| 0x00 | 0x00 | 0x00 | 0x00 | 1520 +---------------+---------------+---------------+---------------+ 1521 28| 0x00 | 0x00 | 0x00 | 0x00 | 1522 +---------------+---------------+---------------+---------------+ 1523 1524 Total 32 bytes (24 byte header, 8 byte value) 1525 </artwork></figure> 1526 1527 The above packet is interpreted as: 1528 1529Field (offset) (value) 1530Magic (0) : 0x81 1531Opcode (1) : 0x05 1532Key length (2,3) : 0x0000 1533Extra length (4) : 0x00 1534Data type (5) : 0x00 1535Status (6,7) : 0x0000 1536Total body (8-11) : 0x00000008 1537Opaque (12-15): 0x00000000 1538CAS (16-23): 0x0000000000000005 1539Extras : None 1540Key : None 1541Value : 0x0000000000000000 1542 </t> 1543 1544 <t> 1545 Lets use the decrement function to decrement a 64-bit variable stored 1546 as the key "counter". We specify 0 as the initial value, and set it to 1547 expire after 2 hours. To do so, the following values must be set in 1548 the request: 1549 1550Field (offset) (value) 1551Magic (0) : 0x80 1552Opcode (1) : 0x06 1553Key length (2,3) : 0x0007 1554Extra length (4) : 0x14 1555Data type (5) : 0x00 1556Reserved (6,7) : 0x0000 1557Total body (8-11) : 0x0000001b 1558Opaque (12-15): 0x00000000 1559CAS (16-23): 0x0000000000000000 1560Extras : 1561 delta (24-31): 0x0000000000000001 1562 initial (32-39): 0x0000000000000000 1563 exipration (40-43): 0x00000e10 1564Key : Textual string "counter" 1565Value : None 1566 1567The packet looks like: 1568 1569 <figure> 1570 <preamble>Decrement request:</preamble> 1571 <artwork> 1572 1573 Byte/ 0 | 1 | 2 | 3 | 1574 / | | | | 1575 |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| 1576 +---------------+---------------+---------------+---------------+ 1577 0| 0x80 | 0x06 | 0x00 | 0x07 | 1578 +---------------+---------------+---------------+---------------+ 1579 4| 0x14 | 0x00 | 0x00 | 0x00 | 1580 +---------------+---------------+---------------+---------------+ 1581 8| 0x00 | 0x00 | 0x00 | 0x1b | 1582 +---------------+---------------+---------------+---------------+ 1583 12| 0x00 | 0x00 | 0x00 | 0x00 | 1584 +---------------+---------------+---------------+---------------+ 1585 16| 0x00 | 0x00 | 0x00 | 0x00 | 1586 +---------------+---------------+---------------+---------------+ 1587 20| 0x00 | 0x00 | 0x00 | 0x00 | 1588 +---------------+---------------+---------------+---------------+ 1589 24| 0x00 | 0x00 | 0x00 | 0x00 | 1590 +---------------+---------------+---------------+---------------+ 1591 28| 0x00 | 0x00 | 0x00 | 0x01 | 1592 +---------------+---------------+---------------+---------------+ 1593 32| 0x00 | 0x00 | 0x00 | 0x00 | 1594 +---------------+---------------+---------------+---------------+ 1595 36| 0x00 | 0x00 | 0x00 | 0x00 | 1596 +---------------+---------------+---------------+---------------+ 1597 40| 0x00 | 0x00 | 0x0e | 0x10 | 1598 +---------------+---------------+---------------+---------------+ 1599 44| 0x63 ('c') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | 1600 +---------------+---------------+---------------+---------------+ 1601 48| 0x74 ('t') | 0x65 ('e') | 0x72 ('r') | 1602 +---------------+---------------+---------------+ 1603 1604 Total 51 bytes (24 byte header, 20 byte extras, 7 byte key) 1605 </artwork></figure></t> 1606 1607 <t> 1608 The server will decrement the counter and return the following packet: 1609 1610 <figure> 1611 <preamble>Decrement response:</preamble> 1612 <artwork> 1613 1614 Byte/ 0 | 1 | 2 | 3 | 1615 / | | | | 1616 |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| 1617 +---------------+---------------+---------------+---------------+ 1618 0| 0x81 | 0x06 | 0x00 | 0x00 | 1619 +---------------+---------------+---------------+---------------+ 1620 4| 0x00 | 0x00 | 0x00 | 0x00 | 1621 +---------------+---------------+---------------+---------------+ 1622 8| 0x00 | 0x00 | 0x00 | 0x08 | 1623 +---------------+---------------+---------------+---------------+ 1624 12| 0x00 | 0x00 | 0x00 | 0x00 | 1625 +---------------+---------------+---------------+---------------+ 1626 16| 0x00 | 0x00 | 0x00 | 0x00 | 1627 +---------------+---------------+---------------+---------------+ 1628 20| 0x00 | 0x00 | 0x00 | 0x00 | 1629 +---------------+---------------+---------------+---------------+ 1630 24| 0x00 | 0x00 | 0x00 | 0x00 | 1631 +---------------+---------------+---------------+---------------+ 1632 28| 0x00 | 0x00 | 0x00 | 0x00 | 1633 +---------------+---------------+---------------+---------------+ 1634 1635 Total: 32 bytes (24 byte header, 8 byte value) 1636 </artwork></figure> 1637 1638 The above packet is interpreted as: 1639 1640Field (offset) (value) 1641Magic (0) : 0x81 1642Opcode (1) : 0x06 1643Key length (2,3) : 0x0000 1644Extra length (4) : 0x00 1645Data type (5) : 0x00 1646Status (6,7) : 0x0000 1647Total body (8-11) : 0x00000008 1648Opaque (12-15): 0x00000000 1649CAS (16-23): 0x0000000000000000 1650Extras : None 1651Key : None 1652Value : 0x0000000000000000 1653 1654 You might be wondering why 0 is returned and not -1 (since the key 1655 exists with the value 0), but the decr-function will never return a 1656 negative number. 1657 </t> 1658 1659 <t> 1660 To end the session to the server, set the following values in the 1661 header: 1662 1663Field (offset) (value) 1664Magic (0) : 0x80 1665Opcode (1) : 0x07 1666Key length (2,3) : 0x0000 1667Extra length (4) : 0x00 1668Data type (5) : 0x00 1669Reserved (6,7) : 0x0000 1670Total body (8-11) : 0x00000000 1671Opaque (12-15): 0x00000000 1672CAS (16-23): 0x0000000000000000 1673Extras : None 1674Key : None 1675Value : None 1676 1677The packet looks like: 1678 1679 <figure> 1680 <preamble>Quit request:</preamble> 1681 <artwork> 1682 1683 Byte/ 0 | 1 | 2 | 3 | 1684 / | | | | 1685 |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| 1686 +---------------+---------------+---------------+---------------+ 1687 0| 0x80 | 0x07 | 0x00 | 0x00 | 1688 +---------------+---------------+---------------+---------------+ 1689 4| 0x00 | 0x00 | 0x00 | 0x00 | 1690 +---------------+---------------+---------------+---------------+ 1691 8| 0x00 | 0x00 | 0x00 | 0x00 | 1692 +---------------+---------------+---------------+---------------+ 1693 12| 0x00 | 0x00 | 0x00 | 0x00 | 1694 +---------------+---------------+---------------+---------------+ 1695 16| 0x00 | 0x00 | 0x00 | 0x00 | 1696 +---------------+---------------+---------------+---------------+ 1697 20| 0x00 | 0x00 | 0x00 | 0x00 | 1698 +---------------+---------------+---------------+---------------+ 1699 1700 Total 24 bytes 1701 </artwork></figure></t> 1702 1703 <t> 1704 The server will respond with the following packet: 1705 1706 <figure> 1707 <preamble>Quit response:</preamble> 1708 <artwork> 1709 1710 Byte/ 0 | 1 | 2 | 3 | 1711 / | | | | 1712 |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| 1713 +---------------+---------------+---------------+---------------+ 1714 0| 0x81 | 0x07 | 0x00 | 0x00 | 1715 +---------------+---------------+---------------+---------------+ 1716 4| 0x00 | 0x00 | 0x00 | 0x00 | 1717 +---------------+---------------+---------------+---------------+ 1718 8| 0x00 | 0x00 | 0x00 | 0x00 | 1719 +---------------+---------------+---------------+---------------+ 1720 12| 0x00 | 0x00 | 0x00 | 0x00 | 1721 +---------------+---------------+---------------+---------------+ 1722 16| 0x00 | 0x00 | 0x00 | 0x00 | 1723 +---------------+---------------+---------------+---------------+ 1724 20| 0x00 | 0x00 | 0x00 | 0x00 | 1725 +---------------+---------------+---------------+---------------+ 1726 1727 Total 24 bytes 1728 </artwork></figure> 1729 1730 The above packet is interpreted as: 1731 1732Field (offset) (value) 1733Magic (0) : 0x81 1734Opcode (1) : 0x07 1735Key length (2,3) : 0x0000 1736Extra length (4) : 0x00 1737Data type (5) : 0x00 1738Status (6,7) : 0x0000 1739Total body (8-11) : 0x00000000 1740Opaque (12-15): 0x00000000 1741CAS (16-23): 0x0000000000000000 1742Extras : None 1743Key : None 1744Value : None 1745 </t> 1746 </section> 1747 1748 <section anchor="security" title="Security Considerations"> 1749 <t> 1750 Memcache has no authentication or security layers whatsoever. It is 1751 RECOMMENDED that memcache be deployed strictly on closed, protected, 1752 back-end networks within a single data center, within a single cluster of 1753 servers, or even on a single host, providing shared caching for multiple 1754 applications. Memcache MUST NOT be made available on a public network. 1755 </t> 1756 </section> 1757 1758 </middle> 1759 1760 <back> 1761 <references title="Normative References"> 1762 <reference anchor="LJ"> 1763 <front> 1764 <title>LJ NEEDS MOAR SPEED</title> 1765 <author fullname="Brad Fitzpatrick"> 1766 <organization>Danga Interactive</organization> 1767 </author> 1768 <date day="5" month="10" year="1999" /> 1769 <abstract> 1770 <t>http://www.livejournal.com/</t> 1771 </abstract> 1772 </front> 1773 </reference> 1774 <dwdrfc-ref anchor='UDP' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.0768.xml'/> 1775 <dwdrfc-ref anchor='KEYWORDS' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/> 1776 </references> 1777 1778 <section anchor="acknowledgments" title="Acknowledgments"> 1779 <t> 1780 Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin 1781 Sallings, for their work on the memcached server. 1782 </t> 1783 1784 <t> 1785 Thanks to Sean Chittenden, Jonathan Steinert, Brian Aker, Evan Martin, 1786 Nathan Neulinger, Eric Hodel, Michael Johnson, Paul Querna, Jamie 1787 McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg, Robin H. 1788 Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean-Francois 1789 Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris Goffinet, Tomash 1790 Brechko, and others for their work reporting bugs and maintaining 1791 memcached client libraries and bindings in many languages. 1792 </t> 1793 </section> 1794 </back> 1795 1796</rfc> 1797 1798