Communication

Communicating with an active E-Chord network is done through TCP sockets. A request-response format is used. For more information, read the communication guide.

Below is a comprehensive list of requests and equivalent responses.

The format used to indicate the correct data types for request and response data is as follows. The data being displayed consist of key-value pairs for the value of the body field of a request/response. For each request/response, the data columns in the tables below contain each key name (as a string) and its corresponding value type. If ANY is used as a value type, it means the key can contain any type of value.

If square brackets surround a value, that means a JSON array is expected. This can contain multiple instances of whichever types of data are contained within it.

Requests

For a request to be valid, it must have a valid request type and contain the expected data in its body.

Ordinary requests

These are requests that are ordinarily used by a client outside the network.

Request Type	Expected Data	Description
find_key	key: string	Asks for the value for a key.
find_and_store_key	key: string value: ANY	Asks a node to locate the correct node and store a pair.
find_and_delete_key	key: string	Asks a node to locate the correct node and delete a pair by key.
poll	-	Polls a node, asking if it is alive. Normally used by seed server, but may be used by other clients.

Debugging requests

These are requests that serve debugging purposes. It is not expected that these requests be used in ordinary function.

Request Type	Expected Data	Description
debug_leave_ring	-	Tells node to leave ring in a semi-ordinary fashion. This consists of moving existing data to another appropriate node, but not notifying nodes beyond this.
debug_pred	-	Tells node to output its predecessor's address and node ID.
debug_succ_list	-	Tells node to output its successor list.
debug_finger_table	-	Tells node to output its finger table.
debug_storage	-	Tells node to output its storage. This includes all pairs saved on the node.
debug_fail	-	Tells node to abruptly fail. This consists of leaving the network without performing any actions.
debug_get_total_keys	-	Tells node to return the number of keys stored on it.

Internal requests

These are requests used between nodes to ensure optimal network operation. These requests should almost never be used during ordinary function, since they could disrupt network operations. Use these at your own risk.

Request Type	Expected Data	Description
get_successor	-	Asks a node for its successor.
get_predecessor	-	Asks a node for its predecessor.
find_successor	for_id: int	Asks a node to find the correct successor for an ID.
get_closest_preceding_finger	for_key_id: int	Asks a node for the closest preceding finger it has for an ID.
get_prev_successor_list	-	Asks a node for its successor list.
lookup	key: string	Asks a node to return the value for a key from its storage.
delete_key	key: string	Asks a node to delete a pair by key from its storage.

The rest of the internal requests, seen below, will almost certainly disrupt network operations, to some degree, if used by outside clients.

Request Type	Expected Data	Description
update_predecessor	ip: string port: int node_id: int	Tells a node to update its predecessor to a new node.
clear_predecessor	-	Tells a node to clear its predecessor.
store_key	key: string value: ANY key_id: int	Tells a node to store a new pair in its storage.
batch_store_keys	keys: [{ key: string value: ANY key_id: int }]	Tells a node to store a set of pairs in its storage.

Responses

For most types of requests, there is an expected response. Few requests do not expect a response. This is denoted below by a missing response status.

Responses always contain a status code in their header. Below are the response codes in use by E-Chord:

Status	Code	Meaning
STATUS_OK	200	Request served successfully.
STATUS_NOT_FOUND	404	Unable to find resource.

Responses might also contain data. In that case, this is contained in the response body. Note that, if the returned status is STATUS_NOT_FOUND, data will not be contained in the response body.

Ordinary requests

Request Type	Response Status	Response Data
find_key	STATUS_OK STATUS_NOT_FOUND	value: ANY
find_and_store_key	STATUS_OK STATUS_NOT_FOUND	-
find_and_delete_key	STATUS_OK STATUS_NOT_FOUND	-
poll	STATUS_OK	-

Debugging requests

Request Type	Response Status	Response Data
debug_leave_ring	STATUS_OK	-
debug_pred	STATUS_OK	-
debug_succ_list	STATUS_OK	-
debug_finger_table	STATUS_OK	-
debug_storage	STATUS_OK	-
debug_fail	-	-
debug_get_total_keys	STATUS_OK	total_keys: int

Internal requests

Request Type	Response Status	Response Data
get_successor	STATUS_OK	ip: string port: int node_id: int
get_predecessor	STATUS_OK STATUS_NOT_FOUND	ip: string port: int node_id: int
find_successor	STATUS_OK STATUS_NOT_FOUND	ip: string port: int node_id: int
get_closest_preceding_finger	STATUS_OK	fingers: [{ ip: string port: int node_id: int }] contains_successor: bool
get_prev_successor_list	STATUS_OK	successor_list: [{ ip: string port: int node_id: int }]
lookup	STATUS_OK STATUS_NOT_FOUND	value: ANY
delete_key	STATUS_OK STATUS_NOT_FOUND	-
update_predecessor	STATUS_OK	-
clear_predecessor	STATUS_OK	-
store_key	STATUS_OK	-
batch_store_keys	STATUS_OK	-