diff options
| author | Trond Norbye <Trond.Norbye@sun.com> | 2009-03-04 13:48:21 +0100 |
|---|---|---|
| committer | Trond Norbye <Trond.Norbye@sun.com> | 2009-03-04 13:48:21 +0100 |
| commit | f181a24d08a52629c897bf9070480054af159380 (patch) | |
| tree | 783007305b1868285c129b26b4604fd3e52d94a7 | |
| parent | effae30eec5a53d069ffc439979d05c7dbacac71 (diff) | |
| download | memcached-f181a24d08a52629c897bf9070480054af159380.tar.gz | |
Detect xml2rfc and xsltproc during configure and generate the documentation as part of make
| -rw-r--r-- | configure.ac | 4 | ||||
| -rw-r--r-- | doc/Makefile-xml2rfc | 8 | ||||
| -rw-r--r-- | doc/Makefile.am | 17 | ||||
| -rw-r--r-- | doc/protocol-binary-range.txt | 336 | ||||
| -rw-r--r-- | doc/protocol-binary.txt | 1736 | ||||
| -rw-r--r-- | doc/readme.txt | 3 |
6 files changed, 21 insertions, 2083 deletions
diff --git a/configure.ac b/configure.ac index 6deed86..1e1c495 100644 --- a/configure.ac +++ b/configure.ac @@ -319,6 +319,10 @@ AC_CHECK_FUNCS(setppriv, [ AM_CONDITIONAL([BUILD_SOLARIS_PRIVS],[test "$build_solaris_privs" = "yes"]) +AC_PATH_PROG([XML2RFC], [xml2rfc], "no") +AC_PATH_PROG([XSLTPROC], [xsltproc], "no") +AM_CONDITIONAL([BUILD_SPECIFICATIONS],[test "x$XML2RFC" != "xno" -a "x$XSLTPROC" != "xno"]) + dnl Let the compiler be a bit more picky. Please note that you cannot dnl specify these flags to the compiler before AC_CHECK_FUNCS, because dnl the test program will generate a compilation warning and hence fail diff --git a/doc/Makefile-xml2rfc b/doc/Makefile-xml2rfc deleted file mode 100644 index e10cd9c..0000000 --- a/doc/Makefile-xml2rfc +++ /dev/null @@ -1,8 +0,0 @@ -%.txt: %.full - xml2rfc $< $@ - -%.chk: %.xml xml2rfc/rfc2629-refchk.xsl - xsltproc xml2rfc/rfc2629-refchk.xsl $< >$@ - -%.full: %.xml xml2rfc/rfc2629-noinc.xsl - xsltproc xml2rfc/rfc2629-noinc.xsl $< >$@ diff --git a/doc/Makefile.am b/doc/Makefile.am index 80cb280..f9f4f46 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,3 +1,20 @@ man_MANS = memcached.1 EXTRA_DIST = *.txt + +BUILT_SOURCES= + +if BUILD_SPECIFICATIONS +BUILT_SOURCES += protocol-binary.txt protocol-binary-range.txt +MOSTLYCLEANFILES = protocol-binary.txt protocol-binary-range.txt +endif + +%.txt: %.full + @XML2RFC@ $< $@ + +%.chk: %.xml xml2rfc/rfc2629-refchk.xsl + @XSLTPROC@ xml2rfc/rfc2629-refchk.xsl $< >$@ + +%.full: %.xml xml2rfc/rfc2629-noinc.xsl + @XSLTPROC@ xml2rfc/rfc2629-noinc.xsl $< >$@ + diff --git a/doc/protocol-binary-range.txt b/doc/protocol-binary-range.txt deleted file mode 100644 index 7bf8d40..0000000 --- a/doc/protocol-binary-range.txt +++ /dev/null @@ -1,336 +0,0 @@ - - - -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 - -Status of this Memo - - This document is an Internet-Draft and is NOT offered in accordance - with Section 10 of RFC 2026, and the author does not provide the IETF - with any rights other than to publish as an Internet-Draft. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. - - 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." - - The list of current Internet-Drafts can be accessed at - http://www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on June 16, 2008. - -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. - - - - - - - - -Aaron Stone Expires June 16, 2008 [Page 1] - -Internet-Draft Memcache Over UDP December 2007 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 1.1. Conventions Used In This Document . . . . . . . . . . . . . 3 - 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3.1. Get Response . . . . . . . . . . . . . . . . . . . . . . . 4 - 3.2. Get Range Request . . . . . . . . . . . . . . . . . . . . . 4 - 3.3. Get Range Response . . . . . . . . . . . . . . . . . . . . 5 - 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 - 5. Normative References . . . . . . . . . . . . . . . . . . . . . 6 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 6 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Aaron Stone Expires June 16, 2008 [Page 2] - -Internet-Draft Memcache Over UDP December 2007 - - -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]. - - -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. - - - - - - -Aaron Stone Expires June 16, 2008 [Page 3] - -Internet-Draft Memcache Over UDP December 2007 - - -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 - 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. - - - - - - - - - - - - - - - - - -Aaron Stone Expires June 16, 2008 [Page 4] - -Internet-Draft Memcache Over UDP December 2007 - - - 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. - - 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 - - - - - - - -Aaron Stone Expires June 16, 2008 [Page 5] - -Internet-Draft Memcache Over UDP December 2007 - - -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 6] - diff --git a/doc/protocol-binary.txt b/doc/protocol-binary.txt deleted file mode 100644 index 7767e68..0000000 --- a/doc/protocol-binary.txt +++ /dev/null @@ -1,1736 +0,0 @@ - - - -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 - -Status of this Memo - - This document is an Internet-Draft and is NOT offered in accordance - with Section 10 of RFC 2026, and the author does not provide the IETF - with any rights other than to publish as an Internet-Draft. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. - - 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." - - The list of current Internet-Drafts can be accessed at - http://www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on March 1, 2009. - -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. - - - - - - - -Stone & Norbye Expires March 1, 2009 [Page 1] - -Internet-Draft Memcache Binary Protocol August 2008 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 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 - - - - - - - - - - - - - - -Stone & Norbye Expires March 1, 2009 [Page 2] - -Internet-Draft Memcache Binary Protocol August 2008 - - -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 - 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). - - - - - - - -Stone & Norbye Expires March 1, 2009 [Page 4] - -Internet-Draft Memcache Binary Protocol August 2008 - - - Extras length Length in bytes of the command extras. - Data type Reserved for future use (Sean is using this - soon). - 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 - 0x0081 Unknown command - - - - - - - -Stone & Norbye Expires March 1, 2009 [Page 5] - -Internet-Draft Memcache Binary Protocol August 2008 - - - 0x0082 Out of memory - -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 not send back a response, except for - GetQ and GetKQ. See the description of the Get commands - (Section 4.2) for a full description. - -3.4. Data Types - - Possible values of the one-byte field: - 0x00 Raw bytes - - -4. Commands - - - - - - -Stone & Norbye Expires March 1, 2009 [Page 6] - -Internet-Draft Memcache Binary Protocol August 2008 - - -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. - - - - - -Stone & Norbye Expires March 1, 2009 [Page 8] - -Internet-Draft Memcache Binary Protocol August 2008 - - - MUST have key. - MUST NOT have value. - - o 4 byte flags - - 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 | 0x0E | - +---------------+---------------+---------------+---------------+ - 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. - -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 | 0x0e | 0x10 | - +---------------+---------------+---------------+---------------+ - 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): 0x00000e10 - 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 | 0x0e | 0x10 | - +---------------+---------------+---------------+---------------+ - 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 - exipration (40-43): 0x00000e10 - 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. - - - - - -Stone & Norbye Expires March 1, 2009 [Page 20] - -Internet-Draft Memcache Binary Protocol August 2008 - - - MUST NOT have value. - - 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 - - - - - - -Stone & Norbye Expires March 1, 2009 [Page 21] - -Internet-Draft Memcache Binary Protocol August 2008 - - - MAY have extras. - MUST NOT have key. - MUST NOT have value. - - 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 | 0x0e | 0x10 | - +---------------+---------------+---------------+---------------+ - 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): 0x000e10 - 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. - - The server responds with a packet containing the version string in - - - -Stone & Norbye Expires March 1, 2009 [Page 24] - -Internet-Draft Memcache Binary Protocol August 2008 - - - 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 - Exstras : None - Key : The textual string "pid" - Value : The textual string "3078" - - -5. Security Considerations - - Memcache has no authentication or 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 - - -6. Normative References - - [KEYWORDS] - Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [LJ] Danga Interactive, "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] - diff --git a/doc/readme.txt b/doc/readme.txt index f21c87b..6a9d0c8 100644 --- a/doc/readme.txt +++ b/doc/readme.txt @@ -1,4 +1 @@ To build the documentation you need xml2rfc ( http://xml.resource.org/ ). - -Create the textual version of the file with the following command: -make -f Makefile-xml2rfc protocol-binary.txt |