diff options
| author | dormando <dormando@rydia.net> | 2022-08-25 14:27:48 -0700 |
|---|---|---|
| committer | dormando <dormando@rydia.net> | 2022-08-25 14:27:48 -0700 |
| commit | 0fd38f9986795f41fe7b8a4191789c52db953da0 (patch) | |
| tree | 1ea2720021917dfa52ddd02fafbce61b76eb5b2a /doc | |
| parent | cfe751ef9fa05b19ec70d4314718d1b3df23f38c (diff) | |
| download | memcached-0fd38f9986795f41fe7b8a4191789c52db953da0.tar.gz | |
docs: don't rebuild binprot XML anymore
xml2rfc's toolchain has bitrotted and I don't intend on changing the
binary protocol documentation anymore. Instead I've included the .txt
files from 1.6.16 and commented out the build docs.
Even if I adjust the call args for xml2rfc it complains about the
copyright being old and I don't want to think about that :(
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 30 | ||||
| -rw-r--r-- | doc/protocol-binary-range.txt | 280 | ||||
| -rw-r--r-- | doc/protocol-binary.full | 1498 | ||||
| -rw-r--r-- | doc/protocol-binary.txt | 1736 |
4 files changed, 3529 insertions, 15 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 3539fc8..5359daa 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -10,24 +10,24 @@ EXTRA_DIST += $(SPECIFICATIONS) BUILT_SOURCES = MOSTLYCLEANFILES = -if BUILD_SPECIFICATIONS -BUILT_SOURCES += $(SPECIFICATIONS) -MOSTLYCLEANFILES += $(SPECIFICATIONS) -endif +#if BUILD_SPECIFICATIONS +#BUILT_SOURCES += $(SPECIFICATIONS) +#MOSTLYCLEANFILES += $(SPECIFICATIONS) +#endif -RFC2629_XSL = $(srcdir)/xml2rfc/rfc2629-noinc.xsl -RFC2629_DTD = $(srcdir)/xml2rfc/rfc2629.dtd +#RFC2629_XSL = $(srcdir)/xml2rfc/rfc2629-noinc.xsl +#RFC2629_DTD = $(srcdir)/xml2rfc/rfc2629.dtd -%.txt: %.full $(RFC2629_DTD) - @XML2RFC@ -d $(RFC2629_DTD) -c $(builddir) $< $@ - -%.full: %.xml $(RFC2629_XSL) - @XSLTPROC@ --nonet $(RFC2629_XSL) $< > $@ +#%.txt: %.full $(RFC2629_DTD) +# @XML2RFC@ -d $(RFC2629_DTD) -c $(builddir) $< $@ +# +#%.full: %.xml $(RFC2629_XSL) +# @XSLTPROC@ --nonet $(RFC2629_XSL) $< > $@ # Prevent make from deleting intermediate files -all-full: $(SPECIFICATIONS:.txt=.full) +#all-full: $(SPECIFICATIONS:.txt=.full) -clean-local: - rm -f $(SPECIFICATIONS:.txt=.full) +#clean-local: +# rm -f $(SPECIFICATIONS:.txt=.full) -.PHONY: all-full +#.PHONY: all-full diff --git a/doc/protocol-binary-range.txt b/doc/protocol-binary-range.txt new file mode 100644 index 0000000..53f52a1 --- /dev/null +++ b/doc/protocol-binary-range.txt @@ -0,0 +1,280 @@ + + + + +Network Working Group Aaron Stone, Ed. +Internet-Draft Six Apart, Ltd. +Intended status: Informational December 14, 2007 +Expires: June 16, 2008 + + + Memcache Binary Protocol: Extensions for UDP + draft-stone-memcache-udp-01 + +Abstract + + This memo explains extensions to the memcache binary protocol for use + in a UDP environment. + + Memcache is a high performance key-value cache. It is intentionally + a dumb cache, optimized for speed only. Applications using memcache + do not rely on it for data -- a persistent database with guaranteed + reliability is strongly recommended -- but applications can run much + faster when cached data is available in memcache. + +Status of This Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at http://datatracker.ietf.org/drafts/current/. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on June 16, 2008. + +Copyright Notice + + Copyright (c) 2007 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + + + +Aaron Stone Expires June 16, 2008 [Page 1] + +Internet-Draft Memcache Over UDP December 2007 + + + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 + 1.1. Conventions Used In This Document . . . . . . . . . . . . 2 + 2. Defined Values . . . . . . . . . . . . . . . . . . . . . . . 3 + 2.1. Magic Byte . . . . . . . . . . . . . . . . . . . . . . . 3 + 2.2. Response Status . . . . . . . . . . . . . . . . . . . . . 3 + 2.3. Command Opcodes . . . . . . . . . . . . . . . . . . . . . 3 + 2.4. Data Types . . . . . . . . . . . . . . . . . . . . . . . 3 + 3. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 3.1. Get Response . . . . . . . . . . . . . . . . . . . . . . 3 + 3.2. Get Range Request . . . . . . . . . . . . . . . . . . . . 4 + 3.3. Get Range Response . . . . . . . . . . . . . . . . . . . 4 + 4. Security Considerations . . . . . . . . . . . . . . . . . . . 5 + 5. Normative References . . . . . . . . . . . . . . . . . . . . 5 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5 + +1. Introduction + + Memcache is a high performance key-value cache. It is intentionally + a dumb cache, optimized for speed only. Applications using memcache + do not rely on it for data -- a persistent database with guaranteed + reliability is strongly recommended -- but applications can run much + faster when cached data is available in memcache. + + Sites may find that, due to their network architecture or application + usage patterns, the stateless [UDP] protocol better suits their + needs. This document provides extensions and descriptions of use of + the memcache protocol [MEMCACHE] in a UDP environment. + + It is a goal of this document to provide sufficient information in + each UDP packet as to avoid any requirement for statefulness on the + part of the server nor significant caching of outstanding packets on + the part of the client. + +1.1. Conventions Used In This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [KEYWORDS]. + + + + + + + +Aaron Stone Expires June 16, 2008 [Page 2] + +Internet-Draft Memcache Over UDP December 2007 + + +2. Defined Values + +2.1. Magic Byte + + The magic bytes remains the same as in [MEMCACHE]. + +2.2. Response Status + + Additional status values: + + 0x0004 Value is larger than a single response packet + +2.3. Command Opcodes + + Additional opcode values: + + 0x0C Get Range + 0x0D Set Range + +2.4. Data Types + + There are no new data types in this extension. + +3. Commands + +3.1. Get Response + + This section extends the behavior of the Get and GetQ commands as + described in [MEMCACHE]. + + When a Get or GetQ request is made via UDP, and the value of the key + for which the request was made is larger than can be placed into a + single UDP packet (noting that the protocol header must also be + counted), a Get Range response packet MUST be sent instead of the Get + response packet. In this instance: + + 1. The Status field of the response header MUST be 0x0004. + 2. The Offset field of the GetR response extras MUST be 0. + 3. The Length field of the GetR response extras, and the data + contained in the Value field of the packet, SHOULD be the maximum + allowed length of a UDP packet, less the space required by the + header and extras; however it MAY be any amount below this + maximum. + 4. The Total value length field of the response extras MUST be the + actual length of the complete value. + + The client, upon receipt of a Get Range response bearing Status 0x004 + and a Message ID corresponding to its Get request, shall then know + + + +Aaron Stone Expires June 16, 2008 [Page 3] + +Internet-Draft Memcache Over UDP December 2007 + + + that it has received only the first portion of the value. The client + MAY choose to request the remaining portion of the value by sending + one or more Get Range requests. + +3.2. Get Range Request + + The Get Range request is primarily intended for use over a UDP + transport to request byte ranges of the value for a key. In the + event that the Data version check fails to match that of the key, an + error MUST be returned. + + Extra data for get range request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Flags | + +---------------+---------------+---------------+---------------+ + 4| Data version check | + | | + +---------------+---------------+---------------+---------------+ + 12| Offset | + +---------------+---------------+---------------+---------------+ + 16| Length | + +---------------+---------------+---------------+---------------+ + Total 20 bytes + +3.3. Get Range Response + + The Get Range request is primarily intended for use over a UDP + transport to indicate the location of the bytes of the value for a + key contained in a given packet. A client receives enough + information in each Get Range extras to construct an appropriately + sized buffer in its own memory and blindly insert the contents of the + packet at the given byte offset. + + + + + + + + + + + + + + + +Aaron Stone Expires June 16, 2008 [Page 4] + +Internet-Draft Memcache Over UDP December 2007 + + + Extra data for get range response: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Flags | + +---------------+---------------+---------------+---------------+ + 4| Data version check | + | | + +---------------+---------------+---------------+---------------+ + 12| Offset | + +---------------+---------------+---------------+---------------+ + 16| Length | + +---------------+---------------+---------------+---------------+ + 20| Total value length | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + +4. Security Considerations + + This document does not introduce any new security considerations + beyond those discussed in [MEMCACHE]. + +5. Normative References + + [KEYWORDS] + Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [MEMCACHE] + Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [UDP] Postel, J., "User Datagram Protocol", STD 6, RFC 768, + August 1980. + +Author's Address + + Aaron Stone (editor) + Six Apart, Ltd. + 548 4th Street + San Francisco, CA 94107 + USA + + Email: aaron@serendipity.palo-alto.ca.us + + + + + +Aaron Stone Expires June 16, 2008 [Page 5] diff --git a/doc/protocol-binary.full b/doc/protocol-binary.full new file mode 100644 index 0000000..7e8c017 --- /dev/null +++ b/doc/protocol-binary.full @@ -0,0 +1,1498 @@ +<?xml version="1.0"?> +<?rfc toc="yes"?><?rfc strict="yes"?><?rfc symrefs="yes"?><?rfc sortrefs="yes" ?><?rfc compact="yes" ?><?rfc subcompact="yes" ?><rfc category="info" docName="draft-stone-memcache-binary-01" ipr="trust200902" obsoletes="" updates="" submissionType="IETF" xml:lang="en"> + <front> + <title> Memcache Binary Protocol </title> + + <author fullname="Aaron Stone" surname="Stone" role="editor"> + <organization>Six Apart, Ltd.</organization> + <address> + <postal> + <street>548 4th Street</street> + <city>San Francisco</city> + <region>CA</region> + <code>94107</code> + <country>USA</country> + </postal> + <email>aaron@serendipity.palo-alto.ca.us</email> + </address> + </author> + <author fullname="Trond Norbye" surname="Norbye" role="editor"> + <organization>Sun Microsystems, INC</organization> + <address> + <postal> + <street>Haakon VII g. 7B</street> + <city>Trondheim</city> + <code>NO-7485 Trondheim</code> + <country>Norway</country> + </postal> + <email>trond.norbye@sun.com</email> + </address> + </author> + <date day="28" month="August" year="2008"/> + <area>Applications</area> + <keyword>memcache memcached cache</keyword> + <abstract> + <t> + This memo explains the memcache binary protocol for informational + purposes. + </t> + <t> + Memcache is a high performance key-value cache. It is intentionally a + dumb cache, optimized for speed only. Applications using memcache do + not rely on it for data -- a persistent database with guaranteed + reliability is strongly recommended -- but applications can run much + faster when cached data is available in memcache. + </t> + </abstract> + </front> + + <middle> + <section anchor="introduction" title="Introduction" toc="default"> + <t> + Memcache is a high performance key-value cache. It is intentionally a + dumb cache, optimized for speed only. Applications using memcache should + not rely on it for data -- a persistent database with guaranteed + reliability is strongly recommended -- but applications can run much + faster when cached data is available in memcache. + </t> + <t> + Memcache was originally written to make + <xref target="LJ">LiveJournal</xref> faster. It now powers all of + the fastest web sites that you love. + </t> + <section anchor="conventions" title="Conventions Used In This Document" toc="default"> + <t> + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in + <xref target="KEYWORDS"/>. + </t> + </section> + </section> + + <section anchor="packet" title="Packet Structure" toc="default"> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>General format of a packet:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0/ HEADER / + / / + / / + / / + +---------------+---------------+---------------+---------------+ + 24/ COMMAND-SPECIFIC EXTRAS (as needed) / + +/ (note length in the extras length header field) / + +---------------+---------------+---------------+---------------+ + m/ Key (as needed) / + +/ (note length in key length header field) / + +---------------+---------------+---------------+---------------+ + n/ Value (as needed) / + +/ (note length is total body length header field, minus / + +/ sum of the extras and key length body fields) / + +---------------+---------------+---------------+---------------+ + Total 24 bytes + </artwork> + </figure> + + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Request header:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Magic | Opcode | Key length | + +---------------+---------------+---------------+---------------+ + 4| Extras length | Data type | Reserved | + +---------------+---------------+---------------+---------------+ + 8| Total body length | + +---------------+---------------+---------------+---------------+ + 12| Opaque | + +---------------+---------------+---------------+---------------+ + 16| CAS | + | | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + </artwork> + </figure> + + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Response header:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Magic | Opcode | Key Length | + +---------------+---------------+---------------+---------------+ + 4| Extras length | Data type | Status | + +---------------+---------------+---------------+---------------+ + 8| Total body length | + +---------------+---------------+---------------+---------------+ + 12| Opaque | + +---------------+---------------+---------------+---------------+ + 16| CAS | + | | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + </artwork> + </figure> + + <t> + Header fields: + <list hangIndent="20" style="hanging"> + <t hangText="Magic">Magic number.</t> + <t hangText="Opcode">Command code.</t> + <t hangText="Key length">Length in bytes of the text key that follows the command extras.</t> + <t hangText="Status">Status of the response (non-zero on error).</t> + <t hangText="Extras length">Length in bytes of the command extras.</t> + <t hangText="Data type">Reserved for future use (Sean is using this soon).</t> + <t hangText="Reserved">Really reserved for future use (up for grabs).</t> + <t hangText="Total body length">Length in bytes of extra + key + value.</t> + <t hangText="Opaque">Will be copied back to you in the response.</t> + <t hangText="CAS">Data version check.</t> + </list> + </t> + </section> + + <section anchor="values" title="Defined Values" toc="default"> + <section anchor="value-magic" title="Magic Byte" toc="default"> + <t> + <list hangIndent="8" style="hanging"> + <t hangText="0x80">Request packet for this protocol version</t> + <t hangText="0x81">Response packet for this protocol version</t> + </list> + </t> + + <t> + Magic byte / version. For each version of the protocol, we'll use a + different request/response value pair. This is useful for protocol + analyzers to distinguish the nature of the packet from the direction + which it is moving. Note, it is common to run a memcached instance on + a host that also runs an application server. Such a host will both + send and receive memcache packets. + </t> + + <t> + The version should hopefully correspond only to different meanings of + the command byte. In an ideal world, we will not change the header + format. As reserved bytes are given defined meaning, the protocol + version / magic byte values should be incremented. + </t> + + <t> + Traffic analysis tools are encouraged to identify memcache packets + and provide detailed interpretation if the magic bytes are recognized + and otherwise to provide a generic breakdown of the packet. Note, that + the key and value positions can always be identified even if the magic + byte or command opcode are not recognized. + </t> + </section> + + <section anchor="value-status" title="Response Status" toc="default"> + <t> + Possible values of this two-byte field: + <list hangIndent="8" style="hanging"> + <t hangText="0x0000">No error</t> + <t hangText="0x0001">Key not found</t> + <t hangText="0x0002">Key exists</t> + <t hangText="0x0003">Value too large</t> + <t hangText="0x0004">Invalid arguments</t> + <t hangText="0x0005">Item not stored</t> + <t hangText="0x0006">Incr/Decr on non-numeric value.</t> + <t hangText="0x0081">Unknown command</t> + <t hangText="0x0082">Out of memory</t> + </list> + </t> + </section> + + <section anchor="value-opcodes" title="Command Opcodes" toc="default"> + <t> + Possible values of the one-byte field: + <list hangIndent="8" style="hanging"> + <t hangText="0x00">Get</t> + <t hangText="0x01">Set</t> + <t hangText="0x02">Add</t> + <t hangText="0x03">Replace</t> + <t hangText="0x04">Delete</t> + <t hangText="0x05">Increment</t> + <t hangText="0x06">Decrement</t> + <t hangText="0x07">Quit</t> + <t hangText="0x08">Flush</t> + <t hangText="0x09">GetQ</t> + <t hangText="0x0A">No-op</t> + <t hangText="0x0B">Version</t> + <t hangText="0x0C">GetK</t> + <t hangText="0x0D">GetKQ</t> + <t hangText="0x0E">Append</t> + <t hangText="0x0F">Prepend</t> + <t hangText="0x10">Stat</t> + <t hangText="0x11">SetQ</t> + <t hangText="0x12">AddQ</t> + <t hangText="0x13">ReplaceQ</t> + <t hangText="0x14">DeleteQ</t> + <t hangText="0x15">IncrementQ</t> + <t hangText="0x16">DecrementQ</t> + <t hangText="0x17">QuitQ</t> + <t hangText="0x18">FlushQ</t> + <t hangText="0x19">AppendQ</t> + <t hangText="0x1A">PrependQ</t> + </list> + </t> + <t> + As a convention all of the commands ending with "Q" for + Quiet. A quiet version of a command will omit responses + that are considered uninteresting. Whether a given response + is interesting is dependent upon the command. See the + descriptions of the + <xref target="command-get">set commands</xref> + and <xref target="command-set">set commands</xref> for + examples of commands that include quiet variants. + </t> + </section> + + <section anchor="value-types" title="Data Types" toc="default"> + <t> + Possible values of the one-byte field: + <list hangIndent="8" style="hanging"> + <t hangText="0x00">Raw bytes</t> + </list> + </t> + </section> + </section> + + <section title="Commands" toc="default"> + <section anchor="command-introduction" title="Introduction" toc="default"> + <t> + All communication is initiated by a request from the client, + and the server will respond to each request with zero or + multiple packets for each request. If the status code of a response + packet is non-nil, the body of the packet will contain a textual error + message. If the status code is nil, the command opcode will define the + layout of the body of the message. + </t> + <section anchor="command-introduction-example" title="Example" toc="default"> + <t> + The following figure illustrates the packet layout for + a packet with an error message. + </t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Packet layout:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x09 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x4e ('N') | 0x6f ('o') | 0x74 ('t') | 0x20 (' ') | + +---------------+---------------+---------------+---------------+ + 28| 0x66 ('f') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | + +---------------+---------------+---------------+---------------+ + 32| 0x64 ('d') | + +---------------+ + Total 33 bytes (24 byte header, and 9 bytes value) + +Field (offset) (value) +Magic (0) : 0x81 +Opcode (1) : 0x00 +Key length (2,3) : 0x0000 +Extra length (4) : 0x00 +Data type (5) : 0x00 +Status (6,7) : 0x0001 +Total body (8-11) : 0x00000009 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000000 +Extras : None +Key : None +Value (24-32): The textual string "Not found" + </artwork> + </figure> + </section> + </section> + + <section anchor="command-get" title="Get, Get Quietly, Get Key, Get Key Quietly" toc="default"> + <t> + Request: + </t> + <t> + <list style="empty"> + <t>MUST NOT have extras.</t> + <t>MUST have key.</t> + <t>MUST NOT have value.</t> + </list> + </t> + + <t> + Response (if found): + </t> + <t> + <list style="empty"> + <t>MUST have extras.</t> + <t>MAY have key.</t> + <t>MAY have value.</t> + </list> + </t> + + <t> + <list style="symbols"> + <t>4 byte flags</t> + </list> + </t> + + <t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Extra data for the get commands:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Flags | + +---------------+---------------+---------------+---------------+ + + Total 4 bytes + </artwork> + </figure> + </t> + + <t> + The get command gets a single key. The getq command is both mum + on cache miss and quiet, holding its response until a non-quiet + command is issued. Getk and getkq differs from get and getq by + adding the key into the response packet. + </t> + + <t> + You're not guaranteed a response to a getq/getkq cache hit until + you send a non-getq/getkq command later, which uncorks the + server and bundles up IOs to send to the client in one go. + </t> + + <t> + Clients should implement multi-get (still important for + reducing network roundtrips!) as n pipelined requests, the + first n-1 being getq/getkq, the last being a regular + get/getk. That way you're guaranteed to get a response, and + you know when the server's done. You can also do the naive + thing and send n pipelined get/getks, but then you could potentially + get back a lot of "NOT_FOUND" error code packets. + Alternatively, you can send 'n' getq/getkqs, followed by a + 'noop' command. + </t> + + <section anchor="command-get-example" title="Example" toc="default"> + <t> + To request the data associated with the key "Hello" the + following fields must be specified in the packet. + </t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>get request:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 28| 0x6f ('o') | + +---------------+ + + Total 29 bytes (24 byte header, and 5 bytes key) + +Field (offset) (value) +Magic (0) : 0x80 +Opcode (1) : 0x00 +Key length (2,3) : 0x0005 +Extra length (4) : 0x00 +Data type (5) : 0x00 +Reserved (6,7) : 0x0000 +Total body (8-11) : 0x00000005 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000000 +Extras : None +Key (24-29): The textual string: "Hello" +Value : None + </artwork> + </figure> + <t>If the item exist on the server the following packet is returned, + otherwise a packet with status code != 0 will be returned (see + <xref target="command-introduction">Introduction</xref>) + </t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>get/getq response:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x04 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x09 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + 24| 0xde | 0xad | 0xbe | 0xef | + +---------------+---------------+---------------+---------------+ + 28| 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 32| 0x64 ('d') | + +---------------+ + + Total 33 bytes (24 byte header, 4 byte extras and 5 byte value) + +Field (offset) (value) +Magic (0) : 0x81 +Opcode (1) : 0x00 +Key length (2,3) : 0x0000 +Extra length (4) : 0x04 +Data type (5) : 0x00 +Status (6,7) : 0x0000 +Total body (8-11) : 0x00000009 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000001 +Extras : + Flags (24-27): 0xdeadbeef +Key : None +Value (28-32): The textual string "World" + </artwork> + </figure> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>getk/getkq response:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x04 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x09 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + 24| 0xde | 0xad | 0xbe | 0xef | + +---------------+---------------+---------------+---------------+ + 28| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 32| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | + +---------------+---------------+---------------+---------------+ + 36| 0x6c ('l') | 0x64 ('d') | + +---------------+---------------+ + + Total 38 bytes (24 byte header, 4 byte extras, 5 byte key + and 5 byte value) + +Field (offset) (value) +Magic (0) : 0x81 +Opcode (1) : 0x00 +Key length (2,3) : 0x0005 +Extra length (4) : 0x04 +Data type (5) : 0x00 +Status (6,7) : 0x0000 +Total body (8-11) : 0x0000000E +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000001 +Extras : + Flags (24-27): 0xdeadbeef +Key (28-32): The textual string: "Hello" +Value (33-37): The textual string: "World" + </artwork> + </figure> + </section> + </section> + + <section anchor="command-set" title="Set, Add, Replace" toc="default"> + <t> + <list style="empty"> + <t>MUST have extras.</t> + <t>MUST have key.</t> + <t>MUST have value.</t> + </list> + </t> + + <t> + <list style="symbols"> + <t>4 byte flags</t> + <t>4 byte expiration time</t> + </list> + </t> + + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Extra data for set/add/replace:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Flags | + +---------------+---------------+---------------+---------------+ + 4| Expiration | + +---------------+---------------+---------------+---------------+ + Total 8 bytes + </artwork> + </figure> + + <t> + If the Data Version Check (CAS) is nonzero, the requested + operation MUST only succeed if the item exists and has a CAS value + identical to the provided value. + </t> + + <t> + Add MUST fail if the item already exist. + </t> + + <t> + Replace MUST fail if the item doesn't exist. + </t> + + <t> + Set should store the data unconditionally if the item exists + or not. + </t> + + <t> + Quiet mutations only return responses on failure. Success + is considered the general case and is suppressed when in + quiet mode, but errors should not be allowed to go + unnoticed. + </t> + + <section anchor="command-set-example" title="Example" toc="default"> + <t>The following figure shows an add-command for + <list style="empty"> + <t>Key: "Hello"</t> + <t>Value: "World"</t> + <t>Flags: 0xdeadbeef</t> + <t>Expiry: in two hours</t> + </list> + </t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Add request:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x02 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x08 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x12 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0xde | 0xad | 0xbe | 0xef | + +---------------+---------------+---------------+---------------+ + 28| 0x00 | 0x00 | 0x1c | 0x20 | + +---------------+---------------+---------------+---------------+ + 32| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 36| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | + +---------------+---------------+---------------+---------------+ + 40| 0x6c ('l') | 0x64 ('d') | + +---------------+---------------+ + + Total 42 bytes (24 byte header, 8 byte extras, 5 byte key and + 5 byte value) + +Field (offset) (value) +Magic (0) : 0x80 +Opcode (1) : 0x02 +Key length (2,3) : 0x0005 +Extra length (4) : 0x08 +Data type (5) : 0x00 +Reserved (6,7) : 0x0000 +Total body (8-11) : 0x00000012 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000000 +Extras : + Flags (24-27): 0xdeadbeef + Expiry (28-31): 0x00001c20 +Key (32-36): The textual string "Hello" +Value (37-41): The textual string "World" + </artwork> + </figure> + <t> + The response-packet contains no extra data, and the result of the + operation is signaled through the status code. If the command + succeeds, the CAS value for the item is returned in the CAS-field + of the packet. + </t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Successful add response:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x02 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + + Total 24 bytes + +Field (offset) (value) +Magic (0) : 0x81 +Opcode (1) : 0x02 +Key length (2,3) : 0x0000 +Extra length (4) : 0x00 +Data type (5) : 0x00 +Status (6,7) : 0x0000 +Total body (8-11) : 0x00000000 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000001 +Extras : None +Key : None +Value : None + </artwork> + </figure> + </section> + </section> + + <section anchor="command-delete" title="Delete" toc="default"> + <t> + <list style="empty"> + <t>MUST NOT have extras.</t> + <t>MUST have key.</t> + <t>MUST NOT have value.</t> + </list> + </t> + + <t> + Delete the item with the specific key. + </t> + + <section anchor="command-delete-example" title="Example" toc="default"> + <t>The following figure shows a delete message for the + item "Hello".</t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Delete request:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x04 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 28| 0x6f ('o') | + +---------------+ + + Total 29 bytes (24 byte header, 5 byte value) + +Field (offset) (value) +Magic (0) : 0x80 +Opcode (1) : 0x04 +Key length (2,3) : 0x0005 +Extra length (4) : 0x00 +Data type (5) : 0x00 +Reserved (6,7) : 0x0000 +Total body (8-11) : 0x00000005 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000000 +Extras : None +Key : The textual string "Hello" +Value : None + </artwork> + </figure> + <t> + The response-packet contains no extra data, and the result of the + operation is signaled through the status code. + </t> + </section> + </section> + + <section anchor="command-incr" title="Increment, Decrement" toc="default"> + <t> + <list style="empty"> + <t>MUST have extras.</t> + <t>MUST have key.</t> + <t>MUST NOT have value.</t> + </list> + </t> + + <t> + <list style="symbols"> + <t>8 byte value to add / subtract</t> + <t>8 byte initial value (unsigned)</t> + <t>4 byte expiration time</t> + </list> + </t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Extra data for incr/decr:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Amount to add | + | | + +---------------+---------------+---------------+---------------+ + 8| Initial value | + | | + +---------------+---------------+---------------+---------------+ + 16| Expiration | + +---------------+---------------+---------------+---------------+ + Total 20 bytes + </artwork> + </figure> + + <t> + These commands will either add or remove the specified + amount to the requested counter. + </t> + <t> + If the counter does not exist, one of two things may happen: + </t> + <t> + <list style="numbers"> + <t>If the expiration value is all one-bits (0xffffffff), the + operation will fail with NOT_FOUND.</t> + <t>For all other expiration values, the operation will succeed + by seeding the value for this key with the provided initial + value to expire with the provided expiration time. The flags + will be set to zero.</t> + </list> + </t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>incr/decr response body:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 64-bit unsigned response. | + | | + +---------------+---------------+---------------+---------------+ + Total 8 bytes + </artwork> + </figure> + <section anchor="command-incr-example" title="Example" toc="default"> + <t>The following figure shows an incr-command for + <list style="empty"> + <t>Key: "counter"</t> + <t>Delta: 0x01</t> + <t>Initial: 0x00</t> + <t>Expiry: in two hours</t> + </list> + </t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Increment request:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x05 | 0x00 | 0x07 | + +---------------+---------------+---------------+---------------+ + 4| 0x14 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x1b | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 28| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + 32| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 36| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 40| 0x00 | 0x00 | 0x1c | 0x20 | + +---------------+---------------+---------------+---------------+ + 44| 0x63 ('c') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | + +---------------+---------------+---------------+---------------+ + 48| 0x74 ('t') | 0x65 ('e') | 0x72 ('r') | + +---------------+---------------+---------------+ + Total 51 bytes (24 byte header, 20 byte extras, 7 byte key) + +Field (offset) (value) +Magic (0) : 0x80 +Opcode (1) : 0x05 +Key length (2,3) : 0x0007 +Extra length (4) : 0x14 +Data type (5) : 0x00 +Reserved (6,7) : 0x0000 +Total body (8-11) : 0x0000001b +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000000 +Extras : + delta (24-31): 0x0000000000000001 + initial (32-39): 0x0000000000000000 + expiration (40-43): 0x00001c20 +Key : Textual string "counter" +Value : None + </artwork> + </figure> + <t> + If the key doesn't exist, the server will respond with the + initial value. If not the incremented value will be returned. + Let's assume that the key didn't exist, so the initial value + is returned. + </t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Increment response:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x05 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x08 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 24| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 28| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 32 bytes (24 byte header, 8 byte value) + +Field (offset) (value) +Magic (0) : 0x81 +Opcode (1) : 0x05 +Key length (2,3) : 0x0000 +Extra length (4) : 0x00 +Data type (5) : 0x00 +Status (6,7) : 0x0000 +Total body (8-11) : 0x00000008 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000005 +Extras : None +Key : None +Value : 0x0000000000000000 + </artwork> + </figure> + </section> + </section> + + <section anchor="command-quit" title="quit" toc="default"> + <t> + <list style="empty"> + <t>MUST NOT have extras.</t> + <t>MUST NOT have key.</t> + <t>MUST NOT have value.</t> + </list> + </t> + + <t> + Close the connection to the server. + </t> + + <section anchor="command-quit-example" title="Example" toc="default"> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Quit request:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x07 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + +Field (offset) (value) +Magic (0) : 0x80 +Opcode (1) : 0x07 +Key length (2,3) : 0x0000 +Extra length (4) : 0x00 +Data type (5) : 0x00 +Reserved (6,7) : 0x0000 +Total body (8-11) : 0x00000000 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000000 +Extras : None +Key : None +Value : None + </artwork> + </figure> + <t> + The response-packet contains no extra data, and the result of the + operation is signaled through the status code. The server will + then close the connection. + </t> + </section> + </section> + + <section anchor="command-flush" title="Flush" toc="default"> + <t> + <list style="empty"> + <t>MAY have extras.</t> + <t>MUST NOT have key.</t> + <t>MUST NOT have value.</t> + </list> + </t> + + <t> + <list style="symbols"> + <t>4 byte expiration time</t> + </list> + </t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Extra data for flush:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Expiration | + +---------------+---------------+---------------+---------------+ + Total 4 bytes + </artwork> + </figure> + <t> + Flush the items in the cache now or some time in the future as + specified by the expiration field. See the documentation of the + textual protocol for the full description on how to specify the + expiration time. + </t> + <section anchor="command-flush-example" title="Example" toc="default"> + <t> + To flush the cache (delete all items) in two hours, the set + the following values in the request + </t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Flush request:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x08 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x04 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x04 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x00 | 0x00 | 0x1c | 0x20 | + +---------------+---------------+---------------+---------------+ + Total 28 bytes (24 byte header, 4 byte body) + +Field (offset) (value) +Magic (0) : 0x80 +Opcode (1) : 0x08 +Key length (2,3) : 0x0000 +Extra length (4) : 0x04 +Data type (5) : 0x00 +Reserved (6,7) : 0x0000 +Total body (8-11) : 0x00000004 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000000 +Extras : + Expiry (24-27): 0x00001c20 +Key : None +Value : None + </artwork> + </figure> + <t> + The response-packet contains no extra data, and the result of the + operation is signaled through the status code. + </t> + </section> + </section> + <section anchor="command-noop" title="noop" toc="default"> + <t> + <list style="empty"> + <t>MUST NOT have extras.</t> + <t>MUST NOT have key.</t> + <t>MUST NOT have value.</t> + </list> + </t> + + <t> + Used as a keep alive. Flushes outstanding getq/getkq's. + </t> + <section anchor="command-noop-example" title="Example" toc="default"> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Noop request:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x0a | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + +Field (offset) (value) +Magic (0) : 0x80 +Opcode (1) : 0x0a +Key length (2,3) : 0x0000 +Extra length (4) : 0x00 +Data type (5) : 0x00 +Reserved (6,7) : 0x0000 +Total body (8-11) : 0x00000000 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000000 +Extras : None +Key : None +Value : None + </artwork> + </figure> + <t> + The response-packet contains no extra data, and the result of the + operation is signaled through the status code. + </t> + </section> + </section> + + <section anchor="command-version" title="version" toc="default"> + <t> + <list style="empty"> + <t>MUST NOT have extras.</t> + <t>MUST NOT have key.</t> + <t>MUST NOT have value.</t> + </list> + </t> + + <t> + Request the server version. + </t> + <t> + The server responds with a packet containing the version string + in the body with the following format: "x.y.z" + </t> + <section anchor="command-version-example" title="Example" toc="default"> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Version request:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x0b | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + +Field (offset) (value) +Magic (0) : 0x80 +Opcode (1) : 0x0b +Key length (2,3) : 0x0000 +Extra length (4) : 0x00 +Data type (5) : 0x00 +Reserved (6,7) : 0x0000 +Total body (8-11) : 0x00000000 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000000 +Extras : None + </artwork> + </figure> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Version response:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x0b | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x31 ('1') | 0x2e ('.') | 0x33 ('3') | 0x2e ('.') | + +---------------+---------------+---------------+---------------+ + 28| 0x31 ('1') | + +---------------+ + Total 29 bytes (24 byte header, 5 byte body) + +Field (offset) (value) +Magic (0) : 0x81 +Opcode (1) : 0x0b +Key length (2,3) : 0x0000 +Extra length (4) : 0x00 +Data type (5) : 0x00 +Status (6,7) : 0x0000 +Total body (8-11) : 0x00000005 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000000 +Extras : None +Key : None +Value : Textual string "1.3.1" + </artwork> + </figure> + </section> + </section> + + <section anchor="command-append" title="Append, Prepend" toc="default"> + <t> + <list style="empty"> + <t>MUST NOT have extras.</t> + <t>MUST have key.</t> + <t>MUST have value.</t> + </list> + </t> + + <t> + These commands will either append or prepend the specified + value to the requested key. + </t> + + <section anchor="command-append-example" title="Example" toc="default"> + <t>The following example appends '!' to the 'Hello' key.</t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Append request:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x0e | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x06 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 28| 0x6f ('o') | 0x21 ('!') | + +---------------+---------------+ + Total 30 bytes (24 byte header, 5 byte key, 1 byte value) + +Field (offset) (value) +Magic (0) : 0x80 +Opcode (1) : 0x0e +Key length (2,3) : 0x0005 +Extra length (4) : 0x00 +Data type (5) : 0x00 +Reserved (6,7) : 0x0000 +Total body (8-11) : 0x00000006 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000000 +Extras : None +Key (24-28): The textual string "Hello" +Value (29) : "!" + </artwork> + </figure> + <t> + The response-packet contains no extra data, and the result of the + operation is signaled through the status code. + </t> + </section> + </section> + + <section anchor="command-stat" title="Stat" toc="default"> + <t> + <list style="empty"> + <t>MUST NOT have extras.</t> + <t>MAY have key.</t> + <t>MUST NOT have value.</t> + </list> + </t> + + <t> + Request server statistics. Without a key specified the server will + respond with a "default" set of statistics information. Each piece + of statistical information is returned in its own packet (key + contains the name of the statistical item and the body contains the + value in ASCII format). The sequence of return packets is terminated + with a packet that contains no key and no value. + </t> + <section anchor="command-stat-example" title="Example" toc="default"> + <t>The following example requests all statistics from the server</t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Stat request:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x10 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + +Field (offset) (value) +Magic (0) : 0x80 +Opcode (1) : 0x10 +Key length (2,3) : 0x0000 +Extra length (4) : 0x00 +Data type (5) : 0x00 +Reserved (6,7) : 0x0000 +Total body (8-11) : 0x00000000 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000000 +Extras : None +Key : None +Value : None + </artwork> + </figure> + <t> + The server will send each value in a separate packet with + an "empty" packet (no key / no value) to terminate the sequence. + Each of the response packets look like the following example: + </t> + <figure title="" suppress-title="false" align="left" alt="" width="" height=""> + <preamble>Stat response:</preamble> + <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x10 | 0x00 | 0x03 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x07 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x70 ('p') | 0x69 ('i') | 0x64 ('d') | 0x33 ('3') | + +---------------+---------------+---------------+---------------+ + 28| 0x30 ('0') | 0x37 ('7') | 0x38 ('8') | + +---------------+---------------+---------------+ + Total 31 bytes (24 byte header, 3 byte key, 4 byte body) + +Field (offset) (value) +Magic (0) : 0x81 +Opcode (1) : 0x10 +Key length (2,3) : 0x0003 +Extra length (4) : 0x00 +Data type (5) : 0x00 +Status (6,7) : 0x0000 +Total body (8-11) : 0x00000007 +Opaque (12-15): 0x00000000 +CAS (16-23): 0x0000000000000000 +Extras : None +Key : The textual string "pid" +Value : The textual string "3078" + </artwork> + </figure> + </section> + </section> + </section> + <section anchor="security" title="Security Considerations" toc="default"> + <t> + Memcache has few authentication and no security layers whatsoever. It is + RECOMMENDED that memcache be deployed strictly on closed, protected, + back-end networks within a single data center, within a single cluster of + servers, or even on a single host, providing shared caching for multiple + applications. Memcache MUST NOT be made available on a public network. + </t> + + <t> + SASL is supported as an authentication mechanism. See the wiki for more + information. + </t> + </section> + + </middle> + + <back> + <references title="Normative References"> + <reference anchor="LJ" quote-title="true"> + <front> + <title>LJ NEEDS MOAR SPEED</title> + <author fullname="Brad Fitzpatrick"> + <organization>Danga Interactive</organization> + </author> + <date day="5" month="10" year="1999"/> + <abstract> + <t>http://www.livejournal.com/</t> + </abstract> + </front> + </reference> + <reference anchor="KEYWORDS"> + +<front> +<title abbrev="RFC Key Words">Key words for use in RFCs to Indicate Requirement Levels</title> +<author initials="S." surname="Bradner" fullname="Scott Bradner"> +<organization>Harvard University</organization> +<address> +<postal> +<street>1350 Mass. Ave.</street> +<street>Cambridge</street> +<street>MA 02138</street></postal> +<phone>- +1 617 495 3864</phone> +<email>sob@harvard.edu</email></address></author> +<date year="1997" month="March"/> +<area>General</area> +<keyword>keyword</keyword> +<abstract> +<t> + In many standards track documents several words are used to signify + the requirements in the specification. These words are often + capitalized. This document defines these words as they should be + interpreted in IETF documents. Authors who follow these guidelines + should incorporate this phrase near the beginning of their document: + +<list> +<t> + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL + NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + RFC 2119. +</t></list></t> +<t> + Note that the force of these words is modified by the requirement + level of the document in which they are used. +</t></abstract></front> + +<seriesInfo name="BCP" value="14"/> +<seriesInfo name="RFC" value="2119"/> +<format type="TXT" octets="4723" target="http://www.rfc-editor.org/rfc/rfc2119.txt"/> +<format type="HTML" octets="17970" target="http://xml.resource.org/public/rfc/html/rfc2119.html"/> +<format type="XML" octets="5777" target="http://xml.resource.org/public/rfc/xml/rfc2119.xml"/> +</reference> + </references> + + <section anchor="acknowledgments" title="Acknowledgments" toc="default"> + <t> + Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin + Sallings, for their work on the memcached server. + </t> + + <t> + Thanks to Sean Chittenden, Jonathan Steinert, Brian Aker, Evan Martin, + Nathan Neulinger, Eric Hodel, Michael Johnson, Paul Querna, Jamie + McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg, Robin H. + Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean-Francois + Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris Goffinet, Tomash + Brechko, and others for their work reporting bugs and maintaining + memcached client libraries and bindings in many languages. + </t> + </section> + </back> + +</rfc> diff --git a/doc/protocol-binary.txt b/doc/protocol-binary.txt new file mode 100644 index 0000000..b59d353 --- /dev/null +++ b/doc/protocol-binary.txt @@ -0,0 +1,1736 @@ + + + + +Network Working Group Stone, Ed. +Internet-Draft Six Apart, Ltd. +Intended status: Informational Norbye, Ed. +Expires: March 1, 2009 Sun Microsystems, INC + August 28, 2008 + + + Memcache Binary Protocol + draft-stone-memcache-binary-01 + +Abstract + + This memo explains the memcache binary protocol for informational + purposes. + + Memcache is a high performance key-value cache. It is intentionally + a dumb cache, optimized for speed only. Applications using memcache + do not rely on it for data -- a persistent database with guaranteed + reliability is strongly recommended -- but applications can run much + faster when cached data is available in memcache. + +Status of This Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at http://datatracker.ietf.org/drafts/current/. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on March 1, 2009. + +Copyright Notice + + Copyright (c) 2008 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + + + +Stone & Norbye Expires March 1, 2009 [Page 1] + +Internet-Draft Memcache Binary Protocol August 2008 + + + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 + 1.1. Conventions Used In This Document . . . . . . . . . . . . 3 + 2. Packet Structure . . . . . . . . . . . . . . . . . . . . . . 3 + 3. Defined Values . . . . . . . . . . . . . . . . . . . . . . . 5 + 3.1. Magic Byte . . . . . . . . . . . . . . . . . . . . . . . 5 + 3.2. Response Status . . . . . . . . . . . . . . . . . . . . . 5 + 3.3. Command Opcodes . . . . . . . . . . . . . . . . . . . . . 6 + 3.4. Data Types . . . . . . . . . . . . . . . . . . . . . . . 6 + 4. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 4.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 7 + 4.1.1. Example . . . . . . . . . . . . . . . . . . . . . . . 7 + 4.2. Get, Get Quietly, Get Key, Get Key Quietly . . . . . . . 8 + 4.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 9 + 4.3. Set, Add, Replace . . . . . . . . . . . . . . . . . . . . 13 + 4.3.1. Example . . . . . . . . . . . . . . . . . . . . . . . 13 + 4.4. Delete . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 4.4.1. Example . . . . . . . . . . . . . . . . . . . . . . . 16 + 4.5. Increment, Decrement . . . . . . . . . . . . . . . . . . 17 + 4.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 18 + 4.6. quit . . . . . . . . . . . . . . . . . . . . . . . . . . 20 + 4.6.1. Example . . . . . . . . . . . . . . . . . . . . . . . 21 + 4.7. Flush . . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 4.7.1. Example . . . . . . . . . . . . . . . . . . . . . . . 22 + 4.8. noop . . . . . . . . . . . . . . . . . . . . . . . . . . 23 + 4.8.1. Example . . . . . . . . . . . . . . . . . . . . . . . 24 + 4.9. version . . . . . . . . . . . . . . . . . . . . . . . . . 24 + 4.9.1. Example . . . . . . . . . . . . . . . . . . . . . . . 25 + 4.10. Append, Prepend . . . . . . . . . . . . . . . . . . . . . 26 + 4.10.1. Example . . . . . . . . . . . . . . . . . . . . . . 27 + 4.11. Stat . . . . . . . . . . . . . . . . . . . . . . . . . . 28 + 4.11.1. Example . . . . . . . . . . . . . . . . . . . . . . 28 + 5. Security Considerations . . . . . . . . . . . . . . . . . . . 30 + 6. Normative References . . . . . . . . . . . . . . . . . . . . 31 + Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 31 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 + +1. Introduction + + Memcache is a high performance key-value cache. It is intentionally + a dumb cache, optimized for speed only. Applications using memcache + should not rely on it for data -- a persistent database with + + + +Stone & Norbye Expires March 1, 2009 [Page 2] + +Internet-Draft Memcache Binary Protocol August 2008 + + + guaranteed reliability is strongly recommended -- but applications + can run much faster when cached data is available in memcache. + + Memcache was originally written to make LiveJournal [LJ] faster. It + now powers all of the fastest web sites that you love. + +1.1. Conventions Used In This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [KEYWORDS]. + +2. Packet Structure + + General format of a packet: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0/ HEADER / + / / + / / + / / + +---------------+---------------+---------------+---------------+ + 24/ COMMAND-SPECIFIC EXTRAS (as needed) / + +/ (note length in the extras length header field) / + +---------------+---------------+---------------+---------------+ + m/ Key (as needed) / + +/ (note length in key length header field) / + +---------------+---------------+---------------+---------------+ + n/ Value (as needed) / + +/ (note length is total body length header field, minus / + +/ sum of the extras and key length body fields) / + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 3] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Request header: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Magic | Opcode | Key length | + +---------------+---------------+---------------+---------------+ + 4| Extras length | Data type | Reserved | + +---------------+---------------+---------------+---------------+ + 8| Total body length | + +---------------+---------------+---------------+---------------+ + 12| Opaque | + +---------------+---------------+---------------+---------------+ + 16| CAS | + | | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + Response header: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Magic | Opcode | Key Length | + +---------------+---------------+---------------+---------------+ + 4| Extras length | Data type | Status | + +---------------+---------------+---------------+---------------+ + 8| Total body length | + +---------------+---------------+---------------+---------------+ + 12| Opaque | + +---------------+---------------+---------------+---------------+ + 16| CAS | + | | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + Header fields: + + Magic Magic number. + Opcode Command code. + Key length Length in bytes of the text key that follows the + command extras. + Status Status of the response (non-zero on error). + Extras length Length in bytes of the command extras. + Data type Reserved for future use (Sean is using this + soon). + + + +Stone & Norbye Expires March 1, 2009 [Page 4] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Reserved Really reserved for future use (up for grabs). + Total body length Length in bytes of extra + key + value. + Opaque Will be copied back to you in the response. + CAS Data version check. + +3. Defined Values + +3.1. Magic Byte + + 0x80 Request packet for this protocol version + 0x81 Response packet for this protocol version + + Magic byte / version. For each version of the protocol, we'll use a + different request/response value pair. This is useful for protocol + analyzers to distinguish the nature of the packet from the direction + which it is moving. Note, it is common to run a memcached instance + on a host that also runs an application server. Such a host will + both send and receive memcache packets. + + The version should hopefully correspond only to different meanings of + the command byte. In an ideal world, we will not change the header + format. As reserved bytes are given defined meaning, the protocol + version / magic byte values should be incremented. + + Traffic analysis tools are encouraged to identify memcache packets + and provide detailed interpretation if the magic bytes are recognized + and otherwise to provide a generic breakdown of the packet. Note, + that the key and value positions can always be identified even if the + magic byte or command opcode are not recognized. + +3.2. Response Status + + Possible values of this two-byte field: + + 0x0000 No error + 0x0001 Key not found + 0x0002 Key exists + 0x0003 Value too large + 0x0004 Invalid arguments + 0x0005 Item not stored + 0x0006 Incr/Decr on non-numeric value. + 0x0081 Unknown command + 0x0082 Out of memory + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 5] + +Internet-Draft Memcache Binary Protocol August 2008 + + +3.3. Command Opcodes + + Possible values of the one-byte field: + + 0x00 Get + 0x01 Set + 0x02 Add + 0x03 Replace + 0x04 Delete + 0x05 Increment + 0x06 Decrement + 0x07 Quit + 0x08 Flush + 0x09 GetQ + 0x0A No-op + 0x0B Version + 0x0C GetK + 0x0D GetKQ + 0x0E Append + 0x0F Prepend + 0x10 Stat + 0x11 SetQ + 0x12 AddQ + 0x13 ReplaceQ + 0x14 DeleteQ + 0x15 IncrementQ + 0x16 DecrementQ + 0x17 QuitQ + 0x18 FlushQ + 0x19 AppendQ + 0x1A PrependQ + + As a convention all of the commands ending with "Q" for Quiet. A + quiet version of a command will omit responses that are considered + uninteresting. Whether a given response is interesting is dependent + upon the command. See the descriptions of the set commands + (Section 4.2) and set commands (Section 4.3) for examples of commands + that include quiet variants. + +3.4. Data Types + + Possible values of the one-byte field: + + 0x00 Raw bytes + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 6] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4. Commands + +4.1. Introduction + + All communication is initiated by a request from the client, and the + server will respond to each request with zero or multiple packets for + each request. If the status code of a response packet is non-nil, + the body of the packet will contain a textual error message. If the + status code is nil, the command opcode will define the layout of the + body of the message. + +4.1.1. Example + + The following figure illustrates the packet layout for a packet with + an error message. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 7] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Packet layout: + + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x09 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x4e ('N') | 0x6f ('o') | 0x74 ('t') | 0x20 (' ') | + +---------------+---------------+---------------+---------------+ + 28| 0x66 ('f') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | + +---------------+---------------+---------------+---------------+ + 32| 0x64 ('d') | + +---------------+ + Total 33 bytes (24 byte header, and 9 bytes value) + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x00 + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Status (6,7) : 0x0001 + Total body (8-11) : 0x00000009 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key : None + Value (24-32): The textual string "Not found" + +4.2. Get, Get Quietly, Get Key, Get Key Quietly + + Request: + + MUST NOT have extras. + MUST have key. + MUST NOT have value. + + + +Stone & Norbye Expires March 1, 2009 [Page 8] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Response (if found): + + MUST have extras. + MAY have key. + MAY have value. + + o 4 byte flags + + Extra data for the get commands: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Flags | + +---------------+---------------+---------------+---------------+ + + Total 4 bytes + + The get command gets a single key. The getq command is both mum on + cache miss and quiet, holding its response until a non-quiet command + is issued. Getk and getkq differs from get and getq by adding the + key into the response packet. + + You're not guaranteed a response to a getq/getkq cache hit until you + send a non-getq/getkq command later, which uncorks the server and + bundles up IOs to send to the client in one go. + + Clients should implement multi-get (still important for reducing + network roundtrips!) as n pipelined requests, the first n-1 being + getq/getkq, the last being a regular get/getk. That way you're + guaranteed to get a response, and you know when the server's done. + You can also do the naive thing and send n pipelined get/getks, but + then you could potentially get back a lot of "NOT_FOUND" error code + packets. Alternatively, you can send 'n' getq/getkqs, followed by a + 'noop' command. + +4.2.1. Example + + To request the data associated with the key "Hello" the following + fields must be specified in the packet. + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 9] + +Internet-Draft Memcache Binary Protocol August 2008 + + + get request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 28| 0x6f ('o') | + +---------------+ + + Total 29 bytes (24 byte header, and 5 bytes key) + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x00 + Key length (2,3) : 0x0005 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000005 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key (24-29): The textual string: "Hello" + Value : None + + If the item exist on the server the following packet is returned, + otherwise a packet with status code != 0 will be returned (see + Introduction (Section 4.1)) + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 10] + +Internet-Draft Memcache Binary Protocol August 2008 + + + get/getq response: + + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x04 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x09 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + 24| 0xde | 0xad | 0xbe | 0xef | + +---------------+---------------+---------------+---------------+ + 28| 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 32| 0x64 ('d') | + +---------------+ + + Total 33 bytes (24 byte header, 4 byte extras and 5 byte value) + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x00 + Key length (2,3) : 0x0000 + Extra length (4) : 0x04 + Data type (5) : 0x00 + Status (6,7) : 0x0000 + Total body (8-11) : 0x00000009 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000001 + Extras : + Flags (24-27): 0xdeadbeef + Key : None + Value (28-32): The textual string "World" + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 11] + +Internet-Draft Memcache Binary Protocol August 2008 + + + getk/getkq response: + + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x04 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x09 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + 24| 0xde | 0xad | 0xbe | 0xef | + +---------------+---------------+---------------+---------------+ + 28| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 32| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | + +---------------+---------------+---------------+---------------+ + 36| 0x6c ('l') | 0x64 ('d') | + +---------------+---------------+ + + Total 38 bytes (24 byte header, 4 byte extras, 5 byte key + and 5 byte value) + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x00 + Key length (2,3) : 0x0005 + Extra length (4) : 0x04 + Data type (5) : 0x00 + Status (6,7) : 0x0000 + Total body (8-11) : 0x0000000E + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000001 + Extras : + Flags (24-27): 0xdeadbeef + Key (28-32): The textual string: "Hello" + Value (33-37): The textual string: "World" + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 12] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.3. Set, Add, Replace + + MUST have extras. + MUST have key. + MUST have value. + + o 4 byte flags + o 4 byte expiration time + + Extra data for set/add/replace: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Flags | + +---------------+---------------+---------------+---------------+ + 4| Expiration | + +---------------+---------------+---------------+---------------+ + Total 8 bytes + + If the Data Version Check (CAS) is nonzero, the requested operation + MUST only succeed if the item exists and has a CAS value identical to + the provided value. + + Add MUST fail if the item already exist. + + Replace MUST fail if the item doesn't exist. + + Set should store the data unconditionally if the item exists or not. + + Quiet mutations only return responses on failure. Success is + considered the general case and is suppressed when in quiet mode, but + errors should not be allowed to go unnoticed. + +4.3.1. Example + + The following figure shows an add-command for + + Key: "Hello" + Value: "World" + Flags: 0xdeadbeef + Expiry: in two hours + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 13] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Add request: + + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x02 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x08 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x12 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0xde | 0xad | 0xbe | 0xef | + +---------------+---------------+---------------+---------------+ + 28| 0x00 | 0x00 | 0x1c | 0x20 | + +---------------+---------------+---------------+---------------+ + 32| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 36| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | + +---------------+---------------+---------------+---------------+ + 40| 0x6c ('l') | 0x64 ('d') | + +---------------+---------------+ + + Total 42 bytes (24 byte header, 8 byte extras, 5 byte key and + 5 byte value) + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x02 + Key length (2,3) : 0x0005 + Extra length (4) : 0x08 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000012 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : + Flags (24-27): 0xdeadbeef + Expiry (28-31): 0x00001c20 + Key (32-36): The textual string "Hello" + Value (37-41): The textual string "World" + + + +Stone & Norbye Expires March 1, 2009 [Page 14] + +Internet-Draft Memcache Binary Protocol August 2008 + + + The response-packet contains no extra data, and the result of the + operation is signaled through the status code. If the command + succeeds, the CAS value for the item is returned in the CAS-field of + the packet. + + Successful add response: + + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x02 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + + Total 24 bytes + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x02 + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Status (6,7) : 0x0000 + Total body (8-11) : 0x00000000 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000001 + Extras : None + Key : None + Value : None + +4.4. Delete + + MUST NOT have extras. + MUST have key. + MUST NOT have value. + + Delete the item with the specific key. + + + +Stone & Norbye Expires March 1, 2009 [Page 15] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.4.1. Example + + The following figure shows a delete message for the item "Hello". + + Delete request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x04 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 28| 0x6f ('o') | + +---------------+ + + Total 29 bytes (24 byte header, 5 byte value) + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x04 + Key length (2,3) : 0x0005 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000005 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key : The textual string "Hello" + Value : None + + The response-packet contains no extra data, and the result of the + operation is signaled through the status code. + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 16] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.5. Increment, Decrement + + MUST have extras. + MUST have key. + MUST NOT have value. + + o 8 byte value to add / subtract + o 8 byte initial value (unsigned) + o 4 byte expiration time + + Extra data for incr/decr: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Amount to add | + | | + +---------------+---------------+---------------+---------------+ + 8| Initial value | + | | + +---------------+---------------+---------------+---------------+ + 16| Expiration | + +---------------+---------------+---------------+---------------+ + Total 20 bytes + + These commands will either add or remove the specified amount to the + requested counter. + + If the counter does not exist, one of two things may happen: + + 1. If the expiration value is all one-bits (0xffffffff), the + operation will fail with NOT_FOUND. + 2. For all other expiration values, the operation will succeed by + seeding the value for this key with the provided initial value to + expire with the provided expiration time. The flags will be set + to zero. + + incr/decr response body: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 64-bit unsigned response. | + | | + +---------------+---------------+---------------+---------------+ + Total 8 bytes + + + +Stone & Norbye Expires March 1, 2009 [Page 17] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.5.1. Example + + The following figure shows an incr-command for + + Key: "counter" + Delta: 0x01 + Initial: 0x00 + Expiry: in two hours + + Increment request: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 18] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x05 | 0x00 | 0x07 | + +---------------+---------------+---------------+---------------+ + 4| 0x14 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x1b | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 28| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + 32| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 36| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 40| 0x00 | 0x00 | 0x1c | 0x20 | + +---------------+---------------+---------------+---------------+ + 44| 0x63 ('c') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | + +---------------+---------------+---------------+---------------+ + 48| 0x74 ('t') | 0x65 ('e') | 0x72 ('r') | + +---------------+---------------+---------------+ + Total 51 bytes (24 byte header, 20 byte extras, 7 byte key) + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x05 + Key length (2,3) : 0x0007 + Extra length (4) : 0x14 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x0000001b + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : + delta (24-31): 0x0000000000000001 + initial (32-39): 0x0000000000000000 + expiration (40-43): 0x00001c20 + Key : Textual string "counter" + Value : None + + + +Stone & Norbye Expires March 1, 2009 [Page 19] + +Internet-Draft Memcache Binary Protocol August 2008 + + + If the key doesn't exist, the server will respond with the initial + value. If not the incremented value will be returned. Let's assume + that the key didn't exist, so the initial value is returned. + + Increment response: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x05 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x08 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 24| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 28| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 32 bytes (24 byte header, 8 byte value) + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x05 + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Status (6,7) : 0x0000 + Total body (8-11) : 0x00000008 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000005 + Extras : None + Key : None + Value : 0x0000000000000000 + +4.6. quit + + MUST NOT have extras. + MUST NOT have key. + MUST NOT have value. + + + + +Stone & Norbye Expires March 1, 2009 [Page 20] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Close the connection to the server. + +4.6.1. Example + + Quit request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x07 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x07 + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000000 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key : None + Value : None + + The response-packet contains no extra data, and the result of the + operation is signaled through the status code. The server will then + close the connection. + +4.7. Flush + + MAY have extras. + MUST NOT have key. + MUST NOT have value. + + + + +Stone & Norbye Expires March 1, 2009 [Page 21] + +Internet-Draft Memcache Binary Protocol August 2008 + + + o 4 byte expiration time + + Extra data for flush: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| Expiration | + +---------------+---------------+---------------+---------------+ + Total 4 bytes + + Flush the items in the cache now or some time in the future as + specified by the expiration field. See the documentation of the + textual protocol for the full description on how to specify the + expiration time. + +4.7.1. Example + + To flush the cache (delete all items) in two hours, the set the + following values in the request + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 22] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Flush request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x08 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x04 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x04 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x00 | 0x00 | 0x1c | 0x20 | + +---------------+---------------+---------------+---------------+ + Total 28 bytes (24 byte header, 4 byte body) + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x08 + Key length (2,3) : 0x0000 + Extra length (4) : 0x04 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000004 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : + Expiry (24-27): 0x00001c20 + Key : None + Value : None + + The response-packet contains no extra data, and the result of the + operation is signaled through the status code. + +4.8. noop + + MUST NOT have extras. + MUST NOT have key. + MUST NOT have value. + + Used as a keep alive. Flushes outstanding getq/getkq's. + + + + +Stone & Norbye Expires March 1, 2009 [Page 23] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.8.1. Example + + Noop request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x0a | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x0a + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000000 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key : None + Value : None + + The response-packet contains no extra data, and the result of the + operation is signaled through the status code. + +4.9. version + + MUST NOT have extras. + MUST NOT have key. + MUST NOT have value. + + Request the server version. + + + + + +Stone & Norbye Expires March 1, 2009 [Page 24] + +Internet-Draft Memcache Binary Protocol August 2008 + + + The server responds with a packet containing the version string in + the body with the following format: "x.y.z" + +4.9.1. Example + + Version request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x0b | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x0b + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000000 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + + + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 25] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Version response: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x0b | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x31 ('1') | 0x2e ('.') | 0x33 ('3') | 0x2e ('.') | + +---------------+---------------+---------------+---------------+ + 28| 0x31 ('1') | + +---------------+ + Total 29 bytes (24 byte header, 5 byte body) + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x0b + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Status (6,7) : 0x0000 + Total body (8-11) : 0x00000005 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key : None + Value : Textual string "1.3.1" + +4.10. Append, Prepend + + MUST NOT have extras. + MUST have key. + MUST have value. + + These commands will either append or prepend the specified value to + the requested key. + + + + + +Stone & Norbye Expires March 1, 2009 [Page 26] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.10.1. Example + + The following example appends '!' to the 'Hello' key. + + Append request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x0e | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x06 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 28| 0x6f ('o') | 0x21 ('!') | + +---------------+---------------+ + Total 30 bytes (24 byte header, 5 byte key, 1 byte value) + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x0e + Key length (2,3) : 0x0005 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000006 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key (24-28): The textual string "Hello" + Value (29) : "!" + + The response-packet contains no extra data, and the result of the + operation is signaled through the status code. + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 27] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.11. Stat + + MUST NOT have extras. + MAY have key. + MUST NOT have value. + + Request server statistics. Without a key specified the server will + respond with a "default" set of statistics information. Each piece + of statistical information is returned in its own packet (key + contains the name of the statistical item and the body contains the + value in ASCII format). The sequence of return packets is terminated + with a packet that contains no key and no value. + +4.11.1. Example + + The following example requests all statistics from the server + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 28] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Stat request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x10 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x10 + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000000 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key : None + Value : None + + The server will send each value in a separate packet with an "empty" + packet (no key / no value) to terminate the sequence. Each of the + response packets look like the following example: + + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 29] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Stat response: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |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| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x10 | 0x00 | 0x03 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x07 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x70 ('p') | 0x69 ('i') | 0x64 ('d') | 0x33 ('3') | + +---------------+---------------+---------------+---------------+ + 28| 0x30 ('0') | 0x37 ('7') | 0x38 ('8') | + +---------------+---------------+---------------+ + Total 31 bytes (24 byte header, 3 byte key, 4 byte body) + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x10 + Key length (2,3) : 0x0003 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Status (6,7) : 0x0000 + Total body (8-11) : 0x00000007 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key : The textual string "pid" + Value : The textual string "3078" + +5. Security Considerations + + Memcache has few authentication and no security layers whatsoever. + It is RECOMMENDED that memcache be deployed strictly on closed, + protected, back-end networks within a single data center, within a + single cluster of servers, or even on a single host, providing shared + caching for multiple applications. Memcache MUST NOT be made + available on a public network. + + + + + +Stone & Norbye Expires March 1, 2009 [Page 30] + +Internet-Draft Memcache Binary Protocol August 2008 + + + SASL is supported as an authentication mechanism. See the wiki for + more information. + +6. Normative References + + [KEYWORDS] + Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [LJ] Fitzpatrick, B., "LJ NEEDS MOAR SPEED", 10 1999. + +Appendix A. Acknowledgments + + Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin + Sallings, for their work on the memcached server. + + Thanks to Sean Chittenden, Jonathan Steinert, Brian Aker, Evan + Martin, Nathan Neulinger, Eric Hodel, Michael Johnson, Paul Querna, + Jamie McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg, + Robin H. Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean- + Francois Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris + Goffinet, Tomash Brechko, and others for their work reporting bugs + and maintaining memcached client libraries and bindings in many + languages. + +Authors' Addresses + + Aaron Stone (editor) + Six Apart, Ltd. + 548 4th Street + San Francisco, CA 94107 + USA + + Email: aaron@serendipity.palo-alto.ca.us + + + Trond Norbye (editor) + Sun Microsystems, INC + Haakon VII g. 7B + Trondheim NO-7485 Trondheim + Norway + + Email: trond.norbye@sun.com + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 31] |