libhive

package
v0.0.0-...-cad05e3 Latest Latest
Warning

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

 Go to latest Published: Feb 10, 2025 License: GPL-3.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNoSuchNode               = errors.New("no such node")
	ErrNoSuchTestSuite          = errors.New("no such test suite")
	ErrNoSuchTestCase           = errors.New("no such test case")
	ErrMissingClientType        = errors.New("missing client type")
	ErrNoAvailableClients       = errors.New("no available clients")
	ErrTestSuiteRunning         = errors.New("test suite still has running tests")
	ErrMissingOutputDestination = errors.New("test suite requires an output")
	ErrNoSummaryResult          = errors.New("test case must be ended with a summary result")
	ErrDBUpdateFailed           = errors.New("could not update results set")
	ErrTestSuiteLimited         = errors.New("testsuite test count is limited")
)
View Source 
var ErrNetworkNotFound = fmt.Errorf("network not found")

This error is returned by NetworkNameToID if a docker network is not present.

Functions

This section is empty.

Types

type APIServer 

type APIServer interface {
	Addr() net.Addr // returns the listening address of the HTTP server
	Close() error   // stops the server
}

APIServer is a handle for the HTTP API server.

type Builder 

type Builder interface {
	BuildClientImage(ctx context.Context, client ClientDesignator) (string, error)
	BuildSimulatorImage(ctx context.Context, name string, buildArgs map[string]string) (string, error)
	BuildImage(ctx context.Context, name string, fsys fs.FS) error

	// ReadFile returns the content of a file in the given image.
	ReadFile(ctx context.Context, image, path string) ([]byte, error)
}

Builder can build docker images of clients and simulators.

type ClientDefinition 

type ClientDefinition struct {
	Name    string         `json:"name"`
	Version string         `json:"version"`
	Image   string         `json:"-"` // not exposed via API
	Meta    ClientMetadata `json:"meta"`
}

ClientDefinition is served by the /clients API endpoint to list the available clients

type ClientDesignator 

type ClientDesignator struct {
	// Client is the client name.
	// This must refer to a subdirectory of clients/
	Client string `yaml:"client" json:"client"`

	// Nametag is used in the name of the client image.
	// This is for assigning meaningful names to different builds of the same client.
	// If unspecified, a default value is chosen to make client names unique.
	Nametag string `yaml:"nametag,omitempty" json:"nametag,omitempty"`

	// DockerfileExt is the extension of the Docker that should be used to build the
	// client. Example: setting this to "git" will build using "Dockerfile.git".
	DockerfileExt string `yaml:"dockerfile,omitempty" json:"dockerfile,omitempty"`

	// Arguments passed to the docker build.
	BuildArgs map[string]string `yaml:"build_args,omitempty" json:"build_args,omitempty"`
}

ClientDesignator specifies a client and build parameters for it.

func FilterClients 

func FilterClients(list []ClientDesignator, filter []string) []ClientDesignator

FilterClients trims the given list to only include clients matching the 'filter list'.

func ParseClientList 

func ParseClientList(inv *Inventory, arg string) ([]ClientDesignator, error)

ParseClientList reads a comma-separated list of client names. Each client name may optionally contain a branch/tag specifier separated from the name by underscore, e.g. "besu_nightly".

func ParseClientListYAML 

func ParseClientListYAML(inv *Inventory, file io.Reader) ([]ClientDesignator, error)

ParseClientListYAML reads a YAML document containing a list of clients.

func (ClientDesignator) Dockerfile 

func (c ClientDesignator) Dockerfile() string

Dockerfile gives the name of the Dockerfile to use when building the client.

func (ClientDesignator) Name 

func (c ClientDesignator) Name() string

Name returns the full client name including nametag.

type ClientInfo 

type ClientInfo struct {
	ID             string    `json:"id"`
	IP             string    `json:"ip"`
	Name           string    `json:"name"`
	InstantiatedAt time.Time `json:"instantiatedAt"`
	LogFile        string    `json:"logFile"` //Absolute path to the logfile.
	// contains filtered or unexported fields
}

ClientInfo describes a client that participated in a test case.

type ClientMetadata 

