env

README

env package

Designed to provide simple and useful tooling to popoulate structs and provide managagement and sergices.

Sample program:

package main

import (
	"context"
	"sync"
	"time"

	"github.com/zxdev/env"
)

type Sample struct{}

func (s *Sample) Start(ctx context.Context, wg *sync.WaitGroup) {
	// bootstrap process
	wg.Done()    // bootstrap completed
	<-ctx.Done() // block signal
	// shutdown process
}

type params struct {
	Name  string `env:"require,order,environ" help:"a name to use"`
	Flag  bool   `name:"loop" default:"on" help:"a flag setting"`
	small int    // not parsed or reported by Summary
}

func main() {

	var param params
	env.NewEnv(&param)
	env.Summary(&param)

	sam := new(Sample)

	grace := env.NewGraceful()
	grace.Manager(sam)

	if param.Flag {

		// loop with timeout to signal shutdown
		for {
			select {
			case <-grace.Context().Done():
			case <-time.After(time.Minute):
			}
			grace.Stop()
		}

	} else {

		// wait for a ^C to terminate
		grace.Wait()

	}
}

The grace.Done() blocks until all the bootstraps placed under the grace.Manager(obj...) have completed. Call grace.Stop() to initiate a direct shutdown or with processes that are intended to run perpetually call grace.Wait() to block and wait for an os.Interrupt, syscall.SIGTERM, syscall.SIGHUP external signal. The program above demonstarates both use cases.

The Fork process provodes a daemon like control with start and stop keyword controls as a wrapper around an application.

Documentation

Index

• Variables
• func Dir(a ...string) string
• func Fork(cfg ...interface{})
• func NewGraceful() *graceful
• func Summary(cfg ...interface{})
• type Env
  • func NewEnv(cfg ...interface{}) *Env
• type Expire
  • func (ex *Expire) Add(age time.Duration, path ...string) *Expire
  • func (ex *Expire) Expire() *Expire
  • func (ex *Expire) Start(ctx context.Context)
• type Parser
  • func (p *Parser) Do(cfg ...interface{})
• type Persist
  • func (p Persist) Load(persist interface{}, age time.Duration) bool
  • func (p Persist) Save(persist interface{}) bool
• type PersistMap
  • func (m *PersistMap) Add(k string)
  • func (m *PersistMap) Next(age time.Duration) func() (key string, more bool)

Variables

var (
	Version, Build string
	Description    string
)

These var should be set externally by a build.sh

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 to be the last element when any of the following ._- characters are present

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 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 finish before the program terminates execution

func Summary

func Summary(cfg ...interface{})

Types

type Env

type Env struct {
	Etc, Srv, Var, Tmp string // paths
}

Env struct

func NewEnv

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

NewEnv is the *Env configurator that sets up the basic envrionment paths and calls the Parser to process the tag fields and populate the interface

name:"alternate" env:"require,order,environ" default:"value" help:"description"

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(age time.Duration, path ...string) *Expire

Add will register a directory/path with customized age timeframe

func (*Expire) Expire

func (ex *Expire) Expire() *Expire

Expire will run the registered expiration processes

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 Parser

type Parser struct {
	ConfPath  string
	EnvMirror bool
	// contains filtered or unexported fields
}

Parser struct

func (*Parser) Do

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

Do will set the speficied cfg values accoring to the tags present and will overload default values with {name}.conf file values, when a conf file is specified, followed by os.Args values, and finally overload with os.Environ values. When set EnvMirror sets all the final values in the key:value os.Environment table.

env: require,order,environ flags name: alternate name for parameter default: default (string, bool, int/64, uint/64 types are supported)

type Persist

type Persist string

Persist type

func (Persist) Load

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

Load persist object from disk or remove when older than stated age; ignores auto expiration when age is set to -1

func (Persist) Save

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

Save persist object to disk; accepts anything

type PersistMap

type PersistMap map[string]time.Time

PersistMap type

func (*PersistMap) Add

func (m *PersistMap) Add(k string)

Add entry

func (*PersistMap) Next

func (m *PersistMap) 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