Navigation

← Previous Changeset
Next Changeset →

Changeset 684

Timestamp:

12/16/07 06:06:15 (1 year ago)

Author:

astone

Message:

Updated binary protocol docs.

Files:

branches/binary/server/doc/binary-protocol-plan-v2.txt (modified) (7 diffs)
branches/binary/server/doc/binary-protocol-plan-v2.xml (modified) (11 diffs)

Legend:

: Unmodified
: Added
: Removed
: Modified
: Copied
: Moved

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

r683	r684
60	60	Table of Contents
61	61
62		1. Introduction ~~. . . . . . . . . . . . . . . . . . . . . . . . .~~ 3
63		1.1. Conventions ~~. . . . . . . . . . . . . . . . . . . . . . . .~~ 3
64		2. Packet ~~formats . . . . . . . . . . . . . . . . . . . . . . . .~~ 3
65		3. ~~Magic values . . . . . . . . . . . . . . . . . . . . . . . . . 4~~
66		~~4. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . .~~ 5
67		~~4.1. get/getq . . . . . . . . . . . . . . . . . . . . . . . . .~~ 5
68		~~4.2. delete . . . . . . . . . . . . . . . . . . . . . . . . . .~~ 5
69		~~4.3. set/add/replace . . . . . . . . . . . . . . . . . . . . . .~~ 6
70		~~4.4. noop . . . . . . . . . . . . . . . . . . . . . . . . . . .~~ 6
71		4.~~5. incr/decr . . . . . . . . . . . . . . . . . . . . . . . . .~~ 6
72		~~5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6~~
73		~~6. Normative References . . . . . . . . . . . . . . . . . . . . .~~ 7
74		~~Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 7~~
75		~~Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 7~~
76
77
78
79
80
	62	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
	63	1.1. Conventions Used In This Document . . . . . . . . . . . . 3
	64	2. Packet Structure . . . . . . . . . . . . . . . . . . . . . . . 3
	65	3. Defined Values . . . . . . . . . . . . . . . . . . . . . . . . 5
	66	3.1. Magic Byte . . . . . . . . . . . . . . . . . . . . . . . . 5
	67	3.2. Response Status . . . . . . . . . . . . . . . . . . . . . 5
	68	3.3. Command Opcodes . . . . . . . . . . . . . . . . . . . . . 5
	69	3.4. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6
	70	4. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
	71	4.1. get/getq . . . . . . . . . . . . . . . . . . . . . . . . . 6
	72	4.2. delete . . . . . . . . . . . . . . . . . . . . . . . . . . 7
	73	4.3. set/add/replace . . . . . . . . . . . . . . . . . . . . . 7
	74	4.4. noop . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
	75	4.5. incr/decr . . . . . . . . . . . . . . . . . . . . . . . . 8
	76	5. Example Session . . . . . . . . . . . . . . . . . . . . . . . 9
	77	6. Security Considerations . . . . . . . . . . . . . . . . . . . 13
	78	7. Normative References . . . . . . . . . . . . . . . . . . . . . 13
	79	Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 13
	80	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13
