runner

package
v0.30.0 Latest Latest
Warning

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

 Go to latest Published: Jul 27, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	RunModeJavaScript = "javascript_script"
	RunModePython     = "python_script"
	RunModeBash       = "bash_script"
)
View Source 
const (
	EnvironmentFromSourceIntegration = "integration"
	EnvironmentFromSourceSecret      = "secret"

	EnvironmentValueSourceLiteral = "literal"
	EnvironmentValueSourceSecret  = "secret"
)
View Source 
const (
	MachineTypeE1LargeAMD64 = "e1-large-amd64"
	MachineTypeE1LargeARM64 = "e1-large-arm64"
	MachineTypeE1TinyAMD64  = "e1-tiny-amd64"
	MachineTypeE1TinyARM64  = "e1-tiny-arm64"
)

Machine type names, which are also the task-broker fleet IDs (GET /v1/fleets) stored in node configuration and sent as fleet_id.

View Source 
const (
	DefaultLiveLogRecordLimit = 200
	MaxLiveLogRecordLimit     = 1000
)
View Source 
const (
	LiveLogStreamTokenPurpose  = "runner_live_logs"
	LiveLogStreamTokenAudience = "task_broker"
)
View Source 
const (
	ExecutionMetadataBrokerTaskID = "runner_broker_task_id"
	ExecutionMetadataTaskLog      = "runner_task_log"
)
View Source 
const (
	RunBashComponentName     = "runnerBash"
	RunBashFinishedEventType = "runnerBash.finished"
)
View Source 
const (
	PassedOutputChannel     = "passed"
	FailedOutputChannel     = "failed"
	RunnerFinishedEventType = "runner.finished"
)
View Source 
const (
	RunJSComponentName     = "runnerJS"
	RunJSFinishedEventType = "runnerJS.finished"
)
View Source 
const (
	RunPythonComponentName     = "runnerPython"
	RunPythonFinishedEventType = "runnerPython.finished"
)
View Source 
const (
	ExecutionModeHost   = "host"
	ExecutionModeDocker = "docker"

	// DockerImagePresetCustom selects the free-text docker_image field instead of a quick-pick ref.
	DockerImagePresetCustom = "custom"

	// DefaultExecutionTimeoutSeconds is the wall-clock limit when a node omits execution_timeout_seconds.
	DefaultExecutionTimeoutSeconds = 3600 // 1 hour
)

Execution modes accepted by the task broker / fleet manager (lowercase JSON).

View Source 
const (
	MachineTypeFieldName              = configurationFieldMachineType
	HookPoll                          = hookActionPoll
	MaxExecutionTimeoutSecondsRequest = maxExecutionTimeoutSecondsRequest
)
View Source 
const ComponentName = "runner"

ComponentName is the registry / canvas component key for Runner.

Variables

View Source 
var (
	ErrLiveLogCanvasNotFound    = errors.New("canvas not found")
	ErrLiveLogExecutionNotFound = errors.New("execution not found")
	ErrLiveLogNodeNotFound      = errors.New("node not found")
	ErrLiveLogNotRunner         = errors.New("not a runner component")
	ErrLiveLogBrokerTaskMissing = errors.New("broker task id missing")
	ErrLiveLogNotConfigured     = errors.New("live logs not configured")
)

Functions

func AfterRunnerTaskCreated added in v0.30.0 

func AfterRunnerTaskCreated(ctx core.ExecutionContext, taskID string) error

func BrokerTaskIDFromExecutionMetadata added in v0.23.0 

func BrokerTaskIDFromExecutionMetadata(meta map[string]any) string

func CancelBrokerTask added in v0.30.0 

func CancelBrokerTask(ctx core.ExecutionContext) error

func EnvironmentFromConfigurationField added in v0.30.0 

func EnvironmentFromConfigurationField() configuration.Field

func HandleBrokerWebhook added in v0.30.0 

func HandleBrokerWebhook(ctx core.WebhookRequestContext, finishedEventType string) (int, *core.WebhookResponseBody, error)

func IntPtr added in v0.30.0 

func IntPtr(v int) *int

func IsRunnerComponent added in v0.28.0 

func IsRunnerComponent(name string) bool

func LiveLogStreamURL added in v0.23.0 

