go-sdk

module
v2.0.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 1, 2019 License: MIT

README

go-sdk

Build Status GoDoc

go-sdk is our core library of packages. These packages can be composed to create anything from CLIs to fully featured web apps.

The general philosophy is to provide loosely coupled libraries that can be composed as a suite of tools, vs. a do it all framework.

Addtional CLI Tools

We also provide the following CLI tools to help with development that leverage some of these packages:

  • cmd/ask : securely input secrets and output to a file to be read by templates.
  • cmd/cover : allows for project level coverage reporting and enforcement.
  • cmd/job : run a command on a cron schedule; useful for writing jobs as kubernetes pods.
  • cmd/profanity : profanity rules checking (i.e. fail on grep match).
  • cmd/recover : recover crashed processes (to be used when debugging panics).
  • cmd/semver : semver maniuplation and validation.
  • cmd/shamir : securely partition secrets using shamir's sharing scheme.
  • cmd/template : commandline template generation using golang text/template.

Repository Organization Notes

  • The repository is organized into composible packages. They are designed to be as loosely coupled as possible, but are all in a single repo to facilitate breaking change management.
  • Any commandline programs should live under cmd/** with the core library code in a top level package. The CLI should just be the bare minimum to run the library from the cli.

Code Style Notes

  • Where possible, follow the golang proverbs.
  • Where possible, make the zero value useful. If you do need to internalize a field, make sure it's accessible with an accessor in the form of the uppercase name of the field, i.e. field foo would have an accessor Foo().
  • Where possible, packages should export configuration objects that can be used to create the core types of that package. Those configuration objects should be readable from both JSON and YAML.
  • Anything that can return an error, should. Anything that needs to return a single value (but would return an error) should panic on that error and should be prefixed by Must....
  • Minimize dependencies between packages as much as possible; add external dependencies with extreme care.

Version Management

Generally we follow semantic versioning. What that means in practice:

[major].[minor].[patch]

We increment the major version if there are any breaking changes. A breaking change is defined as a change that would cause code written against the current major version having a build failure of any type. That's even for a trivial find and replace. Once you merge a new api or name for an object after CR, that's it.

We increment minor versions if we add new things that don't cause breaking changes.

We increment patch versions if we fix issues with the current set of objects.

The current version is stored in the VERSION file at the root of the package.

Version Release Cycle

We aim to target 6 month rollups of breaking changes as new major versions. Each major version is supported for two trailing major versions, i.e. v1.0 will be supported through v2.0 and v3.0 but will be unsupported once we cut v4.0.

To increment the local version

Patch:

make increment-patch

Minor:

make increment-minor

Major:

make increment-major

Directories

Path Synopsis
Package airbrake provides helpers for working with airbrake, such as sending exceptions and configuring the airbrake client.
 Package airbrake provides helpers for working with airbrake, such as sending exceptions and configuring the airbrake client.
Package assert adds helpers to make writing tests easier.
 Package assert adds helpers to make writing tests easier.
Package async provides syncronization primitives and background workers.
 Package async provides syncronization primitives and background workers.
aws
Package aws contains helpers for working with the aws api, namely configuration and session management.
 Package aws contains helpers for working with the aws api, namely configuration and session management.
ses
Package bitflag contains utilities for working with bit flags (or bit masks).
 Package bitflag contains utilities for working with bit flags (or bit masks).
Package certutil contains helpers for working with x509 formatted certificates.
 Package certutil contains helpers for working with x509 formatted certificates.
cmd
ask command
coverage command
job command
profanity command
proxy command
recover command
semver command
shamir command
template command
Package collections contains helper data structures.
 Package collections contains helper data structures.
Package configutil contains helpers for reading and setting up configuration.
 Package configutil contains helpers for reading and setting up configuration.
_examples/config command
Package cron is an implementation of a job scheduler to run within a worker or a server.
 Package cron is an implementation of a job scheduler to run within a worker or a server.
_examples/load_test command
_examples/timeouts command
Package crypto includes common cryptography helpers.
 Package crypto includes common cryptography helpers.
Package datadog includes helpers for interacting with datadog.
 Package datadog includes helpers for interacting with datadog.
db
Package db provides a basic abstraction layer above normal database/sql that makes it easier to interact with the database and organize database related code.
 Package db provides a basic abstraction layer above normal database/sql that makes it easier to interact with the database and organize database related code.
_examples/bench command
_examples/error command
migration
Package env contains environment variable helpers, enabling better tests and easier use of environment variables.
 Package env contains environment variable helpers, enabling better tests and easier use of environment variables.
Package exception adds the ability to wrap errors with stack traces, structured error classes and free form descriptive messages.
 Package exception adds the ability to wrap errors with stack traces, structured error classes and free form descriptive messages.
examples/full command
Package main implements a server for the Status service and implements a number of extra features like logging and recovery.
 Package main implements a server for the Status service and implements a number of extra features like logging and recovery.
examples/full/client command
examples/full/protos
jwt
test
Package logger is our high throughput event bus.
 Package logger is our high throughput event bus.
_examples/custom_event command
_examples/drain command
_examples/http command
_examples/json_logs command
Package names contains helpers for parsing names.
 Package names contains helpers for parsing names.
Package oauth implements some helper wrappers ontop of the existing google implementation of oauth.
 Package oauth implements some helper wrappers ontop of the existing google implementation of oauth.
Package proxy implements a simple reverse http proxy.
 Package proxy implements a simple reverse http proxy.
r2
Package r2 is a rewrite of the request package that eschews fluent apis in favor of the options pattern.
 Package r2 is a rewrite of the request package that eschews fluent apis in favor of the options pattern.
_examples/listener command
_examples/mtls command
_examples/request command
_examples/transport command
Package ref includes helpers for dealing with "optional" values represented by pointers.
 Package ref includes helpers for dealing with "optional" values represented by pointers.
Package reflectutil includes helpers for working with the golang reflection api.
 Package reflectutil includes helpers for working with the golang reflection api.
Package request implements helpers for net/http.Client.
 Package request implements helpers for net/http.Client.
_examples/mtls command
_examples/request command
_examples/transport command
Package secrets implements a high throughput vault client.
 Package secrets implements a high throughput vault client.
_examples/client command
_examples/config command
Package selector is a high performance selector parsing library, tightly coupled to the functionality of selectors found in Kubernetes.
 Package selector is a high performance selector parsing library, tightly coupled to the functionality of selectors found in Kubernetes.
_bench command
Package semver is a fork of Hashicorp's semver package.
 Package semver is a fork of Hashicorp's semver package.
sh
Package sh includes helpers for writing programs that fork or run other programs.
 Package sh includes helpers for writing programs that fork or run other programs.
_examples/password command
_examples/pipe command
_examples/prompt command
Package shamir includes an implementation of shamir's sharing scheme.
 Package shamir includes an implementation of shamir's sharing scheme.
Package slack includes helpers for sending slack webhooks.
 Package slack includes helpers for sending slack webhooks.
Package stats includes helpers for writing stats to collectors by adding listeners to logger instances.
 Package stats includes helpers for writing stats to collectors by adding listeners to logger instances.
tracing
Package tracing implements some helpers and constants for open tracing.
 Package tracing implements some helpers and constants for open tracing.
tracing/crontrace
Package crontrace contains tracer helpers for cron, our job management service.
 Package crontrace contains tracer helpers for cron, our job management service.
tracing/dbtrace
Package dbtrace contains db tracing helpers.
 Package dbtrace contains db tracing helpers.
tracing/r2trace
Package r2trace contains helpers for integrating open tracing into calls made with r2
 Package r2trace contains helpers for integrating open tracing into calls made with r2
tracing/requesttrace
tracing/webtrace
Package stringutil includes string utility functions and helpers.
 Package stringutil includes string utility functions and helpers.
Package template implements helpers on-top of the stdlib `text/template`.
 Package template implements helpers on-top of the stdlib `text/template`.
_examples/basic command
Package timeutil includes helpers for working with timestamps.
 Package timeutil includes helpers for working with timestamps.
Package uuid is a basic implementation of the version 4 spec of the univeral unique identifier.
 Package uuid is a basic implementation of the version 4 spec of the univeral unique identifier.
web
Package web implements a model view controller system for building http servers.
 Package web implements a model view controller system for building http servers.
_benchmark command
_benchmark/clean command
_benchmark/echo command
_examples/api command
_examples/auth command
_examples/basic command
_examples/healthz command
_examples/logging command
_examples/middleware command
_examples/no_content command
_examples/static command
_examples/timeout command
_examples/upgrades command
_examples/views command
Package webutil contains helpers for interacting with the standard library "net/http" package.
 Package webutil contains helpers for interacting with the standard library "net/http" package.
Package yaml is a golang port of `libyaml` by canonical.
 Package yaml is a golang port of `libyaml` by canonical.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.