README
¶
platform
A Go library providing infrastructure abstractions for cloud-native services. Each package defines a stable interface with multiple provider implementations, selected at runtime via config. All packages support Google Wire for dependency injection and instrument with OpenTelemetry where applicable.
Module: github.com/verygoodsoftwarenotvirus/platform
Go: 1.26
Design Patterns
Interface + implementations: Every major concern is defined as an interface in the root package (e.g., cache.Cache[T]), with provider implementations in subpackages. Swap implementations via config without changing call sites.
Config structs: Each package has a config subpackage with env:-tagged structs, ValidateWithContext() validation, and EnsureDefaults().
Wire DI: All packages expose wire.go with a Providers set for Google Wire.
OTel throughout: HTTP, gRPC, database, and messaging layers are instrumented for traces and metrics.
Error handling: Uses cockroachdb/errors for rich error context.
Development
make format # Format all Go code
make lint # Run golangci-lint (Docker) + shellcheck
make test # Run tests with race detector and shuffle
make build # Build all packages
make setup # Install dev tools and vendor deps
make revendor # Clean and re-vendor dependencies
Linting runs in Docker (golangci/golangci-lint). Formatting uses gci, goimports, fieldalignment, tagalign, and gofmt locally.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package analytics provides an event reporting interface for collecting and tracking customer data and events.
|
Package analytics provides an event reporting interface for collecting and tracking customer data and events. |
|
Package cache provides a generic caching interface with support for multiple backend implementations including Redis and in-memory stores.
|
Package cache provides a generic caching interface with support for multiple backend implementations including Redis and in-memory stores. |
|
Package capitalism provides a payment management interface for handling subscription plans and payment provider webhooks.
|
Package capitalism provides a payment management interface for handling subscription plans and payment provider webhooks. |
|
stripe
Package stripe provides Stripe functionality.
|
Package stripe provides Stripe functionality. |
|
Package circuitbreaking implements the circuit breaker pattern for managing service availability and preventing cascading failures.
|
Package circuitbreaking implements the circuit breaker pattern for managing service availability and preventing cascading failures. |
|
Package compression provides data compression and decompression using Zstd and S2 algorithms.
|
Package compression provides data compression and decompression using Zstd and S2 algorithms. |
|
cryptography
|
|
|
encryption
Package cryptography contains the interfaces and implementations for encrypting and decrypting data.
|
Package cryptography contains the interfaces and implementations for encrypting and decrypting data. |
|
encryption/aes
Package aes contains the interfaces and implementations for encrypting and decrypting data.
|
Package aes contains the interfaces and implementations for encrypting and decrypting data. |
|
encryption/mock
Package encryptionmock contains the interfaces and implementations for encrypting and decrypting data.
|
Package encryptionmock contains the interfaces and implementations for encrypting and decrypting data. |
|
encryption/salsa20
Package salsa20 contains the interfaces and implementations for encrypting and decrypting data.
|
Package salsa20 contains the interfaces and implementations for encrypting and decrypting data. |
|
Package database provides interface abstractions for interacting with relational data stores
|
Package database provides interface abstractions for interacting with relational data stores |
|
postgres
Package postgres provides an interface for writing to a Postgres instance.
|
Package postgres provides an interface for writing to a Postgres instance. |
|
Package email provides an interface for sending emails, with implementations for Mailgun, Mailjet, Postmark, Resend, and SendGrid.
|
Package email provides an interface for sending emails, with implementations for Mailgun, Mailjet, Postmark, Resend, and SendGrid. |
|
Package encoding provides HTTP response encoding abstractions
|
Package encoding provides HTTP response encoding abstractions |
|
mock
Package mockencoding provides mockable implementations of every interface defined in the outer encoding package.
|
Package mockencoding provides mockable implementations of every interface defined in the outer encoding package. |
|
Package errors re-exports cockroachdb/errors utilities and defines platform-level sentinel error values and HTTP/gRPC error conversion helpers.
|
Package errors re-exports cockroachdb/errors utilities and defines platform-level sentinel error values and HTTP/gRPC error conversion helpers. |
|
Package eventstream provides event streaming abstractions for server-to-client and bidirectional communication over HTTP, with implementations for SSE and WebSocket.
|
Package eventstream provides event streaming abstractions for server-to-client and bidirectional communication over HTTP, with implementations for SSE and WebSocket. |
|
Package fake provides generic test data generation utilities for creating fake instances of any type.
|
Package fake provides generic test data generation utilities for creating fake instances of any type. |
|
Package featureflags provides a feature flag evaluation interface for controlling feature availability per user, with implementations for LaunchDarkly and PostHog.
|
Package featureflags provides a feature flag evaluation interface for controlling feature availability per user, with implementations for LaunchDarkly and PostHog. |
|
Package healthcheck provides health check monitoring for service components with status tracking and aggregation via a registry pattern.
|
Package healthcheck provides health check monitoring for service components with status tracking and aggregation via a registry pattern. |
|
Package httpclient constructs HTTP clients with optional OpenTelemetry tracing instrumentation.
|
Package httpclient constructs HTTP clients with optional OpenTelemetry tracing instrumentation. |
|
Package identifiers is a handy place to request a new string identifier from.
|
Package identifiers is a handy place to request a new string identifier from. |
|
Package internalerrors provides platform-internal error factory functions for common error scenarios such as nil configuration.
|
Package internalerrors provides platform-internal error factory functions for common error scenarios such as nil configuration. |
|
Package llm provides a language model completion interface with implementations for Anthropic and OpenAI providers.
|
Package llm provides a language model completion interface with implementations for Anthropic and OpenAI providers. |
|
Package messagequeue provides message queue publisher and consumer interfaces with implementations for Google Pub/Sub, Redis, and Amazon SQS.
|
Package messagequeue provides message queue publisher and consumer interfaces with implementations for Google Pub/Sub, Redis, and Amazon SQS. |
|
Package notifications provides a push notification sending interface with implementations for APNs and FCM.
|
Package notifications provides a push notification sending interface with implementations for APNs and FCM. |
|
Package numbers provides numeric utility functions for rounding, scaling, and yield adjustment calculations.
|
Package numbers provides numeric utility functions for rounding, scaling, and yield adjustment calculations. |
|
Package observability provides unified configuration and initialization for the four observability pillars: logging, metrics, tracing, and profiling.
|
Package observability provides unified configuration and initialization for the four observability pillars: logging, metrics, tracing, and profiling. |
|
metrics
Package metrics provides a metrics-tracking implementation for the service.
|
Package metrics provides a metrics-tracking implementation for the service. |
|
metrics/mock
Package mockmetrics provides metrics-related mocks.
|
Package mockmetrics provides metrics-related mocks. |
|
tracing
Package tracing provides distributed tracing utilities.
|
Package tracing provides distributed tracing utilities. |
|
tracing/cloudtrace
Package cloudtrace provides common functions for attaching values to trace spans
|
Package cloudtrace provides common functions for attaching values to trace spans |
|
tracing/oteltrace
Package oteltrace provides common functions for attaching values to trace spans
|
Package oteltrace provides common functions for attaching values to trace spans |
|
utils
Package o11yutils offers observability utility functions.
|
Package o11yutils offers observability utility functions. |
|
Package panicking provides an abstraction over panic behavior, enabling testing and mocking of panic-inducing code paths.
|
Package panicking provides an abstraction over panic behavior, enabling testing and mocking of panic-inducing code paths. |
|
Package pointer provides generic utility functions for creating pointers to values and dereferencing pointer values and slices.
|
Package pointer provides generic utility functions for creating pointers to values and dereferencing pointer values and slices. |
|
Package qrcodes provides QR code generation for TOTP two-factor authentication setup.
|
Package qrcodes provides QR code generation for TOTP two-factor authentication setup. |
|
Package random provides cryptographically secure random string generation in hex, base32, and base64 encodings.
|
Package random provides cryptographically secure random string generation in hex, base32, and base64 encodings. |
|
Package ratelimiting provides a per-key rate limiter interface using the token bucket algorithm.
|
Package ratelimiting provides a per-key rate limiter interface using the token bucket algorithm. |
|
Package reflection provides utilities for struct field inspection, tag extraction, and dynamic method introspection.
|
Package reflection provides utilities for struct field inspection, tag extraction, and dynamic method introspection. |
|
Package retry provides retry policies with exponential backoff and optional jitter for resilient operation execution.
|
Package retry provides retry policies with exponential backoff and optional jitter for resilient operation execution. |
|
Package routing provides HTTP routing abstractions including router, middleware, and route parameter interfaces.
|
Package routing provides HTTP routing abstractions including router, middleware, and route parameter interfaces. |
|
search
|
|
|
text
Package search defines an interface for a search index management structure
|
Package search defines an interface for a search index management structure |
|
text/algolia
Package algolia provides an interface-compatible wrapper around the algolia indexer
|
Package algolia provides an interface-compatible wrapper around the algolia indexer |
|
text/elasticsearch
Package elasticsearch provides an interface-compatible wrapper around the elasticsearch indexer
|
Package elasticsearch provides an interface-compatible wrapper around the elasticsearch indexer |
|
text/mock
Package mocksearch provides an interface-compatible search index mock
|
Package mocksearch provides an interface-compatible search index mock |
|
Package secrets provides a secret retrieval interface with implementations for environment variables, GCP Secret Manager, and AWS SSM Parameter Store.
|
Package secrets provides a secret retrieval interface with implementations for environment variables, GCP Secret Manager, and AWS SSM Parameter Store. |
|
server
|
|
|
http
Package http2 provides an HTTP server comprised of multiple HTTP services
|
Package http2 provides an HTTP server comprised of multiple HTTP services |
|
Package testutils contains common functions for integration/load tests
|
Package testutils contains common functions for integration/load tests |
|
Package types defines common API response types, error codes, and generic range types used across the platform.
|
Package types defines common API response types, error codes, and generic range types used across the platform. |
|
Package uploads provides a file upload management interface for saving and reading files, with implementations for S3, GCS, and local filesystem.
|
Package uploads provides a file upload management interface for saving and reading files, with implementations for S3, GCS, and local filesystem. |
|
images
Package images is largely (and respectfully) inspired by/copied from this repo: github.com/olahol/go-imageupload
|
Package images is largely (and respectfully) inspired by/copied from this repo: github.com/olahol/go-imageupload |
|
Package version manages build-time version and VCS metadata injection via linker flags.
|
Package version manages build-time version and VCS metadata injection via linker flags. |
Click to show internal directories.
Click to hide internal directories.