--- /dev/null
+<?xml version="1.0" encoding="US-ASCII"?>
+<!DOCTYPE rfc SYSTEM "xml2rfc/rfc2629.dtd">
+<?xml-stylesheet type='text/xsl' href='xml2rfc/rfc2629.xslt'?>
+<?rfc toc="yes"?>
+<?rfc strict="yes"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes" ?>
+<?rfc compact="yes" ?>
+<?rfc subcompact="yes" ?>
+<rfc category="info" docName="draft-stone-memcache-udp-01" ipr="none">
+
+ <front>
+
+ <title abbrev="Memcache Over UDP"> Memcache Binary Protocol: Extensions for UDP </title>
+
+ <author fullname="Aaron Stone" surname="Aaron Stone" role="editor">
+ <organization>Six Apart, Ltd.</organization>
+ <address>
+ <postal>
+ <street>548 4th Street</street>
+ <city>San Francisco</city>
+ <region>CA</region>
+ <code>94107</code>
+ <country>USA</country>
+ </postal>
+ <email>aaron@serendipity.palo-alto.ca.us</email>
+ </address>
+ </author>
+
+ <date day="14" month="December" year="2007" />
+
+ <area>Applications</area>
+
+ <keyword>memcache memcached cache udp</keyword>
+
+ <abstract>
+ <t>
+ This memo explains extensions to the memcache binary protocol for use in a UDP environment.
+ </t>
+
+ <t>
+ Memcache is a high performance key-value cache. It is intentionally a
+ dumb cache, optimized for speed only. Applications using memcache do
+ not rely on it for data -- a persistent database with guaranteed reliability
+ is strongly recommended -- but applications can run much faster when
+ cached data is available in memcache.
+ </t>
+ </abstract>
+ </front>
+
+ <middle>
+ <section anchor="introduction" title="Introduction">
+ <t>
+ Memcache is a high performance key-value cache. It is intentionally a
+ dumb cache, optimized for speed only. Applications using memcache do
+ not rely on it for data -- a persistent database with guaranteed reliability
+ is strongly recommended -- but applications can run much faster when
+ cached data is available in memcache.
+ </t>
+ <t>
+ Sites may find that, due to their network architecture or application usage patterns,
+ the stateless <xref target="UDP"/> protocol better suits their needs. This document
+ provides extensions and descriptions of use of the <xref target="MEMCACHE">memcache protocol</xref>
+ in a UDP environment.
+ </t>
+ <t>
+ It is a goal of this document to provide sufficient information in each UDP packet
+ as to avoid any requirement for statefulness on the part of the server nor significant
+ caching of outstanding packets on the part of the client.
+ </t>
+ <section anchor="conventions" title="Conventions Used In This Document">
+ <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in <xref target="KEYWORDS"/>.
+ </t>
+ </section>
+ </section>
+
+ <section anchor="values" title="Defined Values">
+ <section anchor="value-magic" title="Magic Byte">
+ <t>
+ The magic bytes remains the same as in <xref target="MEMCACHE"/>.
+ </t>
+ </section>
+
+ <section anchor="value-status" title="Response Status">
+ <t>
+ Additional status values:
+ <list hangIndent="8" style="hanging">
+ <t hangText="0x0004">Value is larger than a single response packet</t>
+ </list>
+ </t>
+ </section>
+
+ <section anchor="value-opcodes" title="Command Opcodes">
+ <t>
+ Additional opcode values:
+ <list hangIndent="8" style="hanging">
+ <t hangText="0x0C">Get Range</t>
+ <t hangText="0x0D">Set Range</t>
+ </list>
+ </t>
+ </section>
+
+ <section anchor="value-types" title="Data Types">
+ <t>
+ There are no new data types in this extension.
+ </t>
+ </section>
+ </section>
+
+ <section anchor="commands" title="Commands">
+
+ <section anchor="command-get" title="Get Response">
+ <t>
+ This section extends the behavior of the Get and GetQ commands as described in
+ <xref target="MEMCACHE" x:sec="command-get"/>.
+ </t>
+
+ <t>
+ When a Get or GetQ request is made via UDP, and the value of the key for which
+ the request was made is larger than can be placed into a single UDP packet (noting
+ that the protocol header must also be counted), a Get Range response packet
+ MUST be sent instead of the Get response packet. In this instance:
+ <list style="numbers">
+ <t>The Status field of the response header MUST be 0x0004.</t>
+ <t>The Offset field of the GetR response extras MUST be 0.</t>
+ <t>The Length field of the GetR response extras, and the data contained in
+ the Value field of the packet, SHOULD be the maximum
+ allowed length of a UDP packet, less the space required by the header
+ and extras; however it MAY be any amount below this maximum.</t>
+ <t>The Total value length field of the response extras MUST be the
+ actual length of the complete value.</t>
+ </list>
+ </t>
+
+ <t>
+ The client, upon receipt of a Get Range response bearing Status 0x004
+ and a Message ID corresponding to its Get request, shall then know that
+ it has received only the first portion of the value. The client MAY choose
+ to request the remaining portion of the value by sending one or more Get Range requests.
+ </t>
+ </section>
+
+ <section anchor="command-getr-request" title="Get Range Request">
+ <t>
+ The Get Range request is primarily intended for use over a UDP transport
+ to request byte ranges of the value for a key. In the event that the Data version
+ check fails to match that of the key, an error MUST be returned.
+ </t>
+ <t>
+ <figure>
+ <preamble>Extra data for get range request:</preamble>
+ <artwork>
+Byte/ 0 | 1 | 2 | 3 |
+ / | | | |
+ |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+ +---------------+---------------+---------------+---------------+
+ 0| Flags |
+ +---------------+---------------+---------------+---------------+
+ 4| Data version check |
+ | |
+ +---------------+---------------+---------------+---------------+
+12| Offset |
+ +---------------+---------------+---------------+---------------+
+16| Length |
+ +---------------+---------------+---------------+---------------+
+Total 20 bytes
+ </artwork></figure>
+ </t>
+ </section>
+
+ <section anchor="command-getr-response" title="Get Range Response">
+ <t>
+ The Get Range request is primarily intended for use over a UDP transport
+ to indicate the location of the bytes of the value for a key contained in
+ a given packet. A client receives enough information in each Get Range
+ extras to construct an appropriately sized buffer in its own memory and
+ blindly insert the contents of the packet at the given byte offset.
+ </t>
+ <t>
+ <figure>
+ <preamble>Extra data for get range response:</preamble>
+ <artwork>
+Byte/ 0 | 1 | 2 | 3 |
+ / | | | |
+ |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+ +---------------+---------------+---------------+---------------+
+ 0| Flags |
+ +---------------+---------------+---------------+---------------+
+ 4| Data version check |
+ | |
+ +---------------+---------------+---------------+---------------+
+12| Offset |
+ +---------------+---------------+---------------+---------------+
+16| Length |
+ +---------------+---------------+---------------+---------------+
+20| Total value length |
+ +---------------+---------------+---------------+---------------+
+Total 24 bytes
+ </artwork></figure>
+ </t>
+ </section>
+
+ </section>
+
+ <section anchor="security" title="Security Considerations">
+ <t>
+ This document does not introduce any new security considerations
+ beyond those discussed in <xref target="MEMCACHE" x:sec="security"/>.
+ </t>
+ </section>
+
+ </middle>
+
+ <back>
+ <references title="Normative References">
+ <dwdrfc-ref anchor='UDP' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.0768.xml'/>
+ <dwdrfc-ref anchor='KEYWORDS' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/>
+ <!-- FIXME: Get a draft reference for the base document. -->
+ <dwdrfc-ref anchor='MEMCACHE' src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/>
+ </references>
+ </back>
+
+</rfc>
+
projects / awesomized / libmemcached / blobdiff