FastDFS HOWTO

amio555

　　The communication protocol of FastDFS is TCP/IP, the package composes of header and body which may be empty.
　　header format:
  @ TRACKER_PROTO_PKG_LEN_SIZE bytes package length
  @ 1 byte command
  @ 1 byte status
　　note:
   # TRACKER_PROTO_PKG_LEN_SIZE (8) bytes number buff is Big-Endian bytes
　　
body format:
1. common command(普通命令)
* FDFS_PROTO_CMD_QUIT（终止连接）
  # function: notify server connection will be closed
  # request body: none (no body part)
  # response: none (no header and no body)
　　
2. storage server to tracker server command（SS与TS 间的命令）
　　* the reponse command is TRACKER_PROTO_CMD_STORAGE_RESP

* TRACKER_PROTO_CMD_STORAGE_JOIN（SS加入TS）
  # function: storage join to tracker
  # request body:
      @ FDFS_GROUP_NAME_MAX_LEN + 1 bytes: group name
      @ TRACKER_PROTO_PKG_LEN_SIZE bytes: storage port
  # response body: n * (1 + FDFS_IPADDR_SIZE) bytes, n >= 0. One storage entry format:
      @ 1 byte: storage server status
      @ FDFS_IPADDR_SIZE bytes: storage server ip address
  # memo: return all storage servers in the group only when storage servers changed or return none
  
  
* TRACKER_PROTO_CMD_STORAGE_BEAT（SS向TS发送heart beat）
  # function: heart beat
  # request body: none or storage stat info
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: total upload count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: success upload count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: total set metadata count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: success set metadata count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: total delete count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: success delete count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: total download count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: success download count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: total get metadata count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: success get metadata count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: last source update timestamp
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: last sync update timestamp
  # response body: same to command TRACKER_PROTO_CMD_STORAGE_JOIN
  # memo: storage server sync it's stat info to tracker server only when storage stat info changed
　　
* TRACKER_PROTO_CMD_STORAGE_REPORT（报告磁盘使用情况）
  # function: report disk usage
  # request body:
      @ TRACKER_PROTO_PKG_LEN_SIZE bytes: total space in MB
      @ TRACKER_PROTO_PKG_LEN_SIZE bytes: free space in MB
  # response body: same to command TRACKER_PROTO_CMD_STORAGE_JOIN
　　
* TRACKER_PROTO_CMD_STORAGE_REPLICA_CHG（复制新加入的SS）
  # function: replica new storage servers which maybe not exist in the tracker server
  # request body: n * (1 + FDFS_IPADDR_SIZE) bytes, n >= 1. One storage entry format:
      @ 1 byte: storage server status
      @ FDFS_IPADDR_SIZE bytes: storage server ip address
  # response body: none
　　
* TRACKER_PROTO_CMD_STORAGE_SYNC_SRC_REQ（当加入新的SS时，同步SS）
  # function: sourcestorage require sync. when add a new storage server, the existed storage servers in the same group will ask the tracker server to tell the source storage server which will sync old data to it
  # request body:
      @ FDFS_IPADDR_SIZE bytes: dest storage server (new storage server) ip address
  # response body: none or
     @ FDFS_IPADDR_SIZE bytes: source storage server ip address
     @ TRACKER_PROTO_PKG_LEN_SIZE bytes: sync until timestamp
  # memo: if the dest storage server not do need sync from one of storage servers in the group, the response body is emtpy
　　
* TRACKER_PROTO_CMD_STORAGE_SYNC_DEST_REQ（新加入的SS请求同步）
  # function: dest storage server (new storage server) require sync
  # request body: none
  # response body: none or
     @ FDFS_IPADDR_SIZE bytes: source storage server ip address
     @ TRACKER_PROTO_PKG_LEN_SIZE bytes: sync until timestamp
  # memo: if the dest storage server not do need sync from one of storage servers in the group, the response body is emtpy
　　
* TRACKER_PROTO_CMD_STORAGE_SYNC_NOTIFY（新加入的SS同步通知）
  # function: new storage server sync notify
  # request body:
     @ FDFS_IPADDR_SIZE bytes: source storage server ip address
     @ TRACKER_PROTO_PKG_LEN_SIZE bytes: sync until timestamp
  # response body: same to command TRACKER_PROTO_CMD_STORAGE_JOIN
　　
3. client to tracker server command（Client与TS之间的命令）
　　* the reponse command of following 2 commands is TRACKER_PROTO_CMD_SERVER_RESP

* TRACKER_PROTO_CMD_SERVER_LIST_GROUP（列出所有的组）
  # function: list all groups
  # request body: none
  # response body: n group entries, n >= 0, the format of each entry:
     @ FDFS_GROUP_NAME_MAX_LEN+1 bytes: group name
     @ TRACKER_PROTO_PKG_LEN_SIZE bytes: free disk storage in MB
     @ TRACKER_PROTO_PKG_LEN_SIZE bytes: storage server count
     @ TRACKER_PROTO_PKG_LEN_SIZE bytes: storage server port
     @ TRACKER_PROTO_PKG_LEN_SIZE bytes: active server count
     @ TRACKER_PROTO_PKG_LEN_SIZE bytes: current write server index
　　
