tui

package
v0.0.0-...-f902ed3 Latest Latest
Warning

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

 Go to latest Published: Nov 5, 2026 License: MIT Imports: 53 Imported by: 0

Documentation

Overview

Package tui implements the terminal user interface for spt. It provides an interactive UI for monitoring benchmark progress and managing test execution using the Bubble Tea framework.

Index

Constants

View Source 
const (
	// SubmissionNotSubmitted means no ambiguous POST was dispatched.
	SubmissionNotSubmitted = runcontrol.SubmissionNotSubmitted
	// SubmissionSubmitted means structured evidence confirmed acceptance.
	SubmissionSubmitted = runcontrol.SubmissionSubmitted
	// SubmissionUnknown means a dispatched POST could not be reconciled.
	SubmissionUnknown = runcontrol.SubmissionUnknown
)
View Source 
const (
	// LiveViewHeight is the fixed height for the live view panel (including borders)
	// 1 header + 2 data rows + 2 borders
	LiveViewHeight = 5

	// ChartViewportHeight is the total height for chart viewport (including borders)
	// 8 content + 2 borders
	ChartViewportHeight = 10

	// ChartContentHeight is the height of chart content (excluding borders)
	// 1 header + 6 bars + 1 timestamp
	ChartContentHeight = 8

	// ProcessViewportMinHeight is the minimum height for process output viewport
	ProcessViewportMinHeight = 5

	// ProcessViewportMaxHeight is the maximum height for process output viewport
	ProcessViewportMaxHeight = 25
)

Viewport heights define the fixed heights for different UI sections

View Source 
const (
	// StatusLineHeight is the height of the status line at the bottom
	StatusLineHeight = 1

	// ExtraLayoutPadding is additional padding for layout calculations
	ExtraLayoutPadding = 2

	// PageScrollSize is the number of lines to scroll on page up/down
	PageScrollSize = 10

	// BorderWidth is the width of viewport borders
	BorderWidth = 2

	// ViewportPadding is the internal padding for viewports
	ViewportPadding = 4
)

Layout components define the sizes of various UI elements

View Source 
const (
	// LayoutHeightWithCharts is the total fixed height when charts are visible
	// StatusLineHeight + ChartViewportHeight + LiveViewHeight + ExtraLayoutPadding
	LayoutHeightWithCharts = StatusLineHeight + ChartViewportHeight + LiveViewHeight + ExtraLayoutPadding // 1 + 10 + 5 + 2 = 18

	// LayoutHeightWithoutCharts is the total fixed height when charts are hidden
	// StatusLineHeight + LiveViewHeight + ExtraLayoutPadding
	LayoutHeightWithoutCharts = StatusLineHeight + LiveViewHeight + ExtraLayoutPadding // 1 + 5 + 2 = 8

	// ViewportContentPadding is the total padding that reduces content width
	// BorderWidth + ViewportPadding
	ViewportContentPadding = BorderWidth + ViewportPadding // 2 + 4 = 6
)

Layout calculations define derived values for common height calculations

View Source 
const (

	// RuntimeIdentityTierAvailableImage records one participant's available immutable image
	// evidence without representing a cross-host equality proof.
	RuntimeIdentityTierAvailableImage = "available_image"
)

Variables

View Source 
var ErrEngineIncompatible = errors.New("engine is not integrity-capable")

ErrEngineIncompatible indicates the engine cannot run the selected persisted-data workload.

View Source 
var ErrMetricsIncompatible = errors.New("spt metrics payload incompatible with this client")

ErrMetricsIncompatible indicates that the metrics payload cannot be consumed by this client.

View Source 
var ErrMetricsPending = errors.New("spt metrics not yet available for this run")

ErrMetricsPending indicates that the engine responded but has not yet published metrics for the current run, e.g. during pre-step stabilization. It is a normal transient state, not a compatibility failure.

View Source 
var ErrRunOwnershipUnknown = errors.New("cannot stop test without a session-owned run ID")

ErrRunOwnershipUnknown prevents destructive run operations when the client has not established ownership through a confirmed submission or bounded submission reconciliation.

Functions

func CalculateNiceUpperBound 

func CalculateNiceUpperBound(maxVal int64) int64

CalculateNiceUpperBound calculates a "nice" round number for chart scaling Given a maximum value, returns a round number that's >= max

func ExtractDisplayDuration 

func ExtractDisplayDuration(m PerformanceMetric) int64

ExtractDisplayDuration extracts the duration value selected for UI display.

func ExtractDisplayLatency 

func ExtractDisplayLatency(m PerformanceMetric) int64

ExtractDisplayLatency extracts the latency value selected for UI display.

func ExtractFailureIncrement 

func ExtractFailureIncrement(m PerformanceMetric) int64

ExtractFailureIncrement extracts the incremental failure count

func ExtractMeanLatency 

func ExtractMeanLatency(m PerformanceMetric) int64

ExtractMeanLatency is kept for older tests/helpers that still refer to the legacy name.

func ExtractOpsPerSec 

func ExtractOpsPerSec(m PerformanceMetric) int64

ExtractOpsPerSec extracts the ops/sec metric

func FormatFailureValue 

func FormatFailureValue(value int64) string

FormatFailureValue formats failure count values

func FormatLatencyValue 

func FormatLatencyValue(value int64) string

FormatLatencyValue formats latency values in microseconds

func FormatOpsValue 

func FormatOpsValue(value int64) string

FormatOpsValue formats operations per second values

func PrintLayoutCalculations 

func PrintLayoutCalculations(width, height int)

PrintLayoutCalculations prints detailed layout calculations for debugging

func RenderSampleTUIToFile 

func RenderSampleTUIToFile(filename string, width, height int, withData bool) error

RenderSampleTUIToFile renders a sample TUI layout to a file for QA purposes

func StartTUI 

func StartTUI() error

StartTUI starts the TUI with Docker integration

func StartTUIWithContainer 

func StartTUIWithContainer(image string, cmd []string) error

StartTUIWithContainer starts the TUI and immediately launches a container

func StartTUIWithMultiHostOrchestrator 

func StartTUIWithMultiHostOrchestrator(orchestrator *MultiHostOrchestrator, image string, scenarioPath string, params scenario.ScenarioParams, setSummarySink func(func(string))) error

StartTUIWithMultiHostOrchestrator starts the TUI with a pre-configured multi-host orchestrator

func StartTUIWithMultiHostOrchestratorContentTimeoutWithTrace 

func StartTUIWithMultiHostOrchestratorContentTimeoutWithTrace(orchestrator *MultiHostOrchestrator, image string, scenarioPath string, params scenario.ScenarioParams, autoTerminateSeconds int, setSummarySink func(func(string)), tracePath string, traceAppend bool, scenarioContent, defaultsContent []byte) error

StartTUIWithMultiHostOrchestratorContentTimeoutWithTrace starts the multi-host TUI with caller-provided content and optional auto-terminate timeout.

func StartTUIWithMultiHostOrchestratorContentWithTrace 

func StartTUIWithMultiHostOrchestratorContentWithTrace(orchestrator *MultiHostOrchestrator, image string, scenarioPath string, params scenario.ScenarioParams, setSummarySink func(func(string)), tracePath string, traceAppend bool, scenarioContent, defaultsContent []byte) error

StartTUIWithMultiHostOrchestratorContentWithTrace starts the multi-host TUI with caller-provided scenario/defaults content.

func StartTUIWithMultiHostOrchestratorTimeout 

func StartTUIWithMultiHostOrchestratorTimeout(orchestrator *MultiHostOrchestrator, image string, scenarioPath string, params scenario.ScenarioParams, autoTerminateSeconds int, setSummarySink func(func(string))) error

StartTUIWithMultiHostOrchestratorTimeout starts the TUI (multi-host) and exits after autoTerminateSeconds (>0).

func StartTUIWithMultiHostOrchestratorTimeoutWithTrace 

func StartTUIWithMultiHostOrchestratorTimeoutWithTrace(orchestrator *MultiHostOrchestrator, image string, scenarioPath string, params scenario.ScenarioParams, autoTerminateSeconds int, setSummarySink func(func(string)), tracePath string, traceAppend bool) error

StartTUIWithMultiHostOrchestratorTimeoutWithTrace starts the multi-host TUI with timeout and optional full-output trace capture.

func StartTUIWithMultiHostOrchestratorWithTrace 

func StartTUIWithMultiHostOrchestratorWithTrace(orchestrator *MultiHostOrchestrator, image string, scenarioPath string, params scenario.ScenarioParams, setSummarySink func(func(string)), tracePath string, traceAppend bool) error

StartTUIWithMultiHostOrchestratorWithTrace starts the multi-host TUI with optional full-output trace capture.

func StartTUIWithMultiHostRunOptions 

func StartTUIWithMultiHostRunOptions(
	orchestrator *MultiHostOrchestrator,
	image, scenarioPath string,
	params scenario.ScenarioParams,
	options RunOptions,
) error

StartTUIWithMultiHostRunOptions starts a host-orchestrated TUI run with explicit orchestration lifecycle options.

func StartTUIWithScenario 

func StartTUIWithScenario(image string, scenarioPath string) error

StartTUIWithScenario starts the TUI with a scenario file and launches the container

func StartTUIWithScenarioAndParams 

func StartTUIWithScenarioAndParams(image string, scenarioPath string, params scenario.ScenarioParams, apiPort string, setSummarySink func(func(string))) error

StartTUIWithScenarioAndParams starts the TUI with a scenario file and scenario parameters

func StartTUIWithScenarioAndParamsNetworkModeTimeoutWithTrace 

func StartTUIWithScenarioAndParamsNetworkModeTimeoutWithTrace(image string, scenarioPath string, params scenario.ScenarioParams, apiPort string, networkMode string, resultsRoot string, autoTerminateSeconds int, setSummarySink func(func(string)), tracePath string, traceAppend bool) error

StartTUIWithScenarioAndParamsNetworkModeTimeoutWithTrace starts the TUI with a selected Docker network mode and optional timeout.

func StartTUIWithScenarioAndParamsNetworkModeWithTrace 

func StartTUIWithScenarioAndParamsNetworkModeWithTrace(image string, scenarioPath string, params scenario.ScenarioParams, apiPort string, networkMode string, resultsRoot string, setSummarySink func(func(string)), tracePath string, traceAppend bool) error

StartTUIWithScenarioAndParamsNetworkModeWithTrace starts the TUI with a selected Docker network mode.

