go__cache/docs/protocol.yml

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
  -