1
2
3
4
5Network Working Group                                   Aaron Stone, Ed.
6Internet-Draft                                           Six Apart, Ltd.
7Intended status: Informational                         December 14, 2007
8Expires: June 16, 2008
9
10
11              Memcache Binary Protocol: Extensions for UDP
12                      draft-stone-memcache-udp-01
13
14Abstract
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
25Status 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
42Copyright 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
56Aaron Stone               Expires June 16, 2008                 [Page 1]
57
58Internet-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
65Table 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
821.  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
1001.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
112Aaron Stone               Expires June 16, 2008                 [Page 2]
113
114Internet-Draft              Memcache Over UDP              December 2007
115
116
1172.  Defined Values
118
1192.1.  Magic Byte
120
121   The magic bytes remains the same as in [MEMCACHE].
122
1232.2.  Response Status
124
125   Additional status values:
126
127   0x0004  Value is larger than a single response packet
128
1292.3.  Command Opcodes
130
131   Additional opcode values:
132
133   0x0C    Get Range
134   0x0D    Set Range
135
1362.4.  Data Types
137
138   There are no new data types in this extension.
139
1403.  Commands
141
1423.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
168Aaron Stone               Expires June 16, 2008                 [Page 3]
169
170Internet-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
1773.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
2013.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
224Aaron Stone               Expires June 16, 2008                 [Page 4]
225
226Internet-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
2484.  Security Considerations
249
250   This document does not introduce any new security considerations
251   beyond those discussed in [MEMCACHE].
252
2535.  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
266Author'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: [email protected]
275
276
277
278
279
280Aaron Stone               Expires June 16, 2008                 [Page 5]
281