hecho

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 21, 2022 License: MIT Imports: 38 Imported by: 1

README

hecho (hexa echo) contain middlewares,handlers,... for the echo.

Install

go get github.com/kamva/hecho

Middlewares

  • log: set new log handler as context log that contains:

    • request id in eac log record.
    • users data in each log record.

  • transltion: Set new translator in context that localized with users accept-languages and then fallback and default languages.

Handlers

  • error handler: handle hexa errors.

Middleware dependencies:

  • hecho.CurrentUser middleware requires
    • hecho.JWT middleware (load JWT middleware before CurrentUser).
  • hecho.HexaContext middleware requires
    • echo middleware.RequestID
    • hexa hecho.CorrelationID
    • hexa hecho.CurrentUser middleware.
  • hecho.SetContextLogger middleware requires
    • hexa hexa.HexaContext
  • hecho.TracingDataFromUserContext middleware requires
    • hexa hecho.HexaContext

Todo:

  • Map echo errors (see errors list in echo.go:263) to hexa error with translation.
  • Tests
  • Add badges to readme.
  • CI

Documentation

Index

Constants

View Source 
const (

	// ContextKeyHexaRequestID uses as key in context to store request id to use in context middleware
	ContextKeyHexaRequestID = "_hexa_ctx.rid"

	// ContextKeyHexaCorrelationID uses as key in context to store correlation id to use in context middleware
	ContextKeyHexaCorrelationID = "_hexa_ctx.cid"

	// ContextKeyHexaUser is the identifier to set the hexa user as a field in the context of a request.
	ContextKeyHexaUser = "_hexa_ctx.user"
)
View Source 
const (
	AlgorithmHS256 = "HS256"
	AlgorithmHS384 = "HS384"
	AlgorithmHS512 = "HS512"

	AlgorithmRS256 = "RS256"
	AlgorithmRS384 = "RS384"
	AlgorithmRS512 = "RS512"

	AlgorithmES256 = "ES256"
	AlgorithmES384 = "ES384"
	AlgorithmES512 = "ES512"
)

Cryptography algorithms to sign our jwt token

View Source 
const (
	TokenLocationUnknown = iota
	TokenLocationHeader
	TokenLocationCookie
	TokenLocationSession
)
View Source 
const AuthTokenContextKey = "auth_token"
View Source 
const AuthTokenLocationContextKey = "auth_token_location"
View Source 
const JwtContextKey = "jwt"
View Source 
const TokenCookieFieldAuthToken = "hexa_auth_token"
View Source 
const TokenHeaderAuthorization = "Authorization"
View Source 
const TokenSessionFieldToken = "token"

Variables

View Source 
var (
	// HeaderCorrelationID is the http X-Correlation-ID header name.
	HeaderCorrelationID = "X-Correlation-ID"

	// DefaultCorrelationIDConfig is the default CorrelationID middleware config.
	DefaultCorrelationIDConfig = CorrelationIDConfig{
		Skipper:   middleware.DefaultSkipper,
		Generator: uuidGenerator,
	}
)
View Source 
var (
	// CurrentUserContextKey is the context key to set
	// the current user in the request context.
	CurrentUserContextKey = "user"
	SubContextKey         = "sub"
)
View Source 
var (
	// DefaultProxyConfig is the default Proxy middleware config.
	DefaultProxyConfig = ProxyConfig{
		Skipper:    middleware.DefaultSkipper,
		ContextKey: "target",
	}
)
View Source 
var DefaultRequestIDConfig = RequestIDConfig{
	Skipper:   middleware.DefaultSkipper,
	Generator: uuidGenerator,
}

DefaultRequestIDConfig is the default RequestID middleware config.

View Source 
var ErrTooManyRequests = hexa.NewError(http.StatusTooManyRequests, "lib.http.too_many_requests_error")

Functions

func AuthMiddleware 

func AuthMiddleware() echo.MiddlewareFunc

AuthMiddleware is a middleware that force user to authenticate to access to specific API. AuthMiddleware should be after the HexaContext middleware.

func AuthorizeRefreshToken 

func AuthorizeRefreshToken(cfg AuthorizeRefreshTokenConfig) (user hexa.User, err error)

AuthorizeRefreshToken authorize provided jwt token. it first fetch the user from token, and then provide user and claim to the authorizer.

func CSRFSkipperByAuthTokenLocation 

func CSRFSkipperByAuthTokenLocation(ctx echo.Context) bool

CSRFSkipperByAuthTokenLocation skips if request doesn't need to csrf check. We do csrf check when user's token is in the cookie or session. and the request method is post too.

func CorrelationID 

func CorrelationID() echo.MiddlewareFunc

CorrelationID returns a X-Request-ID middleware.

func CorrelationIDWithConfig 

func CorrelationIDWithConfig(config CorrelationIDConfig) echo.MiddlewareFunc

