gkit

README

Gkit

Template for REST/GRPC API server made with Golang.

Features:

• The log uses logrus
• Load middleware cross-domain, add header
• Graceful stop
• Close connection to DB before stop
• Response template error/success/success with pagination

Installation

To install gkit package, you need to install Go.

1. You first need Go installed then you can use the below Go command to install gkit.

go get -u github.com/haoletesuji/gkit

1. Import it in your code:

import "github.com/haoletesuji/gkit"

Quick start

Starting HTTP server

The example how to use gkit with to start REST api in example folder.

package main

import (
	"example/wire"
	"log"
)

func main() {
	server, err := wire.InitializeServer("gkit_example")
	if err != nil {
		log.Fatal(err)
	}
	server.Serve()
}

# run main.go and visit 0.0.0.0:3000/api/health on browser
$ go run main.go

Pre defination response template:

• Error response: GET /api/error

type ErrResponse struct {
	Success bool   `json:"success" example:"false"`
	Error   string `json:"error"`
}

{
  "success": false,
  "error": "response error"
}

• Successfull response: GET /api/success

type SuccessResponse[T any] struct {
	Success bool `json:"success" example:"true"`
	Data    T    `json:"data"`
}

{
  "success": true,
  "data": [
    {
      "uid": "1",
      "name": "John",
      "profile_image": "https://google.com/image/1"
    }
  ]
}

• Successfull with pagination: GET /api/success_paging

type Pagination struct {
	Total int64 `json:"total"`
	Limit int64 `json:"limit"`
}

type SuccessPagingResponse[T any] struct {
	Success    bool       `json:"success" example:"true"`
	Data       T          `json:"data"`
	Pagination Pagination `json:"pagination"`
}

