gohaltlib

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 20, 2020 License: MIT Imports: 20 Imported by: 0

README

gohalt

Gohaltlib 👮‍♀🔧: Gohalt 3rd Party Integrations library

lint test report version license godoc

go get -u github.com/1pkg/gohalt go get -u github.com/1pkg/gohaltlib

Note: in gohalt v0.3.0 all integrations were moved to separate gohaltlib repository to make base gohalt repository dependencies footprint small.

Introduction

Gohalt is simple and convenient yet powerful and efficient throttling go library. Gohalt provides various throttlers and surronding tools to build throttling pipelines and rate limiters of any complexity adjusted to your specific needs. Gohalt provides an easy way to integrate throttling and rate limiting with your infrastructure through built in middlewares.

Features

  • Blastly fast and efficient, Gohalt has minimal performance overhead, it was design with performance as the primary goal.

  • Flexible and powerful, Gohalt supports numbers of different throttling strategies and conditions that could be easily combined and customized to match your needs link.

  • Easy to integrate, Gohalt provides separate package with numbers of built in middlewares for simple (couple lines of code) integrations with stdlib and other libraries, among which are: io, rpc/grpc, http, sql, gin, etc.

  • Metrics awareness, Gohalt could use Prometheus metrics as a conditions for throttling.

  • Queueing and delayed processing, Gohalt supports throttling queueing which means you can easily save throttled query to rabbitmq/kafka stream to process it later.

  • Durable storage, Gohalt has embedded k/v storage to provide thtottling persistence and durability.

  • Meta awareness, Gohalt provides easy way to access inner throttlers state in form of meta that can be later exposed to logging, headers, etc.

Throttlers