81	81
82	82
…	…
124	124	Memcache was originally written to make LiveJournal [LJ] go faster.
125	125
126		1.1. Conventions
127
128		Bits run across the top. Period (.) represent the start of each byte
129		(bit 0 in that byte, so to speak). The characters -, +, \| are used
130		for Ascii art. Number of bits in each field are in parens. Numbers
131		on the left side are helpful for counting four byte word lines in the
132		packet. All numbers are in network byte order (big endian).
133
134
135		2. Packet formats
	126	1.1. Conventions Used In This Document
	127
	128	FIXME: Use RFC 2119 [KEYWORDS] because otherwise we'll never agree on
	129	what MUST means.
	130
	131
	132	2. Packet Structure
	133
	134	General format of a packet:
	135
	136	Byte/ 0 \| 1 \| 2 \| 3 \|
	137	/ \| \| \| \|
	138	\|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\|
	139	+---------------+---------------+---------------+---------------+
	140	0/ HEADER /
	141	/ /
	142	/ /
	143	/ /
	144	+---------------+---------------+---------------+---------------+
	145	16/ COMMAND-SPECIFIC EXTRAS (as needed) /
	146	+/ (note length in th extras length header field) /
	147	+---------------+---------------+---------------+---------------+
	148	m/ Key (as needed) /
	149	+/ (note length in key length header field) /
	150	+---------------+---------------+---------------+---------------+
	151	n/ Value (as needed) /
	152	+/ (note length is total body length header field, minus /
	153	+/ sum of the extras and key length body fields) /
	154	+---------------+---------------+---------------+---------------+
	155	Total 16 bytes
	156
	157
	158
	159
	160
	161
	162
	163
	164
	165
	166
	167	Aaron Stone Expires June 16, 2008 [Page 3]
	168
	169	Internet-Draft Memcache Binary Protocol December 2007
	170
136	171
137	172	Request header:
138	173
139		+.1234567.1234567.1234567.1234567+
140		1 \|Mag (8) Cmd (8) Key len (16) \|
141		2 \|Len (8) Type(8) Reserved (16) \|
142		3 \|Total body length (32) \|
143		4 \|Opaque key (32) \|
144		+.1234567.1234567.1234567.1234567+
	174	Byte/ 0 \| 1 \| 2 \| 3 \|
	175	/ \| \| \| \|
	176	\|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\|
	177	+---------------+---------------+---------------+---------------+
	178	0\| Magic \| Opcode \| Key length \|
	179	+---------------+---------------+---------------+---------------+
	180	4\| Extras length \| Data type \| Reserved \|
	181	+---------------+---------------+---------------+---------------+
	182	8\| Total body length \|
	183	+---------------+---------------+---------------+---------------+
	184	12\| Message ID \|
	185	+---------------+---------------+---------------+---------------+
	186	Total 16 bytes
145	187
146	188	Response header:
147	189
148		+.1234567.1234567.1234567.1234567+
149		1 \|Mag (8) Cmd (8) Stat(8) Resvd(8)\| ***FIXME: see below
150		2 \|Len (8) Type(8) Reserved(16) \|
151		3 \|Total body length (32) \|
152		4 \|Opaque key (32) \|
153		+.1234567.1234567.1234567.1234567+
154
155		The short keywords in the header format expand as follows:
156
157		Mag Magic number.
158
159		Cmd Command code.
160
161
162
163
164
165
166
167		Aaron Stone Expires June 16, 2008 [Page 3]
168
169		Internet-Draft Memcache Binary Protocol December 2007
170
171
172		Key length Length in bytes of the text key that follows the command
173		extras.
174
175		Stat Status of the response (non-zero on error).
176
177		Resvd FIXME: Dustin, please remind me what this is?
178
179		Len Length in bytes of the command extras.
180
181		Type Reserved for future use (Sean is using this soon).
182
183		Reserved Really reserved for future use (up for grabs).
184
185		Total body length Length in bytes of extra + key + value.
186
187		Opaque key Will be copied back to you in the response.
188
189		General format of a packet:
190
191		+.1234567.1234567.1234567.1234567+
192		1 \|HEADER (16 bytes, per above) \|
193		2 \| \|
194		3 \| \|
195		4 \| \|
196		+.1234567.1234567.1234567.1234567+
197		\|Command-specific stuff \|
198		\| (note length in byte 5) \|
199		+.1234567.1234567.1234567.1234567+
200		\|Key \|
201		\| (note length in bytes 3-4) \|
202		\| (never present in responses) \|
203		+.1234567.1234567.1234567.1234567+
204		\|Value \|
205		\| (note length of bytes 9-12, \|
206		\| minus extra length, \|
207		\| minus key length) \|
208		+.1234567.1234567.1234567.1234567+
209
210
211		3. Magic values
	190	Byte/ 0 \| 1 \| 2 \| 3 \|
	191	/ \| \| \| \|
	192	\|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\|
	193	+---------------+---------------+---------------+---------------+
	194	0\| Magic \| Opcode \| Status \|
	195	+---------------+---------------+---------------+---------------+
	196	4\| Extras length \| Data type \| Reserved \|
	197	+---------------+---------------+---------------+---------------+
	198	8\| Total body length \|
	199	+---------------+---------------+---------------+---------------+
	200	12\| Message ID \|
	201	+---------------+---------------+---------------+---------------+
	202	Total 16 bytes
	203
	204	Header fields:
	205	Magic Magic number.
	206	Opcode Command code.
	207	Key length Length in bytes of the text key that follows the
	208	command extras.
	209	Status Status of the response (non-zero on error).
	210	Extras length Length in bytes of the command extras.
	211	Data type Reserved for future use (Sean is using this
	212	soon).
	213	Reserved Really reserved for future use (up for grabs).
	214	Total body length Length in bytes of extra + key + value.
	215	Message ID Will be copied back to you in the response.
	216	FIXME: Can this be used to organize [UDP]
	217	packets?
	218
	219
	220
	221
	222
	223	Aaron Stone Expires June 16, 2008 [Page 4]
	224
	225	Internet-Draft Memcache Binary Protocol December 2007
	226
	227
	228	3. Defined Values
	229
	230	3.1. Magic Byte
	231
	232	0x80 Request packet for this protocol version
	233	0x81 Response packet for this protocol version
