Memcache 协议

zzbb

　　闲暇之余，fish翻译了memcached协议，自娱同时也方便后来者参阅。
　　Protocol
--------
 
       Memcached client 采用tcp、udp协议连接memcached ，发送指令，接受解析响应，从而实现对象的写入与读出。
       Memcached client无须发送任何治指令即可断开与server的会话。不过推荐缓存在client端缓存连接，而非频繁建立关闭连接。尽管memcached被设计为可以同时监听数千的连接，而且在建立连接上并不存在瓶颈，但因为缓存连接可以避免client端tcp连接的瓶颈。
       Memcached协议传输两种类型的数据：文本数据、非结构话数据。文本数据用户client与server见得命令、响应交互，而非结构化数据则用于存储和读取数据。Server并不关心非结构化数据的字节顺序，甚至根本不在意存储的内容，它只管接受并返回client传过来的存储内容。然后client需要关注存储的内容，client从server的响应文本中读取内容的长度，根据长度获取存的非结构换数据并进行解析。
     交互文本以\r\n结尾，非结构化数据也是以\r\n结尾，但是\r 、\n 或者其他任何8bit字符均可出现在非结构化数据中。因此client从server读取数据时，必须以server响应中的data长度进行数据内容读取，而不能仅仅依靠\r\n。
 
Keys
----
      Server中存储的数据以key进行区分。Key是一个文本行，用于client对数据的存储与读取。当前memcached对key的限制为不含控制字符及空格、最长250字节的文本行。
 
Commands
--------
      有三种类型的命令。
Storage commands 有6种：set add replace append prepend cas,用于存储数据。存储时，client先发送一个命令行，然后传送非结构化data，需要时直接传相关命令即可获得之前存储的对象或返回失败。
 
      Retrieval commands 有2种：get gets 用于通过key获取相应的数据。Client发送命令行，可以发送一个或多个key，server收到后查找每个key，并返回响应的数据，一个数据块对应一个key的值，返回结果是以END名行结尾的。
 
     过期时间：可以是unix time或者自当前时间点之后的时间，单位为秒。
     注意当设置为后者时间时，如果值大于 60 * 60 * 24 * 30，则被认为是unix time。
 
 
 
 
 
Error strings
-------------
如果client发送命令错误，服务器可能返回三种类型：
 
- "ERROR\r\n"
 
    指client发送了一个不存在的命令。
 
- "CLIENT_ERROR <error>\r\n"
 
    指client发送的命令行存在如参数等的错误。 <error>是可读的错误字串。
 
- "SERVER_ERROR <error>\r\n"
 
    指server无法提供服务。<error>是可读字串。这种情况一般不会发生，只在server
关闭与client间的连接时出现。
 
     在下面各命令的介绍中，error命令不会重复提及，不过client必须支持这些错误。
　　
Storage commands
----------------
 
格式：
 
    <command name> <key> <flags> <exptime> <bytes> [noreply]\r\n
    cas <key> <flags> <exptime> <bytes> <cas unqiue> [noreply]\r\n
 
- <command name> 分为： "set", "add", "replace", "append" or "prepend"
 
  "set" 只存储一个值
 
  "add"  指只在server不存在这个key时，才存储key-value值。
 
  "replace" 指只有在server存在该key-value时，才进行存储。
 
  "append" 指将值增加到server中该key对应的value之后。
 
  "prepend" 指将值增加到server中对应的value之前。
  
   Append 和prepend命令不支持flag和exptime，他们更新存在的key-value，忽略flag和exptime。
 
  "cas" （check and set）指只有在从上次获取后没有被更新过，才进行set。
 
- <key> client用于存储data的键
 
-  <flags> 是一个16位的无符号int，server会存储并在以后取数据时返回给client。该值用于保存data存储相关信息，对server是透明的。注意从memcached 1.2.1之后，改用32位int存储，不过你可以强制使用16位，以兼容之前版本。
 
-  <exptime> 过期时间，如果设置为0则表示永不过期（但是仍然可能被删除以为新元素腾出空间）。它是一个非负数，保证在过期后，client不再会取到该值。
 
