framework

package
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 2, 2021 License: Apache-2.0 Imports: 47 Imported by: 0

Documentation

Overview

Package framework provides integration test functionality for HORNET with a Docker network. It effectively abstracts away all complexity with creating a custom Docker network per test, discovering peers, waiting for them to autopeer and offers easy access to the peers' web API and logs.

Index

Constants

View Source 
const (
	// The default REST API port of every node.
	RestAPIPort = 14265

	GenesisAddressPublicKeyHex = "f7868ab6bb55800b77b8b74191ad8285a9bf428ace579d541fda47661803ff44"
	GenesisAddressHex          = "6920b176f613ec7be59e68fc68f597eb3393af80f74c7c3db78198147d5f1f92"
)

Variables

View Source 
var (

	// The seed on which the total supply resides on per default.
	GenesisSeed    ed25519.PrivateKey
	GenesisAddress iotago.Ed25519Address
)
View Source 
var (
	ErrNodeMissingInLayout   = errors.New("node is missing in layout")
	ErrSelfPeering           = errors.New("a node can not peer to itself")
	ErrNoStaticPeers         = errors.New("nodes must have static nodes")
	ErrLayoutEmpty           = errors.New("layout must not be empty")
	ErrNodesDidNotPeerInTime = errors.New("nodes did not peer in time")
	ErrNodesDidNotSyncInTime = errors.New("nodes did not sync in time")
	ErrNodesNotOnlineInTime  = errors.New("nodes did not become online in time")
)

Functions

func DefaultStaticPeeringLayout 

func DefaultStaticPeeringLayout() map[int]map[int]connected

DefaultStaticPeeringLayout returns a new static peering layout with 4 nodes which are all statically peered to each other.

func ShutdownNetwork 

func ShutdownNetwork(t *testing.T, n Shutdowner)

ShutdownNetwork shuts down the network and reports errors.

Types

type AutopeeredNetwork 

type AutopeeredNetwork struct {
	*Network
	// contains filtered or unexported fields
}

AutopeeredNetwork is a network consisting out of autopeered nodes. It contains additionally an entry node.

func (*AutopeeredNetwork) AwaitPeering 

func (n *AutopeeredNetwork) AwaitPeering(minimumPeers int) error

AwaitPeering waits until all peers have reached the minimum amount of peers. Returns error if this minimum is not reached after autopeeringMaxTries.

func (*AutopeeredNetwork) CreatePeer 

func (n *AutopeeredNetwork) CreatePeer(cfg *NodeConfig) (*Node, error)

CreatePeer creates a new HORNET node initialized with the right entry node.

func (*AutopeeredNetwork) DeletePartitions 

func (n *AutopeeredNetwork) DeletePartitions() error

DeletePartitions deletes all partitions of the network. All nodes can communicate with the full network again.

func (*AutopeeredNetwork) Partitions 

func (n *AutopeeredNetwork) Partitions() []*Partition

Partitions returns the network's partitions.

func (*AutopeeredNetwork) Shutdown 

func (n *AutopeeredNetwork) Shutdown() error

Shutdown shuts down the network.

func (*AutopeeredNetwork) Split 

func (n *AutopeeredNetwork) Split(partitions ...[]*Node) error

Split splits the existing network in given partitions.

type CfgOverrideFunc 

type CfgOverrideFunc func(index int, cfg *NodeConfig)

CfgOverrideFunc is a function which overrides configuration values.

type CoordinatorConfig 

type CoordinatorConfig struct {
	// Whether to let the node run as the coordinator.
	RunAsCoo bool
	// The coo private keys.
	PrivateKeys []string
	// Whether to run the coordinator in bootstrap node.
	Bootstrap bool
	// The interval in which to issue new milestones.
	IssuanceInterval time.Duration
}

CoordinatorConfig defines coordinator specific configuration.

func DefaultCoordinatorConfig 

func DefaultCoordinatorConfig() CoordinatorConfig

DefaultCoordinatorConfig returns the default coordinator config.

