framework

package
v1.2.8 Latest Latest
Warning

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

 Go to latest Published: Aug 11, 2023 License: Apache-2.0 Imports: 50 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) Shutdown 

func (n *AutopeeredNetwork) Shutdown() error

Shutdown shuts down the network.

type AutopeeringConfig added in v1.2.2 

type AutopeeringConfig struct {
	// The ist of autopeering entry nodes to use.
	EntryNodes []string
	// BindAddr bind address for autopeering.
	BindAddr string
	// Whether the node should act as an autopeering entry node.
	RunAsEntryNode bool
	// The max number of inbound autopeers.
	InboundPeers int
	// The max the number of outbound autopeers.
	OutboundPeers int
	// The lifetime of the private and public local salt.
	SaltLifetime time.Duration
}

AutopeeringConfig defines the autopeering specific configuration.

func DefaultAutopeeringConfig added in v1.2.2 

func DefaultAutopeeringConfig() AutopeeringConfig

DefaultAutopeeringConfig returns the default autopeering config.

func (*AutopeeringConfig) CLIFlags added in v1.2.2 

func (autoConfig *AutopeeringConfig) CLIFlags() []string

CLIFlags returns the config as CLI flags.

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.2.2 

type DebugNodeAPIClient struct {
	*iotago.NodeHTTPAPIClient
}

DebugNodeAPIClient is an API wrapper over the debug node API.

func NewDebugNodeAPIClient added in v1.2.2 

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

NewDebugNodeAPIClient returns a new debug node API instance.

func (*DebugNodeAPIClient) BaseURL added in v1.2.2 

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.2.2 

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) 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.2.2 

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.2.2 

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.2.2 

func DefaultMigratorConfig() MigratorConfig

DefaultMigratorConfig returns the default migrator plugin config.

func (*MigratorConfig) CLIFlags added in v1.2.2 

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, optPrvKey ...crypto.PrivKey) (*Node, error)

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

func (*Network) CreateWhiteFlagMockServer added in v1.2.2 

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

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

func (*Network) TakeHeapSnapshots 

func (n *Network) TakeHeapSnapshots() error

TakeHeapSnapshots 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 p2p database.
	DatabasePath 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.2.2 

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.2.2 

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
	// Autopeering config.
	Autopeering AutopeeringConfig
}

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.2.2 

func (cfg *NodeConfig) WithMigration()

WithMigration adjusts the config to activate the migrator plugin.

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.2.2 

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.2.2 

func DefaultProtocolConfig() ProtocolConfig

DefaultProtocolConfig returns the default protocol config.

func (*ProtocolConfig) CLIFlags added in v1.2.2 

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

CLIFlags returns the config as CLI flags.

type ReceiptsConfig added in v1.2.2 

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.2.2 

func DefaultReceiptValidatorConfig() ReceiptsConfig

DefaultReceiptValidatorConfig returns the default migrator plugin config.

func (*ReceiptsConfig) CLIFlags added in v1.2.2 

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

type RestAPIConfig added in v1.2.2 

type RestAPIConfig struct {
	// The bind address for the REST API.
	BindAddress string
	// Public REST API routes.
	PublicRoutes []string
	// Protected REST API routes.
	ProtectedRoutes []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.2.2 

func DefaultRestAPIConfig() RestAPIConfig

DefaultRestAPIConfig returns the default REST API config.

func (*RestAPIConfig) CLIFlags added in v1.2.2 

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.2.2 

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.2.2 

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.