gmicro

package module
v2.4.0 Latest Latest
Warning

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

 Go to latest Published: Jan 10, 2024 License: MIT Imports: 32 Imported by: 0

README

gmicro

Golang grpc micro library.
Microservice prototype with gRPC + http +h2c+ gRPC gateway + logger + prometheus.
Require Go version >= v1.13.
Reference project：https://github.com/dakalab/micro

supported features

Golang grpc microservice scaffolding mainly encapsulates some components of grpc,
log tracking, link tracking, traffic h2c conversion, service monitoring prometheus
and other functions,as far as possible to maintain the kiss principle, 
so that these components are pluggable of.

The framework supports 2 different methods such as http api, grpc server pb. 
The protocol called by the client can be http or grpc pb format. 
At the same time,it supports the same port, while providing 
http services (supporting http1.x protocol requests) and the processing 
capabilities of grpc server.

go version

if you use go version < 1.16,please use gmicro tag v1.3.3
else use gmicro tag v2.3.0 higher version.

installation

go get -v github.com/daheige/gmicro/v2

quick start

please see example demo

grpc-go

https://github.com/grpc/grpc-go

grpc-gateway doc

https://grpc-ecosystem.github.io/grpc-gateway/

gmicro action

https://github.com/daheige/goapp

https://github.com/daheige/gmicro-demo

Old projects can continue to use the v1 version, and new projects can start to use the v2 version. Note that the gmicro address has changed, and the v2 version is github.com/daheige/gmicro/v2

change log

options desc time
go mod update update grpc version to v1.60.1 2024-01-10
grpc nodejs tools update grpc nodejs client code generated 2024-01-10
grpc mac tools add mac grpc install shell 2024-01-10
options desc time
go mod update update grpc mod 2023-06-04
grpc metadata fix request md for RequestInterceptor 2023-06-04
add x-request-id fix request x-request-id from md 2023-06-04
options desc time
grpc tools update docs 2022-05-15
grpc dockerfile update go grpc tools 2022-05-15
options desc time
grpc gateway upgrade grpc gateway to v2.10.0 2022-05-11
grpc upgrade go grpc to v1.46.0 2022-05-11
protobuf upgrade protobuf to v1.28.0 2022-05-11
grpc dockerfile upgrade go to v1.16.15 and protoc v3.15.8 2022-05-11
options desc time
grpc gateway upgrade grpc gateway to v2.4.0 2021-06-19
grpc upgrade go grpc to v1.38.0 2021-06-19
protobuf upgrade protobuf to v1.26.0 2021-06-19

grpc tools dockerfile

https://github.com/daheige/gmicro-grpc-tools

install grpc tools

sh example/bin/grpc_tools.sh

Google APIs

# googleapis link:https://github.com/googleapis/googleapis
api/rpc link: https://github.com/googleapis/googleapis/tree/master/google

============

Project: Google APIs
URL: https://github.com/google/googleapis
Revision: 3544ab16c3342d790b00764251e348705991ea4b
License: Apache License 2.0


Imported Files
---------------

- google/api/annotations.proto
- google/api/http.proto
- google/api/httpbody.proto


Generated Files
----------------

They are generated from the .proto files by protoc-gen-go.
- google/api/annotations.pb.go
- google/api/http.pb.go

License

MIT

Documentation

Overview

Package gmicro Grpc Microservices components. Copyright 2020 daheige. All rights reserved. Use of this source code is governed by a MIT style license that can be found in the LICENSE file.

Package gmicro Grpc Microservices components.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvokeGRPCClientIP get grpc request client ip fail.
	ErrInvokeGRPCClientIP = errors.New("invoke from context failed")

	// ErrPeerAddressNil gRPC peer address is nil.
	ErrPeerAddressNil = errors.New("peer address is nil")
)
View Source 
var InterruptSignals = []os.Signal{
	syscall.SIGINT, syscall.SIGTERM, os.Interrupt, syscall.SIGHUP,
	syscall.SIGSTOP, syscall.SIGQUIT,
}

InterruptSignals interrupt signals.

Functions

func AllPattern 

func AllPattern() gRuntime.Pattern

AllPattern returns a pattern which matches any url

func DefaultHTTPHandler 

func DefaultHTTPHandler(mux *gRuntime.ServeMux) http.Handler

DefaultHTTPHandler is the default http handler which does nothing.

func GRPCHandlerFunc 

func GRPCHandlerFunc(grpcServer *grpc.Server, otherHandler http.Handler) http.Handler

GRPCHandlerFunc uses the standard library h2c to convert http requests to http2 In this way, you can co-exist with go grpc and http services, and use one port to provide both grpc services and http services. In June 2018, the golang.org/x/net/http2/h2c standard library representing the "h2c" logo was officially merged in, and since then we can use the official standard library (h2c) This standard library implements the unencrypted mode of HTTP/2, so we can use the standard library to provide both HTTP/1.1 and HTTP/2 functions on the same port The h2c.NewHandler method has been specially processed, and h2c.NewHandler will return an http.handler The main internal logic is to intercept all h2c traffic, then hijack and redirect it to the corresponding handler according to different request traffic types to process

