go-sdk

module
v1.20210103.1 Latest Latest
Warning

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

 Go to latest Published: Jan 3, 2021 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.

Requirements

This repository requires golang version 1.13+ to be installed.

To run tests, it is required that you have Docker installed, with docker-compose, or have postgres running locally.

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 manipulation 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.

Contributing

One (or more) of the core team members are required to review any PR (please make sure to tag them on the PR).

Blend employees (members of the Blend organization) feel free to use branches to create PRs.

Non-Blend employees feel free to fork the repo and open PRs with changes. Forked repos present some difficulty pre-go mod because of the path reference being changed (i.e. github.com/blend/go-sdk turns into github.com/<FORKING USER>/go-sdk), so it's recommended to check the fork out to $GOPATH/src/github.com/blend/go-sdk on disk to preserve the project paths.

Code Style Notes

The "Options" Pattern

  • The "Options" pattern is a variadic set of arguments as functions that mutate the returned object, typically in the constructor.
    • This lets callers add their own mutators to be used in constructors.
    • It also lets callers establish a set of "default" options that can be combined / overridden later.
    • It also reduces the amount of code required in the go-sdk repo itself.

Other General Notes

  • Where possible, follow the golang proverbs.
  • Make the zero value useful. Some situations require pointers, and are noted exceptions.
  • Export all fields unless strictly internal state and would never be set by calling code.
  • 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.
    • Notable exceptions include:
      • airbrake
      • sentry
      • lib/pq
      • aws sdk
      • datadog

Version Management

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

[major].[minor].[patch]

Major version changes are changes that break backwards-compatibility. 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. Major changes are rolled up into a release, at most, once-per-year.

Minor version changes are additions to exported types, values, or functions that don't cause break backwards compatibility. These types of changes are rolled into a new minor version at an approximate monthly cadence.

Patch versions are bugfixes and improvements made without changing the current set of exports. They can be cut at any time.

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

Currently we support 2 major version branches of the go-sdk.

  • v1.0 is scheduled for deprecation/end-of-support in Q4 2019
  • v2.0 is the current version and will be supported until at least May 2021

Another version v3.0 is in development as the master branch and will likely be released in late Q2/early Q3 2019.

Version Release Cycle

Our version release cycle has changed. Following v3.0's release later this year, we will not be releasing more than 1 major version in any calendar year, and major versions will recieve at least 2 years of support before being deprecated.

To increment the local version

Patch:

make increment-patch

Minor:

make increment-minor

Major:

make increment-major

Bugs and Feature Requests

Please use the issues page to report any bugs or request new features be added to the SDK. We welcome contributions to any issue reported therein, including those you report. Please ping us on the issue itself for things like access requests.

Maintainers

This repo is maintained by a core group of Blend employees.

This list includes (ordered alpha by username):

Directories

Path Synopsis
Package ansi contains helpers for working with ansi colors.
 Package ansi contains helpers for working with ansi colors.
slant
slant/_fontdata
Package assert is a suite of helpers and convenience methods for writing tests that wrap `*testing.T`.
 Package assert is a suite of helpers and convenience methods for writing tests that wrap `*testing.T`.
Package async provides syncronization primitives and background workers.
 Package async provides syncronization primitives and background workers.
Package bindata containers helpers for linking binary assets into programs.
 Package bindata containers helpers for linking binary assets into programs.
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 breaker provides a circuitbraker mechanism for dealing with flaky or unreliable counterparties.
 Package breaker provides a circuitbraker mechanism for dealing with flaky or unreliable counterparties.
Package bufferutil provides helpers for dealing with buffers.
 Package bufferutil provides helpers for dealing with buffers.
Package cache provides caching primitives for in-memory caches, including LRU eviction.
 Package cache provides caching primitives for in-memory caches, including LRU eviction.
Package certutil contains helpers for working with x509 certificates.
 Package certutil contains helpers for working with x509 certificates.
cmd
ask
bindata
coverage
profanity
recover
reverseproxy
semver
shamir
stats
template
traces
Package collections contains helper data structures.
 Package collections contains helper data structures.
Package configutil contains helpers for configuration.
 Package configutil contains helpers for configuration.
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.
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.
traceserver
Package traceserver is a mocked APM trace server that calls a handler for each spanlists payload it gets.
 Package traceserver is a mocked APM trace server that calls a handler for each spanlists payload it gets.
db
Package db provides a basic abstraction layer above normal database/sql.
 Package db provides a basic abstraction layer above normal database/sql.
dbutil
migration
Package migration provides helpers for writing rerunnable database migrations.
 Package migration provides helpers for writing rerunnable database migrations.
Package email includes helpers for sending SMTP messages.
 Package email includes helpers for sending SMTP messages.
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 ex provides the foundations for error handling in the SDK tree.
 Package ex provides the foundations for error handling in the SDK tree.