212	234
213	235	Magic byte / version. For each version of the protocol, we'll use a
214	236	different request/reponse value pair. This is useful for protocol
215	237	analyzers to know what a packet is in isolation from which direction
216		it is moving.
	238	it is moving. Note that it is common to run a memcached instance on
	239	a host that also runs an application server. Such a host will both
	240	send and receive memcache packets.
217	241
218	242	The version should hopefully correspond only to different meanings of
219	243	the command byte. In an ideal world, we will not change the header
220
221
222
223		~~Aaron Stone Expires June 16, 2008 [Page 4]~~
224
225		~~Internet-Draft Memcache Binary Protocol December 2007~~
226
227
228	244	format. As reserved bytes are given defined meaning, the protocol
229	245	version / magic byte values should be incremented.
230	246
231		Magic byte values will begin at 0x80 and go up from there.
	247	Traffic analysis tools are encouraged to identify memcache packets
	248	and provide detailed interpretation if the magic bytes are recognized
	249	and otherwise to provide a generic breakdown of the packet. Note
	250	that the key and value positions can always be identified even if the
	251	magic byte or command opcode are not recognized.
	252
	253	3.2. Response Status
	254
	255	Possible values of this two-byte field:
	256	0x0000 No error
	257	0x0081 Unknown command
	258	0x0001 Key not found
	259	0x0002 Key exists
	260
	261	3.3. Command Opcodes
	262
	263	Possible values of the one-byte field:
	264	0x00 Get
	265	0x01 Set
	266	0x02 Add
	267	0x03 Replace
	268	0x04 Delete
	269	0x05 Increment
	270	0x06 Decrement
	271	0x07 Quit
	272
	273
	274
	275
	276
	277
	278
	279	Aaron Stone Expires June 16, 2008 [Page 5]
	280
	281	Internet-Draft Memcache Binary Protocol December 2007
	282
	283
	284	0x08 Flush
	285	0x09 GetQ
	286	0x0A No-op
	287	0x0B Version
	288
	289	3.4. Data Types
	290
	291	Possible values of the one-byte field:
	292	0x00 Raw bytes
	293	0x01 My name is what?
	294	0x02 My name is Sean!