func (*CoordinatorConfig) CLIFlags 

func (cooConfig *CoordinatorConfig) CLIFlags() []string

CLIFlags returns the config as CLI flags.

type DashboardConfig 

type DashboardConfig struct {
	// The bind address of the dashboard
	BindAddress string
}

DashboardConfig holds the dashboard specific configuration.

func DefaultDashboardConfig 

func DefaultDashboardConfig() DashboardConfig

DefaultDashboardConfig returns the default profiling config.

func (*DashboardConfig) CLIFlags 

func (dashboardConfig *DashboardConfig) CLIFlags() []string

CLIFlags returns the config as CLI flags.

type DebugNodeAPIClient added in v1.0.0 

type DebugNodeAPIClient struct {
	*iotago.NodeHTTPAPIClient
}

DebugNodeAPIClient is an API wrapper over the debug node API.

func NewDebugNodeAPIClient added in v1.0.0 

func NewDebugNodeAPIClient(baseURL string, opts ...iotago.NodeHTTPAPIClientOption) *DebugNodeAPIClient

NewDebugNodeAPIClient returns a new debug node API instance.

func (*DebugNodeAPIClient) BaseURL added in v1.0.0 

func (api *DebugNodeAPIClient) BaseURL() string

BaseURL returns the baseURL of the API.

type DockerContainer 

type DockerContainer struct {
	// contains filtered or unexported fields
}

DockerContainer is a wrapper object for a Docker container.

func NewDockerContainer 

func NewDockerContainer(c *client.Client) *DockerContainer

NewDockerContainer creates a new DockerContainer.

func NewDockerContainerFromExisting 

func NewDockerContainerFromExisting(c *client.Client, name string) (*DockerContainer, error)

NewDockerContainerFromExisting creates a new DockerContainer from an already existing Docker container by name.

func (*DockerContainer) ConnectToNetwork 

func (d *DockerContainer) ConnectToNetwork(networkID string) error

ConnectToNetwork connects a container to an existent network in the docker host.

func (*DockerContainer) CreateContainer 

func (d *DockerContainer) CreateContainer(name string, containerConfig *container.Config, hostConfigs ...*container.HostConfig) error

CreateContainer creates a new container with the given configuration.

func (*DockerContainer) CreateNodeContainer 

func (d *DockerContainer) CreateNodeContainer(cfg *NodeConfig) error

CreateNodeContainer creates a new node container.

func (*DockerContainer) CreatePumbaContainer 

func (d *DockerContainer) CreatePumbaContainer(name string, containerName string, targetIPs []string) error

CreatePumbaContainer creates a new container with Pumba configuration.

func (*DockerContainer) CreateWhiteFlagMockContainer added in v1.0.0 

func (d *DockerContainer) CreateWhiteFlagMockContainer(cfg *WhiteFlagMockServerConfig) error

CreateWhiteFlagMockContainer creates a new white-flag mock container.

func (*DockerContainer) DisconnectFromNetwork 

func (d *DockerContainer) DisconnectFromNetwork(networkID string) error

DisconnectFromNetwork disconnects a container from an existent network in the docker host.

func (*DockerContainer) ExitStatus 

func (d *DockerContainer) ExitStatus() (int, error)

ExitStatus returns the exit status according to the container information.

func (*DockerContainer) IP 

func (d *DockerContainer) IP(network string) (string, error)

IP returns the IP address according to the container information for the given network.

func (*DockerContainer) Logs 

func (d *DockerContainer) Logs() (io.ReadCloser, error)

Logs returns the logs of the container as io.ReadCloser.

func (*DockerContainer) Remove 

func (d *DockerContainer) Remove() error

Remove kills and removes a container from the docker host.

func (*DockerContainer) Start 

func (d *DockerContainer) Start() error

Start sends a request to the docker daemon to start a container.

func (*DockerContainer) Stop 

func (d *DockerContainer) Stop(optionalTimeout ...time.Duration) error

Stop stops a container without terminating the process. The process is blocked until the container stops or the timeout expires.