* TRACKER_PROTO_CMD_SERVER_LIST_STORAGE（列出一个组的SS信息）
  # function: list storage servers of a group
  # request body:
     @ FDFS_GROUP_NAME_MAX_LEN bytes: the group name to query
  # response body: n storage entries, n >= 0, the format of each entry:
       @ 1 byte: status
       @ FDFS_IPADDR_SIZE byte: ip address
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: total space in MB
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: free space in MB
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: total upload count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: success upload count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: total set metadata count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: success set metadata count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: total delete count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: success delete count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: total download count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: success download count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: total get metadata count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: success get metadata count
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: last source update timestamp
       @ TRACKER_PROTO_PKG_LEN_SIZE bytes: last sync update timestamp


* the reponse command of following 2 commands is TRACKER_PROTO_CMD_SERVICE_RESP

* TRACKER_PROTO_CMD_SERVICE_QUERY_STORE（询问让哪个SS存储文件）
  # function: query which storage server to store file
  # request body: none
  # response body:
     @ FDFS_GROUP_NAME_MAX_LEN bytes: group name
     @ FDFS_IPADDR_SIZE - 1 bytes: storage server ip address
     @ TRACKER_PROTO_PKG_LEN_SIZE bytes: storage server port  
  
  
* TRACKER_PROTO_CMD_SERVICE_QUERY_FETCH（询问从哪个SS下载文件）
  # function: query which storage server to download the file
  # request body:
     @ FDFS_GROUP_NAME_MAX_LEN bytes: group name
     @ filename bytes: filename
  # response body:
     @ FDFS_GROUP_NAME_MAX_LEN bytes: group name
     @ FDFS_IPADDR_SIZE - 1 bytes: storage server ip address
     @ TRACKER_PROTO_PKG_LEN_SIZE bytes: storage server port
　　4. storage server to storage server command（SS之间的命令）
* the reponse command is STORAGE_PROTO_CMD_RESP

* STORAGE_PROTO_CMD_SYNC_CREATE_FILE（同步新创建的文件）
  # function: sync new created file
  # request body:
     @ TRACKER_PROTO_PKG_LEN_SIZE bytes: filename bytes
     @ TRACKER_PROTO_PKG_LEN_SIZE bytes: file size/bytes
     @ FDFS_GROUP_NAME_MAX_LEN bytes: group name
     @ filename bytes : filename
     @ file size bytes: file content
  # response body: none
  
  
* STORAGE_PROTO_CMD_SYNC_DELETE_FILE（同步被删除的文件）
  # function: sync deleted file
  # request body:
     @ FDFS_GROUP_NAME_MAX_LEN bytes: group name
     @ filename bytes: filename
  # response body: none  
　　
* STORAGE_PROTO_CMD_SYNC_UPDATE_FILE（同步被更新的文件）
# function: sync updated file
# request body: same to command STORAGE_PROTO_CMD_SYNC_CREATE_FILE
# respose body: none


5. client to storage server command（Client与SS之间的命令）
* the reponse command is STORAGE_PROTO_CMD_RESP
　　* STORAGE_PROTO_CMD_UPLOAD_FILE（向SS上传文件）
  # function: upload file to storage server
  # request body:
      @ TRACKER_PROTO_PKG_LEN_SIZE bytes: meta data bytes
      @ TRACKER_PROTO_PKG_LEN_SIZE bytes: file size
      @ meta data bytes: each meta data seperated by \x01,
                         name and value seperated by \x02
      @ file size bytes: file content
  # response body:
     @ FDFS_GROUP_NAME_MAX_LEN bytes: group name
     @ filename bytes: filename
　　
* STORAGE_PROTO_CMD_DELETE_FILE（从SS删除文件）
  # function: delete file from storage server
  # request body:
     @ FDFS_GROUP_NAME_MAX_LEN bytes: group name
     @ filename bytes: filename
  # response body: none
　　
* STORAGE_PROTO_CMD_SET_METADATA（从SS删除metadata）
  # function: delete file from storage server
  # request body:
      @ TRACKER_PROTO_PKG_LEN_SIZE bytes: filename length
      @ TRACKER_PROTO_PKG_LEN_SIZE bytes: meta data size
      @ 1 bytes: operation flag,  
           'O' for overwrite all old metadata
           'M' for merge, insert when the meta item not exist, otherwise update it
      @ FDFS_GROUP_NAME_MAX_LEN bytes: group name
      @ filename bytes: filename
      @ meta data bytes: each meta data seperated by \x01,
                         name and value seperated by \x02
  # response body: none
　　
* STORAGE_PROTO_CMD_DOWNLOAD_FILE（从SS下载文件）
  # function: download/fetch file from storage server
  # request body:
      @ FDFS_GROUP_NAME_MAX_LEN bytes: group name
      @ filename bytes: filename
  # response body:
      @ file content
  

* STORAGE_PROTO_CMD_GET_METADATA（从SS获得metadata）
  # function: get metat data from storage server
  # request body:
      @ FDFS_GROUP_NAME_MAX_LEN bytes: group name
      @ filename bytes: filename
  # response body
      @ meta data buff, each meta data seperated by \x01, name and value seperated by \x02