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