Changeset 687

Show
Ignore:
Timestamp:
12/19/07 09:27:19 (1 year ago)
Author:
astone
Message:

Some minor updates to the base binary protocol document.
First pass at a UDP / byte range extension document.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • branches/binary/server/doc/binary-protocol-plan-v2.txt

    r684 r687  
    6969     3.4.  Data Types . . . . . . . . . . . . . . . . . . . . . . . .  6 
    7070   4.  Commands . . . . . . . . . . . . . . . . . . . . . . . . . . .  6 
    71      4.1.  get/getq . . . . . . . . . . . . . . . . . . . . . . . . .  6 
    72      4.2.  delete . . . . . . . . . . . . . . . . . . . . . . . . . .  7 
    73      4.3.  set/add/replace  . . . . . . . . . . . . . . . . . . . . .  7 
     71     4.1.  Get, Get Quietly . . . . . . . . . . . . . . . . . . . . .  6 
     72     4.2.  Delete . . . . . . . . . . . . . . . . . . . . . . . . . .  7 
     73     4.3.  Set, Add, Replace . . . . . . . . . . . . . . . . . . . .  7 
    7474     4.4.  noop . . . . . . . . . . . . . . . . . . . . . . . . . . .  8 
    75      4.5.  incr/decr  . . . . . . . . . . . . . . . . . . . . . . . .  8 
     75     4.5.  Increment, Decrement . . . . . . . . . . . . . . . . . . .  8 
    7676   5.  Example Session  . . . . . . . . . . . . . . . . . . . . . . .  9 
    7777   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 13 
    …… 
    123123 
    124124   Memcache was originally written to make LiveJournal [LJ] go faster. 
     125   It now powers all of the fastest web sites that you love. 
    125126 
    1261271.1.  Conventions Used In This Document 
    127128 
    128    FIXME: Use RFC 2119 [KEYWORDS] because otherwise we'll never agree on 
    129    what MUST means. 
     129   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 
     130   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 
     131   document are to be interpreted as described in [KEYWORDS]. 
    130132 
    131133 
    …… 
    154156       +---------------+---------------+---------------+---------------+ 
    155157      Total 16 bytes 
    156  
    157  
    158158 
    159159 
    …… 
    286286   0x0A    No-op 
    287287   0x0B    Version 
     288   0x0C    GetR 
     289   0x0D    SetR 
    288290 
    2892913.4.  Data Types 
    …… 
    291293   Possible values of the one-byte field: 
    292294   0x00    Raw bytes 
    293    0x01    My name is what? 
    294    0x02    My name is Sean! 
    295295 
    296296 
    2972974.  Commands 
    298298 
    299 4.1.  get/getq 
     2994.1.  Get, Get Quietly 
    300300 
    301301      MUST have extras. 
    …… 
    343343   can send 'n' getqs, followed by an 'echo' or 'noop' command. 
    344344 
    345 4.2.  delete 
     3454.2.  Delete 
    346346 
    347347      MAY have extras (FIXME: Is it OK to issue a delete without 
    …… 
    373373   within its purview). 
    374374 
    375 4.3.  set/add/replace 
     3754.3.  Set, Add, Replace 
    376376 
    377377      MUST have extras. 
    …… 
    409409     Total 16 bytes 
    410410 
    411    If the Data version check is present and nonzero, a set will succeed 
    412    iff the value exists and has a version identifier identical to the 
    413    provided value. 
     411   If the Data Version Check is present and nonzero, the set MUST 
     412   succeed if the key exists and has a version identifier identical to 
     413   the provided value, and MUST NOT succeed if the key does not exist or 
     414   has a different version identifier.  The set response packet will 
     415   include the same values in all three fields. 
     416 
     417   If the Data Version Check is zero, the set MUST succeed 
     418   unconditionally.  The set response packet will include idential 
     419   values for flags and expiration, and a new value for Data Version 
     420   Check, which the client SHOULD keep track of. 
     421 
     422   The key MAY be reserved according to Section 4.2, causing the set to 
     423   fail. 
    414424 
    4154254.4.  noop 
    …… 
    421431   Used as a keep alive.  Flushes outstanding getq's. 
    422432 
    423 4.5.  incr/decr 
     4334.5.  Increment, Decrement 
    424434 
    425435      MUST have extras. 
    …… 
    430440   o  8 byte initial value (unsigned) 
    431441   o  4 byte expiration time 
    432  
    433  
    434  
    435  
    436  
    437  
    438  
    439  
    440  
    441  
    442442 
    443443 
    …… 
    6766766.  Security Considerations 
    677677 
    678    Memcache has no authentication or security layers and is intended 
    679    strictly for use on closed, protected, back-end networks within a 
    680    single data center, within a single cluster of servers, or even on a 
    681    single host, providing shared caching for multiple applications. 
    682    Memcache should not ever be made available on a public network. 
     678   Memcache has no authentication or security layers whatsoever.  It is 
     679   RECOMMENDED that memcache be deployed strictly on closed, protected, 
     680   back-end networks within a single data center, within a single 
     681   cluster of servers, or even on a single host, providing shared 
     682   caching for multiple applications.  Memcache MUST NOT be made 
     683   available on a public network. 
    683684 
    684685 
    6856867.  Normative References 
    686687 
    687    [LJ]   Danga Interactive, "LJ NEEDS MOAR SPEED", 10 1999. 
    688  
    689    [UDP]  Postel, J., "User Datagram Protocol", STD 6, RFC 768, 
    690           August 1980. 
     688   [KEYWORDS] 
     689              Bradner, S., "Key words for use in RFCs to Indicate 
     690              Requirement Levels", BCP 14, RFC 2119, March 1997. 
     691 
     692   [LJ]       Danga Interactive, "LJ NEEDS MOAR SPEED", 10 1999. 
     693 
     694   [UDP]      Postel, J., "User Datagram Protocol", STD 6, RFC 768, 
     695              August 1980. 
    691696 
    692697 
    …… 
    700705   Jamie McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg, 
    701706   Robin H. Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean- 
    702    Francois Bustarret, Paul G, Paul Lindner, Dormando, Dustin Sallings, 
    703    Chris Goffinet, Tomash Brechko, and others for their work reporting 
    704    bugs and maintaining memcached client libraries and bindings in many 
     707   Francois Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris 
     708   Goffinet, Tomash Brechko, and others for their work reporting bugs 
     709   and maintaining memcached client libraries and bindings in many 
    705710   languages. 
    706  
    707    The author takes no credit for the protocol described in this 
    708    document, though certainly any errors in transcription or in prose 
    709    are his. 
    710711 
    711712 
    …… 
    724725 
    725726 
    726  
    727727Aaron Stone               Expires June 16, 2008                [Page 13] 
    728728  

  • branches/binary/server/doc/binary-protocol-plan-v2.xml

    r684 r687  
    6060      <t> 
    6161      Memcache was originally written to make <xref target="LJ">LiveJournal</xref> go faster. 
     62      It now powers all of the fastest web sites that you love. 
    6263      </t> 
    6364      <section anchor="conventions" title="Conventions Used In This Document"> 
    64         <t> 
    65         FIXME: Use RFC 2119 [KEYWORDS] because otherwise we'll never agree on what MUST means. 
     65        <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 
     66        "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 
     67        document are to be interpreted as described in <xref target="KEYWORDS"/>. 
    6668        </t> 
    6769      </section> 
    …… 
    153155    </section> 
    154156 
    155     <section title="Defined Values"> 
    156       <section title="Magic Byte"> 
     157    <section anchor="values" title="Defined Values"> 
     158      <section anchor="value-magic" title="Magic Byte"> 
    157159        <t> 
    158160        <list hangIndent="8" style="hanging"> 
    …… 
    187189      </section> 
    188190 
    189       <section title="Response Status"> 
     191      <section anchor="value-status" title="Response Status"> 
    190192        <t> 
    191193        Possible values of this two-byte field: 
    …… 
    199201      </section> 
    200202 
    201       <section title="Command Opcodes"> 
     203      <section anchor="value-opcodes" title="Command Opcodes"> 
    202204        <t> 
    203205        Possible values of the one-byte field: 
    …… 
    219221      </section> 
    220222 
    221       <section title="Data Types"> 
     223      <section anchor="value-types" title="Data Types"> 
    222224        <t> 
    223225        Possible values of the one-byte field: 
    224226        <list hangIndent="8" style="hanging"> 
    225227          <t hangText="0x00">Raw bytes</t> 
    226           <t hangText="0x01">My name is what?</t> 
    227           <t hangText="0x02">My name is Sean!</t> 
    228228        </list> 
    229229        </t> 
    …… 
    232232 
    233233    <section title="Commands"> 
    234       <section title="get/getq"> 
     234      <section anchor="command-get" title="Get, Get Quietly"> 
    235235        <t> 
    236236        <list style="empty"> 
    …… 
    291291      </section> 
    292292 
    293       <section title="delete"> 
     293      <section anchor="command-delete" title="Delete"> 
    294294        <t> 
    295295        <list style="empty"> 
    …… 
    332332      </section> 
    333333 
    334       <section title="set/add/replace"> 
     334      <section anchor="command-set" title="Set, Add, Replace"> 
    335335        <t> 
    336336        <list style="empty"> 
    …… 
    369369 
    370370        <t> 
    371         If the Data version check is present and nonzero, a set will succeed iff the 
    372         value exists and has a version identifier identical to the provided value. 
    373         </t> 
     371        If the Data Version Check is present and nonzero, the set MUST succeed if the 
     372        key exists and has a version identifier identical to the provided value, and 
     373        MUST NOT succeed if the key does not exist or has a different version identifier. 
     374        The set response packet will include the same values in all three fields. 
     375        </t> 
     376 
     377        <t> 
     378        If the Data Version Check is zero, the set MUST succeed unconditionally. 
     379        The set response packet will include idential values for flags and expiration, 
     380        and a new value for Data Version Check, which the client SHOULD keep track of. 
     381        </t> 
     382 
     383        <t> 
     384        The key MAY be reserved according to <xref target="command-delete"/>, 
     385        causing the set to fail. 
     386        </t> 
    374387      </section> 
    375388 
    …… 
    388401      </section> 
    389402 
    390       <section title="incr/decr"> 
     403      <section anchor="command-incr" title="Increment, Decrement"> 
    391404        <t> 
    392405        <list style="empty"> 
    …… 
    589602    </section> 
    590603 
    591     <section title="Security Considerations"> 
    592       <t> 
    593       Memcache has no authentication or security layers and is intended 
    594       strictly for use on closed, protected, back-end networks within a 
    595       single data center, within a single cluster of servers, or even on 
    596       a single host, providing shared caching for multiple applications. 
    597       Memcache should not ever be made available on a public network. 
     604    <section anchor="security" title="Security Considerations"> 
     605      <t> 
     606      Memcache has no authentication or security layers whatsoever.  It is 
     607      RECOMMENDED that memcache be deployed strictly on closed, protected, 
     608      back-end networks within a single data center, within a single cluster of 
     609      servers, or even on a single host, providing shared caching for multiple 
     610      applications. Memcache MUST NOT be made available on a public network. 
    598611      </t> 
    599612    </section> 
    …… 
    616629      </reference> 
    617630      <dwdrfc-ref anchor='UDP' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.0768.xml'/> 
     631      <dwdrfc-ref anchor='KEYWORDS' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/> 
    618632    </references> 
    619633 
    620634    <section anchor="acknowledgments" title="Acknowledgments"> 
    621635      <t> 
    622       Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin Sallings, 
    623       for their work on the memcached server. 
     636      Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin 
     637      Sallings, for their work on the memcached server. 
    624638      </t> 
    625639       
    …… 
    629643      McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg, Robin H. 
    630644      Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean-Francois 
    631       Bustarret, Paul G, Paul Lindner, Dormando, Dustin Sallings, Chris 
    632       Goffinet, Tomash Brechko, and others for their work reporting bugs and 
    633       maintaining memcached client libraries and bindings in many languages. 
    634       </t> 
    635  
    636       <t> 
    637       The author takes no credit for the protocol described in this document, 
    638       though certainly any errors in transcription or in prose are his. 
     645      Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris Goffinet, Tomash 
     646      Brechko, and others for their work reporting bugs and maintaining 
     647      memcached client libraries and bindings in many languages. 
    639648      </t> 
    640649    </section>