232	295
233	296
…	…
235	298
236	299	4.1. get/getq
	300
	301	MUST have extras.
	302	MUST have key.
	303	MUST NOT have value.
	304
	305	o 4 byte flags
	306	o 8 byte data version check
	307
	308	Extra data for get/getq:
	309
	310	Byte/ 0 \| 1 \| 2 \| 3 \|
	311	/ \| \| \| \|
	312	\|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\|
	313	+---------------+---------------+---------------+---------------+
	314	0\| Flags \|
	315	+---------------+---------------+---------------+---------------+
	316	4\| Data version check \|
	317	\| \|
	318	+---------------+---------------+---------------+---------------+
	319	Total 12 bytes
237	320
238	321	The get command gets a single key. The getq command is both mum on
…	…
247	330	network roundtrips!) as n pipelined requests, the first n-1 being
248	331	getq, the last being a regular get. that way you're guaranteed to get
	332
	333
	334
	335	Aaron Stone Expires June 16, 2008 [Page 6]
	336
	337	Internet-Draft Memcache Binary Protocol December 2007
	338
	339
249	340	a response, and you know when the server's done. you can also do the
250	341	naive thing and send n pipelined gets, but then you could potentially
…	…
252	343	can send 'n' getqs, followed by an 'echo' or 'noop' command.
253	344
	345	4.2. delete
	346
	347	MAY have extras (FIXME: Is it OK to issue a delete without
	348	extras?).
	349	MUST have key.
	350	MUST NOT have value.
	351
	352	o 4 byte expiration time
	353
	354	Extra data for delete:
	355
	356	Byte/ 0 \| 1 \| 2 \| 3 \|
	357	/ \| \| \| \|
	358	\|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\|
	359	+---------------+---------------+---------------+---------------+
	360	0\| Expiration \|
	361	+---------------+---------------+---------------+---------------+
	362	Total 4 bytes
	363
	364	When allows you to 'reserve' a key. When 'when' is set for, say, ten
	365	seconds in the future, the 'add' and 'replace' operations will fail
	366	for that key until ten seconds from now. The 'set' operation will
	367	succeed regardless of any reserved deletes. FIXME: Is the
	368	reservation also cancelled? Say there's a delete with a 10 second
	369	hold. Two seconds later, an 'add' is received. It fails. Two
	370	second later, a 'set' is received. Is succeeds unconditionally.
	371	What if another 'add' is received two more seconds later (a total of
	372	six seconds since the original 10 second delete-hold, thus still
	373	within its purview).
	374
	375	4.3. set/add/replace
	376
	377	MUST have extras.
	378	MUST have key.
	379	MUST have value.
	380
254	381	o 4 byte flags
255
256		~~o 8 byte CAS ID~~
257
258		~~Extra data for get/getq:~~
259
260		~~+.1234567.1234567.1234567.1234567+~~
261		~~1 \|Flags (32) \|~~
262		~~2 \|CAS ID (64) \|~~
263		~~3 \| \|~~
264		~~+.1234567.1234567.1234567.1234567+~~
265
266		~~4.2. delete~~
267
268		~~When allows you to 'reserve' a key. When 'when' is set for, say, ten~~
269		~~seconds in the future, all 'set's on that key will fail until ten~~
270		~~seconds from now.~~
271
272		~~o 4 byte 'when' time~~
273
274
275
276
277
278
279		~~Aaron Stone Expires June 16, 2008 [Page 5]~~
280
281		~~Internet-Draft Memcache Binary Protocol December 2007~~
282
283
284		~~Extra data for delete:~~
285
286		~~+.1234567.1234567.1234567.1234567+~~
287		~~1 \|When (32) \|~~
288		~~+.1234567.1234567.1234567.1234567+~~
289
290		~~4.3. set/add/replace~~
291
292		~~o 4 byte flags~~
293
294	382	o 4 byte expiration time
295
296		o 8 byte CAS ID
	383	o 8 byte data version check
	384
	385
	386
	387
	388
	389
	390
	391	Aaron Stone Expires June 16, 2008 [Page 7]
	392
	393	Internet-Draft Memcache Binary Protocol December 2007
	394
