"Fossies" - the Fresh Open Source Software Archive

Member "memcached-1.6.15/doc/protocol-binary.txt" (30 Mar 2022, 62542 Bytes) of package /linux/www/memcached-1.6.15.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 
    2 
    3 
    4 
    5 Network Working Group                                         Stone, Ed.
    6 Internet-Draft                                           Six Apart, Ltd.
    7 Intended status: Informational                               Norbye, Ed.
    8 Expires: March 1, 2009                             Sun Microsystems, INC
    9                                                          August 28, 2008
   10 
   11 
   12                         Memcache Binary Protocol
   13                      draft-stone-memcache-binary-01
   14 
   15 Abstract
   16 
   17    This memo explains the memcache binary protocol for informational
   18    purposes.
   19 
   20    Memcache is a high performance key-value cache.  It is intentionally
   21    a dumb cache, optimized for speed only.  Applications using memcache
   22    do not rely on it for data -- a persistent database with guaranteed
   23    reliability is strongly recommended -- but applications can run much
   24    faster when cached data is available in memcache.
   25 
   26 Status of This Memo
   27 
   28    This Internet-Draft is submitted in full conformance with the
   29    provisions of BCP 78 and BCP 79.
   30 
   31    Internet-Drafts are working documents of the Internet Engineering
   32    Task Force (IETF).  Note that other groups may also distribute
   33    working documents as Internet-Drafts.  The list of current Internet-
   34    Drafts is at http://datatracker.ietf.org/drafts/current/.
   35 
   36    Internet-Drafts are draft documents valid for a maximum of six months
   37    and may be updated, replaced, or obsoleted by other documents at any
   38    time.  It is inappropriate to use Internet-Drafts as reference
   39    material or to cite them other than as "work in progress."
   40 
   41    This Internet-Draft will expire on March 1, 2009.
   42 
   43 Copyright Notice
   44 
   45    Copyright (c) 2008 IETF Trust and the persons identified as the
   46    document authors.  All rights reserved.
   47 
   48    This document is subject to BCP 78 and the IETF Trust's Legal
   49    Provisions Relating to IETF Documents
   50    (http://trustee.ietf.org/license-info) in effect on the date of
   51    publication of this document.  Please review these documents
   52    carefully, as they describe your rights and restrictions with respect
   53 
   54 
   55 
   56 Stone & Norbye            Expires March 1, 2009                 [Page 1]
   57 
   58 Internet-Draft          Memcache Binary Protocol             August 2008
   59 
   60 
   61    to this document.  Code Components extracted from this document must
   62    include Simplified BSD License text as described in Section 4.e of
   63    the Trust Legal Provisions and are provided without warranty as
   64    described in the Simplified BSD License.
   65 
   66 Table of Contents
   67 
   68    1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   69      1.1.  Conventions Used In This Document . . . . . . . . . . . .   3
   70    2.  Packet Structure  . . . . . . . . . . . . . . . . . . . . . .   3
   71    3.  Defined Values  . . . . . . . . . . . . . . . . . . . . . . .   5
   72      3.1.  Magic Byte  . . . . . . . . . . . . . . . . . . . . . . .   5
   73      3.2.  Response Status . . . . . . . . . . . . . . . . . . . . .   5
   74      3.3.  Command Opcodes . . . . . . . . . . . . . . . . . . . . .   6
   75      3.4.  Data Types  . . . . . . . . . . . . . . . . . . . . . . .   6
   76    4.  Commands  . . . . . . . . . . . . . . . . . . . . . . . . . .   7
   77      4.1.  Introduction  . . . . . . . . . . . . . . . . . . . . . .   7
   78        4.1.1.  Example . . . . . . . . . . . . . . . . . . . . . . .   7
   79      4.2.  Get, Get Quietly, Get Key, Get Key Quietly  . . . . . . .   8
   80        4.2.1.  Example . . . . . . . . . . . . . . . . . . . . . . .   9
   81      4.3.  Set, Add, Replace . . . . . . . . . . . . . . . . . . . .  13
   82        4.3.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  13
   83      4.4.  Delete  . . . . . . . . . . . . . . . . . . . . . . . . .  15
   84        4.4.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  16
   85      4.5.  Increment, Decrement  . . . . . . . . . . . . . . . . . .  17
   86        4.5.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  18
   87      4.6.  quit  . . . . . . . . . . . . . . . . . . . . . . . . . .  20
   88        4.6.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  21
   89      4.7.  Flush . . . . . . . . . . . . . . . . . . . . . . . . . .  21
   90        4.7.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  22
   91      4.8.  noop  . . . . . . . . . . . . . . . . . . . . . . . . . .  23
   92        4.8.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  24
   93      4.9.  version . . . . . . . . . . . . . . . . . . . . . . . . .  24
   94        4.9.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  25
   95      4.10. Append, Prepend . . . . . . . . . . . . . . . . . . . . .  26
   96        4.10.1.  Example  . . . . . . . . . . . . . . . . . . . . . .  27
   97      4.11. Stat  . . . . . . . . . . . . . . . . . . . . . . . . . .  28
   98        4.11.1.  Example  . . . . . . . . . . . . . . . . . . . . . .  28
   99    5.  Security Considerations . . . . . . . . . . . . . . . . . . .  30
  100    6.  Normative References  . . . . . . . . . . . . . . . . . . . .  31
  101    Appendix A.  Acknowledgments  . . . . . . . . . . . . . . . . . .  31
  102    Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  31
  103 
  104 1.  Introduction
  105 
  106    Memcache is a high performance key-value cache.  It is intentionally
  107    a dumb cache, optimized for speed only.  Applications using memcache
  108    should not rely on it for data -- a persistent database with
  109 
  110 
  111 
  112 Stone & Norbye            Expires March 1, 2009                 [Page 2]
  113 
  114 Internet-Draft          Memcache Binary Protocol             August 2008
  115 
  116 
  117    guaranteed reliability is strongly recommended -- but applications
  118    can run much faster when cached data is available in memcache.
  119 
  120    Memcache was originally written to make LiveJournal [LJ] faster.  It
  121    now powers all of the fastest web sites that you love.
  122 
  123 1.1.  Conventions Used In This Document
  124 
  125    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  126    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  127    document are to be interpreted as described in [KEYWORDS].
  128 
  129 2.  Packet Structure
  130 
  131    General format of a packet:
  132 
  133      Byte/     0       |       1       |       2       |       3       |
  134         /              |               |               |               |
  135        |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  136        +---------------+---------------+---------------+---------------+
  137       0/ HEADER                                                        /
  138        /                                                               /
  139        /                                                               /
  140        /                                                               /
  141        +---------------+---------------+---------------+---------------+
  142      24/ COMMAND-SPECIFIC EXTRAS (as needed)                           /
  143       +/  (note length in the extras length header field)              /
  144        +---------------+---------------+---------------+---------------+
  145       m/ Key (as needed)                                               /
  146       +/  (note length in key length header field)                     /
  147        +---------------+---------------+---------------+---------------+
  148       n/ Value (as needed)                                             /
  149       +/  (note length is total body length header field, minus        /
  150       +/   sum of the extras and key length body fields)               /
  151        +---------------+---------------+---------------+---------------+
  152        Total 24 bytes
  153 
  154 
  155 
  156 
  157 
  158 
  159 
  160 
  161 
  162 
  163 
  164 
  165 
  166 
  167 
  168 Stone & Norbye            Expires March 1, 2009                 [Page 3]
  169 
  170 Internet-Draft          Memcache Binary Protocol             August 2008
  171 
  172 
  173    Request header:
  174 
  175      Byte/     0       |       1       |       2       |       3       |
  176         /              |               |               |               |
  177        |0 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|
  178        +---------------+---------------+---------------+---------------+
  179       0| Magic         | Opcode        | Key length                    |
  180        +---------------+---------------+---------------+---------------+
  181       4| Extras length | Data type     | Reserved                      |
  182        +---------------+---------------+---------------+---------------+
  183       8| Total body length                                             |
  184        +---------------+---------------+---------------+---------------+
  185      12| Opaque                                                        |
  186        +---------------+---------------+---------------+---------------+
  187      16| CAS                                                           |
  188        |                                                               |
  189        +---------------+---------------+---------------+---------------+
  190        Total 24 bytes
  191 
  192    Response header:
  193 
  194      Byte/     0       |       1       |       2       |       3       |
  195         /              |               |               |               |
  196        |0 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|
  197        +---------------+---------------+---------------+---------------+
  198       0| Magic         | Opcode        | Key Length                    |
  199        +---------------+---------------+---------------+---------------+
  200       4| Extras length | Data type     | Status                        |
  201        +---------------+---------------+---------------+---------------+
  202       8| Total body length                                             |
  203        +---------------+---------------+---------------+---------------+
  204      12| Opaque                                                        |
  205        +---------------+---------------+---------------+---------------+
  206      16| CAS                                                           |
  207        |                                                               |
  208        +---------------+---------------+---------------+---------------+
  209        Total 24 bytes
  210 
  211    Header fields:
  212 
  213    Magic               Magic number.
  214    Opcode              Command code.
  215    Key length          Length in bytes of the text key that follows the
  216                        command extras.
  217    Status              Status of the response (non-zero on error).
  218    Extras length       Length in bytes of the command extras.
  219    Data type           Reserved for future use (Sean is using this
  220                        soon).
  221 
  222 
  223 
  224 Stone & Norbye            Expires March 1, 2009                 [Page 4]
  225 
  226 Internet-Draft          Memcache Binary Protocol             August 2008
  227 
  228 
  229    Reserved            Really reserved for future use (up for grabs).
  230    Total body length   Length in bytes of extra + key + value.
  231    Opaque              Will be copied back to you in the response.
  232    CAS                 Data version check.
  233 
  234 3.  Defined Values
  235 
  236 3.1.  Magic Byte
  237 
  238    0x80    Request packet for this protocol version
  239    0x81    Response packet for this protocol version
  240 
  241    Magic byte / version.  For each version of the protocol, we'll use a
  242    different request/response value pair.  This is useful for protocol
  243    analyzers to distinguish the nature of the packet from the direction
  244    which it is moving.  Note, it is common to run a memcached instance
  245    on a host that also runs an application server.  Such a host will
  246    both send and receive memcache packets.
  247 
  248    The version should hopefully correspond only to different meanings of
  249    the command byte.  In an ideal world, we will not change the header
  250    format.  As reserved bytes are given defined meaning, the protocol
  251    version / magic byte values should be incremented.
  252 
  253    Traffic analysis tools are encouraged to identify memcache packets
  254    and provide detailed interpretation if the magic bytes are recognized
  255    and otherwise to provide a generic breakdown of the packet.  Note,
  256    that the key and value positions can always be identified even if the
  257    magic byte or command opcode are not recognized.
  258 
  259 3.2.  Response Status
  260 
  261    Possible values of this two-byte field:
  262 
  263    0x0000  No error
  264    0x0001  Key not found
  265    0x0002  Key exists
  266    0x0003  Value too large
  267    0x0004  Invalid arguments
  268    0x0005  Item not stored
  269    0x0006  Incr/Decr on non-numeric value.
  270    0x0081  Unknown command
  271    0x0082  Out of memory
  272 
  273 
  274 
  275 
  276 
  277 
  278 
  279 
  280 Stone & Norbye            Expires March 1, 2009                 [Page 5]
  281 
  282 Internet-Draft          Memcache Binary Protocol             August 2008
  283 
  284 
  285 3.3.  Command Opcodes
  286 
  287    Possible values of the one-byte field:
  288 
  289    0x00    Get
  290    0x01    Set
  291    0x02    Add
  292    0x03    Replace
  293    0x04    Delete
  294    0x05    Increment
  295    0x06    Decrement
  296    0x07    Quit
  297    0x08    Flush
  298    0x09    GetQ
  299    0x0A    No-op
  300    0x0B    Version
  301    0x0C    GetK
  302    0x0D    GetKQ
  303    0x0E    Append
  304    0x0F    Prepend
  305    0x10    Stat
  306    0x11    SetQ
  307    0x12    AddQ
  308    0x13    ReplaceQ
  309    0x14    DeleteQ
  310    0x15    IncrementQ
  311    0x16    DecrementQ
  312    0x17    QuitQ
  313    0x18    FlushQ
  314    0x19    AppendQ
  315    0x1A    PrependQ
  316 
  317    As a convention all of the commands ending with "Q" for Quiet.  A
  318    quiet version of a command will omit responses that are considered
  319    uninteresting.  Whether a given response is interesting is dependent
  320    upon the command.  See the descriptions of the set commands
  321    (Section 4.2) and set commands (Section 4.3) for examples of commands
  322    that include quiet variants.
  323 
  324 3.4.  Data Types
  325 
  326    Possible values of the one-byte field:
  327 
  328    0x00    Raw bytes
  329 
  330 
  331 
  332 
  333 
  334 
  335 
  336 Stone & Norbye            Expires March 1, 2009                 [Page 6]
  337 
  338 Internet-Draft          Memcache Binary Protocol             August 2008
  339 
  340 
  341 4.  Commands
  342 
  343 4.1.  Introduction
  344 
  345    All communication is initiated by a request from the client, and the
  346    server will respond to each request with zero or multiple packets for
  347    each request.  If the status code of a response packet is non-nil,
  348    the body of the packet will contain a textual error message.  If the
  349    status code is nil, the command opcode will define the layout of the
  350    body of the message.
  351 
  352 4.1.1.  Example
  353 
  354    The following figure illustrates the packet layout for a packet with
  355    an error message.
  356 
  357 
  358 
  359 
  360 
  361 
  362 
  363 
  364 
  365 
  366 
  367 
  368 
  369 
  370 
  371 
  372 
  373 
  374 
  375 
  376 
  377 
  378 
  379 
  380 
  381 
  382 
  383 
  384 
  385 
  386 
  387 
  388 
  389 
  390 
  391 
  392 Stone & Norbye            Expires March 1, 2009                 [Page 7]
  393 
  394 Internet-Draft          Memcache Binary Protocol             August 2008
  395 
  396 
  397    Packet layout:
  398 
  399 
  400      Byte/     0       |       1       |       2       |       3       |
  401         /              |               |               |               |
  402        |0 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|
  403        +---------------+---------------+---------------+---------------+
  404       0| 0x81          | 0x00          | 0x00          | 0x00          |
  405        +---------------+---------------+---------------+---------------+
  406       4| 0x00          | 0x00          | 0x00          | 0x01          |
  407        +---------------+---------------+---------------+---------------+
  408       8| 0x00          | 0x00          | 0x00          | 0x09          |
  409        +---------------+---------------+---------------+---------------+
  410      12| 0x00          | 0x00          | 0x00          | 0x00          |
  411        +---------------+---------------+---------------+---------------+
  412      16| 0x00          | 0x00          | 0x00          | 0x00          |
  413        +---------------+---------------+---------------+---------------+
  414      20| 0x00          | 0x00          | 0x00          | 0x00          |
  415        +---------------+---------------+---------------+---------------+
  416      24| 0x4e ('N')    | 0x6f ('o')    | 0x74 ('t')    | 0x20 (' ')    |
  417        +---------------+---------------+---------------+---------------+
  418      28| 0x66 ('f')    | 0x6f ('o')    | 0x75 ('u')    | 0x6e ('n')    |
  419        +---------------+---------------+---------------+---------------+
  420      32| 0x64 ('d')    |
  421        +---------------+
  422        Total 33 bytes (24 byte header, and 9 bytes value)
  423 
  424    Field        (offset) (value)
  425    Magic        (0)    : 0x81
  426    Opcode       (1)    : 0x00
  427    Key length   (2,3)  : 0x0000
  428    Extra length (4)    : 0x00
  429    Data type    (5)    : 0x00
  430    Status       (6,7)  : 0x0001
  431    Total body   (8-11) : 0x00000009
  432    Opaque       (12-15): 0x00000000
  433    CAS          (16-23): 0x0000000000000000
  434    Extras              : None
  435    Key                 : None
  436    Value        (24-32): The textual string "Not found"
  437 
  438 4.2.  Get, Get Quietly, Get Key, Get Key Quietly
  439 
  440    Request:
  441 
  442       MUST NOT have extras.
  443       MUST have key.
  444       MUST NOT have value.
  445 
  446 
  447 
  448 Stone & Norbye            Expires March 1, 2009                 [Page 8]
  449 
  450 Internet-Draft          Memcache Binary Protocol             August 2008
  451 
  452 
  453    Response (if found):
  454 
  455       MUST have extras.
  456       MAY have key.
  457       MAY have value.
  458 
  459    o  4 byte flags
  460 
  461    Extra data for the get commands:
  462 
  463      Byte/     0       |       1       |       2       |       3       |
  464         /              |               |               |               |
  465        |0 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|
  466        +---------------+---------------+---------------+---------------+
  467       0| Flags                                                         |
  468        +---------------+---------------+---------------+---------------+
  469 
  470        Total 4 bytes
  471 
  472    The get command gets a single key.  The getq command is both mum on
  473    cache miss and quiet, holding its response until a non-quiet command
  474    is issued.  Getk and getkq differs from get and getq by adding the
  475    key into the response packet.
  476 
  477    You're not guaranteed a response to a getq/getkq cache hit until you
  478    send a non-getq/getkq command later, which uncorks the server and
  479    bundles up IOs to send to the client in one go.
  480 
  481    Clients should implement multi-get (still important for reducing
  482    network roundtrips!) as n pipelined requests, the first n-1 being
  483    getq/getkq, the last being a regular get/getk.  That way you're
  484    guaranteed to get a response, and you know when the server's done.
  485    You can also do the naive thing and send n pipelined get/getks, but
  486    then you could potentially get back a lot of "NOT_FOUND" error code
  487    packets.  Alternatively, you can send 'n' getq/getkqs, followed by a
  488    'noop' command.
  489 
  490 4.2.1.  Example
  491 
  492    To request the data associated with the key "Hello" the following
  493    fields must be specified in the packet.
  494 
  495 
  496 
  497 
  498 
  499 
  500 
  501 
  502 
  503 
  504 Stone & Norbye            Expires March 1, 2009                 [Page 9]
  505 
  506 Internet-Draft          Memcache Binary Protocol             August 2008
  507 
  508 
  509    get request:
  510 
  511      Byte/     0       |       1       |       2       |       3       |
  512         /              |               |               |               |
  513        |0 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|
  514        +---------------+---------------+---------------+---------------+
  515       0| 0x80          | 0x00          | 0x00          | 0x05          |
  516        +---------------+---------------+---------------+---------------+
  517       4| 0x00          | 0x00          | 0x00          | 0x00          |
  518        +---------------+---------------+---------------+---------------+
  519       8| 0x00          | 0x00          | 0x00          | 0x05          |
  520        +---------------+---------------+---------------+---------------+
  521      12| 0x00          | 0x00          | 0x00          | 0x00          |
  522        +---------------+---------------+---------------+---------------+
  523      16| 0x00          | 0x00          | 0x00          | 0x00          |
  524        +---------------+---------------+---------------+---------------+
  525      20| 0x00          | 0x00          | 0x00          | 0x00          |
  526        +---------------+---------------+---------------+---------------+
  527      24| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
  528        +---------------+---------------+---------------+---------------+
  529      28| 0x6f ('o')    |
  530        +---------------+
  531 
  532        Total 29 bytes (24 byte header, and 5 bytes key)
  533 
  534    Field        (offset) (value)
  535    Magic        (0)    : 0x80
  536    Opcode       (1)    : 0x00
  537    Key length   (2,3)  : 0x0005
  538    Extra length (4)    : 0x00
  539    Data type    (5)    : 0x00
  540    Reserved     (6,7)  : 0x0000
  541    Total body   (8-11) : 0x00000005
  542    Opaque       (12-15): 0x00000000
  543    CAS          (16-23): 0x0000000000000000
  544    Extras              : None
  545    Key          (24-29): The textual string: "Hello"
  546    Value               : None
  547 
  548    If the item exist on the server the following packet is returned,
  549    otherwise a packet with status code != 0 will be returned (see
  550    Introduction (Section 4.1))
  551 
  552 
  553 
  554 
  555 
  556 
  557 
  558 
  559 
  560 Stone & Norbye            Expires March 1, 2009                [Page 10]
  561 
  562 Internet-Draft          Memcache Binary Protocol             August 2008
  563 
  564 
  565    get/getq response:
  566 
  567 
  568      Byte/     0       |       1       |       2       |       3       |
  569         /              |               |               |               |
  570        |0 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|
  571        +---------------+---------------+---------------+---------------+
  572       0| 0x81          | 0x00          | 0x00          | 0x00          |
  573        +---------------+---------------+---------------+---------------+
  574       4| 0x04          | 0x00          | 0x00          | 0x00          |
  575        +---------------+---------------+---------------+---------------+
  576       8| 0x00          | 0x00          | 0x00          | 0x09          |
  577        +---------------+---------------+---------------+---------------+
  578      12| 0x00          | 0x00          | 0x00          | 0x00          |
  579        +---------------+---------------+---------------+---------------+
  580      16| 0x00          | 0x00          | 0x00          | 0x00          |
  581        +---------------+---------------+---------------+---------------+
  582      20| 0x00          | 0x00          | 0x00          | 0x01          |
  583        +---------------+---------------+---------------+---------------+
  584      24| 0xde          | 0xad          | 0xbe          | 0xef          |
  585        +---------------+---------------+---------------+---------------+
  586      28| 0x57 ('W')    | 0x6f ('o')    | 0x72 ('r')    | 0x6c ('l')    |
  587        +---------------+---------------+---------------+---------------+
  588      32| 0x64 ('d')    |
  589        +---------------+
  590 
  591        Total 33 bytes (24 byte header, 4 byte extras and 5 byte value)
  592 
  593    Field        (offset) (value)
  594    Magic        (0)    : 0x81
  595    Opcode       (1)    : 0x00
  596    Key length   (2,3)  : 0x0000
  597    Extra length (4)    : 0x04
  598    Data type    (5)    : 0x00
  599    Status       (6,7)  : 0x0000
  600    Total body   (8-11) : 0x00000009
  601    Opaque       (12-15): 0x00000000
  602    CAS          (16-23): 0x0000000000000001
  603    Extras              :
  604      Flags      (24-27): 0xdeadbeef
  605    Key                 : None
  606    Value        (28-32): The textual string "World"
  607 
  608 
  609 
  610 
  611 
  612 
  613 
  614 
  615 
  616 Stone & Norbye            Expires March 1, 2009                [Page 11]
  617 
  618 Internet-Draft          Memcache Binary Protocol             August 2008
  619 
  620 
  621    getk/getkq response:
  622 
  623 
  624      Byte/     0       |       1       |       2       |       3       |
  625         /              |               |               |               |
  626        |0 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|
  627        +---------------+---------------+---------------+---------------+
  628       0| 0x81          | 0x00          | 0x00          | 0x05          |
  629        +---------------+---------------+---------------+---------------+
  630       4| 0x04          | 0x00          | 0x00          | 0x00          |
  631        +---------------+---------------+---------------+---------------+
  632       8| 0x00          | 0x00          | 0x00          | 0x09          |
  633        +---------------+---------------+---------------+---------------+
  634      12| 0x00          | 0x00          | 0x00          | 0x00          |
  635        +---------------+---------------+---------------+---------------+
  636      16| 0x00          | 0x00          | 0x00          | 0x00          |
  637        +---------------+---------------+---------------+---------------+
  638      20| 0x00          | 0x00          | 0x00          | 0x01          |
  639        +---------------+---------------+---------------+---------------+
  640      24| 0xde          | 0xad          | 0xbe          | 0xef          |
  641        +---------------+---------------+---------------+---------------+
  642      28| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
  643        +---------------+---------------+---------------+---------------+
  644      32| 0x6f ('o')    | 0x57 ('W')    | 0x6f ('o')    | 0x72 ('r')    |
  645        +---------------+---------------+---------------+---------------+
  646      36| 0x6c ('l')    | 0x64 ('d')    |
  647        +---------------+---------------+
  648 
  649        Total 38 bytes (24 byte header, 4 byte extras, 5 byte key
  650                        and 5 byte value)
  651 
  652    Field        (offset) (value)
  653    Magic        (0)    : 0x81
  654    Opcode       (1)    : 0x00
  655    Key length   (2,3)  : 0x0005
  656    Extra length (4)    : 0x04
  657    Data type    (5)    : 0x00
  658    Status       (6,7)  : 0x0000
  659    Total body   (8-11) : 0x0000000E
  660    Opaque       (12-15): 0x00000000
  661    CAS          (16-23): 0x0000000000000001
  662    Extras              :
  663      Flags      (24-27): 0xdeadbeef
  664    Key          (28-32): The textual string: "Hello"
  665    Value        (33-37): The textual string: "World"
  666 
  667 
  668 
  669 
  670 
  671 
  672 Stone & Norbye            Expires March 1, 2009                [Page 12]
  673 
  674 Internet-Draft          Memcache Binary Protocol             August 2008
  675 
  676 
  677 4.3.  Set, Add, Replace
  678 
  679       MUST have extras.
  680       MUST have key.
  681       MUST have value.
  682 
  683    o  4 byte flags
  684    o  4 byte expiration time
  685 
  686    Extra data for set/add/replace:
  687 
  688      Byte/     0       |       1       |       2       |       3       |
  689         /              |               |               |               |
  690        |0 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|
  691        +---------------+---------------+---------------+---------------+
  692       0| Flags                                                         |
  693        +---------------+---------------+---------------+---------------+
  694       4| Expiration                                                    |
  695        +---------------+---------------+---------------+---------------+
  696        Total 8 bytes
  697 
  698    If the Data Version Check (CAS) is nonzero, the requested operation
  699    MUST only succeed if the item exists and has a CAS value identical to
  700    the provided value.
  701 
  702    Add MUST fail if the item already exist.
  703 
  704    Replace MUST fail if the item doesn't exist.
  705 
  706    Set should store the data unconditionally if the item exists or not.
  707 
  708    Quiet mutations only return responses on failure.  Success is
  709    considered the general case and is suppressed when in quiet mode, but
  710    errors should not be allowed to go unnoticed.
  711 
  712 4.3.1.  Example
  713 
  714    The following figure shows an add-command for
  715 
  716       Key: "Hello"
  717       Value: "World"
  718       Flags: 0xdeadbeef
  719       Expiry: in two hours
  720 
  721 
  722 
  723 
  724 
  725 
  726 
  727 
  728 Stone & Norbye            Expires March 1, 2009                [Page 13]
  729 
  730 Internet-Draft          Memcache Binary Protocol             August 2008
  731 
  732 
  733    Add request:
  734 
  735 
  736      Byte/     0       |       1       |       2       |       3       |
  737         /              |               |               |               |
  738        |0 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|
  739        +---------------+---------------+---------------+---------------+
  740       0| 0x80          | 0x02          | 0x00          | 0x05          |
  741        +---------------+---------------+---------------+---------------+
  742       4| 0x08          | 0x00          | 0x00          | 0x00          |
  743        +---------------+---------------+---------------+---------------+
  744       8| 0x00          | 0x00          | 0x00          | 0x12          |
  745        +---------------+---------------+---------------+---------------+
  746      12| 0x00          | 0x00          | 0x00          | 0x00          |
  747        +---------------+---------------+---------------+---------------+
  748      16| 0x00          | 0x00          | 0x00          | 0x00          |
  749        +---------------+---------------+---------------+---------------+
  750      20| 0x00          | 0x00          | 0x00          | 0x00          |
  751        +---------------+---------------+---------------+---------------+
  752      24| 0xde          | 0xad          | 0xbe          | 0xef          |
  753        +---------------+---------------+---------------+---------------+
  754      28| 0x00          | 0x00          | 0x1c          | 0x20          |
  755        +---------------+---------------+---------------+---------------+
  756      32| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
  757        +---------------+---------------+---------------+---------------+
  758      36| 0x6f ('o')    | 0x57 ('W')    | 0x6f ('o')    | 0x72 ('r')    |
  759        +---------------+---------------+---------------+---------------+
  760      40| 0x6c ('l')    | 0x64 ('d')    |
  761        +---------------+---------------+
  762 
  763        Total 42 bytes (24 byte header, 8 byte extras, 5 byte key and
  764                        5 byte value)
  765 
  766    Field        (offset) (value)
  767    Magic        (0)    : 0x80
  768    Opcode       (1)    : 0x02
  769    Key length   (2,3)  : 0x0005
  770    Extra length (4)    : 0x08
  771    Data type    (5)    : 0x00
  772    Reserved     (6,7)  : 0x0000
  773    Total body   (8-11) : 0x00000012
  774    Opaque       (12-15): 0x00000000
  775    CAS          (16-23): 0x0000000000000000
  776    Extras              :
  777      Flags      (24-27): 0xdeadbeef
  778      Expiry     (28-31): 0x00001c20
  779    Key          (32-36): The textual string "Hello"
  780    Value        (37-41): The textual string "World"
  781 
  782 
  783 
  784 Stone & Norbye            Expires March 1, 2009                [Page 14]
  785 
  786 Internet-Draft          Memcache Binary Protocol             August 2008
  787 
  788 
  789    The response-packet contains no extra data, and the result of the
  790    operation is signaled through the status code.  If the command
  791    succeeds, the CAS value for the item is returned in the CAS-field of
  792    the packet.
  793 
  794    Successful add response:
  795 
  796 
  797      Byte/     0       |       1       |       2       |       3       |
  798         /              |               |               |               |
  799        |0 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|
  800        +---------------+---------------+---------------+---------------+
  801       0| 0x81          | 0x02          | 0x00          | 0x00          |
  802        +---------------+---------------+---------------+---------------+
  803       4| 0x00          | 0x00          | 0x00          | 0x00          |
  804        +---------------+---------------+---------------+---------------+
  805       8| 0x00          | 0x00          | 0x00          | 0x00          |
  806        +---------------+---------------+---------------+---------------+
  807      12| 0x00          | 0x00          | 0x00          | 0x00          |
  808        +---------------+---------------+---------------+---------------+
  809      16| 0x00          | 0x00          | 0x00          | 0x00          |
  810        +---------------+---------------+---------------+---------------+
  811      20| 0x00          | 0x00          | 0x00          | 0x01          |
  812        +---------------+---------------+---------------+---------------+
  813 
  814        Total 24 bytes
  815 
  816    Field        (offset) (value)
  817    Magic        (0)    : 0x81
  818    Opcode       (1)    : 0x02
  819    Key length   (2,3)  : 0x0000
  820    Extra length (4)    : 0x00
  821    Data type    (5)    : 0x00
  822    Status       (6,7)  : 0x0000
  823    Total body   (8-11) : 0x00000000
  824    Opaque       (12-15): 0x00000000
  825    CAS          (16-23): 0x0000000000000001
  826    Extras              : None
  827    Key                 : None
  828    Value               : None
  829 
  830 4.4.  Delete
  831 
  832       MUST NOT have extras.
  833       MUST have key.
  834       MUST NOT have value.
  835 
  836    Delete the item with the specific key.
  837 
  838 
  839 
  840 Stone & Norbye            Expires March 1, 2009                [Page 15]
  841 
  842 Internet-Draft          Memcache Binary Protocol             August 2008
  843 
  844 
  845 4.4.1.  Example
  846 
  847    The following figure shows a delete message for the item "Hello".
  848 
  849    Delete request:
  850 
  851      Byte/     0       |       1       |       2       |       3       |
  852         /              |               |               |               |
  853        |0 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|
  854        +---------------+---------------+---------------+---------------+
  855       0| 0x80          | 0x04          | 0x00          | 0x05          |
  856        +---------------+---------------+---------------+---------------+
  857       4| 0x00          | 0x00          | 0x00          | 0x00          |
  858        +---------------+---------------+---------------+---------------+
  859       8| 0x00          | 0x00          | 0x00          | 0x05          |
  860        +---------------+---------------+---------------+---------------+
  861      12| 0x00          | 0x00          | 0x00          | 0x00          |
  862        +---------------+---------------+---------------+---------------+
  863      16| 0x00          | 0x00          | 0x00          | 0x00          |
  864        +---------------+---------------+---------------+---------------+
  865      20| 0x00          | 0x00          | 0x00          | 0x00          |
  866        +---------------+---------------+---------------+---------------+
  867      24| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
  868        +---------------+---------------+---------------+---------------+
  869      28| 0x6f ('o')    |
  870        +---------------+
  871 
  872        Total 29 bytes (24 byte header, 5 byte value)
  873 
  874    Field        (offset) (value)
  875    Magic        (0)    : 0x80
  876    Opcode       (1)    : 0x04
  877    Key length   (2,3)  : 0x0005
  878    Extra length (4)    : 0x00
  879    Data type    (5)    : 0x00
  880    Reserved     (6,7)  : 0x0000
  881    Total body   (8-11) : 0x00000005
  882    Opaque       (12-15): 0x00000000
  883    CAS          (16-23): 0x0000000000000000
  884    Extras              : None
  885    Key                 : The textual string "Hello"
  886    Value               : None
  887 
  888    The response-packet contains no extra data, and the result of the
  889    operation is signaled through the status code.
  890 
  891 
  892 
  893 
  894 
  895 
  896 Stone & Norbye            Expires March 1, 2009                [Page 16]
  897 
  898 Internet-Draft          Memcache Binary Protocol             August 2008
  899 
  900 
  901 4.5.  Increment, Decrement
  902 
  903       MUST have extras.
  904       MUST have key.
  905       MUST NOT have value.
  906 
  907    o  8 byte value to add / subtract
  908    o  8 byte initial value (unsigned)
  909    o  4 byte expiration time
  910 
  911    Extra data for incr/decr:
  912 
  913      Byte/     0       |       1       |       2       |       3       |
  914         /              |               |               |               |
  915        |0 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|
  916        +---------------+---------------+---------------+---------------+
  917       0| Amount to add                                                 |
  918        |                                                               |
  919        +---------------+---------------+---------------+---------------+
  920       8| Initial value                                                 |
  921        |                                                               |
  922        +---------------+---------------+---------------+---------------+
  923      16| Expiration                                                    |
  924        +---------------+---------------+---------------+---------------+
  925        Total 20 bytes
  926 
  927    These commands will either add or remove the specified amount to the
  928    requested counter.
  929 
  930    If the counter does not exist, one of two things may happen:
  931 
  932    1.  If the expiration value is all one-bits (0xffffffff), the
  933        operation will fail with NOT_FOUND.
  934    2.  For all other expiration values, the operation will succeed by
  935        seeding the value for this key with the provided initial value to
  936        expire with the provided expiration time.  The flags will be set
  937        to zero.
  938 
  939    incr/decr response body:
  940 
  941      Byte/     0       |       1       |       2       |       3       |
  942         /              |               |               |               |
  943        |0 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|
  944        +---------------+---------------+---------------+---------------+
  945       0| 64-bit unsigned response.                                     |
  946        |                                                               |
  947        +---------------+---------------+---------------+---------------+
  948        Total 8 bytes
  949 
  950 
  951 
  952 Stone & Norbye            Expires March 1, 2009                [Page 17]
  953 
  954 Internet-Draft          Memcache Binary Protocol             August 2008
  955 
  956 
  957 4.5.1.  Example
  958 
  959    The following figure shows an incr-command for
  960 
  961       Key: "counter"
  962       Delta: 0x01
  963       Initial: 0x00
  964       Expiry: in two hours
  965 
  966    Increment request:
  967 
  968 
  969 
  970 
  971 
  972 
  973 
  974 
  975 
  976 
  977 
  978 
  979 
  980 
  981 
  982 
  983 
  984 
  985 
  986 
  987 
  988 
  989 
  990 
  991 
  992 
  993 
  994 
  995 
  996 
  997 
  998 
  999 
 1000 
 1001 
 1002 
 1003 
 1004 
 1005 
 1006 
 1007 
 1008 Stone & Norbye            Expires March 1, 2009                [Page 18]
 1009 
 1010 Internet-Draft          Memcache Binary Protocol             August 2008
 1011 
 1012 
 1013      Byte/     0       |       1       |       2       |       3       |
 1014         /              |               |               |               |
 1015        |0 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|
 1016        +---------------+---------------+---------------+---------------+
 1017       0| 0x80          | 0x05          | 0x00          | 0x07          |
 1018        +---------------+---------------+---------------+---------------+
 1019       4| 0x14          | 0x00          | 0x00          | 0x00          |
 1020        +---------------+---------------+---------------+---------------+
 1021       8| 0x00          | 0x00          | 0x00          | 0x1b          |
 1022        +---------------+---------------+---------------+---------------+
 1023      12| 0x00          | 0x00          | 0x00          | 0x00          |
 1024        +---------------+---------------+---------------+---------------+
 1025      16| 0x00          | 0x00          | 0x00          | 0x00          |
 1026        +---------------+---------------+---------------+---------------+
 1027      20| 0x00          | 0x00          | 0x00          | 0x00          |
 1028        +---------------+---------------+---------------+---------------+
 1029      24| 0x00          | 0x00          | 0x00          | 0x00          |
 1030        +---------------+---------------+---------------+---------------+
 1031      28| 0x00          | 0x00          | 0x00          | 0x01          |
 1032        +---------------+---------------+---------------+---------------+
 1033      32| 0x00          | 0x00          | 0x00          | 0x00          |
 1034        +---------------+---------------+---------------+---------------+
 1035      36| 0x00          | 0x00          | 0x00          | 0x00          |
 1036        +---------------+---------------+---------------+---------------+
 1037      40| 0x00          | 0x00          | 0x1c          | 0x20          |
 1038        +---------------+---------------+---------------+---------------+
 1039      44| 0x63 ('c')    | 0x6f ('o')    | 0x75 ('u')    | 0x6e ('n')    |
 1040        +---------------+---------------+---------------+---------------+
 1041      48| 0x74 ('t')    | 0x65 ('e')    | 0x72 ('r')    |
 1042        +---------------+---------------+---------------+
 1043        Total 51 bytes (24 byte header, 20 byte extras, 7 byte key)
 1044 
 1045    Field        (offset) (value)
 1046    Magic        (0)    : 0x80
 1047    Opcode       (1)    : 0x05
 1048    Key length   (2,3)  : 0x0007
 1049    Extra length (4)    : 0x14
 1050    Data type    (5)    : 0x00
 1051    Reserved     (6,7)  : 0x0000
 1052    Total body   (8-11) : 0x0000001b
 1053    Opaque       (12-15): 0x00000000
 1054    CAS          (16-23): 0x0000000000000000
 1055    Extras              :
 1056      delta      (24-31): 0x0000000000000001
 1057      initial    (32-39): 0x0000000000000000
 1058      expiration (40-43): 0x00001c20
 1059    Key                 : Textual string "counter"
 1060    Value               : None
 1061 
 1062 
 1063 
 1064 Stone & Norbye            Expires March 1, 2009                [Page 19]
 1065 
 1066 Internet-Draft          Memcache Binary Protocol             August 2008
 1067 
 1068 
 1069    If the key doesn't exist, the server will respond with the initial
 1070    value.  If not the incremented value will be returned.  Let's assume
 1071    that the key didn't exist, so the initial value is returned.
 1072 
 1073    Increment response:
 1074 
 1075      Byte/     0       |       1       |       2       |       3       |
 1076         /              |               |               |               |
 1077        |0 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|
 1078        +---------------+---------------+---------------+---------------+
 1079       0| 0x81          | 0x05          | 0x00          | 0x00          |
 1080        +---------------+---------------+---------------+---------------+
 1081       4| 0x00          | 0x00          | 0x00          | 0x00          |
 1082        +---------------+---------------+---------------+---------------+
 1083       8| 0x00          | 0x00          | 0x00          | 0x08          |
 1084        +---------------+---------------+---------------+---------------+
 1085      12| 0x00          | 0x00          | 0x00          | 0x00          |
 1086        +---------------+---------------+---------------+---------------+
 1087      16| 0x00          | 0x00          | 0x00          | 0x00          |
 1088        +---------------+---------------+---------------+---------------+
 1089      20| 0x00          | 0x00          | 0x00          | 0x05          |
 1090        +---------------+---------------+---------------+---------------+
 1091      24| 0x00          | 0x00          | 0x00          | 0x00          |
 1092        +---------------+---------------+---------------+---------------+
 1093      28| 0x00          | 0x00          | 0x00          | 0x00          |
 1094        +---------------+---------------+---------------+---------------+
 1095        Total 32 bytes (24 byte header, 8 byte value)
 1096 
 1097    Field        (offset) (value)
 1098    Magic        (0)    : 0x81
 1099    Opcode       (1)    : 0x05
 1100    Key length   (2,3)  : 0x0000
 1101    Extra length (4)    : 0x00
 1102    Data type    (5)    : 0x00
 1103    Status       (6,7)  : 0x0000
 1104    Total body   (8-11) : 0x00000008
 1105    Opaque       (12-15): 0x00000000
 1106    CAS          (16-23): 0x0000000000000005
 1107    Extras              : None
 1108    Key                 : None
 1109    Value               : 0x0000000000000000
 1110 
 1111 4.6.  quit
 1112 
 1113       MUST NOT have extras.
 1114       MUST NOT have key.
 1115       MUST NOT have value.
 1116 
 1117 
 1118 
 1119 
 1120 Stone & Norbye            Expires March 1, 2009                [Page 20]
 1121 
 1122 Internet-Draft          Memcache Binary Protocol             August 2008
 1123 
 1124 
 1125    Close the connection to the server.
 1126 
 1127 4.6.1.  Example
 1128 
 1129    Quit request:
 1130 
 1131      Byte/     0       |       1       |       2       |       3       |
 1132         /              |               |               |               |
 1133        |0 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|
 1134        +---------------+---------------+---------------+---------------+
 1135       0| 0x80          | 0x07          | 0x00          | 0x00          |
 1136        +---------------+---------------+---------------+---------------+
 1137       4| 0x00          | 0x00          | 0x00          | 0x00          |
 1138        +---------------+---------------+---------------+---------------+
 1139       8| 0x00          | 0x00          | 0x00          | 0x00          |
 1140        +---------------+---------------+---------------+---------------+
 1141      12| 0x00          | 0x00          | 0x00          | 0x00          |
 1142        +---------------+---------------+---------------+---------------+
 1143      16| 0x00          | 0x00          | 0x00          | 0x00          |
 1144        +---------------+---------------+---------------+---------------+
 1145      20| 0x00          | 0x00          | 0x00          | 0x00          |
 1146        +---------------+---------------+---------------+---------------+
 1147        Total 24 bytes
 1148 
 1149    Field        (offset) (value)
 1150    Magic        (0)    : 0x80
 1151    Opcode       (1)    : 0x07
 1152    Key length   (2,3)  : 0x0000
 1153    Extra length (4)    : 0x00
 1154    Data type    (5)    : 0x00
 1155    Reserved     (6,7)  : 0x0000
 1156    Total body   (8-11) : 0x00000000
 1157    Opaque       (12-15): 0x00000000
 1158    CAS          (16-23): 0x0000000000000000
 1159    Extras              : None
 1160    Key                 : None
 1161    Value               : None
 1162 
 1163    The response-packet contains no extra data, and the result of the
 1164    operation is signaled through the status code.  The server will then
 1165    close the connection.
 1166 
 1167 4.7.  Flush
 1168 
 1169       MAY have extras.
 1170       MUST NOT have key.
 1171       MUST NOT have value.
 1172 
 1173 
 1174 
 1175 
 1176 Stone & Norbye            Expires March 1, 2009                [Page 21]
 1177 
 1178 Internet-Draft          Memcache Binary Protocol             August 2008
 1179 
 1180 
 1181    o  4 byte expiration time
 1182 
 1183    Extra data for flush:
 1184 
 1185      Byte/     0       |       1       |       2       |       3       |
 1186         /              |               |               |               |
 1187        |0 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|
 1188        +---------------+---------------+---------------+---------------+
 1189       0| Expiration                                                    |
 1190        +---------------+---------------+---------------+---------------+
 1191      Total 4 bytes
 1192 
 1193    Flush the items in the cache now or some time in the future as
 1194    specified by the expiration field.  See the documentation of the
 1195    textual protocol for the full description on how to specify the
 1196    expiration time.
 1197 
 1198 4.7.1.  Example
 1199 
 1200    To flush the cache (delete all items) in two hours, the set the
 1201    following values in the request
 1202 
 1203 
 1204 
 1205 
 1206 
 1207 
 1208 
 1209 
 1210 
 1211 
 1212 
 1213 
 1214 
 1215 
 1216 
 1217 
 1218 
 1219 
 1220 
 1221 
 1222 
 1223 
 1224 
 1225 
 1226 
 1227 
 1228 
 1229 
 1230 
 1231 
 1232 Stone & Norbye            Expires March 1, 2009                [Page 22]
 1233 
 1234 Internet-Draft          Memcache Binary Protocol             August 2008
 1235 
 1236 
 1237    Flush request:
 1238 
 1239      Byte/     0       |       1       |       2       |       3       |
 1240         /              |               |               |               |
 1241        |0 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|
 1242        +---------------+---------------+---------------+---------------+
 1243       0| 0x80          | 0x08          | 0x00          | 0x00          |
 1244        +---------------+---------------+---------------+---------------+
 1245       4| 0x04          | 0x00          | 0x00          | 0x00          |
 1246        +---------------+---------------+---------------+---------------+
 1247       8| 0x00          | 0x00          | 0x00          | 0x04          |
 1248        +---------------+---------------+---------------+---------------+
 1249      12| 0x00          | 0x00          | 0x00          | 0x00          |
 1250        +---------------+---------------+---------------+---------------+
 1251      16| 0x00          | 0x00          | 0x00          | 0x00          |
 1252        +---------------+---------------+---------------+---------------+
 1253      20| 0x00          | 0x00          | 0x00          | 0x00          |
 1254        +---------------+---------------+---------------+---------------+
 1255      24| 0x00          | 0x00          | 0x1c          | 0x20          |
 1256        +---------------+---------------+---------------+---------------+
 1257        Total 28 bytes (24 byte header, 4 byte body)
 1258 
 1259    Field        (offset) (value)
 1260    Magic        (0)    : 0x80
 1261    Opcode       (1)    : 0x08
 1262    Key length   (2,3)  : 0x0000
 1263    Extra length (4)    : 0x04
 1264    Data type    (5)    : 0x00
 1265    Reserved     (6,7)  : 0x0000
 1266    Total body   (8-11) : 0x00000004
 1267    Opaque       (12-15): 0x00000000
 1268    CAS          (16-23): 0x0000000000000000
 1269    Extras              :
 1270       Expiry    (24-27): 0x00001c20
 1271    Key                 : None
 1272    Value               : None
 1273 
 1274    The response-packet contains no extra data, and the result of the
 1275    operation is signaled through the status code.
 1276 
 1277 4.8.  noop
 1278 
 1279       MUST NOT have extras.
 1280       MUST NOT have key.
 1281       MUST NOT have value.
 1282 
 1283    Used as a keep alive.  Flushes outstanding getq/getkq's.
 1284 
 1285 
 1286 
 1287 
 1288 Stone & Norbye            Expires March 1, 2009                [Page 23]
 1289 
 1290 Internet-Draft          Memcache Binary Protocol             August 2008
 1291 
 1292 
 1293 4.8.1.  Example
 1294 
 1295    Noop request:
 1296 
 1297      Byte/     0       |       1       |       2       |       3       |
 1298         /              |               |               |               |
 1299        |0 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|
 1300        +---------------+---------------+---------------+---------------+
 1301       0| 0x80          | 0x0a          | 0x00          | 0x00          |
 1302        +---------------+---------------+---------------+---------------+
 1303       4| 0x00          | 0x00          | 0x00          | 0x00          |
 1304        +---------------+---------------+---------------+---------------+
 1305       8| 0x00          | 0x00          | 0x00          | 0x00          |
 1306        +---------------+---------------+---------------+---------------+
 1307      12| 0x00          | 0x00          | 0x00          | 0x00          |
 1308        +---------------+---------------+---------------+---------------+
 1309      16| 0x00          | 0x00          | 0x00          | 0x00          |
 1310        +---------------+---------------+---------------+---------------+
 1311      20| 0x00          | 0x00          | 0x00          | 0x00          |
 1312        +---------------+---------------+---------------+---------------+
 1313        Total 24 bytes
 1314 
 1315    Field        (offset) (value)
 1316    Magic        (0)    : 0x80
 1317    Opcode       (1)    : 0x0a
 1318    Key length   (2,3)  : 0x0000
 1319    Extra length (4)    : 0x00
 1320    Data type    (5)    : 0x00
 1321    Reserved     (6,7)  : 0x0000
 1322    Total body   (8-11) : 0x00000000
 1323    Opaque       (12-15): 0x00000000
 1324    CAS          (16-23): 0x0000000000000000
 1325    Extras              : None
 1326    Key                 : None
 1327    Value               : None
 1328 
 1329    The response-packet contains no extra data, and the result of the
 1330    operation is signaled through the status code.
 1331 
 1332 4.9.  version
 1333 
 1334       MUST NOT have extras.
 1335       MUST NOT have key.
 1336       MUST NOT have value.
 1337 
 1338    Request the server version.
 1339 
 1340 
 1341 
 1342 
 1343 
 1344 Stone & Norbye            Expires March 1, 2009                [Page 24]
 1345 
 1346 Internet-Draft          Memcache Binary Protocol             August 2008
 1347 
 1348 
 1349    The server responds with a packet containing the version string in
 1350    the body with the following format: "x.y.z"
 1351 
 1352 4.9.1.  Example
 1353 
 1354    Version request:
 1355 
 1356      Byte/     0       |       1       |       2       |       3       |
 1357         /              |               |               |               |
 1358        |0 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|
 1359        +---------------+---------------+---------------+---------------+
 1360       0| 0x80          | 0x0b          | 0x00          | 0x00          |
 1361        +---------------+---------------+---------------+---------------+
 1362       4| 0x00          | 0x00          | 0x00          | 0x00          |
 1363        +---------------+---------------+---------------+---------------+
 1364       8| 0x00          | 0x00          | 0x00          | 0x00          |
 1365        +---------------+---------------+---------------+---------------+
 1366      12| 0x00          | 0x00          | 0x00          | 0x00          |
 1367        +---------------+---------------+---------------+---------------+
 1368      16| 0x00          | 0x00          | 0x00          | 0x00          |
 1369        +---------------+---------------+---------------+---------------+
 1370      20| 0x00          | 0x00          | 0x00          | 0x00          |
 1371        +---------------+---------------+---------------+---------------+
 1372        Total 24 bytes
 1373 
 1374    Field        (offset) (value)
 1375    Magic        (0)    : 0x80
 1376    Opcode       (1)    : 0x0b
 1377    Key length   (2,3)  : 0x0000
 1378    Extra length (4)    : 0x00
 1379    Data type    (5)    : 0x00
 1380    Reserved     (6,7)  : 0x0000
 1381    Total body   (8-11) : 0x00000000
 1382    Opaque       (12-15): 0x00000000
 1383    CAS          (16-23): 0x0000000000000000
 1384    Extras              : None
 1385 
 1386 
 1387 
 1388 
 1389 
 1390 
 1391 
 1392 
 1393 
 1394 
 1395 
 1396 
 1397 
 1398 
 1399 
 1400 Stone & Norbye            Expires March 1, 2009                [Page 25]
 1401 
 1402 Internet-Draft          Memcache Binary Protocol             August 2008
 1403 
 1404 
 1405    Version response:
 1406 
 1407      Byte/     0       |       1       |       2       |       3       |
 1408         /              |               |               |               |
 1409        |0 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|
 1410        +---------------+---------------+---------------+---------------+
 1411       0| 0x81          | 0x0b          | 0x00          | 0x00          |
 1412        +---------------+---------------+---------------+---------------+
 1413       4| 0x00          | 0x00          | 0x00          | 0x00          |
 1414        +---------------+---------------+---------------+---------------+
 1415       8| 0x00          | 0x00          | 0x00          | 0x05          |
 1416        +---------------+---------------+---------------+---------------+
 1417      12| 0x00          | 0x00          | 0x00          | 0x00          |
 1418        +---------------+---------------+---------------+---------------+
 1419      16| 0x00          | 0x00          | 0x00          | 0x00          |
 1420        +---------------+---------------+---------------+---------------+
 1421      20| 0x00          | 0x00          | 0x00          | 0x00          |
 1422        +---------------+---------------+---------------+---------------+
 1423      24| 0x31 ('1')    | 0x2e ('.')    | 0x33 ('3')    | 0x2e ('.')    |
 1424        +---------------+---------------+---------------+---------------+
 1425      28| 0x31 ('1')    |
 1426        +---------------+
 1427        Total 29 bytes (24 byte header, 5 byte body)
 1428 
 1429    Field        (offset) (value)
 1430    Magic        (0)    : 0x81
 1431    Opcode       (1)    : 0x0b
 1432    Key length   (2,3)  : 0x0000
 1433    Extra length (4)    : 0x00
 1434    Data type    (5)    : 0x00
 1435    Status       (6,7)  : 0x0000
 1436    Total body   (8-11) : 0x00000005
 1437    Opaque       (12-15): 0x00000000
 1438    CAS          (16-23): 0x0000000000000000
 1439    Extras              : None
 1440    Key                 : None
 1441    Value               : Textual string "1.3.1"
 1442 
 1443 4.10.  Append, Prepend
 1444 
 1445       MUST NOT have extras.
 1446       MUST have key.
 1447       MUST have value.
 1448 
 1449    These commands will either append or prepend the specified value to
 1450    the requested key.
 1451 
 1452 
 1453 
 1454 
 1455 
 1456 Stone & Norbye            Expires March 1, 2009                [Page 26]
 1457 
 1458 Internet-Draft          Memcache Binary Protocol             August 2008
 1459 
 1460 
 1461 4.10.1.  Example
 1462 
 1463    The following example appends '!' to the 'Hello' key.
 1464 
 1465    Append request:
 1466 
 1467      Byte/     0       |       1       |       2       |       3       |
 1468         /              |               |               |               |
 1469        |0 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|
 1470        +---------------+---------------+---------------+---------------+
 1471       0| 0x80          | 0x0e          | 0x00          | 0x05          |
 1472        +---------------+---------------+---------------+---------------+
 1473       4| 0x00          | 0x00          | 0x00          | 0x00          |
 1474        +---------------+---------------+---------------+---------------+
 1475       8| 0x00          | 0x00          | 0x00          | 0x06          |
 1476        +---------------+---------------+---------------+---------------+
 1477      12| 0x00          | 0x00          | 0x00          | 0x00          |
 1478        +---------------+---------------+---------------+---------------+
 1479      16| 0x00          | 0x00          | 0x00          | 0x00          |
 1480        +---------------+---------------+---------------+---------------+
 1481      20| 0x00          | 0x00          | 0x00          | 0x00          |
 1482        +---------------+---------------+---------------+---------------+
 1483      24| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
 1484        +---------------+---------------+---------------+---------------+
 1485      28| 0x6f ('o')    | 0x21 ('!')    |
 1486        +---------------+---------------+
 1487        Total 30 bytes (24 byte header, 5 byte key, 1 byte value)
 1488 
 1489    Field        (offset) (value)
 1490    Magic        (0)    : 0x80
 1491    Opcode       (1)    : 0x0e
 1492    Key length   (2,3)  : 0x0005
 1493    Extra length (4)    : 0x00
 1494    Data type    (5)    : 0x00
 1495    Reserved     (6,7)  : 0x0000
 1496    Total body   (8-11) : 0x00000006
 1497    Opaque       (12-15): 0x00000000
 1498    CAS          (16-23): 0x0000000000000000
 1499    Extras              : None
 1500    Key          (24-28): The textual string "Hello"
 1501    Value        (29)   : "!"
 1502 
 1503    The response-packet contains no extra data, and the result of the
 1504    operation is signaled through the status code.
 1505 
 1506 
 1507 
 1508 
 1509 
 1510 
 1511 
 1512 Stone & Norbye            Expires March 1, 2009                [Page 27]
 1513 
 1514 Internet-Draft          Memcache Binary Protocol             August 2008
 1515 
 1516 
 1517 4.11.  Stat
 1518 
 1519       MUST NOT have extras.
 1520       MAY have key.
 1521       MUST NOT have value.
 1522 
 1523    Request server statistics.  Without a key specified the server will
 1524    respond with a "default" set of statistics information.  Each piece
 1525    of statistical information is returned in its own packet (key
 1526    contains the name of the statistical item and the body contains the
 1527    value in ASCII format).  The sequence of return packets is terminated
 1528    with a packet that contains no key and no value.
 1529 
 1530 4.11.1.  Example
 1531 
 1532    The following example requests all statistics from the server
 1533 
 1534 
 1535 
 1536 
 1537 
 1538 
 1539 
 1540 
 1541 
 1542 
 1543 
 1544 
 1545 
 1546 
 1547 
 1548 
 1549 
 1550 
 1551 
 1552 
 1553 
 1554 
 1555 
 1556 
 1557 
 1558 
 1559 
 1560 
 1561 
 1562 
 1563 
 1564 
 1565 
 1566 
 1567 
 1568 Stone & Norbye            Expires March 1, 2009                [Page 28]
 1569 
 1570 Internet-Draft          Memcache Binary Protocol             August 2008
 1571 
 1572 
 1573    Stat request:
 1574 
 1575      Byte/     0       |       1       |       2       |       3       |
 1576         /              |               |               |               |
 1577        |0 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|
 1578        +---------------+---------------+---------------+---------------+
 1579       0| 0x80          | 0x10          | 0x00          | 0x00          |
 1580        +---------------+---------------+---------------+---------------+
 1581       4| 0x00          | 0x00          | 0x00          | 0x00          |
 1582        +---------------+---------------+---------------+---------------+
 1583       8| 0x00          | 0x00          | 0x00          | 0x00          |
 1584        +---------------+---------------+---------------+---------------+
 1585      12| 0x00          | 0x00          | 0x00          | 0x00          |
 1586        +---------------+---------------+---------------+---------------+
 1587      16| 0x00          | 0x00          | 0x00          | 0x00          |
 1588        +---------------+---------------+---------------+---------------+
 1589      20| 0x00          | 0x00          | 0x00          | 0x00          |
 1590        +---------------+---------------+---------------+---------------+
 1591        Total 24 bytes
 1592 
 1593    Field        (offset) (value)
 1594    Magic        (0)    : 0x80
 1595    Opcode       (1)    : 0x10
 1596    Key length   (2,3)  : 0x0000
 1597    Extra length (4)    : 0x00
 1598    Data type    (5)    : 0x00
 1599    Reserved     (6,7)  : 0x0000
 1600    Total body   (8-11) : 0x00000000
 1601    Opaque       (12-15): 0x00000000
 1602    CAS          (16-23): 0x0000000000000000
 1603    Extras              : None
 1604    Key                 : None
 1605    Value               : None
 1606 
 1607    The server will send each value in a separate packet with an "empty"
 1608    packet (no key / no value) to terminate the sequence.  Each of the
 1609    response packets look like the following example:
 1610 
 1611 
 1612 
 1613 
 1614 
 1615 
 1616 
 1617 
 1618 
 1619 
 1620 
 1621 
 1622 
 1623 
 1624 Stone & Norbye            Expires March 1, 2009                [Page 29]
 1625 
 1626 Internet-Draft          Memcache Binary Protocol             August 2008
 1627 
 1628 
 1629    Stat response:
 1630 
 1631      Byte/     0       |       1       |       2       |       3       |
 1632         /              |               |               |               |
 1633        |0 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|
 1634        +---------------+---------------+---------------+---------------+
 1635       0| 0x81          | 0x10          | 0x00          | 0x03          |
 1636        +---------------+---------------+---------------+---------------+
 1637       4| 0x00          | 0x00          | 0x00          | 0x00          |
 1638        +---------------+---------------+---------------+---------------+
 1639       8| 0x00          | 0x00          | 0x00          | 0x07          |
 1640        +---------------+---------------+---------------+---------------+
 1641      12| 0x00          | 0x00          | 0x00          | 0x00          |
 1642        +---------------+---------------+---------------+---------------+
 1643      16| 0x00          | 0x00          | 0x00          | 0x00          |
 1644        +---------------+---------------+---------------+---------------+
 1645      20| 0x00          | 0x00          | 0x00          | 0x00          |
 1646        +---------------+---------------+---------------+---------------+
 1647      24| 0x70 ('p')    | 0x69 ('i')    | 0x64 ('d')    | 0x33 ('3')    |
 1648        +---------------+---------------+---------------+---------------+
 1649      28| 0x30 ('0')    | 0x37 ('7')    | 0x38 ('8')    |
 1650        +---------------+---------------+---------------+
 1651        Total 31 bytes (24 byte header, 3 byte key, 4 byte body)
 1652 
 1653    Field        (offset) (value)
 1654    Magic        (0)    : 0x81
 1655    Opcode       (1)    : 0x10
 1656    Key length   (2,3)  : 0x0003
 1657    Extra length (4)    : 0x00
 1658    Data type    (5)    : 0x00
 1659    Status       (6,7)  : 0x0000
 1660    Total body   (8-11) : 0x00000007
 1661    Opaque       (12-15): 0x00000000
 1662    CAS          (16-23): 0x0000000000000000
 1663    Extras              : None
 1664    Key                 : The textual string "pid"
 1665    Value               : The textual string "3078"
 1666 
 1667 5.  Security Considerations
 1668 
 1669    Memcache has few authentication and no security layers whatsoever.
 1670    It is RECOMMENDED that memcache be deployed strictly on closed,
 1671    protected, back-end networks within a single data center, within a
 1672    single cluster of servers, or even on a single host, providing shared
 1673    caching for multiple applications.  Memcache MUST NOT be made
 1674    available on a public network.
 1675 
 1676 
 1677 
 1678 
 1679 
 1680 Stone & Norbye            Expires March 1, 2009                [Page 30]
 1681 
 1682 Internet-Draft          Memcache Binary Protocol             August 2008
 1683 
 1684 
 1685    SASL is supported as an authentication mechanism.  See the wiki for
 1686    more information.
 1687 
 1688 6.  Normative References
 1689 
 1690    [KEYWORDS]
 1691               Bradner, S., "Key words for use in RFCs to Indicate
 1692               Requirement Levels", BCP 14, RFC 2119, March 1997.
 1693 
 1694    [LJ]       Fitzpatrick, B., "LJ NEEDS MOAR SPEED", 10 1999.
 1695 
 1696 Appendix A.  Acknowledgments
 1697 
 1698    Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin
 1699    Sallings, for their work on the memcached server.
 1700 
 1701    Thanks to Sean Chittenden, Jonathan Steinert, Brian Aker, Evan
 1702    Martin, Nathan Neulinger, Eric Hodel, Michael Johnson, Paul Querna,
 1703    Jamie McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg,
 1704    Robin H.  Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean-
 1705    Francois Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris
 1706    Goffinet, Tomash Brechko, and others for their work reporting bugs
 1707    and maintaining memcached client libraries and bindings in many
 1708    languages.
 1709 
 1710 Authors' Addresses
 1711 
 1712    Aaron Stone (editor)
 1713    Six Apart, Ltd.
 1714    548 4th Street
 1715    San Francisco, CA  94107
 1716    USA
 1717 
 1718    Email: aaron@serendipity.palo-alto.ca.us
 1719 
 1720 
 1721    Trond Norbye (editor)
 1722    Sun Microsystems, INC
 1723    Haakon VII g. 7B
 1724    Trondheim  NO-7485 Trondheim
 1725    Norway
 1726 
 1727    Email: trond.norbye@sun.com
 1728 
 1729 
 1730 
 1731 
 1732 
 1733 
 1734 
 1735 
 1736 Stone & Norbye            Expires March 1, 2009                [Page 31]