types

package
v0.21.0 Latest Latest
Warning

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

 Go to latest Published: May 4, 2026 License: AGPL-3.0 Imports: 5 Imported by: 0

Documentation

Overview

Package types provides core types for SSH-based automation.

Package types provides shared types for ork packages.

Package types provides core types for SSH-based automation.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultHostKeyAlgorithms = []string{
	"ecdsa-sha2-nistp256",
	"ecdsa-sha2-nistp384",
	"ecdsa-sha2-nistp521",
	"rsa-sha2-256",
	"rsa-sha2-512",
	"ssh-ed25519",
}

DefaultHostKeyAlgorithms are the default host key algorithms for SSH. These are widely compatible with modern SSH servers while being supported by golang.org/x/crypto/ssh.

View Source 
var DefaultKexAlgorithms = []string{
	"ecdh-sha2-nistp256",
	"ecdh-sha2-nistp384",
	"ecdh-sha2-nistp521",
	"diffie-hellman-group-exchange-sha256",
	"diffie-hellman-group16-sha512",
	"diffie-hellman-group18-sha512",
	"diffie-hellman-group14-sha256",
}

DefaultKexAlgorithms are the default KEX algorithms for SSH key exchange. These are widely compatible with modern SSH servers while being supported by golang.org/x/crypto/ssh.

Functions

This section is empty.

Types

type BaseBecome added in v0.12.0 

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

BaseBecome provides a default implementation of BecomeInterface. Embed this in structs that need privilege escalation support.

func (*BaseBecome) GetBecomeUser added in v0.12.0 

func (b *BaseBecome) GetBecomeUser() string

GetBecomeUser returns the configured become user. Returns empty string if not set.

func (*BaseBecome) SetBecomeUser added in v0.12.0 

func (b *BaseBecome) SetBecomeUser(user string) BecomeInterface

SetBecomeUser sets the user to become when executing commands. Returns BecomeInterface for fluent method chaining.

type BasePlaybook added in v0.11.0 

type BasePlaybook struct {
	BaseBecome
	// contains filtered or unexported fields
}

BasePlaybook provides a foundation for playbook development. Embed this in your playbook struct to get boilerplate getter/setter methods. Only implement Run() for the specific playbook logic (Check() is optional).

Example usage: 

type MyPlaybook struct {
    *BasePlaybook
}

func NewMyPlaybook() *MyPlaybook {
    return &MyPlaybook{
        BasePlaybook: types.NewBasePlaybook().
            SetID("my-playbook").
            SetDescription("What this playbook does"),
    }
}

func (m *MyPlaybook) Run() Result {
    // Execute the playbook with complex orchestration logic
}

func NewBasePlaybook added in v0.11.0 

func NewBasePlaybook() *BasePlaybook

NewBasePlaybook creates a new BasePlaybook with default values. Use the setter methods to configure it before returning from your constructor.

func (*BasePlaybook) Check added in v0.11.0 

func (b *BasePlaybook) Check() (bool, error)

Check returns false (no changes needed) by default. Playbooks can override this to provide idempotency checks, but it's optional since playbooks often have complex logic that makes checking difficult.

func (*BasePlaybook) GetArg added in v0.11.0 

func (b *BasePlaybook) GetArg(key string) string

GetArg retrieves a single argument value by key.

func (*BasePlaybook) GetArgs added in v0.11.0 

func (b *BasePlaybook) GetArgs() map[string]string

GetArgs returns the entire arguments map.

func (*BasePlaybook) GetDescription added in v0.11.0 

func (b *BasePlaybook) GetDescription() string

GetDescription returns a short description of what the playbook does.

func (*BasePlaybook) GetID added in v0.11.0 

func (b *BasePlaybook) GetID() string

GetID returns the unique identifier for this playbook.

func (*BasePlaybook) GetNodeConfig added in v0.11.0 

func (b *BasePlaybook) GetNodeConfig() NodeConfig

GetNodeConfig returns the current node configuration for this playbook.

func (*BasePlaybook) GetTimeout added in v0.11.0 

func (b *BasePlaybook) GetTimeout() time.Duration

