framework

package
v2.0.1 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2023 License: Apache-2.0 Imports: 32 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 (
	// RestAPIPort defines the default REST API port of every node.
	RestAPIPort = 14265
)

Variables

View Source 
var (
	// GenesisSeed defines the seed on which the total supply resides on per default.
	GenesisSeed ed25519.PrivateKey
	// GenesisAddress defines the address computed from the GenesisSeed.
	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 AppConfig 

type AppConfig 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
	// INX config.
	INX INXConfig
	// Snapshot config.
	Snapshot SnapshotConfig
	// Protocol config.
	Protocol ProtocolConfig
	// Profiling config.
	Profiling ProfilingConfig
	// Receipts config
	Receipts ReceiptsConfig
	// Autopeering config.
	Autopeering AutopeeringConfig
	// INXCoo inx-coordinator config.
	INXCoo *INXCoordinatorConfig
}

AppConfig defines the config of a HORNET node.

func DefaultConfig 

func DefaultConfig() *AppConfig

DefaultConfig returns the default AppConfig.

func (*AppConfig) AsCoo 

func (cfg *AppConfig) AsCoo()

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

func (*AppConfig) CLIFlags 

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

CLIFlags returns the config as CLI flags.

func (*AppConfig) WithReceipts 

func (cfg *AppConfig) WithReceipts()

