diff --git a/pkg/awsopt/awsopt.go b/pkg/awsopt/awsopt.go index e4d77087..aaaea8e0 100644 --- a/pkg/awsopt/awsopt.go +++ b/pkg/awsopt/awsopt.go @@ -1,7 +1,12 @@ /* -Package awsopt provides functions to configure common AWS options for the official aws-sdk-go-v2 library. - -These common options can be easily used with other AWS-based packages in this library, such as s3 and sqs. +Package awsopt provides functions to configure common AWS options for the +official aws-sdk-go-v2 library. + +These common options can be easily used with other AWS-based packages in this +library: + - awssecretcache + - s3 + - sqs */ package awsopt diff --git a/pkg/awssecretcache/awssecretcache.go b/pkg/awssecretcache/awssecretcache.go index 9bca308c..b39e4a50 100644 --- a/pkg/awssecretcache/awssecretcache.go +++ b/pkg/awssecretcache/awssecretcache.go @@ -1,12 +1,29 @@ /* -Package awssecretcache provides a simple client to retrieve and cache secrets from AWS Secrets Manager. -To improve speed and reduce costs, the client uses a thread-safe local single-flight cache -that avoids duplicate calls for the same secret. -The cache has a maximum size and a time-to-live (TTL) for each entry. -Duplicate calls for the same secret will wait for the first lookup to complete and return the same value. +Package awssecretcache provides a simple client for retrieving and caching +secrets from AWS Secrets Manager. -This package is based on the official aws-sdk-go-v2 library. +This package is based on the official aws-sdk-go-v2 library +(https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/secretsmanager) and +implements github.com/Vonage/gosrvlib/pkg/sfcache to provide a simple, local, +thread-safe, fixed-size, and single-flight cache for AWS Secrets lookup calls. -Reference: https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/secretsmanager. +By caching previous values, awssecretcache improves the performance of secrets +lookup by eliminating the need for repeated expensive requests. + +This package provides a local in-memory cache with a configurable maximum number +of entries. The fixed size helps with efficient memory management and prevents +excessive memory usage. The cache is thread-safe, allowing concurrent access +without the need for external synchronization. It efficiently handles concurrent +requests by sharing results from the first lookup, ensuring that only one +request makes the expensive call, and avoiding unnecessary network load or +resource starvation. Duplicate calls for the same key will wait for the first +call to complete and return the same value. + +Each cache entry has a set time-to-live (TTL), so it will automatically expire. +However, it is also possible to force the removal of a specific entry or reset +the entire cache. + +This package is ideal for any Go application that heavily relies on AWS Secrets +lookups. */ package awssecretcache diff --git a/pkg/bootstrap/bootstrap.go b/pkg/bootstrap/bootstrap.go index 4dc2a00e..0a509947 100644 --- a/pkg/bootstrap/bootstrap.go +++ b/pkg/bootstrap/bootstrap.go @@ -1,6 +1,6 @@ /* -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. For an implementation example see in order: - examples/service/cmd/main.go diff --git a/pkg/config/config.go b/pkg/config/config.go index c10b7b77..3d2114d9 100644 --- a/pkg/config/config.go +++ b/pkg/config/config.go @@ -1,26 +1,40 @@ /* -Package config handles the configuration of a program. -The configuration contains the set of initial parameter settings that are read at runtime by the program. +Package config handles the configuration of a program. The configuration +contains the set of initial parameter settings that are read at runtime by the +program. -This package allows plugging a fully-fledged configuration system into an application, taking care of the boilerplate code, common settings, configuration loading, and validation. +This package allows plugging a fully-fledged configuration system into an +application, taking care of the boilerplate code, common settings, configuration +loading, and validation. -Different configuration sources can be used during development, debugging, testing, or deployment. -The configuration can be loaded from a local file, environment variables, or a remote configuration provider (e.g., Consul, etcd, etcd3, Firestore, NATS). +Different configuration sources can be used during development, debugging, +testing, or deployment. The configuration can be loaded from a local file, +environment variables, or a remote configuration provider (e.g., Consul, etcd, +etcd3, Firestore, NATS). -This is a Viper-based implementation of the configuration model described in the following article: - - Nicola Asuni, 2014-09-13, "Software Configuration", https://technick.net/guides/software/software_configuration/ +This is a Viper-based implementation of the configuration model described in the +following article: + - Nicola Asuni, 2014-09-13, "Software Configuration", + https://technick.net/guides/software/software_configuration/ # Configuration Loading Strategy: -To achieve maximum flexibility, the different configuration entry points are coordinated in the following sequence (1 has the lowest priority and 5 has the highest): +To achieve maximum flexibility, the different configuration entry points are +coordinated in the following sequence (1 has the lowest priority and 5 has the +highest): - 1. In the "myprog" program, the configuration parameters are defined as a data structure that can be easily mapped to and from a JSON object (or any other format supported by Viper like TOML, YAML, and HCL). - Each structure parameter is annotated with the "mapstructure" and "validate" tags to define the name mapping and the validation rules. - The parameters are initialized with constant default values. + 1. In the "myprog" program, the configuration parameters are defined as a data + structure that can be easily mapped to and from a JSON object (or any other + format supported by Viper like TOML, YAML, and HCL). Each structure + parameter is annotated with the "mapstructure" and "validate" tags to define + the name mapping and the validation rules. The parameters are initialized + with constant default values. - 2. The program attempts to load the local "config.json" configuration file, and as soon as one is found, it overwrites the default values previously set. + 2. The program attempts to load the local "config.json" configuration file, and + as soon as one is found, it overwrites the default values previously set. - The configuration file is searched in the following ordered directories based on the Linux Filesystem Hierarchy Standard (FHS): + The configuration file is searched in the following ordered directories + based on the Linux Filesystem Hierarchy Standard (FHS): - ./ @@ -28,7 +42,9 @@ To achieve maximum flexibility, the different configuration entry points are coo - /etc/myprog/ - 3. The program attempts to load the environmental variables that define the remote configuration system. If found, it overwrites the corresponding configuration parameters: + 3. The program attempts to load the environmental variables that define the + remote configuration system. If found, it overwrites the corresponding + configuration parameters: - [ENVIRONMENT VARIABLE NAME] → [CONFIGURATION PARAMETER NAME] @@ -42,22 +58,30 @@ To achieve maximum flexibility, the different configuration entry points are coo - MYPROG_REMOTECONFIGDATA → remoteConfigData - 4. If the "remoteConfigProvider" parameter is not empty, the program attempts to load the configuration data from the specified source. - This can be any remote source supported by the Viper library (e.g., Consul, etcd, etcd3, Firestore, NATS). - The configuration source can also be the "MYPROG_REMOTECONFIGDATA" environment variable as base64-encoded JSON when "MYPROG_REMOTECONFIGPROVIDER" is set to "envvar". + 4. If the "remoteConfigProvider" parameter is not empty, the program attempts + to load the configuration data from the specified source. This can be any + remote source supported by the Viper library (e.g., Consul, etcd, etcd3, + Firestore, NATS). The configuration source can also be the + "MYPROG_REMOTECONFIGDATA" environment variable as base64-encoded JSON when + "MYPROG_REMOTECONFIGPROVIDER" is set to "envvar". - 5. Any specified command-line argument overwrites the corresponding configuration parameter. + 5. Any specified command-line argument overwrites the corresponding + configuration parameter. 6. The configuration parameters are validated via the Validate() function. # Example: - - An implementation example of this configuration package can be found in examples/service/internal/cli/config.go - Note that the "log", "shutdown_timeout", and "remoteConfig" parameters are defined in this package as they are common to all programs. + - An implementation example of this configuration package can be found in + examples/service/internal/cli/config.go Note that the "log", + "shutdown_timeout", and "remoteConfig" parameters are defined in this + package as they are common to all programs. - - The configuration file format of the example service is defined by examples/service/resources/etc/gosrvlibexample/config.schema.json + - The configuration file format of the example service is defined by + examples/service/resources/etc/gosrvlibexample/config.schema.json - - The default configuration file of the example service is defined by examples/service/resources/etc/gosrvlibexample/config.json + - The default configuration file of the example service is defined by + examples/service/resources/etc/gosrvlibexample/config.json */ package config diff --git a/pkg/decint/decint.go b/pkg/decint/decint.go index bb7d5400..931705d0 100644 --- a/pkg/decint/decint.go +++ b/pkg/decint/decint.go @@ -1,7 +1,9 @@ /* -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. -The functions in this package are typically used to store and retrieve small currency values without loss of precision. +The functions in this package are typically used to store and retrieve small +currency values without loss of precision. Safe decimal values are limited up to 2^53 / 1e+6 = 9_007_199_254.740_992. */ diff --git a/pkg/dnscache/dnscache.go b/pkg/dnscache/dnscache.go index 70477202..b800f064 100644 --- a/pkg/dnscache/dnscache.go +++ b/pkg/dnscache/dnscache.go @@ -1,7 +1,28 @@ /* -Package dnscache provides a thread-safe local single-flight DNS cache for LookupHost. -The cache has a maximum size and a time-to-live (TTL) for each DNS entry. -Duplicate LookupHost calls for the same host will wait for the first lookup to complete and return the same value. +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. + +This package provides LookupHost() and DialContext() functions that can be used +in place of the standard ones in the net package. + +By caching previous values, dnscache improves DNS lookup performance by +eliminating the need for repeated expensive requests. + +This package provides a local in-memory cache with a configurable maximum number +of entries. The fixed size helps with efficient memory management and prevents +excessive memory usage. The cache is thread-safe, allowing concurrent access +without the need for external synchronization. It efficiently handles concurrent +requests by sharing results from the first lookup, ensuring only one request +does the expensive call, and avoiding unnecessary network load or resource +starvation. Duplicate calls for the same key will wait for the first call to +complete and return the same value. + +Each cache entry has a set time-to-live (TTL), so it will automatically expire. +However, it is also possible to force the removal of a specific DNS entry or +reset the entire cache. + +This package is ideal for any Go application that relies heavily on DNS lookups. */ package dnscache diff --git a/pkg/encode/encode.go b/pkg/encode/encode.go index c4e174cb..b48c6053 100644 --- a/pkg/encode/encode.go +++ b/pkg/encode/encode.go @@ -1,6 +1,7 @@ /* -Package encode provides serialization and deserialization functions to safely transmit, -store and retrieve data between different systems (e.g., databases, queues, caches, etc.). +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 diff --git a/pkg/encrypt/encrypt.go b/pkg/encrypt/encrypt.go index 5dc63c95..ec7ed1f6 100644 --- a/pkg/encrypt/encrypt.go +++ b/pkg/encrypt/encrypt.go @@ -1,5 +1,7 @@ /* -Package encrypt contains a collection of utility functions to encrypt and decrypt data. +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 diff --git a/pkg/enumbitmap/enumbitmap.go b/pkg/enumbitmap/enumbitmap.go index ebb14f27..3415c32b 100644 --- a/pkg/enumbitmap/enumbitmap.go +++ b/pkg/enumbitmap/enumbitmap.go @@ -1,9 +1,11 @@ /* -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. -Each bit correspond to a unique enumeration value. +Each bit correspond to a unique enumeration value. It supports maximum 32 bit +(33 distinct values including NONE). -# Example: +# Example with 8 bits: 00000000 = 0 dec = NONE 00000001 = 1 dec = FIRST diff --git a/pkg/enumcache/enumcache.go b/pkg/enumcache/enumcache.go index a4fdd728..840753e1 100644 --- a/pkg/enumcache/enumcache.go +++ b/pkg/enumcache/enumcache.go @@ -1,6 +1,8 @@ /* -Package enumcache provides simple thread-safe methods to store and retrieve enumeration sets with an integer ID and string name. -It includes support for binary maps (enumbitmap), where each bit represents a different name in the enumeration set. +Package enumcache provides a collection of thread-safe methods for storing and +retrieving enumeration sets with integer IDs and string names. It includes +support for binary maps (github.com/Vonage/gosrvlib/pkg/enumbitmap), where each +bit represents a different name in the enumeration set. */ package enumcache diff --git a/pkg/enumdb/enumdb.go b/pkg/enumdb/enumdb.go index b09a6cf4..7bf4b144 100644 --- a/pkg/enumdb/enumdb.go +++ b/pkg/enumdb/enumdb.go @@ -1,9 +1,11 @@ /* -Package enumdb allows to load enumeration sets (enumcache) from multiple database tables. +Package enumdb allows loading enumeration sets +(github.com/Vonage/gosrvlib/pkg/enumcache) from multiple database tables. -Each enumeration has a numerical ID ("id" on the database table as primary key) and a string name ("name" on the database table as unique string). +Each enumeration has a numerical ID ("id" on the database table as the primary +key) and a string name ("name" on the database table as a unique string). -Example of MySQL database table that can be used with this package: +Example of a MySQL database table that can be used with this package: CREATE TABLE IF NOT EXISTS `example` ( `id` SMALLINT UNSIGNED NOT NULL, diff --git a/pkg/errtrace/trace.go b/pkg/errtrace/trace.go index 24588b50..1a4b47ec 100644 --- a/pkg/errtrace/trace.go +++ b/pkg/errtrace/trace.go @@ -1,5 +1,7 @@ /* -Package errtrace provides a function to automatically trace errors. +Package errtrace provides a function to automatically trace Go errors. Each +error is annotated with the filename, line number, and function name where it +was created. */ package errtrace @@ -8,7 +10,7 @@ import ( "runtime" ) -// Trace annotates the error message with the filename, line number and function name. +// Trace annotates the error message with the filename, line number, and function name. func Trace(err error) error { if err == nil { return nil diff --git a/pkg/exttools/exttools.go b/pkg/exttools/exttools.go index cadb66e4..78fab11c 100644 --- a/pkg/exttools/exttools.go +++ b/pkg/exttools/exttools.go @@ -1,9 +1,9 @@ //go:build exttools /* -Package exttools lists external build and test tools. -These tools will appear in the `go.mod` file, but will not be a part of the build. -They will be also excluded from the binaries as the "exttools" tag is not used. +Package exttools lists external build and test tools. These tools will appear in +the `go.mod` file but will not be included in the build process. They will also +be excluded from the binaries since the "exttools" tag is not used. */ package exttools diff --git a/pkg/filter/filter.go b/pkg/filter/filter.go index 9bb1dae7..804965cd 100644 --- a/pkg/filter/filter.go +++ b/pkg/filter/filter.go @@ -1,14 +1,18 @@ /* -Package filter provides generic rule-based filtering capabilities for struct slices. +Package filter provides generic rule-based filtering capabilities for struct +slices. -Large sets of data can be filtered down to a subset of elements using a set of rules. +Large sets of data can be filtered down to a subset of elements using a set of +rules. -The filter can be specified as a slice of slices of rules or as JSON (see filter_schema.json for the JSON schema). -The first slice contains the rule sets that will be combined with a boolean AND. -The sub-slices contain the rules that will be combined with a boolean OR. +The filter can be specified as a slice of slices of rules or as JSON (see +filter_schema.json for the JSON schema). The first slice contains the rule sets +that will be combined with a boolean AND. The sub-slices contain the rules that +will be combined with a boolean OR. -A common application consists of users specifying a filter in a URL query parameter to reduce the amount of data to download on a GET request. -The rules are parsed and applied server-side. +A common application consists of users specifying a filter in a URL query +parameter to reduce the amount of data to download on a GET request. The rules +are parsed and applied server-side. # Example: @@ -62,7 +66,8 @@ The supported rule types are listed in the rule.go file: - ">=" : Greater than or equal to - matches when the value is greater than or equal the reference. Every rule type can be prefixed with the symbol "!" to get the negated value. -For example "!==" is equivalent to "Not Equal", matching values that are different. +For example "!==" is equivalent to "Not Equal", matching values that are +different. */ package filter diff --git a/pkg/healthcheck/healthcheck.go b/pkg/healthcheck/healthcheck.go index 90e467f1..c73d74c6 100644 --- a/pkg/healthcheck/healthcheck.go +++ b/pkg/healthcheck/healthcheck.go @@ -1,9 +1,9 @@ /* Package healthcheck provides a simple way to define health checks for external services or components. -It provides an HTTP handler to collect the results of the health checks concurrently. +It provides an HTTP handler to collect and return the results of the health checks concurrently. -For an implementation example see the examples/service/internal/cli/bind.go file. +For an implementation example, see the file examples/service/internal/cli/bind.go. */ package healthcheck diff --git a/pkg/httpclient/httpclient.go b/pkg/httpclient/httpclient.go index 2e60e2c7..c3b81352 100644 --- a/pkg/httpclient/httpclient.go +++ b/pkg/httpclient/httpclient.go @@ -1,5 +1,7 @@ /* -Package httpclient provides a configurable and instrumented HTTP client with common options. -It includes a trace ID header support and common logging capabilities, including the ability to dump the redacted request and response messages. +Package httpclient provides a configurable and instrumented HTTP client with +common options. It includes support for trace ID headers and common logging +capabilities, such as the ability to dump redacted request and response +messages. */ package httpclient diff --git a/pkg/httpretrier/httpretrier.go b/pkg/httpretrier/httpretrier.go index 4d8e06e2..d9f409bf 100644 --- a/pkg/httpretrier/httpretrier.go +++ b/pkg/httpretrier/httpretrier.go @@ -1,18 +1,21 @@ /* -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. -Any part of the returned http.Response (e.g., StatusCode) and error can be used to define the retry function (retry condition). -The default behavior is to retry only in case of an error. +Any part of the returned http.Response (e.g., StatusCode) and error can be used +to define the retry function (retry condition). The default behavior is to retry +only in case of an error. -This package also offers ready-made retry functions that can be used for most cases: +This package also offers ready-made retry functions that can be used for most +cases: -- RetryIfForWriteRequests -- RetryIfForReadRequests + - RetryIfForWriteRequests + - RetryIfForReadRequests -Additionally, it allows you to set the maximum number of retries, -the delay after the first failed attempt, -the time multiplication factor to determine the successive delay value, -and the jitter used to introduce randomness and avoid request collisions. +Additionally, it allows you to set the maximum number of retries, the delay +after the first failed attempt, the time multiplication factor to determine the +successive delay value, and the jitter used to introduce randomness and avoid +request collisions. */ package httpretrier diff --git a/pkg/httpreverseproxy/httpreverseproxy.go b/pkg/httpreverseproxy/httpreverseproxy.go index 9d3098cc..3a08e78d 100644 --- a/pkg/httpreverseproxy/httpreverseproxy.go +++ b/pkg/httpreverseproxy/httpreverseproxy.go @@ -1,5 +1,7 @@ /* -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. -It wraps the standard net/http/httputil ReverseProxy (or equivalent) with common functionalities, including logging and error handling. +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. It wraps the standard net/http/httputil ReverseProxy (or equivalent) +with common functionalities, including logging and error handling. */ package httpreverseproxy diff --git a/pkg/httpserver/httpserver.go b/pkg/httpserver/httpserver.go index 5eddb50b..47139410 100644 --- a/pkg/httpserver/httpserver.go +++ b/pkg/httpserver/httpserver.go @@ -1,12 +1,14 @@ /* -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. Optional common routes are defined in the routes.go file. The routes include: - /ip: Returns the public IP address of the service instance. - /metrics: Returns Prometheus metrics (default and custom). - /ping: Pings the service to check if it is alive. - /pprof: Returns pprof profiling data for the selected profile. - - /status: Checks and returns the health status of the service, including external services or components. + - /status: Checks and returns the health status of the service, including + external services or components. For a usage example, refer to the examples/service/internal/cli/bind.go file. */ diff --git a/pkg/httputil/httputil.go b/pkg/httputil/httputil.go index 7ba4ef6d..1705bc8d 100644 --- a/pkg/httputil/httputil.go +++ b/pkg/httputil/httputil.go @@ -1,4 +1,7 @@ /* -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. The package is designed to be used in conjunction with the +net/http package in the Go standard library. It includes functions for parsing +query parameters, reading request bodies, and writing response bodies. */ package httputil diff --git a/pkg/httputil/jsendx/jsendx.go b/pkg/httputil/jsendx/jsendx.go index 8cc102e9..4911be8f 100644 --- a/pkg/httputil/jsendx/jsendx.go +++ b/pkg/httputil/jsendx/jsendx.go @@ -1,10 +1,14 @@ /* -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. -JSend is a specification that defines rules for formatting JSON responses from web servers. -This implementation extends the JSend model by adding additional fields to enrich the response with application metadata. +JSend is a specification that defines rules for formatting JSON responses from +web servers. This implementation extends the JSend model by adding additional +fields to enrich the response with application metadata. -This model is particularly suitable for REST-style applications and APIs, as it provides a standardized format for all responses, simplifying the development of API clients. +This model is particularly suitable for REST-style applications and APIs, as it +provides a standardized format for all responses, simplifying the development of +API clients. */ package jsendx diff --git a/pkg/ipify/ipify.go b/pkg/ipify/ipify.go index 4a69360b..2cd48d3e 100644 --- a/pkg/ipify/ipify.go +++ b/pkg/ipify/ipify.go @@ -1,5 +1,5 @@ /* -Package ipify allows to get the public IP address of this -service instance via the 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/). */ package ipify diff --git a/pkg/jwt/jwt.go b/pkg/jwt/jwt.go index 76da948a..6ea34a9a 100644 --- a/pkg/jwt/jwt.go +++ b/pkg/jwt/jwt.go @@ -1,5 +1,10 @@ /* -Package jwt provides simple wrapper functions to manage basic JWT Auth with username/password credentials. +Package jwt provides simple wrapper functions for managing basic JWT +Authentication with username/password credentials. + +The package is designed to be used in conjunction with the net/http package in +the Go standard library. It includes functions for handling login, renewal, and +authorization of JWT tokens. */ package jwt diff --git a/pkg/kafka/kafka.go b/pkg/kafka/kafka.go index 06694de2..69d4196a 100644 --- a/pkg/kafka/kafka.go +++ b/pkg/kafka/kafka.go @@ -1,5 +1,12 @@ /* -Package kafka provides a simple high-level API for producing and consuming Apache Kafka messages. -It abstracts away the complexities of the Kafka protocol and provides a simplified interface for working with Kafka topics. +Package kafka provides a simple high-level API for producing and consuming +Apache Kafka messages. + +Based on github.com/segmentio/kafka-go, it abstracts away the complexities of +the Kafka protocol and provides a simplified interface for working with Kafka +topics. + +It allows to specify custom message encoding and decoding functions, including +serialization and encryption. */ package kafka diff --git a/pkg/kafkacgo/kafkacgo.go b/pkg/kafkacgo/kafkacgo.go index 2084b899..67862ce5 100644 --- a/pkg/kafkacgo/kafkacgo.go +++ b/pkg/kafkacgo/kafkacgo.go @@ -1,8 +1,16 @@ /* -Package kafkacgo provides a simple high-level API for producing and consuming Apache Kafka messages. -It abstracts away the complexities of the Kafka protocol and provides a simplified interface for working with Kafka topics. +Package kafkacgo provides a simple high-level API for producing and consuming +Apache Kafka messages. -IMPORTANT: This package depends on a C implementation, CGO must be enabled to use this package. -For a non-CGO implementation see the "kafka" package. +Based on github.com/confluentinc/confluent-kafka-go/kafka, it abstracts away the +complexities of the Kafka protocol and provides a simplified interface for +working with Kafka topics. + +It allows to specify custom message encoding and decoding functions, including +serialization and encryption. + +NOTE: This package depends on a C implementation, CGO must be enabled to use +this package. For a non-CGO implementation see the +github.com/Vonage/gosrvlib/pkg/kafka package. */ package kafkacgo diff --git a/pkg/logging/logging.go b/pkg/logging/logging.go index 87496268..c63ac322 100644 --- a/pkg/logging/logging.go +++ b/pkg/logging/logging.go @@ -1,10 +1,26 @@ /* -Package logging implements a structured-log model with common functionalities and utility functions. -The log messages are augmented with additional fields to enrich the response with application metadata. -The standard syslog levels are automatically mapped to the corresponding zap log levels. - -This is a Zap-based custom implementation of the configuration model described in the following article: - - Nicola Asuni, 2014-08-11, "Software Logging Format", https://technick.net/guides/software/software_logging_format/ +Package logging implements a structured-log model with common functionalities +and utility functions. + +The log messages are augmented by default with additional fields to enrich the +response with application metadata. The standard syslog levels are automatically +mapped to the corresponding zap log levels. + +It includes the following features: + - Default logger configuration with program name, version, and release. + - Custom logger configuration with additional fields. + - Context-based logging with component and method tags. + - Log level function hook for incrementing log metrics. + - Log sync function to flush the logger and ignore the error. + - Log close function to close an object and log an error in case of failure. + +The package is designed to be used in conjunction with the go.uber.org/zap +package. + +This is a custom implementation of the configuration model described in the +following article: + - Nicola Asuni, 2014-08-11, "Software Logging Format", + https://technick.net/guides/software/software_logging_format/ */ package logging diff --git a/pkg/maputil/maputil.go b/pkg/maputil/maputil.go index ccfecd7f..0c89d8e7 100644 --- a/pkg/maputil/maputil.go +++ b/pkg/maputil/maputil.go @@ -1,5 +1,7 @@ /* -Package maputil provides a collection of map utility functions. +Package maputil provides a collection of utility functions for Go maps. + +The functions in this package are generic and can be used with any type of map. */ package maputil @@ -31,7 +33,7 @@ func Map[M ~map[K]V, K, J comparable, V, U any](m M, f func(K, V) (J, U)) map[J] } // Reduce applies the reducing function f -// to each element of the input map m, and returns the value of the last call to f. +// to each element of the input map m and returns the value of the last call to f. // The first parameter of the reducing function f is initialized with init. func Reduce[M ~map[K]V, K comparable, V, U any](m M, init U, f func(K, V, U) U) U { r := init @@ -43,7 +45,7 @@ func Reduce[M ~map[K]V, K comparable, V, U any](m M, init U, f func(K, V, U) U) return r } -// Invert returns a new map were keys and values are swapped. +// Invert returns a new map where keys and values are swapped. func Invert[M ~map[K]V, K, V comparable](m M) map[V]K { r := make(map[V]K, len(m)) diff --git a/pkg/metrics/metrics.go b/pkg/metrics/metrics.go index bde78ede..56294e63 100644 --- a/pkg/metrics/metrics.go +++ b/pkg/metrics/metrics.go @@ -1,5 +1,10 @@ /* -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. + +See also: + - github.com/Vonage/gosrvlib/pkg/metrics/statsd + - github.com/Vonage/gosrvlib/pkg/metrics/prometheus */ package metrics diff --git a/pkg/metrics/prometheus/prometheus.go b/pkg/metrics/prometheus/prometheus.go index 95d92963..dbac7289 100644 --- a/pkg/metrics/prometheus/prometheus.go +++ b/pkg/metrics/prometheus/prometheus.go @@ -1,7 +1,14 @@ /* Package prometheus implements the metrics interface for Prometheus. -Prometheus is an open-source monitoring and alerting system. -It provides a platform for collecting, querying, and visualizing metrics from various sources in real-time. +Prometheus is an open-source monitoring and alerting system that provides a +platform for collecting, querying, and visualizing metrics from various sources +in real-time. + +This package is based on github.com/prometheus/client_golang/prometheus and +provides default metrics for the following components: + - HTTP Server + - HTTP Client + - SQL Database */ package prometheus diff --git a/pkg/metrics/statsd/statsd.go b/pkg/metrics/statsd/statsd.go index f7814f47..8810f7fa 100644 --- a/pkg/metrics/statsd/statsd.go +++ b/pkg/metrics/statsd/statsd.go @@ -1,7 +1,10 @@ /* Package statsd implements the metrics interface for StatsD. -The metrics (counters and timers) are actively sent over UDP or TCP to a central StatsD server. -StatsD is a network daemon that listens for statistics and aggregates them to one or more pluggable backend services (e.g., Graphite). +The metrics (counters and timers) are actively sent over UDP or TCP to a central +StatsD server. StatsD is a network daemon that listens for statistics and +aggregates them to one or more pluggable backend services (e.g., Graphite). + +This package is based on github.com/tecnickcom/statsd. */ package statsd diff --git a/pkg/mysqllock/mysqllock.go b/pkg/mysqllock/mysqllock.go index 26903c56..54eb5990 100644 --- a/pkg/mysqllock/mysqllock.go +++ b/pkg/mysqllock/mysqllock.go @@ -1,8 +1,10 @@ /* -Package mysqllock provides a distributed locking mechanism leveraging MySQL internal functions. +Package mysqllock provides a distributed locking mechanism that leverages +MySQL's internal functions. -This package allows acquiring and releasing locks using MySQL's GET_LOCK and RELEASE_LOCK functions. -It provides a MySQLLock struct that represents a locker and has methods for acquiring and releasing locks. +This package allows you to acquire and release locks using MySQL's GET_LOCK and +RELEASE_LOCK functions. It provides a MySQLLock struct that represents a locker +and has methods for acquiring and releasing locks. Example usage: diff --git a/pkg/paging/paging.go b/pkg/paging/paging.go index fd0b0e37..3a1a7869 100644 --- a/pkg/paging/paging.go +++ b/pkg/paging/paging.go @@ -1,7 +1,8 @@ /* -Package paging contains utilities to handle pagination. +Package paging provides utilities to handle pagination. -The Paging struct represents the paging information and it is automatically populated by the New function. +The Paging struct represents the pagination information and is automatically +populated by the New function. */ package paging diff --git a/pkg/passwordhash/passwordhash.go b/pkg/passwordhash/passwordhash.go index c844de82..6f0becb2 100644 --- a/pkg/passwordhash/passwordhash.go +++ b/pkg/passwordhash/passwordhash.go @@ -1,11 +1,87 @@ /* -Package passwordhash provides functions to create and verify a password hash 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. + +The model implements the best advice of OWASP Password Storage Cheat +(https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) +with specific default settings (parameters) and encoding format. Is uses the +Argon2id algorithm (https://www.rfc-editor.org/info/rfc9106) as implemented in +the golang.org/x/crypto/argon2 package. + +The implementation is based on available standard cryptographic libraries, +enforcing standard settings, and the way parameters and salt are encoded +alongside the hashed password. + +Password Storage Object + + - The input password is checked for min/max length. This prevents any + computation if these requirements are not met. + + - The input password is hashed using the Argon2id algorithm with some default + parameters and a random salt. Argon2id is currently the best recommendation + from OWASP and it is a variant of Argon2 that provides a balanced approach + to resisting both side-channel (Argon2i) and GPU-based (Argon2d) attacks. + + - The hashed password is then encoded as base64 and added as a "K" field in a + JSON object, alongside the Argon2id parameters and base64 encoded salt. + + - The JSON object is then encoded as a base64 string ready for storage. + +Example: + + Password: "Test-Password-01234" + + { + "P": { < Argon2id parameters. + "A": "argon2id", < Name of the hashing algorithm (always "argon2id"). + "V": 19, < Argon2id algorithm version (0x13). + "K": 32, < Length of the returned byte-slice that can be used as a cryptographic key. + "S": 16, < Length of the random password salt. + "T": 3, < Number of passes over the memory. + "M": 65536, < Size of the memory in KiB. + "P": 16 < Number of threads used by the hashing algorithm. + }, + "S": "wQYm4bfktbHq2omIwFu+4Q==", < base64-encoded random salt of "P.S" length. + "K": "aU8hO900Odq6aKtWiWz3RW9ygn734liJaPtM6ynvkYI=" < base64-encoded Argon2id password hash. + } + +While other serialization methods are available, JSON and base64 have been +chosen for their extraordinary portability and compatibility with multiple +systems and programming languages. The proposed JSON schema is such that it can +be easily adapted to other hashing algorithms if required. + +NOTE: Custom parameters should be agreed for production following the +recommendations at: +https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-argon2-04#section-4 The +current reference implementation uses recommended and sensible values by +default. + +The JSON object is then encoded as base64 string for storage (200 bytes in this +example): + + eyJQIjp7IkEiOiJhcmdvbjJpZCIsIlYiOjE5LCJLIjozMiwiUyI6MTYsIlQiOjMsIk0iOjY1NTM2LCJQIjoxNn0sIlMiOiJ3UVltNGJma3RiSHEyb21Jd0Z1KzRRPT0iLCJLIjoiYVU4aE85MDBPZHE2YUt0V2lXejNSVzl5Z243MzRsaUphUHRNNnludmtZST0ifQo= + +Password Verification + + - The hashed password object string is retrieved from the storage and it is + decoded using base64. + + - The resulting JSON is also decoded (unmarshalled) to access the fields + values. + + - The field P.A (name of the hashing algorithm) is compared with the one in + the library to ensure we are using the correct algorithm. + + - The field P.V (algorithm version) is compared with the one in the library to + ensure we are using the correct version. -It supports "peppering" by encrypting the hashed passwords using a secret key. + - The provided live password is hashed using the same Argon2id algorithm with + the parameters extracted from the JSON. -It is based on the Argon2id algorithm (https://www.rfc-editor.org/info/rfc9106), -as recommended by the OWASP Password Storage Cheat Sheet: -https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html + - The hash of the live password is compared with the one retrieved from the + JSON P.K field. The time taken for the comparison is a function of the + length of the slices and is independent of the contents. This prevents + timing attacks. */ package passwordhash diff --git a/pkg/passwordpwned/passwordpwned.go b/pkg/passwordpwned/passwordpwned.go index 0a5b550e..bb2726f6 100644 --- a/pkg/passwordpwned/passwordpwned.go +++ b/pkg/passwordpwned/passwordpwned.go @@ -1,8 +1,12 @@ /* -Package passwordpwned allows to verify if a password was pwned -via the haveibeenpwned.com (HIBP) service API. +Package passwordpwned allows you to verify if a password has been pwned +(compromised) in a data breach. -Ref.: https://haveibeenpwned.com/API/v3#PwnedPasswords +The checks are performed by using the k-anonymity model of the HIBP service API +(https://haveibeenpwned.com/API/v3#PwnedPasswords). + +The client transmits only the first 5 characters of the SHA-1 hash of the +password to query the HIBP service API. */ package passwordpwned diff --git a/pkg/periodic/periodic.go b/pkg/periodic/periodic.go index 7f60c60f..4d919a8f 100644 --- a/pkg/periodic/periodic.go +++ b/pkg/periodic/periodic.go @@ -1,6 +1,11 @@ /* -Package periodic provides a way to execute a given function periodically at a specified interval. -It allows for the configuration of a maximum random jitter time between each function call and a timeout applied to each function call via Context. +Package periodic provides a way to execute a given function periodically at a +specified time interval. + +It allows for the configuration of a maximum random jitter time between each +function call and a timeout applied to each function call via Context. The +jitter is useful for avoiding the Thundering herd problem +(https://en.wikipedia.org/wiki/Thundering_herd_problem). */ package periodic diff --git a/pkg/profiling/profiling.go b/pkg/profiling/profiling.go index 32ce8406..d665ece4 100644 --- a/pkg/profiling/profiling.go +++ b/pkg/profiling/profiling.go @@ -1,5 +1,11 @@ /* -Package profiling provides an HTTP handler that can be registered to a router to expose pprof profiling data. +Package profiling allows accessing the pprof profiling data via the HTTP +interface of the Go program. It provides an HTTP handler that can be registered +to an HTTP router to expose pprof profiling data. + +The tool pprof provides a way to analyze the performance of Go programs. It can +be used to generate a profile of a Go program, display the profile in a web +browser, and analyze the profile data. For an example implementation, see the pkg/httpserver/config.go file. */ diff --git a/pkg/randkey/randkey.go b/pkg/randkey/randkey.go index db8533b8..5e345140 100644 --- a/pkg/randkey/randkey.go +++ b/pkg/randkey/randkey.go @@ -1,5 +1,6 @@ /* -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. */ package randkey diff --git a/pkg/random/random.go b/pkg/random/random.go index 2ace8d25..8c01c44c 100644 --- a/pkg/random/random.go +++ b/pkg/random/random.go @@ -1,5 +1,13 @@ /* -Package random contains a collection of utility functions to generate random numbers and strings. +Package random contains a collection of utility functions for generating random +numbers and strings. + +The random number generator uses the crypto/rand package as the default, but it +can be customized by using the WithReader option. + +The RandString function, which generates random strings, uses a default +character set that includes digits, uppercase and lowercase letters, and +symbols. However, it can be customized by using the WithCharByteMap option. */ package random diff --git a/pkg/redact/redact.go b/pkg/redact/redact.go index c760ddc9..dee2633e 100644 --- a/pkg/redact/redact.go +++ b/pkg/redact/redact.go @@ -1,7 +1,8 @@ /* Package redact contains utility functions to obscure sensitive data. -This is useful for logging and debugging, where sensitive data should not be exposed. +This package is useful for logging and debugging, where sensitive data should +not be exposed. */ package redact diff --git a/pkg/redis/redis.go b/pkg/redis/redis.go index fec64a0c..d0fbea00 100644 --- a/pkg/redis/redis.go +++ b/pkg/redis/redis.go @@ -1,12 +1,14 @@ /* -Package redis provides a simple and basic wrapper client for interacting with Redis, an in-memory data store. -It includes functions for setting, getting, and deleting key/value entries. -Additionally, it supports sending and receiving messages from channels. -The package also allows for custom message encoding and decoding functions. +Package redis provides a simple and basic wrapper client for interacting with +Redis (https://redis.io), an in-memory data store. -This package is based on the official go-redis library. +Based on https://github.com/redis/go-redis, it abstracts away the complexities +of the Redis protocol and provides a simplified interface. -For more information, please refer to the official Redis website: https://redis.io -And the go-redis library on GitHub: https://github.com/redis/go-redis +This package includes functions for setting, getting, and deleting key/value +entries. Additionally, it supports sending and receiving messages from channels. + +It allows to specify custom message encoding and decoding functions, including +serialization and encryption. */ package redis diff --git a/pkg/retrier/retrier.go b/pkg/retrier/retrier.go index 0b9b300b..ce40eef8 100644 --- a/pkg/retrier/retrier.go +++ b/pkg/retrier/retrier.go @@ -1,14 +1,14 @@ /* -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. The default behavior is to retry in case of any error. -This package also offers ready-made DefaultRetryIf function that can be used for most cases. - -Additionally, it allows you to set the maximum number of retries, -the delay after the first failed attempt, -the time multiplication factor to determine the successive delay value, -and the jitter used to introduce randomness and avoid request collisions. +This package provides a ready-made DefaultRetryIf function that can be used for +most cases. Additionally, it allows to set the maximum number of retries, the +delay after the first failed attempt, the time multiplication factor to +determine the successive delay value, and the jitter used to introduce +randomness and avoid request collisions. */ package retrier diff --git a/pkg/s3/s3.go b/pkg/s3/s3.go index d4659d14..88b51364 100644 --- a/pkg/s3/s3.go +++ b/pkg/s3/s3.go @@ -1,8 +1,8 @@ /* -Package s3 provides a simple client to interact with a AWS S3 bucket, including the ability to upload, download, and delete objects. +Package s3 provides a simple and basic wrapper client for interacting with an +AWS S3 bucket. It includes the ability to upload, download, and delete objects. -It is based on the official aws-sdk-go-v2 library. - -Ref.: https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3 +This package is based on github.com/aws/aws-sdk-go-v2/service/s3 and abstracts +away the complexities of the S3 protocol, providing a simplified interface. */ package s3 diff --git a/pkg/sfcache/sfcache.go b/pkg/sfcache/sfcache.go index 35da562c..6fcb71c0 100644 --- a/pkg/sfcache/sfcache.go +++ b/pkg/sfcache/sfcache.go @@ -1,7 +1,32 @@ /* -Package sfcache provides a thread-safe local single-flight cache for external lookup calls. -The cache has a maximum size and a time-to-live (TTL) for each entry. -Duplicate external calls for the same key will wait for the first call to complete and return the same value. +Package sfcache provides a simple, local, thread-safe, fixed-size, and +single-flight cache for expensive lookup calls. + +This package is designed to improve the performance of expensive, slow, or +high-frequency function calls that retrieve data associated with a unique +identifier (key). It achieves this by caching previous values, eliminating the +need for repeated expensive requests. + +The sfcache package offers a local in-memory cache with a configurable maximum +number of entries. The fixed-size nature of the cache ensures efficient memory +management and prevents excessive memory usage. Additionally, the cache is +thread-safe, allowing concurrent access without the need for external +synchronization. It efficiently handles concurrent requests by sharing results +from the first lookup, ensuring that only one request performs the expensive +call. This approach avoids unnecessary network load or resource starvation. +Duplicate calls for the same key will wait for the first call to complete and +return the same value. + +Each cache entry has a time-to-live (TTL) value, which determines its +expiration. The cache also provides methods to force the removal of a specific +entry or reset the entire cache. + +The sfcache package is ideal for any Go application that heavily relies on +expensive or slow lookups. + +Example applications that can benefit from this package include: + - github.com/Vonage/gosrvlib/pkg/awssecretcache + - github.com/Vonage/gosrvlib/pkg/dnscache */ package sfcache diff --git a/pkg/slack/slack.go b/pkg/slack/slack.go index c44c4bd3..605fcfa5 100644 --- a/pkg/slack/slack.go +++ b/pkg/slack/slack.go @@ -1,6 +1,8 @@ /* -Package slack is a basic client for the official Slack API to send messages via a Webhook. +Package slack is a basic client for the official Slack API used to send messages +via a Webhook. -Ref.: https://api.slack.com/messaging/webhooks +This package is based on https://api.slack.com/messaging/webhooks and provides a +simple interface for sending messages to a Slack channel. */ package slack diff --git a/pkg/sleuth/sleuth.go b/pkg/sleuth/sleuth.go index 5b57be52..12760bbf 100644 --- a/pkg/sleuth/sleuth.go +++ b/pkg/sleuth/sleuth.go @@ -1,7 +1,10 @@ /* -Package sleuth is a basic client for the official Sleuth.io API to register deployments, manual changes, custom incident impact, and custom metric impact. +Package sleuth provides a basic client for the official Sleuth.io API. It allows +to register deployments, manual changes, custom incident impact, and custom +metric impact. -Ref.: https://help.sleuth.io/sleuth-api +This package is based on the Sleuth API documentation available at: +https://help.sleuth.io/sleuth-api */ package sleuth diff --git a/pkg/sliceutil/sliceutil.go b/pkg/sliceutil/sliceutil.go index edeff283..894c9d08 100644 --- a/pkg/sliceutil/sliceutil.go +++ b/pkg/sliceutil/sliceutil.go @@ -1,5 +1,8 @@ /* -Package sliceutil provides a collection of slice utility functions, including descriptive statistics functions for numerical slices. +Package sliceutil provides a collection of utility functions for Go slices. + +It includes functions for filtering, mapping, and reducing slices, as well as +generating descriptive statistics for numerical slices. */ package sliceutil diff --git a/pkg/sqlconn/sqlconn.go b/pkg/sqlconn/sqlconn.go index 1d83711d..e26caeee 100644 --- a/pkg/sqlconn/sqlconn.go +++ b/pkg/sqlconn/sqlconn.go @@ -1,6 +1,8 @@ /* -Package sqlconn provides a simple way to connect to a SQL database and manage the connection. -It also provides a way to perform a health check on the connection. +Package sqlconn provides a simple way to connect to a SQL database and manage +the connection. It is based on the database/sql package and provides a way to +perform a health check on the connection. This packages also provide a way to +gracefully shutdown the connection when the application is shutting down. */ package sqlconn diff --git a/pkg/sqltransaction/sqltransaction.go b/pkg/sqltransaction/sqltransaction.go index 56209447..fa0c4fad 100644 --- a/pkg/sqltransaction/sqltransaction.go +++ b/pkg/sqltransaction/sqltransaction.go @@ -1,8 +1,11 @@ /* -Package sqltransaction provides a simple way to execute a function inside an SQL transaction. -The function to be executed is passed as an argument to the Exec function. +Package sqltransaction provides a simple way to execute a function inside an SQL +transaction. The function to be executed is passed as an argument to the Exec +function. -See also the sqlxtransaction package for the same functionality but using the jmoiron/sqlx package. +For a similar functionality using the github.com/jmoiron/sqlx package instead of +the standard database/sql one, see the +github.com/Vonage/gosrvlib/pkg/sqlxtransaction package. */ package sqltransaction diff --git a/pkg/sqlutil/sqlutil.go b/pkg/sqlutil/sqlutil.go index 358bef32..90d61515 100644 --- a/pkg/sqlutil/sqlutil.go +++ b/pkg/sqlutil/sqlutil.go @@ -1,4 +1,7 @@ -// Package sqlutil provides SQL utilities. +/* +Package sqlutil provides SQL utility functions. +It includes functions for quoting identifiers and values in SQL queries. +*/ package sqlutil import ( diff --git a/pkg/sqlxtransaction/sqlxtransaction.go b/pkg/sqlxtransaction/sqlxtransaction.go index 5b982c8c..a11261ca 100644 --- a/pkg/sqlxtransaction/sqlxtransaction.go +++ b/pkg/sqlxtransaction/sqlxtransaction.go @@ -1,8 +1,11 @@ /* -Package sqlxtransaction provides a simple way to execute a function inside an SQLX transaction. -The function to be executed is passed as an argument to the Exec function. +Package sqlxtransaction provides a simple way to execute a function inside an +SQLX transaction. The function to be executed is passed as an argument to the +Exec function. -See also the sqltransaction package for the same functionality but using the standard library sql package. +For a similar functionality using the standard database/sql package instead of +the github.com/jmoiron/sqlx one, see the +github.com/Vonage/gosrvlib/pkg/sqltransaction package. */ package sqlxtransaction diff --git a/pkg/sqs/sqs.go b/pkg/sqs/sqs.go index ae8e3590..d0810aab 100644 --- a/pkg/sqs/sqs.go +++ b/pkg/sqs/sqs.go @@ -1,10 +1,13 @@ /* -Package sqs provides a simple client for interacting with AWS SQS (Amazon Simple Queue Service), -including the ability to send, receive, and delete messages. -The package also allows for custom message encoding and decoding functions. +Package sqs provides a simple and basic wrapper client for interacting with AWS +SQS (Amazon Simple Queue Service). -This package is based on the official aws-sdk-go-v2 library. +Based on github.com/aws/aws-sdk-go-v2/service/sqs, it abstracts away the +complexities of the SQS protocol and provides a simplified interface. -Reference: https://docs.aws.amazon.com/sdk-for-go/api/service/sqs/ +This package includes functions for sending, receiving, and deleting messages. + +It allows to specify custom message encoding and decoding functions, including +serialization and encryption. */ package sqs diff --git a/pkg/stringkey/stringkey.go b/pkg/stringkey/stringkey.go index a5c6d43d..23275f36 100644 --- a/pkg/stringkey/stringkey.go +++ b/pkg/stringkey/stringkey.go @@ -1,13 +1,19 @@ /* -Package stringkey provides the ability to create a simple unique key from multiple strings. +Package stringkey provides the ability to create a simple unique hash key from +multiple strings. -This package uses the farmhash64 algorithm to create a 64 bit hash from the concatenation of input strings. -The input strings are tab-concatenated, unicode-normalized, converted to lowercase and stripped of multiple, leading and trailing spaces. +This package uses the farmhash64 algorithm to create a 64-bit hash from the +concatenation of input strings. The input strings are tab-concatenated, +unicode-normalized, converted to lowercase, and stripped of leading, trailing, +and multiple spaces. -This package only works with few small strings and it is not intended to be used for cryptographic purposes. -The total number of input bytes should be reasonably small to be compatible with a 64 bit hash. +This package is designed for working with a small number of strings and is not +intended for cryptographic purposes. The total number of input bytes should be +reasonably small to be compatible with a 64-bit hash. -According to the birthday problem, with a 64 bit hash, the hash space is 1.8x10^19 and the probability of a collision is 1% with 6.1×10^8 keys and 50% with 5.1×10^9 keys. +According to the birthday problem, with a 64-bit hash, the hash space is +1.8x10^19 and the probability of a collision is 1% with 6.1×10^8 keys and 50% +with 5.1×10^9 keys. */ package stringkey diff --git a/pkg/stringmetric/stringmetric.go b/pkg/stringmetric/stringmetric.go index 6b463f85..9dfd4a16 100644 --- a/pkg/stringmetric/stringmetric.go +++ b/pkg/stringmetric/stringmetric.go @@ -1,15 +1,17 @@ /* -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. -A string metric measures the distance ("inverse similarity") between two text strings -for approximate string matching, comparison, and fuzzy string searching. +A string metric measures the distance ("inverse similarity") between two text +strings for approximate string matching, comparison, and fuzzy string searching. */ package stringmetric -// DLDistance calculates the Damerau-Levenshtein edit distance between two strings. -// It provides the distance between two strings as the minimum number of operations required to change one string into the other. -// The operations include insertions, deletions, substitutions, and transpositions of two adjacent characters. +// DLDistance calculates the Damerau-Levenshtein edit distance between two +// strings. It provides the distance between two strings as the minimum number +// of operations required to change one string into the other. The operations +// include insertions, deletions, substitutions, and transpositions of two +// adjacent characters. // // Ref.: https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance func DLDistance(sa, sb string) int { diff --git a/pkg/testutil/testutil.go b/pkg/testutil/testutil.go index f4c20b2d..51642395 100644 --- a/pkg/testutil/testutil.go +++ b/pkg/testutil/testutil.go @@ -1,6 +1,9 @@ /* Package testutil provides common testing utility functions. -The provided functions are intended to simplify the process of setting up tests and to provide a consistent way to do so across the codebase. +The functions provided by this package are intended to simplify the process of +setting up tests and to provide a consistent way to do so across the codebase. + +These functions are intended for use in tests only. */ package testutil diff --git a/pkg/threadsafe/threadsafe.go b/pkg/threadsafe/threadsafe.go index a6b81e5d..b3f8c434 100644 --- a/pkg/threadsafe/threadsafe.go +++ b/pkg/threadsafe/threadsafe.go @@ -1,7 +1,9 @@ /* -Package threadsafe provides an interface for thread-safe functions that can be safely used between multiple goroutines. +Package threadsafe provides an interface for thread-safe functions that can be +safely used across multiple goroutines. -See the tsmap and tsslice packages for examples of how to use this interface. +See the examples in the github.com/Vonage/gosrvlib/pkg/tsmap and +github.com/Vonage/gosrvlib/pkg/tsslice packages for usage of this interface. */ package threadsafe diff --git a/pkg/threadsafe/tsmap/tsmap.go b/pkg/threadsafe/tsmap/tsmap.go index 9d8c7ff0..06e3d615 100644 --- a/pkg/threadsafe/tsmap/tsmap.go +++ b/pkg/threadsafe/tsmap/tsmap.go @@ -1,7 +1,11 @@ /* -Package tsmap provides a collection of generic thread-safe 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. -The provided functions are intended to simplify the process of working with maps in a thread-safe manner. +The provided functions are intended to simplify the process of working with maps +in a thread-safe manner. + +See also: github.com/Vonage/gosrvlib/pkg/threadsafe */ package tsmap diff --git a/pkg/threadsafe/tsslice/tsslice.go b/pkg/threadsafe/tsslice/tsslice.go index 7b489910..0b570062 100644 --- a/pkg/threadsafe/tsslice/tsslice.go +++ b/pkg/threadsafe/tsslice/tsslice.go @@ -1,7 +1,11 @@ /* -Package tsslice provides a collection of generic thread-safe slice utility functions that can be safely used between multiple goroutines. +Package tsslice provides a collection of generic thread-safe Go slice utility +functions that can be safely used across multiple goroutines. -The provided functions are intended to simplify the process of working with slices in a thread-safe manner. +The provided functions are intended to simplify the process of working with +slices in a thread-safe manner. + +See also: github.com/Vonage/gosrvlib/pkg/threadsafe */ package tsslice diff --git a/pkg/timeutil/timeutil.go b/pkg/timeutil/timeutil.go index abbefeca..0f02df88 100644 --- a/pkg/timeutil/timeutil.go +++ b/pkg/timeutil/timeutil.go @@ -1,6 +1,8 @@ /* -Package timeutil adds utility functions to the standard time library. +Package timeutil provides utility functions for working with time-related +operations. -The package provides a set of functions to work with time.Duration in human readable format in JSON. +This package offers a collection of functions that facilitate working with +time.Duration in a human-readable format when dealing with JSON. */ package timeutil diff --git a/pkg/traceid/traceid.go b/pkg/traceid/traceid.go index f1932e23..911d3ba4 100644 --- a/pkg/traceid/traceid.go +++ b/pkg/traceid/traceid.go @@ -1,13 +1,17 @@ /* -Package traceid allows to store and retrieve 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. -It provides functions to set and retrieve the trace ID from both the context and the HTTP request headers. +It provides functions to set and retrieve the trace ID from both the Context and +the HTTP request headers. -The trace ID is typically used in distributed systems to track requests as they propagate through different services. -It can be used for debugging, performance monitoring, and troubleshooting purposes. +The Trace ID is typically used in distributed systems to track requests as they +propagate through different services. It can be used for debugging, performance +monitoring, and troubleshooting purposes. -The trace ID is expected to be a string that follows the regex pattern "^[0-9A-Za-z\-\_\.]{1,64}$". -If the trace ID does not match this pattern, the default value is used instead. +The Trace ID is expected to be a string that follows the regex pattern +"^[0-9A-Za-z\-\_\.]{1,64}$". If the Trace ID does not match this pattern, the +default value is used instead. */ package traceid diff --git a/pkg/typeutil/typeutil.go b/pkg/typeutil/typeutil.go index 692bda30..5d3b87e2 100644 --- a/pkg/typeutil/typeutil.go +++ b/pkg/typeutil/typeutil.go @@ -1,7 +1,9 @@ /* -Package typeutil contains a collection of type-related utility functions. +Package typeutil contains a collection of type-related generic utility +functions. -This package provides a set of utility functions and definitions to work with generic types in Go. +This package provides a set of utility functions and definitions for working +with generic types in Go. */ package typeutil diff --git a/pkg/uid/uid.go b/pkg/uid/uid.go index 6e485418..46cbb1cd 100644 --- a/pkg/uid/uid.go +++ b/pkg/uid/uid.go @@ -1,5 +1,6 @@ /* -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. Deprecated: Use github.com/Vonage/gosrvlib/pkg/uidc instead. */ diff --git a/pkg/uidc/uidc.go b/pkg/uidc/uidc.go index 3b50b83c..b8fcca1f 100644 --- a/pkg/uidc/uidc.go +++ b/pkg/uidc/uidc.go @@ -1,7 +1,13 @@ /* -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. -It provides functions to generate 64 and 128 bit random identifiers in base-36 string format. +It offers functions to generate 64-bit and 128-bit random identifiers in base-36 +string format. + +The generated IDs are not intended for cryptographic or security-related +purposes. Instead, they serve as simple unique identifiers for various use +cases. */ package uidc diff --git a/pkg/validator/validator.go b/pkg/validator/validator.go index 0f88516c..729af3bc 100644 --- a/pkg/validator/validator.go +++ b/pkg/validator/validator.go @@ -1,7 +1,9 @@ /* -Package validator provides a simple and extensible fields 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. -It wraps the package https://github.com/go-playground/validator and includes new custom validation rules and a simpler translation mechanism for errors. +It wraps the https://github.com/go-playground/validator package and includes new +custom validation rules and a simpler error translation mechanism. */ package validator