status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Cleanup docs/agent/rpc

This commit is contained in:
Ryan Breen 2015-02-03 17:07:03 -05:00
parent 954aec6623
commit 4c1cd629ae
1 changed files with 35 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
website/source/docs/agent/rpc.html.markdown
View File

@ -3,23 +3,24 @@ layout: "docs"
page_title: "RPC" page_title: "RPC"
sidebar_current: "docs-agent-rpc" sidebar_current: "docs-agent-rpc"
description: |- description: |-
The Consul agent provides a complete RPC mechanism that can be used to control the agent programmatically. This RPC mechanism is the same one used by the CLI, but can be used by other applications to easily leverage the power of Consul without directly embedding. The Consul agent provides a complete RPC mechanism that can be used to control the agent programmatically. This RPC mechanism is the same one used by the CLI but can be used by other applications to easily leverage the power of Consul without directly embedding.
--- ---
# RPC Protocol # RPC Protocol
The Consul agent provides a complete RPC mechanism that can The Consul agent provides a complete RPC mechanism that can
be used to control the agent programmatically. This RPC be used to control the agent programmatically. This RPC
mechanism is the same one used by the CLI, but can be mechanism is the same one used by the CLI but can be
used by other applications to easily leverage the power used by other applications to easily leverage the power
of Consul without directly embedding. It is important to note of Consul without directly embedding.
that the RPC protocol does not support all the same operations
as the [HTTP API](/docs/agent/http.html). It is important to note that the RPC protocol does not support
all the same operations as the [HTTP API](/docs/agent/http.html).
## Implementation Details ## Implementation Details
The RPC protocol is implemented using [MsgPack](http://msgpack.org/) The RPC protocol is implemented using [MsgPack](http://msgpack.org/)
over TCP. This choice is driven by the fact that all operating over TCP. This choice was driven by the fact that all operating
systems support TCP, and MsgPack provides a fast serialization format systems support TCP, and MsgPack provides a fast serialization format
that is broadly available across languages. that is broadly available across languages.
@ -43,35 +44,35 @@ a response body. The response header looks like:
} }
``` ```
The `Command` is used to specify what command the server should The `Command` in the quest is used to specify what command the server should
run, and the `Seq` is used to track the request. Responses are run, and the `Seq` is used to track the request. Responses are
tagged with the same `Seq` as the request. This allows for some tagged with the same `Seq` as the request. This allows for some
concurrency on the server side, as requests are not purely FIFO. concurrency on the server side as requests are not purely FIFO.
Thus, the `Seq` value should not be re-used between commands. Thus, the `Seq` value should not be re-used between commands.
All responses may be accompanied by an error. All responses may be accompanied by an error.
Possible commands include: Possible commands include:
* handshake - Used to initialize the connection, set the version * handshake - Initializes the connection and set the version
* force-leave - Removes a failed node from the cluster * force-leave - Removes a failed node from the cluster
* join - Requests Consul join another node * join - Requests Consul join another node
* members-lan - Returns the list of LAN members * members-lan - Returns the list of LAN members
* members-wan - Returns the list of WAN members * members-wan - Returns the list of WAN members
* monitor - Starts streaming logs over the connection * monitor - Starts streaming logs over the connection
* stop - Stops streaming logs * stop - Stops streaming logs
* leave - Consul agent performs a graceful leave and shutdown * leave - Instructs Consul agent to perform a graceful leave and shutdown
* stats - Provides various debugging statistics * stats - Provides various debugging statistics
* reload - Triggers a configuration reload * reload - Triggers a configuration reload
Below each command is documented along with any request or Each command is documented below along with any request or
response body that is applicable. response body that is applicable.
### handshake ### handshake
The handshake MUST be the first command that is sent, as it informs The handshake MUST be the first command that is sent as it informs
the server which version the client is using. the server which version the client is using.
The request header must be followed with a handshake body, like: The request header must be followed by a handshake body, like:
```javascript ```javascript
{ {
@ -79,7 +80,7 @@ The request header must be followed with a handshake body, like:
} }
``` ```
The body specifies the IPC version being used, however only version The body specifies the IPC version being used; however, only version
1 is currently supported. This is to ensure backwards compatibility 1 is currently supported. This is to ensure backwards compatibility
in the future. in the future.
@ -101,7 +102,7 @@ There is no special response body.
### join ### join
This command is used to join an existing cluster using a known node. This command is used to join an existing cluster using one or more known nodes.
It takes the following body: It takes the following body:
```javascript ```javascript
@ -115,13 +116,13 @@ It takes the following body:
``` ```
The `Existing` nodes are each contacted, and `WAN` controls if we are adding a The `Existing` nodes are each contacted, and `WAN` controls if we are adding a
WAN member or LAN member. LAN members are expected to be in the same datacenter, WAN member or LAN member. LAN members are expected to be in the same datacenter
and should be accessible at relatively low latencies. WAN members are expected to and should be accessible at relatively low latencies. WAN members are expected to
be operating in different datacenters, with relatively high access latencies. It is be operating in different datacenters with relatively high access latencies. It is
important that only agents running in "server" mode are able to join nodes over the important that only agents running in "server" mode are able to join nodes over the
WAN. WAN.
The response body in addition to the header is returned. The body looks like: The response contains both a header and body. The body looks like:
```javascript ```javascript
{ {
@ -129,11 +130,11 @@ The response body in addition to the header is returned. The body looks like:
} }
``` ```
The body returns the number of nodes successfully joined. 'Num' indicates the number of nodes successfully joined.
### members-lan ### members-lan
The members-lan command is used to return all the known LAN members and associated This command is used to return all the known LAN members and associated
information. All agents will respond to this command. information. All agents will respond to this command.
There is no request body, but the response looks like: There is no request body, but the response looks like:
@ -163,7 +164,7 @@ There is no request body, but the response looks like:
### members-wan ### members-wan
The members-wan command is used to return all the known WAN members and associated This command is used to return all the known WAN members and associated
information. Only agents in server mode will respond to this command. information. Only agents in server mode will respond to this command.
There is no request body, and the response is the same as `members-lan` There is no request body, and the response is the same as `members-lan`
@ -172,7 +173,7 @@ There is no request body, and the response is the same as `members-lan`
The monitor command subscribes the channel to log messages from the Agent. The monitor command subscribes the channel to log messages from the Agent.
The request is like: The request looks like:
```javascript ```javascript
{ {
@ -183,8 +184,8 @@ The request is like:
This subscribes the client to all messages of at least DEBUG level. This subscribes the client to all messages of at least DEBUG level.
The server will respond with a standard response header indicating if the monitor The server will respond with a standard response header indicating if the monitor
was successful. However, now as logs occur they will be sent and tagged with was successful. If so, any future logs will be sent and tagged with
the same `Seq` as the monitor command that matches. the same `Seq` as in the `monitor` request.
Assume we issued the previous monitor command with Seq `50`, Assume we issued the previous monitor command with Seq `50`,
we may start getting messages like: we may start getting messages like:
@ -200,8 +201,8 @@ we may start getting messages like:
} }
``` ```
It is important to realize that these messages are sent asynchronously, It is important to realize that these messages are sent asynchronously
and not in response to any command. That means if a client is streaming and not in response to any command. If a client is streaming
commands, there may be logs streamed while a client is waiting for a commands, there may be logs streamed while a client is waiting for a
response to a command. This is why the `Seq` must be used to pair requests response to a command. This is why the `Seq` must be used to pair requests
with their corresponding responses. with their corresponding responses.
@ -211,7 +212,8 @@ To stop streaming, the `stop` command is used.
### stop ### stop
The stop command is used to stop a monitor. This command stops a monitor.
The request looks like: The request looks like:
```javascript ```javascript
@ -222,17 +224,17 @@ The request looks like:
This unsubscribes the client from the monitor with `Seq` value of 50. This unsubscribes the client from the monitor with `Seq` value of 50.
There is no special response body. There is no response body.
### leave ### leave
The leave command is used trigger a graceful leave and shutdown. This command is used trigger a graceful leave and shutdown.
There is no request body, or special response body. There is no request body or special response body.
### stats ### stats
The stats command is used to provide operator information for debugging. This command provides debug information. There is no request body, and the
There is no request body, the response body looks like: response body looks like:
```javascript ```javascript
{ {
@ -250,5 +252,5 @@ There is no request body, the response body looks like:
### reload ### reload
The reload command is used trigger a reload of configurations. This command is used trigger a reload of configurations.
There is no request body, or special response body. There is no request body, or special response body.