297	395
298	396	Extra data for set/add/replace:
299	397
300		+.1234567.1234567.1234567.1234567+
301		1 \|Flags (32) \|
302		2 \|Expiration (32) \|
303		3 \|CAS ID (64) \|
304		4 \| \|
305		+.1234567.1234567.1234567.1234567+
	398	Byte/ 0 \| 1 \| 2 \| 3 \|
	399	/ \| \| \| \|
	400	\|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\|
	401	+---------------+---------------+---------------+---------------+
	402	0\| Flags \|
	403	+---------------+---------------+---------------+---------------+
	404	4\| Expiration \|
	405	+---------------+---------------+---------------+---------------+
	406	8\| Data version check \|
	407	\| \|
	408	+---------------+---------------+---------------+---------------+
	409	Total 16 bytes
	410
	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.
306	414
307	415	4.4. noop
308	416
309		Used as a keep alive. Flushes outstanding getq's. Should not have
310		any command extra data. Must not have a key.
	417	MUST NOT have extras.
	418	MUST NOT have key.
	419	MUST NOT have value.
	420
	421	Used as a keep alive. Flushes outstanding getq's.
311	422
312	423	4.5. incr/decr
313	424
	425	MUST have extras.
	426	MUST have key.
	427	MUST NOT have value.
	428
	429	o 8 byte value to add / subtract (FIXME: Is this unsigned?)
	430	o 8 byte initial value (unsigned)
	431	o 4 byte expiration time
	432
	433
	434
	435
	436
	437
	438
	439
	440
	441
	442
	443
	444
	445
	446
	447	Aaron Stone Expires June 16, 2008 [Page 8]
	448
	449	Internet-Draft Memcache Binary Protocol December 2007
	450
	451
