"Fossies" - the Fresh Open Source Software Archive

Member "memcached-1.6.15/doc/protocol-binary-range.txt" (30 Mar 2022, 10242 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                                   Aaron Stone, Ed.
    6 Internet-Draft                                           Six Apart, Ltd.
    7 Intended status: Informational                         December 14, 2007
    8 Expires: June 16, 2008
    9 
   10 
   11               Memcache Binary Protocol: Extensions for UDP
   12                       draft-stone-memcache-udp-01
   13 
   14 Abstract
   15 
   16    This memo explains extensions to the memcache binary protocol for use
   17    in a UDP environment.
   18 
   19    Memcache is a high performance key-value cache.  It is intentionally
   20    a dumb cache, optimized for speed only.  Applications using memcache
   21    do not rely on it for data -- a persistent database with guaranteed
   22    reliability is strongly recommended -- but applications can run much
   23    faster when cached data is available in memcache.
   24 
   25 Status of This Memo
   26 
   27    This Internet-Draft is submitted in full conformance with the
   28    provisions of BCP 78 and BCP 79.
   29 
   30    Internet-Drafts are working documents of the Internet Engineering
   31    Task Force (IETF).  Note that other groups may also distribute
   32    working documents as Internet-Drafts.  The list of current Internet-
   33    Drafts is at http://datatracker.ietf.org/drafts/current/.
   34 
   35    Internet-Drafts are draft documents valid for a maximum of six months
   36    and may be updated, replaced, or obsoleted by other documents at any
   37    time.  It is inappropriate to use Internet-Drafts as reference
   38    material or to cite them other than as "work in progress."
   39 
   40    This Internet-Draft will expire on June 16, 2008.
   41 
   42 Copyright Notice
   43 
   44    Copyright (c) 2007 IETF Trust and the persons identified as the
   45    document authors.  All rights reserved.
   46 
   47    This document is subject to BCP 78 and the IETF Trust's Legal
   48    Provisions Relating to IETF Documents
   49    (http://trustee.ietf.org/license-info) in effect on the date of
   50    publication of this document.  Please review these documents
   51    carefully, as they describe your rights and restrictions with respect
   52    to this document.  Code Components extracted from this document must
   53 
   54 
   55 
   56 Aaron Stone               Expires June 16, 2008                 [Page 1]
   57 
   58 Internet-Draft              Memcache Over UDP              December 2007
   59 
   60 
   61    include Simplified BSD License text as described in Section 4.e of
   62    the Trust Legal Provisions and are provided without warranty as
   63    described in the Simplified BSD License.
   64 
   65 Table of Contents
   66 
   67    1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   68      1.1.  Conventions Used In This Document . . . . . . . . . . . .   2
   69    2.  Defined Values  . . . . . . . . . . . . . . . . . . . . . . .   3
   70      2.1.  Magic Byte  . . . . . . . . . . . . . . . . . . . . . . .   3
   71      2.2.  Response Status . . . . . . . . . . . . . . . . . . . . .   3
   72      2.3.  Command Opcodes . . . . . . . . . . . . . . . . . . . . .   3
   73      2.4.  Data Types  . . . . . . . . . . . . . . . . . . . . . . .   3
   74    3.  Commands  . . . . . . . . . . . . . . . . . . . . . . . . . .   3
   75      3.1.  Get Response  . . . . . . . . . . . . . . . . . . . . . .   3
   76      3.2.  Get Range Request . . . . . . . . . . . . . . . . . . . .   4
   77      3.3.  Get Range Response  . . . . . . . . . . . . . . . . . . .   4
   78    4.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
   79    5.  Normative References  . . . . . . . . . . . . . . . . . . . .   5
   80    Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   5
   81 
   82 1.  Introduction
   83 
   84    Memcache is a high performance key-value cache.  It is intentionally
   85    a dumb cache, optimized for speed only.  Applications using memcache
   86    do not rely on it for data -- a persistent database with guaranteed
   87    reliability is strongly recommended -- but applications can run much
   88    faster when cached data is available in memcache.
   89 
   90    Sites may find that, due to their network architecture or application
   91    usage patterns, the stateless [UDP] protocol better suits their
   92    needs.  This document provides extensions and descriptions of use of
   93    the memcache protocol [MEMCACHE] in a UDP environment.
   94 
   95    It is a goal of this document to provide sufficient information in
   96    each UDP packet as to avoid any requirement for statefulness on the
   97    part of the server nor significant caching of outstanding packets on
   98    the part of the client.
   99 
  100 1.1.  Conventions Used In This Document
  101 
  102    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  103    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  104    document are to be interpreted as described in [KEYWORDS].
  105 
  106 
  107 
  108 
  109 
  110 
  111 
  112 Aaron Stone               Expires June 16, 2008                 [Page 2]
  113 
  114 Internet-Draft              Memcache Over UDP              December 2007
  115 
  116 
  117 2.  Defined Values
  118 
  119 2.1.  Magic Byte
  120 
  121    The magic bytes remains the same as in [MEMCACHE].
  122 
  123 2.2.  Response Status
  124 
  125    Additional status values:
  126 
  127    0x0004  Value is larger than a single response packet
  128 
  129 2.3.  Command Opcodes
  130 
  131    Additional opcode values:
  132 
  133    0x0C    Get Range
  134    0x0D    Set Range
  135 
  136 2.4.  Data Types
  137 
  138    There are no new data types in this extension.
  139 
  140 3.  Commands
  141 
  142 3.1.  Get Response
  143 
  144    This section extends the behavior of the Get and GetQ commands as
  145    described in [MEMCACHE].
  146 
  147    When a Get or GetQ request is made via UDP, and the value of the key
  148    for which the request was made is larger than can be placed into a
  149    single UDP packet (noting that the protocol header must also be
  150    counted), a Get Range response packet MUST be sent instead of the Get
  151    response packet.  In this instance:
  152 
  153    1.  The Status field of the response header MUST be 0x0004.
  154    2.  The Offset field of the GetR response extras MUST be 0.
  155    3.  The Length field of the GetR response extras, and the data
  156        contained in the Value field of the packet, SHOULD be the maximum
  157        allowed length of a UDP packet, less the space required by the
  158        header and extras; however it MAY be any amount below this
  159        maximum.
  160    4.  The Total value length field of the response extras MUST be the
  161        actual length of the complete value.
  162 
  163    The client, upon receipt of a Get Range response bearing Status 0x004
  164    and a Message ID corresponding to its Get request, shall then know
  165 
  166 
  167 
  168 Aaron Stone               Expires June 16, 2008                 [Page 3]
  169 
  170 Internet-Draft              Memcache Over UDP              December 2007
  171 
  172 
  173    that it has received only the first portion of the value.  The client
  174    MAY choose to request the remaining portion of the value by sending
  175    one or more Get Range requests.
  176 
  177 3.2.  Get Range Request
  178 
  179    The Get Range request is primarily intended for use over a UDP
  180    transport to request byte ranges of the value for a key.  In the
  181    event that the Data version check fails to match that of the key, an
  182    error MUST be returned.
  183 
  184    Extra data for get range request:
  185 
  186    Byte/     0       |       1       |       2       |       3       |
  187       /              |               |               |               |
  188      |0 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|
  189      +---------------+---------------+---------------+---------------+
  190     0| Flags                                                         |
  191      +---------------+---------------+---------------+---------------+
  192     4| Data version check                                            |
  193      |                                                               |
  194      +---------------+---------------+---------------+---------------+
  195    12| Offset                                                        |
  196      +---------------+---------------+---------------+---------------+
  197    16| Length                                                        |
  198      +---------------+---------------+---------------+---------------+
  199    Total 20 bytes
  200 
  201 3.3.  Get Range Response
  202 
  203    The Get Range request is primarily intended for use over a UDP
  204    transport to indicate the location of the bytes of the value for a
  205    key contained in a given packet.  A client receives enough
  206    information in each Get Range extras to construct an appropriately
  207    sized buffer in its own memory and blindly insert the contents of the
  208    packet at the given byte offset.
  209 
  210 
  211 
  212 
  213 
  214 
  215 
  216 
  217 
  218 
  219 
  220 
  221 
  222 
  223 
  224 Aaron Stone               Expires June 16, 2008                 [Page 4]
  225 
  226 Internet-Draft              Memcache Over UDP              December 2007
  227 
  228 
  229    Extra data for get range response:
  230 
  231    Byte/     0       |       1       |       2       |       3       |
  232       /              |               |               |               |
  233      |0 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|
  234      +---------------+---------------+---------------+---------------+
  235     0| Flags                                                         |
  236      +---------------+---------------+---------------+---------------+
  237     4| Data version check                                            |
  238      |                                                               |
  239      +---------------+---------------+---------------+---------------+
  240    12| Offset                                                        |
  241      +---------------+---------------+---------------+---------------+
  242    16| Length                                                        |
  243      +---------------+---------------+---------------+---------------+
  244    20| Total value length                                            |
  245      +---------------+---------------+---------------+---------------+
  246    Total 24 bytes
  247 
  248 4.  Security Considerations
  249 
  250    This document does not introduce any new security considerations
  251    beyond those discussed in [MEMCACHE].
  252 
  253 5.  Normative References
  254 
  255    [KEYWORDS]
  256               Bradner, S., "Key words for use in RFCs to Indicate
  257               Requirement Levels", BCP 14, RFC 2119, March 1997.
  258 
  259    [MEMCACHE]
  260               Bradner, S., "Key words for use in RFCs to Indicate
  261               Requirement Levels", BCP 14, RFC 2119, March 1997.
  262 
  263    [UDP]      Postel, J., "User Datagram Protocol", STD 6, RFC 768,
  264               August 1980.
  265 
  266 Author's Address
  267 
  268    Aaron Stone (editor)
  269    Six Apart, Ltd.
  270    548 4th Street
  271    San Francisco, CA  94107
  272    USA
  273 
  274    Email: aaron@serendipity.palo-alto.ca.us
  275 
  276 
  277 
  278 
  279 
  280 Aaron Stone               Expires June 16, 2008                 [Page 5]