proc

README

proc

Process control, logging and child processes

Description

Golang is a great language for concurrency, but sometimes you want parallelism, and it's often simpler to design apps as little units that plug together via RPC APIs. Services don't always have easy start/stop/reconfig/restart controls, and sometimes they use their own custom configuration scheme that is complicated to integrate with yours.

In addition, you may want to design your applications as neat little pieces, but how to attach them together and orchestrate them starting up and coming down cleanly, and not have to deal with several different ttys to get the logs.

Proc creates a simple framework for creating observable, controllable execution units out of your code, and more easily integrating the code of others.

This project is the merge of several libraries for logging, spawning and controlling child processes, and creating an RPC to child processes that controls the run of the child process. Due to the confusing duplication of signals as a means of control and the lack of uniformity in signals (ie windows) the goal of proc is to create one way to do, following the principles of design used for Go itself.

Badges

<insert badges here

Installation

For developers:

To make nice tagged versions with the version number in the commit as well as matching to the tag, there is a tool called bumper that bumps the version to the next patch version (vX.X.PATCH), embeds this new version number into version.go with the matching corresponding git commit hash. This will make importing this library at an exact commit much more human.

In addition, it makes it easy to make a nice multi line commit message as many repositories request in their CONTRIBUTION file by replacing -- with two carriage returns.

To install:

go install ./bumper/.

To use:

bumper make a commit comment here -- text after double \
    hyphen will be separated by a carriage return -- \
    anywhere in the text

Usage

reasonably include in the README.

Support

Roadmap

• Implement basic logger
• Create concurrent safe configuration CLI/env/config system

Contributing

Authors and acknowledgment

David Vennik david@cybriq.systems

License

Unlicenced: see here

Project status

In the process of revision and merging together several related libraries that need to be unified.

Documentation

Index

• Variables
• func Add(pathBase string) (subsystem string)
• func GetLoc(skip int, subsystem string) (output string)
• func Item(m *metadata) (t types.Item)
• func List(items ...string) []string
• func New(args Desc) *metadata
• func NewBool(m *metadata) (b *_bool)
• func NewDuration(m *metadata) (b *_dur)
• func NewFloat(m *metadata) (b *_flt)
• func NewInt(m *metadata) (b *_int)
• func NewList(m *metadata) (b *_lst)
• func NewString(m *metadata) (b *_str)
• func NewUint(m *metadata) (b *_uin)
• func SetLogLevel(l LogLevel)
• func SetTimeStampFormat(format string)
• func Version() string
• type Chk
• type Configs
  • func Create(items ...Desc) (c Configs)
  • func (c *Configs) Get(name string) (t types.Item, err error)
  • func (c *Configs) MarshalJSON() ([]byte, error)
  • func (c *Configs) UnmarshalJSON(bytes []byte) error
• type Desc
• type LevelPrinter
• type LevelSpec
• type LogLevel
• type Logger
  • func GetLogger(pathBase string) (l *Logger)
• type Printc
• type Printf
• type Println
• type Prints

Variables

var (

	// App is the name of the application
	App = "  main"
	// AllSubsystems stores all of the package subsystem names found in the current
	// application
	AllSubsystems []string
)

var (
	// URL is the git URL for the repository
	URL = "gitlab.com/cybriqsystems/proc"
	// GitRef is the gitref, as in refs/heads/branchname
	GitRef = "refs/heads/master"
	// GitCommit is the commit hash of the current HEAD
	GitCommit = "e98186012bb0c4279fb5768e73d6c5685bd31e3a"
	// BuildTime stores the time when the current binary was built
	BuildTime = "2022-08-01T07:21:06+02:00"
	// SemVer lists the (latest) git tag on the build
	SemVer = "v0.0.28"
	// PathBase is the path base returned from runtime caller
	PathBase = "/home/davidvennik/src/gitlab.com/cybriqsystems/proc/"
	// Major is the major number from the tag
	Major = 0
	// Minor is the minor number from the tag
	Minor = 0
	// Patch is the patch version number from the tag
	Patch = 28
)

var LevelSpecs = map[LogLevel]LevelSpec{
	Off:   gLS(Off, 0, 0, 0),
	Fatal: gLS(Fatal, 255, 0, 0),
	Error: gLS(Error, 255, 128, 0),
	Check: gLS(Check, 255, 255, 0),
	Warn:  gLS(Warn, 255, 255, 0),
	Info:  gLS(Info, 0, 255, 0),
	Debug: gLS(Debug, 0, 128, 255),
	Trace: gLS(Trace, 128, 0, 255),
}

