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