puppet

Documentation

Overview

Package puppet is a pure-Go (no cgo) adapter that presents the Ruby Puppet API surface over the Puppet-language engine github.com/go-puppet/puppet.

The go-puppet engine already implements everything that is Puppet-language semantics: lexing and parsing a manifest, evaluating expressions, scoping, conditionals and iteration, class and defined-type instantiation, resource declaration and relationship chaining, and compiling the result into a catalog graph. It delegates the type system to github.com/go-pcore/pcore, data binding to github.com/go-hiera/hiera, and node facts to an injectable provider. This package does not reimplement any of that; it wraps the engine and adds the thin, Ruby-facing conveniences the engine deliberately omits so that a consumer such as go-embedded-ruby (rbgo) can expose a Ruby "Puppet" class:

• Parse, the surface behind a Ruby Puppet::Pops parse check, which reports a manifest's syntax error (or nil) without exposing the AST;
• Compile, which compiles a manifest into a catalog given a node's facts, name and optional Hiera configuration, returning the compiled catalog, the notice/warning/err log lines and any evaluation error;
• CompileHCL (and the CompileOptions Format field), which compiles a Terraform-style HCL2 manifest into the identical catalog by swapping only the parse step for the go-puppet hcl front-end and sharing the whole evaluate→catalog path with the native Puppet compile;
• Catalog and Resource, a Ruby-shaped view of the compiled catalog: resources addressed by their canonical `Type[Title]` reference, edges as flat source/target reference pairs, the catalog size, and the Puppet catalog JSON;
• CompileOptions, carrying the per-node compile context (facts, node name, Hiera configuration path and interpolation scope).

The package has no dependency on any Ruby runtime: the surface is Go-typed, and a Ruby binding layer marshals Ruby values onto these Go types. Being pure Go, it cross-compiles to and runs on every 64-bit Go target and links into a static binary by default.

Index

• func Compile(manifest string, opts CompileOptions) (*Catalog, []LogEntry, error)
• func CompileHCL(manifest string, opts CompileOptions) (*Catalog, []LogEntry, error)
• func Parse(manifest string) error
• type Catalog
  • func (c *Catalog) Edges() [][2]string
  • func (c *Catalog) JSON() string
  • func (c *Catalog) Resource(ref string) (*Resource, bool)
  • func (c *Catalog) Resources() []*Resource
  • func (c *Catalog) Size() int
• type CompileOptions
• type Format
• type LogEntry
• type Resource
  • func (r *Resource) Ref() string

Functions

func Compile

func Compile(manifest string, opts CompileOptions) (*Catalog, []LogEntry, error)

Compile compiles a manifest into a catalog for the node described by opts, returning the catalog, the emitted log lines, and any evaluation error.

It always wires the facts provider and node name. When opts.HieraConfig is set it loads a Hiera engine from that hiera.yaml — using opts.HieraScope, or a MapScope built from opts.Facts when the scope is nil — and wires it for data binding; a Hiera load error is returned before evaluation.

func CompileHCL

func CompileHCL(manifest string, opts CompileOptions) (*Catalog, []LogEntry, error)

CompileHCL compiles a Terraform-style HCL2 manifest into a catalog. It is a convenience wrapper that forces opts.Format to FormatHCL2 before delegating to Compile; the resulting catalog is identical to the one the twin Puppet source would produce.

func Parse

func Parse(manifest string) error

Parse parses a manifest and reports a syntax error, if any. It is the surface behind a Ruby Puppet::Pops parse check: it discards the resulting AST and returns only whether the manifest is syntactically valid.

Types

type Catalog

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

Catalog wraps a compiled go-puppet catalog with a Ruby-shaped surface.

func (*Catalog) Edges

func (c *Catalog) Edges() [][2]string

Edges returns the catalog's directed relationships as flat [source ref, target ref] pairs, in insertion order.

func (*Catalog) JSON

func (c *Catalog) JSON() string

JSON renders the catalog in the Puppet catalog JSON shape.

func (*Catalog) Resource

func (c *Catalog) Resource(ref string) (*Resource, bool)

Resource returns the resource for ref (`Type[Title]`) and whether it exists.

func (*Catalog) Resources

func (c *Catalog) Resources() []*Resource

Resources returns the compiled resources in declaration order.

func (*Catalog) Size

func (c *Catalog) Size() int

Size reports the number of resources in the catalog.

type CompileOptions

type CompileOptions struct {
	// Format is the surface syntax of the manifest (default FormatPuppet).
	Format Format
	// Facts are the node facts, also exposed to manifests via $facts and the
	// engine's FactsProvider.
	Facts map[string]any
	// NodeName is the compiling node's name (default "default").
	NodeName string
	// HieraConfig is an optional path to a hiera.yaml; when set, a Hiera engine
	// is loaded and wired for data binding and lookup().
	HieraConfig string
	// HieraScope is an optional scope for Hiera interpolation; when nil a
	// MapScope is derived from Facts.
	HieraScope gohiera.Scope
}

CompileOptions carries the node context for a compile.

type Format

type Format int

Format selects the surface syntax a manifest is written in. Both formats parse to the same ast.Program and evaluate through the identical engine, so they produce identical catalogs.

const (
	// FormatPuppet is native Puppet (.pp) source. It is the zero value, so a
	// CompileOptions with no Format set stays a Puppet compile.
	FormatPuppet Format = iota
	// FormatHCL2 is Terraform-style HCL2 source, translated to the same AST by
	// the go-puppet hcl front-end.
	FormatHCL2
)

type LogEntry

type LogEntry = eval.LogEntry

LogEntry re-exports the engine's notice/warning/err log line so a Ruby binding can surface Puppet log output without importing the engine directly.

type Resource

type Resource struct {
	Type       string
	Title      string
	Parameters map[string]any
	Tags       []string
}

Resource is one compiled catalog resource: a typed, titled bag of parameters together with its tags. It is the Ruby-shaped view of a go-puppet catalog resource.

func (*Resource) Ref

func (r *Resource) Ref() string

Ref returns the canonical Puppet reference `Type[Title]`.