type Framework 

type Framework struct {
	// contains filtered or unexported fields
}

Framework is a wrapper that provides the integration testing functionality.

func Instance 

func Instance() (f *Framework, err error)

Instance returns the singleton Framework instance.

func (*Framework) CreateAutopeeredNetwork 

func (f *Framework) CreateAutopeeredNetwork(name string, peerCount int, minimumPeers int, cfgOverrideF ...CfgOverrideFunc) (*AutopeeredNetwork, error)

CreateAutopeeredNetwork creates a network consisting out of peersCount nodes. It waits for the nodes to autopeer until the minimum peers criteria is met for every node.

func (*Framework) CreateNetworkWithPartitions 

func (f *Framework) CreateNetworkWithPartitions(name string, peerCount, partitions, minimumPeers int, cfgOverrideF ...CfgOverrideFunc) (*AutopeeredNetwork, error)

CreateNetworkWithPartitions creates a network consisting out of partitions that contain peerCount nodes per partition. It waits for the peers to autopeer until the minimum peers criteria is met for every peer. The entry node is reachable by all nodes at all times.

func (*Framework) CreateStaticNetwork 

func (f *Framework) CreateStaticNetwork(name string, intNetCfg *IntegrationNetworkConfig, layout StaticPeeringLayout, cfgOverrideF ...CfgOverrideFunc) (*StaticNetwork, error)

CreateStaticNetwork creates a network made out of statically peered nodes by the given layout. The first node is initialized with the Coordinator plugin enabled.

type IntegrationNetworkConfig added in v1.0.0 

type IntegrationNetworkConfig struct {
	// Whether the network should have a white-flag mock server running.
	SpawnWhiteFlagMockServer bool
	// The config to use for the white-flag mock server.
	WhiteFlagMockServerConfig *WhiteFlagMockServerConfig
}

IntegrationNetworkConfig holds configuration for a network.

type MigratorConfig added in v1.0.0 

type MigratorConfig struct {
	// The max amount of entries to include in a receipt.
	MaxEntries int
	// Whether to run the migrator plugin in bootstrap mode.
	Bootstrap bool
	// The index of the first legacy milestone to migrate.
	StartIndex int
	// The state file path.
	StateFilePath string
}

MigratorConfig defines migrator plugin specific configuration.

func DefaultMigratorConfig added in v1.0.0 

func DefaultMigratorConfig() MigratorConfig

DefaultMigratorConfig returns the default migrator plugin config.

func (*MigratorConfig) CLIFlags added in v1.0.0 

func (migConfig *MigratorConfig) CLIFlags() []string

CLIFlags returns the config as CLI flags.

type Network 

type Network struct {
	// The ID of the network.
	ID string
	// the type of the network.
	NetworkType NetworkType
	// The name of the network.
	Name string
	// The nodes within the network in the order in which they were spawned.
	Nodes []*Node
	// The white-flag mock server if one was started.
	WhiteFlagMockServer *DockerContainer
	// contains filtered or unexported fields
}

Network is a network consisting out of HORNET nodes.

func (*Network) AwaitAllSync 

func (n *Network) AwaitAllSync(ctx context.Context) error

AwaitAllSync awaits until all nodes see themselves as synced.

func (*Network) AwaitOnline 

func (n *Network) AwaitOnline(ctx context.Context) error

AwaitOnline awaits until all nodes are online or the given context is canceled.

func (*Network) Coordinator 

func (n *Network) Coordinator() *Node

Coordinator returns the node with the coordinator plugin enabled.

func (*Network) CreateNode 

func (n *Network) CreateNode(cfg *NodeConfig) (*Node, error)

CreateNode creates a new HORNET node in the network and returns it.

func (*Network) CreateWhiteFlagMockServer added in v1.0.0 

func (n *Network) CreateWhiteFlagMockServer(cfg *WhiteFlagMockServerConfig) error

CreateWhiteFlagMockServer creates a new white-flag moc kserver in the network.

func (*Network) PrefixName 