func LiveLogStreamURL(brokerTaskID string) (string, error)

func MachineTypeOptions added in v0.30.0 

func MachineTypeOptions() []configuration.FieldOption

func MintLiveLogStreamToken added in v0.23.0 

func MintLiveLogStreamToken(brokerTaskID string, now time.Time) (string, time.Time, error)

func NewSpecDecoder added in v0.30.0 

func NewSpecDecoder(result any) (*mapstructure.Decoder, error)

func PollBrokerTask added in v0.30.0 

func PollBrokerTask(ctx core.ActionHookContext, finishedEventType string) error

func ProcessBrokerTaskStatus added in v0.30.0 

func ProcessBrokerTaskStatus(state core.ExecutionStateContext, task *Task, finishedEventType string) error

func RegisterRunnerComponent added in v0.30.0 

func RegisterRunnerComponent(name string)

RegisterRunnerComponent marks a runner subpackage component as eligible for live logs.

func ValidateEnvironment added in v0.30.0 

func ValidateEnvironment(environment []EnvironmentVariable) error

func ValidateEnvironmentFrom added in v0.30.0 

func ValidateEnvironmentFrom(environmentFrom []EnvironmentFromEntry) error

func ValidateLiveLogStreamToken added in v0.23.0 

func ValidateLiveLogStreamToken(tokenString, brokerTaskID, secret string) error

ValidateLiveLogStreamToken validates a browser stream token and ensures it matches the requested task.

Types

type ActiveTask added in v0.22.0 

type ActiveTask struct {
	ID                      string     `json:"id"`
	Status                  string     `json:"status"`
	FleetID                 string     `json:"fleet_id"`
	CreatedAt               time.Time  `json:"created_at"`
	ClaimedAt               *time.Time `json:"claimed_at,omitempty"`
	LeaseUntil              *time.Time `json:"lease_until,omitempty"`
	RunnerID                string     `json:"runner_id,omitempty"`
	ExecutionMode           string     `json:"execution_mode,omitempty"`
	DockerImage             string     `json:"docker_image,omitempty"`
	CancelRequested         bool       `json:"cancel_requested,omitempty"`
	ExecutionTimeoutSeconds *int       `json:"execution_timeout_seconds,omitempty"`
}

ActiveTask is a non-terminal task from GET /v1/tasks on the task broker.

type BrokerClient 

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

func NewBrokerClient 

func NewBrokerClient(httpClient core.HTTPContext) (*BrokerClient, error)

func (*BrokerClient) CancelTask added in v0.22.0 

func (b *BrokerClient) CancelTask(brokerTaskID string) error

func (*BrokerClient) CreateTask 

func (b *BrokerClient) CreateTask(p CreateTaskParams) (string, error)

func (*BrokerClient) FetchTaskStatus 

func (b *BrokerClient) FetchTaskStatus(taskID string) (*Task, error)

func (*BrokerClient) ListActiveTasks added in v0.22.0 

func (b *BrokerClient) ListActiveTasks() ([]ActiveTask, error)

func (*BrokerClient) ProcessWebhook 

func (b *BrokerClient) ProcessWebhook(body []byte) (*Task, error)

type BrokerCommand added in v0.30.0 

type BrokerCommand struct {
	Name    string `json:"name,omitempty"`
	Command string `json:"command"`
}

BrokerCommand is one command_list entry sent as {"name","command"} (name optional). Unmarshal still accepts legacy plain strings for tests/fixtures.

func BrokerCommandsFromLines added in v0.30.0 

func BrokerCommandsFromLines(lines []string) []BrokerCommand

BrokerCommandsFromLines adapts plain shell lines into unnamed broker commands.

func (*BrokerCommand) UnmarshalJSON added in v0.30.0 

func (c *BrokerCommand) UnmarshalJSON(data []byte) error

type BrokerEnvironmentVariable 

type BrokerEnvironmentVariable struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

BrokerEnvironmentVariable is forwarded to the task broker as JSON.

func ResolveEnvironment added in v0.30.0 

func ResolveEnvironment(
	secrets core.SecretsContext,
	environmentFrom []EnvironmentFromEntry,
	environment []EnvironmentVariable,
) ([]BrokerEnvironmentVariable, error)

