Index: /branches/binary/server/doc/protocol-binary.txt
===================================================================
--- /branches/binary/server/doc/protocol-binary.txt (revision 776)
+++ /branches/binary/server/doc/protocol-binary.txt (revision 776)
@@ -0,0 +1,728 @@
+
+
+
+Network Working Group                                   Aaron Stone, Ed.
+Internet-Draft                                           Six Apart, Ltd.
+Intended status: Informational                         December 14, 2007
+Expires: June 16, 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 June 16, 2008.
+
+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.
+
+
+
+
+
+
+
+
+Aaron Stone               Expires June 16, 2008                 [Page 1]
+
+Internet-Draft          Memcache Binary Protocol           December 2007
+
+
+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  . . . . . . . . . . . . . . . . . . . . .  5
+     3.4.  Data Types . . . . . . . . . . . . . . . . . . . . . . . .  6
+   4.  Commands . . . . . . . . . . . . . . . . . . . . . . . . . . .  6
+     4.1.  Get, Get Quietly . . . . . . . . . . . . . . . . . . . . .  6
+     4.2.  Delete . . . . . . . . . . . . . . . . . . . . . . . . . .  7
+     4.3.  Set, Add, Replace  . . . . . . . . . . . . . . . . . . . .  7
+     4.4.  noop . . . . . . . . . . . . . . . . . . . . . . . . . . .  8
+     4.5.  Increment, Decrement . . . . . . . . . . . . . . . . . . .  8
+   5.  Example Session  . . . . . . . . . . . . . . . . . . . . . . .  9
+   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 13
+   7.  Normative References . . . . . . . . . . . . . . . . . . . . . 13
+   Appendix A.  Acknowledgments . . . . . . . . . . . . . . . . . . . 13
+   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Aaron Stone               Expires June 16, 2008                 [Page 2]
+
+Internet-Draft          Memcache Binary Protocol           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.
+
+   Memcache was originally written to make LiveJournal [LJ] go 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                                                        /
+       /                                                               /
+       /                                                               /
+       /                                                               /
+       +---------------+---------------+---------------+---------------+
+     16/ COMMAND-SPECIFIC EXTRAS (as needed)                           /
+      +/  (note length in th 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 16 bytes
+
+
+
+
+
+
+
+
+
+Aaron Stone               Expires June 16, 2008                 [Page 3]
+
+Internet-Draft          Memcache Binary Protocol           December 2007
+
+
+   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| Message ID                                                    |
+       +---------------+---------------+---------------+---------------+
+     Total 16 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        | Status                        |
+       +---------------+---------------+---------------+---------------+
+      4| Extras length | Data type     | Reserved                      |
+       +---------------+---------------+---------------+---------------+
+      8| Total body length                                             |
+       +---------------+---------------+---------------+---------------+
+     12| Message ID                                                    |
+       +---------------+---------------+---------------+---------------+
+     Total 16 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).
+   Reserved            Really reserved for future use (up for grabs).
+   Total body length   Length in bytes of extra + key + value.
+   Message ID          Will be copied back to you in the response.
+                       FIXME: Can this be used to organize [UDP]
+                       packets?
+
+
+
+
+
+Aaron Stone               Expires June 16, 2008                 [Page 4]
+
+Internet-Draft          Memcache Binary Protocol           December 2007
+
+
+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/reponse value pair.  This is useful for protocol
+   analyzers to know what a packet is in isolation from which direction
+   it is moving.  Note that 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
+   0x0081  Unknown command
+   0x0001  Key not found
+   0x0002  Key exists
+
+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
+
+
+
+
+
+
+
+Aaron Stone               Expires June 16, 2008                 [Page 5]
+
+Internet-Draft          Memcache Binary Protocol           December 2007
+
+
+   0x08    Flush
+   0x09    GetQ
+   0x0A    No-op
+   0x0B    Version
+
+3.4.  Data Types
+
+   Possible values of the one-byte field:
+   0x00    Raw bytes
+
+
+4.  Commands
+
+4.1.  Get, Get Quietly
+
+      MUST have extras.
+      MUST have key.
+      MUST NOT have value.
+
+   o  4 byte flags
+   o  8 byte data version check
+
+   Extra data for get/getq:
+
+     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| Data version check                                            |
+       |                                                               |
+       +---------------+---------------+---------------+---------------+
+      8| Flags                                                         |
+       +---------------+---------------+---------------+---------------+
+     Total 12 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.
+
+   You're not guaranteed a response to a getq cache hit until you send a
+   non-getq command later, which uncorks the server which 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, the last being a regular get. 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 gets, but then you could potentially
+
+
+
+Aaron Stone               Expires June 16, 2008                 [Page 6]
+
+Internet-Draft          Memcache Binary Protocol           December 2007
+
+
+   get back a lot of "NOT_FOUND!" error code packets. alternatively, you
+   can send 'n' getqs, followed by an 'echo' or 'noop' command.
+
+4.2.  Delete
+
+      MAY have extras (FIXME: Is it OK to issue a delete without
+      extras?).
+      MUST have key.
+      MUST NOT have value.
+
+   o  4 byte expiration time
+
+   Extra data for delete:
+
+     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
+
+   When allows you to 'reserve' a key.  When 'when' is set for, say, ten
+   seconds in the future, the 'add' and 'replace' operations will fail
+   for that key until ten seconds from now.  The 'set' operation will
+   succeed regardless of any reserved deletes.  FIXME: Is the
+   reservation also cancelled?  Say there's a delete with a 10 second
+   hold.  Two seconds later, an 'add' is received.  It fails.  Two
+   second later, a 'set' is received.  Is succeeds unconditionally.
+   What if another 'add' is received two more seconds later (a total of
+   six seconds since the original 10 second delete-hold, thus still
+   within its purview).
+
+4.3.  Set, Add, Replace
+
+      MUST have extras.
+      MUST have key.
+      MUST have value.
+
+   o  4 byte flags
+   o  4 byte expiration time
+   o  8 byte data version check
+
+
+
+
+
+
+
+
+
+Aaron Stone               Expires June 16, 2008                 [Page 7]
+
+Internet-Draft          Memcache Binary Protocol           December 2007
+
+
+   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| Data version check                                            |
+       |                                                               |
+       +---------------+---------------+---------------+---------------+
+      8| Flags                                                         |
+       +---------------+---------------+---------------+---------------+
+     12| Expiration                                                    |
+       +---------------+---------------+---------------+---------------+
+     Total 16 bytes
+
+   If the Data Version Check is present and nonzero, the set MUST
+   succeed if the key exists and has a version identifier identical to
+   the provided value, and MUST NOT succeed if the key does not exist or
+   has a different version identifier.  The set response packet will
+   include the same values in all three fields.
+
+   If the Data Version Check is zero, the set MUST succeed
+   unconditionally.  The set response packet will include idential
+   values for flags and expiration, and a new value for Data Version
+   Check, which the client SHOULD keep track of.
+
+   The key MAY be reserved according to Section 4.2, causing the set to
+   fail.
+
+4.4.  noop
+
+      MUST NOT have extras.
+      MUST NOT have key.
+      MUST NOT have value.
+
+   Used as a keep alive.  Flushes outstanding getq's.
+
+4.5.  Increment, Decrement
+
+      MUST have extras.
+      MUST have key.
+      MUST NOT have value.
+
+   o  8 byte value to add / subtract (FIXME: Is this unsigned?)
+   o  8 byte initial value (unsigned)
+   o  4 byte expiration time
+
+
+
+
+
+Aaron Stone               Expires June 16, 2008                 [Page 8]
+
+Internet-Draft          Memcache Binary Protocol           December 2007
+
+
+   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
+
+   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
+
+   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.
+
+   Note that in the creation case, flags will be set to zero (FIXME:
+   Should they be provided here as well?)
+
+
+5.  Example Session
+
+   We start up our application, and it asks for the value associated
+   with the 'Hello' key.
+
+
+
+
+
+
+
+Aaron Stone               Expires June 16, 2008                 [Page 9]
+
+Internet-Draft          Memcache Binary Protocol           December 2007
+
+
+   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          | 5 in big endian (BE)          |
+       +---------------+---------------+---------------+---------------+
+       | 12 in BE      | 0x00          |                               |
+       +---------------+---------------+---------------+---------------+
+       | 17 in BE                                                      |
+       +---------------+---------------+---------------+---------------+
+       | 0xDEADBEEF                                                    |
+       +---------------+---------------+---------------+---------------+
+     16| 0x00000000                                                    |
+       +---------------+---------------+---------------+---------------+
+     24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
+       |                                                               |
+       +---------------+---------------+---------------+---------------+
+     28| 'H'             'e'             'l'             'l'           |
+       | 'o'           |
+       +---------------+
+     Total 33 bytes (16 header + 12 get-extras + 5 key)
+
+   Since nobody has set this key, it returns not found.
+
+   Get 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          | 0x0001                        |
+       +---------------+---------------+---------------+---------------+
+       | 0 in BE       | 0x00          |                               |
+       +---------------+---------------+---------------+---------------+
+       | 0 in BE                                                       |
+       +---------------+---------------+---------------+---------------+
+       | 0xDEADBEEF                                                    |
+       +---------------+---------------+---------------+---------------+
+     Total 16 bytes
+
+   Well, looks like we need to set the key!  Let's set it to expire on
+   December 15, 2007 at 9:51:09 PM.
+
+
+
+
+
+
+
+Aaron Stone               Expires June 16, 2008                [Page 10]
+
+Internet-Draft          Memcache Binary Protocol           December 2007
+
+
+   Set 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          | 0x01          | 5 in BE                       |
+       +---------------+---------------+---------------+---------------+
+       | 16 in BE      | 0x00          |                               |
+       +---------------+---------------+---------------+---------------+
+       | 26 in BE                                                      |
+       +---------------+---------------+---------------+---------------+
+       | 0xDA7ABA5E                                                    |
+       +---------------+---------------+---------------+---------------+
+     16| 0x00000000                                                    |
+       +---------------+---------------+---------------+---------------+
+     20| 0xDCCB4674                                                    |
+       +---------------+---------------+---------------+---------------+
+     24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
+       |                                                               |
+       +---------------+---------------+---------------+---------------+
+     32| 'H'             'e'             'l'             'l'           |
+       | 'o'           | 'W'             'o'             'r'           |
+       | 'l'             'd'           |
+       +---------------+---------------+
+     Total 42 bytes (16 header + 16 set-extras + 5 key + 5 value)
+
+   The set succeeds.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Aaron Stone               Expires June 16, 2008                [Page 11]
+
+Internet-Draft          Memcache Binary Protocol           December 2007
+
+
+   Set 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          | 0x01          | 0x0000                        |
+       +---------------+---------------+---------------+---------------+
+       | 16 in BE      | 0x00          |                               |
+       +---------------+---------------+---------------+---------------+
+       | 16 in BE                                                      |
+       +---------------+---------------+---------------+---------------+
+       | 0xDA7ABA5E                                                    |
+       +---------------+---------------+---------------+---------------+
+     16| 0x00000000                                                    |
+       +---------------+---------------+---------------+---------------+
+     20| 0xDCCB4674                                                    |
+       +---------------+---------------+---------------+---------------+
+     24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
+       |                                                               |
+       +---------------+---------------+---------------+---------------+
+     Total 32 bytes (16 header + 16 set-extras)
+
+   If the original get request is sent again, the key would be found.
+
+   Get 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          |               |
+       +---------------+---------------+---------------+---------------+
+       | 12 in BE      | 0x00          |                               |
+       +---------------+---------------+---------------+---------------+
+       | 17 in BE                                                      |
+       +---------------+---------------+---------------+---------------+
+       | 0xDEADBEEF                                                    |
+       +---------------+---------------+---------------+---------------+
+     16| 0xDCCB4674                                                    |
+       +---------------+---------------+---------------+---------------+
+     24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
+       |                                                               |
+       +---------------+---------------+---------------+---------------+
+     28| 'W'             'o'             'r'             'l'           |
+       | 'd'           |
+       +---------------+
+     Total 33 bytes (16 header + 12 get-extras + 5 value)
+
+
+
+Aaron Stone               Expires June 16, 2008                [Page 12]
+
+Internet-Draft          Memcache Binary Protocol           December 2007
+
+
+6.  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.
+
+
+7.  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.
+
+   [UDP]      Postel, J., "User Datagram Protocol", STD 6, RFC 768,
+              August 1980.
+
+
+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.
+
+
+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 13]
+
Index: /branches/binary/server/doc/protocol-binary.xml
===================================================================
--- /branches/binary/server/doc/protocol-binary.xml (revision 776)
+++ /branches/binary/server/doc/protocol-binary.xml (revision 776)
@@ -0,0 +1,668 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<!DOCTYPE rfc SYSTEM "xml2rfc/rfc2629.dtd">
+<?xml-stylesheet type='text/xsl' href='rfc2629.xslt'?>
+<?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="none">
+
+  <front>
+
+    <title> Memcache Binary Protocol </title>
+
+    <author fullname="Aaron Stone" surname="Aaron 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>
+
+    <date day="14" month="December" year="2007" />
+
+    <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">
+      <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>
+      <t>
+      Memcache was originally written to make <xref target="LJ">LiveJournal</xref> go faster.
+      It now powers all of the fastest web sites that you love.
+      </t>
+      <section anchor="conventions" title="Conventions Used In This Document">
+        <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">
+      <t>
+      <figure>
+        <preamble>General format of a packet:</preamble>
+          <artwork>
+    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                                                        /
+      /                                                               /
+      /                                                               /
+      /                                                               /
+      +---------------+---------------+---------------+---------------+
+    16/ COMMAND-SPECIFIC EXTRAS (as needed)                           /
+     +/  (note length in th 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 16 bytes
+      </artwork></figure>
+      </t>
+
+      <t>
+      <figure>
+        <preamble>Request header:</preamble>
+          <artwork>
+    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| Message ID                                                    |
+      +---------------+---------------+---------------+---------------+
+    Total 16 bytes
+      </artwork></figure>
+      </t>
+
+      <t>
+      <figure>
+        <preamble>Response header:</preamble>
+          <artwork>
+    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        | Status                        |
+      +---------------+---------------+---------------+---------------+
+     4| Extras length | Data type     | Reserved                      |
+      +---------------+---------------+---------------+---------------+
+     8| Total body length                                             |
+      +---------------+---------------+---------------+---------------+
+    12| Message ID                                                    |
+      +---------------+---------------+---------------+---------------+
+    Total 16 bytes
+      </artwork></figure>
+      </t>
+
+      <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="Message ID">Will be copied back to you in the response.
+              FIXME: Can this be used to organize <xref target="UDP"/> packets?</t>
+        </list>
+      </t>
+    </section>
+
+    <section anchor="values" title="Defined Values">
+      <section anchor="value-magic" title="Magic Byte">
+        <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/reponse value pair. This is useful for protocol
+          analyzers to know what a packet is in isolation from which direction
+          it is moving. Note that 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">
+        <t>
+        Possible values of this two-byte field:
+        <list hangIndent="8" style="hanging">
+          <t hangText="0x0000">No error</t>
+          <t hangText="0x0081">Unknown command</t>
+          <t hangText="0x0001">Key not found</t>
+          <t hangText="0x0002">Key exists</t>
+        </list>
+        </t>
+      </section>
+
+      <section anchor="value-opcodes" title="Command Opcodes">
+        <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>
+        </list>
+        </t>
+      </section>
+
+      <section anchor="value-types" title="Data Types">
+        <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">
+      <section anchor="command-get" title="Get, Get Quietly">
+        <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>4 byte flags</t>
+          <t>8 byte data version check</t>
+        </list>
+        </t>
+
+        <t>
+      <figure>
+        <preamble>Extra data for get/getq:</preamble>
+          <artwork>
+    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| Data version check                                            |
+      |                                                               |
+      +---------------+---------------+---------------+---------------+
+     8| Flags                                                         |
+      +---------------+---------------+---------------+---------------+
+    Total 12 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.
+        </t>
+
+        <t>
+          You're not guaranteed a response to a getq cache hit until
+          you send a non-getq command later, which uncorks the
+          server which 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, the last being a regular
+          get.  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 gets, but then you could potentially
+          get back a lot of "NOT_FOUND!" error code packets.
+          alternatively, you can send 'n' getqs, followed by an 'echo'
+          or 'noop' command.
+        </t>
+
+      </section>
+
+      <section anchor="command-delete" title="Delete">
+        <t>
+        <list style="empty">
+          <t>MAY have extras (FIXME: Is it OK to issue a delete without extras?).</t>
+          <t>MUST have key.</t>
+          <t>MUST NOT have value.</t>
+        </list>
+        </t>
+
+        <t>
+          <list style="symbols">
+            <t>4 byte expiration time</t>
+          </list>
+        </t>
+
+        <t>
+      <figure>
+        <preamble>Extra data for delete:</preamble>
+          <artwork>
+    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>
+
+        <t>
+          When allows you to 'reserve' a key. When 'when' is set
+          for, say, ten seconds in the future, the 'add' and 'replace' operations will fail for that key 
+          until ten seconds from now.  The 'set' operation will succeed regardless of any reserved deletes.
+          FIXME: Is the reservation also cancelled? Say there's a delete with a 10 second hold. Two seconds
+          later, an 'add' is received. It fails. Two second later, a 'set' is received. Is succeeds unconditionally.
+          What if another 'add' is received two more seconds later (a total of six seconds since the original
+          10 second delete-hold, thus still within its purview).
+        </t>
+
+      </section>
+
+      <section anchor="command-set" title="Set, Add, Replace">
+        <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>
+            <t>8 byte data version check</t>
+          </list>
+        </t>
+
+        <t>
+        <figure>
+          <preamble>Extra data for set/add/replace:</preamble>
+            <artwork>
+    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| Data version check                                            |
+      |                                                               |
+      +---------------+---------------+---------------+---------------+
+     8| Flags                                                         |
+      +---------------+---------------+---------------+---------------+
+    12| Expiration                                                    |
+      +---------------+---------------+---------------+---------------+
+    Total 16 bytes
+        </artwork></figure>
+        </t>
+
+        <t>
+        If the Data Version Check is present and nonzero, the set MUST succeed if the
+        key exists and has a version identifier identical to the provided value, and
+	MUST NOT succeed if the key does not exist or has a different version identifier.
+	The set response packet will include the same values in all three fields.
+        </t>
+
+        <t>
+        If the Data Version Check is zero, the set MUST succeed unconditionally.
+	The set response packet will include idential values for flags and expiration,
+	and a new value for Data Version Check, which the client SHOULD keep track of.
+        </t>
+
+	<t>
+	The key MAY be reserved according to <xref target="command-delete"/>,
+	causing the set to fail.
+	</t>
+      </section>
+
+      <section title="noop">
+        <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's.
+        </t>
+      </section>
+
+      <section anchor="command-incr" title="Increment, Decrement">
+        <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 (FIXME: Is this unsigned?)</t>
+            <t>8 byte initial value (unsigned)</t>
+            <t>4 byte expiration time</t>
+          </list>
+        </t>
+
+        <t>
+      <figure>
+        <preamble>Extra data for incr/decr:</preamble>
+          <artwork>
+    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>
+
+        <t>
+      <figure>
+        <preamble>incr/decr response body:</preamble>
+          <artwork>
+    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>
+        </t>
+
+        <t>
+          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:
+          
+          <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.</t>
+          </list>
+        </t>
+          
+        <t>
+          Note that in the creation case, flags will be set to zero
+          (FIXME:  Should they be provided here as well?)
+        </t>
+      </section>
+    </section>
+
+    <section title="Example Session">
+      <t>
+      We start up our application, and it asks for the value associated with the 'Hello' key.
+      <figure>
+        <preamble>Get request:</preamble>
+          <artwork>
+    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          | 5 in big endian (BE)          |
+      +---------------+---------------+---------------+---------------+
+      | 12 in BE      | 0x00          |                               |
+      +---------------+---------------+---------------+---------------+
+      | 17 in BE                                                      |
+      +---------------+---------------+---------------+---------------+
+      | 0xDEADBEEF                                                    |
+      +---------------+---------------+---------------+---------------+
+    16| 0x00000000                                                    |
+      +---------------+---------------+---------------+---------------+
+    24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
+      |                                                               |
+      +---------------+---------------+---------------+---------------+
+    28| 'H'             'e'             'l'             'l'           |
+      | 'o'           |
+      +---------------+
+    Total 33 bytes (16 header + 12 get-extras + 5 key)
+      </artwork></figure>
+      </t>
+
+      <t>
+      Since nobody has set this key, it returns not found.
+      <figure>
+        <preamble>Get response:</preamble>
+          <artwork>
+    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          | 0x0001                        |
+      +---------------+---------------+---------------+---------------+
+      | 0 in BE       | 0x00          |                               |
+      +---------------+---------------+---------------+---------------+
+      | 0 in BE                                                       |
+      +---------------+---------------+---------------+---------------+
+      | 0xDEADBEEF                                                    |
+      +---------------+---------------+---------------+---------------+
+    Total 16 bytes
+      </artwork></figure>
+      </t>
+
+      <t>
+      Well, looks like we need to set the key! Let's set it to expire on
+      December 15, 2007 at 9:51:09 PM.
+      <figure>
+        <preamble>Set request:</preamble>
+          <artwork>
+    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          | 0x01          | 5 in BE                       |
+      +---------------+---------------+---------------+---------------+
+      | 16 in BE      | 0x00          |                               |
+      +---------------+---------------+---------------+---------------+
+      | 26 in BE                                                      |
+      +---------------+---------------+---------------+---------------+
+      | 0xDA7ABA5E                                                    |
+      +---------------+---------------+---------------+---------------+
+    16| 0x00000000                                                    |
+      +---------------+---------------+---------------+---------------+
+    20| 0xDCCB4674                                                    | 
+      +---------------+---------------+---------------+---------------+
+    24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
+      |                                                               |
+      +---------------+---------------+---------------+---------------+
+    32| 'H'             'e'             'l'             'l'           |
+      | 'o'           | 'W'             'o'             'r'           |
+      | 'l'             'd'           |
+      +---------------+---------------+
+    Total 42 bytes (16 header + 16 set-extras + 5 key + 5 value)
+      </artwork></figure>
+      </t>
+
+      <t>
+      The set succeeds.
+      <figure>
+        <preamble>Set response:</preamble>
+          <artwork>
+    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          | 0x01          | 0x0000                        |
+      +---------------+---------------+---------------+---------------+
+      | 16 in BE      | 0x00          |                               |
+      +---------------+---------------+---------------+---------------+
+      | 16 in BE                                                      |
+      +---------------+---------------+---------------+---------------+
+      | 0xDA7ABA5E                                                    |
+      +---------------+---------------+---------------+---------------+
+    16| 0x00000000                                                    |
+      +---------------+---------------+---------------+---------------+
+    20| 0xDCCB4674                                                    | 
+      +---------------+---------------+---------------+---------------+
+    24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
+      |                                                               |
+      +---------------+---------------+---------------+---------------+
+    Total 32 bytes (16 header + 16 set-extras)
+      </artwork></figure>
+      </t>
+
+      <t>
+      If the original get request is sent again, the key would be found.
+      <figure>
+        <preamble>Get response:</preamble>
+          <artwork>
+    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          |               |
+      +---------------+---------------+---------------+---------------+
+      | 12 in BE      | 0x00          |                               |
+      +---------------+---------------+---------------+---------------+
+      | 17 in BE                                                      |
+      +---------------+---------------+---------------+---------------+
+      | 0xDEADBEEF                                                    |
+      +---------------+---------------+---------------+---------------+
+    16| 0xDCCB4674                                                    | 
+      +---------------+---------------+---------------+---------------+
+    24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
+      |                                                               |
+      +---------------+---------------+---------------+---------------+
+    28| 'W'             'o'             'r'             'l'           |
+      | 'd'           |
+      +---------------+
+    Total 33 bytes (16 header + 12 get-extras + 5 value)
+      </artwork></figure>
+      </t>
+    </section>
+
+    <section anchor="security" title="Security Considerations">
+      <t>
+      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.
+      </t>
+    </section>
+
+  </middle>
+
+  <back>
+    <references title="Normative References">
+      <reference anchor="LJ">
+        <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>
+      <dwdrfc-ref anchor='UDP' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.0768.xml'/>
+      <dwdrfc-ref anchor='KEYWORDS' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/>
+    </references>
+
+    <section anchor="acknowledgments" title="Acknowledgments">
+      <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>
+
Index: /branches/binary/server/doc/Makefile-xml2rfc
===================================================================
--- /branches/binary/server/doc/Makefile-xml2rfc (revision 776)
+++ /branches/binary/server/doc/Makefile-xml2rfc (revision 776)
@@ -0,0 +1,8 @@
+%.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 $< >$@
Index: /branches/binary/server/doc/protocol-binary-range.txt
===================================================================
--- /branches/binary/server/doc/protocol-binary-range.txt (revision 776)
+++ /branches/binary/server/doc/protocol-binary-range.txt (revision 776)
@@ -0,0 +1,336 @@
+
+
+
+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]
+
Index: /branches/binary/server/doc/protocol-binary-range.xml
===================================================================
--- /branches/binary/server/doc/protocol-binary-range.xml (revision 776)
+++ /branches/binary/server/doc/protocol-binary-range.xml (revision 776)
@@ -0,0 +1,226 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
+<?xml-stylesheet type='text/xsl' href='rfc2629.xslt'?>
+<?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-udp-01" ipr="none">
+
+  <front>
+
+    <title abbrev="Memcache Over UDP"> Memcache Binary Protocol: Extensions for UDP </title>
+
+    <author fullname="Aaron Stone" surname="Aaron 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>
+
+    <date day="14" month="December" year="2007" />
+
+    <area>Applications</area>
+
+    <keyword>memcache memcached cache udp</keyword>
+
+    <abstract>
+      <t>
+      This memo explains extensions to the memcache binary protocol for use in a UDP environment.
+      </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">
+      <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>
+      <t>
+      Sites may find that, due to their network architecture or application usage patterns,
+      the stateless <xref target="UDP"/> protocol better suits their needs. This document
+      provides extensions and descriptions of use of the <xref target="MEMCACHE">memcache protocol</xref>
+      in a UDP environment.
+      </t>
+      <t>
+      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.
+      </t>
+      <section anchor="conventions" title="Conventions Used In This Document">
+        <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="values" title="Defined Values">
+      <section anchor="value-magic" title="Magic Byte">
+        <t>
+        The magic bytes remains the same as in <xref target="MEMCACHE"/>.
+        </t>
+      </section>
+
+      <section anchor="value-status" title="Response Status">
+        <t>
+        Additional status values:
+        <list hangIndent="8" style="hanging">
+          <t hangText="0x0004">Value is larger than a single response packet</t>
+        </list>
+        </t>
+      </section>
+
+      <section anchor="value-opcodes" title="Command Opcodes">
+        <t>
+        Additional opcode values:
+        <list hangIndent="8" style="hanging">
+          <t hangText="0x0C">Get Range</t>
+          <t hangText="0x0D">Set Range</t>
+        </list>
+        </t>
+      </section>
+
+      <section anchor="value-types" title="Data Types">
+        <t>
+        There are no new data types in this extension.
+        </t>
+      </section>
+    </section>
+
+    <section anchor="commands" title="Commands">
+
+      <section anchor="command-get" title="Get Response">
+        <t>
+        This section extends the behavior of the Get and GetQ commands as described in 
+        <xref target="MEMCACHE" x:sec="command-get"/>.
+        </t>
+
+        <t>
+        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:
+        <list style="numbers">
+          <t>The Status field of the response header MUST be 0x0004.</t>
+          <t>The Offset field of the GetR response extras MUST be 0.</t>
+          <t>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.</t>
+          <t>The Total value length field of the response extras MUST be the
+             actual length of the complete value.</t>
+        </list>
+        </t>
+
+        <t>
+        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.
+        </t>
+      </section>
+
+      <section anchor="command-getr-request" title="Get Range Request">
+        <t>
+	  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.
+	</t>
+        <t>
+      <figure>
+        <preamble>Extra data for get range request:</preamble>
+          <artwork>
+    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
+      </artwork></figure>
+        </t>
+      </section>
+
+      <section anchor="command-getr-response" title="Get Range Response">
+        <t>
+	  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.
+	</t>
+        <t>
+      <figure>
+        <preamble>Extra data for get range response:</preamble>
+          <artwork>
+    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
+      </artwork></figure>
+        </t>
+      </section>
+
+    </section>
+
+    <section anchor="security" title="Security Considerations">
+      <t>
+      This document does not introduce any new security considerations
+      beyond those discussed in <xref target="MEMCACHE" x:sec="security"/>.
+      </t>
+    </section>
+
+  </middle>
+
+  <back>
+    <references title="Normative References">
+      <dwdrfc-ref anchor='UDP' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.0768.xml'/>
+      <dwdrfc-ref anchor='KEYWORDS' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/>
+      <!-- FIXME: Get a draft reference for the base document. -->
+      <dwdrfc-ref anchor='MEMCACHE' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/>
+    </references>
+  </back>
+
+</rfc>
+
Index: /branches/binary/server/doc/xml2rfc/rfc2629-other.ent
===================================================================
--- /branches/binary/server/doc/xml2rfc/rfc2629-other.ent (revision 776)
+++ /branches/binary/server/doc/xml2rfc/rfc2629-other.ent (revision 776)
@@ -0,0 +1,61 @@
+<!-- rfc2629-other.ent
+
+     Character entity set for RFC-2629 source xml documents.
+     There is no need to invoke this directly from
+     the source document itself; just invoke the DTD.
+
+     These are unknown to (X)HTML, so any converter to these
+     formats must either substitute these entities
+     or invoke this file from the output file.
+
+     Conversion to txt or nroff format will replace
+     these entities by the parenthesized text.
+
+     Typical invocation:
+       <!ENTITY % rfc2629-other
+                PUBLIC "-//IETF//ENTITIES Other for RFC 2629//EN"
+                       "http://xml.resource.org/authoring/rfc2629-other.ent">
+       %rfc2629-other;
+-->
+
+<!-- Magical -->
+<!--     rfc.number            (automatically expanded to content
+                                of number="..." attribute
+                                of <rfc> element, or to "XXXX")                       -->
+
+<!-- ASCII -->
+<!ENTITY excl     "&#33;"><!-- U+0021 EXCLAMATION MARK                  ("!")         -->
+<!ENTITY num      "&#35;"><!-- U+0023 NUMBER SIGN                       ("#")         -->
+<!ENTITY dollar   "&#36;"><!-- U+0024 DOLLAR SIGN                       ("$")         -->
+<!ENTITY percnt   "&#37;"><!-- U+0025 PERCENT SIGN                      ("%")         -->
+<!ENTITY lpar     "&#40;"><!-- U+0028 LEFT PARENTHESIS                  ("(")         -->
+<!ENTITY rpar     "&#41;"><!-- U+0029 RIGHT PARENTHESIS                 (")")         -->
+<!ENTITY ast      "&#42;"><!-- U+002A ASTERISK                          ("*")         -->
+<!ENTITY plus     "&#43;"><!-- U+002B PLUS SIGN                         ("+")         -->
+<!ENTITY comma    "&#44;"><!-- U+002C COMMA                             (",")         -->
+<!ENTITY hyphen   "&#45;"><!-- U+002D HYPHEN-MINUS                      ("-")         -->
+<!ENTITY period   "&#46;"><!-- U+002E FULL STOP                         (".")         -->
+<!ENTITY sol      "&#47;"><!-- U+002F SOLIDUS                           ("/")         -->
+<!ENTITY colon    "&#58;"><!-- U+003A COLON                             (":")         -->
+<!ENTITY semi     "&#59;"><!-- U+003B SEMICOLON                         (";")         -->
+<!ENTITY equals   "&#61;"><!-- U+003D EQUALS SIGN                       ("=")         -->
+<!ENTITY quest    "&#63;"><!-- U+003F QUESTION MARK                     ("?")         -->
+<!ENTITY commat   "&#64;"><!-- U+0040 COMMERCIAL AT                     ("@")         -->
+<!ENTITY lsqb     "&#91;"><!-- U+005B LEFT SQUARE BRACKET               ("[")         -->
+<!ENTITY bsol     "&#92;"><!-- U+005C REVERSE SOLIDUS                   ("\\")        -->
+<!ENTITY rsqb     "&#93;"><!-- U+005D RIGHT SQUARE BRACKET              ("]")         -->
+<!ENTITY circ     "&#94;"><!-- U+005E CIRCUMFLEX ACCENT                 ("^")         -->
+<!ENTITY lowbar   "&#95;"><!-- U+005F LOW LINE                          ("_")         -->
+<!ENTITY grave    "&#96;"><!-- U+0060 GRAVE ACCENT                      ("`")         -->
+<!ENTITY lcub    "&#123;"><!-- U+007B LEFT CURLY BRACKET                ("{")         -->
+<!ENTITY verbar  "&#124;"><!-- U+007C VERTICAL LINE                     ("|")         -->
+<!ENTITY rcub    "&#125;"><!-- U+007D RIGHT CURLY BRACKET               ("}")         -->
+
+<!-- Useful Unicode -->
+<!ENTITY Zcaron  "&#381;"><!-- U+017D LATIN CAPITAL LETTER Z WITH CARON ("Z")         -->
+<!ENTITY zcaron  "&#382;"><!-- U+017E LATIN SMALL LETTER Z WITH CARON   ("z")         -->
+<!ENTITY dash   "&#8208;"><!-- U+2010 HYPHEN                            ("-")         -->
+<!ENTITY nbhy   "&#8209;"><!-- U+2011 NON-BREAKING HYPHEN               (special "-") -->
+<!ENTITY wj     "&#8288;"><!-- U+2060 WORD JOINER                       (special "")  -->
+
+<!-- EOF -->
Index: /branches/binary/server/doc/xml2rfc/rfc2629-refchk.xsl
===================================================================
--- /branches/binary/server/doc/xml2rfc/rfc2629-refchk.xsl (revision 776)
+++ /branches/binary/server/doc/xml2rfc/rfc2629-refchk.xsl (revision 776)
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                version="1.0">
+
+  <xsl:output method="xml"/>
+
+  <xsl:template match='/'>
+    <refcheck>
+      <xsl:apply-templates select='//xref' mode='missing'/>
+      <xsl:apply-templates select='//reference' mode='orphans'/>
+      <xsl:apply-templates select='//references[@dwdrfc-type = "norm"]' mode='normcheck'/>
+      <xsl:apply-templates select='//xref[@dwdrfc-type = "norm"]' mode='normrefs'/>
+    </refcheck>
+  </xsl:template>
+  
+  <xsl:template match='xref' mode='missing'>
+    <xsl:param name='refname'>
+      <xsl:value-of select='@target'/>
+    </xsl:param>
+    <xsl:param name='reftgt'>
+      <xsl:value-of select='//*[@anchor = $refname]/@anchor'/>
+    </xsl:param>
+    <xsl:choose>
+      <xsl:when test='$reftgt = $refname'/>
+      <xsl:otherwise>
+        <missing><xsl:value-of select='$refname'/></missing><xsl:text>
+      </xsl:text>
+    </xsl:otherwise>
+  </xsl:choose>
+  </xsl:template>
+  
+  <xsl:template match='xref' mode='normrefs'>
+    <xsl:param name='refname'>
+      <xsl:value-of select='@target'/>
+    </xsl:param>
+    <xsl:param name='reftgt'>
+      <xsl:value-of select='//references[@dwdrfc-type = "norm"]/*[@anchor = $refname]/@anchor'/>
+    </xsl:param>
+    <xsl:choose>
+      <xsl:when test='$reftgt = $refname'/>
+      <xsl:otherwise>
+        <missing-norm><xsl:value-of select='$refname'/></missing-norm><xsl:text>
+      </xsl:text>
+    </xsl:otherwise>
+  </xsl:choose>
+  </xsl:template>
+  
+  <xsl:template match='reference' mode='orphans'>
+    <xsl:param name='refname'>
+      <xsl:value-of select='@anchor'/>
+    </xsl:param>
+    <xsl:param name='reftgt'>
+      <xsl:value-of select='//xref[@target = $refname]/@target'/>
+    </xsl:param>
+    <xsl:if test='$reftgt != $refname'>
+      <orphan><xsl:value-of select='$refname'/></orphan><xsl:text>
+    </xsl:text>
+  </xsl:if>
+</xsl:template>
+
+<xsl:template match='references' mode='normcheck'>
+  <xsl:apply-templates mode='normcheck'/>
+</xsl:template>
+
+<xsl:template match='*' mode='normcheck'>
+  <!-- Need to find at least one normative reference -->
+  <xsl:param name='refname'>
+    <xsl:value-of select='@anchor'/>
+  </xsl:param>
+  <xsl:param name='reftgt'>
+    <xsl:value-of select='//xref[@dwdrfc-type = "norm" and @target = $refname]/@target'/>
+  </xsl:param>
+  <xsl:if test='$refname != $reftgt'>
+    <normchk><xsl:value-of select='$refname'/></normchk><xsl:text>
+</xsl:text>
+  </xsl:if>
+</xsl:template>
+
+<xsl:template match='text()' mode='normcheck'/>
+
+</xsl:stylesheet>
Index: /branches/binary/server/doc/xml2rfc/rfc2629-noinc.xsl
===================================================================
--- /branches/binary/server/doc/xml2rfc/rfc2629-noinc.xsl (revision 776)
+++ /branches/binary/server/doc/xml2rfc/rfc2629-noinc.xsl (revision 776)
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                version="1.0">
+
+  <xsl:output method="xml"/>
+
+  <xsl:template name='noinc'>
+    <xsl:apply-templates mode='noinc'/>
+  </xsl:template>
+  
+  <xsl:template match="*" mode='noinc'>
+    <xsl:copy>
+      <xsl:apply-templates select='@*' mode='noinc'/>
+      <xsl:apply-templates mode='noinc'/>
+    </xsl:copy>
+  </xsl:template>
+  <xsl:template match='@*' mode='noinc'>
+    <xsl:attribute name='{name()}'>
+      <xsl:value-of select='.'/>
+    </xsl:attribute>
+  </xsl:template>
+  
+  <xsl:template match='processing-instruction("rfc")' mode='noinc'>
+    <xsl:choose>
+      <xsl:when test='substring-before(.,"=") = "include"'>
+        <xsl:call-template name='include-pi'>
+          <xsl:with-param name='include-href'>
+            <xsl:value-of select="translate( substring-after( ., '=' ), '&quot; ', '' )"/><xsl:text>.xml</xsl:text>
+          </xsl:with-param>
+        </xsl:call-template>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:copy-of select='.'/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+  
+  <xsl:template name='include-pi'>
+    <xsl:param name='include-href'/>
+    <xsl:apply-templates select="document( $include-href )" mode='noinc'/>
+  </xsl:template>
+  
+  <xsl:template match='dwdrfc-ref' mode='noinc'>	
+	<xsl:param name='include-href'>
+          <xsl:choose>
+            <xsl:when test='starts-with( @src, "http://" )'>
+              <xsl:value-of select='@src'/>
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:text>http://xml.resource.org/public/rfc/</xsl:text>
+              <xsl:value-of select='@src'/>
+              <xsl:text>.xml</xsl:text>
+            </xsl:otherwise>
+          </xsl:choose>
+	</xsl:param>
+        <reference anchor="{@anchor}">
+          <xsl:apply-templates select="document( $include-href )" mode="refrename"/>
+	</reference>
+  </xsl:template>
+	
+	<xsl:template match='*' mode='refrename'>
+	<xsl:apply-templates mode='refrename'/>
+	</xsl:template>
+	
+	<xsl:template match='reference' mode='refrename'>
+	<xsl:apply-templates mode='noinc'/>
+	</xsl:template>
+  
+  <xsl:template match='/'>
+    <xsl:call-template name='noinc'/>
+  </xsl:template>
+  
+  <xsl:template name='output'>
+    <xsl:param name='foo'/>
+    <xsl:copy-of select='$foo'/>
+    <xsl:apply-templates select='$foo'/>
+  </xsl:template>
+  
+  <xsl:template match='*' mode='output'>
+    <element>
+      <xsl:value-of select='name()'/>
+      <xsl:apply-templates mode='output'/>
+    </element>
+  </xsl:template>
+  <xsl:template match='text()' mode='output'/>
+  
+  <!-- Reference checking attributes stripped here. -->
+  <xsl:template match='references' mode='noinc'>
+    <xsl:element name='references'>
+      <xsl:attribute name='title'>
+        <xsl:value-of select='@title'/>
+      </xsl:attribute>
+      <xsl:apply-templates mode='noinc'/>
+    </xsl:element>
+  </xsl:template>
+  
+  <xsl:template match='xref' mode='noinc'>
+    <xsl:element name='xref'>
+      <xsl:attribute name='target'>
+        <xsl:value-of select='@target'/>
+      </xsl:attribute>
+      <xsl:apply-templates mode='noinc'/>
+    </xsl:element>
+  </xsl:template>
+  
+</xsl:stylesheet>
Index: /branches/binary/server/doc/xml2rfc/rfc2629.dtd
===================================================================
--- /branches/binary/server/doc/xml2rfc/rfc2629.dtd (revision 776)
+++ /branches/binary/server/doc/xml2rfc/rfc2629.dtd (revision 776)
@@ -0,0 +1,304 @@
+<!--
+  revised DTD for the RFC document series, draft of 2007-03-29
+  -->
+
+
+<!--
+  Typical invocation:
+      <!DOCTYPE rfc PUBLIC "-//IETF//DTD RFC 2629//EN"
+                           "http://xml.resource.org/authoring/rfc2629.dtd" [
+        ... dtd subset ...
+      ]>
+    or
+      <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
+        ... dtd subset ...
+      ]>
+  -->
+
+
+<!--
+  Contents
+
+    Character entities
+
+    DTD data types
+
+    The top-level
+
+    Front matter
+
+    The Body
+
+    Back matter
+  -->
+
+
+<!--
+  Character entities
+  -->
+
+
+<!ENTITY % rfc2629-xhtml
+         PUBLIC "-//IETF//ENTITIES XHTML subset for RFC 2629//EN"
+                "rfc2629-xhtml.ent">
+%rfc2629-xhtml;
+
+<!ENTITY % rfc2629-other
+         PUBLIC "-//IETF//ENTITIES Other for RFC 2629//EN"
+                "rfc2629-other.ent">
+%rfc2629-other;
+
+
+<!--
+  DTD data types:
+
+        entity        description
+        ======        ===============================================
+        NUMBER        [0-9]+
+        NUMBERS       a comma-separated list of NUMBER
+
+        DAY           the day of the month, e.g., "1"
+        MONTH         the month of the year, e.g., "January"
+        YEAR          a four-digit year, e.g., "1999"
+
+        URI           e.g., "http://invisible.net/"
+
+        ATEXT/CTEXT   printable ASCII text (no line-terminators)
+
+        TEXT          character data
+  -->
+
+
+<!ENTITY % NUMBER     "CDATA">
+<!ENTITY % NUMBERS    "CDATA">
+
+<!ENTITY % DAY        "CDATA">
+<!ENTITY % MONTH      "CDATA">
+<!ENTITY % YEAR       "CDATA">
+
+<!ENTITY % URI        "CDATA">
+
+<!ENTITY % ATEXT      "CDATA">
+<!ENTITY % CTEXT      "#PCDATA">
+
+<!ENTITY % TEXT       "#PCDATA">
+
+<!ENTITY   rfc.number "XXXX">
+
+
+<!--
+  The top-level
+  -->
+
+
+<!--
+  attributes for the "rfc" element are supplied by the RFC
+  editor. when preparing drafts, authors should leave them blank.
+
+  the "seriesNo" attribute is used if the category is, e.g., BCP.
+  -->
+<!ELEMENT rfc         (front,middle,back?)>
+<!ATTLIST rfc
+          number      %NUMBER;           #IMPLIED
+          obsoletes   %NUMBERS;          ""
+          updates     %NUMBERS;          ""
+          category    (std|bcp|info|exp|historic)
+                                         #IMPLIED
+          seriesNo    %NUMBER;           #IMPLIED
+          ipr         (full2026|noDerivativeWorks2026|none
+                      |full3667|noModification3667|noDerivatives3667
+                      |full3978|noModification3978|noDerivatives3978)
+                                         #IMPLIED
+          iprExtract  IDREF              #IMPLIED
+          submissionType
+                      (IETF|independent) "IETF"
+          docName     %ATEXT;            #IMPLIED
+          xml:lang    %ATEXT;            "en">
+
+
+<!--
+  Front matter
+  -->
+
+
+<!ELEMENT front       (title,author+,date,area*,workgroup*,keyword*,
+                       abstract?,note*)>
+
+<!-- the "abbrev" attribute is used for headers, etc. -->
+<!ELEMENT title       (%CTEXT;)>
+<!ATTLIST title
+          abbrev      %ATEXT;            #IMPLIED> 
+
+<!ELEMENT author      (organization,address?)>
+<!ATTLIST author
+          initials    %ATEXT;            #IMPLIED
+          surname     %ATEXT;            #IMPLIED
+          fullname    %ATEXT;            #IMPLIED
+          role        (editor)           #IMPLIED>
+
+<!ELEMENT organization
+                      (%CTEXT;)>
+<!ATTLIST organization
+          abbrev      %ATEXT;            #IMPLIED> 
+ 
+<!ELEMENT address     (postal?,phone?,facsimile?,email?,uri?)>
+
+<!-- this content model should be more strict:
+     at most one of each the city, region, code, and country
+     elements may be present -->
+<!ELEMENT postal      (street+,(city|region|code|country)*)>
+<!ELEMENT street      (%CTEXT;)>
+<!ELEMENT city        (%CTEXT;)>
+<!ELEMENT region      (%CTEXT;)>
+<!ELEMENT code        (%CTEXT;)>
+<!ELEMENT country     (%CTEXT;)>
+<!ELEMENT phone       (%CTEXT;)>
+<!ELEMENT facsimile   (%CTEXT;)>
+<!ELEMENT email       (%CTEXT;)>
+<!ELEMENT uri         (%CTEXT;)>
+
+<!ELEMENT date        EMPTY>
+<!ATTLIST date
+          day         %DAY;              #IMPLIED
+          month       %MONTH;            #IMPLIED
+          year        %YEAR;             #IMPLIED>
+
+<!-- meta-data... -->
+<!ELEMENT area        (%CTEXT;)>
+<!ELEMENT workgroup   (%CTEXT;)>
+<!ELEMENT keyword     (%CTEXT;)>
+
+<!ELEMENT abstract    (t)+>
+<!ELEMENT note        (t)+>
+<!ATTLIST note
+          title       %ATEXT;            #REQUIRED>
+
+
+<!--
+  The body
+  -->
+
+
+<!-- later on, may be (section+,appendix*,section*) -->
+<!ELEMENT middle      (section+)>
+
+<!ELEMENT section     ((t|figure|texttable|iref)*,section*)>
+<!ATTLIST section
+          anchor      ID                 #IMPLIED
+          title       %ATEXT;            #REQUIRED
+          toc         (include|exclude|default)
+                                         "default">
+
+<!--
+<!ELEMENT appendix    ((t|figure|texttable|iref)*,appendix*)>
+<!ATTLIST appendix
+          anchor      ID                 #IMPLIED
+          title       %ATEXT;            #REQUIRED
+          toc         (include|exclude|default)
+                                         "default">
+  -->
+
+<!-- use of <figure/> is deprecated... -->
+<!ELEMENT t           (%TEXT;|list|figure|xref|eref|iref|cref|spanx|vspace)*>
+<!ATTLIST t
+          anchor      ID                 #IMPLIED
+          hangText    %ATEXT;            #IMPLIED>
+
+<!-- the value of the style attribute is inherited from the closest 
+     parent -->
+<!ELEMENT list        (t+)>
+<!ATTLIST list
+          style       %ATEXT;            #IMPLIED
+          hangIndent  %NUMBER;           #IMPLIED
+          counter     %ATEXT;            #IMPLIED>
+
+<!ELEMENT xref        (%CTEXT;)>
+<!ATTLIST xref
+          target      IDREF              #REQUIRED
+          pageno      (true|false)       "false"
+          format      (counter|title|none|default)
+                                         "default">
+
+<!ELEMENT eref        (%CTEXT;)>
+<!ATTLIST eref
+          target      %URI;              #REQUIRED>
+
+<!ELEMENT iref        EMPTY>
+<!ATTLIST iref
+          item        %ATEXT;            #REQUIRED
+          subitem     %ATEXT;            ""
+          primary    (true|false)       "false">
+
+<!ELEMENT cref        (%CTEXT;)>
+<!ATTLIST cref
+          anchor      ID                 #IMPLIED
+          source      %ATEXT;            #IMPLIED>
+
+<!ELEMENT spanx       (%CTEXT;)>
+<!ATTLIST spanx
+          style       %ATEXT;            "emph">
+
+<!ELEMENT vspace      EMPTY>
+<!ATTLIST vspace
+          blankLines  %NUMBER;           "0">
+
+<!ELEMENT figure      (iref*,preamble?,artwork,postamble?)>
+<!ATTLIST figure
+          anchor      ID                 #IMPLIED
+          title       %ATEXT;            ""
+          src         %URI;              #IMPLIED
+          align       (left|center|right) "left"
+          alt         %ATEXT;            ""
+          width       %ATEXT;            ""
+          height      %ATEXT;            "">
+
+<!ELEMENT preamble    (%TEXT;|xref|eref|iref|cref|spanx)*>
+<!ELEMENT artwork     (%TEXT;)*>
+<!ATTLIST artwork
+          xml:space   (default|preserve) "preserve"
+          name        %ATEXT;            ""
+          type        %ATEXT;            ""
+          src         %URI;              #IMPLIED
+          align       (left|center|right) "left"
+          alt         %ATEXT;            ""
+          width       %ATEXT;            ""
+          height      %ATEXT;            "">
+
+<!ELEMENT postamble   (%TEXT;|xref|eref|iref|cref|spanx)*>
+    
+<!ELEMENT texttable   (preamble?,ttcol+,c*,postamble?)>
+<!ATTLIST texttable
+          anchor      ID                 #IMPLIED
+          title       %ATEXT;            "">
+<!ELEMENT ttcol       (%CTEXT;)>
+<!ATTLIST ttcol
+          width       %ATEXT;           #IMPLIED
+          align       (left|center|right) "left">
+<!ELEMENT c           (%TEXT;|xref|eref|iref|cref|spanx)*>
+
+
+<!--
+  Back matter
+  -->
+
+
+<!-- sections, if present, are appendices -->
+<!ELEMENT back        (references*,section*)>
+
+<!ELEMENT references  (reference+)>
+<!ATTLIST references
+          title       %ATEXT;            "References">
+<!ELEMENT reference   (front,seriesInfo*,format*,annotation*)>
+<!ATTLIST reference
+          anchor      ID                 #IMPLIED
+          target      %URI;              #IMPLIED>
+<!ELEMENT seriesInfo  EMPTY>
+<!ATTLIST seriesInfo
+          name        %ATEXT;            #REQUIRED
+          value       %ATEXT;            #REQUIRED>
+<!ELEMENT format      EMPTY>
+<!ATTLIST format
+          target      %URI;              #IMPLIED
+          type        %ATEXT;            #REQUIRED
+          octets      %NUMBER;           #IMPLIED>
+<!ELEMENT annotation  (%TEXT;|xref|eref|iref|cref|spanx)*>
Index: /branches/binary/server/doc/xml2rfc/reference.RFC.0768.xml
===================================================================
--- /branches/binary/server/doc/xml2rfc/reference.RFC.0768.xml (revision 776)
+++ /branches/binary/server/doc/xml2rfc/reference.RFC.0768.xml (revision 776)
@@ -0,0 +1,22 @@
+<?xml version='1.0' encoding='UTF-8'?>
+
+<reference anchor='RFC0768'>
+
+<front>
+<title>User Datagram Protocol</title>
+<author initials='J.' surname='Postel' fullname='J. Postel'>
+<organization>University of Southern California (USC)/Information Sciences Institute</organization>
+<address>
+<postal>
+<street>4676 Admiralty Way</street>
+<city>Marina del Rey</city>
+<region>CA</region>
+<code>90291</code>
+<country>US</country></postal>
+<phone>+1 213 822 1511</phone></address></author>
+<date year='1980' day='28' month='August' /></front>
+
+<seriesInfo name='STD' value='6' />
+<seriesInfo name='RFC' value='768' />
+<format type='TXT' octets='5896' target='ftp://ftp.isi.edu/in-notes/rfc768.txt' />
+</reference>
Index: /branches/binary/server/doc/xml2rfc/rfc2629-xhtml.ent
===================================================================
--- /branches/binary/server/doc/xml2rfc/rfc2629-xhtml.ent (revision 776)
+++ /branches/binary/server/doc/xml2rfc/rfc2629-xhtml.ent (revision 776)
@@ -0,0 +1,165 @@
+<!-- rfc2629-xhtml.ent
+
+     Character entity set for RFC-2629 source xml documents.
+     There is no need to invoke this directly from
+     the source document itself; just invoke the DTD.
+
+     These are known to (X)HTML, so any converter to these
+     formats can just leave them as is without having
+     to invoke this file from the output file.
+
+     Conversion to txt or nroff format will replace
+     these entities by the parenthesized text.
+
+     Typical invocation:
+       <!ENTITY % rfc2629-xhtml
+                PUBLIC "-//IETF//ENTITIES XHTML subset for RFC 2629//EN"
+                       "http://xml.resource.org/authoring/rfc2629-xhtml.ent">
+       %rfc2629-xhtml;
+-->
+
+<!-- All of ISO Latin 1 -->
+<!ENTITY nbsp    "&#160;"><!-- U+00A0 NO-BREAK SPACE                             (special " ")        -->
+<!ENTITY iexcl   "&#161;"><!-- U+00A1 INVERTED EXCLAMATION MARK                  ("!")                -->
+<!ENTITY cent    "&#162;"><!-- U+00A2 CENT SIGN                                  ("[cents]")          -->
+<!ENTITY pound   "&#163;"><!-- U+00A3 POUND SIGN                                 ("GBP")              -->
+<!ENTITY curren  "&#164;"><!-- U+00A4 CURRENCY SIGN                              ("[currency units]") -->
+<!ENTITY yen     "&#165;"><!-- U+00A5 YEN SIGN                                   ("JPY")              -->
+<!ENTITY brvbar  "&#166;"><!-- U+00A6 BROKEN BAR                                 ("|")                -->
+<!ENTITY sect    "&#167;"><!-- U+00A7 SECTION SIGN                               ("S.")               -->
+<!ENTITY uml     "&#168;"><!-- U+00A8 DIAERESIS                                  ('"')                -->
+<!ENTITY copy    "&#169;"><!-- U+00A9 COPYRIGHT SIGN                             ("(C)")              -->
+<!ENTITY ordf    "&#170;"><!-- U+00AA FEMININE ORDINAL INDICATOR                 ("a")                -->
+<!ENTITY laquo   "&#171;"><!-- U+00AB LEFT-POINTING DOUBLE ANGLE QUOTATION MARK  ("<<")               -->
+<!ENTITY not     "&#172;"><!-- U+00AC NOT SIGN                                   ("[not]")            -->
+<!ENTITY shy     "&#173;"><!-- U+00AD SOFT HYPHEN                                (ignored "")         -->
+<!ENTITY reg     "&#174;"><!-- U+00AE REGISTERED SIGN                            ("(R)")              -->
+<!ENTITY macr    "&#175;"><!-- U+00AF MACRON                                     ("_")                -->
+<!ENTITY deg     "&#176;"><!-- U+00B0 DEGREE SIGN                                ("o")                -->
+<!ENTITY plusmn  "&#177;"><!-- U+00B1 PLUS-MINUS SIGN                            ("+/-")              -->
+<!ENTITY sup2    "&#178;"><!-- U+00B2 SUPERSCRIPT TWO                            ("^2")               -->
+<!ENTITY sup3    "&#179;"><!-- U+00B3 SUPERSCRIPT THREE                          ("^3")               -->
+<!ENTITY acute   "&#180;"><!-- U+00B4 ACUTE ACCENT                               ("'")                -->
+<!ENTITY micro   "&#181;"><!-- U+00B5 MICRO SIGN                                 ("[micro]")          -->
+<!ENTITY para    "&#182;"><!-- U+00B6 PILCROW SIGN                               ("P.")               -->
+<!ENTITY middot  "&#183;"><!-- U+00B7 MIDDLE DOT                                 (".")                -->
+<!ENTITY cedil   "&#184;"><!-- U+00B8 CEDILLA                                    (",")                -->
+<!ENTITY sup1    "&#185;"><!-- U+00B9 SUPERSCRIPT ONE                            ("^1")               -->
+<!ENTITY ordm    "&#186;"><!-- U+00BA MASCULINE ORDINAL INDICATOR                ("o")                -->
+<!ENTITY raquo   "&#187;"><!-- U+00BB RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK (">>")               -->
+<!ENTITY frac14  "&#188;"><!-- U+00BC VULGAR FRACTION ONE QUARTER                ("1/4")              -->
+<!ENTITY frac12  "&#189;"><!-- U+00BD VULGAR FRACTION ONE HALF                   ("1/2")              -->
+<!ENTITY frac34  "&#190;"><!-- U+00BE VULGAR FRACTION THREE QUARTERS             ("3/4")              -->
+<!ENTITY iquest  "&#191;"><!-- U+00BF INVERTED QUESTION MARK                     ("?")                -->
+<!ENTITY Agrave  "&#192;"><!-- U+00C0 LATIN CAPITAL LETTER A WITH GRAVE          ("A")                -->
+<!ENTITY Aacute  "&#193;"><!-- U+00C1 LATIN CAPITAL LETTER A WITH ACUTE          ("A")                -->
+<!ENTITY Acirc   "&#194;"><!-- U+00C2 LATIN CAPITAL LETTER A WITH CIRCUMFLEX     ("A")                -->
+<!ENTITY Atilde  "&#195;"><!-- U+00C3 LATIN CAPITAL LETTER A WITH TILDE          ("A")                -->
+<!ENTITY Auml    "&#196;"><!-- U+00C4 LATIN CAPITAL LETTER A WITH DIAERESIS      ("Ae")               -->
+<!ENTITY Aring   "&#197;"><!-- U+00C5 LATIN CAPITAL LETTER A WITH RING ABOVE     ("Ae")               -->
+<!ENTITY AElig   "&#198;"><!-- U+00C6 LATIN CAPITAL LETTER AE                    ("AE")               -->
+<!ENTITY Ccedil  "&#199;"><!-- U+00C7 LATIN CAPITAL LETTER C WITH CEDILLA        ("C")                -->
+<!ENTITY Egrave  "&#200;"><!-- U+00C8 LATIN CAPITAL LETTER E WITH GRAVE          ("E")                -->
+<!ENTITY Eacute  "&#201;"><!-- U+00C9 LATIN CAPITAL LETTER E WITH ACUTE          ("E")                -->
+<!ENTITY Ecirc   "&#202;"><!-- U+00CA LATIN CAPITAL LETTER E WITH CIRCUMFLEX     ("E")                -->
+<!ENTITY Euml    "&#203;"><!-- U+00CB LATIN CAPITAL LETTER E WITH DIAERESIS      ("E")                -->
+<!ENTITY Igrave  "&#204;"><!-- U+00CC LATIN CAPITAL LETTER I WITH GRAVE          ("I")                -->
+<!ENTITY Iacute  "&#205;"><!-- U+00CD LATIN CAPITAL LETTER I WITH ACUTE          ("I")                -->
+<!ENTITY Icirc   "&#206;"><!-- U+00CE LATIN CAPITAL LETTER I WITH CIRCUMFLEX     ("I")                -->
+<!ENTITY Iuml    "&#207;"><!-- U+00CF LATIN CAPITAL LETTER I WITH DIAERESIS      ("I")                -->
+<!ENTITY ETH     "&#208;"><!-- U+00D0 LATIN CAPITAL LETTER ETH                   ("[ETH]")            -->
+<!ENTITY Ntilde  "&#209;"><!-- U+00D1 LATIN CAPITAL LETTER N WITH TILDE          ("N")                -->
+<!ENTITY Ograve  "&#210;"><!-- U+00D2 LATIN CAPITAL LETTER O WITH GRAVE          ("O")                -->
+<!ENTITY Oacute  "&#211;"><!-- U+00D3 LATIN CAPITAL LETTER O WITH ACUTE          ("O")                -->
+<!ENTITY Ocirc   "&#212;"><!-- U+00D4 LATIN CAPITAL LETTER O WITH CIRCUMFLEX     ("O")                -->
+<!ENTITY Otilde  "&#213;"><!-- U+00D5 LATIN CAPITAL LETTER O WITH TILDE          ("O")                -->
+<!ENTITY Ouml    "&#214;"><!-- U+00D6 LATIN CAPITAL LETTER O WITH DIAERESIS      ("Oe")               -->
+<!ENTITY times   "&#215;"><!-- U+00D7 MULTIPLICATION SIGN                        ("x")                -->
+<!ENTITY Oslash  "&#216;"><!-- U+00D8 LATIN CAPITAL LETTER O WITH STROKE         ("Oe")               -->
+<!ENTITY Ugrave  "&#217;"><!-- U+00D9 LATIN CAPITAL LETTER U WITH GRAVE          ("U")                -->
+<!ENTITY Uacute  "&#218;"><!-- U+00DA LATIN CAPITAL LETTER U WITH ACUTE          ("U")                -->
+<!ENTITY Ucirc   "&#219;"><!-- U+00DB LATIN CAPITAL LETTER U WITH CIRCUMFLEX     ("U")                -->
+<!ENTITY Uuml    "&#220;"><!-- U+00DC LATIN CAPITAL LETTER U WITH DIAERESIS      ("Ue")               -->
+<!ENTITY Yacute  "&#221;"><!-- U+00DD LATIN CAPITAL LETTER Y WITH ACUTE          ("Y")                -->
+<!ENTITY THORN   "&#222;"><!-- U+00DE LATIN CAPITAL LETTER THORN                 ("[THORN]")          -->
+<!ENTITY szlig   "&#223;"><!-- U+00DF LATIN SMALL LETTER SHARP S                 ("ss")               -->
+<!ENTITY agrave  "&#224;"><!-- U+00E0 LATIN SMALL LETTER A WITH GRAVE            ("a")                -->
+<!ENTITY aacute  "&#225;"><!-- U+00E1 LATIN SMALL LETTER A WITH ACUTE            ("a")                -->
+<!ENTITY acirc   "&#226;"><!-- U+00E2 LATIN SMALL LETTER A WITH CIRCUMFLEX       ("a")                -->
+<!ENTITY atilde  "&#227;"><!-- U+00E3 LATIN SMALL LETTER A WITH TILDE            ("a")                -->
+<!ENTITY auml    "&#228;"><!-- U+00E4 LATIN SMALL LETTER A WITH DIAERESIS        ("ae")               -->
+<!ENTITY aring   "&#229;"><!-- U+00E5 LATIN SMALL LETTER A WITH RING ABOVE       ("ae")               -->
+<!ENTITY aelig   "&#230;"><!-- U+00E6 LATIN SMALL LETTER AE                      ("ae")               -->
+<!ENTITY ccedil  "&#231;"><!-- U+00E7 LATIN SMALL LETTER C WITH CEDILLA          ("c")                -->
+<!ENTITY egrave  "&#232;"><!-- U+00E8 LATIN SMALL LETTER E WITH GRAVE            ("e")                -->
+<!ENTITY eacute  "&#233;"><!-- U+00E9 LATIN SMALL LETTER E WITH ACUTE            ("e")                -->
+<!ENTITY ecirc   "&#234;"><!-- U+00EA LATIN SMALL LETTER E WITH CIRCUMFLEX       ("e")                -->
+<!ENTITY euml    "&#235;"><!-- U+00EB LATIN SMALL LETTER E WITH DIAERESIS        ("e")                -->
+<!ENTITY igrave  "&#236;"><!-- U+00EC LATIN SMALL LETTER I WITH GRAVE            ("i")                -->
+<!ENTITY iacute  "&#237;"><!-- U+00ED LATIN SMALL LETTER I WITH ACUTE            ("i")                -->
+<!ENTITY icirc   "&#238;"><!-- U+00EE LATIN SMALL LETTER I WITH CIRCUMFLEX       ("i")                -->
+<!ENTITY iuml    "&#239;"><!-- U+00EF LATIN SMALL LETTER I WITH DIAERESIS        ("i")                -->
+<!ENTITY eth     "&#240;"><!-- U+00F0 LATIN SMALL LETTER ETH                     ("[eth]")            -->
+<!ENTITY ntilde  "&#241;"><!-- U+00F1 LATIN SMALL LETTER N WITH TILDE            ("n")                -->
+<!ENTITY ograve  "&#242;"><!-- U+00F2 LATIN SMALL LETTER O WITH GRAVE            ("o")                -->
+<!ENTITY oacute  "&#243;"><!-- U+00F3 LATIN SMALL LETTER O WITH ACUTE            ("o")                -->
+<!ENTITY ocirc   "&#244;"><!-- U+00F4 LATIN SMALL LETTER O WITH CIRCUMFLEX       ("o")                -->
+<!ENTITY otilde  "&#245;"><!-- U+00F5 LATIN SMALL LETTER O WITH TILDE            ("o")                -->
+<!ENTITY ouml    "&#246;"><!-- U+00F6 LATIN SMALL LETTER O WITH DIAERESIS        ("oe")               -->
+<!ENTITY divide  "&#247;"><!-- U+00F7 DIVISION SIGN                              ("/")                -->
+<!ENTITY oslash  "&#248;"><!-- U+00F8 LATIN SMALL LETTER O WITH STROKE           ("oe")               -->
+<!ENTITY ugrave  "&#249;"><!-- U+00F9 LATIN SMALL LETTER U WITH GRAVE            ("u")                -->
+<!ENTITY uacute  "&#250;"><!-- U+00FA LATIN SMALL LETTER U WITH ACUTE            ("u")                -->
+<!ENTITY ucirc   "&#251;"><!-- U+00FB LATIN SMALL LETTER U WITH CIRCUMFLEX       ("u")                -->
+<!ENTITY uuml    "&#252;"><!-- U+00FC LATIN SMALL LETTER U WITH DIAERESIS        ("ue")               -->
+<!ENTITY yacute  "&#253;"><!-- U+00FD LATIN SMALL LETTER Y WITH ACUTE            ("y")                -->
+<!ENTITY thorn   "&#254;"><!-- U+00FE LATIN SMALL LETTER THORN                   ("[thorn]")          -->
+<!ENTITY yuml    "&#255;"><!-- U+00FF LATIN SMALL LETTER Y WITH DIAERESIS        ("y")                -->
+
+<!-- Some of ISO Latin 9 and 10 -->
+<!ENTITY OElig   "&#338;"><!-- U+0152 LATIN CAPITAL LIGATURE OE                  ("OE")               -->
+<!ENTITY oelig   "&#339;"><!-- U+0153 LATIN SMALL LIGATURE OE                    ("oe")               -->
+<!ENTITY Scaron  "&#352;"><!-- U+0160 LATIN CAPITAL LETTER S WITH CARON          ("S")                -->
+<!ENTITY scaron  "&#353;"><!-- U+0161 LATIN SMALL LETTER S WITH CARON            ("s")                -->
+<!ENTITY Yuml    "&#376;"><!-- U+0178 LATIN CAPITAL LETTER Y WITH DIAERESIS      ("Y")                -->
+
+<!-- Other Unicode (including some characters from the windows-1252 repertoire) -->
+<!ENTITY fnof    "&#402;"><!-- U+0192 LATIN SMALL LETTER F WITH HOOK             ("f")                -->
+<!ENTITY tilde   "&#732;"><!-- U+02DC SMALL TILDE                                ("~")                -->
+<!ENTITY ensp   "&#8194;"><!-- U+2002 EN SPACE                                   (" ")                -->
+<!ENTITY emsp   "&#8195;"><!-- U+2003 EM SPACE                                   (" ")                -->
+<!ENTITY thinsp "&#8201;"><!-- U+2009 THIN SPACE                                 (" ")                -->
+<!ENTITY ndash  "&#8211;"><!-- U+2013 EN DASH                                    ("-")                -->
+<!ENTITY mdash  "&#8212;"><!-- U+2014 EM DASH                                    ("-\u002D")          -->
+<!ENTITY lsquo  "&#8216;"><!-- U+2018 LEFT SINGLE QUOTATION MARK                 ("'")                -->
+<!ENTITY rsquo  "&#8217;"><!-- U+2019 RIGHT SINGLE QUOTATION MARK                ("'")                -->
+<!ENTITY sbquo  "&#8218;"><!-- U+201A SINGLE LOW-9 QUOTATION MARK                ("'")                -->
+<!ENTITY ldquo  "&#8220;"><!-- U+201C LEFT DOUBLE QUOTATION MARK                 ('"')                -->
+<!ENTITY rdquo  "&#8221;"><!-- U+201D RIGHT DOUBLE QUOTATION MARK                ('"')                -->
+<!ENTITY bdquo  "&#8222;"><!-- U+201E DOUBLE LOW-9 QUOTATION MARK                ('"')                -->
+<!ENTITY dagger "&#8224;"><!-- U+2020 DAGGER                                     ("*!*")              -->
+<!ENTITY Dagger "&#8225;"><!-- U+2021 DOUBLE DAGGER                              ("*!!*")             -->
+<!ENTITY bull   "&#8226;"><!-- U+2022 BULLET                                     ("o")                -->
+<!ENTITY hellip "&#8230;"><!-- U+2026 HORIZONTAL ELLIPSIS                        ("...")              -->
+<!ENTITY permil "&#8242;"><!-- U+2030 PER MILLE SIGN                             ("[/1000]")          -->
+<!ENTITY prime  "&#8242;"><!-- U+2032 PRIME                                      ("'")                -->
+<!ENTITY Prime  "&#8243;"><!-- U+2033 DOUBLE PRIME                               ('"')                -->
+<!ENTITY lsaquo "&#8249;"><!-- U+2039 SINGLE LEFT-POINTING ANGLE QUOTATION MARK  ("<")                -->
+<!ENTITY rsaquo "&#8250;"><!-- U+203A SINGLE RIGHT-POINTING ANGLE QUOTATION MARK (">")                -->
+<!ENTITY frasl  "&#8260;"><!-- U+2044 FRACTION SLASH                             ("/")                -->
+<!ENTITY euro   "&#8364;"><!-- U+20AC EURO SIGN                                  ("EUR")              -->
+<!ENTITY trade  "&#8482;"><!-- U+2122 TRADE MARK SIGN                            ("[TM]")             -->
+<!ENTITY larr   "&#8592;"><!-- U+2190 LEFTWARDS ARROW                            ("<-\u002D")         -->
+<!ENTITY rarr   "&#8594;"><!-- U+2192 RIGHTWARDS ARROW                           ("\u002D->")         -->
+<!ENTITY harr   "&#8596;"><!-- U+2194 LEFT RIGHT ARROW                           ("<->")              -->
+<!ENTITY lArr   "&#8656;"><!-- U+21D0 LEFTWARDS DOUBLE ARROW                     ("<==")              -->
+<!ENTITY rArr   "&#8658;"><!-- U+21D2 RIGHTWARDS DOUBLE ARROW                    ("==>")              -->
+<!ENTITY hArr   "&#8660;"><!-- U+21D4 LEFT RIGHT DOUBLE ARROW                    ("<=>")              -->
+<!ENTITY minus  "&#8722;"><!-- U+2212 MINUS SIGN                                 ("-")                -->
+<!ENTITY lowast "&#8727;"><!-- U+2217 ASTERISK OPERATOR                          ("*")                -->
+<!ENTITY le     "&#8804;"><!-- U+2264 LESS-THAN OR EQUAL TO                      ("<=")               -->
+<!ENTITY ge     "&#8805;"><!-- U+2265 GREATER-THAN OR EQUAL TO                   (">=")               -->
+<!ENTITY lang   "&#9001;"><!-- U+2329 LEFT-POINTING ANGLE BRACKET                ("<")                -->
+<!ENTITY rang   "&#9002;"><!-- U+232A RIGHT-POINTING ANGLE BRACKET               (">")                -->
+
+<!-- EOF -->
Index: /anches/binary/server/doc/binary-protocol-plan-udp.txt
===================================================================
--- /branches/binary/server/doc/binary-protocol-plan-udp.txt (revision 687)
+++  (revision )
@@ -1,336 +1,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]
-
Index: /anches/binary/server/doc/binary-protocol-plan-v2.xml
===================================================================
--- /branches/binary/server/doc/binary-protocol-plan-v2.xml (revision 761)
+++  (revision )
@@ -1,668 +1,0 @@
-<?xml version="1.0" encoding="US-ASCII"?>
-<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
-<?xml-stylesheet type='text/xsl' href='rfc2629.xslt'?>
-<?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="none">
-
-  <front>
-
-    <title> Memcache Binary Protocol </title>
-
-    <author fullname="Aaron Stone" surname="Aaron 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>
-
-    <date day="14" month="December" year="2007" />
-
-    <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">
-      <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>
-      <t>
-      Memcache was originally written to make <xref target="LJ">LiveJournal</xref> go faster.
-      It now powers all of the fastest web sites that you love.
-      </t>
-      <section anchor="conventions" title="Conventions Used In This Document">
-        <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">
-      <t>
-      <figure>
-        <preamble>General format of a packet:</preamble>
-          <artwork>
-    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                                                        /
-      /                                                               /
-      /                                                               /
-      /                                                               /
-      +---------------+---------------+---------------+---------------+
-    16/ COMMAND-SPECIFIC EXTRAS (as needed)                           /
-     +/  (note length in th 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 16 bytes
-      </artwork></figure>
-      </t>
-
-      <t>
-      <figure>
-        <preamble>Request header:</preamble>
-          <artwork>
-    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| Message ID                                                    |
-      +---------------+---------------+---------------+---------------+
-    Total 16 bytes
-      </artwork></figure>
-      </t>
-
-      <t>
-      <figure>
-        <preamble>Response header:</preamble>
-          <artwork>
-    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        | Status                        |
-      +---------------+---------------+---------------+---------------+
-     4| Extras length | Data type     | Reserved                      |
-      +---------------+---------------+---------------+---------------+
-     8| Total body length                                             |
-      +---------------+---------------+---------------+---------------+
-    12| Message ID                                                    |
-      +---------------+---------------+---------------+---------------+
-    Total 16 bytes
-      </artwork></figure>
-      </t>
-
-      <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="Message ID">Will be copied back to you in the response.
-              FIXME: Can this be used to organize <xref target="UDP"/> packets?</t>
-        </list>
-      </t>
-    </section>
-
-    <section anchor="values" title="Defined Values">
-      <section anchor="value-magic" title="Magic Byte">
-        <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/reponse value pair. This is useful for protocol
-          analyzers to know what a packet is in isolation from which direction
-          it is moving. Note that 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">
-        <t>
-        Possible values of this two-byte field:
-        <list hangIndent="8" style="hanging">
-          <t hangText="0x0000">No error</t>
-          <t hangText="0x0081">Unknown command</t>
-          <t hangText="0x0001">Key not found</t>
-          <t hangText="0x0002">Key exists</t>
-        </list>
-        </t>
-      </section>
-
-      <section anchor="value-opcodes" title="Command Opcodes">
-        <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>
-        </list>
-        </t>
-      </section>
-
-      <section anchor="value-types" title="Data Types">
-        <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">
-      <section anchor="command-get" title="Get, Get Quietly">
-        <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>4 byte flags</t>
-          <t>8 byte data version check</t>
-        </list>
-        </t>
-
-        <t>
-      <figure>
-        <preamble>Extra data for get/getq:</preamble>
-          <artwork>
-    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| Data version check                                            |
-      |                                                               |
-      +---------------+---------------+---------------+---------------+
-     8| Flags                                                         |
-      +---------------+---------------+---------------+---------------+
-    Total 12 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.
-        </t>
-
-        <t>
-          You're not guaranteed a response to a getq cache hit until
-          you send a non-getq command later, which uncorks the
-          server which 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, the last being a regular
-          get.  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 gets, but then you could potentially
-          get back a lot of "NOT_FOUND!" error code packets.
-          alternatively, you can send 'n' getqs, followed by an 'echo'
-          or 'noop' command.
-        </t>
-
-      </section>
-
-      <section anchor="command-delete" title="Delete">
-        <t>
-        <list style="empty">
-          <t>MAY have extras (FIXME: Is it OK to issue a delete without extras?).</t>
-          <t>MUST have key.</t>
-          <t>MUST NOT have value.</t>
-        </list>
-        </t>
-
-        <t>
-          <list style="symbols">
-            <t>4 byte expiration time</t>
-          </list>
-        </t>
-
-        <t>
-      <figure>
-        <preamble>Extra data for delete:</preamble>
-          <artwork>
-    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>
-
-        <t>
-          When allows you to 'reserve' a key. When 'when' is set
-          for, say, ten seconds in the future, the 'add' and 'replace' operations will fail for that key 
-          until ten seconds from now.  The 'set' operation will succeed regardless of any reserved deletes.
-          FIXME: Is the reservation also cancelled? Say there's a delete with a 10 second hold. Two seconds
-          later, an 'add' is received. It fails. Two second later, a 'set' is received. Is succeeds unconditionally.
-          What if another 'add' is received two more seconds later (a total of six seconds since the original
-          10 second delete-hold, thus still within its purview).
-        </t>
-
-      </section>
-
-      <section anchor="command-set" title="Set, Add, Replace">
-        <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>
-            <t>8 byte data version check</t>
-          </list>
-        </t>
-
-        <t>
-        <figure>
-          <preamble>Extra data for set/add/replace:</preamble>
-            <artwork>
-    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| Data version check                                            |
-      |                                                               |
-      +---------------+---------------+---------------+---------------+
-     8| Flags                                                         |
-      +---------------+---------------+---------------+---------------+
-    12| Expiration                                                    |
-      +---------------+---------------+---------------+---------------+
-    Total 16 bytes
-        </artwork></figure>
-        </t>
-
-        <t>
-        If the Data Version Check is present and nonzero, the set MUST succeed if the
-        key exists and has a version identifier identical to the provided value, and
-	MUST NOT succeed if the key does not exist or has a different version identifier.
-	The set response packet will include the same values in all three fields.
-        </t>
-
-        <t>
-        If the Data Version Check is zero, the set MUST succeed unconditionally.
-	The set response packet will include idential values for flags and expiration,
-	and a new value for Data Version Check, which the client SHOULD keep track of.
-        </t>
-
-	<t>
-	The key MAY be reserved according to <xref target="command-delete"/>,
-	causing the set to fail.
-	</t>
-      </section>
-
-      <section title="noop">
-        <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's.
-        </t>
-      </section>
-
-      <section anchor="command-incr" title="Increment, Decrement">
-        <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 (FIXME: Is this unsigned?)</t>
-            <t>8 byte initial value (unsigned)</t>
-            <t>4 byte expiration time</t>
-          </list>
-        </t>
-
-        <t>
-      <figure>
-        <preamble>Extra data for incr/decr:</preamble>
-          <artwork>
-    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>
-
-        <t>
-      <figure>
-        <preamble>incr/decr response body:</preamble>
-          <artwork>
-    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>
-        </t>
-
-        <t>
-          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:
-          
-          <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.</t>
-          </list>
-        </t>
-          
-        <t>
-          Note that in the creation case, flags will be set to zero
-          (FIXME:  Should they be provided here as well?)
-        </t>
-      </section>
-    </section>
-
-    <section title="Example Session">
-      <t>
-      We start up our application, and it asks for the value associated with the 'Hello' key.
-      <figure>
-        <preamble>Get request:</preamble>
-          <artwork>
-    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          | 5 in big endian (BE)          |
-      +---------------+---------------+---------------+---------------+
-      | 12 in BE      | 0x00          |                               |
-      +---------------+---------------+---------------+---------------+
-      | 17 in BE                                                      |
-      +---------------+---------------+---------------+---------------+
-      | 0xDEADBEEF                                                    |
-      +---------------+---------------+---------------+---------------+
-    16| 0x00000000                                                    |
-      +---------------+---------------+---------------+---------------+
-    24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
-      |                                                               |
-      +---------------+---------------+---------------+---------------+
-    28| 'H'             'e'             'l'             'l'           |
-      | 'o'           |
-      +---------------+
-    Total 33 bytes (16 header + 12 get-extras + 5 key)
-      </artwork></figure>
-      </t>
-
-      <t>
-      Since nobody has set this key, it returns not found.
-      <figure>
-        <preamble>Get response:</preamble>
-          <artwork>
-    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          | 0x0001                        |
-      +---------------+---------------+---------------+---------------+
-      | 0 in BE       | 0x00          |                               |
-      +---------------+---------------+---------------+---------------+
-      | 0 in BE                                                       |
-      +---------------+---------------+---------------+---------------+
-      | 0xDEADBEEF                                                    |
-      +---------------+---------------+---------------+---------------+
-    Total 16 bytes
-      </artwork></figure>
-      </t>
-
-      <t>
-      Well, looks like we need to set the key! Let's set it to expire on
-      December 15, 2007 at 9:51:09 PM.
-      <figure>
-        <preamble>Set request:</preamble>
-          <artwork>
-    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          | 0x01          | 5 in BE                       |
-      +---------------+---------------+---------------+---------------+
-      | 16 in BE      | 0x00          |                               |
-      +---------------+---------------+---------------+---------------+
-      | 26 in BE                                                      |
-      +---------------+---------------+---------------+---------------+
-      | 0xDA7ABA5E                                                    |
-      +---------------+---------------+---------------+---------------+
-    16| 0x00000000                                                    |
-      +---------------+---------------+---------------+---------------+
-    20| 0xDCCB4674                                                    | 
-      +---------------+---------------+---------------+---------------+
-    24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
-      |                                                               |
-      +---------------+---------------+---------------+---------------+
-    32| 'H'             'e'             'l'             'l'           |
-      | 'o'           | 'W'             'o'             'r'           |
-      | 'l'             'd'           |
-      +---------------+---------------+
-    Total 42 bytes (16 header + 16 set-extras + 5 key + 5 value)
-      </artwork></figure>
-      </t>
-
-      <t>
-      The set succeeds.
-      <figure>
-        <preamble>Set response:</preamble>
-          <artwork>
-    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          | 0x01          | 0x0000                        |
-      +---------------+---------------+---------------+---------------+
-      | 16 in BE      | 0x00          |                               |
-      +---------------+---------------+---------------+---------------+
-      | 16 in BE                                                      |
-      +---------------+---------------+---------------+---------------+
-      | 0xDA7ABA5E                                                    |
-      +---------------+---------------+---------------+---------------+
-    16| 0x00000000                                                    |
-      +---------------+---------------+---------------+---------------+
-    20| 0xDCCB4674                                                    | 
-      +---------------+---------------+---------------+---------------+
-    24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
-      |                                                               |
-      +---------------+---------------+---------------+---------------+
-    Total 32 bytes (16 header + 16 set-extras)
-      </artwork></figure>
-      </t>
-
-      <t>
-      If the original get request is sent again, the key would be found.
-      <figure>
-        <preamble>Get response:</preamble>
-          <artwork>
-    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          |               |
-      +---------------+---------------+---------------+---------------+
-      | 12 in BE      | 0x00          |                               |
-      +---------------+---------------+---------------+---------------+
-      | 17 in BE                                                      |
-      +---------------+---------------+---------------+---------------+
-      | 0xDEADBEEF                                                    |
-      +---------------+---------------+---------------+---------------+
-    16| 0xDCCB4674                                                    | 
-      +---------------+---------------+---------------+---------------+
-    24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
-      |                                                               |
-      +---------------+---------------+---------------+---------------+
-    28| 'W'             'o'             'r'             'l'           |
-      | 'd'           |
-      +---------------+
-    Total 33 bytes (16 header + 12 get-extras + 5 value)
-      </artwork></figure>
-      </t>
-    </section>
-
-    <section anchor="security" title="Security Considerations">
-      <t>
-      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.
-      </t>
-    </section>
-
-  </middle>
-
-  <back>
-    <references title="Normative References">
-      <reference anchor="LJ">
-        <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>
-      <dwdrfc-ref anchor='UDP' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.0768.xml'/>
-      <dwdrfc-ref anchor='KEYWORDS' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/>
-    </references>
-
-    <section anchor="acknowledgments" title="Acknowledgments">
-      <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>
-
Index: /anches/binary/server/doc/binary-protocol-plan-udp.xml
===================================================================
--- /branches/binary/server/doc/binary-protocol-plan-udp.xml (revision 687)
+++  (revision )
@@ -1,226 +1,0 @@
-<?xml version="1.0" encoding="US-ASCII"?>
-<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
-<?xml-stylesheet type='text/xsl' href='rfc2629.xslt'?>
-<?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-udp-01" ipr="none">
-
-  <front>
-
-    <title abbrev="Memcache Over UDP"> Memcache Binary Protocol: Extensions for UDP </title>
-
-    <author fullname="Aaron Stone" surname="Aaron 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>
-
-    <date day="14" month="December" year="2007" />
-
-    <area>Applications</area>
-
-    <keyword>memcache memcached cache udp</keyword>
-
-    <abstract>
-      <t>
-      This memo explains extensions to the memcache binary protocol for use in a UDP environment.
-      </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">
-      <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>
-      <t>
-      Sites may find that, due to their network architecture or application usage patterns,
-      the stateless <xref target="UDP"/> protocol better suits their needs. This document
-      provides extensions and descriptions of use of the <xref target="MEMCACHE">memcache protocol</xref>
-      in a UDP environment.
-      </t>
-      <t>
-      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.
-      </t>
-      <section anchor="conventions" title="Conventions Used In This Document">
-        <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="values" title="Defined Values">
-      <section anchor="value-magic" title="Magic Byte">
-        <t>
-        The magic bytes remains the same as in <xref target="MEMCACHE"/>.
-        </t>
-      </section>
-
-      <section anchor="value-status" title="Response Status">
-        <t>
-        Additional status values:
-        <list hangIndent="8" style="hanging">
-          <t hangText="0x0004">Value is larger than a single response packet</t>
-        </list>
-        </t>
-      </section>
-
-      <section anchor="value-opcodes" title="Command Opcodes">
-        <t>
-        Additional opcode values:
-        <list hangIndent="8" style="hanging">
-          <t hangText="0x0C">Get Range</t>
-          <t hangText="0x0D">Set Range</t>
-        </list>
-        </t>
-      </section>
-
-      <section anchor="value-types" title="Data Types">
-        <t>
-        There are no new data types in this extension.
-        </t>
-      </section>
-    </section>
-
-    <section anchor="commands" title="Commands">
-
-      <section anchor="command-get" title="Get Response">
-        <t>
-        This section extends the behavior of the Get and GetQ commands as described in 
-        <xref target="MEMCACHE" x:sec="command-get"/>.
-        </t>
-
-        <t>
-        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:
-        <list style="numbers">
-          <t>The Status field of the response header MUST be 0x0004.</t>
-          <t>The Offset field of the GetR response extras MUST be 0.</t>
-          <t>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.</t>
-          <t>The Total value length field of the response extras MUST be the
-             actual length of the complete value.</t>
-        </list>
-        </t>
-
-        <t>
-        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.
-        </t>
-      </section>
-
-      <section anchor="command-getr-request" title="Get Range Request">
-        <t>
-	  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.
-	</t>
-        <t>
-      <figure>
-        <preamble>Extra data for get range request:</preamble>
-          <artwork>
-    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
-      </artwork></figure>
-        </t>
-      </section>
-
-      <section anchor="command-getr-response" title="Get Range Response">
-        <t>
-	  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.
-	</t>
-        <t>
-      <figure>
-        <preamble>Extra data for get range response:</preamble>
-          <artwork>
-    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
-      </artwork></figure>
-        </t>
-      </section>
-
-    </section>
-
-    <section anchor="security" title="Security Considerations">
-      <t>
-      This document does not introduce any new security considerations
-      beyond those discussed in <xref target="MEMCACHE" x:sec="security"/>.
-      </t>
-    </section>
-
-  </middle>
-
-  <back>
-    <references title="Normative References">
-      <dwdrfc-ref anchor='UDP' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.0768.xml'/>
-      <dwdrfc-ref anchor='KEYWORDS' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/>
-      <!-- FIXME: Get a draft reference for the base document. -->
-      <dwdrfc-ref anchor='MEMCACHE' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/>
-    </references>
-  </back>
-
-</rfc>
-
Index: /anches/binary/server/doc/binary-protocol-plan.txt
===================================================================
--- /branches/binary/server/doc/binary-protocol-plan.txt (revision 599)
+++  (revision )
@@ -1,66 +1,0 @@
-Notes regarding the proposed binary protocol from Facebook's hosted
-memcached hackathon on 2007-07-09:
-
-REQUEST STRUCTURE:
-
-  * Magic byte / version
-  * Cmd byte
-  * Key len byte  (if no key, 0)
-  * Reserved byte (should be 0)
-
-  * 4 byte opaque id.  (will be copied back in response; means nothing to server)
-
-  * 4 byte body length (network order; not including 12 byte header)
-
-  [ cmd-specific fixed-width fields ]
-
-  * key, if key length above is non-zero.
-
-  [ cmd-specific variable-width field ]
-
-
-RESPONSE STRUCTURE:
-
-  * Magic byte / version (different from req's magic byte/version, to distinguish
-    that it's a response for, say, protocol analyzers)
-  * cmd byte (same as response it goes to)
-  * err code byte (0 on success, else errcode.  hit bit set if fatal/non-normal error)
-  * Reserved byte (should be 0)
-
-  * 4 byte opaque id copied back from response
-
-  * 4 byte body length (network order; not including 12 byte header)
-
-  [cmd-specific body]
-
-
-COMMANDS:  (for cmd byte)
-
-  get    - single key get (no more multi-get; clients should pipeline)
-  getq   - like get, but quiet.  that is, no cache miss, return nothing.
-
-      Note: you're not guaranteed a response to a getq cache hit until
-            you send a non-getq command later, which uncorks the
-            server which bundles up IOs to send to the client in one go.
-
-      Note: clients should implement multi-get (still important for
-            reducing network roundtrips!) as n pipelined requests, the
-            first n-1 being getq, the last being a regular
-            get.  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 gets, but then you could potentially
-            get back a lot of "NOT_FOUND!" error code packets.
-            alternatively, you can send 'n' getqs, followed by an 'echo'
-            or 'noop' command.
-
-  delete
-  set/add/replace
-
-       cmd-specific fixed-width fields for set/add/replace:
-
-           * 4 byte expiration time
-           * 4 byte flags
-           (the 4 byte length is inferred from the total body length,
-            subtracting (keylen + body length))
-
-
Index: /anches/binary/server/doc/binary-protocol-plan-v2.txt
===================================================================
--- /branches/binary/server/doc/binary-protocol-plan-v2.txt (revision 760)
+++  (revision )
@@ -1,728 +1,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
-                     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 June 16, 2008.
-
-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.
-
-
-
-
-
-
-
-
-Aaron Stone               Expires June 16, 2008                 [Page 1]
-
-Internet-Draft          Memcache Binary Protocol           December 2007
-
-
-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  . . . . . . . . . . . . . . . . . . . . .  5
-     3.4.  Data Types . . . . . . . . . . . . . . . . . . . . . . . .  6
-   4.  Commands . . . . . . . . . . . . . . . . . . . . . . . . . . .  6
-     4.1.  Get, Get Quietly . . . . . . . . . . . . . . . . . . . . .  6
-     4.2.  Delete . . . . . . . . . . . . . . . . . . . . . . . . . .  7
-     4.3.  Set, Add, Replace  . . . . . . . . . . . . . . . . . . . .  7
-     4.4.  noop . . . . . . . . . . . . . . . . . . . . . . . . . . .  8
-     4.5.  Increment, Decrement . . . . . . . . . . . . . . . . . . .  8
-   5.  Example Session  . . . . . . . . . . . . . . . . . . . . . . .  9
-   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 13
-   7.  Normative References . . . . . . . . . . . . . . . . . . . . . 13
-   Appendix A.  Acknowledgments . . . . . . . . . . . . . . . . . . . 13
-   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Aaron Stone               Expires June 16, 2008                 [Page 2]
-
-Internet-Draft          Memcache Binary Protocol           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.
-
-   Memcache was originally written to make LiveJournal [LJ] go 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                                                        /
-       /                                                               /
-       /                                                               /
-       /                                                               /
-       +---------------+---------------+---------------+---------------+
-     16/ COMMAND-SPECIFIC EXTRAS (as needed)                           /
-      +/  (note length in th 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 16 bytes
-
-
-
-
-
-
-
-
-
-Aaron Stone               Expires June 16, 2008                 [Page 3]
-
-Internet-Draft          Memcache Binary Protocol           December 2007
-
-
-   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| Message ID                                                    |
-       +---------------+---------------+---------------+---------------+
-     Total 16 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        | Status                        |
-       +---------------+---------------+---------------+---------------+
-      4| Extras length | Data type     | Reserved                      |
-       +---------------+---------------+---------------+---------------+
-      8| Total body length                                             |
-       +---------------+---------------+---------------+---------------+
-     12| Message ID                                                    |
-       +---------------+---------------+---------------+---------------+
-     Total 16 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).
-   Reserved            Really reserved for future use (up for grabs).
-   Total body length   Length in bytes of extra + key + value.
-   Message ID          Will be copied back to you in the response.
-                       FIXME: Can this be used to organize [UDP]
-                       packets?
-
-
-
-
-
-Aaron Stone               Expires June 16, 2008                 [Page 4]
-
-Internet-Draft          Memcache Binary Protocol           December 2007
-
-
-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/reponse value pair.  This is useful for protocol
-   analyzers to know what a packet is in isolation from which direction
-   it is moving.  Note that 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
-   0x0081  Unknown command
-   0x0001  Key not found
-   0x0002  Key exists
-
-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
-
-
-
-
-
-
-
-Aaron Stone               Expires June 16, 2008                 [Page 5]
-
-Internet-Draft          Memcache Binary Protocol           December 2007
-
-
-   0x08    Flush
-   0x09    GetQ
-   0x0A    No-op
-   0x0B    Version
-
-3.4.  Data Types
-
-   Possible values of the one-byte field:
-   0x00    Raw bytes
-
-
-4.  Commands
-
-4.1.  Get, Get Quietly
-
-      MUST have extras.
-      MUST have key.
-      MUST NOT have value.
-
-   o  4 byte flags
-   o  8 byte data version check
-
-   Extra data for get/getq:
-
-     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| Data version check                                            |
-       |                                                               |
-       +---------------+---------------+---------------+---------------+
-      8| Flags                                                         |
-       +---------------+---------------+---------------+---------------+
-     Total 12 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.
-
-   You're not guaranteed a response to a getq cache hit until you send a
-   non-getq command later, which uncorks the server which 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, the last being a regular get. 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 gets, but then you could potentially
-
-
-
-Aaron Stone               Expires June 16, 2008                 [Page 6]
-
-Internet-Draft          Memcache Binary Protocol           December 2007
-
-
-   get back a lot of "NOT_FOUND!" error code packets. alternatively, you
-   can send 'n' getqs, followed by an 'echo' or 'noop' command.
-
-4.2.  Delete
-
-      MAY have extras (FIXME: Is it OK to issue a delete without
-      extras?).
-      MUST have key.
-      MUST NOT have value.
-
-   o  4 byte expiration time
-
-   Extra data for delete:
-
-     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
-
-   When allows you to 'reserve' a key.  When 'when' is set for, say, ten
-   seconds in the future, the 'add' and 'replace' operations will fail
-   for that key until ten seconds from now.  The 'set' operation will
-   succeed regardless of any reserved deletes.  FIXME: Is the
-   reservation also cancelled?  Say there's a delete with a 10 second
-   hold.  Two seconds later, an 'add' is received.  It fails.  Two
-   second later, a 'set' is received.  Is succeeds unconditionally.
-   What if another 'add' is received two more seconds later (a total of
-   six seconds since the original 10 second delete-hold, thus still
-   within its purview).
-
-4.3.  Set, Add, Replace
-
-      MUST have extras.
-      MUST have key.
-      MUST have value.
-
-   o  4 byte flags
-   o  4 byte expiration time
-   o  8 byte data version check
-
-
-
-
-
-
-
-
-
-Aaron Stone               Expires June 16, 2008                 [Page 7]
-
-Internet-Draft          Memcache Binary Protocol           December 2007
-
-
-   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| Data version check                                            |
-       |                                                               |
-       +---------------+---------------+---------------+---------------+
-      8| Flags                                                         |
-       +---------------+---------------+---------------+---------------+
-     12| Expiration                                                    |
-       +---------------+---------------+---------------+---------------+
-     Total 16 bytes
-
-   If the Data Version Check is present and nonzero, the set MUST
-   succeed if the key exists and has a version identifier identical to
-   the provided value, and MUST NOT succeed if the key does not exist or
-   has a different version identifier.  The set response packet will
-   include the same values in all three fields.
-
-   If the Data Version Check is zero, the set MUST succeed
-   unconditionally.  The set response packet will include idential
-   values for flags and expiration, and a new value for Data Version
-   Check, which the client SHOULD keep track of.
-
-   The key MAY be reserved according to Section 4.2, causing the set to
-   fail.
-
-4.4.  noop
-
-      MUST NOT have extras.
-      MUST NOT have key.
-      MUST NOT have value.
-
-   Used as a keep alive.  Flushes outstanding getq's.
-
-4.5.  Increment, Decrement
-
-      MUST have extras.
-      MUST have key.
-      MUST NOT have value.
-
-   o  8 byte value to add / subtract (FIXME: Is this unsigned?)
-   o  8 byte initial value (unsigned)
-   o  4 byte expiration time
-
-
-
-
-
-Aaron Stone               Expires June 16, 2008                 [Page 8]
-
-Internet-Draft          Memcache Binary Protocol           December 2007
-
-
-   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
-
-   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
-
-   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.
-
-   Note that in the creation case, flags will be set to zero (FIXME:
-   Should they be provided here as well?)
-
-
-5.  Example Session
-
-   We start up our application, and it asks for the value associated
-   with the 'Hello' key.
-
-
-
-
-
-
-
-Aaron Stone               Expires June 16, 2008                 [Page 9]
-
-Internet-Draft          Memcache Binary Protocol           December 2007
-
-
-   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          | 5 in big endian (BE)          |
-       +---------------+---------------+---------------+---------------+
-       | 12 in BE      | 0x00          |                               |
-       +---------------+---------------+---------------+---------------+
-       | 17 in BE                                                      |
-       +---------------+---------------+---------------+---------------+
-       | 0xDEADBEEF                                                    |
-       +---------------+---------------+---------------+---------------+
-     16| 0x00000000                                                    |
-       +---------------+---------------+---------------+---------------+
-     24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
-       |                                                               |
-       +---------------+---------------+---------------+---------------+
-     28| 'H'             'e'             'l'             'l'           |
-       | 'o'           |
-       +---------------+
-     Total 33 bytes (16 header + 12 get-extras + 5 key)
-
-   Since nobody has set this key, it returns not found.
-
-   Get 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          | 0x0001                        |
-       +---------------+---------------+---------------+---------------+
-       | 0 in BE       | 0x00          |                               |
-       +---------------+---------------+---------------+---------------+
-       | 0 in BE                                                       |
-       +---------------+---------------+---------------+---------------+
-       | 0xDEADBEEF                                                    |
-       +---------------+---------------+---------------+---------------+
-     Total 16 bytes
-
-   Well, looks like we need to set the key!  Let's set it to expire on
-   December 15, 2007 at 9:51:09 PM.
-
-
-
-
-
-
-
-Aaron Stone               Expires June 16, 2008                [Page 10]
-
-Internet-Draft          Memcache Binary Protocol           December 2007
-
-
-   Set 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          | 0x01          | 5 in BE                       |
-       +---------------+---------------+---------------+---------------+
-       | 16 in BE      | 0x00          |                               |
-       +---------------+---------------+---------------+---------------+
-       | 26 in BE                                                      |
-       +---------------+---------------+---------------+---------------+
-       | 0xDA7ABA5E                                                    |
-       +---------------+---------------+---------------+---------------+
-     16| 0x00000000                                                    |
-       +---------------+---------------+---------------+---------------+
-     20| 0xDCCB4674                                                    |
-       +---------------+---------------+---------------+---------------+
-     24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
-       |                                                               |
-       +---------------+---------------+---------------+---------------+
-     32| 'H'             'e'             'l'             'l'           |
-       | 'o'           | 'W'             'o'             'r'           |
-       | 'l'             'd'           |
-       +---------------+---------------+
-     Total 42 bytes (16 header + 16 set-extras + 5 key + 5 value)
-
-   The set succeeds.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Aaron Stone               Expires June 16, 2008                [Page 11]
-
-Internet-Draft          Memcache Binary Protocol           December 2007
-
-
-   Set 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          | 0x01          | 0x0000                        |
-       +---------------+---------------+---------------+---------------+
-       | 16 in BE      | 0x00          |                               |
-       +---------------+---------------+---------------+---------------+
-       | 16 in BE                                                      |
-       +---------------+---------------+---------------+---------------+
-       | 0xDA7ABA5E                                                    |
-       +---------------+---------------+---------------+---------------+
-     16| 0x00000000                                                    |
-       +---------------+---------------+---------------+---------------+
-     20| 0xDCCB4674                                                    |
-       +---------------+---------------+---------------+---------------+
-     24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
-       |                                                               |
-       +---------------+---------------+---------------+---------------+
-     Total 32 bytes (16 header + 16 set-extras)
-
-   If the original get request is sent again, the key would be found.
-
-   Get 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          |               |
-       +---------------+---------------+---------------+---------------+
-       | 12 in BE      | 0x00          |                               |
-       +---------------+---------------+---------------+---------------+
-       | 17 in BE                                                      |
-       +---------------+---------------+---------------+---------------+
-       | 0xDEADBEEF                                                    |
-       +---------------+---------------+---------------+---------------+
-     16| 0xDCCB4674                                                    |
-       +---------------+---------------+---------------+---------------+
-     24| 0xDECAF 0x15 0xBAD 0xC0FFEE                                   |
-       |                                                               |
-       +---------------+---------------+---------------+---------------+
-     28| 'W'             'o'             'r'             'l'           |
-       | 'd'           |
-       +---------------+
-     Total 33 bytes (16 header + 12 get-extras + 5 value)
-
-
-
-Aaron Stone               Expires June 16, 2008                [Page 12]
-
-Internet-Draft          Memcache Binary Protocol           December 2007
-
-
-6.  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.
-
-
-7.  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.
-
-   [UDP]      Postel, J., "User Datagram Protocol", STD 6, RFC 768,
-              August 1980.
-
-
-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.
-
-
-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 13]
-