func GetCtxValue added in v2.3.0 

func GetCtxValue(ctx context.Context, key CtxKey) interface{}

GetCtxValue returns ctx when you set key/value into ctx

func GetGRPCClientIP 

func GetGRPCClientIP(ctx context.Context) (string, error)

GetGRPCClientIP get client ip address from context

func GetIncomingMD added in v2.3.0 

func GetIncomingMD(ctx context.Context) metadata.MD

GetIncomingMD returns metadata.MD from incoming ctx get request metadata this method is mainly used at the server end to get the relevant metadata data

func GetOutgoingMD added in v2.3.0 

func GetOutgoingMD(ctx context.Context) metadata.MD

GetOutgoingMD returns metadata.MD from outgoing ctx Use this method when you pass ctx to a downstream service

func GetSliceFromMD added in v2.3.0 

func GetSliceFromMD(md metadata.MD, key CtxKey) []string

GetSliceFromMD returns []string from md

func GetStringFromMD added in v2.3.0 

func GetStringFromMD(md metadata.MD, key CtxKey) string

GetSliceFromMD returns string from md

func Md5 

func Md5(str string) string

Md5 md5 func

func RandInt64 

func RandInt64(min, max int64) int64

RandInt64 crete a num [m,n]

func RndUUID 

func RndUUID() string

RndUUID realizes unique uuid based on time ns and random number There is no duplication of uuid on a single machine If you want to generate non-duplicate uuid on a distributed architecture Just add some custom strings in front of rndStr Return format: eba1e8cd-0460-4910-49c6-44bdf3cf024d

func RndUUIDMd5 

func RndUUIDMd5() string

RndUUIDMd5 make an uuid

func SetCtxValue added in v2.3.0 

func SetCtxValue(ctx context.Context, key CtxKey, val interface{}) context.Context

SetCtxValue returns ctx when you set key/value into ctx

func Uuid added in v2.3.0 

func Uuid() string

Uuid uuid of version4 eg:eba1e8cd0460491049c644bdf3cf024d

func WithRateLimit 

func WithRateLimit(limiter Limiter) grpc.UnaryServerInterceptor

WithRateLimit rate limit

Types

type AnnotatorFunc 

type AnnotatorFunc func(context.Context, *http.Request) metadata.MD

AnnotatorFunc is the annotator function is for injecting metadata from http request into gRPC context

type CtxKey 

type CtxKey string

CtxKey ctx key type. 

const (
	// XRequestID request_id
	XRequestID CtxKey = "x-request-id"

	// GRPCClientIP grpc client_ip
	GRPCClientIP CtxKey = "client-ip"

	// RequestMethod request method
	RequestMethod CtxKey = "request_method"

	// RequestURI request uri
	RequestURI CtxKey = "request_uri"
)

func (CtxKey) String added in v2.3.0 

func (c CtxKey) String() string

String returns string

type HTTPHandlerFunc 

type HTTPHandlerFunc func(*gRuntime.ServeMux) http.Handler

HTTPHandlerFunc is the http middleware handler function.

type HandlerFromEndpoint 

type HandlerFromEndpoint func(ctx context.Context, mux *gRuntime.ServeMux,
	endpoint string, opts []grpc.DialOption) error

HandlerFromEndpoint is the callback that the caller should implement to steps to reverse-proxy the HTTP/1 requests to gRPC handlerFromEndpoint http gw endPoint automatically dials to "endpoint" and closes the connection when "ctx" gets done.

type Limiter 

type Limiter interface {
	Limit() bool
}

Limiter defines the interface to perform request rate limiting. If Limit function return true, the request will be rejected. Otherwise, the request will pass.

type Logger 

type Logger interface {
	Printf(string, ...interface{})
}

Logger is logger interface.

type LoggerFunc 

type LoggerFunc func(string, ...interface{})

LoggerFunc is a bridge between Logger and any third party logger.

func (LoggerFunc) Printf 

func (f LoggerFunc) Printf(msg string, args ...interface{})

Printf implements Logger interface.

type Option 

type Option func(s *Service)

Option is service functional option See this post about the "functional options" pattern: http://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis

func WithAnnotator 

func WithAnnotator(annotator ...AnnotatorFunc) Option

WithAnnotator returns an Option to append some annotator

func WithErrorHandler 

func WithErrorHandler(errorHandler gRuntime.ErrorHandlerFunc) Option

WithErrorHandler returns an Option to set the errorHandler

func WithGRPCDialOption 

func WithGRPCDialOption(dialOption ...grpc.DialOption) Option

WithGRPCDialOption returns an Option to append a gRPC dial option

func WithGRPCNetwork 

func WithGRPCNetwork(network string) Option

WithGRPCNetwork set gRPC start network type.

func WithGRPCServerOption 

func WithGRPCServerOption(serverOption ...grpc.ServerOption) Option

WithGRPCServerOption returns an Option to append a gRPC server option

func WithHTTPHandler 

func WithHTTPHandler(h HTTPHandlerFunc) Option

WithHTTPHandler returns an Option to set the httpHandler