type ClientMetadata struct {
	Roles []string `yaml:"roles" json:"roles"`
}

ClientMetadata is metadata to describe the client in more detail, configured with a YAML file in the client dir.

type ContainerBackend 

type ContainerBackend interface {
	// Build is a hook allowing ContainerBackend to build internal helper images.
	// This is called before anything else in the simulation run.
	Build(context.Context, Builder) error

	// This is for launching the simulation API server.
	ServeAPI(context.Context, http.Handler) (APIServer, error)

	// These methods work with containers.
	CreateContainer(ctx context.Context, image string, opt ContainerOptions) (string, error)
	StartContainer(ctx context.Context, containerID string, opt ContainerOptions) (*ContainerInfo, error)
	DeleteContainer(containerID string) error
	PauseContainer(containerID string) error
	UnpauseContainer(containerID string) error

	// RunProgram runs a command in the given container and returns its outputs and exit code.
	RunProgram(ctx context.Context, containerID string, cmdline []string) (*ExecInfo, error)

	// These methods configure docker networks.
	NetworkNameToID(name string) (string, error)
	CreateNetwork(name string) (string, error)
	RemoveNetwork(id string) error
	ContainerIP(containerID, networkID string) (net.IP, error)
	ConnectContainer(containerID, networkID string) error
	DisconnectContainer(containerID, networkID string) error
}

ContainerBackend captures the docker interactions of the simulation API.

type ContainerInfo 

type ContainerInfo struct {
	ID      string // docker container ID
	IP      string // IP address
	MAC     string // MAC address. TODO: remove
	LogFile string

	// The wait function returns when the container is stopped.
	// This must be called for all containers that were started
	// to avoid resource leaks.
	Wait func()
}

ContainerInfo is returned by StartContainer.

type ContainerOptions 

type ContainerOptions struct {
	Env   map[string]string
	Files map[string]*multipart.FileHeader

	// This requests checking for the given TCP port to be opened by the container.
	CheckLive uint16

	// Output: if LogFile is set, container stdin and stderr is redirected to the
	// given log file. If Output is set, stdout is redirected to the writer. These
	// options are mutually exclusive.
	LogFile string
	Output  io.WriteCloser

	// Input: if set, container stdin draws from the given reader.
	Input io.ReadCloser
}

ContainerOptions contains the launch parameters for docker containers.

type ExecInfo 

type ExecInfo struct {
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
	ExitCode int    `json:"exitCode"`
}

ExecInfo is the result of running a script in a client container.

type HiveInfo 

type HiveInfo struct {
	Command    []string           `json:"command"`
	ClientFile []ClientDesignator `json:"clientFile"`
	Commit     string             `json:"commit"`
	Date       string             `json:"date"`
}

HiveInfo contains information about the hive instance running the simulation.

type HiveInstance 

type HiveInstance struct {
	SourceCommit string `json:"sourceCommit"`
	SourceDate   string `json:"sourceDate"`
	BuildDate    string `json:"buildDate"`
}

HiveInstance contains information about hive itself.

type Inventory 

type Inventory struct {
	BaseDir    string
	Clients    map[string]InventoryClient
	Simulators map[string]struct{}
}

Inventory keeps names of clients and simulators.

func LoadInventory 

func LoadInventory(basedir string) (Inventory, error)

LoadInventory finds all clients and simulators in basedir.

func (*Inventory) AddClient 

func (inv *Inventory) AddClient(name string, ic *InventoryClient)

AddClient ensures the given client name is known to the inventory. This method exists for unit testing purposes only.

func (*Inventory) AddSimulator 

func (inv *Inventory) AddSimulator(name string)

AddSimulator ensures the given simulator name is known to the inventory. This method exists for unit testing purposes only.

func (Inventory) ClientDirectory 

func (inv Inventory) ClientDirectory(client ClientDesignator) string

ClientDirectory returns the directory containing the given client's Dockerfile. The client name may contain a branch specifier.

func (*Inventory) MatchSimulators 

func (inv *Inventory) MatchSimulators(expr string) ([]string, error)

MatchSimulators returns matching simulator names.

func (Inventory) SimulatorDirectory 