examples
ansi
async
breaker
cache
certutil/create_certs
certutil/notafter
certutil/selfsigned
configutil
cron/basic
cron/immediate
cron/load_test
cron/timeouts
db/bench
db/error
db/migration/custom
db/migration/timeouts
db/multiple
db/prevent-deadlock
db/statement-timeout
email/smtp
fileutil
logger/basic
logger/custom_event
logger/drain
logger/json_logs
logger/meta
logger/scope
r2/logged
r2/mtls
r2/request
r2/transport
reverseproxy
sh/password
sh/pipe
sh/prompt
template/basic
validate
vault/client
vault/config
web/api
web/auth
web/basic
web/gzip_middleware
web/logging
web/middleware
web/no_content
web/static
web/timeout
web/tracing
web/views
webutil/httplogged
Package fileutil provides helpers for reading and writing files.
 Package fileutil provides helpers for reading and writing files.
Package graceful provides a mechanism to gracefully stop processes on os signals.
 Package graceful provides a mechanism to gracefully stop processes on os signals.
Package grpcutil provides helpers for writing GRPC clients and servers.
 Package grpcutil provides helpers for writing GRPC clients and servers.
calculator
calculator/v1
Package jwt provides helpers for creating and validating json web tokens.
 Package jwt provides helpers for creating and validating json web tokens.
Package logger is our high throughput event bus.
 Package logger is our high throughput event bus.
Package mathutil provides the missing standard library math functions we need for various statistical computations.
 Package mathutil provides the missing standard library math functions we need for various statistical computations.
Package names contains helpers for parsing names into constituent parts, i.e.
 Package names contains helpers for parsing names into constituent parts, i.e.
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 profanity is the rules engine that powers the command `profanity` found in `github.com/blend/go-sdk/cmd/profanity`.
 Package profanity is the rules engine that powers the command `profanity` found in `github.com/blend/go-sdk/cmd/profanity`.
Package proxyprotocol implements network reader shims for terminating proxy protocol connections.
 Package proxyprotocol implements network reader shims for terminating proxy protocol connections.
r2
Package r2 is a rewrite of the sdk http request package that eschews fluent apis in favor of the options pattern.
 Package r2 is a rewrite of the sdk http request package that eschews fluent apis in favor of the options pattern.
r2test
Package r2test provides helpers for writing tests involving calls with sdk/r2.
 Package r2test provides helpers for writing tests involving calls with sdk/r2.
Package ratelimiter implements two common rate limiters; queue and token/leaky bucket.
 Package ratelimiter implements two common rate limiters; queue and token/leaky bucket.
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 retry implements a generic retry provider.
 Package retry implements a generic retry provider.
Package reverseproxy implements a simple reverse http proxy.
 Package reverseproxy implements a simple reverse http proxy.
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
Package semver is a fork of Hashicorp's semver package.
 Package semver is a fork of Hashicorp's semver package.
Package sentry provides helpers for logging errors to sentry from sdk primitives like the logger.
 Package sentry provides helpers for logging errors to sentry from sdk primitives like the logger.
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.
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.
cronstats
dbstats
Package dbstats provides shims for writing db logger events to a stats collector.
 Package dbstats provides shims for writing db logger events to a stats collector.
grpcstats
Package grpcstats provides shims for writing rpc logger events to a stats collector.
 Package grpcstats provides shims for writing rpc logger events to a stats collector.
httpstats
Package httpstats provides shims for writing webutil logger events to a stats collector.
 Package httpstats provides shims for writing webutil logger events to a stats collector.
r2stats
vaultstats
Package statsd implements a client and a debugging server for UDP statsd datagrams.
 Package statsd implements a client and a debugging server for UDP statsd datagrams.
_bench
_bench/server
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`.
Package timeutil includes helpers for working with timestamps.
 Package timeutil includes helpers for working with timestamps.
Package tracing implements some helpers and constants for open tracing.
 Package tracing implements some helpers and constants for open tracing.
autoflushtrace
crontrace
Package crontrace contains tracer helpers for cron, our job management service.
 Package crontrace contains tracer helpers for cron, our job management service.
dbtrace
Package dbtrace contains db tracing helpers.
 Package dbtrace contains db tracing helpers.
grpctrace
Package grpctrace provides tracing helpers for grpc servers and clients.
 Package grpctrace provides tracing helpers for grpc servers and clients.
httptrace
Package httptrace provides helpers for integrating http servers into distributed tracing results.
 Package httptrace provides helpers for integrating http servers into distributed tracing results.
oauthtrace
Package oauthtrace provides helpers for integrating OAuth calls into distributed tracing results.
 Package oauthtrace provides helpers for integrating OAuth calls into distributed tracing results.
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.
vaulttrace
Package vaulttrace contains helpers for integrating open tracing into calls made to vault with the go-sdk/secrets package.
 Package vaulttrace contains helpers for integrating open tracing into calls made to vault with the go-sdk/secrets package.
webtrace
Package webtrace implements shims for reporting tracing spans from web applications.
 Package webtrace implements shims for reporting tracing spans from web applications.
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.
Package validate provides helpers for validating struct values.
 Package validate provides helpers for validating struct values.
Package vault implements a high throughput vault client.
 Package vault implements a high throughput vault client.
Package web implements a model view controller system for building http servers.
 Package web implements a model view controller system for building http servers.
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.

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.