| 1 | Notes regarding the proposed binary protocol from Facebook's hosted |
|---|
| 2 | memcached hackathon on 2007-07-09: |
|---|
| 3 | |
|---|
| 4 | REQUEST STRUCTURE: |
|---|
| 5 | |
|---|
| 6 | * Magic byte / version |
|---|
| 7 | * Cmd byte |
|---|
| 8 | * Key len byte (if no key, 0) |
|---|
| 9 | * Reserved byte (should be 0) |
|---|
| 10 | |
|---|
| 11 | * 4 byte opaque id. (will be copied back in response; means nothing to server) |
|---|
| 12 | |
|---|
| 13 | * 4 byte body length (network order; not including 12 byte header) |
|---|
| 14 | |
|---|
| 15 | [ cmd-specific fixed-width fields ] |
|---|
| 16 | |
|---|
| 17 | * key, if key length above is non-zero. |
|---|
| 18 | |
|---|
| 19 | [ cmd-specific variable-width field ] |
|---|
| 20 | |
|---|
| 21 | |
|---|
| 22 | RESPONSE STRUCTURE: |
|---|
| 23 | |
|---|
| 24 | * Magic byte / version (different from req's magic byte/version, to distinguish |
|---|
| 25 | that it's a response for, say, protocol analyzers) |
|---|
| 26 | * cmd byte (same as response it goes to) |
|---|
| 27 | * err code byte (0 on success, else errcode. hit bit set if fatal/non-normal error) |
|---|
| 28 | * Reserved byte (should be 0) |
|---|
| 29 | |
|---|
| 30 | * 4 byte opaque id copied back from response |
|---|
| 31 | |
|---|
| 32 | * 4 byte body length (network order; not including 12 byte header) |
|---|
| 33 | |
|---|
| 34 | [cmd-specific body] |
|---|
| 35 | |
|---|
| 36 | |
|---|
| 37 | COMMANDS: (for cmd byte) |
|---|
| 38 | |
|---|
| 39 | get - single key get (no more multi-get; clients should pipeline) |
|---|
| 40 | getq - like get, but quiet. that is, no cache miss, return nothing. |
|---|
| 41 | |
|---|
| 42 | Note: you're not guaranteed a response to a getq cache hit until |
|---|
| 43 | you send a non-getq command later, which uncorks the |
|---|
| 44 | server which bundles up IOs to send to the client in one go. |
|---|
| 45 | |
|---|
| 46 | Note: clients should implement multi-get (still important for |
|---|
| 47 | reducing network roundtrips!) as n pipelined requests, the |
|---|
| 48 | first n-1 being getq, the last being a regular |
|---|
| 49 | get. that way you're guaranteed to get a response, and |
|---|
| 50 | you know when the server's done. you can also do the naive |
|---|
| 51 | thing and send n pipelined gets, but then you could potentially |
|---|
| 52 | get back a lot of "NOT_FOUND!" error code packets. |
|---|
| 53 | alternatively, you can send 'n' getqs, followed by an 'echo' |
|---|
| 54 | or 'noop' command. |
|---|
| 55 | |
|---|
| 56 | delete |
|---|
| 57 | set/add/replace |
|---|
| 58 | |
|---|
| 59 | cmd-specific fixed-width fields for set/add/replace: |
|---|
| 60 | |
|---|
| 61 | * 4 byte expiration time |
|---|
| 62 | * 4 byte flags |
|---|
| 63 | (the 4 byte length is inferred from the total body length, |
|---|
| 64 | subtracting (keylen + body length)) |
|---|
| 65 | |
|---|
| 66 | |
|---|
