stdlib

README

Stdlib

This is a collection of standard library modules for go i use in my projects. The package offers a set of modules that are useful in most projects such as logging,tracing,pooling,caching,HTTP Request,etc.

Modules

• Cache
• HTTP Client
• SQL
• Pool

Usage

Importing

in code

import "github.com/karim-w/stdlib"

and

go get github.com/karim-w/stdlib

Cache

Caching tools are provided to make it easier to use caching in your projects. The package provides two types of caching, in memory and redis. The package uses the go-cache package for in memory caching and the go-redis package for redis caching.

Redis Cache

uses the go-redis package

cache, err := InitRedisCache("redis://:@localhost:6379/0")
if err != nil {
	t.Error(err)
}
err = cache.SetCtx(context.TODO(),"key",map[string]interface{}{
	"value":8,
})

In Memory Cache

uses the go-cache package

cache, err := InitInMemoryCache(
		time.Minute,
		time.Minute*2,
	)
if err != nil {
	t.Error(err)
}
err = cache.SetCtx(context.TODO(),"key",map[string]interface{}{
	"value":8,
})

Extentedable via

Logger

use the ZapLogger or any other logger that implements the Logger interface

var logger *zap.Logger
newCache := cache.WithLogger(logger)

Tracer

currently only support the applicationinsights tracer loacted at appinsights

var tracer *tracer.AppInsightsCore
newCache := cache.WithTracer(tracer)

HTTP Client

The package provides a wrapper for the http package to make it easier to use. The package provides a client that can be used to make HTTP requests. The package also provides a middleware that can be used to add tracing and logging to the requests.

Initializing

Plain client

var logger *zap.Logger
client := stdlib.ClientProvider()

Note: This function WILL panic if it fails to initialize a logger

Traceable client

var logger *zap.Logger
var tracer *tracer.AppInsightsCore
client := stdlib.TracedClientProvider(
	tracer,
	logger,
)

Client Options

type ClientOptions struct {
	Authorization string             //Authorization header
	ContentType   string             //Content-Type header
	Query         string             //Query string to append to the url
	Headers       *map[string]string //Headers to add to the request
	Timeout       *time.Time         //Timeout for the request
}

Usage

The client provides 5 Main Methods to make requests which are GET , POST , PUT , DELETE , PATCH. Each method takes a context, url, options, body and response. The response MUST be a pointer to the response type. GET And Del do not take a body in the request.

GET

Make a GET request

Response := interface{}		//any type
code,err := client.Get(
	context.TODO(),
	"http://localhost:8080",
	&stdlib.ClientOptions{},
	&Response,
)

Note: MUST pass a pointer to the response

POST

Make a POST request

Body := interface{}			//any type
Response := interface{}		//any type
code,err := client.Post(
	context.TODO(),
	"http://localhost:8080",
	&stdlib.ClientOptions{},
	Body,
	&Response,
)

Note: MUST pass a pointer to the response

PUT

Make a PUT request

Body := interface{}			//any type
Response := interface{}		//any type
code,err := client.Put(
	context.TODO(),
	"http://localhost:8080",
	&stdlib.ClientOptions{},
	Body,
	&Response,
)

Note: MUST pass a pointer to the response

PATCH

Make a PATCH request

Body := interface{}			//any type
Response := interface{}		//any type
code,err := client.Patch(
	context.TODO(),
	"http://localhost:8080",
	&stdlib.ClientOptions{},
	Body,
	&Response,
)

Note: MUST pass a pointer to the response

DELETE

Make a DELETE request

Response := interface{}		//any type
code,err := client.Del(
	context.TODO(),
	"http://localhost:8080",
	&stdlib.ClientOptions{},
	&Response,
)

Note: MUST pass a pointer to the response

Extentedable via

Authorization

client.SetAuthHandler(authProvider)

Auth provider must implement the AuthProvider interface

type AuthProvider interface {
	GetAuthHeader() string
}

SQL

The package provides a wrapper for the sql package to make it easier to use. The package provides a client that can be used to make SQL requests. The package also provides a middleware that can be used to add tracing and logging to the requests.

Initializing

Only supports Postgres, planning to add more

Will not support MSSQL

db := stdlib.NativeDatabaseProvider(
	databaseDriver,
	databaseConnectionString,
)

for tracing and logging use the TracedNativeDBWrapper function

db := stdlib.TracedNativeDBWrapper(
	databaseDriver,
	databaseConnectionString,
	tracer,
	dbName,
)
dbwithlogger := db.WithLogger(logger)

