9feec51e2d
This commit introduces a network simulation framework which can be used to run simulated networks of devp2p nodes. The intention is to use this for testing protocols, performing benchmarks and visualising emergent network behaviour.
182 lines
6.1 KiB
Markdown
182 lines
6.1 KiB
Markdown
# devp2p Simulations
|
|
|
|
The `p2p/simulations` package implements a simulation framework which supports
|
|
creating a collection of devp2p nodes, connecting them together to form a
|
|
simulation network, performing simulation actions in that network and then
|
|
extracting useful information.
|
|
|
|
## Nodes
|
|
|
|
Each node in a simulation network runs multiple services by wrapping a collection
|
|
of objects which implement the `node.Service` interface meaning they:
|
|
|
|
* can be started and stopped
|
|
* run p2p protocols
|
|
* expose RPC APIs
|
|
|
|
This means that any object which implements the `node.Service` interface can be
|
|
used to run a node in the simulation.
|
|
|
|
## Services
|
|
|
|
Before running a simulation, a set of service initializers must be registered
|
|
which can then be used to run nodes in the network.
|
|
|
|
A service initializer is a function with the following signature:
|
|
|
|
```go
|
|
func(ctx *adapters.ServiceContext) (node.Service, error)
|
|
```
|
|
|
|
These initializers should be registered by calling the `adapters.RegisterServices`
|
|
function in an `init()` hook:
|
|
|
|
```go
|
|
func init() {
|
|
adapters.RegisterServices(adapters.Services{
|
|
"service1": initService1,
|
|
"service2": initService2,
|
|
})
|
|
}
|
|
```
|
|
|
|
## Node Adapters
|
|
|
|
The simulation framework includes multiple "node adapters" which are
|
|
responsible for creating an environment in which a node runs.
|
|
|
|
### SimAdapter
|
|
|
|
The `SimAdapter` runs nodes in-memory, connecting them using an in-memory,
|
|
synchronous `net.Pipe` and connecting to their RPC server using an in-memory
|
|
`rpc.Client`.
|
|
|
|
### ExecAdapter
|
|
|
|
The `ExecAdapter` runs nodes as child processes of the running simulation.
|
|
|
|
It does this by executing the binary which is running the simulation but
|
|
setting `argv[0]` (i.e. the program name) to `p2p-node` which is then
|
|
detected by an init hook in the child process which runs the `node.Service`
|
|
using the devp2p node stack rather than executing `main()`.
|
|
|
|
The nodes listen for devp2p connections and WebSocket RPC clients on random
|
|
localhost ports.
|
|
|
|
### DockerAdapter
|
|
|
|
The `DockerAdapter` is similar to the `ExecAdapter` but executes `docker run`
|
|
to run the node in a Docker container using a Docker image containing the
|
|
simulation binary at `/bin/p2p-node`.
|
|
|
|
The Docker image is built using `docker build` when the adapter is initialised,
|
|
meaning no prior setup is necessary other than having a working Docker client.
|
|
|
|
Each node listens on the external IP of the container and the default p2p and
|
|
RPC ports (`30303` and `8546` respectively).
|
|
|
|
## Network
|
|
|
|
A simulation network is created with an ID and default service (which is used
|
|
if a node is created without an explicit service), exposes methods for
|
|
creating, starting, stopping, connecting and disconnecting nodes, and emits
|
|
events when certain actions occur.
|
|
|
|
### Events
|
|
|
|
A simulation network emits the following events:
|
|
|
|
* node event - when nodes are created / started / stopped
|
|
* connection event - when nodes are connected / disconnected
|
|
* message event - when a protocol message is sent between two nodes
|
|
|
|
The events have a "control" flag which when set indicates that the event is the
|
|
outcome of a controlled simulation action (e.g. creating a node or explicitly
|
|
connecting two nodes together).
|
|
|
|
This is in contrast to a non-control event, otherwise called a "live" event,
|
|
which is the outcome of something happening in the network as a result of a
|
|
control event (e.g. a node actually started up or a connection was actually
|
|
established between two nodes).
|
|
|
|
Live events are detected by the simulation network by subscribing to node peer
|
|
events via RPC when the nodes start up.
|
|
|
|
## Testing Framework
|
|
|
|
The `Simulation` type can be used in tests to perform actions in a simulation
|
|
network and then wait for expectations to be met.
|
|
|
|
With a running simulation network, the `Simulation.Run` method can be called
|
|
with a `Step` which has the following fields:
|
|
|
|
* `Action` - a function which performs some action in the network
|
|
|
|
* `Expect` - an expectation function which returns whether or not a
|
|
given node meets the expectation
|
|
|
|
* `Trigger` - a channel which receives node IDs which then trigger a check
|
|
of the expectation function to be performed against that node
|
|
|
|
As a concrete example, consider a simulated network of Ethereum nodes. An
|
|
`Action` could be the sending of a transaction, `Expect` it being included in
|
|
a block, and `Trigger` a check for every block that is mined.
|
|
|
|
On return, the `Simulation.Run` method returns a `StepResult` which can be used
|
|
to determine if all nodes met the expectation, how long it took them to meet
|
|
the expectation and what network events were emitted during the step run.
|
|
|
|
## HTTP API
|
|
|
|
The simulation framework includes a HTTP API which can be used to control the
|
|
simulation.
|
|
|
|
The API is initialised with a particular node adapter and has the following
|
|
endpoints:
|
|
|
|
```
|
|
GET / Get network information
|
|
POST /start Start all nodes in the network
|
|
POST /stop Stop all nodes in the network
|
|
GET /events Stream network events
|
|
GET /snapshot Take a network snapshot
|
|
POST /snapshot Load a network snapshot
|
|
POST /nodes Create a node
|
|
GET /nodes Get all nodes in the network
|
|
GET /nodes/:nodeid Get node information
|
|
POST /nodes/:nodeid/start Start a node
|
|
POST /nodes/:nodeid/stop Stop a node
|
|
POST /nodes/:nodeid/conn/:peerid Connect two nodes
|
|
DELETE /nodes/:nodeid/conn/:peerid Disconnect two nodes
|
|
GET /nodes/:nodeid/rpc Make RPC requests to a node via WebSocket
|
|
```
|
|
|
|
For convenience, `nodeid` in the URL can be the name of a node rather than its
|
|
ID.
|
|
|
|
## Command line client
|
|
|
|
`p2psim` is a command line client for the HTTP API, located in
|
|
`cmd/p2psim`.
|
|
|
|
It provides the following commands:
|
|
|
|
```
|
|
p2psim show
|
|
p2psim events [--current] [--filter=FILTER]
|
|
p2psim snapshot
|
|
p2psim load
|
|
p2psim node create [--name=NAME] [--services=SERVICES] [--key=KEY]
|
|
p2psim node list
|
|
p2psim node show <node>
|
|
p2psim node start <node>
|
|
p2psim node stop <node>
|
|
p2psim node connect <node> <peer>
|
|
p2psim node disconnect <node> <peer>
|
|
p2psim node rpc <node> <method> [<args>] [--subscribe]
|
|
```
|
|
|
|
## Example
|
|
|
|
See [p2p/simulations/examples/README.md](examples/README.md).
|