go-sdk

module
v1.0.0-rc3 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2018 License: MIT

README

go-sdk

Build Status

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.

Packages

The main packages are as follows:

  • assert : helpers for writing tests; wraps *testing.T with more useful assertions.
  • collections : common collections like ringbuffers and sets.
  • configutil : helpers for reading config files.
  • cron : time triggered job management.
  • db : our postgres orm.
  • db/migration : helpers for writing postgres migrations.
  • env : helpers for reading / writing / testing environment variables.
  • exception : wraps error types with stack traces.
  • logger : our performance oriented event bus; event triggering is supported in most major packages.
  • oauth : a wrapper on golang.org/x/oauth2 that automates fetching profiles for google oauth.
  • proxy : an http/https reverse proxy.
  • proxy/proxy : a cli server the proxy.
  • request : wrappers for http.Client with support for testing and a fluent api.
  • selector : a portable implementation of kubernetes selectors.
  • semver : semantic versioning helpers.
  • template : text-template helpers.
  • template/template : a cli for reading templates and outputting results.
  • util : the junk drawer of random stuff.
  • uuid : generate and parse uuid v4's.
  • web : our web framework; useful for both rest api's and view based apps.
  • workqueue : a background work queue when you need to have a fixed number of workers.
  • yaml : a yaml marshaller / unmarshaller. based on go-yaml.

Addtional CLI Tools

We also provide the following CLI tools to help with development:

  • _bin/cover : allows for project level coverage reporting and enforcement.
  • _bin/profanity : profanity rules checking (i.e. fail on grep match).
  • _bin/recover : recover crashed processes (to be used when debugging panics).
  • _bin/semver : semver maniuplation and validation.

Code Style Notes

  • Where possible, follow the golang proverbs.
  • The primary type a package exports should be creatable with a bare constructor New() unless there are non-trivial defaults to set.
  • "Fluent APIs"
    • Mutators that return a reference to the receiver, and don't produce an error, should start with With...().
    • This allows you to chain calls, ex. New().WithFoo(...).WithBar(...).
    • Mutators that can return an error should start with Set...()
  • Field accessors should be the uppercase name of the field, i.e. foo would have an accessor Foo().
  • Where possible, types should have a config object that fully represent the options you can set with With or Set mutators.
  • Said types should also have a constructor in the form NewFromEnv that uses the go-sdk/env package to read options set in the environment.
  • 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.

To increment the local version

Patch:

make increment-patch

Minor:

make increment-minor

Major:

make increment-major

Directories

Path Synopsis
_bin
coverage
profanity
recover
semver
Package assert adds helpers to make writing tests easier.
 Package assert adds helpers to make writing tests easier.
Package collections contains some helper data structures.
 Package collections contains some helper data structures.
Package configutil contains helpers for reading configuration for programs.
 Package configutil contains helpers for reading configuration for programs.
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
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
_load_test
migration
migration/_examples/datafiles
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.
jwt
test
Package logger is our high throughput event bus.
 Package logger is our high throughput event bus.
_examples/custom_event
_examples/drain
_examples/http
_examples/json_logs
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 request implements helpers ontop of net/http.Client.
 Package request implements helpers ontop of net/http.Client.
_examples/request
_examples/transport
Package secrets implements a high throughput vault client.
 Package secrets implements a high throughput vault client.
_examples/client
_examples/config
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.
airbrake
crontrace
datadog
dbtrace
oauthtrace
requesttrace
tracing
webtrace
Package util is the junk drawer of helper functions.
 Package util is the junk drawer of helper functions.
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
_benchmark/clean
_benchmark/echo
_examples/api
_examples/auth
_examples/basic
_examples/healthz
_examples/logging
_examples/middleware
_examples/static
_examples/timeout
_examples/upgrades
_examples/views
Package workqueue implements a queue dispatched by a fixed group of workers.
 Package workqueue implements a queue dispatched by a fixed group of workers.
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.