func StartTUIWithScenarioAndParamsTimeout 

func StartTUIWithScenarioAndParamsTimeout(image string, scenarioPath string, params scenario.ScenarioParams, apiPort string, autoTerminateSeconds int, setSummarySink func(func(string))) error

StartTUIWithScenarioAndParamsTimeout starts the TUI (single host) and exits after autoTerminateSeconds (>0).

func StartTUIWithScenarioAndParamsTimeoutWithTrace 

func StartTUIWithScenarioAndParamsTimeoutWithTrace(image string, scenarioPath string, params scenario.ScenarioParams, apiPort string, autoTerminateSeconds int, setSummarySink func(func(string)), tracePath string, traceAppend bool) error

StartTUIWithScenarioAndParamsTimeoutWithTrace starts the TUI (single host), exits after timeout, and can capture full output.

func StartTUIWithScenarioAndParamsWithTrace 

func StartTUIWithScenarioAndParamsWithTrace(image string, scenarioPath string, params scenario.ScenarioParams, apiPort string, setSummarySink func(func(string)), tracePath string, traceAppend bool) error

StartTUIWithScenarioAndParamsWithTrace starts the TUI with optional full-output trace capture.

func StartTUIWithScenarioContentAndParamsTimeoutWithTrace 

func StartTUIWithScenarioContentAndParamsTimeoutWithTrace(image string, scenarioPath string, params scenario.ScenarioParams, apiPort string, networkMode string, resultsRoot string, autoTerminateSeconds int, setSummarySink func(func(string)), tracePath string, traceAppend bool, scenarioContent, defaultsContent []byte) error

StartTUIWithScenarioContentAndParamsTimeoutWithTrace starts the TUI with caller-provided content and optional timeout.

func StartTUIWithScenarioContentAndParamsWithTrace 

func StartTUIWithScenarioContentAndParamsWithTrace(image string, scenarioPath string, params scenario.ScenarioParams, apiPort string, networkMode string, resultsRoot string, setSummarySink func(func(string)), tracePath string, traceAppend bool, scenarioContent, defaultsContent []byte) error

StartTUIWithScenarioContentAndParamsWithTrace starts the TUI with caller-provided scenario/defaults content.

func StartTUIWithScenarioRunOptions 

func StartTUIWithScenarioRunOptions(
	image, scenarioPath string, params scenario.ScenarioParams, options RunOptions,
) error

StartTUIWithScenarioRunOptions starts a local TUI run with explicit orchestration lifecycle options.

Types

type APIMetricsPoller 

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

APIMetricsPoller implements MetricsPoller using SptAPIClient

func NewAPIMetricsPoller 

func NewAPIMetricsPoller() *APIMetricsPoller

NewAPIMetricsPoller creates a new API-based metrics poller

func (*APIMetricsPoller) PollMetrics 

func (p *APIMetricsPoller) PollMetrics(_ context.Context, _ string) (*PerformanceMetric, error)

PollMetrics polls metrics from a specific node using its API client

type AmbiguousSubmissionError 

type AmbiguousSubmissionError struct {
	ExpectedRunID int64
	Cause         error
}

AmbiguousSubmissionError means POST /run was dispatched but the response and bounded run-id reconciliation did not prove whether it was accepted.

func (*AmbiguousSubmissionError) Error 

func (e *AmbiguousSubmissionError) Error() string

func (*AmbiguousSubmissionError) Unwrap 

func (e *AmbiguousSubmissionError) Unwrap() error

type CPUMonitor 

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

CPUMonitor provides cross-platform CPU usage monitoring

func NewCPUMonitor 

func NewCPUMonitor(interval time.Duration) *CPUMonitor

NewCPUMonitor creates a new CPU monitor with the specified sampling interval

func (*CPUMonitor) GetCPUPercent 

func (c *CPUMonitor) GetCPUPercent() float64

GetCPUPercent returns the current CPU usage percentage (0-100) Returns 0 if monitoring is not available or not started

func (*CPUMonitor) IsStarted 

func (c *CPUMonitor) IsStarted() bool

IsStarted returns true if the CPU monitor is currently running

func (*CPUMonitor) Start 

func (c *CPUMonitor) Start() error

Start begins CPU monitoring in a background goroutine

func (*CPUMonitor) Stop 

func (c *CPUMonitor) Stop()

Stop stops the CPU monitoring goroutine

type DebugLayoutRenderer 

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

DebugLayoutRenderer provides debugging utilities for TUI layout

func NewDebugLayoutRenderer 

func NewDebugLayoutRenderer(width, height int) *DebugLayoutRenderer

NewDebugLayoutRenderer creates a new debug layout renderer

func (*DebugLayoutRenderer) RenderLayoutToString 

func (d *DebugLayoutRenderer) RenderLayoutToString(withSampleData bool) string

RenderLayoutToString renders the complete TUI layout to a string for debugging

type DeleteBatchMetrics 

type DeleteBatchMetrics = deletemetrics.Batches

DeleteBatchMetrics aliases the shared batch contract.

type DeleteBucketMetrics 

type DeleteBucketMetrics = deletemetrics.Bucket

DeleteBucketMetrics aliases the shared bounded bucket contract.

type DeleteCompletionMetrics 

type DeleteCompletionMetrics = deletemetrics.Completion

DeleteCompletionMetrics aliases the shared completion contract.

type DeleteFailurePolicy 

type DeleteFailurePolicy = deletemetrics.FailurePolicy

DeleteFailurePolicy aliases the shared failure policy contract.

type DeleteMetricUnits 

type DeleteMetricUnits = deletemetrics.Units

DeleteMetricUnits aliases the shared unit contract.

type DeleteMetrics 

type DeleteMetrics = deletemetrics.Metrics

DeleteMetrics preserves the public TUI/API surface for schema-v4 metrics.

type DeleteObjectMetrics 

type DeleteObjectMetrics = deletemetrics.Objects

DeleteObjectMetrics aliases the shared object contract.

type DeletePerformanceApplicability 

type DeletePerformanceApplicability = deletemetrics.Performance

DeletePerformanceApplicability aliases the shared applicability contract.

type DeletePhaseMetrics 

type DeletePhaseMetrics = deletemetrics.Phases

DeletePhaseMetrics aliases the shared lifecycle phase contract.

type DeleteRequestMetrics 

type DeleteRequestMetrics = deletemetrics.Requests

DeleteRequestMetrics aliases the shared request contract.

type DeleteResultIdentity 

type DeleteResultIdentity = deletemetrics.Identity

DeleteResultIdentity aliases the shared run identity contract.

type DeleteTimingMetrics 

type DeleteTimingMetrics = deletemetrics.Timing

DeleteTimingMetrics aliases the shared request timing contract.

type DeleteVerificationMetrics 

type DeleteVerificationMetrics = deletemetrics.Verification

DeleteVerificationMetrics aliases the shared verification contract.

type DeleteVersionMetrics 

type DeleteVersionMetrics = deletemetrics.Versions

DeleteVersionMetrics aliases the shared version contract.

type DistributedRuntimeIdentityEvidence 

type DistributedRuntimeIdentityEvidence struct {
	Tier           string                                  `json:"tier"`
	ImageReference string                                  `json:"imageReference"`
	ImageID        string                                  `json:"imageId"`
	PayloadSHA256  string                                  `json:"payloadSha256,omitempty"`
	Participants   []DistributedRuntimeIdentityParticipant `json:"participants"`
}

DistributedRuntimeIdentityEvidence records the mandatory immutable-image tier used by a distributed persisted-data verification run.

type DistributedRuntimeIdentityParticipant 

type DistributedRuntimeIdentityParticipant struct {
	Host          string   `json:"host"`
	ImageID       string   `json:"imageId"`
	RepoDigests   []string `json:"repoDigests,omitempty"`
	PayloadSHA256 string   `json:"payloadSha256,omitempty"`
}

DistributedRuntimeIdentityParticipant is host-specific image evidence.

type DockerInterface 

type DockerInterface interface {
	// ContainerID returns the current container ID
	ContainerID() string

	// StartContainer creates and starts a new container with the given command
	StartContainer(image string, cmd []string) (string, error)

	// StartContainerWithScenario creates and starts a container with a scenario file
	StartContainerWithScenario(image string, scenarioPath string, additionalArgs []string) (string, error)

	// StartContainerInNodeMode starts a container in API server mode.
	StartContainerInNodeMode(image string, apiPort string, networkMode string, additionalArgs []string) (string, error)

	// StartWorkerNodeContainer starts a container in RMI worker node mode
	StartWorkerNodeContainer(image string, rmiHostname string, rmiPortStart, rmiPortCount int, additionalArgs []string) (string, error)

	// StartEntryNodeContainer starts a container as RMI entry node with worker addresses
	StartEntryNodeContainer(image string, workerAddresses []string, additionalArgs []string, networkMode string) (string, error)

	// StreamOutput starts streaming container output with callback functions
	StreamOutput(containerID string, stdoutCallback func(string), stderrCallback func(string))

	// Cleanup stops and removes the container
	Cleanup() error

	// CleanupContext stops/removes the container and ancillary staging within
	// the caller's bounded lifecycle budget.
	CleanupContext(context.Context) error

	// Close cleans up resources
	Close()
}

DockerInterface defines the interface for Docker operations This allows for easy mocking in tests

type DockerManager 

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

DockerManager provides Docker operations for the TUI. It wraps a minimal dockerClient interface for easier testing and can delegate to a RemoteDockerManager when managing remote hosts.

func NewDockerManager 

func NewDockerManager() (*DockerManager, error)

NewDockerManager creates a new Docker manager

func NewDockerManagerForHost 

func NewDockerManagerForHost(ctx context.Context, hostInfo *hostparse.HostInfo) (*DockerManager, error)

NewDockerManagerForHost creates a Docker client for a specific host

func (*DockerManager) Cleanup 

func (dm *DockerManager) Cleanup() error

Cleanup stops and removes the container

func (*DockerManager) CleanupContext 

func (dm *DockerManager) CleanupContext(ctx context.Context) error

CleanupContext stops and removes the container within the caller's budget.

func (*DockerManager) CleanupResourcesContext 

func (dm *DockerManager) CleanupResourcesContext(ctx context.Context) error

CleanupResourcesContext removes containers and staging without attempting diagnostics again. Canonical finalization uses this after its independently bounded diagnostics phase.

func (*DockerManager) Close 

func (dm *DockerManager) Close()

Close cleans up resources