WARNING: Both functions will panic if they fail to initialize a logger

Usage

The client provides 3 Main Methods to make requests which are Query , Exec , QueryRow. Each with a variant for context they all take in query, args.

QueryRow

Make a Query request that returns a single row

var res int
row := db.Query(
	"SELECT COUNT(*) FROM table",
	[]interface{}{}...,
)
err:=row.Scan(&res)

QueryRowContext

Make a Query request with context that returns a single row

var res int
row := db.QueryContext(
	context.TODO(),
	"SELECT COUNT(*) FROM table",
	[]interface{}{}...,
)
err:=row.Scan(&res)

Exec

Execute a query that does not return a result rather the number of rows affected

res,err := db.Exec(
	"INSERT INTO table VALUES($1,$2)",
	[]interface{}{}...,
)

ExecContext

Execute a query that does not return a result rather the number of rows affected with context

res,err := db.ExecContext(
	context.TODO(),
	"INSERT INTO table VALUES($1,$2)",
	[]interface{}{}...,
)

QueryRow

Make a Query request that returns multiple rows

res := []int{}
rows,err := db.Query(
	"SELECT COUNT(*) FROM table",
	[]interface{}{}...,
)
for rows.Next(){
	var i int
	err:=rows.Scan(&i)
	if err!=nil{
		return err
	}
	res = append(res,i)
}

QueryRowContext

Make a Query request with context that returns multiple rows

res := []int{}
rows,err := db.QueryContext(
	context.TODO(),
	"SELECT COUNT(*) FROM table",
	[]interface{}{}...,
)
for rows.Next(){
	var i int
	err:=rows.Scan(&i)
	if err!=nil{
		return err
	}
	res = append(res,i)
}

Begin

Begin starts and returns a new transaction Object

tx,err := db.Begin()

BeginTx

Begin starts and returns a new transaction Object

tx,err := db.BeginTx(context.TODO(),opts) //opts is a *sql.TxOptions

Extentedable via

Logger

newDb := db.withLogger(logger) //*zap.Logger

Pooler

The package provides Pooling utility for any type of object. The package rotates the objects in the pool and provides a way to get the object from the pool in a round robin thread safe manner.

Initializing

type customType struct{
	//some fields
}

pool,err := stdlib.NewPooler(
	func () *customType{
		return &customType{}
	},
	&stdlib.PoolerOptions{
		PoolSize: 10,
	},
)

Usage

Get

Get an object from the pool

obj := pool.Get()

Size

Get the size of the pool

size := pool.Size()

Clear

Clear the pool

pool.Clear()

Tests

Coverage

Grid

Sunburst

Icicle

Documentation

Index

• Constants
• func EmbedNamedPositionArgs(stringObject string, args ...string) string
• func GenerateNewTraceparent(sampled bool) (string, error)
• func GenerateParentId() (string, error)
• func GenerateParentIdRaw() ([]byte, error)
• func GenerateRandomBytes(n int) ([]byte, error)
• func GenerateTraceId() (string, error)
• func GenerateTraceIdRaw() ([]byte, error)
• func ParseTraceparent(traceparent string) (string, string, string, string, error)
• func ParseTraceparentRaw(traceparent string) ([]byte, []byte, []byte, []byte, error)
• func ValidateParentIdValue(parentId []byte) error
• func ValidateTraceIdValue(traceId []byte) error
• type AuthProvider
• type Client
  • func ClientProvider() (Client, error)
• type ClientOptions
• type TracedClient
  • func TracedClientProvider(t *tracer.AppInsightsCore, l *zap.Logger) TracedClient
  • func TracedClientProviderWithName(t *tracer.AppInsightsCore, l *zap.Logger, clientName string) TracedClient

Constants

const (
	INVALID_VALUE_COUNT     = "invalid number of values"
	VERSION_INVALID_LENGTH  = "invalid version length"
	TRACEID_INVALID_LENGTH  = "invalid traceid length"
	PARENTID_INVALID_LENGTH = "invalid parentid length"
	FLAG_INVALID_LENGTH     = "invalid flag length"
	TRACEID_IS_ZERO         = "error traceid value is zero"
	PARENTID_IS_ZERO        = "error parentid value is zero"
)

Functions

func EmbedNamedPositionArgs

func EmbedNamedPositionArgs(stringObject string, args ...string) string

func GenerateNewTraceparent

func GenerateNewTraceparent(sampled bool) (string, error)

func GenerateParentId

func GenerateParentId() (string, error)

Counting on go compiler to inline these plsplspls :)

