Categorygithub.com/blend/go-sdk
module
1.20240719.1
Repository: https://github.com/blend/go-sdk.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
0
Dependents
0
Files
0

# 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.16+ 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/copyright : injects and verifies copyright headers are present in files.
  • 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

We currently don't accept PRs as this repository at this time, but feel free to log issues and we'll address when we can.

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

We follow calendar versioning. What that means in practice:

[major].[year][month][day].[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 is the used to distinguish different versions from the same calendar day.

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

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

  • v1.xxxxxxxx.x

All other major versions are deprecated. The previous semver scheme is deprecated.

Version Release Cycle

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.

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, including:

# Packages

Package ansi contains helpers for working with ansi colors.
Package assert adds helpers to make writing tests easier.
Package async provides synchronization primitives and background workers.
No description provided by the author
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 bufferutil provides helpers for dealing with buffers.
Package cache provides caching primitives for in-memory caches, including LRU eviction.
Package certutil contains helpers for working with x509 certificates.
No description provided by the author
Package codeowners includes github codeowners management utilities */.
Package generic contains generic helper data structures.
Package configmeta provides a configutil metadata type to provide a canonical location to hold common config variables.
Package configutil contains helpers for configuration.
Package consistenthash contains helpers for mapping items to buckets using consistent hashing.
Package copyright includes copyright header management utilities */.
Package cron is an implementation of a job scheduler to run within a worker or a server.
Package crypto includes common cryptography helpers.
Package datadog includes helpers for interacting with datadog.
Package db provides a basic abstraction layer above normal database/sql.
Package diff includes text diffing functions.
Package email includes helpers for sending SMTP messages.
Package env contains environment variable helpers, enabling better tests and easier use of environment variables.
No description provided by the author
Package ex provides the foundations for error handling in the SDK tree.
No description provided by the author
Package expvar provides a standardized interface to public variables, such as operation counters in servers.
Package filelock provides a platform-independent API for advisory file locking.
Package fileutil provides helpers for reading and writing files.
Package graceful provides a mechanism to gracefully stop processes on os signals.
Package grpcutil provides helpers for writing GRPC clients and servers.
No description provided by the author
Package logger is our high throughput event bus.
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 oauth implements some helper wrappers ontop of the existing google implementation of oauth.
No description provided by the author
Package profanity is the rules engine that powers the command `profanity` found in `github.com/blend/go-sdk/cmd/profanity`.
No description provided by the author
Package proxyprotocol implements network reader shims for terminating proxy protocol connections.
Package r2 is a rewrite of the sdk http request package that eschews fluent apis in favor of the options pattern.
Package ratelimiter implements two common rate limiters; queue and token/leaky bucket.
No description provided by the author
Package ref includes helpers for dealing with "optional" values represented by pointers.
Package reflectutil includes helpers for working with the golang reflection api.
Package retry implements a generic retry provider.
Package reverseproxy implements a simple reverse http proxy.
No description provided by the author
No description provided by the author
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 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 shamir includes an implementation of shamir's sharing scheme.
Package shardutil provides some sdk/db primitives for dealing with (manually) sharded postgres databases.
Package slack includes helpers for sending slack webhooks.
No description provided by the author
No description provided by the author
No description provided by the author
Package stats includes helpers for writing stats to collectors by adding listeners to logger instances.
Package statsd implements a client and a debugging server for UDP statsd datagrams.
No description provided by the author
Package status provides helpers for building standardized sla status endpoints in web services.
Package stringutil includes string utility functions and helpers.
Package template implements helpers on-top of the stdlib `text/template`.
No description provided by the author
Package timeutil includes helpers for working with timestamps.
Package tracing implements some helpers and constants for open tracing.
Package uuid is a basic implementation of the version 4 spec of the universal unique identifier.
Package validate provides helpers for validating struct values.
Package vault implements a high throughput vault client.
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.