CorrelationIDWithConfig returns a X-Correlation-ID middleware with config.

func CurrentUser 

func CurrentUser(uf UserFinderBySub) echo.MiddlewareFunc

CurrentUser is a middleware to set the user in the context. If provided jwt, so this function find user and set it as user otherwise set guest user.

func CurrentUserBySub 

func CurrentUserBySub(uf UserFinderBySub) echo.MiddlewareFunc

func CurrentUserBySubWithConfig 

func CurrentUserBySubWithConfig(cfg CurrentUserBySubConfig) echo.MiddlewareFunc

func CurrentUserWithConfig 

func CurrentUserWithConfig(cfg CurrentUserConfig) echo.MiddlewareFunc

CurrentUser is a middleware to set the user in the context. If provided jwt, so this function find user and set it as user otherwise set guest user.

func CurrentUserWithoutFetch 

func CurrentUserWithoutFetch() echo.MiddlewareFunc

CurrentUserWithoutFetch is for when you have a gateway that find the user and include it in the jwt. so you will dont need to any user finder.

func DebugMiddleware 

func DebugMiddleware(e *echo.Echo) echo.MiddlewareFunc

DebugMiddleware make a route available just in debug mode.

func ExtractAuthToken 

func ExtractAuthToken(extractors ...TokenExtractor) echo.MiddlewareFunc

ExtractAuthToken extracts the authentication token. If you want to ignore session, set nil store and empty session name.

func ExtractTokenWithConfig 

func ExtractTokenWithConfig(cfg ExtractTokenConfig) echo.MiddlewareFunc

ExtractTokenWithConfig extracts the authentication token from the cookie or Authorization header.

func GenerateToken 

func GenerateToken(u hexa.User, cfg GenerateTokenConfig) (token string, err error)

GenerateToken generate new token for the user.

func GuestMiddleware 

func GuestMiddleware() echo.MiddlewareFunc

GuestMiddleware is a middleware that force user to be guest to access to specific API. GuestMiddleware should be after the hexaContext middleware.

func HTTPErrorHandler 

func HTTPErrorHandler(l hlog.Logger, t hexa.Translator, debug bool) echo.HTTPErrorHandler

HTTPErrorHandler is the echo error handler. This function needs to the HexaContext middleware.

func HexaContext 

func HexaContext(logger hlog.Logger, translator hexa.Translator) echo.MiddlewareFunc

HexaContext set hexa context on each request.

func HexaToEchoLogger 

func HexaToEchoLogger(logger hlog.Logger, level string) echo.Logger

HexaToEchoLogger convert hexa logger to echo logger.

func IDAsSubjectGenerator 

func IDAsSubjectGenerator(user hexa.User) (string, error)

IDAsSubjectGenerator return user's id as jwt subject (sub).

func IPKeyExtractor 

func IPKeyExtractor(c echo.Context) (string, error)

func JwtClaimAuthorizer 

func JwtClaimAuthorizer(cfg JwtClaimAuthorizerConfig) echo.MiddlewareFunc

func JwtErrorHandler 

func JwtErrorHandler(err error) error

JwtErrorHandler check errors type and return relative hexa error.

func LimitBodySize 

func LimitBodySize(n int64) echo.MiddlewareFunc

LimitBodySize limits the request body size. n less than or equal to zero means unlimited. n is in bytes.

func Metrics 

func Metrics(cfg MetricsConfig) echo.MiddlewareFunc

func NewRenderer 

func NewRenderer(pattern string) echo.Renderer

NewTemplate creaets new template engine. This engine parses the template definitions from the files identified by the pattern.

func NewSingleHostReverseProxyRewriteHost 

func NewSingleHostReverseProxyRewriteHost(target *url.URL) *httputil.ReverseProxy

NewSingleHostReverseProxyRewriteHost is just like httputil.NewSingleHostReverseProxyRewriteHost, but it overwrite host of the request also.

func Proxy 

func Proxy(balancer ProxyBalancer) echo.MiddlewareFunc

Proxy returns a Proxy middleware.

Proxy middleware forwards the request to upstream server using a configured load balancing technique.

func ProxyWithConfig 

func ProxyWithConfig(config ProxyConfig) echo.MiddlewareFunc

ProxyWithConfig returns a Proxy middleware with config. See: `Proxy()`

func RateLimiter 

func RateLimiter(cfg RateLimiterConfig) echo.MiddlewareFunc

func RateLimiterByIP 

func RateLimiterByIP(rl limiter.Store) echo.MiddlewareFunc

func Recover 

func Recover() echo.MiddlewareFunc

Recover returns a middleware which recovers from panics anywhere in the chain and handles the control to the centralized HTTPErrorHandler.

func RecoverWithConfig 

func RecoverWithConfig(skipper middleware.Skipper) echo.MiddlewareFunc