314	452	Extra data for incr/decr:
315	453
316		+.1234567.1234567.1234567.1234567+
317		1 \|Amount (64) \|
318		2 \| \|
319		3 \|Initial value (64) \|
320		4 \| \|
321		5 \|Expiration (32) \|
322		+.1234567.1234567.1234567.1234567+
323
324
325		5. Security Considerations
	454	Byte/ 0 \| 1 \| 2 \| 3 \|
	455	/ \| \| \| \|
	456	\|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\|
	457	+---------------+---------------+---------------+---------------+
	458	0\| Amount to add \|
	459	\| \|
	460	+---------------+---------------+---------------+---------------+
	461	8\| Initial value \|
	462	\| \|
	463	+---------------+---------------+---------------+---------------+
	464	16\| Expiration \|
	465	+---------------+---------------+---------------+---------------+
	466	Total 20 bytes
	467
	468	These commands will either add or remove the specified amount to the
	469	requested counter. If the counter does not exist, one of two things
	470	may happen:
	471	1. If the expiration value is all one-bits (0xffffffff), the
	472	operation will fail with NOT_FOUND.
	473	2. For all other expiration values, the operation will succeed by
	474	seeding the value for this key with the provided initial value to
	475	expire with the provided expiration time.
	476
	477	Note that in the creation case, flags will be set to zero (FIXME:
	478	Should they be provided here as well?)
	479
	480
	481	5. Example Session
	482
	483	We start up our application, and it asks for the value associated
	484	with the 'Hello' key.
	485
	486
	487
	488
	489
	490
	491
	492
	493
	494
	495
	496
	497
	498
	499
	500
	501
	502
	503	Aaron Stone Expires June 16, 2008 [Page 9]
	504
	505	Internet-Draft Memcache Binary Protocol December 2007
	506
	507
	508	Get request:
	509
	510	Byte/ 0 \| 1 \| 2 \| 3 \|
	511	/ \| \| \| \|
	512	\|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\|
	513	+---------------+---------------+---------------+---------------+
	514	0\| 0x80 \| 0x00 \| 5 in big endian (BE) \|
	515	+---------------+---------------+---------------+---------------+
	516	\| 12 in BE \| 0x00 \| \|
	517	+---------------+---------------+---------------+---------------+
	518	\| 17 in BE \|
	519	+---------------+---------------+---------------+---------------+
	520	\| 0xDEADBEEF \|
	521	+---------------+---------------+---------------+---------------+
	522	16\| 0x00000000 \|
	523	+---------------+---------------+---------------+---------------+
	524	24\| 0xDECAF 0x15 0xBAD 0xC0FFEE \|
	525	\| \|
	526	+---------------+---------------+---------------+---------------+
	527	28\| 'H' 'e' 'l' 'l' \|
	528	\| 'o' \|
	529	+---------------+
	530	Total 33 bytes (16 header + 12 get-extras + 5 key)
	531
	532	Since nobody has set this key, it returns not found.
	533
	534	Get response:
	535
	536	Byte/ 0 \| 1 \| 2 \| 3 \|
	537	/ \| \| \| \|
	538	\|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\|
	539	+---------------+---------------+---------------+---------------+
	540	0\| 0x81 \| 0x00 \| 0x0001 \|
	541	+---------------+---------------+---------------+---------------+
	542	\| 0 in BE \| 0x00 \| \|
	543	+---------------+---------------+---------------+---------------+
	544	\| 0 in BE \|
	545	+---------------+---------------+---------------+---------------+
	546	\| 0xDEADBEEF \|
	547	+---------------+---------------+---------------+---------------+
	548	Total 16 bytes
	549
	550	Well, looks like we need to set the key! Let's set it to expire on
	551	December 15, 2007 at 9:51:09 PM.
	552
	553
	554
	555
	556
	557
	558
	559	Aaron Stone Expires June 16, 2008 [Page 10]
	560
	561	Internet-Draft Memcache Binary Protocol December 2007
	562
	563
	564	Set request:
	565
	566	Byte/ 0 \| 1 \| 2 \| 3 \|
	567	/ \| \| \| \|
	568	\|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\|
	569	+---------------+---------------+---------------+---------------+
	570	0\| 0x80 \| 0x01 \| 5 in BE \|
	571	+---------------+---------------+---------------+---------------+
	572	\| 16 in BE \| 0x00 \| \|
	573	+---------------+---------------+---------------+---------------+
	574	\| 26 in BE \|
	575	+---------------+---------------+---------------+---------------+
	576	\| 0xDA7ABA5E \|
	577	+---------------+---------------+---------------+---------------+
	578	16\| 0x00000000 \|
	579	+---------------+---------------+---------------+---------------+
	580	20\| 0xDCCB4674 \|
	581	+---------------+---------------+---------------+---------------+
	582	24\| 0xDECAF 0x15 0xBAD 0xC0FFEE \|
	583	\| \|
	584	+---------------+---------------+---------------+---------------+
	585	32\| 'H' 'e' 'l' 'l' \|
	586	\| 'o' \| 'W' 'o' 'r' \|
	587	\| 'l' 'd' \|
	588	+---------------+---------------+
	589	Total 42 bytes (16 header + 16 set-extras + 5 key + 5 value)
	590
	591	The set succeeds.
	592
	593
	594
	595
	596
	597
	598
	599
	600
	601
	602
	603
	604
	605
	606
	607
	608
	609
	610
	611
	612
	613
	614
	615	Aaron Stone Expires June 16, 2008 [Page 11]
	616
	617	Internet-Draft Memcache Binary Protocol December 2007
	618
	619
	620	Set response:
	621
	622	Byte/ 0 \| 1 \| 2 \| 3 \|
	623	/ \| \| \| \|
	624	\|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\|
	625	+---------------+---------------+---------------+---------------+
	626	0\| 0x81 \| 0x01 \| 0x0000 \|
	627	+---------------+---------------+---------------+---------------+
	628	\| 16 in BE \| 0x00 \| \|
	629	+---------------+---------------+---------------+---------------+
	630	\| 16 in BE \|
	631	+---------------+---------------+---------------+---------------+
	632	\| 0xDA7ABA5E \|
	633	+---------------+---------------+---------------+---------------+
	634	16\| 0x00000000 \|
	635	+---------------+---------------+---------------+---------------+
	636	20\| 0xDCCB4674 \|
	637	+---------------+---------------+---------------+---------------+
	638	24\| 0xDECAF 0x15 0xBAD 0xC0FFEE \|
	639	\| \|
	640	+---------------+---------------+---------------+---------------+
	641	Total 32 bytes (16 header + 16 set-extras)
	642
	643	If the original get request is sent again, the key would be found.
	644
	645	Get response:
	646
	647	Byte/ 0 \| 1 \| 2 \| 3 \|
	648	/ \| \| \| \|
	649	\|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\|
	650	+---------------+---------------+---------------+---------------+
	651	0\| 0x81 \| 0x00 \| 0x00 \| \|
	652	+---------------+---------------+---------------+---------------+
	653	\| 12 in BE \| 0x00 \| \|
	654	+---------------+---------------+---------------+---------------+
	655	\| 17 in BE \|
	656	+---------------+---------------+---------------+---------------+
	657	\| 0xDEADBEEF \|
	658	+---------------+---------------+---------------+---------------+
	659	16\| 0xDCCB4674 \|
	660	+---------------+---------------+---------------+---------------+
	661	24\| 0xDECAF 0x15 0xBAD 0xC0FFEE \|
	662	\| \|
	663	+---------------+---------------+---------------+---------------+
	664	28\| 'W' 'o' 'r' 'l' \|
	665	\| 'd' \|
	666	+---------------+
	667	Total 33 bytes (16 header + 12 get-extras + 5 value)
	668
	669
	670
	671	Aaron Stone Expires June 16, 2008 [Page 12]
	672
	673	Internet-Draft Memcache Binary Protocol December 2007
	674
	675
	676	6. Security Considerations
