memcache.md

Memcache Command Support

Request

• Twemproxy implements only the memached ASCII commands
• Binary commands are currently unsupported

Ascii Storage Command

+-------------------+------------+--------------------------------------------------------------------------+
|      Command      | Supported? | Format                                                                   |
+-------------------+------------+--------------------------------------------------------------------------+
|        set        |    Yes     | set <key> <flags> <expiry> <datalen> [noreply]\r\n<data>\r\n             |
+-------------------+------------+--------------------------------------------------------------------------+
|        add        |    Yes     | add <key> <flags> <expiry> <datalen> [noreply]\r\n<data>\r\n             |
+-------------------+------------+--------------------------------------------------------------------------+
|      replace      |    Yes     | replace <key> <flags> <expiry> <datalen> [noreply]\r\n<data>\r\n         |
+-------------------+------------+--------------------------------------------------------------------------+
|      append       |    Yes     | append <key> <flags> <expiry> <datalen> [noreply]\r\n<data>\r\n          |
+-------------------+------------+--------------------------------------------------------------------------+
|      prepend      |    Yes     | prepend <key> <flags> <expiry> <datalen> [noreply]\r\n<data>\r\n         |
+-------------------+------------+--------------------------------------------------------------------------+
|       cas         |    Yes     | cas <key> <flags> <expiry> <datalen> <cas> [noreply]\r\n<data>\r\n       |
+-------------------+------------+--------------------------------------------------------------------------+

• Where,
  • - uint32_t : data specific client side flags
  • - uint32_t : expiration time (in seconds)
  • - uint32_t : size of the data (in bytes)
  • - uint8_t[]: data block
  • - uint64_t

Ascii Retrieval Command

+-------------------+------------+--------------------------------------------------------------------------+
|      Command      | Supported? | Format                                                                   |
+-------------------+------------+--------------------------------------------------------------------------+
|        get        |    Yes     | get <key> [<key>]+\r\n                                                   |
+-------------------+------------+--------------------------------------------------------------------------+
|        gets       |    Yes     | gets <key> [<key>]+\r\n                                                  |
+-------------------+------------+--------------------------------------------------------------------------+

Ascii Delete

+-------------------+------------+--------------------------------------------------------------------------+
|      Command      | Supported? | Format                                                                   |
+-------------------+------------+--------------------------------------------------------------------------+
|        delete     |    Yes     | delete <key> [noreply]\r\n                                               |
+-------------------+------------+--------------------------------------------------------------------------+

Ascii Arithmetic Command

+-------------------+------------+--------------------------------------------------------------------------+
|      Command      | Supported? | Format                                                                   |
+-------------------+------------+--------------------------------------------------------------------------+
|        incr       |    Yes     | incr <key> <value> [noreply]\r\n                                         |
+-------------------+------------+--------------------------------------------------------------------------+
|        decr       |    Yes     | decr <key> <value> [noreply]\r\n                                         |
+-------------------+------------+--------------------------------------------------------------------------+

• Where,
  • - uint64_t

Ascii Misc Command

+-------------------+------------+--------------------------------------------------------------------------+
|      Command      | Supported? | Format                                                                   |
+-------------------+------------+--------------------------------------------------------------------------+
|       touch       |    Yes     | touch <key> <expiry>[noreply]\r\n                                        |
+-------------------+------------+--------------------------------------------------------------------------+
|        gat        |  Planned   | gat <expiry> <key>+\r\n                                                  |
+-------------------+------------+--------------------------------------------------------------------------+
|        gats       |  Planned   | gats <expiry> <key>+\r\n                                                 |
+-------------------+------------+--------------------------------------------------------------------------+
|        quit       |    Yes     | quit\r\n                                                                 |
+-------------------+------------+--------------------------------------------------------------------------+
|      flush_all    |    No      | flush_all [<delay>] [noreply]\r\n                                        |
+-------------------+------------+--------------------------------------------------------------------------+
|      version      |    Yes     | version\r\n                                                              |
+-------------------+------------+--------------------------------------------------------------------------+
|      verbosity    |    No      | verbosity <num> [noreply]\r\n                                            |
+-------------------+------------+--------------------------------------------------------------------------+
|       stats       |    No      | stats\r\n                                                                |
+-------------------+------------+--------------------------------------------------------------------------+
|       stats       |    No      | stats <args>\r\n                                                         |
+-------------------+------------+--------------------------------------------------------------------------+

Response

Error Responses

ERROR\r\n
CLIENT_ERROR [error]\r\n
SERVER_ERROR [error]\r\n

Where,
- ERROR means client sent a non-existent command name
- CLIENT_ERROR means that command sent by the client does not conform to the protocol
- SERVER_ERROR means that there was an error on the server side that made processing of the command impossible

Storage Command Responses

STORED\r\n
NOT_STORED\r\n
EXISTS\r\n
NOT_FOUND\r\n

Where,
- STORED indicates success.
- NOT_STORED indicates the data was not stored because condition for an add or replace wasn't met.
- EXISTS indicates that the item you are trying to store with a cas has been modified since you last fetched it.
- NOT_FOUND indicates that the item you are trying to store with a cas does not exist.

Delete Command Responses

NOT_FOUND\r\n
DELETED\r\n

Retrieval Responses

END\r\n
VALUE <key> <flags> <datalen> [<cas>]\r\n<data>\r\nEND\r\n
VALUE <key> <flags> <datalen> [<cas>]\r\n<data>\r\n[VALUE <key> <flags> <datalen> [<cas>]\r\n<data>]+\r\nEND\r\n

Arithmetic Responses

NOT_FOUND\r\n
<value>\r\n

Where,
- <value> - uint64_t : new key value after incr or decr operation

Touch Command Responses

NOT_FOUND\r\n
TOUCHED\r\n

Statistics Response

[STAT <name> <value>\r\n]+END\r\n

Misc Responses

OK\r\n
VERSION <version>\r\n

Notes

• set always creates mapping irrespective of whether it is present on not.
• add, adds only if the mapping is not present
• replace, only replaces if the mapping is present
• append and prepend command ignore flags and expiry values
• noreply instructs the server to not send the reply even if there is an error.
• decr of 0 is 0, while incr of UINT64_MAX is 0
• maximum length of the key is 250 characters
• expiry of 0 means that item never expires, though it could be evicted from the cache
• non-zero expiry is either unix time (# seconds since 01/01/1970) or, offset in seconds from the current time (< 60 x 60 x 24 x 30 seconds = 30 days)
• expiry time is with respect to the server (not client)
• can be zero and when it is, the block is empty.
• Thoughts:
  • ascii protocol is easier to debug - think using strace or tcpdump to see protocol on the wire, Or using telnet or netcat or socat to build memcache requests and responses https://stackoverflow.com/questions/2525188/are-binary-protocols-dead
  • nutcracker will support the more efficient meta-text protocol after the protocol is marked as stable and memcached servers using it have had several releases.
  • https://news.ycombinator.com/item?id=1712788