func (*DockerManager) ContainerDiagnosticTail 

func (dm *DockerManager) ContainerDiagnosticTail(containerID string, maxLines int) (string, error)

ContainerDiagnosticTail returns recent container startup diagnostics from Docker logs plus engine error logs captured through the private node log mount.

func (*DockerManager) ContainerID 

func (dm *DockerManager) ContainerID() string

ContainerID returns the current container ID

func (*DockerManager) ContainerLogTail 

func (dm *DockerManager) ContainerLogTail(containerID string, maxLines int) (string, error)

ContainerLogTail returns recent stdout/stderr lines from Docker logs.

func (*DockerManager) CreateContainer 

func (dm *DockerManager) CreateContainer(containerConfig *container.Config, hostConfig *container.HostConfig, containerName string) (string, error)

CreateContainer creates a container with the given configuration

func (*DockerManager) GetDockerVersion 

func (dm *DockerManager) GetDockerVersion(ctx context.Context) (string, error)

GetDockerVersion returns the Docker daemon version

func (*DockerManager) HasManagedResources 

func (dm *DockerManager) HasManagedResources() bool

HasManagedResources reports container or remote staging ownership after cleanup.

func (*DockerManager) HostInfo 

func (dm *DockerManager) HostInfo() *hostparse.HostInfo

HostInfo returns the host information for this Docker manager

func (*DockerManager) RemoveContainer 

func (dm *DockerManager) RemoveContainer(containerID string) error

RemoveContainer removes a container by ID

func (*DockerManager) SetFileMounts 

func (dm *DockerManager) SetFileMounts(mounts []scenario.FileMount) error

SetFileMounts configures read-only external files that must be visible inside SPT containers.

func (*DockerManager) SetFileMountsContext 

func (dm *DockerManager) SetFileMountsContext(ctx context.Context, mounts []scenario.FileMount) error

SetFileMountsContext stages external files within the launch lifecycle.

func (*DockerManager) StartContainer 

func (dm *DockerManager) StartContainer(image string, cmd []string) (string, error)

StartContainer creates and starts a new container

func (*DockerManager) StartContainerByID 

func (dm *DockerManager) StartContainerByID(containerID string) error

StartContainerByID starts an existing container by ID

func (*DockerManager) StartContainerContext 

func (dm *DockerManager) StartContainerContext(ctx context.Context, image string, cmd []string) (string, error)

StartContainerContext creates and starts a container within the caller's context.

func (*DockerManager) StartContainerInNodeMode 

func (dm *DockerManager) StartContainerInNodeMode(image string, apiPort string, networkMode string, additionalArgs []string) (string, error)

StartContainerInNodeMode starts a Spt container in API server mode.

func (*DockerManager) StartContainerInNodeModeContext 

func (dm *DockerManager) StartContainerInNodeModeContext(
	ctx context.Context, image string, apiPort string, networkMode string, additionalArgs []string,
) (string, error)

StartContainerInNodeModeContext starts an API node within the caller's context.

func (*DockerManager) StartContainerWithScenario 

func (dm *DockerManager) StartContainerWithScenario(image string, scenarioPath string, additionalArgs []string) (string, error)

StartContainerWithScenario creates and starts a container with a scenario file

func (*DockerManager) StartContainerWithScenarioContext 

func (dm *DockerManager) StartContainerWithScenarioContext(
	ctx context.Context, image string, scenarioPath string, additionalArgs []string,
) (string, error)

StartContainerWithScenarioContext starts a scenario container within the caller's context.

func (*DockerManager) StartEntryNodeContainer 

func (dm *DockerManager) StartEntryNodeContainer(image string, workerAddresses []string, additionalArgs []string, networkMode string) (string, error)

StartEntryNodeContainer starts a container as RMI entry node with worker addresses

func (*DockerManager) StartEntryNodeContainerContext 

func (dm *DockerManager) StartEntryNodeContainerContext(ctx context.Context, image string, workerAddresses []string, additionalArgs []string, networkMode string) (string, error)

StartEntryNodeContainerContext starts an RMI entry node within the caller's context.

func (*DockerManager) StartWorkerNodeContainer 

func (dm *DockerManager) StartWorkerNodeContainer(image string, rmiHostname string, rmiPortStart, rmiPortCount int, additionalArgs []string) (string, error)

StartWorkerNodeContainer starts a container in RMI worker node mode

func (*DockerManager) StartWorkerNodeContainerContext 

func (dm *DockerManager) StartWorkerNodeContainerContext(ctx context.Context, image string, rmiHostname string, rmiPortStart, rmiPortCount int, additionalArgs []string) (string, error)

StartWorkerNodeContainerContext starts an RMI worker within the caller's context.

func (*DockerManager) StopContainer 

func (dm *DockerManager) StopContainer(containerID string, timeoutSeconds int) error

StopContainer stops a container by ID

func (*DockerManager) StreamOutput 

func (dm *DockerManager) StreamOutput(containerID string, stdoutCallback func(string), stderrCallback func(string))

StreamOutput starts streaming container output with callback functions

type DockerStreamResult 

type DockerStreamResult struct {
	StdoutLines []string
	StderrLines []string
}

DockerStreamResult holds the parsed stdout and stderr lines

type EntryLogRelay 

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

EntryLogRelay tails entry-node console output and forwards lines into the TUI.

func NewEntryLogRelay 

func NewEntryLogRelay(fetcher LogFetcher) *EntryLogRelay

NewEntryLogRelay creates a relay that streams lines from fetcher.

func (*EntryLogRelay) Start 

func (r *EntryLogRelay) Start(parent context.Context, onLine func(string))

Start begins forwarding lines to onLine. Safe to call once.

func (*EntryLogRelay) Stop 

func (r *EntryLogRelay) Stop()

Stop cancels the relay and waits for it to exit.

type GenericChartRenderer 

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

GenericChartRenderer handles rendering of any performance metric chart

func NewGenericChartRenderer 

func NewGenericChartRenderer(title, unit string, extractor MetricExtractor, formatter ValueFormatter) *GenericChartRenderer

NewGenericChartRenderer creates a new generic chart renderer

func NewGenericChartRendererWithScale 

func NewGenericChartRendererWithScale(title, unit string, extractor MetricExtractor, formatter ValueFormatter, initialScale int64) *GenericChartRenderer

NewGenericChartRendererWithScale creates a new generic chart renderer with a custom initial scale

func (*GenericChartRenderer) RenderChart 

func (cr *GenericChartRenderer) RenderChart(collector *MetricsCollector, width int) string

RenderChart renders the performance bar chart

func (*GenericChartRenderer) RenderChartWithSelection 

func (cr *GenericChartRenderer) RenderChartWithSelection(collector *MetricsCollector, width int, selectedIndex int, isHistorical bool) string

RenderChartWithSelection renders the performance bar chart with optional selection highlighting

type HTTPStatusError 

type HTTPStatusError struct {
	StatusCode  int
	URL         string
	BodyPreview string
}

HTTPStatusError is returned when the Spt API responds with a non-200 status code.

func (*HTTPStatusError) Error 

func (e *HTTPStatusError) Error() string

type HostConnection 

type HostConnection struct {
	Info          *hostparse.HostInfo
	DockerManager DockerInterface
	APIClient     *SptAPIClient
	ContainerID   string
	AdvertisedIP  string // Routable IP used for java.rmi.server.hostname and worker address CSV
	Status        HostStatus
	Error         error
	Managed       bool // true when spt launched the container
	// contains filtered or unexported fields
}

HostConnection represents a connection to a Docker host

func (*HostConnection) GetError 

func (hc *HostConnection) GetError() error

GetError returns the last recorded error for the host connection (if any).

func (*HostConnection) GetPhase 

func (hc *HostConnection) GetPhase() NodePhase

GetPhase returns the node lifecycle phase.

func (*HostConnection) GetStatus 

func (hc *HostConnection) GetStatus() HostStatus

GetStatus returns the current status of a host connection

func (*HostConnection) IsManaged 

func (hc *HostConnection) IsManaged() bool

IsManaged reports whether spt started and should stop the container.

func (*HostConnection) SetError 

func (hc *HostConnection) SetError(err error)

SetError sets an error for the host connection

func (*HostConnection) SetManaged 

func (hc *HostConnection) SetManaged(managed bool)

SetManaged records whether the host's container lifecycle is owned by spt.

func (*HostConnection) SetPhase 

func (hc *HostConnection) SetPhase(phase NodePhase)

SetPhase records the current node lifecycle phase.

func (*HostConnection) SetStatus 

func (hc *HostConnection) SetStatus(status HostStatus)

SetStatus updates the status of a host connection

type HostStatus 

type HostStatus string

HostStatus represents the lifecycle state of a remote host. 

const (
	// HostStatusPending indicates the host has not begun connecting.
	HostStatusPending HostStatus = "pending"
	// HostStatusConnecting indicates a connection attempt is in progress.
	HostStatusConnecting HostStatus = "connecting"
	// HostStatusReady indicates the host is ready to start workloads.
	HostStatusReady HostStatus = "ready"
	// HostStatusRunning indicates the test container is running on the host.
	HostStatusRunning HostStatus = "running"
	// HostStatusFailed indicates an error occurred on the host.
	HostStatusFailed HostStatus = "failed"
	// HostStatusStopped indicates the test container has been stopped.
	HostStatusStopped HostStatus = "stopped"
)

type IncompatibleEngineError 

type IncompatibleEngineError struct {
	EntryNode    string
	EngineImage  string
	MissingPaths []string
	Reason       string
	Err          error
}

IncompatibleEngineError explains why a persisted-data run was refused before any object I/O. It always names the entry node and what could not be proven, and includes the configured engine image when the caller knows it.

func (*IncompatibleEngineError) Error 

func (e *IncompatibleEngineError) Error() string

func (*IncompatibleEngineError) Is 

func (e *IncompatibleEngineError) Is(target error) bool

Is lets callers match this error with errors.Is(err, ErrEngineIncompatible) regardless of the specific reason the engine was rejected.

func (*IncompatibleEngineError) Unwrap 

func (e *IncompatibleEngineError) Unwrap() error

type JSONMetricsBandwidth 

type JSONMetricsBandwidth struct {
	BytesTotal    int64   `json:"bytes_total"`
	BytesRateLast float64 `json:"bytes_rate_last"`
}

JSONMetricsBandwidth contains bandwidth-related metrics

type JSONMetricsConcurrency 