-  <bytes> 数据块的字节数，不包括\r\n。可以为0，表示value为空。
 
-  <cas unique> 是一个64位的存储键值对的唯一标识。Client在用gets命令时返回，在cas时需要带上该标记。
 
-        "noreply" 一个通知server不用返回响应结果的可选参数。如果请求命令错误，server不能正确识别noreply，仍然会返回error。
 
输入上述行后，client即可发送数据块。
 
格式：
<data block>\r\n
 
-  <data block>  是8位字节序列。
 
在发送完命令行和数据块后，server可能返回如下结果给client：
 
- "STORED\r\n", 表示成功
 
-  "NOT_STORED\r\n"  表示存储失败，但是不是由于一个错误引起的。在使用add、replace
时，或者在delete时，如果server并没有该key值，则会出现这种结果。
 
- "EXISTS\r\n"  表示要cas的键值对已经被修改过。
 
-  "NOT_FOUND\r\n" 表示要cas的键值对并不存在，或者已经被删除了。
  
 
Retrieval command:
------------------
 
获取命令包括get gets：
 
get <key>*\r\n
gets <key>*\r\n
 
- <key>* 表示一个或多个键，多个键之间用空格分开。
 
Client发送该指令后，server会返回一行或多行数据块，每一行是一个key的值。在所有数据块被传输后，server返回 END\r\n
"END\r\n" 表示响应的结尾。
　　
返回值的格式如下：
　　VALUE <key> <flags> <bytes> [<cas unique>]\r\n
　　<data block>\r\n
 
- <key> is the key for the item being sent
 
- <flags> 存储时设入的标记
 
- <bytes> 存储内容的长度，不包括\r\n
 
- <cas unique> 8字节int，指定kv条目的唯一标记
 
- <data block> 存储的数据块
 
如果有些key及value没有返回，则表示该key-value不存在或被删除了。
 
 
 
Deletion
--------
 
删除命令格式:
 
delete <key> [<time>] [noreply]\r\n
 
- <key> 要删除的key
 
<time> 删除，并且在指定秒数内server拒绝add、replace命令操作该key，该key在指定时间被设入删除队列，之后最终从内存删除。可以是自当前时间之后的秒数或unix time （unit：s）。该参数是可选，默认是0。
 
- "noreply"可选参数，通知server不用回复
 
Server响应命令行:
 
- "DELETED\r\n" 删除成功
 
- "NOT_FOUND\r\n" 没有发现该kv
 
"flush_all"使所有KV失效。
 
 
Increment/Decrement
 
Incr、decr命令用于增加减少条目的值。该值是一个64未无符号整型，如果当前值不是上述类型，则被视为0。在使用该命令时，该条目必须存在，命令不会视一个不存在的条目值为0，而是直接返回false。
 
Client发出的命令行格式:
 
incr <key> <value> [noreply]\r\n
 
or
 
decr <key> <value> [noreply]\r\n
 
- <key> 需要更新的key
 
<value> 要增加或减少的一个无符号整型值。
 
- "noreply" 无需server应答
 
Server返回应答:
 
- "NOT_FOUND\r\n" 没有发现key
 
- <value>\r\n ,在incr、decr执行后的值.
注意1：当decr下溢（值小于0）时，该值被设为0，而若值上溢（大于上边界），则返回
64位上界值（待确认）。
注意2：在decr时，如果操作后值的长度减少，目前则会用空格代替，但这只是一种优化
实现，client不得依赖于此。
 
Statistics
----------
 
Stats命令用于请求server的存储统计信息，有带参数or不带参数两种请求方式。
 
stats\r\n  用于请求server常用统计、设置等信息。
 
stats <args>\r\n ：请求指定项的统计信息。参数不在本协议规定，由memcache开发者决定统计项。
 
常用统计项
　　--------------------------
　　在收到无参的stats命令，server响应如下:
　　STAT <name> <value>\r\n
　　name表示统计项，value表示统计值。
　　响应结束符：
　　END\r\n
　　下表是返回值说明，32u表示32位无符号整型，64u表示64位无符号整型，32u:32u表示两个用冒号分开的32位无符号整型。
 
 
Name              Type     Meaning
----------------------------------
pid               32u      server pid
uptime            32u      server已经运行时间。
time              32u      server当前的unix时间
version           string   server版本
pointer_size      32       server所在的os的指针长度（32or64）
rusage_user       32u:32u  用户累计使用的时间
                           (seconds:microseconds)