type BrokerTaskFile added in v0.30.0 

type BrokerTaskFile struct {
	Path    string `json:"path"`
	Content string `json:"content"`
	Mode    string `json:"mode,omitempty"`
}

BrokerTaskFile is materialized under SUPERPLANE_TASK_DIR before execution.

type CreateTaskParams 

type CreateTaskParams struct {
	MachineType             string
	RunMode                 string
	Script                  string
	MessageChain            json.RawMessage
	Commands                []BrokerCommand
	SetupCommands           []string
	WebhookURL              string
	WebhookPayloadSizeLimit int
	Environment             []BrokerEnvironmentVariable
	Files                   []BrokerTaskFile
	ExecutionMode           string
	DockerImage             string
	TimeoutSeconds          int // 0 = DefaultExecutionTimeoutSeconds
}

CreateTaskParams is forwarded to the task broker POST /v1/tasks.

type EnvironmentFromEntry added in v0.30.0 

type EnvironmentFromEntry struct {
	Source      string                       `json:"source" mapstructure:"source"`
	Integration configuration.IntegrationRef `json:"integration,omitempty" mapstructure:"integration"`
	Secret      configuration.SecretRef      `json:"secret,omitempty" mapstructure:"secret"`
}

type EnvironmentVariable 

type EnvironmentVariable struct {
	Name        string                     `json:"name" mapstructure:"name"`
	ValueSource string                     `json:"valueSource" mapstructure:"valueSource"`
	Value       *string                    `json:"value,omitempty" mapstructure:"value"`
	Secret      configuration.SecretKeyRef `json:"secret,omitempty" mapstructure:"secret"`
}

EnvironmentVariable is one row in the Runner "Environment variables" list.

type LiveLogAccessContext added in v0.23.0 

type LiveLogAccessContext struct {
	BrokerTaskID string
}

LiveLogAccessContext is the resolved runner execution context for live log access.

func ResolveLiveLogAccess added in v0.23.0 

func ResolveLiveLogAccess(orgID uuid.UUID, canvasID uuid.UUID, executionID uuid.UUID) (*LiveLogAccessContext, error)

type LiveLogFetchOptions added in v0.28.0 

type LiveLogFetchOptions struct {
	Limit       int
	HTTPClient  *http.Client
	Now         time.Time
	IdleTimeout time.Duration
}

type LiveLogFetchResult added in v0.28.0 

type LiveLogFetchResult struct {
	Records   []LiveLogRecord
	Truncated bool
}

func FetchLiveLogRecords added in v0.28.0 

func FetchLiveLogRecords(ctx context.Context, brokerTaskID string, opts LiveLogFetchOptions) (*LiveLogFetchResult, error)

func FetchLiveLogSessionRecords added in v0.28.0 

func FetchLiveLogSessionRecords(ctx context.Context, session LiveLogSession, opts LiveLogFetchOptions) (*LiveLogFetchResult, error)

type LiveLogRecord added in v0.28.0 

type LiveLogRecord struct {
	Type       string `json:"type,omitempty"`
	Text       string `json:"text,omitempty"`
	Message    string `json:"message,omitempty"`
	Index      *int   `json:"index,omitempty"`
	Status     string `json:"status,omitempty"`
	DurationMS *int64 `json:"duration_ms,omitempty"`
	StartedAt  *int64 `json:"started_at,omitempty"`
}

type LiveLogSession added in v0.23.0 

type LiveLogSession struct {
	StreamURL string    `json:"stream_url"`
	Token     string    `json:"token"`
	ExpiresAt time.Time `json:"expires_at"`
}

LiveLogSession is returned to the browser after SuperPlane authorizes log access.

func NewLiveLogSession added in v0.23.0 

func NewLiveLogSession(brokerTaskID string, now time.Time) (*LiveLogSession, error)

type LiveLogStreamTokenClaims added in v0.23.0 

type LiveLogStreamTokenClaims struct {
	TaskID  string `json:"task_id"`
	Purpose string `json:"purpose"`
	gojwt.RegisteredClaims
}

LiveLogStreamTokenClaims is the JWT payload SuperPlane mints for browser → task-broker streaming.

type RunBash added in v0.25.1 