type JSONMetricsConcurrency struct {
	Current float64 `json:"current"`
	Mean    float64 `json:"mean"`
}

JSONMetricsConcurrency contains concurrency-related metrics

type JSONMetricsLimit 

type JSONMetricsLimit struct {
	Type    string `json:"type"` // "op_count" | "time" | "none"
	OpCount int64  `json:"op_count,omitempty"`
	TimeSec int64  `json:"time_sec,omitempty"`
}

JSONMetricsLimit summarizes which limit governs completion

type JSONMetricsOperations 

type JSONMetricsOperations struct {
	SuccessCount    int64   `json:"success_count"`
	FailedCount     int64   `json:"failed_count"`
	CorruptCount    *int64  `json:"corrupt_count"`
	SuccessRateLast float64 `json:"success_rate_last"`
	FailedRateLast  float64 `json:"failed_rate_last"`
}

JSONMetricsOperations contains operation-related metrics

type JSONMetricsStep 

type JSONMetricsStep struct {
	MetricsSchema        int                    `json:"metrics_schema"`
	Scope                string                 `json:"scope"`
	Role                 string                 `json:"role"`
	ClusterID            string                 `json:"cluster_id,omitempty"`
	NodeID               string                 `json:"node_id"`
	RunID                string                 `json:"run_id"`
	SampleTimestampRaw   string                 `json:"sample_ts"`
	StepID               string                 `json:"step_id"`
	OpType               string                 `json:"op_type"`
	Timestamp            int64                  `json:"timestamp"`
	ElapsedTimeSeconds   float64                `json:"elapsed_time_seconds"`
	TestState            int                    `json:"test_state"`
	CompletionPercent    int                    `json:"completion_percent"`
	OverallCompletion    int                    `json:"overall_completion_percent"`
	Unbounded            bool                   `json:"unbounded"`
	OverallUnbounded     bool                   `json:"overall_unbounded"`
	Operations           JSONMetricsOperations  `json:"operations"`
	Bandwidth            JSONMetricsBandwidth   `json:"bandwidth"`
	Timing               JSONMetricsTiming      `json:"timing"`
	Concurrency          JSONMetricsConcurrency `json:"concurrency"`
	Limit                *JSONMetricsLimit      `json:"limit,omitempty"`
	NodesCount           int                    `json:"nodes_count,omitempty"`
	NodesPresent         []string               `json:"nodes_present,omitempty"`
	ContributorsPresent  []string               `json:"contributors_present,omitempty"`
	Partial              bool                   `json:"partial,omitempty"`
	DeleteDetailExpected bool                   `json:"delete_detail_expected,omitempty"`
	Delete               *DeleteMetrics         `json:"delete,omitempty"`
}

JSONMetricsStep represents a single load step's metrics from the JSON endpoint

type JSONMetricsTiming 

type JSONMetricsTiming struct {
	LatencyMeanUs  float64         `json:"latency_mean_us"`
	DurationMeanUs float64         `json:"duration_mean_us"`
	Latency        *JSONTimingStat `json:"latency,omitempty"`
	Duration       *JSONTimingStat `json:"duration,omitempty"`
	TTFB           *JSONTimingStat `json:"ttfb,omitempty"`
}

JSONMetricsTiming contains timing-related metrics

type JSONTimingStat 

type JSONTimingStat = deletemetrics.TimingStat

JSONTimingStat contains schema 3+ timing distribution fields.

type LaunchHooks 

type LaunchHooks struct {
	OnSubmitted func()
	// contains filtered or unexported fields
}

LaunchHooks carries orchestration lifecycle notifications that are not part of scenario configuration. Hooks run synchronously at the named boundary.

func NewLaunchHooks 

func NewLaunchHooks(onSubmitted func()) LaunchHooks

NewLaunchHooks creates hooks with a race-safe, exactly-once submission state. The zero value remains valid for compatibility callers that do not need to inspect submission state.

func NewSessionLaunchHooks 

func NewSessionLaunchHooks(session *runcontrol.Session, onSubmitted func()) LaunchHooks

NewSessionLaunchHooks binds launch notifications and resource registration to the supplied RunSession.

func (LaunchHooks) NormalEvidencePermitted 

func (h LaunchHooks) NormalEvidencePermitted() bool

NormalEvidencePermitted reports whether the launch established the trusted run identity required for ordinary completion tracking and artifact use. Accepted-for-cleanup and unresolved submissions deliberately return false.

func (LaunchHooks) NotifyAcceptedForCleanup 

func (h LaunchHooks) NotifyAcceptedForCleanup()

NotifyAcceptedForCleanup reports that the engine accepted POST /run, but its response did not establish a trusted run identity. It retains cleanup ownership without arming the normal evidence monitor.

func (LaunchHooks) NotifySubmissionUnknown 

func (h LaunchHooks) NotifySubmissionUnknown()

NotifySubmissionUnknown records that POST /run may have reached the engine, but bounded reconciliation could not prove whether it was accepted. The state may later advance to SubmissionSubmitted if matching /status evidence appears; it never moves back to NotSubmitted.

func (LaunchHooks) NotifySubmitted 

func (h LaunchHooks) NotifySubmitted()

NotifySubmitted reports that the engine accepted the /run submission and established the trusted identity required for ordinary evidence.

func (LaunchHooks) PotentiallySubmitted 

func (h LaunchHooks) PotentiallySubmitted() bool

PotentiallySubmitted includes both confirmed and unresolved submissions.

func (LaunchHooks) ProvenNotSubmitted 

func (h LaunchHooks) ProvenNotSubmitted() bool

ProvenNotSubmitted reports that no request with an ambiguous outcome was dispatched. Evidence permission is reported separately.

func (LaunchHooks) RegisterResourceFinalizer 

func (h LaunchHooks) RegisterResourceFinalizer(finalizer runcontrol.ResourceFinalizer) error

RegisterResourceFinalizer binds launcher-owned resources to the session. Compatibility/self-managed hooks intentionally ignore registration.

func (LaunchHooks) RunPreSubmissionCheck 

func (h LaunchHooks) RunPreSubmissionCheck(ctx context.Context) ([]string, error)

RunPreSubmissionCheck executes the optional readiness-to-submission gate.

func (LaunchHooks) SessionManaged 

func (h LaunchHooks) SessionManaged() bool

SessionManaged reports whether post-submission disposal belongs to a RunSession rather than this presentation adapter.

func (LaunchHooks) SubmissionState 

func (h LaunchHooks) SubmissionState() SubmissionState

SubmissionState returns the strongest submission fact observed by these hooks. A zero-value LaunchHooks reports SubmissionNotSubmitted.

func (LaunchHooks) Submitted 

func (h LaunchHooks) Submitted() bool

Submitted reports confirmed POST acceptance, including an identity-invalid response retained only for cleanup.

func (LaunchHooks) WithPreSubmissionCheck 

func (h LaunchHooks) WithPreSubmissionCheck(
	check func(context.Context) ([]string, error),
) LaunchHooks

WithPreSubmissionCheck returns a copy that runs check synchronously after engine readiness and before POST /run. The returned lines are already safe for normal launch output and the error prevents submission.

func (LaunchHooks) WorkloadTerminal 

func (h LaunchHooks) WorkloadTerminal() <-chan struct{}

WorkloadTerminal returns the authoritative terminal-workload signal. Compatibility hooks return nil and retain presentation-owned completion.

type LaunchState 

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

LaunchState records cleanup ownership and whether ordinary run evidence is trusted. It is shared by value-copied LaunchHooks so launchers and callers agree on both facts after an unrelated UI, signal, or cleanup error.

type LiveViewRenderer 

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

LiveViewRenderer handles formatting and rendering of live performance statistics

func NewLiveViewRenderer 

func NewLiveViewRenderer(params *scenario.ScenarioParams) *LiveViewRenderer

NewLiveViewRenderer creates a new live view renderer with CPU monitoring

func (*LiveViewRenderer) RenderLiveView 

func (l *LiveViewRenderer) RenderLiveView(metrics *MetricsCollector, width int) string

RenderLiveView generates the complete live view content (without borders - handled by TUI)

func (*LiveViewRenderer) Stop 

func (l *LiveViewRenderer) Stop()

Stop cleanly shuts down the live view renderer

type LogFetcher 

type LogFetcher interface {
	// Stream should block and invoke onLine for each new line until ctx is cancelled or an error occurs.
	// It should return when ctx.Done() is closed or on fatal error.
	Stream(ctx context.Context, onLine func(string)) error
}

LogFetcher abstracts a source of entry-node logs for the relay.

type MetricExtractor 

type MetricExtractor func(PerformanceMetric) int64

MetricExtractor is a function that extracts a metric value from a PerformanceMetric

type MetricsAggregator 

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

MetricsAggregator produces client-side totals from per-node metrics.

func NewMetricsAggregator 

func NewMetricsAggregator() *MetricsAggregator

NewMetricsAggregator creates a new metrics aggregator.

func NewMetricsAggregatorWithEntry 

func NewMetricsAggregatorWithEntry(entryNodeID string) *MetricsAggregator

NewMetricsAggregatorWithEntry creates a metrics aggregator that treats the provided node identifier as the aggregate (entry) source.

func (*MetricsAggregator) Aggregate 

func (ma *MetricsAggregator) Aggregate(nodeMetrics map[string]*PerformanceMetric) *PerformanceMetric

Aggregate combines node-scoped metrics into a single aggregate view. Returns nil if no node-scoped samples are available.

type MetricsCollector 

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

MetricsCollector manages the collection and storage of performance metrics

func NewMetricsCollector 

func NewMetricsCollector() *MetricsCollector

NewMetricsCollector creates a new metrics collector

func (*MetricsCollector) AddMultiNodeSample 

func (mc *MetricsCollector) AddMultiNodeSample(update *MultiNodeMetricsUpdate)

AddMultiNodeSample processes a multi-node metrics update

func (*MetricsCollector) AddSample 

func (mc *MetricsCollector) AddSample(metric PerformanceMetric)

AddSample adds a new performance metric sample (aggregated metrics for charts)

func (*MetricsCollector) GetActiveNodeCount 

func (mc *MetricsCollector) GetActiveNodeCount() int

GetActiveNodeCount returns the number of currently active nodes

func (*MetricsCollector) GetLatestNodeSample 

func (mc *MetricsCollector) GetLatestNodeSample(nodeID string) *PerformanceMetric

GetLatestNodeSample returns the most recent sample for a specific node

