yaml.go

// Package inventory provides loaders that build a legatus.Inventory from

// declarative sources. It is an opt-in battery: callers that prefer to

// construct an inventory programmatically can ignore it entirely.

package inventory

import (

	"io"

	"os"

	"gopkg.in/yaml.v3"

	"go.bigb.es/auxilia/culpa"

	"go.bigb.es/auxilia/legatus"

)

// yamlSchema is the on-disk shape of a YAML inventory.

//

//	hosts:

//	  - name: web1

//	    addr: 10.0.0.1

//	    port: 22

//	    user: deploy

//	    tags: [web, prod]

//	    groups: [frontend]

//	    vars: {role: nginx}

//	groups:            # optional: membership declared by host name

//	  frontend: [web1, web2]

//

// Group membership from both forms (inline host.groups and the named groups

// map) is merged onto each Host's Groups field, which legatus treats as a pure

// predicate via InGroup.

type yamlSchema struct {

	Hosts  []yamlHost          `yaml:"hosts"`

	Groups map[string][]string `yaml:"groups"`

}

type yamlHost struct {

	Name   string         `yaml:"name"`

	Addr   string         `yaml:"addr"`

	Port   int            `yaml:"port"`

	User   string         `yaml:"user"`

	Tags   []string       `yaml:"tags"`

	Groups []string       `yaml:"groups"`

	Vars   map[string]any `yaml:"vars"`

}

// LoadYAML parses a YAML inventory from r and returns the resulting Inventory.

//

// It raises (never silently drops) on malformed YAML, hosts without a name,

// duplicate host names, and groups that reference an unknown host.

func LoadYAML(r io.Reader) (*legatus.Inventory, error) {

	var schema yamlSchema

	dec := yaml.NewDecoder(r)

	dec.KnownFields(true)

	if err := dec.Decode(&schema); err != nil {

		return nil, culpa.WithCode(culpa.Wrap(err, "parse YAML inventory"), "INVENTORY_PARSE")

	}

	return build(&schema)

}

// LoadYAMLFile reads the file at path and parses it as a YAML inventory.

func LoadYAMLFile(path string) (*legatus.Inventory, error) {

	f, err := os.Open(path)

	if err != nil {

		return nil, culpa.WithCode(culpa.Wrapf(err, "open inventory file %q", path), "INVENTORY_READ")

	}

	defer f.Close()

	return LoadYAML(f)

}

func build(schema *yamlSchema) (*legatus.Inventory, error) {

	byName := make(map[string]*legatus.Host, len(schema.Hosts))

	hosts := make([]*legatus.Host, 0, len(schema.Hosts))

	for i := range schema.Hosts {

		yh := &schema.Hosts[i]

		if yh.Name == "" {

			return nil, culpa.WithCode(

				culpa.Errorf("host at index %d has no name", i), "INVENTORY_INVALID_HOST")

		}

		if _, dup := byName[yh.Name]; dup {

			return nil, culpa.WithCode(

				culpa.Errorf("duplicate host %q", yh.Name), "INVENTORY_DUPLICATE_HOST")

		}

		h := &legatus.Host{

			Name:   yh.Name,

			Addr:   yh.Addr,

			Port:   yh.Port,

			User:   yh.User,

			Tags:   yh.Tags,

			Groups: yh.Groups,

			Vars:   yh.Vars,

		}

		byName[h.Name] = h

		hosts = append(hosts, h)

	}

	if err := mergeGroups(schema.Groups, byName); err != nil {

		return nil, err

	}

	return legatus.NewInventory(hosts...), nil

}

// mergeGroups folds the named-groups map into each referenced host's Groups

// field, deduplicating against memberships already declared inline. A group

// referencing an unknown host is an error, not a silently skipped entry.

func mergeGroups(groups map[string][]string, byName map[string]*legatus.Host) error {

	for group, members := range groups {

		for _, name := range members {

			h, ok := byName[name]

			if !ok {

				return culpa.WithCode(

					culpa.Errorf("group %q references unknown host %q", group, name),

					"INVENTORY_UNKNOWN_HOST")

			}

			if !contains(h.Groups, group) {

				h.Groups = append(h.Groups, group)

			}

		}

	}

	return nil

}

func contains(haystack []string, needle string) bool {

	for _, s := range haystack {

		if s == needle {

			return true

		}

	}

	return false

}