|
|
@@ -0,0 +1,169 @@
|
|
|
+specification:
|
|
|
+ - https://github.com/memcached/memcached/blob/master/doc/protocol.txt
|
|
|
+ - Expiration times:
|
|
|
+ - Some commands involve a client sending some kind of expiration time (relative to an item or to
|
|
|
+ an operation requested by the client) to the server.
|
|
|
+ - In all such cases, the actual value sent may either be
|
|
|
+ - Unix time (number of seconds since January 1, 1970, as a 32-bit value),
|
|
|
+ - or a number of seconds starting from current time.
|
|
|
+ - In the latter case, this number of seconds may not exceed 60*60*24*30 (number of seconds in 30
|
|
|
+ days); if the number sent by a client is larger than that, the server will consider it to be
|
|
|
+ real Unix time value rather than an offset from current time.
|
|
|
+ - errors:
|
|
|
+ - "ERROR\r\n": means the client sent a nonexistent command name.
|
|
|
+ - "CLIENT_ERROR <error>\r\n": means some sort of client error in the input line, i.e. the input
|
|
|
+ doesn't conform to the protocol in some way. <error> is a human-readable error string.
|
|
|
+ - "SERVER_ERROR <error>\r\n": means some sort of server error prevents the server from carrying
|
|
|
+ out the command. <error> is a human-readable error string. In cases of severe server errors,
|
|
|
+ which make it impossible to continue serving the client (this shouldn't normally happen),
|
|
|
+ the server will close the connection after sending the error line. This is the only case in
|
|
|
+ which the server closes a connection to a client.
|
|
|
+ - In the descriptions of individual commands below, these error lines are not again specifically
|
|
|
+ mentioned, but clients must allow for their possibility.
|
|
|
+
|
|
|
+commands:
|
|
|
+ - A command line always starts with the name of the command, followed by parameters (if any)
|
|
|
+ delimited by whitespace.
|
|
|
+ - Command names are lower-case and are case-sensitive.
|
|
|
+
|
|
|
+storage:
|
|
|
+ - ask the server to store some data identified by a key.
|
|
|
+ - The client sends a command line, and then a data block;
|
|
|
+ - After that the client expects one line of response, which will indicate success or failure.
|
|
|
+ - commands:
|
|
|
+ basic commands:
|
|
|
+ - "add|replace|set <key> <flags> <exptime> <bytes> [noreply]\r\n"
|
|
|
+ - add: store the data under the key, but only if data for the key does not already exist
|
|
|
+ - replace: store the data under the key, but only if data for the key already exist
|
|
|
+ - set: store the data under the key
|
|
|
+ update commands:
|
|
|
+ - "append|prepend <key> <bytes> [noreply]\r\n"
|
|
|
+ - append: add this data to an existing key after existing data (?)
|
|
|
+ - prepend: add this data to an existing key before existing data (?)
|
|
|
+ cas:
|
|
|
+ - "cas <key> <flags> <exptime> <bytes> <cas unique> [noreply]\r\n"
|
|
|
+ - check and set operation which means "store this data but only if no one else has updated
|
|
|
+ since I last fetched it."
|
|
|
+ - command format:
|
|
|
+ <key>: the key under which the client asks to store the data
|
|
|
+ <flags>: is an arbitrary 16-bit unsigned integer (written out in decimal) that the server stores
|
|
|
+ along with the data and sends back when the item is retrieved. Clients may use this as a bit
|
|
|
+ field to store data-specific information; this field is opaque to the server. Note that in
|
|
|
+ memcached 1.2.1 and higher, flags may be 32-bits, instead of 16, but you might want to
|
|
|
+ restrict yourself to 16 bits for compatibility with older versions.
|
|
|
+ <exptime>: is expiration time.:
|
|
|
+ - If it's 0, the item never expires (although it may be deleted from the cache to make place
|
|
|
+ for other items).
|
|
|
+ - If it's non-zero (either Unix time or offset in seconds from current time), it is guaranteed
|
|
|
+ that clients will not be able to retrieve this item after the expiration time arrives
|
|
|
+ (measured byserver time).
|
|
|
+ - If a negative value is given the item is immediately expired.
|
|
|
+ <bytes>:
|
|
|
+ - the number of bytes in the data block to follow, *not* including the delimiting \r\n.
|
|
|
+ - <bytes> may be zero (in which case it's followed by an empty data block).
|
|
|
+ <cas unique>:
|
|
|
+ - only used by the cas command
|
|
|
+ - a unique 64-bit value of an existing entry.
|
|
|
+ - Clients should use the value returned from the "gets" command when issuing "cas" updates.
|
|
|
+ "noreply":
|
|
|
+ - optional parameter instructs the server to not send the reply.
|
|
|
+ - NOTE: if the request line is malformed, the server can't parse "noreply" option reliably.
|
|
|
+ In this case it may send the error to the client, and not reading it on the client side will
|
|
|
+ break things. Client should construct only valid requests.
|
|
|
+ data:
|
|
|
+ - After this line, the client sends the data block:
|
|
|
+ - <data block>\r\n
|
|
|
+ - <data block> is a chunk of arbitrary 8-bit data of length <bytes> from the previous line.
|
|
|
+ - responses:
|
|
|
+ - After sending the command line and the data block the client awaits the reply, which may be:
|
|
|
+ - "STORED\r\n", to indicate success.
|
|
|
+ - "NOT_STORED\r\n" to indicate the data was not stored, but not because of an error.
|
|
|
+ This normally means that the condition for an "add" or a "replace" command wasn't met.
|
|
|
+ - "EXISTS\r\n" to indicate that the item you are trying to store with a "cas" command has been
|
|
|
+ modified since you last fetched it.
|
|
|
+ - "NOT_FOUND\r\n" to indicate that the item you are trying to store with a "cas" command did
|
|
|
+ not exist.
|
|
|
+retrieval:
|
|
|
+ - ask the server to retrieve data corresponding to a set of keys (one or more keys in one
|
|
|
+ request).
|
|
|
+ - The client sends a command line, which includes all the requested keys;
|
|
|
+ - after that for each item the server finds it sends to the client one response line with
|
|
|
+ information about the item, and one data block with the item's data;
|
|
|
+ - this continues until the server finished with the "END" response line.
|
|
|
+ - commands:
|
|
|
+ - "get|gets <key>*\r\n"
|
|
|
+ - <key>* means one or more key strings separated by whitespace.
|
|
|
+ - After this command, the client expects zero or more items, each of which is received as a text
|
|
|
+ line followed by a data block. After all the items have been transmitted, the server sends the
|
|
|
+ string "END\r\n" to indicate the end of response.
|
|
|
+ - Each item sent by the server looks like this:
|
|
|
+ - VALUE <key> <flags> <bytes> [<cas unique>]\r\n
|
|
|
+ - <data block>\r\n
|
|
|
+ - <key> is the key for the item being sent
|
|
|
+ - <flags> is the flags value set by the storage command
|
|
|
+ - <bytes> is the length of the data block to follow, *not* including its delimiting \r\n
|
|
|
+ - <cas unique> is a unique 64-bit integer that uniquely identifies this specific item.
|
|
|
+ - <data block> is the data for this item.
|
|
|
+ - If some of the keys appearing in a retrieval request are not sent back by the server in the
|
|
|
+ item list this means that the server does not hold items with such keys (because they were
|
|
|
+ never stored, or stored but deleted to make space for more items, or expired, or explicitly
|
|
|
+ deleted by a client).
|
|
|
+other:
|
|
|
+ - don't involve unstructured data.
|
|
|
+ - In all of them, the client sends one command line, and expects (depending on the
|
|
|
+ command) either one line of response, or several lines of response ending with "END" on the last
|
|
|
+ line.
|
|
|
+ - commands:
|
|
|
+ - delete:
|
|
|
+ - "delete <key> [noreply]\r\n"
|
|
|
+ - <key> is the key of the item the client wishes the server to delete
|
|
|
+ - "noreply" optional parameter instructs the server to not send the reply.
|
|
|
+ - The response line to this command can be one of:
|
|
|
+ - "DELETED\r\n" to indicate success
|
|
|
+ - "NOT_FOUND\r\n" to indicate that the item with this key was not found.
|
|
|
+ - See the "flush_all" command below for immediate invalidation of all existing items.
|
|
|
+ - increment/decrement:
|
|
|
+ - change data for some item in-place, incrementing or decrementing it.
|
|
|
+ - "incr|decr <key> <value> [noreply]\r\n"
|
|
|
+ - <key> is the key of the item the client wishes to change
|
|
|
+ - <value> is the amount by which the client wants to increase/decrease the item. It is a
|
|
|
+ decimal representation of a 64-bit unsigned integer.
|
|
|
+ - "noreply" optional parameter instructs the server to not send the reply.
|
|
|
+ - The response will be one of:
|
|
|
+ - "NOT_FOUND\r\n" to indicate the item with this value was not found
|
|
|
+ - "<value>\r\n" , where <value> is the new value of the item's data, after the
|
|
|
+ increment/decrement operation was carried out.
|
|
|
+ - The data for the item is treated as decimal representation of a 64-bit unsigned integer.
|
|
|
+ - If the current data value does not conform to such a representation, the incr/decr commands
|
|
|
+ return an error
|
|
|
+ - The item must already exist for incr/decr to work; these commands won't pretend that a
|
|
|
+ non-existent key exists with value 0; instead, they will fail.
|
|
|
+ - Underflow in the "decr" command is caught: if a client tries to decrease the value below 0,
|
|
|
+ the new value will be 0.
|
|
|
+ - Overflow in the "incr" command will wrap around the 64 bit mark.
|
|
|
+ - Decrementing a number such that it loses length isn't guaranteed to decrement its returned
|
|
|
+ length. The number MAY be space-padded at the end, but this is purely an implementation
|
|
|
+ optimization, so you also shouldn't rely on that.
|
|
|
+ - quit:
|
|
|
+ - touch:
|
|
|
+ - update the expiration time of an existing item without fetching it.
|
|
|
+ - "touch <key> <exptime> [noreply]\r\n"
|
|
|
+ - "<exptime>"
|
|
|
+ - Expiration time, same as with the storage commands (set/add/etc).
|
|
|
+ - This replaces the existing expiration time. If an existing item were to expire in 10
|
|
|
+ seconds, but then was touched with an expiration time of "20", the item would then expire
|
|
|
+ in 20 seconds.
|
|
|
+ - The response line to this command can be one of:
|
|
|
+ - "TOUCHED\r\n" to indicate success
|
|
|
+ - "NOT_FOUND\r\n" to indicate that the item with this key was not found.
|
|
|
+versions:
|
|
|
+ - Some notable changes... see Changelog for full list
|
|
|
+ - 2003 / 1.1.10: added flush_all command
|
|
|
+ - 2006 / 1.2.0: added UDP transport
|
|
|
+ - 2007 / 1.2.1: <flags> switched from a 16-bit value to a 32-bit value
|
|
|
+ - 2007 / 1.2.2: added verbosity command
|
|
|
+ - 2007 / 1.2.4:
|
|
|
+ - added cas and gets commands
|
|
|
+ - incr/decr values switched from 32-bit to 64-bit values
|
|
|
+ - 2009 / 1.2.7: increment/decrement no longer treats a non-integer value as 0 but returns an error
|
|
|
+ -
|