func (*MetricsCollector) GetLatestOpsPerSec 

func (mc *MetricsCollector) GetLatestOpsPerSec() int64

GetLatestOpsPerSec returns the most recent ops/sec value, or 0 if no samples

func (*MetricsCollector) GetLatestSample 

func (mc *MetricsCollector) GetLatestSample() *PerformanceMetric

GetLatestSample returns the most recent aggregated sample, or nil if no samples

func (*MetricsCollector) GetMetricRange 

func (mc *MetricsCollector) GetMetricRange(extractor func(PerformanceMetric) int64) (minVal, maxVal int64)

GetMetricRange returns the min and max values for a given metric extractor

func (*MetricsCollector) GetNodeSamples 

func (mc *MetricsCollector) GetNodeSamples(nodeID string) []PerformanceMetric

GetNodeSamples returns metrics history for a specific node

func (*MetricsCollector) GetNodeStatus 

func (mc *MetricsCollector) GetNodeStatus() map[string]NodeConnectionStatus

GetNodeStatus returns connection status for all nodes

func (*MetricsCollector) GetOpsPerSecRange 

func (mc *MetricsCollector) GetOpsPerSecRange() (minVal, maxVal int64)

GetOpsPerSecRange returns the min and max ops/sec values across all samples

func (*MetricsCollector) GetSamples 

func (mc *MetricsCollector) GetSamples() []PerformanceMetric

GetSamples returns all collected samples (aggregated metrics for charts)

type MetricsPoller 

type MetricsPoller interface {
	PollMetrics(ctx context.Context, nodeID string) (*PerformanceMetric, error)
}

MetricsPoller interface for testable metrics collection

type MockDockerManager 

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

MockDockerManager is a mock implementation of DockerInterface for testing

func NewMockDockerManager 

func NewMockDockerManager() *MockDockerManager

NewMockDockerManager creates a new mock Docker manager

func (*MockDockerManager) Cleanup 

func (m *MockDockerManager) Cleanup() error

Cleanup simulates container cleanup

func (*MockDockerManager) CleanupContext 

func (m *MockDockerManager) CleanupContext(ctx context.Context) error

CleanupContext simulates bounded container cleanup.

func (*MockDockerManager) Close 

func (m *MockDockerManager) Close()

Close simulates closing the Docker manager

func (*MockDockerManager) ContainerID 

func (m *MockDockerManager) ContainerID() string

ContainerID returns the mock container ID

func (*MockDockerManager) GetCleanupCallCount 

func (m *MockDockerManager) GetCleanupCallCount() int

GetCleanupCallCount returns the number of times Cleanup was called

func (*MockDockerManager) GetCloseCallCount 

func (m *MockDockerManager) GetCloseCallCount() int

GetCloseCallCount returns the number of times Close was called

func (*MockDockerManager) GetContainerCalls 

func (m *MockDockerManager) GetContainerCalls() []struct {
	Image string
	Cmd   []string
}

GetContainerCalls returns all regular container starts

func (*MockDockerManager) GetEntryNodeCalls 

func (m *MockDockerManager) GetEntryNodeCalls() []struct {
	Image           string
	WorkerAddresses []string
	AdditionalArgs  []string
	NetworkMode     string
}

GetEntryNodeCalls returns all entry node container starts

func (*MockDockerManager) GetFileMounts 

func (m *MockDockerManager) GetFileMounts() []scenario.FileMount

GetFileMounts returns configured file mounts.

func (*MockDockerManager) GetScenarioCalls 

func (m *MockDockerManager) GetScenarioCalls() []struct {
	Image          string
	ScenarioPath   string
	AdditionalArgs []string
}

GetScenarioCalls returns all scenario-based container starts

func (*MockDockerManager) GetStartCallCount 

func (m *MockDockerManager) GetStartCallCount() int

GetStartCallCount returns the number of times StartContainer was called

func (*MockDockerManager) GetStreamCallCount 

func (m *MockDockerManager) GetStreamCallCount() int

GetStreamCallCount returns the number of times StreamOutput was called

func (*MockDockerManager) GetWorkerNodeCalls 

func (m *MockDockerManager) GetWorkerNodeCalls() []struct {
	Image          string
	RMIHostname    string
	RMIPortStart   int
	RMIPortCount   int
	AdditionalArgs []string
}

GetWorkerNodeCalls returns all worker node container starts

func (*MockDockerManager) HasManagedResources 

func (m *MockDockerManager) HasManagedResources() bool

HasManagedResources reports whether the mock still owns a container.

func (*MockDockerManager) SetContainerID 

func (m *MockDockerManager) SetContainerID(id string)

SetContainerID sets the mock container ID

func (*MockDockerManager) SetFailOnCleanup 

func (m *MockDockerManager) SetFailOnCleanup(fail bool)

SetFailOnCleanup configures whether Cleanup should fail

func (*MockDockerManager) SetFailOnStart 

func (m *MockDockerManager) SetFailOnStart(fail bool)

SetFailOnStart configures whether StartContainer should fail

func (*MockDockerManager) SetFileMounts 

func (m *MockDockerManager) SetFileMounts(mounts []scenario.FileMount) error

SetFileMounts records configured file mounts.

func (*MockDockerManager) SetOnStreamOutput 

func (m *MockDockerManager) SetOnStreamOutput(callback func(containerID string))

SetOnStreamOutput sets a callback to be called when StreamOutput is invoked

func (*MockDockerManager) SetOutputDelay 

func (m *MockDockerManager) SetOutputDelay(delay time.Duration)

SetOutputDelay sets the delay between output lines

func (*MockDockerManager) SetOutputLines 

func (m *MockDockerManager) SetOutputLines(lines []string)

SetOutputLines sets the lines to output during streaming

func (*MockDockerManager) StartContainer 

func (m *MockDockerManager) StartContainer(image string, cmd []string) (string, error)

StartContainer simulates starting a container

func (*MockDockerManager) StartContainerInNodeMode 

func (m *MockDockerManager) StartContainerInNodeMode(image string, apiPort string, networkMode string, additionalArgs []string) (string, error)

StartContainerInNodeMode simulates starting a container in API server mode.

func (*MockDockerManager) StartContainerWithScenario 

func (m *MockDockerManager) StartContainerWithScenario(image string, scenarioPath string, additionalArgs []string) (string, error)

StartContainerWithScenario simulates starting a container with a scenario file

func (*MockDockerManager) StartEntryNodeContainer 

func (m *MockDockerManager) StartEntryNodeContainer(image string, workerAddresses []string, additionalArgs []string, networkMode string) (string, error)

StartEntryNodeContainer simulates starting an entry node container

func (*MockDockerManager) StartWorkerNodeContainer 

func (m *MockDockerManager) StartWorkerNodeContainer(image string, rmiHostname string, rmiPortStart, rmiPortCount int, additionalArgs []string) (string, error)

StartWorkerNodeContainer simulates starting a worker node container

func (*MockDockerManager) StreamOutput 

func (m *MockDockerManager) StreamOutput(containerID string, stdoutCallback func(string), _ func(string))

StreamOutput simulates streaming container output

type Model 

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

Model represents the TUI state

func InitialModel 

func InitialModel() Model

InitialModel creates a new model instance

func (Model) Init 

func (m Model) Init() tea.Cmd

Init initializes the model

func (Model) Update 

func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update handles messages

func (Model) View 

func (m Model) View() string

View renders the TUI

type MultiHostOrchestrator 

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

MultiHostOrchestrator manages tests across multiple Docker hosts

func NewMultiHostOrchestrator 

func NewMultiHostOrchestrator(hostInfos []*hostparse.HostInfo, minHosts int) *MultiHostOrchestrator

NewMultiHostOrchestrator creates a new multi-host orchestrator

func NewMultiHostOrchestratorWithRMI 

func NewMultiHostOrchestratorWithRMI(hostInfos []*hostparse.HostInfo, minHosts int, rmiConfig RMIConfig) *MultiHostOrchestrator

NewMultiHostOrchestratorWithRMI creates a new multi-host orchestrator with RMI configuration

func (*MultiHostOrchestrator) AttachExistingWorkersEnabled 

func (o *MultiHostOrchestrator) AttachExistingWorkersEnabled() bool

AttachExistingWorkersEnabled reports if attach mode is enabled.

func (*MultiHostOrchestrator) CollectDiagnostics 

func (o *MultiHostOrchestrator) CollectDiagnostics(ctx context.Context) error

CollectDiagnostics copies diagnostics from all managed hosts into the run results directory.

func (*MultiHostOrchestrator) ConnectHosts 

func (o *MultiHostOrchestrator) ConnectHosts(ctx context.Context) error

ConnectHosts establishes Docker connections to all hosts

func (*MultiHostOrchestrator) FinalizeDiagnosticsAndCleanup 

func (o *MultiHostOrchestrator) FinalizeDiagnosticsAndCleanup(ctx context.Context) error

FinalizeDiagnosticsAndCleanup collects diagnostics from every managed host and then fully stops/removes their containers (and cleans up remote staging). It is the single, canonical end-of-run action for delegated auto-results shutdown: without it, containers were only ever stopped as a side effect of collecting diagnostics (never removed, staging never cleaned up) on the normal-completion path, and a slow diagnostics copy could otherwise race a caller-side timeout fallback trying to do the same cleanup concurrently.

Safe to call more than once, including concurrently. Work starts once, while each waiter remains independently cancellable.

func (*MultiHostOrchestrator) FinalizeDiagnosticsAndCleanupOutcome 

func (o *MultiHostOrchestrator) FinalizeDiagnosticsAndCleanupOutcome(
	ctx context.Context,
) runcontrol.FinalizationOutcome

FinalizeDiagnosticsAndCleanupOutcome preserves diagnostics, mandatory removal, and final ownership as independently inspectable results.

func (*MultiHostOrchestrator) GetExecutionParticipantHosts 

func (o *MultiHostOrchestrator) GetExecutionParticipantHosts() ([]*HostConnection, bool, error)

GetExecutionParticipantHosts returns the locked RMI execution topology in entry/worker order. The boolean is false before a distributed topology has been established; failed readiness must not remove a locked participant.

func (*MultiHostOrchestrator) GetHostCount 

func (o *MultiHostOrchestrator) GetHostCount() int

GetHostCount returns the total number of hosts

func (*MultiHostOrchestrator) GetHostsInfo 

func (o *MultiHostOrchestrator) GetHostsInfo() []map[string]interface{}

