README
¶
go-sdk
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/cover: allows for project level coverage reporting and enforcement.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.
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...()
- Mutators that return a reference to the receiver, and don't produce an error, should start with
- Field accessors should be the uppercase name of the field, i.e.
foowould have an accessorFoo(). - Where possible, types should have a config object that fully represent the options you can set with
WithorSetmutators. - Said types should also have a constructor in the form
NewFromEnvthat uses thego-sdk/envpackage 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 |
|---|---|
|
Package assert adds helpers to make writing tests easier.
|
Package assert adds helpers to make writing tests easier. |
|
cmd
|
|
|
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. |
|
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. |
|
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. |
|
Package logger is our high throughput event bus.
|
Package logger is our high throughput event bus. |
|
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. |
|
Package request implements helpers ontop of net/http.Client.
|
Package request implements helpers ontop of net/http.Client. |
|
Package secrets implements a high throughput vault client.
|
Package secrets implements a high throughput vault client. |
|
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. |
|
Package semver is a fork of Hashicorp's semver package.
|
Package semver is a fork of Hashicorp's semver package. |
|
Package template implements helpers ontop of the stdlib `text/template`.
|
Package template implements helpers ontop of the stdlib `text/template`. |
|
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. |
|
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 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. |
Click to show internal directories.
Click to hide internal directories.