GetTimeout returns the maximum duration for playbook execution.

func (*BasePlaybook) IsDryRun added in v0.11.0 

func (b *BasePlaybook) IsDryRun() bool

IsDryRun returns true if this is a dry-run execution.

func (*BasePlaybook) Run added in v0.11.0 

func (b *BasePlaybook) Run() Result

Run must be overridden by playbook implementations. Playbooks implement complex orchestration logic here.

func (*BasePlaybook) SetArg added in v0.11.0 

func (b *BasePlaybook) SetArg(key, value string) RunnableInterface

SetArg sets a single argument value. Returns RunnableInterface for fluent method chaining.

func (*BasePlaybook) SetArgs added in v0.11.0 

func (b *BasePlaybook) SetArgs(args map[string]string) RunnableInterface

SetArgs replaces the entire arguments map. Returns RunnableInterface for fluent method chaining.

func (*BasePlaybook) SetDescription added in v0.11.0 

func (b *BasePlaybook) SetDescription(description string) RunnableInterface

SetDescription sets a short description of what the playbook does. Returns RunnableInterface for fluent method chaining with embedding types.

func (*BasePlaybook) SetDryRun added in v0.11.0 

func (b *BasePlaybook) SetDryRun(dryRun bool) RunnableInterface

SetDryRun sets whether to simulate execution without making changes. Returns RunnableInterface for fluent method chaining.

func (*BasePlaybook) SetID added in v0.11.0 

func (b *BasePlaybook) SetID(id string) RunnableInterface

SetID sets the unique identifier for this playbook. Returns RunnableInterface for fluent method chaining with embedding types.

func (*BasePlaybook) SetNodeConfig added in v0.11.0 

func (b *BasePlaybook) SetNodeConfig(cfg NodeConfig) RunnableInterface

SetNodeConfig sets the node configuration for this playbook execution. Returns RunnableInterface for fluent method chaining with embedding types.

func (*BasePlaybook) SetTimeout added in v0.11.0 

func (b *BasePlaybook) SetTimeout(timeout time.Duration) RunnableInterface

SetTimeout sets the maximum duration for playbook execution. Returns RunnableInterface for fluent method chaining.

func (*BasePlaybook) WithArg added in v0.16.0 

func (b *BasePlaybook) WithArg(key, value string) *BasePlaybook

WithArg sets a single argument and returns BasePlaybook for chaining. Shortcut alias to SetArg for fluent interface convenience.

func (*BasePlaybook) WithArgs added in v0.16.0 

func (b *BasePlaybook) WithArgs(args map[string]string) *BasePlaybook

WithArgs replaces the arguments map and returns BasePlaybook for chaining. Shortcut alias to SetArgs for fluent interface convenience.

func (*BasePlaybook) WithBecomeUser added in v0.16.0 

func (b *BasePlaybook) WithBecomeUser(user string) *BasePlaybook

WithBecomeUser sets the become user and returns BasePlaybook for chaining. Shortcut alias to SetBecomeUser for fluent interface convenience.

func (*BasePlaybook) WithDescription added in v0.16.0 

func (b *BasePlaybook) WithDescription(description string) *BasePlaybook

WithDescription sets a description and returns BasePlaybook for chaining. Shortcut alias to SetDescription for fluent interface convenience.

func (*BasePlaybook) WithDryRun added in v0.16.0 

func (b *BasePlaybook) WithDryRun(dryRun bool) *BasePlaybook

WithDryRun sets dry-run mode and returns BasePlaybook for chaining. Shortcut alias to SetDryRun for fluent interface convenience.

func (*BasePlaybook) WithID added in v0.16.0 

func (b *BasePlaybook) WithID(id string) *BasePlaybook

WithID sets the unique identifier and returns BasePlaybook for chaining. Shortcut alias to SetID for fluent interface convenience.

func (*BasePlaybook) WithNodeConfig added in v0.16.0 

func (b *BasePlaybook) WithNodeConfig(cfg NodeConfig) *BasePlaybook

WithNodeConfig sets the node config and returns BasePlaybook for chaining. Shortcut alias to SetNodeConfig for fluent interface convenience.