Throttler Definition Description
echo func NewThrottlerEcho(err error) Throttler Always throttles with the specified error back.
wait func NewThrottlerWait(duration time.Duration) Throttler Always waits for the specified duration.
square func NewThrottlerSquare(duration time.Duration, limit time.Duration, reset bool) Throttler Always waits for square growing [1, 4, 9, 16, ...] multiplier on the specified initial duration, up until the specified duration limit is reached.
If reset is set then after throttler riches the specified duration limit next multiplier value will be reseted.
jitter func NewThrottlerJitter(initial time.Duration, limit time.Duration, reset bool, jitter float64) Throttler Waits accordingly to undelying square throttler but also adds the provided jitter delta distribution on top.
Jitter value is normalized to [0.0, 1.0] range and defines which part of square delay could be randomized in percents.
Implementation uses math/rand as PRNG function and expects rand seeding by a client.
context func NewThrottlerContext() Throttler Always throttless on done context.
panic func NewThrottlerPanic() Throttler Always panics.
each func NewThrottlerEach(threshold uint64) Throttler Throttles each periodic i-th call defined by the specified threshold.
before func NewThrottlerBefore(threshold uint64) Throttler Throttles each call below the i-th call defined by the specified threshold.
after func NewThrottlerAfter(threshold uint64) Throttler Throttles each call after the i-th call defined by the specified threshold.
chance func NewThrottlerChance(threshold float64) Throttler Throttles each call with the chance p defined by the specified threshold.
Chance value is normalized to [0.0, 1.0] range.
Implementation uses math/rand as PRNG function and expects rand seeding by a client.
running func NewThrottlerRunning(threshold uint64) Throttler Throttles each call which exeeds the running quota acquired - release q defined by the specified threshold.
buffered func NewThrottlerBuffered(threshold uint64) Throttler Waits on call which exeeds the running quota acquired - release q defined by the specified threshold until the running quota is available again.
priority func NewThrottlerPriority(threshold uint64, levels uint8) Throttler Waits on call which exeeds the running quota acquired - release q defined by the specified threshold until the running quota is available again.
Running quota is not equally distributed between n levels of priority defined by the specified levels.
Use func WithPriority(ctx context.Context, priority uint8) context.Context to override context call priority, 1 by default.
timed func NewThrottlerTimed(threshold uint64, interval time.Duration, quantum time.Duration) Throttler Throttles each call which exeeds the running quota acquired - release q defined by the specified threshold in the specified interval.
Periodically each specified interval the running quota number is reseted.
If quantum is set then quantum will be used instead of interval to provide the running quota delta updates.
latency func NewThrottlerLatency(threshold time.Duration, retention time.Duration) Throttler Throttles each call after the call latency l defined by the specified threshold was exeeded once.
If retention is set then throttler state will be reseted after retention duration.
Use func WithTimestamp(ctx context.Context, ts time.Time) context.Context to specify running duration between throttler acquire and release.
percentile func NewThrottlerPercentile(threshold time.Duration, capacity uint8, percentile float64, retention time.Duration) Throttler Throttles each call after the call latency l defined by the specified threshold was exeeded once considering the specified percentile.
Percentile values are kept in bounded buffer with capacity c defined by the specified capacity.
If retention is set then throttler state will be reseted after retention duration.
Use func WithTimestamp(ctx context.Context, ts time.Time) context.Context to specify running duration between throttler acquire and release.
monitor func NewThrottlerMonitor(mnt Monitor, threshold Stats) Throttler Throttles call if any of the stats returned by provided monitor exceeds any of the stats defined by the specified threshold or if any internal error occurred.
Builtin Monitor implementations come with stats caching by default.
Use builtin NewMonitorSystem to create go system monitor instance.
metric func NewThrottlerMetric(mtc Metric) Throttler Throttles call if boolean metric defined by the specified boolean metric is reached or if any internal error occurred.
Builtin Metric implementations come with boolean metric caching by default.
Use builtin NewMetricPrometheus to create Prometheus metric instance.
enqueuer func NewThrottlerEnqueue(enq Enqueuer) Throttler Always enqueues message to the specified queue throttles only if any internal error occurred.
Use func WithMessage(ctx context.Context, message interface{}) context.Context to specify context message for enqueued message and func WithMarshaler(ctx context.Context, mrsh Marshaler) context.Context to specify context message marshaler.
Builtin Enqueuer implementations come with connection reuse and retries by default.
Use builtin func NewEnqueuerRabbit(url string, queue string, retries uint64) Enqueuer to create RabbitMQ enqueuer instance or func NewEnqueuerKafka(net string, url string, topic string, retries uint64) Enqueuer to create Kafka enqueuer instance.
adaptive func NewThrottlerAdaptive(threshold uint64, interval time.Duration, quantum time.Duration, step uint64, thr Throttler) Throttler Throttles each call which exeeds the running quota acquired - release q defined by the specified threshold in the specified interval.
Periodically each specified interval the running quota number is reseted.
If quantum is set then quantum will be used instead of interval to provide the running quota delta updates.
Provided adapted throttler adjusts the running quota of adapter throttler by changing the value by d defined by the specified step, it subtracts d^2 from the running quota if adapted throttler throttles or adds d to the running quota if it doesn't.
pattern func NewThrottlerPattern(patterns ...Pattern) Throttler Throttles if matching throttler from provided patterns throttles.
Use func WithKey(ctx context.Context, key string) context.Context to specify key for regexp pattern throttler matching.
Pattern defines a pair of regexp and related throttler.
ring func NewThrottlerRing(thrs ...Throttler) Throttler Throttles if the i-th call throttler from provided list throttle.
all func NewThrottlerAll(thrs ...Throttler) Throttler Throttles call if all provided throttlers throttle.
any func NewThrottlerAny(thrs ...Throttler) Throttler Throttles call if any of provided throttlers throttle.
not func NewThrottlerNot(thr Throttler) Throttler Throttles call if provided throttler doesn't throttle.
suppress func NewThrottlerSuppress(thr Throttler) Throttler Suppresses provided throttler to never throttle.
retry func NewThrottlerRetry(thr Throttler, retries uint64) Throttler Retries provided throttler error up until the provided retries threshold.
Internally retry uses square throttler with DefaultRetriedDuration initial duration.
cache func NewThrottlerCache(thr Throttler, cache time.Duration) Throttler Caches provided throttler calls for the provided cache duration, throttler release resulting resets cache.
Only non throttling calls are cached for the provided cache duration.

Integrations

