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