func (*BasePlaybook) WithTimeout added in v0.16.0 

func (b *BasePlaybook) WithTimeout(timeout time.Duration) *BasePlaybook

WithTimeout sets the timeout and returns BasePlaybook for chaining. Shortcut alias to SetTimeout for fluent interface convenience.

type BaseSkill added in v0.11.0 

type BaseSkill struct {
	BaseBecome
	// contains filtered or unexported fields
}

BaseSkill provides default implementations of the RunnableInterface. Embed this in your skill struct to get boilerplate getter/setter methods. Only implement Check() and Run() for the specific skill logic.

Example usage with fluent chaining: 

type MySkill struct {
    *BaseSkill
}

func NewMySkill() *MySkill {
    return &MySkill{
        BaseSkill: types.NewBaseSkill().
            WithID("my-skill").
            WithDescription("What this skill does").
            WithDryRun(false),
    }
}

func (m *MySkill) Check() (bool, error) {
    // Check if changes are needed
}

func (m *MySkill) Run() Result {
    // Execute the skill
}

func NewBaseSkill added in v0.11.0 

func NewBaseSkill() *BaseSkill

NewBaseSkill creates a new BaseSkill with default values. Use the setter methods to configure it before returning from your constructor.

func (*BaseSkill) Check added in v0.11.0 

func (b *BaseSkill) Check() (bool, error)

Check is a stub that embedding types must override.

func (*BaseSkill) GetArg added in v0.11.0 

func (b *BaseSkill) GetArg(key string) string

GetArg retrieves a single argument value by key.

func (*BaseSkill) GetArgs added in v0.11.0 

func (b *BaseSkill) GetArgs() map[string]string

GetArgs returns the entire arguments map.

func (*BaseSkill) GetDescription added in v0.11.0 

func (b *BaseSkill) GetDescription() string

GetDescription returns a short description of what the skill does.

func (*BaseSkill) GetID added in v0.11.0 

func (b *BaseSkill) GetID() string

GetID returns the unique identifier for this skill.

func (*BaseSkill) GetNodeConfig added in v0.11.0 

func (b *BaseSkill) GetNodeConfig() NodeConfig

GetNodeConfig returns the current node configuration for this skill.

func (*BaseSkill) GetTimeout added in v0.11.0 

func (b *BaseSkill) GetTimeout() time.Duration

GetTimeout returns the maximum duration for skill execution.

func (*BaseSkill) IsDryRun added in v0.11.0 

func (b *BaseSkill) IsDryRun() bool

IsDryRun returns true if this is a dry-run execution.

func (*BaseSkill) Run added in v0.11.0 

func (b *BaseSkill) Run() Result

Run is a stub that embedding types must override.

func (*BaseSkill) SetArg added in v0.11.0 

func (b *BaseSkill) SetArg(key, value string) RunnableInterface

SetArg sets a single argument value. Returns RunnableInterface for fluent method chaining.

func (*BaseSkill) SetArgs added in v0.11.0 

func (b *BaseSkill) SetArgs(args map[string]string) RunnableInterface

SetArgs replaces the entire arguments map. Returns RunnableInterface for fluent method chaining.

func (*BaseSkill) SetDescription added in v0.11.0 

func (b *BaseSkill) SetDescription(description string) RunnableInterface

SetDescription sets a short description of what the skill does. Returns RunnableInterface for fluent method chaining with embedding types.

func (*BaseSkill) SetDryRun added in v0.11.0 

func (b *BaseSkill) SetDryRun(dryRun bool) RunnableInterface

SetDryRun sets whether to simulate execution without making changes. Returns RunnableInterface for fluent method chaining.

func (*BaseSkill) SetID added in v0.11.0 

func (b *BaseSkill) SetID(id string) RunnableInterface

SetID sets the unique identifier for this skill. Returns RunnableInterface for fluent method chaining with embedding types.

func (*BaseSkill) SetNodeConfig added in v0.11.0 

func (b *BaseSkill) SetNodeConfig(cfg NodeConfig) RunnableInterface

SetNodeConfig sets the node configuration for this skill execution. Returns RunnableInterface for fluent method chaining with embedding types.

