sim

Documentation

Overview

Package sim provides a multi-server Docker sshd simulation harness for integration-testing the control-plane pipeline without touching live hosts.

The harness spins up N Docker containers (each running sshd) on an isolated bridge network, injects an in-memory ED25519 key-pair, and exposes a Fleet value whose servers can be passed directly to controlplane.Resolve / controlplane.Run.

All containers are torn down on Close, even if the test panics, so the host environment is never dirtied.

Build tag: integration — tests in this package are skipped unless INTEGRATION=1 is set in the environment.

Index

• Constants
• func TempFile(t *testing.T, name string) string
• type ContainerSpec
• type Fleet
  • func Start(t *testing.T, cfg FleetConfig) *Fleet
  • func (f *Fleet) Close()
• type FleetConfig
  • func DefaultFleetConfig() FleetConfig
• type SimServer
  • func (s SimServer) SSHHostPort() string

Constants

const (
	RoleApp           = "app"
	RoleLB            = "lb"
	RoleObservability = "observability"
)

Role constants mirror controlplane.ServerRole but kept local to avoid importing the parent package (the harness must not import impl under test).

Functions

func TempFile

func TempFile(t *testing.T, name string) string

TempFile returns a path inside t.TempDir() for storing auxiliary files.

Types

type ContainerSpec

type ContainerSpec struct {
	Name string
	Role string
	// Primary marks the server as the primary app server (non-zero exit on skip).
	Primary bool
}

ContainerSpec describes one simulated host in the fleet.

type Fleet

type Fleet struct {
	// Servers is the ordered list of simulated hosts.
	Servers []SimServer
	// PrivateKeyPath is the path to the ED25519 private key that all
	// containers accept. Set this env var value as the SSH key for probers.
	PrivateKeyPath string
	// EnvVarName is the environment variable that must be set to PrivateKeyPath
	// so the control-plane prober can find the key.
	EnvVarName string
	// NetworkName is the Docker bridge network created for this fleet.
	NetworkName string
	// contains filtered or unexported fields
}

Fleet is the full simulation environment returned by Start.

func Start

func Start(t *testing.T, cfg FleetConfig) *Fleet

Start launches the simulation fleet. It is called from integration tests gated by INTEGRATION=1. The caller must call fleet.Close() or defer it.

Start generates an ephemeral ED25519 key-pair, writes the private key to a temp file (mode 0600), and configures each sshd container to accept that key as the only authorised identity.

func (*Fleet) Close

func (f *Fleet) Close()

Close tears down all containers and the bridge network.

type FleetConfig

type FleetConfig struct {
	// AppCount is the number of app-role containers (≥1).
	AppCount int
	// HasLB controls whether a load-balancer container is included.
	HasLB bool
	// HasObservability controls whether an observability container is added.
	HasObservability bool
	// EnvVarName is the SSH key env var name injected into the fleet.
	// Defaults to "NSELF_SSH_KEY_SIM".
	EnvVarName string
}

FleetConfig controls how many servers of each role are started.

func DefaultFleetConfig

func DefaultFleetConfig() FleetConfig

DefaultFleetConfig returns the 4-server configuration used by CP-T19: 1 lb + 1 observability + 2 app.

type SimServer

type SimServer struct {
	ContainerSpec
	// Host is the container's address reachable from the test host.
	Host string
	// Port is the sshd port mapped to a random high port on the host.
	Port int
	// ContainerID is the Docker container ID for cleanup.
	ContainerID string
}

SimServer is one running container with its connection details.

func (SimServer) SSHHostPort

func (s SimServer) SSHHostPort() string

SSHHostPort returns the SSH connection address for a SimServer as "host:port".