florist

Documentation

Overview

Package florist helps to create non-idempotent, one-file-contains-everything installers/provisioners.

Index

• Constants
• func CacheValidity() time.Duration
• func Chown(fpath string, username string) error
• func CmdRun(log *slog.Logger, cmd *exec.Cmd) error
• func CopyFile(srcPath string, dstPath string, mode os.FileMode, owner string) error
• func CopyFileFs(srcFs fs.FS, srcPath string, dstPath string, mode os.FileMode, owner string) error
• func GroupSystemAdd(groupname string) error
• func JoinErrors(errs ...error) error
• func ListFs(fsys fs.FS) []string
• func ListeningSockets() (*sets.Set[string], error)
• func Log() *slog.Logger
• func LowLevelInit(logOutput io.Writer, logLevel string, cacheValidity time.Duration) error
• func MainErr(opts *Options) error
• func MainInt(opts *Options) int
• func MakeTmplData(secrets fs.FS, keys ...string) (map[string]string, error)
• func NetFetch(client *http.Client, url string, hashType Hash, hash string, dstDir string) (string, error)
• func PrivateIPs() ([]string, error)
• func PublicIPs() ([]string, error)
• func SkipIfNotDisposableHost(t *testing.T)
• func SupplementaryGroups(username string, groups ...string) error
• func TemplateFromFs(srcFs fs.FS, srcPath string, tmplData any) (string, error)
• func TemplateFromFsWithDelims(srcFs fs.FS, srcPath string, tmplData any) (string, error)
• func TemplateFromText(tmplText string, tmplData any, tmplName string) (string, error)
• func UnzipOne(zipPath string, name string, dstPath string) error
• func User() *user.User
• func UserAdd(username string) error
• func UserSystemAdd(username string, homedir string) error
• func WriteFile(fname string, data string, mode os.FileMode, owner string) error
• type Config
  • func NewConfig(settingsPaths []string) (*Config, error)
  • func (cfg *Config) Errors() error
  • func (cfg *Config) Get(k string) string
  • func (cfg *Config) Lookup(k string) (string, error)
• type ConfigureFn
• type Configurer
• type Flower
• type Hash
• type Installer
• type Options
• type Provisioner
  • func (prov *Provisioner) AddFlowers(flowers ...Flower) error
  • func (prov *Provisioner) Flowers() map[string]Flower
  • func (prov *Provisioner) UseWorkdir()

Constants

const (
	WorkDir = "/tmp/florist.work"
)

Functions

func CacheValidity

func CacheValidity() time.Duration

func Chown

func Chown(fpath string, username string) error

Chown sets the owner of fpath to username.

func CmdRun

func CmdRun(log *slog.Logger, cmd *exec.Cmd) error

func CopyFile

func CopyFile(
	srcPath string, dstPath string,
	mode os.FileMode, owner string,
) error

CopyFile copies file srcPath to dstPath, with mode and owner. The source and destination files reside in the "real" filesystem. Notes: - If dstPath exists, it will be overwritten. - Setting an owner different that the current user requires elevated privileges.

func CopyFileFs

func CopyFileFs(
	srcFs fs.FS, srcPath string, dstPath string,
	mode os.FileMode, owner string,
) error

CopyFileFs copies file srcPath to dstPath, with mode and owner. The source file resides in the srcFs filesystem (for example, via go:embed), while the destination file resides in the "real" filesystem. Notes: - If dstPath exists, it will be overwritten. - Setting an owner different that the current user requires elevated privileges.

func GroupSystemAdd

func GroupSystemAdd(groupname string) error

func JoinErrors

func JoinErrors(errs ...error) error

Return an error containing the joined error messages of errs. If all elements of errs are nil, return nil. Does not preserve the error types nor provides Unwrap.

func ListFs

func ListFs(fsys fs.FS) []string

ListFs returns a list of the files (not directories) in fsys. In case of error, it encodes the error in a file name in the list.

func ListeningSockets

func ListeningSockets() (*sets.Set[string], error)

func Log

func Log() *slog.Logger

func LowLevelInit

func LowLevelInit(logOutput io.Writer, logLevel string, cacheValidity time.Duration) error

LowLevelInit should be called only by low-level test code. Absolutely do not call in non-test code! Call florist.MainInt instead!

func MainErr

func MainErr(opts *Options) error

MainErr is a ready-made function for the main() of your installer.

func MainInt

func MainInt(opts *Options) int

MainInt is a ready-made function for the main() of your installer.

Usage:

func main() {
	os.Exit(florist.MainInt(&florist.Options{
		SetupFn:     setup,
		ConfigureFn: configure,
	}))
}

func MakeTmplData

func MakeTmplData(secrets fs.FS, keys ...string) (map[string]string, error)