func GenerateParentIdRaw

func GenerateParentIdRaw() ([]byte, error)

func GenerateRandomBytes

func GenerateRandomBytes(n int) ([]byte, error)

func GenerateTraceId

func GenerateTraceId() (string, error)

func GenerateTraceIdRaw

func GenerateTraceIdRaw() ([]byte, error)

func ParseTraceparent

func ParseTraceparent(
	traceparent string,
) (string, string, string, string, error)

func ParseTraceparentRaw

func ParseTraceparentRaw(
	traceparent string,
) ([]byte, []byte, []byte, []byte, error)

func ValidateParentIdValue

func ValidateParentIdValue(parentId []byte) error

func ValidateTraceIdValue

func ValidateTraceIdValue(traceId []byte) error

Types

type AuthProvider

type AuthProvider interface {
	GetAuthHeader() string
}

type Client

type Client interface {
	Get(ctx context.Context, Url string, opt *ClientOptions, dest interface{}) (int, error)
	Put(ctx context.Context, Url string, opt *ClientOptions, body interface{}, dest interface{}) (int, error)
	Del(ctx context.Context, Url string, opt *ClientOptions, dest interface{}) (int, error)
	Post(ctx context.Context, Url string, opt *ClientOptions, body interface{}, dest interface{}) (int, error)
	Patch(ctx context.Context, Url string, opt *ClientOptions, body interface{}, dest interface{}) (int, error)
	Invoke(ctx context.Context, method string, url string, opt *ClientOptions, body interface{}, dest interface{}) (int, error)
	// doRequest(ctx context.Context, opt *ClientOptions, body interface{}, dest interface{}) (int, error)
	SetAuthHandler(provider AuthProvider)
	WithLogger(l *zap.Logger) Client
	WithTracer(t *appinsightstrace.AppInsightsCore) Client
}

func ClientProvider

func ClientProvider() (Client, error)

ClientProvider returns a new instance of Client This is a constructor function params:

• none

returns:

• Client
• error

type ClientOptions

type ClientOptions struct {
	Authorization string             `json:"authorization"`
	ContentType   string             `json:"content_type"`
	Query         string             `json:"query"`
	Headers       *map[string]string `json:"headers"`
	Timeout       *time.Time         `json:"timeout"`
	RequestType   string             `json:"request_type"`

	PositionalArgs []string
	// contains filtered or unexported fields
}

ClientOptions is a struct that contains the options for the http client Parameters:

	Authorization: The authorization header
	ContentType: The content type of the request
	Query: The query string
	Headers: The headers to be sent with the request
	Timeout: The timeout for the request
	RequestType: The type of request to be made
  PositionalArgs: The positional arguments to be sent with the request

type TracedClient

type TracedClient interface {
	Get(ctx context.Context, Url string, opt *ClientOptions, dest interface{}) (int, error)
	Put(ctx context.Context, Url string, opt *ClientOptions, body interface{}, dest interface{}) (int, error)
	Del(ctx context.Context, Url string, opt *ClientOptions, dest interface{}) (int, error)
	Post(ctx context.Context, Url string, opt *ClientOptions, body interface{}, dest interface{}) (int, error)
	Patch(ctx context.Context, Url string, opt *ClientOptions, body interface{}, dest interface{}) (int, error)
	Invoke(ctx context.Context, method string, url string, opt *ClientOptions, body interface{}, dest interface{}) (int, error)
	// doRequest(ctx context.Context, opt *ClientOptions, body interface{}, dest interface{}) (int, error)
	SetAuthHandler(provider AuthProvider)
	WithTransport(transport http.Transport) TracedClient
	WithStandardTransport() TracedClient
	WithClientName(clientName string) TracedClient
	Close()
}

func TracedClientProvider

func TracedClientProvider(
	t *tracer.AppInsightsCore,
	l *zap.Logger,
) TracedClient

TracedClientProvider returns a new instance of the TracedClient Params:

• t: The tracer to be used check the tracer package for more details at https://github.com/BetaLixT/appInsightsTrace
• l: The zap logger to be used

Returns:

• TracedClient: The TracedClient instance

func TracedClientProviderWithName

func TracedClientProviderWithName(
	t *tracer.AppInsightsCore,
	l *zap.Logger,
	clientName string,
) TracedClient

TracedClientProviderWithName returns a new instance of the TracedClient Params:

• t: The tracer to be used check the tracer package for more details at
• l: The zap logger to be used
• clientName: The name of the client

Returns:

• TracedClient: The TracedClient instance