RecoverWithConfig returns a Recover middleware with config. See `Recover()` document.

func RequestID 

func RequestID() echo.MiddlewareFunc

RequestID returns a X-Request-ID middleware.

func RequestIDWithConfig 

func RequestIDWithConfig(config RequestIDConfig) echo.MiddlewareFunc

RequestIDWithConfig returns a X-Request-ID middleware with config.

func ResourceAPI 

func ResourceAPI(group *echo.Group, resource any, prefix string, m ...echo.MiddlewareFunc)

ResourceAPI defines every http route which its method is satisfied by the resource.

func SetContextLogger 

func SetContextLogger(level string) echo.MiddlewareFunc

SetContextLogger set the hexa logger on each context.

func SkipIfNotProvidedHeader 

func SkipIfNotProvidedHeader(header string) middleware.Skipper

SkipIfNotProvidedHeader skip jwt middleware if jwt authorization header is not provided.

func Tracing 

func Tracing(cfg TracingConfig) echo.MiddlewareFunc

Tracing Enables distributed tracing using openTelemetry library. In echo if a handler panic error, it will catch by the `Recover` middleware, to get panic errors too, please use this middleware before the Recover middleware, so it will get the recovered errors too. You can use TracingDataFromUserContext middleware to set user_id and correlation_id too.

func TracingDataFromUserContext 

func TracingDataFromUserContext() echo.MiddlewareFunc

TracingDataFromUserContext sets some tags,... on tracing span using hexa context. This middleware should be after hexa context middleware because if needs to the hexa context.

func UserGateMiddleware 

func UserGateMiddleware(cfg GateMiddlewareConfig) echo.MiddlewareFunc

UserGateMiddleware is a middleware to specify user should be authenticated or be guest to access to specific API.

func Write 

func Write(c echo.Context, reply hexa.Reply) error

Write writes reply as response. You MUST have hexa context in your echo context to use this function to use its logger and translator.

func WriteWithOpts 

func WriteWithOpts(c echo.Context, l hlog.Logger, t hexa.Translator, reply hexa.Reply) error

WriteWithOpts writes the reply as response.

Types

type AuthorizeRefreshTokenConfig 

type AuthorizeRefreshTokenConfig struct {
	SingingMethod jwt.SigningMethod
	Key           any // for rsa this is the public key
	Token         string
	// Use Authorizer to verify that can get new token.
	Authorizer TokenAuthorizer
	UserFinder UserFinderBySub
}

AuthorizeRefreshTokenConfig use as config to refresh access token.

type CorrelationIDConfig 

type CorrelationIDConfig struct {
	// Skipper defines a function to skip middleware.
	Skipper middleware.Skipper

	// Generator defines a function to generate an ID.
	// Optional. Default value unique uuid.
	Generator func() string
}

CorrelationIDConfig defines the config for CorrelationID middleware.

type CreateResource 

type CreateResource interface {
	Create(c echo.Context) error
}

type CurrentUserBySubConfig 

type CurrentUserBySubConfig struct {
	UserFinder     UserFinderBySub
	SubContextKey  string
	UserContextKey string
}

type CurrentUserConfig 

type CurrentUserConfig struct {
	ExtendJWT      bool
	UserContextKey string
	JWTContextKey  string
	// contains filtered or unexported fields
}

CurrentUserConfig is the config to use in CurrentUser middleware.

type DeleteResource 

type DeleteResource interface {
	Delete(c echo.Context) error
}

type EchoService 

type EchoService struct {
	*echo.Echo
	Address string
}

EchoService implements hexa service.

func (*EchoService) HealthIdentifier 

func (s *EchoService) HealthIdentifier() string

func (*EchoService) HealthStatus 

func (s *EchoService) HealthStatus(ctx context.Context) hexa.HealthStatus

func (*EchoService) LivenessStatus 

func (s *EchoService) LivenessStatus(ctx context.Context) hexa.LivenessStatus

func (*EchoService) ReadinessStatus 

func (s *EchoService) ReadinessStatus(ctx context.Context) hexa.ReadinessStatus

func (*EchoService) Run 

func (s *EchoService) Run() error

func (*EchoService) Shutdown 

func (s *EchoService) Shutdown(ctx context.Context) error

type ExtractTokenConfig 

type ExtractTokenConfig struct {
	Skipper                 middleware.Skipper
	TokenContextKey         string
	TokenLocationContextKey string
	Extractors              []TokenExtractor
}

type GateMiddlewareConfig 

type GateMiddlewareConfig struct {
	MustBeGuest bool
}

type GenerateTokenConfig 

type GenerateTokenConfig struct {
	SingingMethod    jwt.SigningMethod
	Key              any // for rsa this is the private key
	SubGenerator     SubGenerator
	Claims           jwt.MapClaims
	ExpireTokenAfter time.Duration
}