LevelSpecs specifies the id, string name and color-printing function

var LvlStr = map[LogLevel]string{
	Off:   "off  ",
	Fatal: "fatal",
	Error: "error",
	Warn:  "warn ",
	Info:  "info ",
	Check: "check",
	Debug: "debug",
	Trace: "trace",
}

Functions

func Add

func Add(pathBase string) (subsystem string)

Add adds a subsystem to the list of known subsystems and returns the string so it is nice and neat in the package logg.go file

func GetLoc

func GetLoc(skip int, subsystem string) (output string)

GetLoc calls runtime.Caller and formats as expected by source code editors for terminal hyperlinks

Regular expressions and the substitution texts to make these clickable in Tilix and other RE hyperlink configurable terminal emulators:

This matches the shortened paths generated in this command and printed at the very beginning of the line as this logger prints:

^((([\/a-zA-Z@0-9-_.]+/)+([a-zA-Z@0-9-_.]+)):([0-9]+))
/usr/local/bin/goland --line $5 $GOPATH/src/github.com/p9c/matrjoska/$2

I have used a shell variable there but tilix doesn't expand them, so put your GOPATH in manually, and obviously change the repo subpath.

func Item

func Item(m *metadata) (t types.Item)

func List

func List(items ...string) []string

List is a more compact way of declaring a []string

func New

func New(args Desc) *metadata

New allows you to create a metadata with a sparsely filled, named field struct literal.

name, type, group and tags all will be canonicalized to lower case.

func NewBool

func NewBool(m *metadata) (b *_bool)

func NewDuration

func NewDuration(m *metadata) (b *_dur)

func NewFloat

func NewFloat(m *metadata) (b *_flt)

func NewInt

func NewInt(m *metadata) (b *_int)

func NewList

func NewList(m *metadata) (b *_lst)

func NewString

func NewString(m *metadata) (b *_str)

func NewUint

func NewUint(m *metadata) (b *_uin)

func SetLogLevel

func SetLogLevel(l LogLevel)

func SetTimeStampFormat

func SetTimeStampFormat(format string)

func Version

func Version() string

Version returns a pretty printed version information string

Types

type Chk

type Chk func(e error) bool

Chk is a shortcut for printing if there is an error, or returning true

type Configs

type Configs struct {
	sync.Mutex
	// contains filtered or unexported fields
}

func Create

func Create(items ...Desc) (c Configs)

func (*Configs) Get

func (c *Configs) Get(name string) (t types.Item, err error)

func (*Configs) MarshalJSON

func (c *Configs) MarshalJSON() ([]byte, error)

func (*Configs) UnmarshalJSON

func (c *Configs) UnmarshalJSON(bytes []byte) error

type Desc

type Desc struct {
	Name, Group, Description, Documentation, Default string
	Type                                             types.Type
	Tags, Aliases                                    []string
}

Desc is the named field form of metadata for generating a metadata

type LevelPrinter

type LevelPrinter struct {
	Ln Println
	// F prints like fmt.Println surrounded by log details
	F Printf
	// S uses spew.dump to show the content of a variable
	S Prints
	// C accepts a function so that the extra computation can be avoided if
	// it is not being viewed
	C Printc
	// Chk is a shortcut for printing if there is an error, or returning
	// true
	Chk Chk
}

LevelPrinter defines a set of terminal printing primitives that output with extra data, time, level, and code location

type LevelSpec

type LevelSpec struct {
	Name      string
	Colorizer func(format string, a ...interface{}) string
}

type LogLevel

type LogLevel int32

const (
	Off LogLevel = iota
	Fatal
	Error
	Check
	Warn
	Info
	Debug
	Trace
)

type Logger

type Logger struct {
	F, E, W, I, D, T LevelPrinter
}

func GetLogger

func GetLogger(pathBase string) (l *Logger)

GetLogger returns a set of LevelPrinter with their subsystem preloaded

type Printc

type Printc func(closure func() string)

Printc accepts a function so that the extra computation can be avoided if it is not being viewed

type Printf

type Printf func(format string, a ...interface{})

Printf prints like fmt.Println surrounded by log details

type Println

type Println func(a ...interface{})

Println prints lists of interfaces with spaces in between

type Prints

type Prints func(a ...interface{})

Prints prints a spew.Sdump for an interface slice