MakeTmplData returns a map, where each key is a path in the secrets FS and each value is the contents of the corresponding path.

func NetFetch

func NetFetch(client *http.Client, url string, hashType Hash, hash string, dstDir string) (string, error)

NetFetch uses client to download url to dstDir, returning the path of the downloaded file. Directory dstDir must exist. If after the download the hash doesn't match, it will return an error. If the file in dstDir exists and the hash matches, it will not be redownloaded.

func PrivateIPs

func PrivateIPs() ([]string, error)

func PublicIPs

func PublicIPs() ([]string, error)

func SkipIfNotDisposableHost

func SkipIfNotDisposableHost(t *testing.T)

SkipIfNotDisposableHost skips the test if it is running on a precious host.

func SupplementaryGroups

func SupplementaryGroups(username string, groups ...string) error

if username is present, then add it to the supplementary groups

func TemplateFromFs

func TemplateFromFs(srcFs fs.FS, srcPath string, tmplData any) (string, error)

TemplateFromFs reads file srcPath in filesystem srcFs and renders its contents // as a template with data tmplData.

func TemplateFromFsWithDelims

func TemplateFromFsWithDelims(srcFs fs.FS, srcPath string, tmplData any) (string, error)

TemplateFromFsWithDelims reads file srcPath in filesystem srcFs and renders its contents as a template with data tmplData, with "<<", ">>" as template delimiters. This is useful to escape the default delimiters "{{", "}}" in the template.

func TemplateFromText

func TemplateFromText(tmplText string, tmplData any, tmplName string) (string, error)

TemplateFromText renders the template 'tmplText' with data 'tmplData'. Parameter 'tmplName' is used for debugging purposes, a typical example is the template file name.

func UnzipOne

func UnzipOne(zipPath string, name string, dstPath string) error

UnzipOne extracts file `name` from ZIP file `zipPath` and saves it to `dstPath`.

func User

func User() *user.User

User returns the current user, as set by Init.

func UserAdd

func UserAdd(username string) error

Add user and create home directory. Do nothing if user already present. Password login is disabled (use SSH public key or use passwd)

func UserSystemAdd

func UserSystemAdd(username string, homedir string) error

func WriteFile

func WriteFile(fname string, data string, mode os.FileMode, owner string) error

WriteFile writes data to fname and sets the mode and owner of fname. If also creates any missing directories in the path, if any.

Types

type Config

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

func NewConfig

func NewConfig(settingsPaths []string) (*Config, error)

func (*Config) Errors

func (cfg *Config) Errors() error

func (*Config) Get

func (cfg *Config) Get(k string) string

Get returns the value of key k if found. If the key is missing, it returns the empty string and adds the error to the list returned by Errors. This allows a simple sequence of calling Get multiple times and checking for all the keys that were missing keys only once at the end, by calling Errors.

If on the other end you want to know immediately if the key is missing, use Lookup.

func (*Config) Lookup

func (cfg *Config) Lookup(k string) (string, error)

Lookup returns the value of key k if found. If the key is missing, it returns an error. Contrary to Get, it does not append a lookup failure to the errors returned by Errors.

type ConfigureFn

type ConfigureFn func(prov *Provisioner, config *Config) error

type Configurer

type Configurer interface {
	Configure() error
}

type Flower

type Flower interface {
	Installer
	Configurer
}

type Hash

type Hash int

const (
	SHA256 Hash = iota + 1
)

type Installer

type Installer interface {
	String() string
	Description() string
	Embedded() []string
	Init() error
	Install() error
}

type Options

type Options struct {
	// Output for the logger. Defaults to os.Stdout. Before changing to os.Stderr,
	// consider that HashiCorp Packer renders any output to stderr in red, thus
	// making everything look like an error.
	// The default log level is INFO; it can be changed to DEBUG via the --log-level
	// command-line flag.
	LogOutput io.Writer
	// Optimization to avoid refreshing the OS package manager cache each time before
	// installing an OS package. Defaults to 1h.
	OsPkgCacheValidity time.Duration
	// The setup function, called before any command-line subcommand. No default.
	SetupFn func(prov *Provisioner) error
	// The configure function, called before the command-line configure subcommand.
	// No default.
	ConfigureFn ConfigureFn
}

The Options passed to MainInt. For an example, see florist/example/main.go

type Provisioner

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

func (*Provisioner) AddFlowers

func (prov *Provisioner) AddFlowers(flowers ...Flower) error

func (*Provisioner) Flowers

func (prov *Provisioner) Flowers() map[string]Flower

Flowers returns

func (*Provisioner) UseWorkdir

func (prov *Provisioner) UseWorkdir()

FIXME what is this doing????