GetHostsInfo returns a summary of all hosts and their status

func (*MultiHostOrchestrator) GetReadyHostCount 

func (o *MultiHostOrchestrator) GetReadyHostCount() int

GetReadyHostCount returns the number of ready hosts

func (*MultiHostOrchestrator) GetReadyHosts 

func (o *MultiHostOrchestrator) GetReadyHosts() []*HostConnection

GetReadyHosts returns all hosts that are ready for testing

func (*MultiHostOrchestrator) GetRunningHostCount 

func (o *MultiHostOrchestrator) GetRunningHostCount() int

GetRunningHostCount returns the number of hosts with running containers

func (*MultiHostOrchestrator) MetricContributorIDs 

func (o *MultiHostOrchestrator) MetricContributorIDs() ([]string, error)

MetricContributorIDs returns the immutable contributor topology supplied to the entry engine for the active execution. It is unavailable until the entry and its active workers have started.

func (*MultiHostOrchestrator) PrepareDistributedIntegrityRuntimeIdentity 

func (o *MultiHostOrchestrator) PrepareDistributedIntegrityRuntimeIdentity(
	ctx context.Context,
	image string,
) (DistributedRuntimeIdentityEvidence, error)

PrepareDistributedIntegrityRuntimeIdentity runs and caches the selected distributed identity gate. The command layer calls this after host preflight but before starting auto-results, so a pre-I/O gate failure cannot leave a completion tracker waiting for an engine that never starts.

func (*MultiHostOrchestrator) SetAPIPort 

func (o *MultiHostOrchestrator) SetAPIPort(apiPort string)

SetAPIPort overrides the Spt API port used for node startup and polling.

func (*MultiHostOrchestrator) SetAttachExistingWorkers 

func (o *MultiHostOrchestrator) SetAttachExistingWorkers(attach bool)

SetAttachExistingWorkers toggles attach mode (skip worker launches, do not manage worker lifecycle).

func (*MultiHostOrchestrator) SetForceCleanup 

func (o *MultiHostOrchestrator) SetForceCleanup(force bool)

SetForceCleanup enables stopping conflicting containers during preflight

func (*MultiHostOrchestrator) SetImage 

func (o *MultiHostOrchestrator) SetImage(image string)

SetImage sets the image used for distributed runs (used by preflight)

func (*MultiHostOrchestrator) SetIntegrityRuntimeIdentityTier 

func (o *MultiHostOrchestrator) SetIntegrityRuntimeIdentityTier(tier string)

SetIntegrityRuntimeIdentityTier selects the mandatory image-only tier or the stronger image plus /opt/spt payload tier for distributed persisted-data verification.

func (*MultiHostOrchestrator) SetNotifier 

func (o *MultiHostOrchestrator) SetNotifier(fn func(string))

SetNotifier configures a callback for progress messages so that callers (like the TUI) can render them inside a messages pane instead of stdout.

func (*MultiHostOrchestrator) SetResultsRoot 

func (o *MultiHostOrchestrator) SetResultsRoot(resultsRoot string)

SetResultsRoot configures the run results directory used for local diagnostics collection.

func (*MultiHostOrchestrator) SetRuntimeIdentityRecorder 

func (o *MultiHostOrchestrator) SetRuntimeIdentityRecorder(recorder func(DistributedRuntimeIdentityEvidence))

SetRuntimeIdentityRecorder receives immutable runtime evidence before any verification container starts. The command layer uses it to persist evidence in run metadata.

func (*MultiHostOrchestrator) StartContainers 

func (o *MultiHostOrchestrator) StartContainers(ctx context.Context, image string, additionalArgs []string) error

StartContainers starts Spt containers on all ready hosts

func (*MultiHostOrchestrator) StartDistributedTest 

func (o *MultiHostOrchestrator) StartDistributedTest(ctx context.Context, image string, params scenario.ScenarioParams) error

StartDistributedTest starts a distributed test using RMI coordination

func (*MultiHostOrchestrator) StartDistributedTestWithContent 

func (o *MultiHostOrchestrator) StartDistributedTestWithContent(ctx context.Context, image string, params scenario.ScenarioParams, scenarioContent []byte) error

StartDistributedTestWithContent starts the RMI entry/worker topology with caller-provided scenario content for later API submission.

func (*MultiHostOrchestrator) StopAllContainers 

func (o *MultiHostOrchestrator) StopAllContainers(ctx context.Context) error

StopAllContainers stops all managed containers within the caller's budget.

func (*MultiHostOrchestrator) VerifyRunningIntegrityPayloadIdentity 

func (o *MultiHostOrchestrator) VerifyRunningIntegrityPayloadIdentity(ctx context.Context) error

VerifyRunningIntegrityPayloadIdentity is retained for driver and extension compatibility. It now enforces the common running-participant image contract for both identity tiers.

func (*MultiHostOrchestrator) VerifyRunningIntegrityRuntimeIdentity 

func (o *MultiHostOrchestrator) VerifyRunningIntegrityRuntimeIdentity(ctx context.Context) error

VerifyRunningIntegrityRuntimeIdentity reconciles prepared image evidence against the exact containers that will execute the scenario, then rechecks payload bytes when that tier is selected. It must run after start and before API submission.

func (*MultiHostOrchestrator) WaitForAPIs 

func (o *MultiHostOrchestrator) WaitForAPIs(ctx context.Context, timeout time.Duration) error

WaitForAPIs waits for all container APIs to be ready

type MultiHostTestOrchestrator 

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

MultiHostTestOrchestrator wraps MultiHostOrchestrator to provide TestOrchestrator interface

func NewMultiHostTestOrchestrator 

func NewMultiHostTestOrchestrator(multiHost *MultiHostOrchestrator) *MultiHostTestOrchestrator

NewMultiHostTestOrchestrator creates a wrapper around MultiHostOrchestrator

func (*MultiHostTestOrchestrator) BuildBaselineUpdate 

func (m *MultiHostTestOrchestrator) BuildBaselineUpdate() *MultiNodeMetricsUpdate

BuildBaselineUpdate constructs a status-only update for all configured hosts (no per-node samples).

func (*MultiHostTestOrchestrator) CompletionCh 

func (m *MultiHostTestOrchestrator) CompletionCh() <-chan struct{}

CompletionCh returns a channel that closes when orchestration is complete.

func (*MultiHostTestOrchestrator) CompletionError 

func (m *MultiHostTestOrchestrator) CompletionError() error

CompletionError returns a terminal distributed presentation failure, if one was observed.

func (*MultiHostTestOrchestrator) SetCallbacks 

func (m *MultiHostTestOrchestrator) SetCallbacks(
	onStatusUpdate func(status *TestStatus),
	onMetrics func(update *MultiNodeMetricsUpdate),
	onOutput func(line string),
	onError func(err string),
)

SetCallbacks sets the callback functions for status, metrics, and output events

func (*MultiHostTestOrchestrator) SetExpectedStepIDs 

func (m *MultiHostTestOrchestrator) SetExpectedStepIDs(stepIDs []string)

SetExpectedStepIDs constrains completion detection to the final step in the generated scenario. This prevents a precondition/seed step from ending a multi-step headless run.

func (*MultiHostTestOrchestrator) SetMessageSink 

func (m *MultiHostTestOrchestrator) SetMessageSink(fn func(string))

SetMessageSink configures a sink for user-visible messages (wired by the TUI to append lines to the Messages viewport).

func (*MultiHostTestOrchestrator) StartMetricsPolling 

func (m *MultiHostTestOrchestrator) StartMetricsPolling(ctx context.Context)

StartMetricsPolling begins concurrent metrics collection from all ready hosts

func (*MultiHostTestOrchestrator) StartTest 

func (m *MultiHostTestOrchestrator) StartTest(ctx context.Context, image string, params scenario.ScenarioParams) error

StartTest starts monitoring tests on all hosts

func (*MultiHostTestOrchestrator) StartTestWithContent 

func (m *MultiHostTestOrchestrator) StartTestWithContent(ctx context.Context, image string, params scenario.ScenarioParams, scenarioContent, defaultsContent []byte) error

StartTestWithContent starts a test using caller-provided scenario and defaults content.

func (*MultiHostTestOrchestrator) StartTestWithContentAndLaunchHooks 

func (m *MultiHostTestOrchestrator) StartTestWithContentAndLaunchHooks(
	ctx context.Context,
	image string,
	params scenario.ScenarioParams,
	scenarioContent, defaultsContent []byte,
	hooks LaunchHooks,
) error

StartTestWithContentAndLaunchHooks starts caller-provided content and reports the accepted API submission through explicit orchestration hooks.

func (*MultiHostTestOrchestrator) StartTestWithLaunchHooks 

func (m *MultiHostTestOrchestrator) StartTestWithLaunchHooks(
	ctx context.Context, image string, params scenario.ScenarioParams, hooks LaunchHooks,
) error

StartTestWithLaunchHooks starts a host-orchestrated test and reports its API submission through explicit orchestration hooks.

func (*MultiHostTestOrchestrator) StopMetricsPolling 

func (m *MultiHostTestOrchestrator) StopMetricsPolling()

StopMetricsPolling stops the metrics collection

func (*MultiHostTestOrchestrator) StopTest 

func (m *MultiHostTestOrchestrator) StopTest() error

StopTest stops monitoring tests on all hosts

type MultiNodeMetricsUpdate 

type MultiNodeMetricsUpdate struct {
	Timestamp  time.Time
	Aggregated *PerformanceMetric              // Aggregated metrics for charts (sum of all op types)
	PerNode    map[string]*PerformanceMetric   // Individual node metrics (primary/first metric per node)
	PerOpType  map[string]*PerformanceMetric   // Per-operation-type aggregates (e.g. "CREATE", "READ", "DELETE")
	NodeStatus map[string]NodeConnectionStatus // Connection health per node
}

MultiNodeMetricsUpdate contains all metrics data for multi-node tests

type NodeConnectionStatus 

type NodeConnectionStatus struct {
	LastSeen    time.Time
	IsConnected bool  // Whether the node is reachable
	IsActive    bool  // Whether the node is actively processing
	Error       error // Last error if any
	Phase       NodePhase
}

NodeConnectionStatus tracks the health and connection status of individual nodes

type NodePhase 

type NodePhase string

NodePhase represents the lifecycle stage of a node from spt's perspective. 

