322 lines
No EOL
19 KiB
YAML
322 lines
No EOL
19 KiB
YAML
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.
|
|
- Short list:
|
|
- level 0: basic functionality
|
|
- get
|
|
- set
|
|
- delete
|
|
- flush_all
|
|
- quit
|
|
- level 1: debuggability
|
|
- stats|stats * (some)
|
|
- verbosity
|
|
- version
|
|
- level 2: update functions
|
|
- add|replace
|
|
- append|prepend
|
|
- incr|decr
|
|
- touch
|
|
- stats (related to these functions)
|
|
- level 3: cas
|
|
- cas
|
|
- gets
|
|
- stats (cas-related)
|
|
- level 4: legacy
|
|
- slab_automove|slabs_reassign
|
|
- stats (related to slabs)
|
|
|
|
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.
|
|
- "flush_all [<delay>]\r\n":
|
|
- It always succeeds, and the server sends "OK\r\n" in response (unless "noreply" is given as the last parameter).
|
|
- Its effect is to invalidate all existing items immediately (by default) or after the
|
|
expiration specified in <delay>.
|
|
- After invalidation none of the items will be returned in response to a retrieval command
|
|
(unless it's stored again under the same key *after* flush_all has invalidated the items).
|
|
- flush_all doesn't actually free all the memory taken up by existing items; that will happen
|
|
gradually as new items are stored.
|
|
- The most precise definition of what flush_all does is the following: it causes all items
|
|
whose update time is earlier than the time at which flush_all was set to be executed to be
|
|
ignored for retrieval purposes.
|
|
- The intent of flush_all with a delay, was that in a setting where you have a pool of
|
|
memcached servers, and you need to flush all content, you have the option of not resetting
|
|
all memcached servers at the same time (which could e.g. cause a spike in database load
|
|
with all clients suddenly needing to recreate content that would otherwise have been found
|
|
in the memcached daemon). The delay option allows you to have them reset in e.g. 10 second
|
|
intervals (by passing 0 to the first, 10 to the second, 20 to the third, etc. etc.).
|
|
- 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\r\n":
|
|
- Upon receiving this command, the server closes the connection. However, the client may also
|
|
simply close the connection when it no longer needs it, without issuing this command.
|
|
- slabs automove:
|
|
- "slabs automove <0|1|2>":
|
|
- 0|1|2 is the indicator on whether to enable the slabs automover or not.
|
|
- <0> means to set the thread on standby
|
|
- <1> means to run the builtin slow algorithm to choose pages to move
|
|
- <2> is a highly aggressive mode which causes pages to be moved every time there is an
|
|
eviction. It is not recommended to run for very long in this mode unless your access
|
|
patterns are very well understood.
|
|
- The response should always be "OK\r\n"
|
|
- slabs reassign:
|
|
- distribute memory once a running instance has hit its limit. It might be desireable to have
|
|
memory laid out differently than was automatically assigned after the server started.
|
|
- "slabs reassign <source class> <dest class>\r\n":
|
|
- <source class> is an id number for the slab class to steal a page from.
|
|
- A source class id of -1 means "pick from any valid class"
|
|
- <dest class> is an id number for the slab class to move a page to
|
|
- The response line could be one of:
|
|
- "OK" to indicate the page has been scheduled to move
|
|
- "BUSY [message]" to indicate a page is already being processed, try again later.
|
|
- "BADCLASS [message]" a bad class id was specified
|
|
- "NOSPARE [message]" source class has no spare pages
|
|
- "NOTFULL [message]" dest class must be full to move new pages to it
|
|
- "UNSAFE [message]" source class cannot move a page right now
|
|
- "SAME [message]" must specify different source/dest ids.
|
|
- 1.5.0: "NOTE: This command is subject to change as of this writing."
|
|
- stats:
|
|
- "stats\r\n":
|
|
- it causes the server to output general-purpose statistics and settings, documented below.
|
|
- "stats <args>\r\n":
|
|
- Depending on <args>, various internal data is sent by the server. The kinds of arguments
|
|
and the data sent are not documented in this version of the protocol, and are subject to
|
|
change for the convenience of memcache developers.
|
|
- Upon receiving the "stats" command without arguments, the server sents a number of lines
|
|
which look like this:
|
|
- "STAT <name> <value>\r\n"
|
|
- "<name>" is the name of this statistic,
|
|
- "<value>" is the data.
|
|
- The server terminates this list with the line:
|
|
- "END\r\n"
|
|
- refer to the protocl document for the actual list of values, liable to change on each
|
|
version of memcached.
|
|
- "stats settings\r\n":
|
|
- returns details of the settings of the running memcached. This is primarily made up of
|
|
the results of processing commandline options.
|
|
- these are not guaranteed to return in any specific order and the list in the protocol
|
|
document may not be exhaustive. Otherwise, this returns like any other stats command.
|
|
- "stats items\r\n":
|
|
- Rows look like "STAT items:<slabclass>:<stat> <value>\r\n"
|
|
- <slabclass> aligns with class ids used by the "stats slabs" command. Where "stats slabs"
|
|
describes size and memory usage, "stats items" shows higher level information.
|
|
- <stat> is the name of the statistic being reported by the row
|
|
- <value> is the value of the statistic
|
|
- "stats sizes\r\n":
|
|
- Rows look like "<size> <count>\r\n"
|
|
- <size> is an approximate size of the item, within 32 bytes.
|
|
- <count> is the amount of items that exist within that 32-byte range.
|
|
- May also return "STAT sizes_status disabled"
|
|
- Since 1.4.27, needs to be enabled from the CLI or command "STAT sizes_status disabled"
|
|
which may not work
|
|
- This is essentially a display of all of your items if there was a slab class for every 32
|
|
bytes. You can use this to determine if adjusting the slab growth factor would save memory
|
|
overhead. For example: generating more classes in the lower range could allow items to fit
|
|
more snugly into their slab classes, if most of your items are less than 200 bytes in size.
|
|
- "stats sizes_enable\r\n":
|
|
- enable the histogram at runtime. This has a small overhead to every store or delete
|
|
operation. If you don't want to incur this, leave it off.
|
|
- "stats slabs\r\n" Row may look like:
|
|
- "STAT <slabclass>:<stat> <value>\r\n"
|
|
- <slabclass> aligns with class ids used by the "stats slabs" command.
|
|
- <stat> is the name of the statistic being reported by the row
|
|
- <value> is the value of the statistic
|
|
- "STAT <stat> <value>\r\n"
|
|
- <stat> is the name of the statistic being reported by the row
|
|
- <value> is the value of the statistic
|
|
- 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.
|
|
- "verbosity <level>\r\n":
|
|
- Always succeeds, and the server sends "OK\r\n" in response (unless "noreply" is given as the
|
|
last parameter). Its effect is to set the verbosity level of the logging output.
|
|
- "version\r\n":
|
|
- Response: "VERSION <version>\r\n"
|
|
- <version> is the version string for the server.
|
|
udp:
|
|
uses:
|
|
- The UDP interface does not provide guaranteed delivery,
|
|
- so should only be used for operations that aren't required to succeed;
|
|
- typically used for "get" requests where a missing or incomplete response can simply be treated as a cache miss.
|
|
format:
|
|
- Each UDP datagram contains a simple frame header, followed by data in the same format as the
|
|
TCP protocol described above.
|
|
- The frame header is 8 bytes long. All values are 16-bit integers in network byte order, high byte first:
|
|
0-1: Request ID
|
|
- The request ID is supplied by the client. Typically it will be a monotonically increasing
|
|
value starting from a random seed, but the client is free to use whatever request IDs it likes.
|
|
- The server's response will contain the same ID as the incoming request.
|
|
- The client uses the request ID to differentiate between responses to outstanding requests if
|
|
there are several pending from the same server;
|
|
- Any datagrams with an unknown request ID are probably delayed responses to an earlier
|
|
request and should be discarded.
|
|
2-3: Sequence number
|
|
- The sequence number ranges from 0 to n-1, where n is the total number of datagrams in the message.
|
|
- The client should concatenate the payloads of the datagrams for a given response in
|
|
sequence number order; the resulting byte stream will contain a complete response in the
|
|
same format as the TCP protocol (including terminating \r\n sequences).
|
|
4-5: Total number of datagrams in this message
|
|
6-7: Reserved for future use; must be 0
|
|
- In the current implementation, requests must be contained in a single UDP datagram, but
|
|
responses may span several datagrams.
|
|
- The only common requests that would span multiple datagrams are huge multi-key "get" requests
|
|
and "set" requests, both of which are more suitable to TCP transport for reliability reasons
|
|
anyway.
|
|
|
|
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
|
|
- |