func WithHTTPServer 

func WithHTTPServer(server *http.Server) Option

WithHTTPServer returns an Option to set the http server, note that the Addr and Handler will be reset in startGRPCGateway(), so you are not able to specify them

func WithHandlerFromEndpoint 

func WithHandlerFromEndpoint(reverseProxyFunc ...HandlerFromEndpoint) Option

WithHandlerFromEndpoint add handlerFromEndpoint to http gw endPoint

func WithInterruptSignal 

func WithInterruptSignal(signal os.Signal) Option

WithInterruptSignal returns an Option to append a interrupt signal

func WithLogger 

func WithLogger(logger Logger) Option

WithLogger uses the provided logger

func WithMuxOption 

func WithMuxOption(muxOption ...gRuntime.ServeMuxOption) Option

WithMuxOption returns an Option to append a mux option

func WithPreShutdownDelay 

func WithPreShutdownDelay(timeout time.Duration) Option

WithPreShutdownDelay returns an Option to set the time waiting for running goroutines to finish their jobs before the shutdown starts

func WithPrometheus 

func WithPrometheus(b bool) Option

WithPrometheus enble prometheus config.

func WithRecovery 

func WithRecovery(f func()) Option

WithRecovery service recover func.

func WithRequestAccess 

func WithRequestAccess(b bool) Option

WithRequestAccess request access log config.

func WithRouteOpt 

func WithRouteOpt(routes ...Route) Option

WithRouteOpt adds additional routes

func WithShutdownFunc 

func WithShutdownFunc(f func()) Option

WithShutdownFunc returns an Option to register a function which will be called when server shutdown

func WithShutdownTimeout 

func WithShutdownTimeout(timeout time.Duration) Option

WithShutdownTimeout returns an Option to set the timeout before the server shutdown abruptly

func WithStaticAccess 

func WithStaticAccess(b bool) Option

WithStaticAccess enable static file access

func WithStaticDir 

func WithStaticDir(dir string) Option

WithStaticDir returns an Option to set the staticDir

func WithStreamInterceptor 

func WithStreamInterceptor(streamInterceptor ...grpc.StreamServerInterceptor) Option

WithStreamInterceptor returns an Option to append some streamInterceptor

func WithUnaryInterceptor 

func WithUnaryInterceptor(unaryInterceptor ...grpc.UnaryServerInterceptor) Option

WithUnaryInterceptor returns an Option to append some unaryInterceptor

type Route 

type Route struct {
	Method  string
	Path    string
	Handler gRuntime.HandlerFunc
}

Route represents the route for mux

type Service 

type Service struct {
	GRPCServer *grpc.Server // gRPC server
	HTTPServer *http.Server // if you need gRPC gw,please use it
	// contains filtered or unexported fields
}

Service represents the microservice.

func NewService 

func NewService(opts ...Option) *Service

NewService creates a new microservice

func NewServiceWithoutGateway 

func NewServiceWithoutGateway(opts ...Option) *Service

NewServiceWithoutGateway new a service without http gw.

func (*Service) AddHandlerFromEndpoint 

func (s *Service) AddHandlerFromEndpoint(h ...HandlerFromEndpoint)

AddHandlerFromEndpoint add HandlerFromEndpoint.

func (*Service) AddRoute 

func (s *Service) AddRoute(routes ...Route)

AddRoute add some route to routes

func (*Service) GetPid 

func (s *Service) GetPid() int

GetPid gets the process id of server

func (*Service) RequestInterceptor 

func (s *Service) RequestInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo,
	handler grpc.UnaryHandler) (reply interface{}, err error)

RequestInterceptor request interceptor to record basic information of the request

func (*Service) ServeFile 

func (s *Service) ServeFile(w http.ResponseWriter, r *http.Request, _ map[string]string)

ServeFile serves a file

func (*Service) Start 

func (s *Service) Start(httpPort, grpcPort int) error

Start starts the microservice with listening on the ports start grpc gateway and http server on different port

func (*Service) StartGRPCAndHTTPServer 

func (s *Service) StartGRPCAndHTTPServer(port int) error

StartGRPCAndHTTPServer grpc server and grpc gateway port share a port error: rpc error: code = Unavailable desc = all SubConns are in TransientFailure, latest connection error: timed out waiting for server handshake please set this gRPC var. export GRPC_GO_REQUIRE_HANDSHAKE=off

func (*Service) StartGRPCWithoutGateway 

func (s *Service) StartGRPCWithoutGateway(grpcPort int) error

StartGRPCWithoutGateway start gRPC without gw.

func (*Service) Stop 

func (s *Service) Stop()

Stop stops the microservice gracefully.

func (*Service) StopGRPCWithoutGateway 

func (s *Service) StopGRPCWithoutGateway()

StopGRPCWithoutGateway stop the gRPC server gracefully

Source Files

View all Source files

Directories

Path Synopsis
example
clients/go
clients/go/pb
Package pb is a reverse proxy.
 Package pb is a reverse proxy.
pb
Package pb is a reverse proxy.
 Package pb is a reverse proxy.
server

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.