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