{
  "success": true,
  "data": [
    {
      "uid": "1",
      "name": "John",
      "profile_image": "https://google.com/image/1"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10
  }
}

Starting GRPC server

The example how to use gkit with to start grpc server in example folder.

# run main.go
$ go run main.go

Then you will see the following logging

INFO[0000] grpc server listening on   0.0.0.0:50001      type=grpc

Using Postman to invoke functions

Documentation

Index

• Variables
• func CheckPasswordHash(password, hash string) bool
• func ConstructKey(prefix, key string) string
• func CorsMiddleware() gin.HandlerFunc
• func ExtractToken(r *http.Request) string
• func ExtractTokenFromHeader(r *http.Request) string
• func GetEnv(key, fallback string) string
• func GetPageNumber(page string) int
• func GetServerAddrs(addrs string) []string
• func HashPassword(password string) (string, error)
• func InitLogger(mode string)
• func InitializeGrpcClient(svcHost string) (*grpc.ClientConn, error)
• func InitializeGrpcServer(logger GrpcLogger) *grpc.Server
• func IsValidEmail(email string) bool
• func Join(strs ...string) string
• func LogTraceUnary() grpc.UnaryServerInterceptor
• func LoggingMiddleware(logger HttpLogger) gin.HandlerFunc
• func MaxAllowed(n int64) gin.HandlerFunc
• func NewGrpcEndpoint(conn *grpc.ClientConn, serviceID, serviceName, method string, ...) endpoint.Endpoint
• func ParseTimeYMD(value string) *time.Time
• func ResponseError(c *gin.Context, httpCode int, err error)
• func StringToStringValue(value *string) *wrapperspb.StringValue
• func StringValueToString(value *wrapperspb.StringValue) *string
• func TimeToYMDStringValue(t *time.Time) *wrapperspb.StringValue
• func TokenAuthMiddleware(secret string) gin.HandlerFunc
• func TokenValid(tokenString string, secret string) error
• func VerifyToken(tokenString string, secret string) (*jwt.Token, error)
• type AccessDetails
  • func ExtractRefreshTokenMetadata(tokenString string, secret string) (AccessDetails, error)
  • func ExtractTokenMetadata(tokenString string, secret string) (AccessDetails, error)
• type Closer
• type ErrResponse
• type GrpcLogger
  • func NewGrpcLogger() GrpcLogger
• type GrpcServer
• type HttpLogger
  • func NewHttpLogger() HttpLogger
• type HttpServer
• type IDGenerator
  • func NewIDGenerator() (IDGenerator, error)
• type Migrator
• type Pagination
• type Runner
• type Server
  • func NewServer(name string, runner Runner, closer Closer, migrator Migrator) *Server
  • func (s *Server) GracefulShutdown(ctx context.Context, done chan bool)
  • func (s *Server) Serve()
• type SuccessPagingResponse
• type SuccessResponse
• type TokenDetails
  • func CreateToken(userUuid string, atSecret, rtSecret string, atExpires, rtExpires int64) (TokenDetails, error)

Variables

var (
	ErrInvalidParam = errors.New("invalid parameter")
	ErrServer       = errors.New("server error")
	ErrUnauthorized = errors.New("unauthorized")
)

var (
	JWTAuthHeader = "Authorization"
	JaegerHeader  = "Trace-Id"
)

var (
	DefaultLimit int64 = 20
)

var (
	ServiceIdHeader string = "Service-Id"
)

Functions

func CheckPasswordHash

func CheckPasswordHash(password, hash string) bool

func ConstructKey

func ConstructKey(prefix, key string) string

func CorsMiddleware

func CorsMiddleware() gin.HandlerFunc

func ExtractToken

func ExtractToken(r *http.Request) string

func ExtractTokenFromHeader

func ExtractTokenFromHeader(r *http.Request) string

func GetEnv

func GetEnv(key, fallback string) string

func GetPageNumber

func GetPageNumber(page string) int

func GetServerAddrs

func GetServerAddrs(addrs string) []string

func HashPassword

func HashPassword(password string) (string, error)

func InitLogger

func InitLogger(mode string)

func InitializeGrpcClient

func InitializeGrpcClient(svcHost string) (*grpc.ClientConn, error)

func InitializeGrpcServer

func InitializeGrpcServer(logger GrpcLogger) *grpc.Server

func IsValidEmail

func IsValidEmail(email string) bool

func Join

func Join(strs ...string) string

func LogTraceUnary

func LogTraceUnary() grpc.UnaryServerInterceptor

LogTraceUnary logs trace id from the incoming request context

func LoggingMiddleware

func LoggingMiddleware(logger HttpLogger) gin.HandlerFunc

func MaxAllowed

func MaxAllowed(n int64) gin.HandlerFunc

func NewGrpcEndpoint

func NewGrpcEndpoint(conn *grpc.ClientConn, serviceID, serviceName, method string, grpcReply interface{}) endpoint.Endpoint

func ParseTimeYMD

func ParseTimeYMD(value string) *time.Time

func ResponseError

func ResponseError(c *gin.Context, httpCode int, err error)

func StringToStringValue

func StringToStringValue(value *string) *wrapperspb.StringValue

func StringValueToString

func StringValueToString(value *wrapperspb.StringValue) *string

func TimeToYMDStringValue

func TimeToYMDStringValue(t *time.Time) *wrapperspb.StringValue

func TokenAuthMiddleware

func TokenAuthMiddleware(secret string) gin.HandlerFunc

func TokenValid

func TokenValid(tokenString string, secret string) error

func VerifyToken

func VerifyToken(tokenString string, secret string) (*jwt.Token, error)

Types

type AccessDetails

type AccessDetails struct {
	AccessUuid string
	UserUuid   string
}

func ExtractRefreshTokenMetadata

func ExtractRefreshTokenMetadata(tokenString string, secret string) (AccessDetails, error)

func ExtractTokenMetadata

func ExtractTokenMetadata(tokenString string, secret string) (AccessDetails, error)

type Closer

type Closer interface {
	Close() error
}

type ErrResponse

type ErrResponse struct {
	Success bool   `json:"success" example:"false"`
	Error   string `json:"error"`
}

type GrpcLogger

type GrpcLogger struct {
	*log.Entry
}

func NewGrpcLogger

func NewGrpcLogger() GrpcLogger

type GrpcServer

type GrpcServer interface {
	Register()
	Run()
	GracefulShutdown()
}

type HttpLogger

type HttpLogger struct {
	*log.Entry
}

func NewHttpLogger

func NewHttpLogger() HttpLogger

type HttpServer

type HttpServer interface {
	RegisterRoutes()
	Run()
	GracefulShutdown(ctx context.Context) error
}

type IDGenerator

type IDGenerator interface {
	NextID() (uint64, error)
}

func NewIDGenerator

func NewIDGenerator() (IDGenerator, error)

type Migrator

type Migrator interface {
	Migrate() error
}

type Pagination

type Pagination struct {
	Total int64 `json:"total"`
	Limit int64 `json:"limit"`
}

type Runner

type Runner interface {
	Run()
	GracefulShutdown(ctx context.Context) error
}

type Server

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

func NewServer

func NewServer(name string, runner Runner, closer Closer, migrator Migrator) *Server

func (*Server) GracefulShutdown

func (s *Server) GracefulShutdown(ctx context.Context, done chan bool)

func (*Server) Serve

func (s *Server) Serve()

type SuccessPagingResponse

type SuccessPagingResponse[T any] struct {
	Success    bool       `json:"success" example:"true"`
	Data       T          `json:"data"`
	Pagination Pagination `json:"pagination"`
}

type SuccessResponse

type SuccessResponse[T any] struct {
	Success bool `json:"success" example:"true"`
	Data    T    `json:"data"`
}

type TokenDetails

type TokenDetails struct {
	AccessToken  string
	RefreshToken string
	AccessUuid   string
	RefreshUuid  string
	AtExpires    int64
	RtExpires    int64
}

func CreateToken

func CreateToken(userUuid string, atSecret, rtSecret string, atExpires, rtExpires int64) (TokenDetails, error)