env

README

env package

Designed to provide simple and useful tooling to popoulate simple structs and provide managagement and helpful services utilizing struct tags instead of package like flag or third-party solutions.

type params struct {
	Action    string `env:"A,require,order" help:"a name to use"`
	Secret    string `env:"hidden" help:"a secret"`
	Flag      bool   `default:"on"  help:"a flag setting"`
	Number    int    `default:"5" help:"a number"`
	timestamp int64  // not parsed or reported in Summary
}

func main() {
	var param params
	paths := env.NewEnv(&param)
}

Set struct params and populate by calling env.NewEnv(&param) to parse and populate the struct as shown.

• Any default value is overloaded by system environment that is in turn overloaded by any command line values.

Supported types in env.Parser are limited to string, bool, and int.

• Bool understands and accepts: on, yes, ok, true, and 1 and their associated negative counter parts.
• Everything you want can be derived from these three basic types, including arrays and maps that utilize your own encoding and decoding.
  • Array can be passed or set as one,two,three and split by on comman, simarly a map can be encode as k1:v1,k1:v2 and decoded by splitting on comma and then each set split on the colon.

---

Struct tag element supported and descriptions.

• env: alias,order,require,environ,hidden

  • alias support can be short form of the switch -A instead of -action
  • order makes it switchless and populated based on os.Args location index
  • require will cause hard stop when not defaulted or provided
  • environ sets all struct elements in the system envronment
  • hidden redacts the struct value in the summary report

• default: string, bool, int values

• help: description

Automatic -help support reports basic information, the struct field name, the alias is any, the env:tag in use, any default value and the help description.

 % go run example/main.go -help

 development
--------------------
 version 
 build   

 action         A     [or  ] default:           an action to do
 secret               [   *] default:           a secret
 flag                 [    ] default:on         a flag setting
 number               [    ] default:5          a number

A summary log reports the struct values and integrates with other env system. If more than one param is populated by env.NewENV(&param,&server), each will appear as seperate sets in the order provided in the log summary output.

% go run example/main.go run   
2024/07/10 21:19:54 |----------------------------------------|
2024/07/10 21:19:54 | MAIN ::::::::::::::::::::::: event log |
2024/07/10 21:19:54 |-----//o--------------------------------|
2024/07/10 21:19:54                                 version
2024/07/10 21:19:54                                 build
2024/07/10 21:19:54                             pid 65812
2024/07/10 21:19:54 |-----//o--------------------------------|
2024/07/10 21:19:54  action         | run
2024/07/10 21:19:54  secret         | <hidden>
2024/07/10 21:19:54  flag           | true
2024/07/10 21:19:54  number         | 5
2024/07/10 21:19:54 |----------------------------------------|
2024/07/10 21:19:54 _dev/srv
2024/07/10 21:19:54 sample: start
2024/07/10 21:19:55 main: bootstrap complete
2024/07/10 21:19:58 main: interrupt shutdown
2024/07/10 21:19:58 sample: stop
2024/07/10 21:19:58 main: shutdown initiated
2024/07/10 21:19:58 |----------------------------------------|
2024/07/10 21:19:58 main: bye
2024/07/10 21:19:58 |----------------------------------------|

• env.NewEnv - parse and populate a param struct

• env.Parser - parser used with NewEnv methods

• env.Dir - ensure a directory exists

• env.Expire - expiration file manager with graceful interface support

• env.Graceful - graceful interface startup/shutdown controller

• env.Lock - process file lock (simple in use detection)

• env.Persist - persist and resume with data on disk

• env.Shutdown - shutdown, not necessary with graceful controller

Documentation

Index

• Variables
• func Configure(cfg ...interface{}) (path struct{ ... })
• func Dir(a ...string) string
• func NewEnv(cfg ...interface{}) (path struct{ ... })
• func NewGraceful() *graceful
• func Shutdown(ctx context.Context, onInterrupt func())
• type Expire
  • func (ex *Expire) Add(ttl *time.Duration, path ...string) *Expire
  • func (ex *Expire) Expire() *Expire
  • func (ex *Expire) Silent() *Expire
  • func (ex *Expire) Start(ctx context.Context)
• type Lock
  • func (lock *Lock) Exist(ttl *time.Duration) bool
  • func (lock Lock) Lock() bool
  • func (lock Lock) Unlock() bool