func (n *Network) PrefixName(suffix string) string

PrefixName returns the suffix prefixed with the name.

func (*Network) RandomNode 

func (n *Network) RandomNode() *Node

RandomNode returns a random peer out of the list of peers.

func (*Network) Shutdown 

func (n *Network) Shutdown() error

Shutdown stops all nodes, persists their container logs and removes them from Docker.

func (*Network) SpamZeroVal 

func (n *Network) SpamZeroVal(dur time.Duration, parallelism int) error

SpamZeroVal starts spamming zero value messages on all nodes for the given duration.

func (*Network) TakeCPUProfiles 

func (n *Network) TakeCPUProfiles(dur time.Duration) error

TakeCPUProfile takes a CPU profile on all nodes within the network.

func (*Network) TakeHeapSnapshots 

func (n *Network) TakeHeapSnapshots() error

TakeHeapSnapshot takes a heap snapshot on all nodes within the network.

type NetworkConfig 

type NetworkConfig struct {
	// the private key used to derive the node identity.
	IdentityPrivKey string
	// the bind addresses of this node.
	BindMultiAddresses []string
	// the path to the peerstore.
	PeerStorePath string
	// the high watermark to use within the connection manager.
	ConnMngHighWatermark int
	// the low watermark to use within the connection manager.
	ConnMngLowWatermark int
	// the static peers this node should retain a connection to.
	Peers []string
	// aliases of the static peers.
	PeerAliases []string
	// time to wait before trying to reconnect to a disconnected peer.
	ReconnectInterval time.Duration
	// the maximum amount of unknown peers a gossip protocol connection is established to
	GossipUnknownPeersLimit int
}

NetworkConfig defines the network specific configuration.

func DefaultNetworkConfig 

func DefaultNetworkConfig() NetworkConfig

DefaultNetworkConfig returns the default network config.

func (*NetworkConfig) CLIFlags 

func (netConfig *NetworkConfig) CLIFlags() []string

CLIFlags returns the config as CLI flags.

type NetworkType 

type NetworkType byte
const (
	// Defines a network which consists out of autopeered nodes.
	NetworkTypeAutopeered NetworkType = iota
	// Defines a network which consists out of statically peered nodes.
	NetworkTypeStatic
)

type Node 

type Node struct {
	// Name of the node derived from the container and hostname.
	Name string
	// the IP address of this node within the network.
	IP string
	// The configuration with which the node was started.
	Config *NodeConfig
	// The libp2p identifier of the peer.
	ID peer.ID
	// The iota.go web API instance with additional information used to communicate with the node.
	DebugNodeAPIClient *DebugNodeAPIClient
	// The profiler instance.
	Profiler
	// The DockerContainer that this peer is running in
	*DockerContainer
	// contains filtered or unexported fields
}

Node represents a HORNET node inside the Docker network.

func (*Node) APIURI 

func (p *Node) APIURI() string

APIURI returns the URL under which this node's web API is accessible.

func (*Node) SetPeers added in v1.0.0 

func (p *Node) SetPeers(peers []*iotago.PeerResponse)

SetPeers sets the peers of the peer accordingly.

func (*Node) Spam 

func (p *Node) Spam(dur time.Duration, parallelism int) (int32, error)

Spam spams zero value transactions on the node. Returns the number of spammed transactions.

func (*Node) String 

func (p *Node) String() string

func (*Node) TotalPeers added in v1.0.0 

func (p *Node) TotalPeers() int

TotalPeers returns the total number of peers the peer has.

type NodeConfig 

type NodeConfig struct {
	// The name of this node.
	Name string
	// Environment variables.
	Envs []string
	// Binds for the container.
	Binds []string
	// Exposed ports of this container.
	ExposedPorts nat.PortSet
	// Network config.
	Network NetworkConfig
	// Web API config.
	RestAPI RestAPIConfig
	// Snapshot config.
	Snapshot SnapshotConfig
	// Coordinator config.
	Coordinator CoordinatorConfig
	// Protocol config.
	Protocol ProtocolConfig
	// Plugin config.
	Plugins PluginConfig
	// Profiling config.
	Profiling ProfilingConfig
	// Dashboard config.
	Dashboard DashboardConfig
	// Receipts config
	Receipts ReceiptsConfig
	// Migrator config.
	Migrator MigratorConfig
}

