workloads

Documentation

Overview

Package workloads contains high-level logic for managing the lifecycle of ToolHive-managed containers.

Index

• Constants
• Variables
• type Manager
  • func NewManager(ctx context.Context) (Manager, error)
  • func NewManagerFromRuntime(runtime rt.Runtime) Manager
• type StatusManager
  • func NewStatusManager(ctx context.Context) (StatusManager, error)
  • func NewStatusManagerFromRuntime(runtime rt.Runtime) StatusManager
• type Workload
  • func WorkloadFromContainerInfo(container *runtime.ContainerInfo) (Workload, error)
• type WorkloadStatus

Constants

const (
	// AsyncOperationTimeout is the timeout for async workload operations
	AsyncOperationTimeout = 5 * time.Minute
)

Variables

var (
	ErrWorkloadNotFound    = fmt.Errorf("workload not found")
	ErrWorkloadNotRunning  = fmt.Errorf("workload not running")
	ErrInvalidWorkloadName = fmt.Errorf("invalid workload name")
)

ErrWorkloadNotFound is returned when a container cannot be found by name. ErrInvalidWorkloadName is returned when a workload name fails validation.

Types

type Manager

type Manager interface {
	// GetWorkload retrieves details of the named workload including its status.
	GetWorkload(ctx context.Context, workloadName string) (Workload, error)
	// ListWorkloads retrieves the states of all workloads.
	// The `listAll` parameter determines whether to include workloads that are not running.
	ListWorkloads(ctx context.Context, listAll bool) ([]Workload, error)
	// DeleteWorkloads deletes the specified workloads by name.
	// It is implemented as an asynchronous operation which returns an errgroup.Group
	DeleteWorkloads(ctx context.Context, names []string) (*errgroup.Group, error)
	// StopWorkloads stops the specified workloads by name.
	// It is implemented as an asynchronous operation which returns an errgroup.Group
	StopWorkloads(ctx context.Context, names []string) (*errgroup.Group, error)
	// RunWorkload runs a container in the foreground.
	RunWorkload(ctx context.Context, runConfig *runner.RunConfig) error
	// RunWorkloadDetached runs a container in the background.
	RunWorkloadDetached(runConfig *runner.RunConfig) error
	// RestartWorkloads restarts the specified workloads by name.
	// It is implemented as an asynchronous operation which returns an errgroup.Group
	RestartWorkloads(ctx context.Context, names []string) (*errgroup.Group, error)
	// GetLogs retrieves the logs of a container.
	GetLogs(ctx context.Context, containerName string, follow bool) (string, error)
}

Manager is responsible for managing the state of ToolHive-managed containers. NOTE: This interface may be split up in future PRs, in particular, operations which are only relevant to the CLI/API use case will be split out.

func NewManager

func NewManager(ctx context.Context) (Manager, error)

NewManager creates a new container manager instance.

func NewManagerFromRuntime

func NewManagerFromRuntime(runtime rt.Runtime) Manager

NewManagerFromRuntime creates a new container manager instance from an existing runtime.

type StatusManager

type StatusManager interface {
	// SetWorkloadStatus sets the status of a workload by its name.
	SetWorkloadStatus(ctx context.Context, workloadName string, status WorkloadStatus, contextMsg string) error
	// DeleteWorkloadStatus removes the status of a workload by its name.
	DeleteWorkloadStatus(ctx context.Context, workloadName string) error
}

StatusManager is an interface for fetching and retrieving workload statuses.

func NewStatusManager

func NewStatusManager(ctx context.Context) (StatusManager, error)

NewStatusManager creates a new container manager instance. It instantiates a runtime as part of creating the manager.

func NewStatusManagerFromRuntime

func NewStatusManagerFromRuntime(runtime rt.Runtime) StatusManager

NewStatusManagerFromRuntime creates a new instance of StatusManager from an existing runtime.

type Workload

type Workload struct {
	// Name is the name of the workload.
	// It is used as a unique identifier.
	Name string `json:"name"`
	// Package specifies the Workload Package used to create this Workload.
	Package string `json:"package"`
	// URL is the URL of the workload exposed by the ToolHive proxy.
	URL string `json:"url"`
	// Port is the port on which the workload is exposed.
	// This is embedded in the URL.
	Port int `json:"port"`
	// ToolType is the type of tool this workload represents.
	// For now, it will always be "mcp" - representing an MCP server.
	ToolType string `json:"tool_type"`
	// TransportType is the type of transport used for this workload.
	TransportType types.TransportType `json:"transport_type"`
	// Status is the current status of the workload.
	Status WorkloadStatus `json:"status"`
	// StatusContext provides additional context about the workload's status.
	// The exact meaning is determined by the status and the underlying runtime.
	StatusContext string `json:"status_context,omitempty"`
	// CreatedAt is the timestamp when the workload was created.
	CreatedAt time.Time `json:"created_at"`
}

Workload is a domain model representing a workload in the system. This is used in our API to hide details of the underlying runtime.

func WorkloadFromContainerInfo

func WorkloadFromContainerInfo(container *runtime.ContainerInfo) (Workload, error)

WorkloadFromContainerInfo creates a Workload struct from the runtime container info.

type WorkloadStatus

type WorkloadStatus string

WorkloadStatus is an enum representing the possible statuses of a workload.

const (
	// WorkloadStatusRunning indicates that the workload is currently running.
	WorkloadStatusRunning WorkloadStatus = "running"
	// WorkloadStatusStopped indicates that the workload is stopped.
	WorkloadStatusStopped WorkloadStatus = "stopped"
	// WorkloadStatusError indicates that the workload encountered an error.
	WorkloadStatusError WorkloadStatus = "error"
	// WorkloadStatusStarting indicates that the workload is being started.
	WorkloadStatusStarting WorkloadStatus = "starting"
	// WorkloadStatusUnknown indicates that the workload status is unknown.
	WorkloadStatusUnknown WorkloadStatus = "unknown"
)