WithReceipts adjusts the config to activate the receipts plugin.

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 *AppConfig) (*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 

type AutopeeringConfig struct {
	// Enabled defines whether the autopeering plugin is enabled.
	Enabled bool
	// The list 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 

func DefaultAutopeeringConfig() AutopeeringConfig

DefaultAutopeeringConfig returns the default autopeering config.

func (*AutopeeringConfig) CLIFlags 

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

CLIFlags returns the config as CLI flags.

type CfgOverrideFunc 

type CfgOverrideFunc func(index int, cfg *AppConfig)

CfgOverrideFunc is a function which overrides configuration values.

type Connected 

type Connected bool

Connected is a bool whether nodes are Connected or not.

type CoordinatorConfig 

type CoordinatorConfig struct {
	// 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
	// Block Backups Enabled.
	BlockBackupsEnabled bool
}

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 DebugNodeAPIClient 

type DebugNodeAPIClient struct {
	*nodeclient.Client
}

DebugNodeAPIClient is an API wrapper over the debug node API.

func NewDebugNodeAPIClient 

func NewDebugNodeAPIClient(baseURL string, opts ...nodeclient.ClientOption) *DebugNodeAPIClient

NewDebugNodeAPIClient returns a new debug node API instance.

func (*DebugNodeAPIClient) BalanceByAddress 

func (api *DebugNodeAPIClient) BalanceByAddress(ctx context.Context, addr iotago.Address) (uint64, error)

func (*DebugNodeAPIClient) BaseURL 

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) CreateCoordinatorContainer 

func (d *DockerContainer) CreateCoordinatorContainer(cfg *INXCoordinatorConfig) error

CreateCoordinatorContainer creates a new coordinator container.

func (*DockerContainer) CreateIndexerContainer 

func (d *DockerContainer) CreateIndexerContainer(cfg *INXIndexerConfig) error

CreateIndexerContainer creates a new indexer container.

func (*DockerContainer) CreateNodeContainer 

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

CreateNodeContainer creates a new node container.

func (*DockerContainer) CreateWhiteFlagMockContainer 

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 INXConfig 

type INXConfig struct {
	// Enabled defines whether the INX plugin is enabled.
	Enabled bool
	// The bind address for the INX.
	BindAddress string
}

INXConfig defines the INX specific configuration.

func DefaultINXConfig 

func DefaultINXConfig() INXConfig

DefaultINXConfig returns the default INX config.

func (*INXConfig) CLIFlags 

func (inxConfig *INXConfig) CLIFlags() []string

CLIFlags returns the config as CLI flags.

type INXCoordinatorConfig 

type INXCoordinatorConfig struct {
	// Whether to let the node run as the coordinator.
	RunAsCoo bool
	// The name of this node.
	Name string
	// Environment variables.
	Envs []string
	// Binds for the container.
	Binds []string
	// INXAddress is the INX address of the node.
	INXAddress string
	// Coordinator config.
	Coordinator CoordinatorConfig
	// Migrator config.
	Migrator MigratorConfig
	// Receipt validator config.
	Validator ReceiptValidatorConfig
}

func DefaultINXCoordinatorConfig 

func DefaultINXCoordinatorConfig() *INXCoordinatorConfig

DefaultINXCoordinatorConfig returns the default INX coordinator config.

func (*INXCoordinatorConfig) CLIFlags 

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

CLIFlags returns the config as CLI flags.

func (*INXCoordinatorConfig) WithMigration 

func (cfg *INXCoordinatorConfig) WithMigration()

WithMigration adjusts the config to activate the migrator plugin.

type INXExtension 

type INXExtension struct {
	Name string
	IP   string
	*DockerContainer
}

type INXIndexerConfig 

type INXIndexerConfig struct {
	// The name of this node.
	Name string
	// Environment variables.
	Envs []string
	// Binds for the container.
	Binds       []string
	INXAddress  string
	BindAddress string
}

INXIndexerConfig defines the config of an INX-Indexer.

func DefaultINXIndexerConfig 

func DefaultINXIndexerConfig() *INXIndexerConfig

func (*INXIndexerConfig) CLIFlags 

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

type IntegrationNetworkConfig 

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 

type MigratorConfig struct {
	// Enabled defines whether the migrator plugin is enabled.
	Enabled bool
	// 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 

func DefaultMigratorConfig() MigratorConfig

DefaultMigratorConfig returns the default migrator plugin config.

func (*MigratorConfig) CLIFlags 

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 containers running INX extensions in the network.
	INXExtensions []*INXExtension
	// 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) CreateCoordinator 

func (n *Network) CreateCoordinator(cfg *INXCoordinatorConfig) (*INXExtension, error)

CreateCoordinator creates a new INX-Coordinator in the network.

func (*Network) CreateIndexer 

func (n *Network) CreateIndexer(cfg *INXIndexerConfig) (*INXExtension, error)

CreateIndexer creates a new INX-Indexer in the network.

func (*Network) CreateNode 

func (n *Network) CreateNode(cfg *AppConfig, optPrvKey ...crypto.PrivKey) (*Node, error)

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

func (*Network) CreateWhiteFlagMockServer 

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 blocks 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 (
	// NetworkTypeAutopeered defines a network which consists out of autopeered nodes.
	NetworkTypeAutopeered NetworkType = iota
	// NetworkTypeStatic 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 *AppConfig
	// 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 

func (p *Node) SetPeers(peers []*nodeclient.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 

func (p *Node) TotalPeers() int

TotalPeers returns the total number of peers the peer has.

type Profiler 

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

Profiler profiles a node for metrics.

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 

type ProtocolConfig struct {
	// The initial network name on which this node operates on.
	TargetNetworkName string
	// The amount of public keys in a milestone.
	MilestonePublicKeyCount int
	// The coo public key ranges.
	PublicKeyRanges []protocfg.ConfigPublicKeyRange
}

ProtocolConfig defines protocol specific configuration.

func DefaultProtocolConfig 

func DefaultProtocolConfig() ProtocolConfig

DefaultProtocolConfig returns the default protocol config.

func (*ProtocolConfig) CLIFlags 

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

CLIFlags returns the config as CLI flags.

type ReceiptValidatorConfig 

type ReceiptValidatorConfig struct {
	// The API to query.
	APIAddress string
	// The API timeout.
	APITimeout time.Duration
	// Legacy Coordinator address
	CoordinatorAddress string
	// The merkle tree depth.
	CoordinatorMerkleTreeDepth int
}

func DefaultReceiptValidatorConfig 

func DefaultReceiptValidatorConfig() ReceiptValidatorConfig

DefaultReceiptValidatorConfig returns the default receipt validator config.

func (*ReceiptValidatorConfig) CLIFlags 

func (validatorConfig *ReceiptValidatorConfig) CLIFlags() []string

type ReceiptsConfig 

type ReceiptsConfig struct {
	// Enabled defines whether the receipts plugin is enabled.
	Enabled bool
	// 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 validator config
	Validator ReceiptValidatorConfig
}

ReceiptsConfig defines the receipt validator plugin specific configuration.

func DefaultNodeReceiptValidatorConfig 

func DefaultNodeReceiptValidatorConfig() ReceiptsConfig

func (*ReceiptsConfig) CLIFlags 

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

type RestAPIConfig 

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 blocks.
	PoWEnabled bool
}

RestAPIConfig defines the REST API specific configuration.

func DefaultRestAPIConfig 

func DefaultRestAPIConfig() RestAPIConfig

DefaultRestAPIConfig returns the default REST API config.

func (*RestAPIConfig) CLIFlags 

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 

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 

func DefaultWhiteFlagMockServerConfig(name string, 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.