326	677
327	678	Memcache has no authentication or security layers and is intended
…	…
332	683
333	684
334
335		Aaron Stone Expires June 16, 2008 [Page 6]
336
337		Internet-Draft Memcache Binary Protocol December 2007
338
339
340		6. Normative References
341
342		[LJ] Danga Interactive, "LJ NEEDS MOAR SPEED", 10 1999.
	685	7. Normative References
	686
	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.
343	691
344	692
345	693	Appendix A. Acknowledgments
346	694
347		Thanks to Brad Fitzpatrick, Sean Chittenden, Jonathan Steinert, Brian
348		Aker, Chris Goffinet, Dustin Sailings, and Steven Grimm, for their
349		work on the memcached server and client libraries in a variety of
	695	Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin
	696	Sallings, for their work on the memcached server.
	697
	698	Thanks to Sean Chittenden, Jonathan Steinert, Brian Aker, Evan
	699	Martin, Nathan Neulinger, Eric Hodel, Michael Johnson, Paul Querna,
	700	Jamie McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg,
	701	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
350	705	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.
351	710
352	711
…	…
359	718	USA
360	719
361		Email: astone@sixapart.com
362		URI: aaron@serendipity.palo-alto.ca.us
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391		Aaron Stone Expires June 16, 2008 [Page 7]
392
	720	Email: aaron@serendipity.palo-alto.ca.us
	721
	722
	723
	724
	725
	726
	727	Aaron Stone Expires June 16, 2008 [Page 13]
	728

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

r683	r684
7	7	<?rfc sortrefs="yes" ?>
8	8	<?rfc compact="yes" ?>
9		<?rfc subcompact="no" ?>
	9	<?rfc subcompact="yes" ?>