type RunBash struct{}

func (*RunBash) Cancel added in v0.25.1 

func (c *RunBash) Cancel(ctx core.ExecutionContext) error

func (*RunBash) Cleanup added in v0.25.1 

func (c *RunBash) Cleanup(ctx core.SetupContext) error

func (*RunBash) Color added in v0.25.1 

func (c *RunBash) Color() string

func (*RunBash) Configuration added in v0.25.1 

func (c *RunBash) Configuration() []configuration.Field

func (*RunBash) Description added in v0.25.1 

func (c *RunBash) Description() string

func (*RunBash) Documentation added in v0.25.1 

func (c *RunBash) Documentation() string

func (*RunBash) ExampleOutput added in v0.25.1 

func (c *RunBash) ExampleOutput() map[string]any

func (*RunBash) Execute added in v0.25.1 

func (c *RunBash) Execute(ctx core.ExecutionContext) error

func (*RunBash) HandleHook added in v0.25.1 

func (c *RunBash) HandleHook(ctx core.ActionHookContext) error

func (*RunBash) HandleWebhook added in v0.25.1 

func (c *RunBash) HandleWebhook(ctx core.WebhookRequestContext) (int, *core.WebhookResponseBody, error)

func (*RunBash) Hooks added in v0.25.1 

func (c *RunBash) Hooks() []core.Hook

func (*RunBash) Icon added in v0.25.1 

func (c *RunBash) Icon() string

func (*RunBash) Label added in v0.25.1 

func (c *RunBash) Label() string

func (*RunBash) Name added in v0.25.1 

func (c *RunBash) Name() string

func (*RunBash) OutputChannels added in v0.25.1 

func (c *RunBash) OutputChannels(configuration any) []core.OutputChannel

func (*RunBash) ProcessQueueItem added in v0.25.1 

func (c *RunBash) ProcessQueueItem(ctx core.ProcessQueueContext) (*uuid.UUID, error)

func (*RunBash) Setup added in v0.25.1 

func (c *RunBash) Setup(ctx core.SetupContext) error

type RunBashSpec added in v0.25.1 

type RunBashSpec struct {
	MachineType             string                 `mapstructure:"machine_type"`
	Script                  string                 `mapstructure:"script"`
	EnableSetupCommands     bool                   `mapstructure:"enable_setup_commands"`
	SetupCommands           string                 `mapstructure:"setup_commands"`
	EnvironmentFrom         []EnvironmentFromEntry `mapstructure:"environmentFrom"`
	Environment             []EnvironmentVariable  `mapstructure:"environment"`
	ExecutionMode           string                 `mapstructure:"execution_mode"`
	DockerImagePreset       string                 `mapstructure:"docker_image_preset"`
	DockerImage             string                 `mapstructure:"docker_image"`
	ExecutionTimeoutSeconds int                    `mapstructure:"execution_timeout_seconds"` // 0 = DefaultExecutionTimeoutSeconds
}

RunBashSpec is persisted runnerBash node configuration.

type RunJS added in v0.25.0 

type RunJS struct{}

func (*RunJS) Cancel added in v0.25.0 

func (c *RunJS) Cancel(ctx core.ExecutionContext) error

func (*RunJS) Cleanup added in v0.25.0 

func (c *RunJS) Cleanup(ctx core.SetupContext) error

func (*RunJS) Color added in v0.25.0 

func (c *RunJS) Color() string

func (*RunJS) Configuration added in v0.25.0 

func (c *RunJS) Configuration() []configuration.Field

func (*RunJS) Description added in v0.25.0 

func (c *RunJS) Description() string

func (*RunJS) Documentation added in v0.25.0 

func (c *RunJS) Documentation() string

func (*RunJS) ExampleOutput added in v0.25.0 

func (c *RunJS) ExampleOutput() map[string]any

func (*RunJS) Execute added in v0.25.0 

func (c *RunJS) Execute(ctx core.ExecutionContext) error

func (*RunJS) HandleHook added in v0.25.0 

func (c *RunJS) HandleHook(ctx core.ActionHookContext) error

func (*RunJS) HandleWebhook added in v0.25.0 

func (c *RunJS) HandleWebhook(ctx core.WebhookRequestContext) (int, *core.WebhookResponseBody, error)