Library Adapter
gin func NewMiddlewareGin(thr Throttler, with GinWith, on GinOn) gin.HandlerFunc
stdlib http handler func NewMiddlewareStd(h http.Handler, thr Throttler, with StdWith, on StdOn) http.Handler
echo func NewMiddlewareEcho(thr Throttler, with EchoWith, on EchoOn) echo.MiddlewareFunc
beego func NewMiddlewareBeego(thr Throttler, with BeegoWith, on BeegoOn) beego.FilterFunc
kit func NewMiddlewareKit(thr Throttler, with KitWith, on KitOn) endpoint.Middleware
mux func NewMiddlewareMux(h http.Handler, thr Throttler, with MuxWith, on MuxOn) http.Handler
httprouter func NewMiddlewareRouter(h http.Handler, thr Throttler, with RouterWith, on RouterOn) http.Handler
reveal func NewMiddlewareRevel(thr Throttler, with RevealWith, on RevealOn) revel.Filter
iris func NewMiddlewareIris(thr Throttler, with IrisWith, on IrisOn) iris.Handler
fasthttp func NewMiddlewareFast(h fasthttp.RequestHandler, thr Throttler, with FastWith, on FastOn) fasthttp.RequestHandler
stdlib rt func NewRoundTripperStd(rt http.RoundTripper, thr Throttler, with RoundTripperStdWith, on RoundTripperStdOn) http.RoundTripper
fasthttp rt func NewRoundTripperFast(rt RoundTripperFast, thr Throttler, with RoundTripperFastWith, on RoundTripperFastOn) RoundTripperFast
stdlib rpc client coded func NewRPCClientCodec(cc rpc.ClientCodec, thr Throttler, with RPCCodecWith, on RPCCodecOn) rpc.ClientCodec
stdlib rpc server coded func NewRPCServerCodec(sc rpc.ServerCodec, thr Throttler, with RPCCodecWith, on RPCCodecOn) rpc.ServerCodec
grpc client stream func NewGRPCClientStream(cs grpc.ClientStream, thr Throttler, with GRPCStreamWith, on GRPCStreamOn) grpc.ClientStream
grpc server stream func NewGrpServerStream(ss grpc.ServerStream, thr Throttler, with GRPCStreamWith, on GRPCStreamOn) grpc.ServerStream
go-micro client func NewMicroClient(thr Throttler, with MicroClientWith, on MicroOn) client.Wrapper
go-micro server func NewMicroHandler(thr Throttler, with MicroServerWith, on MicroOn) server.HandlerWrapper
stdlib net conn func NewNetConn(conn net.Conn, thr Throttler, with NetConnWith, on NetConnOn, mode NetConnMode) net.Conn
stdlib sql func NewSQLClient(cli SQLClient, thr Throttler, with SQLClientWith, on SQLClientOn) SQLClient
stdlib io reader func NewReader(r io.Reader, thr Throttler, with RWWith, on RWOn) io.Reader
stdlib io writer func NewWriter(w io.Writer, thr Throttler, with RWWith, on RWOn) io.Writer

Licence

Gohaltlib is licensed under the MIT License.
See LICENSE for the full license text.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BeegoOnAbort 

func BeegoOnAbort(bctx *beegoctx.Context, err error)

func BeegoWithIP 

func BeegoWithIP(bctx *beegoctx.Context) context.Context

func EchoOnAbort 

func EchoOnAbort(ectx echo.Context, err error) error

func EchoWithIP 

func EchoWithIP(ectx echo.Context) context.Context

func FastOnAbort 

func FastOnAbort(fctx *fasthttp.RequestCtx, err error)

func FastWithIPBackground 

func FastWithIPBackground(fctx *fasthttp.RequestCtx) context.Context

func GRPCStreamAbort 

func GRPCStreamAbort(err error) error

func GRPCStreamWithEmpty 

func GRPCStreamWithEmpty(ctx context.Context, msg interface{}) context.Context

func GinOnAbort 

func GinOnAbort(gctx *gin.Context, err error)

func GinWithIP 

func GinWithIP(gctx *gin.Context) context.Context

func IrisOnAbort 

func IrisOnAbort(ictx iris.Context, err error)

func IrisWithIP 

func IrisWithIP(ictx iris.Context) context.Context

func KitOnAbort 

func KitOnAbort(err error) (interface{}, error)

func KitWithEmpty 

func KitWithEmpty(ctx context.Context, req interface{}) context.Context

func MicroClientWithEmpty 

func MicroClientWithEmpty(ctx context.Context, req client.Request) context.Context

func MicroOnAbort 

func MicroOnAbort(err error) error