rusage_system     32u:32u  该server进程的累计系统时间
                           (seconds:microseconds)
curr_items        32u      server当前存储的条目数
total_items       32u      自server启动后共存储的条目数
bytes             64u      server当前用于存储数据的字节数             
           
更多参考如下:
curr_connections  32u      Number of open connections
total_connections 32u      Total number of connections opened since
                           the server started running
connection_structures 32u  Number of connection structures allocated
                           by the server
cmd_get           64u      Cumulative number of retrieval requests
cmd_set           64u      Cumulative number of storage requests
get_hits          64u      Number of keys that have been requested and
                           found present
get_misses        64u      Number of items that have been requested
                           and not found
evictions         64u      Number of valid items removed from cache                                                                          
                           to free memory for new items                                                                                      
bytes_read        64u      Total number of bytes read by this server
                           from network
bytes_written     64u      Total number of bytes sent by this server to
                           network
limit_maxbytes    32u      Number of bytes this server is allowed to
                           use for storage.
threads           32u      Number of worker threads requested.
                           (see doc/threads.txt)
 
 
Item statistics
　　---------------
　　Stats items ：stats后带items参数用于请求每一个slab class 的统计信息。
　　Server返回格式如下
　　STAT items:<slabclass>:<stat> <value>\r\n
　　Server响应结束符：
　　END\r\n
　　Stats还可带slabs作为参数使用，stats slabs描述内存使用信息，而stats items描述更上层信息。
　　The following item values are defined as of writing.
　　Name                   Meaning
　　------------------------------
　　number                 Number of items presently stored in this class. Expired
　　items are not automatically excluded.
　　age                    Age of the oldest item in the LRU.
　　evicted                Number of times an item had to be evicted from the LRU                    before it expired.
　　outofmemory            Number of times the underlying slab class was unable to
　　store a new item. This means you are running with -M or
　　an eviction failed.
　　注意:这个命令值返回已经存在的slabs，如果cache是空的，则返回一个空的结果集。
　　Item size statistics
　　Stats sizes: 返回存储条目的长度及数量信息。
　　警告:该命令会锁住整个cache。该命令会查找每一个条目并计算存储尺寸。
　　Server响应格式：
　　<size> <count>\r\n
　　END\r\n （结束符）
　　'size' 存储kv的大致长度，是一个32位值.
　　'count' 存储kv条目的数量，32位值.
　　Slab statistics
　　---------------
　　返回server的每一个slabs统计信息
　　Server响应格式:
　　STAT <slabclass>:<stat> <value>\r\n
　　STAT <stat> <value>\r\n
　　END\r\n
　　返回参数说明
　　Name                   Meaning
　　------------------------------
　　chunk_size             The amount of space each chunk uses. One item will use   one chunk of the appropriate size.
　　chunks_per_page        How many chunks exist within one page. A page by
　　default is one megabyte in size. Slabs are allocated per page, then broken into chunks.
　　total_pages            Total number of pages allocated to the slab class.
　　total_chunks           Total number of chunks allocated to the slab class.
　　used_chunks            How many chunks have been allocated to items.
　　free_chunks            Chunks not yet allocated to items, or freed via delete.
　　free_chunks_end        Number of free chunks at the end of the last allocated page.
　　active_slabs           Total number of slab classes allocated.
　　total_malloced         Total amount of memory allocated to slab pages.
　　
Other commands
--------------
 
flush_all 使所有数据过期，但实际上并不回收内存，仅仅在存储数据时直接使用之前的
存储空间。
 
Version 返回server的version
 
version\r\n
 
verbosity 设置server打印出详细日志。Server一般返回 OK。
 
quit 通知关闭连接 （client也可以直接关闭连接而不通知）:
 
quit\r\n
 
UDP protocol
------------
 
Memcache 也支持UDP协议，但一般用者寥寥，此处不再介绍。