func (*BaseSkill) SetTimeout added in v0.11.0 

func (b *BaseSkill) SetTimeout(timeout time.Duration) RunnableInterface

SetTimeout sets the maximum duration for skill execution. Returns RunnableInterface for fluent method chaining.

func (*BaseSkill) WithArg added in v0.16.0 

func (b *BaseSkill) WithArg(key, value string) *BaseSkill

WithArg sets a single argument and returns BaseSkill for chaining. Shortcut alias to SetArg for fluent interface convenience.

func (*BaseSkill) WithArgs added in v0.16.0 

func (b *BaseSkill) WithArgs(args map[string]string) *BaseSkill

WithArgs replaces the arguments map and returns BaseSkill for chaining. Shortcut alias to SetArgs for fluent interface convenience.

func (*BaseSkill) WithBecomeUser added in v0.16.0 

func (b *BaseSkill) WithBecomeUser(user string) *BaseSkill

WithBecomeUser sets the become user and returns BaseSkill for chaining. Shortcut alias to SetBecomeUser for fluent interface convenience.

func (*BaseSkill) WithDescription added in v0.16.0 

func (b *BaseSkill) WithDescription(description string) *BaseSkill

WithDescription sets a description and returns BaseSkill for chaining. Shortcut alias to SetDescription for fluent interface convenience.

func (*BaseSkill) WithDryRun added in v0.16.0 

func (b *BaseSkill) WithDryRun(dryRun bool) *BaseSkill

WithDryRun sets dry-run mode and returns BaseSkill for chaining. Shortcut alias to SetDryRun for fluent interface convenience.

func (*BaseSkill) WithID added in v0.16.0 

func (b *BaseSkill) WithID(id string) *BaseSkill

WithID sets the unique identifier and returns BaseSkill for chaining. Shortcut alias to SetID for fluent interface convenience.

func (*BaseSkill) WithNodeConfig added in v0.16.0 

func (b *BaseSkill) WithNodeConfig(cfg NodeConfig) *BaseSkill

WithNodeConfig sets the node config and returns BaseSkill for chaining. Shortcut alias to SetNodeConfig for fluent interface convenience.

func (*BaseSkill) WithTimeout added in v0.16.0 

func (b *BaseSkill) WithTimeout(timeout time.Duration) *BaseSkill

WithTimeout sets the timeout and returns BaseSkill for chaining. Shortcut alias to SetTimeout for fluent interface convenience.

type BecomeInterface added in v0.12.0 

type BecomeInterface interface {
	// SetBecomeUser sets the user to become when executing commands.
	// If empty, no privilege escalation is performed.
	// Returns BecomeInterface for fluent method chaining.
	SetBecomeUser(user string) BecomeInterface

	// GetBecomeUser returns the configured become user.
	// Returns empty string if not set.
	GetBecomeUser() string
}

BecomeInterface defines privilege escalation capabilities. It allows running commands as a different user via sudo.

Example: 

node.SetBecomeUser("root")
node.RunCommand("apt-get update")  // Runs: sudo -u root apt-get update

type Command added in v0.10.0 

type Command struct {
	Command     string
	Description string
	Chdir       string // Working directory for command execution
	BecomeUser  string // User to become when executing command (e.g., "postgres", "www-data")
	Required    bool   // Whether the command must succeed for execution to continue
}

Command represents a shell command with its description and optional execution settings.

It is used to display and execute shell commands in a structured way.

Also useful when running in dry-run mode to see what commands would be executed.

Example:

  • Command: "ls -la"
  • Description: "List all files in long format"
  • Chdir: "/var/www"
  • BecomeUser: "www-data"
  • Required: true

Usage:

  • command := types.Command{Command: "ls -la", Description: "List all files in long format", Chdir: "/var/www"}

type NodeConfig added in v0.11.0 