func MicroServerEmpty 

func MicroServerEmpty(ctx context.Context, req server.Request) context.Context

func MuxOnAbort 

func MuxOnAbort(w http.ResponseWriter, err error)

func MuxWithIP 

func MuxWithIP(req *http.Request) context.Context

func NetConnAbort 

func NetConnAbort(err error) error

func NetConnWithBackground 

func NetConnWithBackground() context.Context

func NewGRPCClientStream 

func NewGRPCClientStream(cs grpc.ClientStream, thr gohalt.Throttler, with GRPCStreamWith, on GRPCStreamOn) grpc.ClientStream

func NewGrpServerStream 

func NewGrpServerStream(ss grpc.ServerStream, thr gohalt.Throttler, with GRPCStreamWith, on GRPCStreamOn) grpc.ServerStream

func NewMicroClient 

func NewMicroClient(thr gohalt.Throttler, with MicroClientWith, on MicroOn) client.Wrapper

func NewMicroHandler 

func NewMicroHandler(thr gohalt.Throttler, with MicroServerWith, on MicroOn) server.HandlerWrapper

func NewMiddlewareBeego 

func NewMiddlewareBeego(thr gohalt.Throttler, with BeegoWith, on BeegoOn) beego.FilterFunc

func NewMiddlewareEcho 

func NewMiddlewareEcho(thr gohalt.Throttler, with EchoWith, on EchoOn) echo.MiddlewareFunc

func NewMiddlewareFast 

func NewMiddlewareFast(h fasthttp.RequestHandler, thr gohalt.Throttler, with FastWith, on FastOn) fasthttp.RequestHandler

func NewMiddlewareGin 

func NewMiddlewareGin(thr gohalt.Throttler, with GinWith, on GinOn) gin.HandlerFunc

func NewMiddlewareIris 

func NewMiddlewareIris(thr gohalt.Throttler, with IrisWith, on IrisOn) iris.Handler

func NewMiddlewareKit 

func NewMiddlewareKit(thr gohalt.Throttler, with KitWith, on KitOn) endpoint.Middleware

func NewMiddlewareMux 

func NewMiddlewareMux(h http.Handler, thr gohalt.Throttler, with MuxWith, on MuxOn) http.Handler

func NewMiddlewareRevel 

func NewMiddlewareRevel(thr gohalt.Throttler, with RevealWith, on RevealOn) revel.Filter

func NewMiddlewareRouter 

func NewMiddlewareRouter(h http.Handler, thr gohalt.Throttler, with RouterWith, on RouterOn) http.Handler

func NewMiddlewareStd 

func NewMiddlewareStd(h http.Handler, thr gohalt.Throttler, with StdWith, on StdOn) http.Handler

func NewNetConn 

func NewNetConn(conn net.Conn, thr gohalt.Throttler, with NetConnWith, on NetConnOn, mode NetConnMode) net.Conn

func NewRPCClientCodec 

func NewRPCClientCodec(cc rpc.ClientCodec, thr gohalt.Throttler, with RPCCodecWith, on RPCCodecOn) rpc.ClientCodec

func NewRPCServerCodec 

func NewRPCServerCodec(sc rpc.ServerCodec, thr gohalt.Throttler, with RPCCodecWith, on RPCCodecOn) rpc.ServerCodec

func NewReader 

func NewReader(r io.Reader, thr gohalt.Throttler, with RWWith, on RWOn) io.Reader

func NewRoundTripperStd 

func NewRoundTripperStd(
	rt http.RoundTripper,
	thr gohalt.Throttler,
	with RoundTripperStdWith,
	on RoundTripperStdOn,
) http.RoundTripper

func NewWriter 

func NewWriter(w io.Writer, thr gohalt.Throttler, with RWWith, on RWOn) io.Writer

func RPCCodecOnAbort 

func RPCCodecOnAbort(err error) error

func RPCCodecWithBackground 

func RPCCodecWithBackground(req *rpc.Request, resp *rpc.Response, msg interface{}) context.Context

func RWAbort 

func RWAbort(err error) error

func RWWithBackground 

func RWWithBackground() context.Context

func RevealOnAbort 

func RevealOnAbort(rc *revel.Controller, err error) revel.Result

func RevealWithIP 

func RevealWithIP(rc *revel.Controller) context.Context