10	10	<rfc category="info" docName="draft-stone-memcache-binary-01" ipr="none">
11	11
…	…
24	24	<country>USA</country>
25	25	</postal>
26		<email>astone@sixapart.com</email>
27		<uri>aaron@serendipity.palo-alto.ca.us</uri>
	26	<email>aaron@serendipity.palo-alto.ca.us</email>
28	27	</address>
29	28	</author>
…	…
32	31
33	32	<area>Applications</area>
34
35		~~<!-- workgroup>Memcache Working Group</workgroup-->~~
36	33
37	34	<keyword>memcache memcached cache</keyword>
…	…
53	50
54	51	<middle>
55		<section title="Introduction">
	52	<section anchor="introduction" title="Introduction">
56	53	<t>
57	54	Memcache is a high performance key-value cache. It is intentionally a
…	…
64	61	Memcache was originally written to make <xref target="LJ">LiveJournal</xref> go faster.
65	62	</t>
66		<section title="Conventions">
67		<t>
68		Bits run across the top. Period (.) represent the
69		start of each byte (bit 0 in that byte, so to speak).
70		The characters -, +, \| are used for Ascii art.
71		Number of bits in each field are in parens.
72		Numbers on the left side are helpful for counting
73		four byte word lines in the packet.
74		All numbers are in network byte order (big endian).
	63	<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.
75	66	</t>
76	67	</section>
77	68	</section>
78	69
79		<section title="Packet formats">
	70	<section anchor="packet" title="Packet Structure">
	71	<t>
	72	<figure>
	73	<preamble>General format of a packet:</preamble>
	74	<artwork>
	75	Byte/ 0 \| 1 \| 2 \| 3 \|
	76	/ \| \| \| \|
	77	\|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\|
	78	+---------------+---------------+---------------+---------------+
	79	0/ HEADER /
	80	/ /
	81	/ /
	82	/ /
	83	+---------------+---------------+---------------+---------------+
	84	16/ COMMAND-SPECIFIC EXTRAS (as needed) /
	85	+/ (note length in th extras length header field) /
	86	+---------------+---------------+---------------+---------------+
	87	m/ Key (as needed) /
	88	+/ (note length in key length header field) /
	89	+---------------+---------------+---------------+---------------+
	90	n/ Value (as needed) /
	91	+/ (note length is total body length header field, minus /
	92	+/ sum of the extras and key length body fields) /
	93	+---------------+---------------+---------------+---------------+
	94	Total 16 bytes
	95	</artwork></figure>
	96	</t>
	97
80	98	<t>
81	99	<figure>
82	100	<preamble>Request header:</preamble>
83	101	<artwork>
84		+.1234567.1234567.1234567.1234567+
85		1 \|Mag (8) Cmd (8) Key len (16) \|
86		2 \|Len (8) Type(8) Reserved (16) \|
87		3 \|Total body length (32) \|
88		4 \|Opaque key (32) \|
89		+.1234567.1234567.1234567.1234567+
	102	Byte/ 0 \| 1 \| 2 \| 3 \|
	103	/ \| \| \| \|
	104	\|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\|
	105	+---------------+---------------+---------------+---------------+
	106	0\| Magic \| Opcode \| Key length \|
	107	+---------------+---------------+---------------+---------------+
	108	4\| Extras length \| Data type \| Reserved \|
	109	+---------------+---------------+---------------+---------------+
	110	8\| Total body length \|
	111	+---------------+---------------+---------------+---------------+
	112	12\| Message ID \|
	113	+---------------+---------------+---------------+---------------+
	114	Total 16 bytes
90	115	</artwork></figure>
91	116	</t>
…	…
95	120	<preamble>Response header:</preamble>
96	121	<artwork>
97		+.1234567.1234567.1234567.1234567+
98		1 \|Mag (8) Cmd (8) Stat(8) Resvd(8)\| ***FIXME: see below
99		2 \|Len (8) Type(8) Reserved(16) \|
100		3 \|Total body length (32) \|
101		4 \|Opaque key (32)