func (inv Inventory) SimulatorDirectory(name string) string

SimulatorDirectory returns the directory of containing the given simulator's Dockerfile.

type InventoryClient 

type InventoryClient struct {
	Dockerfiles []string
	Meta        ClientMetadata
}

type Runner 

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

Runner executes a simulation runs.

func NewRunner 

func NewRunner(inv Inventory, b Builder, cb ContainerBackend) *Runner

func (*Runner) Build 

func (r *Runner) Build(ctx context.Context, clientList []ClientDesignator, simList []string, simBuildArgs map[string]string) error

Build builds client and simulator images.

func (*Runner) Run 

func (r *Runner) Run(ctx context.Context, sim string, env SimEnv, hiveInfo HiveInfo) (SimResult, error)

func (*Runner) RunDevMode 

func (r *Runner) RunDevMode(ctx context.Context, env SimEnv, endpoint string, hiveInfo HiveInfo) error

RunDevMode starts simulator development mode. In this mode, the simulator is not launched and the API server runs on the local network instead of listening for requests on the docker network.

Note: Sim* options in env are ignored, but Client* options and LogDir still apply.

type SimEnv 

type SimEnv struct {
	LogDir string

	// Parameters of simulation.
	SimLogLevel    int
	SimParallelism int
	SimRandomSeed  int
	SimTestPattern string
	SimBuildArgs   []string

	// This is the time limit for the simulation run.
	// There is no default limit.
	SimDurationLimit time.Duration

	// These are the clients which are made available to the simulator.
	// If unset (i.e. nil), all built clients are used.
	ClientList []ClientDesignator

	// This configures the amount of time the simulation waits
	// for the client to open port 8545 after launching the container.
	ClientStartTimeout time.Duration
}

SimEnv contains the simulation parameters.

type SimResult 

type SimResult struct {
	Suites       int
	SuitesFailed int
	Tests        int
	TestsFailed  int
}

SimResult summarizes the results of a simulation run.

type TestCase 

type TestCase struct {
	Name          string                 `json:"name"`        // Test case short name.
	Description   string                 `json:"description"` // Test case long description in MD.
	Start         time.Time              `json:"start"`
	End           time.Time              `json:"end"`
	SummaryResult TestResult             `json:"summaryResult"` // The result of the whole test case.
	ClientInfo    map[string]*ClientInfo `json:"clientInfo"`    // Info about each client.
}

TestCase represents a single test case in a test suite.

type TestID 

type TestID uint32

TestID identifies a test case context.

func (TestID) String 

func (tsID TestID) String() string

type TestLogOffsets 

type TestLogOffsets struct {
	Begin int64 `json:"begin"`
	End   int64 `json:"end"`
}

type TestManager 

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

TestManager collects test results during a simulation run.

func NewTestManager 

func NewTestManager(config SimEnv, b ContainerBackend, clients []*ClientDefinition, hiveInfo HiveInfo) *TestManager

func (*TestManager) API 

func (manager *TestManager) API() http.Handler

API returns the simulation API handler.

func (*TestManager) ConnectContainer 

func (manager *TestManager) ConnectContainer(testSuite TestSuiteID, networkName, containerID string) error

ConnectContainer connects the given container to the given network.

func (*TestManager) ContainerIP 

func (manager *TestManager) ContainerIP(testSuite TestSuiteID, networkName, containerID string) (string, error)

ContainerIP gets the IP address of the given container on the given network.

func (*TestManager) CreateNetwork 

func (manager *TestManager) CreateNetwork(testSuite TestSuiteID, name string) error

CreateNetwork creates a docker network with the given network name.

func (*TestManager) DisconnectContainer 

func (manager *TestManager) DisconnectContainer(testSuite TestSuiteID, networkName, containerID string) error

DisconnectContainer disconnects the given container from the given network.

func (*TestManager) EndTest 

func (manager *TestManager) EndTest(suiteID TestSuiteID, testID TestID, result *TestResult) error

EndTest finishes the test case

func (*TestManager) EndTestSuite 

func (manager *TestManager) EndTestSuite(testSuite TestSuiteID) error