GenerateTokenConfig use as config to generate new token.

type GetResource 

type GetResource interface {
	Get(c echo.Context) error
}

type JwtClaimAuthorizerConfig 

type JwtClaimAuthorizerConfig struct {
	Skipper       middleware.Skipper
	JWTContextKey string
	Authorizer    TokenAuthorizer
}

type KeyExtractor 

type KeyExtractor func(c echo.Context) (string, error)

type MetricsConfig 

type MetricsConfig struct {
	Skipper       middleware.Skipper
	MeterProvider metric.MeterProvider
}

type PatchResource 

type PatchResource interface {
	Patch(c echo.Context) error
}

type ProxyBalancer 

type ProxyBalancer interface {
	AddTarget(*ProxyTarget) bool
	RemoveTarget(string) bool
	Next(echo.Context) *ProxyTarget
}

ProxyBalancer defines an interface to implement a load balancing technique.

func NewRandomBalancer 

func NewRandomBalancer(targets []*ProxyTarget) ProxyBalancer

NewRandomBalancer returns a random proxy balancer.

func NewRoundRobinBalancer 

func NewRoundRobinBalancer(targets []*ProxyTarget) ProxyBalancer

NewRoundRobinBalancer returns a round-robin proxy balancer.

type ProxyConfig 

type ProxyConfig struct {
	// Skipper defines a function to skip middleware.
	Skipper middleware.Skipper

	// Balancer defines a load balancing technique.
	// Required.
	Balancer ProxyBalancer

	// Rewrite defines URL path rewrite rules. The values captured in asterisk can be
	// retrieved by index e.g. $1, $2 and so on.
	// Examples:
	// "/old":              "/new",
	// "/api/*":            "/$1",
	// "/js/*":             "/public/javascripts/$1",
	// "/users/*/orders/*": "/user/$1/order/$2",
	Rewrite map[string]string

	// Context key to store selected ProxyTarget into context.
	// Optional. Default value "target".
	ContextKey string

	// To customize the transport to remote.
	// Examples: If custom TLS certificates are required.
	Transport http.RoundTripper

	ReverseProxyProvider func(target *url.URL) *httputil.ReverseProxy
	// contains filtered or unexported fields
}

ProxyConfig defines the config for Proxy middleware.

type ProxyTarget 

type ProxyTarget struct {
	Name string
	URL  *url.URL
	Meta echo.Map
}

ProxyTarget defines the upstream target.

type QueryResource 

type QueryResource interface {
	Query(c echo.Context) error
}

type RateLimiterConfig 

type RateLimiterConfig struct {
	Skipper      middleware.Skipper
	RateLimiter  limiter.Store
	KeyExtractor KeyExtractor
}

type RequestIDConfig 

type RequestIDConfig struct {
	// Skipper defines a function to skip middleware.
	Skipper middleware.Skipper

	// Generator defines a function to generate an ID.
	// Optional. Default value random.String(32).
	Generator func() string
}

RequestIDConfig defines the config for RequestID middleware.

type SubGenerator 

type SubGenerator func(user hexa.User) (string, error)

type Template 

type Template struct {
	// contains filtered or unexported fields
}

Template is very simple template engine

func (*Template) Render 

func (t *Template) Render(w io.Writer, name string, data any, c echo.Context) error

type TokenAuthorizer 

type TokenAuthorizer func(claims jwt.MapClaims) error

TokenAuthorizer authorize the token.

func AuthorizeAudience 

func AuthorizeAudience(aud string) TokenAuthorizer

type TokenExtractor 

type TokenExtractor func(ctx echo.Context) (string, TokenLocation, error)

TokenExtractor extracts a token from somewhere and then returns the token and its location.

func CookieTokenExtractor 

func CookieTokenExtractor(cookieFieldName string) TokenExtractor

func HeaderAuthTokenExtractor 

func HeaderAuthTokenExtractor(headerFieldName string) TokenExtractor

func SessionTokenExtractor 

func SessionTokenExtractor(store sessions.Store, sessionName string, tokenField string) TokenExtractor

type TokenLocation 

type TokenLocation int

type TracingConfig 

type TracingConfig struct {
	Skipper middleware.Skipper

	Propagator     propagation.TextMapPropagator
	TracerProvider trace.TracerProvider
	ServerName     string
}

type UpdateResource 

type UpdateResource interface {
	Update(c echo.Context) error
}

type UserFinderBySub 

type UserFinderBySub func(ctx context.Context, sub string) (hexa.User, error)

UserFinderBySub find the user by provided sub.

Source Files

View all Source files

Directories

Path Synopsis
examples
docexample
docexample/api
docexample/doc
Package classification awesome.
 Package classification awesome.
metrics
reverseproxy
stacktrace
tracing

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.