Documentation
¶
Overview ¶
Package testenv is what the two live suites share: the Dockhand and the Docker hosts .scripts/testenv.sh started for them, and which of the two ways a Dockhand is run they stand for - open, as it comes, with no login, or with its login switched on and asked with an API token. The machinery for reading the environment is go-kt's (test/env).
The SDK suite (../../acceptance/dockhand) drives the client in sdk/dockhand and the tool suite (../../acceptance/tools) drives the tools over MCP. Each runs twice on the same server, in order: open, and then with the login on - which this package switches on, through the client, as part of opening the second: the first user, the login, and a token for that user.
Opening a world also registers the two hosts as environments, through the client, each the way Dockhand reaches it: alpha by its socket and beta by the Hawser agent in front of it.
It is also where something is started on a host from outside Dockhand (Run, Compose): what Dockhand did not make is half of what it manages, and no API of Dockhand's makes it.
Index ¶
- Constants
- func Configured() bool
- func HostPort(address string) (host string, port int, err error)
- type Stage
- type World
- func (w *World) Branch(ctx context.Context, repository, branch string) error
- func (w *World) CallIn(ctx context.Context, host, token string) error
- func (w *World) Commit(ctx context.Context, repository string, files map[string]string, ...) (string, error)
- func (w *World) Compose(ctx context.Context, host, project, file string) error
- func (w *World) Docker(ctx context.Context, host string, args ...string) (string, error)
- func (w *World) Env(host string) dockhand.EnvironmentID
- func (w *World) Freeze(ctx context.Context, host string) error
- func (w *World) HangUp(ctx context.Context, host string) error
- func (w *World) Laid(ctx context.Context, path string) (string, error)
- func (w *World) Lay(ctx context.Context, path, content string) error
- func (w *World) Manages(host string, id dockhand.EnvironmentID)
- func (w *World) Repository(name string, private bool) string
- func (w *World) Secrets(ctx context.Context, args ...string) (string, error)
- func (w *World) Serve(ctx context.Context, host, name, file, content string) (string, error)
- func (w *World) Unlay(ctx context.Context, dir string) error
- func (w *World) Unserve(ctx context.Context, host, name string) error
Constants ¶
const ( // Alpha and Beta are the two Docker hosts .scripts/testenv.sh starts, by the names the suites register them under: alpha is reached by its // socket, and beta by the Hawser agent in front of it. Alpha = "alpha" Beta = "beta" // NotConfigured is why a live test skips when the environment names no server. NotConfigured = `DOCKHAND_SERVER is not set: run "make testacc", or eval "$(.scripts/testenv.sh up)" first` )
const ( ConnectionSocket = "socket" ConnectionDirect = "direct" ConnectionAgent = "hawser-standard" ConnectionCaller = "hawser-edge" )
The ways Dockhand reaches a host, as it names them.
const Calls = "ws://dockhand:3000/api/hawser/connect" //nolint:revive // unsecure-url-scheme: the throwaway Dockhand is served without TLS, on a network of its own
Calls is what a Hawser agent that calls the Dockhand is told to call: the Dockhand by the name it has on the network the hosts share, where nothing outside that network hears what is said.
Variables ¶
This section is empty.
Functions ¶
func Configured ¶
func Configured() bool
Configured reports whether the environment names a server and the hosts it is to manage. It names no token: a fresh Dockhand has none to give, and the suites make their own.
Types ¶
type World ¶
type World struct {
Stage Stage
// Server is the address the Dockhand answers on
Server string
// Token is the API token this run minted, "" in the open stage
Token string
// Dock is a client for the server as this stage asks it: with nothing, or with the token
Dock *dockhand.Client
// User and Password are the administrator the login stage makes
User string
Password string
// Socket is where Dockhand finds alpha's Docker socket, Direct the address alpha's Docker also listens on, and Agent the address of the Hawser
// agent in front of beta, with the token it was started with
Socket string
Direct string
Agent string
AgentToken string
// Image is what the suites run on the hosts
Image string
// Scanned is an image old enough that a scanner finds plenty in it, and Scanner the image the scanner is run from: both where a host can pull
// them without asking Docker Hub
Scanned string
Scanner string
// Registry is where the hosts and the Dockhand find the registry the suites push to, which speaks plain HTTP and asks for the administrator's
// name and password
Registry string
// Vault is where the Dockhand finds the secret store the suites save as a secret provider, which speaks Vault's API, and VaultToken the token it
// takes: made up, and good for nothing but that store
Vault string
VaultToken string
// VaultByName is the same secret store by another address, its container's own name: for showing what Dockhand does when a provider's address
// changes
VaultByName string
// Git is where the Dockhand finds the suites' git server, which speaks plain HTTP: a repository is at /open/<name>.git for anyone and at
// /private/<name>.git for GitUser and GitPassword, a login made up for that server alone
Git string
GitUser string
GitPassword string
// Environments are the numbers Dockhand gave alpha and beta
Environments map[string]dockhand.EnvironmentID
// contains filtered or unexported fields
}
World is the Dockhand a live suite runs against, how it is run, and the hosts it manages.
func Open ¶
Open finds the Dockhand under test, runs it the way the stage asks - which for the login stage is switching its login on and minting a token - and registers the two hosts as environments.
func OpenBare ¶
OpenBare is Open without the hosts: the Dockhand is run the way the stage asks and is left managing whatever it already manages, which on a fresh server is nothing. It is for a suite that adds the hosts itself, through what it tests, and then says which it added (Manages).
func (*World) Branch ¶
Branch gives a repository of the suites' git server another branch, at the commit its main branch is at.
func (*World) CallIn ¶
CallIn starts a Hawser agent before one of the hosts that calls the Dockhand with a token, as an agent on a host Dockhand cannot reach does. One a run that was cut short left is taken away first.
func (*World) Commit ¶
func (w *World) Commit(ctx context.Context, repository string, files map[string]string, gone ...string) (string, error)
Commit writes files into a repository of the suites' git server and commits them to its main branch, making the repository when there is none of that name, and takes out the files named as gone. It answers the new commit, shortened as Dockhand shortens one, and there always is one: a repository outlives a stage of the suites, so the next finds the files it writes there already and commits all the same. It is how a repository comes to hold something for Dockhand to deploy, and how it changes under a stack already deployed, which nothing in Dockhand can do.
func (*World) Compose ¶
Compose starts a compose project on a host from outside Dockhand, as a person at the host would: its file is written on the host and brought up.
func (*World) Docker ¶
Docker runs a docker command on one of the hosts, inside the container the host is, and returns what it printed: how something is started on a host that Dockhand had no part in.
func (*World) Env ¶
func (w *World) Env(host string) dockhand.EnvironmentID
Env is the number Dockhand gave a host.
func (*World) Freeze ¶
Freeze holds the agent CallIn started for a host still, so that it neither answers nor calls again. An agent whose token stops working calls again with it a second later, is turned away, and Dockhand then turns away every call from the agent's address for five minutes, the next agent's with the right token among them, since a container that is removed leaves its address to the next. So a test that ends an agent's token holds the agent still first, and takes it away after.
func (*World) HangUp ¶
HangUp takes away the agent CallIn started for a host; one that is not there is no error.
func (*World) Lay ¶
Lay writes a file inside the Dockhand's own container, as a folder mounted into it would hold one: where Dockhand looks for a compose file it is shown rather than given.
func (*World) Manages ¶
func (w *World) Manages(host string, id dockhand.EnvironmentID)
Manages records the number Dockhand gave a host, for a suite that added the hosts itself.
func (*World) Repository ¶
Repository is the address Dockhand fetches a repository of the suites' git server from: the one anyone may read, or with private the one that asks for the server's login.
func (*World) Secrets ¶
Secrets runs a command of the secret store's own in its container, signed in with its token, and returns what it printed: how a suite puts a secret there for Dockhand to load, and takes it away again, which nothing in Dockhand can do. The first argument is the command, as kv.
func (*World) Serve ¶
Serve has one of the hosts serve one file over HTTP, from a small container started on it from outside Dockhand, and returns the address Dockhand fetches it at: how a test gives Dockhand something to fetch without either of them asking the internet. One a run that was cut short left under the same name is taken away first.