modules

README

modules

Ansible module execution protocol plus the core module library.

Part of go-ansible — a pure-Go (CGO=0), functional-parity port of Ansible.

Usage

reg := modules.Default() // pre-populated with the built-in module set

res, err := reg.Run(ctx, "copy", conn, map[string]any{
    "src": "app.conf", "dest": "/etc/app.conf", "mode": "0644",
})
if res.Failed {
    // res.Msg explains why
}

conn is a github.com/go-remoteexec/transport.Connection (local or SSH). Unlike real Ansible, a module here runs its logic on the control node and reaches the target only through the connection's Exec/Put/Fetch primitives — no Python, no script copied to the target. reg.Names() lists every registered module name; reg.Register adds or overrides one.

Documentation

Overview

Package modules implements Ansible's module execution model: each module is a Go function that takes a target connection (github.com/go-remoteexec/transport) and a set of arguments (already Jinja2-rendered by the caller) and returns a Result — Ansible's changed/failed/msg triple plus any module-specific fields.

Unlike real Ansible, which copies a Python script to the target and runs it there, a module here runs its logic on the control node and reaches the target only through the Connection's Exec/Put/Fetch primitives. The observable behavior is the same (the target ends up in the same state); the difference is architectural, not behavioral, and it means a module needs no Go toolchain on the target.

Index

• Variables
• type Func
• type Registry
  • func Default() *Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Get(name string) (Func, bool)
  • func (r *Registry) Names() []string
  • func (r *Registry) Register(name string, fn Func)
  • func (r *Registry) Run(ctx context.Context, name string, conn remoteexec.Connection, ...) (Result, error)
• type Result
  • func Changed(msg string) Result
  • func Fail(msg string) Result
  • func Ok(msg string) Result
  • func (r Result) WithExtra(key string, value any) Result

Variables

var Docs = map[string]string{}/* 126 elements not displayed */

Docs maps every registered module name to its Go doc comment — the same argument/deviation documentation this project has always written on each module<Name> function, extracted once at build time so ansible-doc can print it without the source tree present.

Types

type Func

type Func func(ctx context.Context, conn remoteexec.Connection, args map[string]any) (Result, error)

Func is a module's entry point. ctx carries cancellation/timeout; conn is already connected to the task's target; args is the task's parameters, already Jinja2-rendered by the caller (this package never templates anything itself). A non-nil error means the module could not determine an outcome at all (a transport failure); an expected failure is a Result with Failed=true and a nil error.

type Registry

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

Registry maps module names to their Func.

func Default

func Default() *Registry

Default returns a Registry pre-populated with this package's built-in module set.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty Registry.

func (*Registry) Get

func (r *Registry) Get(name string) (Func, bool)

Get looks up a module by name.

func (*Registry) Names

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

Names returns every registered module name, sorted.

func (*Registry) Register

func (r *Registry) Register(name string, fn Func)

Register adds fn under name, replacing any existing module of the same name (so a caller can override a built-in with a custom module).

func (*Registry) Run

func (r *Registry) Run(ctx context.Context, name string, conn remoteexec.Connection, args map[string]any) (Result, error)

Run looks up name and runs it, returning a Result{Failed:true} (not a Go error) for an unknown module name — matching Ansible's own "couldn't resolve module" being a task failure, not a crash.

type Result

type Result struct {
	Changed bool
	Failed  bool
	Msg     string
	Facts   map[string]any
	Extra   map[string]any
}

Result is a module's outcome: Ansible's changed/failed/msg triple, plus optional facts (merged into ansible_facts, e.g. by set_fact) and module-specific extra fields (e.g. command's stdout/stderr/rc).

func Changed

func Changed(msg string) Result

Changed returns a successful, changed result.

func Fail

func Fail(msg string) Result

Fail returns a failed result. Modules normally return this alongside a non-nil error only when the failure is unexpected (a connection error, an unreadable file); an expected, well-formed failure (e.g. the `fail` module itself, or `assert` on a false condition) returns it with a nil error, since it is not the module's own execution that went wrong.

func Ok

func Ok(msg string) Result

Ok returns a successful, unchanged result.

func (Result) WithExtra

func (r Result) WithExtra(key string, value any) Result

WithExtra returns a copy of r with key set in Extra.