"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]