const (
	// NodePhasePending indicates the orchestrator has not contacted the node yet.
	NodePhasePending NodePhase = "pending"
	// NodePhaseContacted indicates basic connectivity (e.g., SSH/Docker) succeeded.
	NodePhaseContacted NodePhase = "contacted"
	// NodePhaseContainerStarting indicates container launch has been initiated.
	NodePhaseContainerStarting NodePhase = "container_starting"
	// NodePhaseAPIReady indicates the node's API reported readiness.
	NodePhaseAPIReady NodePhase = "api_ready"
	// NodePhaseMetricsFlowing indicates metrics are being successfully collected.
	NodePhaseMetricsFlowing NodePhase = "metrics_flowing"
)

type PerformanceMetric 

type PerformanceMetric struct {
	Timestamp          time.Time
	SampleTimestamp    time.Time
	SampleTimestampRaw string
	StepID             string
	SptTimestamp       string  // Raw Spt timestamp (column 1)
	OpType             string  // Operation type (CREATE, READ, etc.)
	TestState          int     // Spt test state (0=idle, 1=running, 2=completed)
	ConcurrencyCurrent int64   // Current concurrency level
	ConcurrencyMean    float64 // Mean concurrency level
	SuccessCount       int64   // Successful operations count
	FailedCount        int64   // Failed operations count
	CorruptCount       int64   // Integrity corruption failures (a subset of FailedCount)
	HasCorruptCount    bool    // Whether the engine supplied operations.corrupt_count
	StepTime           float64 // Step time in seconds
	OpsPerSec          int64   // Last Rate [op/s] - primary chart metric
	MiBPerSec          int64   // Last Rate [MiB/s] - secondary chart metric
	MeanLatency        int64   // Display latency [us]; schema 3 prefers p50 with mean fallback
	MeanDuration       int64   // Display duration [us]; schema 3 prefers p50 with mean fallback
	HasLatency         bool    // Whether request-latency timing is available in the sample
	HasDuration        bool    // Whether request-duration timing is available in the sample
	MeanTTFB           int64   // Display TTFB [us]
	HasTTFB            bool    // Whether TTFB was present in the metrics sample
	FailureIncrement   int64   // Incremental failures since last sample

	MetricsSchema int
	Scope         string
	Role          string
	ClusterID     string
	NodeID        string
	RunID         string
	NodesCount    int
	NodesPresent  []string
	// ContributorsPresent is the additive schema-v4 freshness/identity set. NodesPresent retains
	// its established public presentation semantics.
	ContributorsPresent []string
	Partial             bool
	// DeleteDetailExpected opts this row into the standalone schema-v4 detail contract.
	DeleteDetailExpected bool

	LimitType    string
	LimitOpCount int64
	LimitTimeSec int64
	HasLimit     bool

	// Completion tracking (per-phase)
	// CompletionPercent is a 0-100 value reported by the node JSON API.
	// When Unbounded is true (no time/op-count limit), UI should display "∞" instead of a number.
	CompletionPercent        float64
	OverallCompletionPercent float64
	Unbounded                bool
	OverallUnbounded         bool

	// Delete holds schema-v4 explicit request/object units. It is nil for v2/v3,
	// generic DELETE operations, and non-DELETE operations.
	Delete *DeleteMetrics
}

PerformanceMetric represents a single performance data point from Spt

func AggregateByOpType 

func AggregateByOpType(metrics []*PerformanceMetric) (combined *PerformanceMetric, perOp map[string]*PerformanceMetric)

AggregateByOpType groups a slice of metrics by OpType and produces a combined aggregate plus a per-op-type map. For non-mixed workloads (single metric) the aggregate is the metric itself and the map has one entry. For mixed workloads the aggregate sums additive fields (ops/s, MiB/s, counts) across op types and uses ops-weighted averages for latency/duration. Combined TTFB is populated only when every contributor has TTFB for the same READ or LIST operation type.

type PollResults 

type PollResults struct {
	Metrics        map[string]*PerformanceMetric
	AllMetrics     map[string][]*PerformanceMetric // All op-type metrics per node
	Status         map[string]NodeConnectionStatus
	ContributorIDs map[string]string // Host display identifier to fleet contributor identifier.
}

PollResults holds the results of concurrent node polling

type RMIConfig 

type RMIConfig struct {
	NetworkMode string
	PortStart   int
	PortCount   int
}

RMIConfig holds RMI configuration parameters

type RemoteDockerManager 

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

RemoteDockerManager implements DockerInterface by executing docker CLI via SSH using the shared command layer (internal/docker/command). It is used for remote hosts where the Docker SDK ssh:// transport is unavailable.

func NewRemoteDockerManager 

func NewRemoteDockerManager(host *hostparse.HostInfo) (*RemoteDockerManager, error)

NewRemoteDockerManager constructs a RemoteDockerManager for the given host.

func (*RemoteDockerManager) Cleanup 

func (m *RemoteDockerManager) Cleanup() error

Cleanup force-removes the last started container (if any)

func (*RemoteDockerManager) CleanupContext 

func (m *RemoteDockerManager) CleanupContext(ctx context.Context) error

CleanupContext force-removes the last container and staging within the caller's budget.

func (*RemoteDockerManager) CleanupResourcesContext 

func (m *RemoteDockerManager) CleanupResourcesContext(ctx context.Context) error

CleanupResourcesContext removes the container and staging without retrying diagnostics. A preserved diagnostics directory remains managed for a later collection/removal attempt.

func (*RemoteDockerManager) Close 

func (m *RemoteDockerManager) Close()

Close is a no-op for the remote manager

func (*RemoteDockerManager) ContainerID 

func (m *RemoteDockerManager) ContainerID() string

ContainerID returns the last started container ID (if any)

func (*RemoteDockerManager) HasManagedResources 

func (m *RemoteDockerManager) HasManagedResources() bool

HasManagedResources reports whether cleanup must retain ownership for retry.

func (*RemoteDockerManager) SetFileMounts 

func (m *RemoteDockerManager) SetFileMounts(mounts []scenario.FileMount) error

SetFileMounts stages local item files onto the remote Docker host for bind mounting.

func (*RemoteDockerManager) SetFileMountsContext 

func (m *RemoteDockerManager) SetFileMountsContext(ctx context.Context, mounts []scenario.FileMount) error

SetFileMountsContext stages remote bind-mount inputs within the caller's context.

func (*RemoteDockerManager) StartContainer 

func (m *RemoteDockerManager) StartContainer(_ string, _ []string) (string, error)

StartContainer is not used for remote multi-host mode; return a clear error

func (*RemoteDockerManager) StartContainerContext 

func (m *RemoteDockerManager) StartContainerContext(_ context.Context, _ string, _ []string) (string, error)

StartContainerContext reports that generic remote starts are unsupported.

func (*RemoteDockerManager) StartContainerInNodeMode 

func (m *RemoteDockerManager) StartContainerInNodeMode(image string, apiPort string, networkMode string, additionalArgs []string) (string, error)

StartContainerInNodeMode starts a single Spt node exposing the provided API port.

func (*RemoteDockerManager) StartContainerInNodeModeContext 

func (m *RemoteDockerManager) StartContainerInNodeModeContext(
	ctx context.Context, image string, apiPort string, networkMode string, additionalArgs []string,
) (string, error)

StartContainerInNodeModeContext starts a remote API node within the caller's context.

func (*RemoteDockerManager) StartContainerWithScenario 

func (m *RemoteDockerManager) StartContainerWithScenario(_ string, _ string, _ []string) (string, error)

StartContainerWithScenario is not used in remote multi-host mode.

func (*RemoteDockerManager) StartContainerWithScenarioContext 

func (m *RemoteDockerManager) StartContainerWithScenarioContext(_ context.Context, _ string, _ string, _ []string) (string, error)

StartContainerWithScenarioContext reports that remote scenario starts are unsupported.

func (*RemoteDockerManager) StartEntryNodeContainer 

func (m *RemoteDockerManager) StartEntryNodeContainer(image string, workerAddresses []string, additionalArgs []string, networkMode string) (string, error)

StartEntryNodeContainer starts the entry node with worker addresses and extra args (e.g., S3 params).

func (*RemoteDockerManager) StartEntryNodeContainerContext 

func (m *RemoteDockerManager) StartEntryNodeContainerContext(ctx context.Context, image string, workerAddresses []string, additionalArgs []string, networkMode string) (string, error)

StartEntryNodeContainerContext starts a remote RMI entry node within the caller's context.

func (*RemoteDockerManager) StartWorkerNodeContainer 

func (m *RemoteDockerManager) StartWorkerNodeContainer(image string, rmiHostname string, rmiPortStart, rmiPortCount int, additionalArgs []string) (string, error)

StartWorkerNodeContainer starts a worker in RMI mode on the remote host.

func (*RemoteDockerManager) StartWorkerNodeContainerContext 

func (m *RemoteDockerManager) StartWorkerNodeContainerContext(ctx context.Context, image string, rmiHostname string, _ int, _ int, additionalArgs []string) (string, error)

StartWorkerNodeContainerContext starts a remote RMI worker within the caller's context.

func (*RemoteDockerManager) StreamOutput 

func (m *RemoteDockerManager) StreamOutput(containerID string, stdoutCallback func(string), stderrCallback func(string))

StreamOutput fetches logs once and forwards lines to callbacks (non-streaming fallback).

type RunOptions 

type RunOptions struct {
	Context              context.Context
	Verbose              bool
	APIPort              string
	NetworkMode          string
	ResultsRoot          string
	AutoTerminateSeconds int
	SetSummarySink       func(func(string))
	TracePath            string
	TraceAppend          bool
	ScenarioContent      []byte
	DefaultsContent      []byte
	LaunchHooks          LaunchHooks
}

RunOptions carries orchestration-only launch settings separately from scenario configuration. Existing TUI entrypoints remain compatibility wrappers.

type SptAPIClient 

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

SptAPIClient handles communication with the Spt REST API

func NewSptAPIClient 

func NewSptAPIClient(baseURL string) *SptAPIClient

NewSptAPIClient creates a new API client

func (*SptAPIClient) GetFleetJSONMetrics 

func (c *SptAPIClient) GetFleetJSONMetrics() (string, error)

GetFleetJSONMetrics fetches the engine's authoritative merged histograms.

func (*SptAPIClient) GetJSONMetrics 

func (c *SptAPIClient) GetJSONMetrics() (string, error)

GetJSONMetrics fetches the current metrics from the JSON endpoint.

func (*SptAPIClient) GetJSONMetricsVerbose 