func (*RunJS) Hooks added in v0.25.0 

func (c *RunJS) Hooks() []core.Hook

func (*RunJS) Icon added in v0.25.0 

func (c *RunJS) Icon() string

func (*RunJS) Label added in v0.25.0 

func (c *RunJS) Label() string

func (*RunJS) Name added in v0.25.0 

func (c *RunJS) Name() string

func (*RunJS) OutputChannels added in v0.25.0 

func (c *RunJS) OutputChannels(configuration any) []core.OutputChannel

func (*RunJS) ProcessQueueItem added in v0.25.0 

func (c *RunJS) ProcessQueueItem(ctx core.ProcessQueueContext) (*uuid.UUID, error)

func (*RunJS) Setup added in v0.25.0 

func (c *RunJS) Setup(ctx core.SetupContext) error

type RunJSSpec added in v0.25.0 

type RunJSSpec struct {
	MachineType             string                 `mapstructure:"machine_type"`
	Script                  string                 `mapstructure:"script"`
	EnableSetupCommands     bool                   `mapstructure:"enable_setup_commands"`
	SetupCommands           string                 `mapstructure:"setup_commands"`
	EnvironmentFrom         []EnvironmentFromEntry `mapstructure:"environmentFrom"`
	Environment             []EnvironmentVariable  `mapstructure:"environment"`
	ExecutionMode           string                 `mapstructure:"execution_mode"`
	DockerImagePreset       string                 `mapstructure:"docker_image_preset"`
	DockerImage             string                 `mapstructure:"docker_image"`
	ExecutionTimeoutSeconds int                    `mapstructure:"execution_timeout_seconds"` // 0 = DefaultExecutionTimeoutSeconds
}

RunJSSpec is persisted runnerJS node configuration.

type RunPython added in v0.25.0 

type RunPython struct{}

func (*RunPython) Cancel added in v0.25.0 

func (c *RunPython) Cancel(ctx core.ExecutionContext) error

func (*RunPython) Cleanup added in v0.25.0 

func (c *RunPython) Cleanup(ctx core.SetupContext) error

func (*RunPython) Color added in v0.25.0 

func (c *RunPython) Color() string

func (*RunPython) Configuration added in v0.25.0 

func (c *RunPython) Configuration() []configuration.Field

func (*RunPython) Description added in v0.25.0 

func (c *RunPython) Description() string

func (*RunPython) Documentation added in v0.25.0 

func (c *RunPython) Documentation() string

func (*RunPython) ExampleOutput added in v0.25.0 

func (c *RunPython) ExampleOutput() map[string]any

func (*RunPython) Execute added in v0.25.0 

func (c *RunPython) Execute(ctx core.ExecutionContext) error

func (*RunPython) HandleHook added in v0.25.0 

func (c *RunPython) HandleHook(ctx core.ActionHookContext) error

func (*RunPython) HandleWebhook added in v0.25.0 

func (c *RunPython) HandleWebhook(ctx core.WebhookRequestContext) (int, *core.WebhookResponseBody, error)

func (*RunPython) Hooks added in v0.25.0 

func (c *RunPython) Hooks() []core.Hook

func (*RunPython) Icon added in v0.25.0 

func (c *RunPython) Icon() string

func (*RunPython) Label added in v0.25.0 

func (c *RunPython) Label() string

func (*RunPython) Name added in v0.25.0 

func (c *RunPython) Name() string

func (*RunPython) OutputChannels added in v0.25.0 

func (c *RunPython) OutputChannels(configuration any) []core.OutputChannel

func (*RunPython) ProcessQueueItem added in v0.25.0 

func (c *RunPython) ProcessQueueItem(ctx core.ProcessQueueContext) (*uuid.UUID, error)

func (*RunPython) Setup added in v0.25.0 

func (c *RunPython) Setup(ctx core.SetupContext) error

type RunPythonSpec added in v0.25.0 