• type Map
  • func NewMap() *Map
  • func (m *Map) Add(k string)
  • func (m *Map) Next(age time.Duration) func() (key string, more bool)
• type Options
• type Persist
  • func (p Persist) Load(persist interface{}, ttl *time.Duration) bool
  • func (p Persist) Save(persist interface{}) bool

Variables

var (
	Version, Build string
	Description    string
)

These var should be set externally by the build command

Functions

func Configure

func Configure(cfg ...interface{}) (path struct {
	Etc, Srv, Var, Tmp string
})

Configure sets up the basic environment and returns environment paths; pass Options as the first item to set or specify custom configuration options to silence log and help output and env.Options.M map populates, struct initially, overloaded by environment vars, overloaded by default tag, that is then overloaded by command line swithches, in this order

func Dir

func Dir(a ...string) string

Dir will create the directory tree when it does not exist and return a string representation of the full composite path. A file is presumed when the last element contains any of the following ._- characters and fs.FileMode is coded to 0755

func NewEnv

func NewEnv(cfg ...interface{}) (path struct {
	Etc, Srv, Var, Tmp string
})

NewEnv that sets up the basic envrionment paths and calls the Parser to process the struct tag fields and populates any interfaces that are provided

tags
	env:"alias,order,require,environ,hidden"
	help:"description"
	default:"value" (bool, string, int)

Action string `env:"A,require" default:"server" help:"action [server|client]"`

func NewGraceful

func NewGraceful() *graceful

NewGraceful configurator returns *graceful and starts the shutdown controller to capture (os.Interrupt, syscall.SIGTERM, syscall.SIGHUP) signals and waits on the <-graceful.context.Done() for a signal and waits for the graceful.Manager controller wgShutdown to confirm all managed processes and completed tasks before the program terminates execution

func Shutdown

func Shutdown(ctx context.Context, onInterrupt func())

Shutdown blocks on context.Context or signal.Notify; only use this when env.Graceful is not used; onInterrupt is func that will execute when an interrupt if received, when nil just exits

Types

type Expire

type Expire struct {
	CheckOn time.Duration // frequency of checks (default: hourly)
	// contains filtered or unexported fields
}

Expire struct

func (*Expire) Add

func (ex *Expire) Add(ttl *time.Duration, path ...string) *Expire

Add will register a directory/path with customized age timeframe (default: 24hr expiration)

func (*Expire) Expire

func (ex *Expire) Expire() *Expire

Expire will run the registered expiration processes

func (*Expire) Silent

func (ex *Expire) Silent() *Expire

Silent flag toggle for env.Expire, writes logs on os.Stderr (default: on)

func (*Expire) Start

func (ex *Expire) Start(ctx context.Context)

Start expire service manger to check for expired files periodically based on expire.CheckOn setting (default: check hourly, expire after 24hr)

type Lock

type Lock string

Lock directory; default /tmp

func (*Lock) Exist

func (lock *Lock) Exist(ttl *time.Duration) bool

Exist reports the {file}.lock state as a boolean and expires the lock when past the ttl; default 1hr

func (Lock) Lock

func (lock Lock) Lock() bool

Lock creates a {file}.lock and writes the current pid

func (Lock) Unlock

func (lock Lock) Unlock() bool

Unlock removes a {file}.lock

type Map

type Map map[string]time.Time

Map of items with ttl

func NewMap

func NewMap() *Map

NewMap

func (*Map) Add

func (m *Map) Add(k string)

Add entry

func (*Map) Next

func (m *Map) Next(age time.Duration) func() (key string, more bool)

Next returns a function return the key; removes key when used or when older than age, when age is non-zero

type Options

type Options struct {
	Silent bool // silence log configuration output
	NoHelp bool // silence help output
	SetENV bool // set KEY=VALUE in environment
}

Options for env.Configure

Silent: log configuration output
NoHelp: silences the help output
SetENV: set KEY=VALUE in environemnt

type Persist

type Persist string

Persist type

func (Persist) Load

func (p Persist) Load(persist interface{}, ttl *time.Duration) bool

Load persist object from disk or remove when older than stated ttl; ignores auto expiration when ttl is nil or 0

func (Persist) Save

func (p Persist) Save(persist interface{}) bool

Save persist object to disk; accepts anything