type NodeConfig struct {
	// SSH connection settings
	SSHHost  string
	SSHPort  string
	SSHLogin string
	SSHKey   string

	// User settings
	RootUser    string
	NonRootUser string

	// Database settings (when applicable)
	DBPort         string
	DBRootPassword string

	// Extra arguments passed via command line
	Args map[string]string

	// Logger for structured logging. Defaults to slog.Default() if nil.
	Logger *slog.Logger

	// IsDryRunMode indicates whether to simulate execution without making changes.
	// When true, ssh.Run() will log commands and return "[dry-run]" marker instead of executing.
	IsDryRunMode bool

	// BecomeUser is the user to become when executing commands via sudo.
	// If empty, no privilege escalation is performed.
	BecomeUser string

	// Chdir is the working directory for command execution.
	// If set, commands will be executed in this directory.
	Chdir string

	// KexAlgorithms specifies the key exchange algorithms to use for SSH.
	// If empty, defaults to DefaultKexAlgorithms.
	KexAlgorithms []string

	// HostKeyAlgorithms specifies the host key algorithms to use for SSH.
	// If empty, defaults to DefaultHostKeyAlgorithms.
	HostKeyAlgorithms []string
}

NodeConfig holds all configuration variables for remote server operations.

func (NodeConfig) GetArg added in v0.11.0 

func (c NodeConfig) GetArg(key string) string

GetArg retrieves an argument from the Args map. Returns empty string if not found.

func (NodeConfig) GetArgOr added in v0.11.0 

func (c NodeConfig) GetArgOr(key, defaultValue string) string

GetArgOr retrieves an argument from the Args map with a default value.

func (NodeConfig) GetLoggerOrDefault added in v0.11.0 

func (c NodeConfig) GetLoggerOrDefault() *slog.Logger

GetLoggerOrDefault returns the configured logger or slog.Default() if nil.

func (NodeConfig) SSHAddr added in v0.11.0 

func (c NodeConfig) SSHAddr() string

SSHAddr returns the full SSH address as host:port. Defaults to port 22 if SSHPort is not set.

func (*NodeConfig) SetChdir added in v0.15.0 

func (c *NodeConfig) SetChdir(dir string)

SetChdir sets the working directory for command execution.

func (*NodeConfig) WithArg added in v0.16.0 

func (c *NodeConfig) WithArg(key, value string) *NodeConfig

WithArg sets a single argument and returns NodeConfig for chaining.

func (*NodeConfig) WithArgs added in v0.16.0 

func (c *NodeConfig) WithArgs(args map[string]string) *NodeConfig

WithArgs replaces the arguments map and returns NodeConfig for chaining.

func (*NodeConfig) WithBecomeUser added in v0.16.0 

func (c *NodeConfig) WithBecomeUser(user string) *NodeConfig

WithBecomeUser sets the become user and returns NodeConfig for chaining.

func (*NodeConfig) WithChdir added in v0.16.0 

func (c *NodeConfig) WithChdir(dir string) *NodeConfig

WithChdir sets the working directory and returns NodeConfig for chaining.

func (*NodeConfig) WithDBPort added in v0.16.0 

func (c *NodeConfig) WithDBPort(port string) *NodeConfig

WithDBPort sets the database port and returns NodeConfig for chaining.

func (*NodeConfig) WithDBRootPassword added in v0.16.0 

func (c *NodeConfig) WithDBRootPassword(password string) *NodeConfig

WithDBRootPassword sets the database root password and returns NodeConfig for chaining.

func (*NodeConfig) WithDryRun added in v0.16.0 

func (c *NodeConfig) WithDryRun(dryRun bool) *NodeConfig

WithDryRun sets dry-run mode and returns NodeConfig for chaining.

func (*NodeConfig) WithHost added in v0.16.0 

func (c *NodeConfig) WithHost(host string) *NodeConfig

WithHost sets the SSH host and returns NodeConfig for chaining.

func (*NodeConfig) WithHostKeyAlgorithms added in v0.19.0 

func (c *NodeConfig) WithHostKeyAlgorithms(algorithms []string) *NodeConfig

func (*NodeConfig) WithKexAlgorithms added in v0.19.0 

func (c *NodeConfig) WithKexAlgorithms(algorithms []string) *NodeConfig

func (*NodeConfig) WithKey added in v0.16.0 

func (c *NodeConfig) WithKey(key string) *NodeConfig

WithKey sets the SSH key path and returns NodeConfig for chaining.