func (c *SptAPIClient) GetJSONMetricsVerbose() (string, error)

GetJSONMetricsVerbose fetches the metrics payload with verbose diagnostics enabled.

func (*SptAPIClient) GetStatus 

func (c *SptAPIClient) GetStatus() (*TestStatus, error)

GetStatus retrieves the current test status

func (*SptAPIClient) GetStatusContext 

func (c *SptAPIClient) GetStatusContext(ctx context.Context) (*TestStatus, error)

GetStatusContext retrieves observed status within the caller's cancellation budget. Observing another run never changes this client's owned run ID.

func (*SptAPIClient) LogReadySnapshot 

func (c *SptAPIClient) LogReadySnapshot(label string)

LogReadySnapshot emits a single-line readiness snapshot using the /ready endpoint.

func (*SptAPIClient) LogReadySnapshotContext 

func (c *SptAPIClient) LogReadySnapshotContext(ctx context.Context, label string)

LogReadySnapshotContext emits a readiness snapshot within the caller's cancellation budget.

func (*SptAPIClient) ParseFleetJSONMetrics 

func (c *SptAPIClient) ParseFleetJSONMetrics(data string) ([]*PerformanceMetric, error)

ParseFleetJSONMetrics parses authoritative fleet-scoped aggregate samples.

func (*SptAPIClient) ParseJSONMetrics 

func (c *SptAPIClient) ParseJSONMetrics(data string) ([]*PerformanceMetric, error)

ParseJSONMetrics parses JSON format metrics into a slice of PerformanceMetric. For non-mixed workloads the slice contains a single element. For mixed workloads the engine emits one entry per op-type (e.g. CREATE, READ, DELETE) sharing the same step_id; all valid entries are returned. The slice is sorted by timestamp descending so callers that only need a single metric can use [0].

func (*SptAPIClient) SetRunID 

func (c *SptAPIClient) SetRunID(runID string)

SetRunID sets the run ID (useful for testing)

func (*SptAPIClient) Shutdown 

func (c *SptAPIClient) Shutdown() error

Shutdown requests a graceful node shutdown via /shutdown.

func (*SptAPIClient) ShutdownContext 

func (c *SptAPIClient) ShutdownContext(ctx context.Context) error

ShutdownContext requests graceful shutdown within the caller's cancellation budget.

func (*SptAPIClient) StartTest 

func (c *SptAPIClient) StartTest(scenario, defaults []byte) (string, error)

StartTest starts a new test run with the provided scenario and defaults. It is retained as a compatibility wrapper; production launchers use StartTestContext with their configured numeric run id.

func (*SptAPIClient) StartTestContext 

func (c *SptAPIClient) StartTestContext(
	ctx context.Context, scenario, defaults []byte, expectedRunIDs ...int64,
) (StartTestOutcome, error)

StartTestContext posts an exact scenario/defaults pair within the caller's launch context. expectedRunID is optional for compatibility; production callers provide it so an ambiguous transport result can be reconciled using structured /status evidence. An unknown submission is never retried.

func (*SptAPIClient) StopTest 

func (c *SptAPIClient) StopTest() error

StopTest stops the currently running test gracefully

func (*SptAPIClient) VerifyIntegrityCapability 

func (c *SptAPIClient) VerifyIntegrityCapability(engineImage string) error

VerifyIntegrityCapability proves, before scenario submission, that the entry node declares every configuration path the verification contract depends on.

The engine serves its merged confuse schema at /config/schema. Schema leaves are type descriptors rather than runtime values, so this checks path presence only and never interprets leaf contents.

Engine startup rejection and the scenario POST are both unreliable substitutes: startup argument handling can continue past an invalid path, and an integrity-unaware engine rejects the generated scenario later with an opaque HTTP 400 that cannot be distinguished from any other bad config.

func (*SptAPIClient) VerifyIntegrityCapabilityContext 

func (c *SptAPIClient) VerifyIntegrityCapabilityContext(ctx context.Context, engineImage string) error

VerifyIntegrityCapabilityContext binds the schema capability probe to the caller's launch lifecycle.

func (*SptAPIClient) VerifyScenarioIntegrityCapabilityContext 

func (c *SptAPIClient) VerifyScenarioIntegrityCapabilityContext(
	ctx context.Context, engineImage string, params scenario.Params,
) error

VerifyScenarioIntegrityCapabilityContext probes only the schema paths used by params. In particular, the destructive existing-prefix guard must be present for that DELETE mode without expanding verification-only planning or finalization to standalone DELETE.

func (*SptAPIClient) WaitForAPIReady 

func (c *SptAPIClient) WaitForAPIReady(timeout time.Duration) error

WaitForAPIReady waits for the Spt API to become ready

func (*SptAPIClient) WaitForAPIReadyContext 

func (c *SptAPIClient) WaitForAPIReadyContext(ctx context.Context, timeout time.Duration) error

WaitForAPIReadyContext waits for readiness within both the caller lifecycle and timeout.

func (*SptAPIClient) WaitForLinger 

func (c *SptAPIClient) WaitForLinger(linger time.Duration) error

WaitForLinger waits for /status to keep returning a terminal state for the given duration.

func (*SptAPIClient) WaitForLingerContext 

func (c *SptAPIClient) WaitForLingerContext(ctx context.Context, linger time.Duration) error

WaitForLingerContext allows shutdown to transition through an attributed active state, then requires terminal/idle status for the remainder of the supplied linger budget.

type StartTestOutcome 

type StartTestOutcome struct {
	RunID      string
	Submission SubmissionState
}

StartTestOutcome preserves the submission boundary even when POST /run returns a transport error. Callers must not retry SubmissionUnknown.

type SubmissionIdentityError 

type SubmissionIdentityError struct {
	ExpectedRunID int64
	Cause         error
}

SubmissionIdentityError means POST /run was accepted, but its response did not establish the configured run identity. The submission remains cleanup owned even though the launch must not proceed.

func (*SubmissionIdentityError) Error 

func (e *SubmissionIdentityError) Error() string

func (*SubmissionIdentityError) Unwrap 

func (e *SubmissionIdentityError) Unwrap() error

type SubmissionState 

type SubmissionState = runcontrol.SubmissionState

SubmissionState is retained as a TUI compatibility alias while RunSession owns the authoritative state for session-managed launches.

type TestOrchestrator 

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

TestOrchestrator manages the complete lifecycle of an API-based Spt test

func NewTestOrchestrator 

func NewTestOrchestrator(dm DockerInterface, apiPort string, nodeLogResultsRoot string) *TestOrchestrator

NewTestOrchestrator creates a new test orchestrator

func (*TestOrchestrator) CompletionCh 

func (o *TestOrchestrator) CompletionCh() <-chan struct{}

CompletionCh returns a channel that is closed when the run reaches a terminal state.

func (*TestOrchestrator) CompletionError 

func (o *TestOrchestrator) CompletionError() error

CompletionError returns a terminal presentation failure, if one prevented a valid final result.

func (*TestOrchestrator) FinalizeDiagnosticsAndCleanupOutcome 

func (o *TestOrchestrator) FinalizeDiagnosticsAndCleanupOutcome(
	ctx context.Context,
) runcontrol.FinalizationOutcome

FinalizeDiagnosticsAndCleanupOutcome is the canonical local post-submission resource finalizer. Diagnostics and mandatory removal receive independent budgets, and concurrent callers join one active attempt.

func (*TestOrchestrator) SetCallbacks 

func (o *TestOrchestrator) SetCallbacks(
	onStatus func(*TestStatus),
	onMetrics func(*MultiNodeMetricsUpdate),
	onOutput func(string),
	onError func(string),
)

SetCallbacks sets the callback functions for status updates

func (*TestOrchestrator) SetNetworkMode 

func (o *TestOrchestrator) SetNetworkMode(networkMode string)

SetNetworkMode selects the Docker network mode used for API node startup.

func (*TestOrchestrator) StartTest 

func (o *TestOrchestrator) StartTest(ctx context.Context, image string, params scenario.Params) error

StartTest starts a Spt test using the API approach

func (*TestOrchestrator) StartTestWithContent 

func (o *TestOrchestrator) StartTestWithContent(ctx context.Context, image string, params scenario.Params, scenarioContent, defaultsContent []byte) error

StartTestWithContent starts a Spt test with caller-provided scenario and defaults content.

func (*TestOrchestrator) StartTestWithContentAndLaunchHooks 

func (o *TestOrchestrator) StartTestWithContentAndLaunchHooks(
	ctx context.Context,
	image string,
	params scenario.Params,
	scenarioContent, defaultsContent []byte,
	hooks LaunchHooks,
) error

StartTestWithContentAndLaunchHooks starts caller-provided content and reports the accepted API submission through explicit orchestration hooks.

func (*TestOrchestrator) StartTestWithLaunchHooks 

func (o *TestOrchestrator) StartTestWithLaunchHooks(
	ctx context.Context, image string, params scenario.Params, hooks LaunchHooks,
) error

StartTestWithLaunchHooks starts a Spt test and reports its API submission through explicit orchestration hooks.

func (*TestOrchestrator) StopTest 

func (o *TestOrchestrator) StopTest() error

StopTest gracefully stops the test and cleans up

func (*TestOrchestrator) Wait 

func (o *TestOrchestrator) Wait()

Wait waits for the orchestrator to finish

type TestOrchestratorInterface 

type TestOrchestratorInterface interface {
	SetCallbacks(
		onStatus func(*TestStatus),
		onMetrics func(*MultiNodeMetricsUpdate),
		onOutput func(string),
		onError func(string),
	)
	StartTest(ctx context.Context, image string, params scenario.ScenarioParams) error
	StopTest() error
}

TestOrchestratorInterface defines the interface that test orchestrators must implement

type TestStatus 

type TestStatus struct {
	State    string  // RUNNING, COMPLETED, FAILED, IDLE
	Progress float64 // Progress percentage if available
	Message  string  // Status message or error
	RunID    string  // Current run ID
	StepID   string  // Step the engine attributes its state to, when known
	Category string  // Lowercase failure category of a FAILED run
	// contains filtered or unexported fields
}

TestStatus represents the status of a running test

type ValueFormatter 

type ValueFormatter func(int64) string

ValueFormatter is a function that formats a metric value for display

Source Files

View all Source files

Directories

Path Synopsis
Package headless provides non-interactive execution flows for running Spt via Docker without the TUI.
 Package headless provides non-interactive execution flows for running Spt via Docker without the TUI.

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.