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 instrument with OpenTelemetry where applicable.
Module: github.com/primandproper/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().
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. |
|
mock
Package analyticsmock provides moq-generated mocks for the analytics package.
|
Package analyticsmock provides moq-generated mocks for the analytics package. |
|
Package bitmask provides a generic, immutable bitmask type with set operations for unsigned integer types.
|
Package bitmask provides a generic, immutable bitmask type with set operations for unsigned integer types. |
|
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. |
|
mock
Package mock provides moq-generated mock implementations of interfaces in the cache package.
|
Package mock provides moq-generated mock implementations of interfaces in the cache package. |
|
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. |
|
mock
Package capitalismmock provides mock implementations of the capitalism package's interfaces.
|
Package capitalismmock provides mock implementations of the capitalism package's interfaces. |
|
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. |
|
mock
Package mock provides mock implementations of the circuitbreaking package's interfaces.
|
Package mock provides mock implementations of the circuitbreaking package's interfaces. |
|
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 provides mock implementations of the encryption package's interfaces.
|
Package encryptionmock provides mock implementations of the encryption package's interfaces. |
|
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 |
|
mock
Package mockdatabase provides moq-generated mocks for the database package.
|
Package mockdatabase provides moq-generated mocks for the database package. |
|
mysql
Package mysql provides an interface for writing to a MySQL instance.
|
Package mysql provides an interface for writing to a MySQL instance. |
|
postgres
Package postgres provides an interface for writing to a Postgres instance.
|
Package postgres provides an interface for writing to a Postgres instance. |
|
sqlite
Package sqlite provides an interface for writing to a SQLite database.
|
Package sqlite provides an interface for writing to a SQLite database. |
|
Package distributedlock provides a pessimistic mutual-exclusion atom for coordinating exclusive access to a named resource across processes.
|
Package distributedlock provides a pessimistic mutual-exclusion atom for coordinating exclusive access to a named resource across processes. |
|
mock
Package mock provides mock implementations of the distributedlock package's interfaces.
|
Package mock provides mock implementations of the distributedlock package's interfaces. |
|
postgres
Package postgres implements distributedlock.Locker against PostgreSQL session- scoped advisory locks (pg_try_advisory_lock).
|
Package postgres implements distributedlock.Locker against PostgreSQL session- scoped advisory locks (pg_try_advisory_lock). |
|
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. |
|
mock
Package emailmock provides mock implementations of the email package's interfaces.
|
Package emailmock provides mock implementations of the email package's interfaces. |
|
Package embeddings provides a vector embedding interface with implementations for OpenAI, Ollama, and Cohere providers.
|
Package embeddings provides a vector embedding interface with implementations for OpenAI, Ollama, and Cohere providers. |
|
mock
Package mock provides mock implementations of the embeddings package's interfaces.
|
Package mock provides mock implementations of the embeddings package's interfaces. |
|
Package encoding provides HTTP response encoding abstractions
|
Package encoding provides HTTP response encoding abstractions |
|
mock
Package mockencoding provides moq-generated mocks for the encoding package.
|
Package mockencoding provides moq-generated mocks for the 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. |
|
mock
Package mock provides mock implementations of the featureflags package's interfaces.
|
Package mock provides mock implementations of the featureflags package's interfaces. |
|
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 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. |
|
mock
Package mock provides mock implementations of the llm package's interfaces.
|
Package mock provides mock implementations of the llm package's interfaces. |
|
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. |
|
mock
Package mockpublishers provides moq-generated mocks for the messagequeue package's Publisher, PublisherProvider, Consumer, and ConsumerProvider interfaces.
|
Package mockpublishers provides moq-generated mocks for the messagequeue package's Publisher, PublisherProvider, Consumer, and ConsumerProvider interfaces. |
|
notifications
|
|
|
async
Package async provides a channel-based async event delivery interface with implementations for WebSocket, SSE, Pusher, and Ably.
|
Package async provides a channel-based async event delivery interface with implementations for WebSocket, SSE, Pusher, and Ably. |
|
mobile
Package mobile provides a push notification sending interface with implementations for APNs and FCM.
|
Package mobile 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 moq-generated mocks for the metrics package.
|
Package mockmetrics provides moq-generated mocks for the metrics package. |
|
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. |
|
mock
Package mockpanicking provides mock implementations of the panicking package's interfaces.
|
Package mockpanicking provides mock implementations of the panicking package's interfaces. |
|
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. |
|
mock
Package randommock provides mock implementations of the random package's interfaces.
|
Package randommock provides mock implementations of the random package's interfaces. |
|
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. |
|
mock
Package mockrouting provides mock implementations of the routing package's interfaces.
|
Package mockrouting provides mock implementations of the routing package's 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 moq-generated mocks for the search/text package.
|
Package mocksearch provides moq-generated mocks for the search/text package. |
|
vector
Package vectorsearch provides a generic interface for vector (nearest-neighbor) search backends, parallel to the textsearch package under search/text.
|
Package vectorsearch provides a generic interface for vector (nearest-neighbor) search backends, parallel to the textsearch package under search/text. |
|
vector/mock
Package mock provides moq-generated mocks for the search/vector package.
|
Package mock provides moq-generated mocks for the search/vector package. |
|
vector/pgvector
Package pgvector implements vectorsearch.Index against a PostgreSQL database running the pgvector extension.
|
Package pgvector implements vectorsearch.Index against a PostgreSQL database running the pgvector extension. |
|
vector/qdrant
Package qdrant implements vectorsearch.Index against a Qdrant vector database over its REST API.
|
Package qdrant implements vectorsearch.Index against a Qdrant vector database over its REST API. |
|
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 |
|
containers
Package containers provides shared helpers for starting testcontainers with uniform retry behavior.
|
Package containers provides shared helpers for starting testcontainers with uniform retry behavior. |
|
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 |
|
mock
Package mockuploads provides mock implementations of the uploads package's interfaces.
|
Package mockuploads provides mock implementations of the uploads package's interfaces. |
|
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.