func (*NodeConfig) WithLogger added in v0.16.0 

func (c *NodeConfig) WithLogger(logger *slog.Logger) *NodeConfig

WithLogger sets the logger and returns NodeConfig for chaining.

func (*NodeConfig) WithLogin added in v0.16.0 

func (c *NodeConfig) WithLogin(login string) *NodeConfig

WithLogin sets the SSH login user and returns NodeConfig for chaining.

func (*NodeConfig) WithNonRootUser added in v0.16.0 

func (c *NodeConfig) WithNonRootUser(user string) *NodeConfig

WithNonRootUser sets the non-root user and returns NodeConfig for chaining.

func (*NodeConfig) WithPort added in v0.16.0 

func (c *NodeConfig) WithPort(port string) *NodeConfig

WithPort sets the SSH port and returns NodeConfig for chaining.

func (*NodeConfig) WithRootUser added in v0.16.0 

func (c *NodeConfig) WithRootUser(user string) *NodeConfig

WithRootUser sets the root user and returns NodeConfig for chaining.

type PromptConfig added in v0.11.0 

type PromptConfig struct {
	Name     string             // Variable name
	Prompt   string             // Prompt message to display
	Private  bool               // Hide input (true) or show it (false)
	Default  string             // Default value if user provides no input
	Confirm  bool               // Require confirmation (for passwords)
	Validate func(string) error // Validation function
	Required bool               // Whether the field is required
}

PromptConfig defines a single prompt configuration

type PromptResult added in v0.11.0 

type PromptResult map[string]string

PromptResult contains the results of a prompt session

type Registry added in v0.10.0 

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

Registry holds a collection of runnables.

func NewRegistry added in v0.10.0 

func NewRegistry() *Registry

NewRegistry creates a new registry.

func (*Registry) FindByID added in v0.12.0 

func (r *Registry) FindByID(id string) (RunnableInterface, bool)

FindByID retrieves a runnable by ID.

func (*Registry) GetIDs added in v0.12.0 

func (r *Registry) GetIDs() []string

GetIDs returns all registered runnable IDs.

func (*Registry) List added in v0.12.0 

func (r *Registry) List() []RunnableInterface

List returns all registered runnables.

func (*Registry) Set added in v0.21.0 

func (r *Registry) Set(runnable RunnableInterface) error

func (*Registry) SetAll added in v0.21.0 

func (r *Registry) SetAll(runnables []RunnableInterface) error

SetAll adds multiple runnables to the registry at once. Returns an error if any runnable is nil or if setting any runnable fails.

type Result 

type Result struct {
	// Changed indicates whether the playbook made any changes to the system.
	// false means the system was already in the desired state.
	// true means the playbook modified the system.
	Changed bool

	// Message is a human-readable description of what happened.
	Message string

	// Details contains additional information about the execution.
	// Keys are field names, values are string representations.
	Details map[string]string

	// Error is non-nil if the playbook failed to execute.
	// When Error is non-nil, Changed may be true if some changes occurred before the failure.
	Error error
}

Result represents the outcome of a playbook execution. It indicates whether any changes were made and provides details about the execution.

type Results 

type Results struct {
	Results map[string]Result
}

Results contains per-node results from any operation.

func (Results) FirstResult added in v0.15.0 

func (r Results) FirstResult() Result

FirstResult returns the first result from the results map. Useful when running on a single node. Returns zero Result if no results.

func (Results) Summary 

func (r Results) Summary() Summary

Summary returns aggregated statistics.

type RunnableInterface added in v0.11.0 