NodeConfig defines the config of a HORNET node.

func DefaultConfig 

func DefaultConfig() *NodeConfig

DefaultConfig returns the default NodeConfig.

func (*NodeConfig) AsCoo 

func (cfg *NodeConfig) AsCoo()

AsCoo adjusts the config to make it usable as the Coordinator's config.

func (*NodeConfig) CLIFlags 

func (cfg *NodeConfig) CLIFlags() []string

CLIFlags returns the config as CLI flags.

func (*NodeConfig) WithMigration added in v1.0.0 

func (cfg *NodeConfig) WithMigration()

WithMigrator adjusts the config to activate the migrator plugin.

type Partition 

type Partition struct {
	// contains filtered or unexported fields
}

Partition represents a network partition. It contains its peers and the corresponding Pumba instances that block all traffic to peers in other partitions.

func (*Partition) Peers 

func (p *Partition) Peers() []*Node

Nodes returns the partition's peers.

func (*Partition) PeersMap 

func (p *Partition) PeersMap() map[string]*Node

PeersMap returns the partition's peers map.

func (*Partition) String 

func (p *Partition) String() string

type PluginConfig 

type PluginConfig struct {
	// Holds explicitly enabled plugins.
	Enabled []string
	// Holds explicitly disabled plugins.
	Disabled []string
}

PluginConfig defines plugin specific configuration.

func DefaultPluginConfig 

func DefaultPluginConfig() PluginConfig

DefaultPluginConfig returns the default plugin config.

func (*PluginConfig) CLIFlags 

func (pluginConfig *PluginConfig) CLIFlags() []string

CLIFlags returns the config as CLI flags.

type Profiler 

type Profiler struct {
	http.Client
	// contains filtered or unexported fields
}

Profiler profiles a node for metrics.

func (*Profiler) GraphMetrics 

func (n *Profiler) GraphMetrics(dur time.Duration) error

GraphMetrics graphs metrics about MPS, memory consumption, confirmation rate of the node and saves it into the log dir.

func (*Profiler) TakeCPUProfile 

func (n *Profiler) TakeCPUProfile(dur time.Duration) error

TakeCPUProfile takes a CPU profile for the given duration and then saves it to the log directory.

func (*Profiler) TakeHeapSnapshot 

func (n *Profiler) TakeHeapSnapshot() error

TakeHeapSnapshot takes a snapshot of the heap memory and then saves it to the log directory.

type ProfilingConfig 

type ProfilingConfig struct {
	// The bind address of the pprof server.
	BindAddress string
}

ProfilingConfig defines the profiling specific configuration.

func DefaultProfilingConfig 

func DefaultProfilingConfig() ProfilingConfig

DefaultProfilingConfig returns the default profiling config.

func (*ProfilingConfig) CLIFlags 

func (profilingConfig *ProfilingConfig) CLIFlags() []string

CLIFlags returns the config as CLI flags.

type ProtocolConfig added in v1.0.0 

type ProtocolConfig struct {
	// The minimum PoW score needed.
	MinPoWScore float64
	// The coo public key ranges.
	PublicKeyRanges []coopkg.PublicKeyRange
	// The network ID on which this node operates on.
	NetworkIDName string
}

ProtocolConfig defines protocol specific configuration.

func DefaultProtocolConfig added in v1.0.0 

func DefaultProtocolConfig() ProtocolConfig

DefaultProtocolConfig returns the default protocol config.

func (*ProtocolConfig) CLIFlags added in v1.0.0 

func (protoConfig *ProtocolConfig) CLIFlags() []string

CLIFlags returns the config as CLI flags.

type ReceiptsConfig added in v1.0.0 