type RunPythonSpec struct {
	MachineType             string                 `mapstructure:"machine_type"`
	Script                  string                 `mapstructure:"script"`
	EnableSetupCommands     bool                   `mapstructure:"enable_setup_commands"`
	SetupCommands           string                 `mapstructure:"setup_commands"`
	EnvironmentFrom         []EnvironmentFromEntry `mapstructure:"environmentFrom"`
	Environment             []EnvironmentVariable  `mapstructure:"environment"`
	ExecutionMode           string                 `mapstructure:"execution_mode"`
	DockerImagePreset       string                 `mapstructure:"docker_image_preset"`
	DockerImage             string                 `mapstructure:"docker_image"`
	ExecutionTimeoutSeconds int                    `mapstructure:"execution_timeout_seconds"` // 0 = DefaultExecutionTimeoutSeconds
}

RunPythonSpec is persisted runnerPython node configuration.

type Runner 

type Runner struct{}

func (*Runner) Cancel 

func (c *Runner) Cancel(ctx core.ExecutionContext) error

func (*Runner) Cleanup 

func (c *Runner) Cleanup(ctx core.SetupContext) error

func (*Runner) Color 

func (c *Runner) Color() string

func (*Runner) Configuration 

func (c *Runner) Configuration() []configuration.Field

func (*Runner) Description 

func (c *Runner) Description() string

func (*Runner) Documentation 

func (c *Runner) Documentation() string

func (*Runner) ExampleOutput 

func (c *Runner) ExampleOutput() map[string]any

func (*Runner) Execute 

func (c *Runner) Execute(ctx core.ExecutionContext) error

func (*Runner) HandleHook 

func (c *Runner) HandleHook(ctx core.ActionHookContext) error

func (*Runner) HandleWebhook 

func (c *Runner) HandleWebhook(ctx core.WebhookRequestContext) (int, *core.WebhookResponseBody, error)

func (*Runner) Hooks 

func (c *Runner) Hooks() []core.Hook

func (*Runner) Icon 

func (c *Runner) Icon() string

func (*Runner) Label 

func (c *Runner) Label() string

func (*Runner) Name 

func (c *Runner) Name() string

func (*Runner) OutputChannels 

func (c *Runner) OutputChannels(configuration any) []core.OutputChannel

func (*Runner) ProcessQueueItem 

func (c *Runner) ProcessQueueItem(ctx core.ProcessQueueContext) (*uuid.UUID, error)

func (*Runner) Setup 

func (c *Runner) Setup(ctx core.SetupContext) error

type Spec 

type Spec struct {
	MachineType             string                 `mapstructure:"machine_type"`
	Commands                string                 `mapstructure:"commands"`
	EnvironmentFrom         []EnvironmentFromEntry `mapstructure:"environmentFrom"`
	Environment             []EnvironmentVariable  `mapstructure:"environment"`
	ExecutionMode           string                 `mapstructure:"execution_mode"`
	DockerImagePreset       string                 `mapstructure:"docker_image_preset"`
	DockerImage             string                 `mapstructure:"docker_image"`
	ExecutionTimeoutSeconds int                    `mapstructure:"execution_timeout_seconds"` // 0 = DefaultExecutionTimeoutSeconds
}

Spec is persisted Runner node configuration.

type Task 

type Task struct {
	TaskID   string          `json:"task_id"`
	Status   string          `json:"status"`
	ExitCode *int            `json:"exit_code,omitempty"`
	Output   string          `json:"output,omitempty"`
	Error    string          `json:"error,omitempty"`
	Result   json.RawMessage `json:"result,omitempty"`

	TaskLog *TaskLogSink `json:"task_log,omitempty"`

	CloudWatchLogGroup  string `json:"cloudwatch_log_group,omitempty"`
	CloudWatchLogStream string `json:"cloudwatch_log_stream,omitempty"`
}

Task is the broker task payload (GET /v1/tasks/:id and webhook body).

func (*Task) IsInTerminalState 

func (t *Task) IsInTerminalState() bool

type TaskLogSink 

type TaskLogSink struct {
	Type       string `json:"type"`
	CloudWatch *struct {
		LogGroupName  string `json:"log_group_name"`
		LogStreamName string `json:"log_stream_name"`
		Region        string `json:"region,omitempty"`
	} `json:"cloudwatch,omitempty"`
}

TaskLogSink matches the task-broker / fleet-manager JSON shape for CloudWatch-backed live logs.

Source Files

View all Source files

Directories

Path Synopsis

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.