type RunnableInterface interface {
	// BecomeInterface provides privilege escalation capabilities.
	BecomeInterface
	// GetID returns the unique identifier for this skill (e.g., "apt-update")
	GetID() string

	// SetID sets the unique identifier for this skill.
	SetID(id string) RunnableInterface

	// GetDescription returns a short description of what the skill does
	GetDescription() string

	// SetDescription sets a short description of what the skill does.
	SetDescription(description string) RunnableInterface

	// GetNodeConfig returns the current node configuration for this skill.
	GetNodeConfig() NodeConfig

	// SetNodeConfig sets the node configuration for this skill execution.
	// Returns the RunnableInterface for fluent method chaining.
	SetNodeConfig(cfg NodeConfig) RunnableInterface

	// GetArg retrieves a single argument value by key.
	GetArg(key string) string

	// SetArg sets a single argument value.
	// Returns the RunnableInterface for fluent method chaining.
	SetArg(key, value string) RunnableInterface

	// GetArgs returns the entire arguments map.
	GetArgs() map[string]string

	// SetArgs replaces the entire arguments map.
	// Returns the RunnableInterface for fluent method chaining.
	SetArgs(args map[string]string) RunnableInterface

	// IsDryRun returns true if this is a dry-run execution.
	IsDryRun() bool

	// SetDryRun sets whether to simulate execution without making changes.
	// Returns the RunnableInterface for fluent method chaining.
	SetDryRun(dryRun bool) RunnableInterface

	// GetTimeout returns the maximum duration for skill execution.
	GetTimeout() time.Duration

	// SetTimeout sets the maximum duration for skill execution.
	// Returns the RunnableInterface for fluent method chaining.
	SetTimeout(timeout time.Duration) RunnableInterface

	// Check determines if the skill needs to make any changes.
	// Uses the config and options set via SetConfig/SetOptions.
	// Returns true if changes are needed, false if the system is already in the desired state.
	// Returns an error if the check itself fails.
	Check() (bool, error)

	// Run executes the skill and returns a detailed result.
	// Uses the config and options set via SetConfig/SetOptions.
	// The Result.Changed field indicates whether any changes were made.
	Run() Result
}

RunnableInterface defines anything that can be executed on a remote server. Both commands and skills implement this interface, allowing a single Run() method to handle any executable operation.

Usage: 

skill := skills.NewUserCreate().
    SetNodeConfig(cfg).
    SetOptions(&types.RunnableOptions{Args: map[string]string{"username": "alice"}})

needsRun, _ := skill.Check()
result := skill.Run()

type RunnableOptions added in v0.11.0 

type RunnableOptions struct {
	// Args contains runnable-specific variables that override node-level arguments.
	// These are merged with node-level args (runnable args take precedence).
	Args map[string]string

	// DryRun indicates whether to simulate execution without making changes.
	// When true, the runnable should preview what would be done.
	DryRun bool

	// Timeout specifies the maximum duration for runnable execution.
	// Zero means no timeout.
	Timeout time.Duration
}

RunnableOptions provides configuration options for runnable execution. This allows per-runnable variable scoping and additional execution controls.

type RunnerInterface added in v0.11.0 

type RunnerInterface interface {
	// RunCommand executes a shell command and returns the output.
	// For Inventory, runs concurrently across all nodes.
	RunCommand(cmd string) Results

	// Run executes any runnable (command or skill).
	// For Inventory, runs concurrently across all nodes.
	Run(runnable RunnableInterface) Results

	// RunByID executes a skill by ID from the registry.
	// Deprecated: Use Run() instead.
	RunByID(id string, opts ...RunnableOptions) Results

	// Check runs the runnable's check mode to determine if changes would be made.
	// Sets Changed=true on result if changes are needed.
	Check(runnable RunnableInterface) Results

	// GetLogger returns the logger. Returns slog.Default() if not set.
	GetLogger() *slog.Logger

	// SetLogger sets a custom logger. Returns self for chaining.
	SetLogger(logger *slog.Logger) RunnerInterface

	// SetDryRunMode sets whether to simulate execution without making changes.
	// When true, ssh.Run() will log commands and return "[dry-run]" marker instead of executing.
	// Returns self for chaining.
	SetDryRunMode(dryRun bool) RunnerInterface

	// GetDryRunMode returns true if dry-run mode is enabled.
	// When true, commands are logged but not executed on the server.
	GetDryRunMode() bool
}

RunnerInterface defines operations that can be performed on either a single Node or an Inventory of nodes.

type Summary 

type Summary struct {
	Total     int
	Changed   int
	Unchanged int
	Failed    int
}

Summary holds aggregated result statistics.

Source Files

View all Source files

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.