README
¶
gosrvlib
Go Service Library
This open-source project provides a collection of high-quality Go (Golang) packages.
Each package adheres to common conventions and can be imported individually into any project.
These packages serve as a solid foundation for building fully-featured, production-ready web services.
You can generate a new web service by running make project CONFIG=project.cfg. The project's name, description, and other settings can be customized in the configuration file specified by the CONFIG parameter.
The package documentation is available at: https://pkg.go.dev/github.com/Vonage/gosrvlib/
- category Library
- license MIT
- link https://github.com/Vonage/gosrvlib
TOC
Packages
gosrvlib offers a comprehensive collection of well-tested Go packages. Each package adheres to common conventions and coding standards, making them easy to integrate into your projects.
- awsopt – Utilities for configuring common AWS options with the aws-sdk-go-v2 library.
- awssecretcache – Client for retrieving and caching secrets from AWS Secrets Manager.
- bootstrap – Helpers for application bootstrap and initialization.
- config – Utilities for configuration loading and management.
- countrycode – Functions for country code lookup and validation.
- countryphone – Phone number parsing and country association.
- decint – Helpers for parsing and formatting decimal integers.
- devlake – Client for the DevLake Webhook API.
- dnscache – DNS resolution with caching support.
- encode – Utilities for data encoding and serialization.
- encrypt – Helpers for encryption and decryption.
- enumbitmap – Encode and decode slices of enumeration strings as integer bitmap values.
- enumcache – Caching for enumeration values with bitmap support.
- enumdb – Helpers for storing and retrieving enumeration sets in databases.
- errtrace – Error tracing and context propagation.
- filter – Generic rule-based filtering for struct slices.
- healthcheck – Health check endpoints and logic.
- httpclient – HTTP client with enhanced features.
- httpretrier – HTTP request retry logic.
- httpreverseproxy – HTTP reverse proxy implementation.
- httpserver – HTTP server setup and management.
- httputil – HTTP utility functions.
- jsendx – Helpers for JSend-compliant responses.
- ipify – IP address lookup using the ipify service.
- jirasrv – Client for Jira server APIs.
- jwt – JSON Web Token creation and validation.
- kafka – Kafka producer and consumer utilities.
- kafkacgo – Kafka integration using CGO bindings.
- logging – Structured logging utilities.
- maputil – Helpers for Go map manipulation.
- metrics – Metrics collection and reporting.
- prometheus – Prometheus metrics exporter.
- statsd – StatsD metrics exporter.
- mysqllock – Distributed locking using MySQL.
- numtrie – Trie data structure for numeric keys with partial matching.
- paging – Helpers for data pagination.
- passwordhash – Password hashing and verification.
- passwordpwned – Password breach checking via HaveIBeenPwned.
- periodic – Periodic task scheduling.
- phonekeypad – Phone keypad mapping utilities.
- profiling – Application profiling tools.
- randkey – Helpers for random key generation.
- random – Utilities for random data generation.
- redact – Data redaction helpers.
- redis – Redis client and utilities.
- retrier – Retry logic for operations.
- s3 – Helpers for AWS S3 integration.
- sfcache – Simple, in-memory, thread-safe, fixed-size, single-flight cache for expensive lookups.
- slack – Client for sending messages via the Slack API Webhook.
- sleuth – Client for the Sleuth.io API.
- sliceutil – Utilities for slice manipulation.
- sqlconn – Helpers for SQL database connections.
- sqltransaction – SQL transaction management.
- sqlutil – SQL utility functions.
- sqlxtransaction – Helpers for SQLX transactions.
- sqs – Utilities for AWS SQS (Simple Queue Service) integration.
- stringkey – Create unique hash keys from multiple strings.
- stringmetric – String similarity and distance metrics.
- testutil – Utilities for testing.
- threadsafe – Thread-safe data structures.
- timeutil – Time and date utilities.
- traceid – Trace ID generation and management.
- typeutil – Type conversion and utility functions.
- uidc – Unique identifier generation.
- validator – Data validation utilities.
- valkey – Wrapper client for interacting with valkey.io, an open-source in-memory data store.
Developers' Quick Start
To get started quickly with this project, follow these steps:
- Ensure you have the latest versions of Go and Python 3 installed (Python is required for additional tests).
- Clone the repository:
git clone https://github.com/Vonage/gosrvlib.git - Navigate to the project directory:
cd gosrvlib - Install dependencies and run all tests:
make x
You are now ready to start developing with gosrvlib!
This project includes a Makefile that simplifies testing and building on Linux-compatible systems. All artifacts and reports generated by the Makefile are stored in the target folder.
Alternatively, you can build the project inside a Docker container using:
make dbuild
This command uses the environment defined in resources/docker/Dockerfile.dev.
To view all available Makefile options, run:
make help
Running all tests
Before committing your code, ensure it is properly formatted and passes all tests by running:
make x
Alternatively, you can build and test the project inside a Docker container with:
make dbuild
Web-service project example
Refer to the examples/service directory for a sample web service built using this library.
To create a new project based on the example and the settings defined in project.cfg, run:
make project CONFIG=project.cfg
Directories
¶
| Path | Synopsis |
|---|---|
|
pkg
|
|
|
awsopt
Package awsopt provides functions to configure common AWS options for the official aws-sdk-go-v2 library.
|
Package awsopt provides functions to configure common AWS options for the official aws-sdk-go-v2 library. |
|
awssecretcache
Package awssecretcache provides a simple client for retrieving and caching secrets from AWS Secrets Manager.
|
Package awssecretcache provides a simple client for retrieving and caching secrets from AWS Secrets Manager. |
|
bootstrap
Package bootstrap provides a simple way to bootstrap an application with managed configuration, logging, metrics, application context, and shutdown signals.
|
Package bootstrap provides a simple way to bootstrap an application with managed configuration, logging, metrics, application context, and shutdown signals. |
|
config
Package config handles the configuration of a program.
|
Package config handles the configuration of a program. |
|
countrycode
Package countrycode provides information about countries and their ISO-3166 Codes.
|
Package countrycode provides information about countries and their ISO-3166 Codes. |
|
countryphone
Package countryphone provides geographical information of phone numbers.
|
Package countryphone provides geographical information of phone numbers. |
|
decint
Package decint provides utility functions to parse and represent decimal values as integers with a set precision.
|
Package decint provides utility functions to parse and represent decimal values as integers with a set precision. |
|
devlake
Package devlake provides a basic client for the DevLake Webhook API.
|
Package devlake provides a basic client for the DevLake Webhook API. |
|
dnscache
Package dnscache implements github.com/Vonage/gosrvlib/pkg/sfcache to provide a simple, local, thread-safe, fixed-size, and single-flight cache for DNS lookup calls.
|
Package dnscache implements github.com/Vonage/gosrvlib/pkg/sfcache to provide a simple, local, thread-safe, fixed-size, and single-flight cache for DNS lookup calls. |
|
encode
Package encode provides a collection of functions for safe serialization and deserialization of data between different systems, such as databases, queues, and caches.
|
Package encode provides a collection of functions for safe serialization and deserialization of data between different systems, such as databases, queues, and caches. |
|
encrypt
Package encrypt provides a collection of functions for safe encryption and decryption of data between different systems, such as databases, queues, and caches.
|
Package encrypt provides a collection of functions for safe encryption and decryption of data between different systems, such as databases, queues, and caches. |
|
enumbitmap
Package enumbitmap provides functions to encode slices of enumeration strings into integer bitmap values and vice versa.
|
Package enumbitmap provides functions to encode slices of enumeration strings into integer bitmap values and vice versa. |
|
enumcache
Package enumcache provides a collection of thread-safe methods for storing and retrieving enumeration sets with integer IDs and string names.
|
Package enumcache provides a collection of thread-safe methods for storing and retrieving enumeration sets with integer IDs and string names. |
|
enumdb
Package enumdb allows loading enumeration sets (github.com/Vonage/gosrvlib/pkg/enumcache) from multiple database tables.
|
Package enumdb allows loading enumeration sets (github.com/Vonage/gosrvlib/pkg/enumcache) from multiple database tables. |
|
errtrace
Package errtrace provides a function to automatically trace Go errors.
|
Package errtrace provides a function to automatically trace Go errors. |
|
filter
Package filter provides generic rule-based filtering capabilities for struct slices.
|
Package filter provides generic rule-based filtering capabilities for struct slices. |
|
healthcheck
Package healthcheck provides a simple way to define health checks for external services or components.
|
Package healthcheck provides a simple way to define health checks for external services or components. |
|
httpclient
Package httpclient provides a configurable and instrumented HTTP client with common options.
|
Package httpclient provides a configurable and instrumented HTTP client with common options. |
|
httpretrier
Package httpretrier provides the ability to automatically repeat HTTP requests based on user-defined conditions.
|
Package httpretrier provides the ability to automatically repeat HTTP requests based on user-defined conditions. |
|
httpreverseproxy
Package httpreverseproxy provides an HTTP Reverse Proxy that takes an incoming request and sends it to another server, proxying the response back to the client.
|
Package httpreverseproxy provides an HTTP Reverse Proxy that takes an incoming request and sends it to another server, proxying the response back to the client. |
|
httpserver
Package httpserver defines a default configurable HTTP server with common routes and options.
|
Package httpserver defines a default configurable HTTP server with common routes and options. |
|
httpserver/route
Package route is deprecated.
|
Package route is deprecated. |
|
httputil
Package httputil contains a collection of common HTTP Request and Response utility functions.
|
Package httputil contains a collection of common HTTP Request and Response utility functions. |
|
httputil/jsendx
Package jsendx implements a custom JSend model to wrap all HTTP responses in a consistent JSON object with default fields.
|
Package jsendx implements a custom JSend model to wrap all HTTP responses in a consistent JSON object with default fields. |
|
ipify
Package ipify allows to retrieve the public IP address of a service instance using the external ipify API (https://www.ipify.org/).
|
Package ipify allows to retrieve the public IP address of a service instance using the external ipify API (https://www.ipify.org/). |
|
jirasrv
Package jirasrv provides a basic boilerplate client for the official Jira server API.
|
Package jirasrv provides a basic boilerplate client for the official Jira server API. |
|
jwt
Package jwt provides simple wrapper functions for managing basic JWT Authentication with username/password credentials.
|
Package jwt provides simple wrapper functions for managing basic JWT Authentication with username/password credentials. |
|
kafka
Package kafka provides a simple high-level API for producing and consuming Apache Kafka messages.
|
Package kafka provides a simple high-level API for producing and consuming Apache Kafka messages. |
|
kafkacgo
Package kafkacgo provides a simple high-level API for producing and consuming Apache Kafka messages.
|
Package kafkacgo provides a simple high-level API for producing and consuming Apache Kafka messages. |
|
logging
Package logging implements a structured-log model with common functionalities and utility functions.
|
Package logging implements a structured-log model with common functionalities and utility functions. |
|
maputil
Package maputil provides a collection of utility functions for Go maps.
|
Package maputil provides a collection of utility functions for Go maps. |
|
metrics
Package metrics defines a common interface for instrumenting applications and components to collect metrics.
|
Package metrics defines a common interface for instrumenting applications and components to collect metrics. |
|
metrics/prometheus
Package prometheus implements the metrics interface for Prometheus.
|
Package prometheus implements the metrics interface for Prometheus. |
|
metrics/statsd
Package statsd implements the metrics interface for StatsD.
|
Package statsd implements the metrics interface for StatsD. |
|
mysqllock
Package mysqllock provides a distributed locking mechanism that leverages MySQL's internal functions.
|
Package mysqllock provides a distributed locking mechanism that leverages MySQL's internal functions. |
|
numtrie
Package numtrie provides a numerical-indexed trie data structure.
|
Package numtrie provides a numerical-indexed trie data structure. |
|
paging
Package paging provides utilities to handle pagination.
|
Package paging provides utilities to handle pagination. |
|
passwordhash
Package passwordhash implements a practical model to create and verify a password hashes using a strong one-way hashing algorithm.
|
Package passwordhash implements a practical model to create and verify a password hashes using a strong one-way hashing algorithm. |
|
passwordpwned
Package passwordpwned allows you to verify if a password has been pwned (compromised) in a data breach.
|
Package passwordpwned allows you to verify if a password has been pwned (compromised) in a data breach. |
|
periodic
Package periodic provides a way to execute a given function periodically at a specified time interval.
|
Package periodic provides a way to execute a given function periodically at a specified time interval. |
|
phonekeypad
Package phonekeypad provides functions to convert number strings to sequences of numbers corresponding to a standard phone keypad:
|
Package phonekeypad provides functions to convert number strings to sequences of numbers corresponding to a standard phone keypad: |
|
profiling
Package profiling allows accessing the pprof profiling data via the HTTP interface of the Go program.
|
Package profiling allows accessing the pprof profiling data via the HTTP interface of the Go program. |
|
randkey
Package randkey provides utility functions to generate random uint64 keys in different formats.
|
Package randkey provides utility functions to generate random uint64 keys in different formats. |
|
random
Package random contains a collection of utility functions for generating random numbers and strings.
|
Package random contains a collection of utility functions for generating random numbers and strings. |
|
redact
Package redact contains utility functions to obscure sensitive data.
|
Package redact contains utility functions to obscure sensitive data. |
|
redis
Package redis provides a simple and basic wrapper client for interacting with Redis (https://redis.io), an in-memory data store.
|
Package redis provides a simple and basic wrapper client for interacting with Redis (https://redis.io), an in-memory data store. |
|
retrier
Package retrier provides the ability to automatically repeat a user-defined function based on the error status.
|
Package retrier provides the ability to automatically repeat a user-defined function based on the error status. |
|
s3
Package s3 provides a simple and basic wrapper client for interacting with an AWS S3 bucket.
|
Package s3 provides a simple and basic wrapper client for interacting with an AWS S3 bucket. |
|
sfcache
Package sfcache provides a simple, local, thread-safe, fixed-size, and single-flight cache for expensive lookup calls.
|
Package sfcache provides a simple, local, thread-safe, fixed-size, and single-flight cache for expensive lookup calls. |
|
slack
Package slack is a basic client for the official Slack API used to send messages via a Webhook.
|
Package slack is a basic client for the official Slack API used to send messages via a Webhook. |
|
sleuth
Package sleuth provides a basic client for the official Sleuth.io API.
|
Package sleuth provides a basic client for the official Sleuth.io API. |
|
sliceutil
Package sliceutil provides a collection of utility functions for Go slices.
|
Package sliceutil provides a collection of utility functions for Go slices. |
|
sqlconn
Package sqlconn provides a simple way to connect to a SQL database and manage the connection.
|
Package sqlconn provides a simple way to connect to a SQL database and manage the connection. |
|
sqltransaction
Package sqltransaction provides a simple way to execute a function inside an SQL transaction.
|
Package sqltransaction provides a simple way to execute a function inside an SQL transaction. |
|
sqlutil
Package sqlutil provides SQL utility functions.
|
Package sqlutil provides SQL utility functions. |
|
sqlxtransaction
Package sqlxtransaction provides a simple way to execute a function inside an SQLX transaction.
|
Package sqlxtransaction provides a simple way to execute a function inside an SQLX transaction. |
|
sqs
Package sqs provides a simple and basic wrapper client for interacting with AWS SQS (Amazon Simple Queue Service).
|
Package sqs provides a simple and basic wrapper client for interacting with AWS SQS (Amazon Simple Queue Service). |
|
stringkey
Package stringkey provides the ability to create a simple unique hash key from multiple strings.
|
Package stringkey provides the ability to create a simple unique hash key from multiple strings. |
|
stringmetric
Package stringmetric provides functions to calculate string metrics, also known as string similarity metrics or string distance functions.
|
Package stringmetric provides functions to calculate string metrics, also known as string similarity metrics or string distance functions. |
|
testutil
Package testutil provides common testing utility functions.
|
Package testutil provides common testing utility functions. |
|
threadsafe
Package threadsafe provides an interface for thread-safe functions that can be safely used across multiple goroutines.
|
Package threadsafe provides an interface for thread-safe functions that can be safely used across multiple goroutines. |
|
threadsafe/tsmap
Package tsmap provides a collection of generic thread-safe Go map utility functions that can be safely used between multiple goroutines.
|
Package tsmap provides a collection of generic thread-safe Go map utility functions that can be safely used between multiple goroutines. |
|
threadsafe/tsslice
Package tsslice provides a collection of generic thread-safe Go slice utility functions that can be safely used across multiple goroutines.
|
Package tsslice provides a collection of generic thread-safe Go slice utility functions that can be safely used across multiple goroutines. |
|
timeutil
Package timeutil provides utility functions for working with time-related operations.
|
Package timeutil provides utility functions for working with time-related operations. |
|
traceid
Package traceid allows storing and retrieving a Trace ID value associated with a context.Context and an HTTP request.
|
Package traceid allows storing and retrieving a Trace ID value associated with a context.Context and an HTTP request. |
|
typeutil
Package typeutil contains a collection of type-related generic utility functions.
|
Package typeutil contains a collection of type-related generic utility functions. |
|
uid
Package uid provides functions to generate simple time-and-random-based unique identifiers.
|
Package uid provides functions to generate simple time-and-random-based unique identifiers. |
|
uidc
Package uidc provides functions to generate simple time-and-random-based unique identifiers.
|
Package uidc provides functions to generate simple time-and-random-based unique identifiers. |
|
validator
Package validator provides a simple and extensible field validation mechanism for structs and individual fields based on tags.
|
Package validator provides a simple and extensible field validation mechanism for structs and individual fields based on tags. |
|
valkey
Package valkey provides a simple and basic wrapper client for interacting with Valkey (https://valkey.io), an open source in-memory data store.
|
Package valkey provides a simple and basic wrapper client for interacting with Valkey (https://valkey.io), an open source in-memory data store. |
Click to show internal directories.
Click to hide internal directories.