func RoundTripperFastBackground 

func RoundTripperFastBackground(req *fasthttp.Request) context.Context

func RoundTripperFastOnAbort 

func RoundTripperFastOnAbort(err error) error

func RoundTripperStdOnAbort 

func RoundTripperStdOnAbort(err error) error

func RoundTripperStdWithEmpty 

func RoundTripperStdWithEmpty(req *http.Request) context.Context

func RouterOnAbort 

func RouterOnAbort(w http.ResponseWriter, err error)

func RouterWithIP 

func RouterWithIP(req *http.Request) context.Context

func SQLClientAbort 

func SQLClientAbort(err error) error

func SQLClientQuery 

func SQLClientQuery(ctx context.Context, query string, args ...interface{}) context.Context

func StdOnAbort 

func StdOnAbort(w http.ResponseWriter, err error)

func StdWithIP 

func StdWithIP(req *http.Request) context.Context

Types

type BeegoOn 

type BeegoOn func(*beegoctx.Context, error)

type BeegoWith 

type BeegoWith func(*beegoctx.Context) context.Context

type EchoOn 

type EchoOn func(echo.Context, error) error

type EchoWith 

type EchoWith func(echo.Context) context.Context

type FastOn 

type FastOn func(*fasthttp.RequestCtx, error)

type FastWith 

type FastWith func(*fasthttp.RequestCtx) context.Context

type GRPCStreamOn 

type GRPCStreamOn func(error) error

type GRPCStreamWith 

type GRPCStreamWith func(context.Context, interface{}) context.Context

type GinOn 

type GinOn func(*gin.Context, error)

type GinWith 

type GinWith func(*gin.Context) context.Context

type IrisOn 

type IrisOn func(iris.Context, error)

type IrisWith 

type IrisWith func(iris.Context) context.Context

type KitOn 

type KitOn func(error) (interface{}, error)

type KitWith 

type KitWith func(context.Context, interface{}) context.Context

type MicroClientWith 

type MicroClientWith func(context.Context, client.Request) context.Context

type MicroOn 

type MicroOn func(error) error

type MicroServerWith 

type MicroServerWith func(context.Context, server.Request) context.Context

type MuxOn 

type MuxOn StdOn

type MuxWith 

type MuxWith StdWith

type NetConnMode 

type NetConnMode int
const (
	NetConnModeRead  NetConnMode = iota
	NetConnModeWrite NetConnMode = iota
)

type NetConnOn 

type NetConnOn func(error) error

type NetConnWith 

type NetConnWith func() context.Context

type RPCCodecOn 

type RPCCodecOn func(error) error

type RPCCodecWith 

type RPCCodecWith func(*rpc.Request, *rpc.Response, interface{}) context.Context

type RWOn 

type RWOn func(error) error

type RWWith 

type RWWith func() context.Context

type RevealOn 

type RevealOn func(error) revel.Result

type RevealWith 

type RevealWith func(*revel.Controller) context.Context

type RoundTripperFast 

type RoundTripperFast interface {
	Do(req *fasthttp.Request, resp *fasthttp.Response) error
}

func NewRoundTripperFast 

func NewRoundTripperFast(
	rt RoundTripperFast,
	thr gohalt.Throttler,
	with RoundTripperFastWith,
	on RoundTripperFastOn,
) RoundTripperFast

type RoundTripperFastOn 

type RoundTripperFastOn func(error) error

type RoundTripperFastWith 

type RoundTripperFastWith func(*fasthttp.Request) context.Context

type RoundTripperStdOn 

type RoundTripperStdOn func(error) error

type RoundTripperStdWith 

type RoundTripperStdWith func(*http.Request) context.Context

type RouterOn 

type RouterOn StdOn

type RouterWith 

type RouterWith StdWith

type SQLClient 

type SQLClient interface {
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
	QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row
}

func NewSQLClient 

func NewSQLClient(cli SQLClient, thr gohalt.Throttler, with SQLClientWith, on SQLClientOn) SQLClient

type SQLClientOn 

type SQLClientOn func(error) error

type SQLClientWith 

type SQLClientWith func(context.Context, string, ...interface{}) context.Context

type StdOn 

type StdOn func(http.ResponseWriter, error)

type StdWith 

type StdWith func(*http.Request) context.Context

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.