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