type ReceiptsConfig struct {
	// Whether receipt backups are enabled.
	BackupEnabled bool
	// The path to the receipts folder.
	BackupFolder string
	// Whether the receipts plugin should validate receipts
	Validate bool
	// Whether to ignore soft errors or not.
	IgnoreSoftErrors bool
	// The API to query.
	APIAddress string
	// The API timeout.
	APITimeout time.Duration
	// Legacy Coordinator address
	CoordinatorAddress string
	// The merkle tree depth.
	CoordinatorMerkleTreeDepth int
}

ReceiptsConfig defines the receipt validator plugin specific configuration.

func DefaultReceiptValidatorConfig added in v1.0.0 

func DefaultReceiptValidatorConfig() ReceiptsConfig

DefaultReceiptValidatorConfig returns the default migrator plugin config.

func (*ReceiptsConfig) CLIFlags added in v1.0.0 

func (receiptsConfig *ReceiptsConfig) CLIFlags() []string

type RestAPIConfig added in v1.0.0 

type RestAPIConfig struct {
	// The bind address for the REST API.
	BindAddress string
	// Explicit permitted REST API routes.
	PermittedRoutes []string
	// Whether the node does proof-of-work for submitted messages.
	PoWEnabled bool
}

RestAPIConfig defines the REST API specific configuration.

func DefaultRestAPIConfig added in v1.0.0 

func DefaultRestAPIConfig() RestAPIConfig

DefaultRestAPIConfig returns the default REST API config.

func (*RestAPIConfig) CLIFlags added in v1.0.0 

func (restAPIConfig *RestAPIConfig) CLIFlags() []string

CLIFlags returns the config as CLI flags.

type Shutdowner 

type Shutdowner interface {
	Shutdown() error
}

Shutdowner can shutdown itself.

type SnapshotConfig 

type SnapshotConfig struct {
	// The path to the full snapshot file.
	FullSnapshotFilePath string
	// the path to the delta snapshot file.
	DeltaSnapshotFilePath string
}

SnapshotConfig defines snapshot specific configuration.

func DefaultSnapshotConfig 

func DefaultSnapshotConfig() SnapshotConfig

DefaultSnapshotConfig returns the default snapshot config.

func (*SnapshotConfig) CLIFlags 

func (snapshotConfig *SnapshotConfig) CLIFlags() []string

CLIFlags returns the config as CLI flags.

type StaticNetwork 

type StaticNetwork struct {
	*Network
	// contains filtered or unexported fields
}

StaticNetwork defines a network made out of statically peered nodes.

func (*StaticNetwork) AwaitPeering 

func (n *StaticNetwork) AwaitPeering(ctx context.Context) error

AwaitPeering awaits until all nodes are peered according to the peering layout.

func (*StaticNetwork) ConnectNodes 

func (n *StaticNetwork) ConnectNodes() error

ConnectNodes peers the nodes of the network according to the given layout with each other.

type StaticPeeringLayout 

type StaticPeeringLayout map[int]map[int]connected

StaticPeeringLayout defines how in a statically peered network nodes are peered to each other.

func (StaticPeeringLayout) Validate 

func (spl StaticPeeringLayout) Validate() error

Validate validates whether the static peering layout is valid by checking:

  • the layout isn't empty
  • keys must be continuous numbers reflecting the ID of the node
  • a node must hold nodes to peer to and they must exist in the map
  • a node doesn't peer to itself

type WhiteFlagMockServerConfig added in v1.0.0 

type WhiteFlagMockServerConfig struct {
	// The name for this white-flag mock server.
	Name string
	// environment variables.
	Envs []string
	// Binds for the container.
	Binds []string
}

WhiteFlagMockServerConfig defines the config for a white-flag mock server instance.

func DefaultWhiteFlagMockServerConfig added in v1.0.0 

func DefaultWhiteFlagMockServerConfig(configFileName string) *WhiteFlagMockServerConfig

DefaultWhiteFlagMockServerConfig returns the default WhiteFlagMockServerConfig.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.