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.Fork - process fork manager

• env.Graceful - graceful interface startup/shutdown controller

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

• env.Persist - persist simple data to diks

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

See the example/main.gofor a sample use cases.

Documentation

Index

• Variables
• func Dir(a ...string) string
• func Fork(cfg ...interface{})
• func NewEnv(cfg ...interface{}) *paths
• func NewEnvSilent(cfg ...interface{}) *paths
• func NewGraceful() *graceful
• func Shutdown(ctx context.Context, exit bool)
• 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 Parser
  • func (p *Parser) Do(cfg ...interface{})
• 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 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 Fork

func Fork(cfg ...interface{})

Fork is an wrapper around NewEnv that enables a program to run normally or like a daemon with start|stop signals and control referencse are written to /var/fork/{name.pid} and should be left alone for proper Fork processing

func NewEnv

func NewEnv(cfg ...interface{}) *paths

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

type params struct {

	env:"alias,order,require,environ,hidden"
	help:"description"
	default:"value"

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

supports bool, string, int types

func NewEnvSilent

func NewEnvSilent(cfg ...interface{}) *paths

NewEnvSilent sets up a silent environment

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, exit bool)

Shutdown blocks on context.Context or signal.Notify; only use this when env.Graceful is not used; exit will call os.Exit(0)

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 Parser

type Parser struct {
	ConfPath *[]string
	SetENV   bool
	// contains filtered or unexported fields
}

func (*Parser) Do

func (p *Parser) Do(cfg ...interface{})

Do will set the speficied cfg struct field value according to the tag:env and tag:default provided in the struct, and will overload in the following order:

tag:default, conf k:v sets, os.Args, os.Environ

final values in the key:value os.Environment table.

env: alias,require,order,environ field flags
supports: string, bool, int/64, uint/64 types

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