Documentation
¶
Index ¶
- Constants
- func EnsureImages(ctx context.Context, imageRefs []string, buildRoot string) error
- func NormalizeImageRefs(in []string) []string
- func Purge(ctx context.Context) error
- func ResolveBuildRoot(startDir string) (string, error)
- func SetSonicLocalPath(path string)
- func SonicLocalPath() string
- func WillBuildImage(imageRef string) bool
- type Client
- func (c *Client) Close() error
- func (c *Client) ContainerExists(name string) (bool, error)
- func (c *Client) CreateBridgeNetwork(ctx context.Context) (*Network, error)
- func (c *Client) CreateTestBridgeNetwork(t *testing.T) *Network
- func (c *Client) Start(ctx context.Context, config *ContainerConfig) (*Container, error)
- type Container
- func (c *Container) CheckRunning(ctx context.Context) error
- func (c *Container) Cleanup(ctx context.Context) error
- func (c *Container) Exec(ctx context.Context, cmd []string) (string, error)
- func (c *Container) GetAddressForService(service *network.ServiceDescription) (*network.AddressPort, error)
- func (c *Container) Hostname() string
- func (c *Container) IsRunning() bool
- func (c *Container) SaveLogTo(ctx context.Context, directory string) error
- func (c *Container) SendSignal(ctx context.Context, signal Signal) error
- func (c *Container) Stop(ctx context.Context) error
- func (c *Container) StreamLog(ctx context.Context) (io.ReadCloser, error)
- type ContainerConfig
- type Network
- type Signal
Constants ¶
const DefaultSonicLocalPath = "sonic"
DefaultSonicLocalPath is the default path used as the build context when building the "sonic:local" image. It is interpreted relative to the Norma build root (see ResolveBuildRoot) unless overridden with SetSonicLocalPath to point at an arbitrary location on disk.
Variables ¶
This section is empty.
Functions ¶
func EnsureImages ¶
EnsureImages makes sure the given image refs are locally available.
The function provides the runtime image provisioning path used by scenario execution. It performs the following steps:
- Normalize and deduplicate image references.
- Resolve the Norma build root (must contain Dockerfile and scripts/run_sonic.sh).
- For each image: - choose build or pull strategy via planImage; - build (Sonic-specific refs) or pull (all other refs).
For Sonic image refs, it lazily builds from the project's Dockerfile:
- sonic: from sonicRepositoryURL
- sonic:local: from the currently configured sonic local path (see SetSonicLocalPath / SonicLocalPath, default DefaultSonicLocalPath)
- sonic:<tag>: from sonicRepositoryURL#<tag>
- sonic:<commit hash>: from sonicRepositoryURL#<commit hash>
Other images are pulled if missing.
The operation is idempotent with respect to already present tags, and relies on Docker's own image/layer cache for repeated builds.
func NormalizeImageRefs ¶
NormalizeImageRefs removes empty refs, deduplicates, and returns image refs in lexical order.
func ResolveBuildRoot ¶
ResolveBuildRoot finds the Norma repository root to execute docker builds.
Starting from startDir, it walks up parent directories until it finds a directory containing both:
- Dockerfile
- scripts/run_sonic.sh
This guards against running docker build in unrelated directories while keeping call sites simple.
func SetSonicLocalPath ¶
func SetSonicLocalPath(path string)
SetSonicLocalPath configures the path used as the docker build context for the "sonic:local" image. An empty path resets the configuration to the built-in default (DefaultSonicLocalPath).
The path may be absolute or relative; when relative it is resolved against the Norma build root at build time.
func SonicLocalPath ¶
func SonicLocalPath() string
SonicLocalPath returns the currently configured path used as the docker build context for the "sonic:local" image.
func WillBuildImage ¶
WillBuildImage reports whether EnsureImages will build (not pull) the given image reference.
This is true for Sonic image refs handled via local or remote source build contexts (e.g. sonic, sonic:local, sonic:<tag-or-commit>). For all other refs, EnsureImages will pull instead.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client provides means to spawn Docker containers capable of hosting services like the go-opera client.
func NewClient ¶
NewClient creates a new client facilitating the creation of Docker Containers capable of hosting services. Clients successfully created through this function should be Closed() eventually.
func (*Client) ContainerExists ¶
ContainerExists returns true if a container with the given name is currently running on the Docker host.
func (*Client) CreateBridgeNetwork ¶
CreateBridgeNetwork creates a new Docker bridge network.
func (*Client) CreateTestBridgeNetwork ¶
CreateTestBridgeNetwork creates a Docker bridge network for use in tests. When t is non-nil a cleanup function is registered that removes the network after the test completes. When t is nil an error is returned.
func (*Client) Start ¶
Start creates and runs one Container. The provided configuration allows to configure the Docker image to run inside the container -- and thus the services to be offered. When a Network is provided, the container's IP on that network is resolved and used to reach services directly, without port forwarding.
type Container ¶
type Container struct {
// contains filtered or unexported fields
}
Container represents a Docker Container, typically used for running a Fantom network Node, thus an instance of the go-opera client. *Container implements the driver.Host interface.
func (*Container) CheckRunning ¶
CheckRunning returns an error if the container process is no longer running, either because it exited on its own or because its state cannot be determined.
func (*Container) Cleanup ¶
Cleanup stops the container (unless it is already stopped) and frees any resources associated to it. After the operation, the Container is to be considered invalid.
func (*Container) Exec ¶
Exec executes a command in the container. This method is blocking until the command has finished. The output of the command is returned as a string (stdout + stderr). The command is required to be tokenized and interpreted in shell's exec form.
func (*Container) GetAddressForService ¶
func (c *Container) GetAddressForService(service *network.ServiceDescription) (*network.AddressPort, error)
GetAddressForService retrieves the Address of a service running in this Container. Services are reached via the container's IP on the Docker network using the service's internal port. If the IP was not resolved at start time, it is looked up on demand via container inspection.
func (*Container) Hostname ¶
Hostname returns the hostname of the Container. In this case it is the ID of the Docker Container.
func (*Container) IsRunning ¶
IsRunning returns true if the Container has not been stopped yet and is expected to offer its services.
func (*Container) SaveLogTo ¶
SaveLogTo fetches the log of the container and saves it to the given directory.
func (*Container) SendSignal ¶
SendSignal sends a signal to the container.
type ContainerConfig ¶
type ContainerConfig struct {
Hostname string
ImageName string
ShutdownTimeout *time.Duration
Environment map[string]string
Entrypoint []string // Entrypoint to run when starting the container. Optional.
Network *Network // Docker network to join
DataDirBinding *string // mount client datadir to this path on host
GenesisFileBind *string // mount genesis file on host to /genesis.json:ro in container
KeystoreBinding *string // mount keystore dir on host to /datadir/keystore:ro in container
}
ContainerConfig defines parameters for running Docker Containers.
Source Files