types

Documentation

Overview

Package types provides shared types for ork packages.

Index

• type Command
• type PlaybookInterface
• type PlaybookOptions
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) GetPlaybookIDs() []string
  • func (r *Registry) PlaybookFindByID(id string) (PlaybookInterface, bool)
  • func (r *Registry) PlaybookList() []PlaybookInterface
  • func (r *Registry) PlaybookRegister(p PlaybookInterface) error
• type Result
• type Results
  • func (r Results) Summary() Summary
• type Summary

Types

type Command

type Command struct {
	Command     string
	Description string
}

Command represents a shell command with its description.

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"

Usage:

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

type PlaybookInterface

type PlaybookInterface interface {
	// GetID returns the unique identifier for this playbook (e.g., "apt-update")
	GetID() string

	// SetID sets the unique identifier for this playbook.
	SetID(id string) PlaybookInterface

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

	// SetDescription sets a short description of what the playbook does.
	SetDescription(description string) PlaybookInterface

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

	// SetNodeConfig sets the node configuration for this playbook execution.
	// Returns the PlaybookInterface for fluent method chaining.
	SetNodeConfig(cfg config.NodeConfig) PlaybookInterface

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

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

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

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

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

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

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

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

	// Check determines if the playbook 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 playbook 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
}

PlaybookInterface is the interface that all playbooks must implement. A playbook is a self-contained automation task that runs on a remote server. All playbooks support idempotency through the Check() method and Result return value.

Usage:

pb := playbooks.NewUserCreate().
    SetNodeConfig(cfg).
    SetOptions(&types.PlaybookOptions{Args: map[string]string{"username": "alice"}})

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

type PlaybookOptions

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

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

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

PlaybookOptions provides configuration options for playbook execution. This allows per-playbook variable scoping and additional execution controls.

type Registry

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

Registry holds a collection of playbooks.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates a new playbook registry.

func (*Registry) GetPlaybookIDs

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

GetPlaybookIDs returns all registered playbook IDs.

func (*Registry) PlaybookFindByID

func (r *Registry) PlaybookFindByID(id string) (PlaybookInterface, bool)

PlaybookFindByID retrieves a playbook by ID.

func (*Registry) PlaybookList

func (r *Registry) PlaybookList() []PlaybookInterface

PlaybookList returns all registered playbooks.

func (*Registry) PlaybookRegister

func (r *Registry) PlaybookRegister(p PlaybookInterface) error

PlaybookRegister adds a playbook to the registry. Returns an error if the playbook is nil or if a playbook with the same ID already exists.

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) Summary

func (r Results) Summary() Summary

Summary returns aggregated statistics.

type Summary

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

Summary holds aggregated result statistics.