EndTestSuite ends the test suite by writing the test suite results to the supplied stream and removing the test suite from the running list

func (*TestManager) GetNodeInfo 

func (manager *TestManager) GetNodeInfo(testSuite TestSuiteID, test TestID, nodeID string) (*ClientInfo, error)

GetNodeInfo gets some info on a client belonging to some test

func (*TestManager) IsTestRunning 

func (manager *TestManager) IsTestRunning(test TestID) (*TestCase, bool)

IsTestRunning checks if the test is still running and returns it if so.

func (*TestManager) IsTestSuiteRunning 

func (manager *TestManager) IsTestSuiteRunning(testSuite TestSuiteID) (*TestSuite, bool)

IsTestSuiteRunning checks if the test suite is still running and returns it if so

func (*TestManager) NetworkExists 

func (manager *TestManager) NetworkExists(testSuite TestSuiteID, networkName string) bool

NetworkExists reports whether a network exists in the current test context.

func (*TestManager) PauseNode 

func (manager *TestManager) PauseNode(testID TestID, nodeID string) error

PauseNode pauses a client container.

func (*TestManager) PruneNetworks 

func (manager *TestManager) PruneNetworks(testSuite TestSuiteID) []error

PruneNetworks removes all networks created by the given test suite.

func (*TestManager) RegisterNode 

func (manager *TestManager) RegisterNode(testID TestID, nodeID string, nodeInfo *ClientInfo) error

RegisterNode is used by test suite hosts to register the creation of a node in the context of a test

func (*TestManager) RemoveNetwork 

func (manager *TestManager) RemoveNetwork(testSuite TestSuiteID, network string) error

RemoveNetwork removes a docker network by the given network name.

func (*TestManager) Results 

func (manager *TestManager) Results() map[TestSuiteID]*TestSuite

Results returns the results for all suites that have already ended.

func (*TestManager) SetSimContainerInfo 

func (manager *TestManager) SetSimContainerInfo(id, logFile string)

SetSimContainerInfo makes the manager aware of the simulation container. This must be called after creating the simulation container, but before starting it.

func (*TestManager) StartTest 

func (manager *TestManager) StartTest(testSuiteID TestSuiteID, name string, description string) (TestID, error)

StartTest starts a new test case, returning the testcase id as a context identifier

func (*TestManager) StartTestSuite 

func (manager *TestManager) StartTestSuite(name string, description string) (TestSuiteID, error)

StartTestSuite starts a test suite and returns the context id

func (*TestManager) StopNode 

func (manager *TestManager) StopNode(testID TestID, nodeID string) error

StopNode stops a client container.

func (*TestManager) Terminate 

func (manager *TestManager) Terminate() error

Terminate forces the termination of any running tests with an error message. This can be called as a cleanup method. If there are no running tests, there is no effect.

func (*TestManager) UnpauseNode 

func (manager *TestManager) UnpauseNode(testID TestID, nodeID string) error

UnpauseNode unpauses a client container.

type TestResult 

type TestResult struct {
	Pass    bool `json:"pass"`
	Timeout bool `json:"timeout,omitempty"`

	// The test log can be stored inline ("details"), or as offsets into the
	// suite's TestDetailsLog file ("log").
	Details    string          `json:"details,omitempty"`
	LogOffsets *TestLogOffsets `json:"log,omitempty"`
}

TestResult represents the result of a test case.

type TestSuite 

type TestSuite struct {
	ID             TestSuiteID          `json:"id"`
	Name           string               `json:"name"`
	Description    string               `json:"description"`
	ClientVersions map[string]string    `json:"clientVersions"`
	TestCases      map[TestID]*TestCase `json:"testCases"`

	SimulatorLog   string `json:"simLog"`         // path to simulator log-file simulator. (may be shared with multiple suites)
	TestDetailsLog string `json:"testDetailsLog"` // the test details output file
	// contains filtered or unexported fields
}

TestSuite is a single run of a simulator, a collection of testcases.

type TestSuiteID 

type TestSuiteID uint32

TestSuiteID identifies a test suite context.

func (TestSuiteID) String 

func (tsID TestSuiteID) String() string

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.