README
¶
gobox
A collection of libraries that are useful for implementing Go services, libraries, and more.
Contributing
Please read the CONTRIBUTING.md document for guidelines on developing and contributing changes.
High-level Overview
Please see individual packages in the generated documentation for overviews on each.
Go idioms
Standard idioms
Please see Code review comments, go proverbs and Idiomatic Go.
Log errors with events.NewErrorInfo
When logging errors, use log.Debug(ctx, "some debug event", events.NewErrorInfo(err)) instead of using log.F{"error": err}. NewErrorInfo logs errors using outreach naming conventions and also takes care of logging stack traces.
Do not use context.WithValue
Context is often abused for thread local state. There are very few legitimate uses for this (tracing is one of those).
Do not use fmt.PrintXXX or the standard log package
Prefer the gobox log package. This logs data in structured format suitable for outreach go services.
Do not use non-literal messages with log
Do not use the following pattern:
message := fmt.Sprintf("working on org: %s", model.Org.ShortName)
log.Info(ctx, message, modelInfo)
The first arg of log.XXX calls should be a literal string so we can
quickly find out where a log message comes from. The rest of the args
can hold any structured data we want. The
events
package exposes a few common logging structures.
Use code generation for stringifying enums
See go generate:
For example, given this snippet,
package painkiller
//go:generate ./scripts/gobin.sh golang.org/x/tools/cmd/stringer@v0.1.0 -type=Pill
type Pill int
const (
Placebo Pill = iota
Aspirin
Ibuprofen
Paracetamol
Acetaminophen = Paracetamol
)
running go generate ./... from the root of the repo will create the
file pill_string.go, in package painkiller, containing a definition of
func (Pill) String() string which can be used to get the string
representation of the enum.
A suggested workflow is to run go generate ./... from the root of the repo before sending PRs out.
Use events.Org for logging org tenancy info.
Org information can be logged with standard naming conventions using:
orgInfo := events.Org{Bento: xyz, DatabaseHost: ...}
log.Debug(ctx, "doing xyz", orgInfo)
In most cases, though you probably have some other model struct which has this info. In those cases, the preferred route is to make those model types themselves loggable:
type Model struct {...}
func (m *Model) MarshalLog(addField func(key string, value interface{}) {
m.Org().MarshalLog(addField)
... add any custom fields you want: addField("myCustomField", m.CustomInfo)...
}
func (m *Model) Org() events.Org {
return events.Org{...}
}
Now Model can be used in logs like so:
var myModel m
log.Debug(ctx, "doing xyz", myModel)
Better still is to generate the MarshalLog function using struct tags
Documentation
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
call
Package call helps support tracking latency and other metrics for calls.
|
Package call helps support tracking latency and other metrics for calls. |
|
logf
Package logf has the log.F implementation
|
Package logf has the log.F implementation |
|
pkg
|
|
|
app
Package app has the static app info
|
Package app has the static app info |
|
async
Package async has helper utilities for running async code with proper tracing.
|
Package async has helper utilities for running async code with proper tracing. |
|
async/pool
Package pool implements an async pool
|
Package pool implements an async pool |
|
box
Package box implements the definitions of a box configuration file and tools to access it.
|
Package box implements the definitions of a box configuration file and tools to access it. |
|
caller
Package caller provides info on the caller
|
Package caller provides info on the caller |
|
callerinfo
Package callerinfo provides the GetCallerFunction to get the name of the module and function that has called you.
|
Package callerinfo provides the GetCallerFunction to get the name of the module and function that has called you. |
|
cfg
Package cfg manages config for outreach go services
|
Package cfg manages config for outreach go services |
|
cleanup
Package cleanup provides helpers to make it easy to do cleanups.
|
Package cleanup provides helpers to make it easy to do cleanups. |
|
cli
Description: This file contains cli functions used in bootstrap and eventually in stencil.
|
Description: This file contains cli functions used in bootstrap and eventually in stencil. |
|
cli/aws
Package aws contains helpers for working with AWS in CLIs
|
Package aws contains helpers for working with AWS in CLIs |
|
cli/github
Description: Implements consistent ways to get Auth across platforms.
|
Description: Implements consistent ways to get Auth across platforms. |
|
cli/updater
Description: Provides miscellaneous helpers for the updater
|
Description: Provides miscellaneous helpers for the updater |
|
cli/updater/archive
Package archive contains methods for extracting file(s) from arbitrary archive types.
|
Package archive contains methods for extracting file(s) from arbitrary archive types. |
|
cli/updater/release
Package release contains methods that interact with releases from VCS providers that do not exist natively in git.
|
Package release contains methods that interact with releases from VCS providers that do not exist natively in git. |
|
cli/updater/resolver
Package resolver contains a git tag aware version resolver that supports channels to determine the latest version.
|
Package resolver contains a git tag aware version resolver that supports channels to determine the latest version. |
|
codec
Package codec provides encoding/decoding utilities.
|
Package codec provides encoding/decoding utilities. |
|
differs
Description: Implements a custom Comperer that turns an a function into a Comparer
|
Description: Implements a custom Comperer that turns an a function into a Comparer |
|
env
Package env provides environment specific overrides
|
Package env provides environment specific overrides |
|
events
Package events defines the standard logging event structures
|
Package events defines the standard logging event structures |
|
exec
Package exec implements os/exec stdlib helpers
|
Package exec implements os/exec stdlib helpers |
|
log
Package log implements standard go logging
|
Package log implements standard go logging |
|
log/adapters
Package adapters integrates the logger with 3rd party loggers
|
Package adapters integrates the logger with 3rd party loggers |
|
log/internal/entries
Package entries provides an interface to work with Entries
|
Package entries provides an interface to work with Entries |
|
log/logtest
logtest provides the ability to test logs
|
logtest provides the ability to test logs |
|
metrics
Package metrics implements the outreach metrics API
|
Package metrics implements the outreach metrics API |
|
orerr
Package orerr implements outreach specific error utilities.
|
Package orerr implements outreach specific error utilities. |
|
orio
Description: Implements a buffered writer that writes the last N bytes written to it
|
Description: Implements a buffered writer that writes the last N bytes written to it |
|
queue
Package queue provides queue data structure.
|
Package queue provides queue data structure. |
|
region
Description: This file contains the read through cache implementation for this package.
|
Description: This file contains the read through cache implementation for this package. |
|
secrets
Package secrets manages secrets config for outreach applications
|
Package secrets manages secrets config for outreach applications |
|
shuffler
Package shuffler primarily provides the Suite struct that functions as a test runner and randomizer when embedded in your test struct.
|
Package shuffler primarily provides the Suite struct that functions as a test runner and randomizer when embedded in your test struct. |
|
sshconfig
Package sshconfig implements a small ssh config parser based on the output of `ssh -G`.
|
Package sshconfig implements a small ssh config parser based on the output of `ssh -G`. |
|
sshhelper
Package sshhelper is a toolkit for common ssh-related operations.
|
Package sshhelper is a toolkit for common ssh-related operations. |
|
statuscodes
Package statuscodes provides custom status types and helpers
|
Package statuscodes provides custom status types and helpers |
|
telefork
Description: Implements a telefork client
|
Description: Implements a telefork client |
|
tester
Package tester implements a test runner compatible with testing.T
|
Package tester implements a test runner compatible with testing.T |
|
trace
Package trace wraps standard tracing for outreach.
|
Package trace wraps standard tracing for outreach. |
|
ometrics
Module
|
|
|
tools
|
|
|
logger
main
|
main |