grpcx

package module
v0.11.2 Latest Latest
Warning

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

Go to latest
Published: Dec 3, 2023 License: Apache-2.0 Imports: 29 Imported by: 0

README

gRPCX

GoDoc

gRPCX is a framework for building enterprise-grade Saas applications with gRPC. It is meant to be a batteries-included framework for building enterprise-grade gRPC services.

go get github.com/autom8ter/grpcx

Features

  • gRPC
  • gRPC-gateway
  • Serve Gateway/gRPC same port(cmux)
  • Flexible Provider/Interface based architecture: use the same code with different providers depending on tech stack
  • Metrics(prometheus)
  • File Storage dependency injection(local, gcs)
  • Structured Logging(slog)
  • Database Migrations(golang-migrate)
  • Database dependency injection(sqlite,mysql,postgres)
  • Cache dependency injection(redis)
  • Stream dependency injection(redis,nats)
  • Email dependency injection(smtp)
  • Payment Processing dependency injection(stripe)
  • Context Tagging Middleware/Interceptor
  • Authentication with protoc-gen-authenticate
  • Authorization with protoc-gen-authorize
  • Rate-limiting with protoc-gen-ratelimit
  • Request Validation with protoc-gen-validate
  • Compatible with protoc-gen-validate
  • Flexible configuration(viper)
  • Graceful Shutdown
  • Panic Recovery middleware/interceptor
  • CORS middleware(for gRPC-gateway)
  • Can be run completely in-memory for testing

Other gRPC Projects

TODO

  • Add more tests
  • Add more examples
  • Add more documentation
  • Add kafka stream provider
  • Add rabbitmq stream provider
  • Add sendgrid email provider
  • Add mailgun email provider
  • Add tracing support

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CustomHTTPRoute

type CustomHTTPRoute struct {
	// Method is the http method
	Method string
	// Path is the http path
	Path string
	// Handler is the http handler
	Handler runtime.HandlerFunc
}

CustomHTTPRoute is a custom route that can be added to the rest-gateway

type Server

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

Server is a highly configurable grpc server with a built-in rest-gateway(grpc-gateway) The server supports the following features via ServerOptions: - Logging Interface (slog) - Metrics Interface (prometheus) - Database Interface (sqlite/mysql/postgres) - Cache Interface (redis) - Stream Interface (nats/redis) - Context Tags - Authentication (see github.com/autom8ter/protoc-gen-authenticate) - Authorization (see github.com/autom8ter/protoc-gen-authorize) - Rate Limiting (see github.com/autom8ter/protoc-gen-ratelimit)

func NewServer

func NewServer(ctx context.Context, opts ...ServerOption) (*Server, error)

NewServer creates a new server with the given config and options

Example
package main

import (
	"context"
	"fmt"

	"google.golang.org/grpc"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/metadata"
	"google.golang.org/grpc/status"

	"github.com/autom8ter/grpcx"
	echov1 "github.com/autom8ter/grpcx/gen/echo"
	"github.com/autom8ter/grpcx/providers/prometheus"

	redis2 "github.com/autom8ter/grpcx/providers/redis"
	"github.com/autom8ter/grpcx/providers/sqlite"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()
	cache, err := redis2.NewInMem()
	if err != nil {
		panic(err)
	}
	metrics := prometheus.New()
	database, err := sqlite.New(ctx, "file::memory:?cache=shared", "")
	if err != nil {
		panic(err)
	}
	port := 8080
	if err != nil {
		panic(err)
	}
	srv, err := grpcx.NewServer(
		ctx,
		// Register Cache Provider
		grpcx.WithCache(cache),
		// Register Stream Provider
		grpcx.WithStream(cache),
		// Register Database
		grpcx.WithDatabase(database),
		// Register Metrics
		grpcx.WithMetrics(metrics),
	)
	if err != nil {
		panic(err)
	}
	go func() {
		if err := srv.Serve(ctx, port, EchoService()); err != nil {
			panic(err)
		}
	}()

	conn, err := grpc.DialContext(ctx, fmt.Sprintf("localhost:%v", port), grpc.WithInsecure())
	if err != nil {
		panic(err)
	}
	defer conn.Close()
	echoClient := echov1.NewEchoServiceClient(conn)
	ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "test:test")
	resp, err := echoClient.Echo(ctx, &echov1.EchoRequest{
		Message: "hello",
	})
	if err != nil {
		panic(err)
	}
	println(resp.Message)
}

type echoServer struct {
	echov1.UnimplementedEchoServiceServer
}

func (e *echoServer) Echo(ctx context.Context, req *echov1.EchoRequest) (*echov1.EchoResponse, error) {
	var meta = map[string]string{}
	md, ok := metadata.FromIncomingContext(ctx)
	if !ok {
		return nil, status.Error(codes.Unauthenticated, "no metadata found in context")
	}
	for k, v := range md {
		meta[k] = v[0]
	}
	return &echov1.EchoResponse{
		Message:        req.Message,
		ClientMetadata: meta,
	}, nil
}

// EchoService returns a ServiceRegistration that registers an echo service
func EchoService() grpcx.ServiceRegistration {
	return grpcx.ServiceRegistration(func(ctx context.Context, cfg grpcx.ServiceRegistrationConfig) error {
		echov1.RegisterEchoServiceServer(cfg.GrpcServer, &echoServer{})
		return nil
	})
}
Output:

func (*Server) Providers

func (s *Server) Providers() providers.All

Providers returns the server providers

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, port int, services ...Service) error

Serve registers the given services and starts the server. This function blocks until the server is shutdown. The server will shutdown when the context is canceled or an interrupt signal is received. The server will start grpc/rest-gateway servers on the port specified by the config key "api.port" The server will register a health check at /health and a readiness check at /ready The server will register a metrics endpoint at /metrics if the config key "metrics.prometheus" is true

type ServerOption

type ServerOption func(opt *serverOpt)

ServerOption is a function that configures the server. All ServerOptions are optional.

func WithAuth

func WithAuth(auth authenticator.AuthFunc, selectors ...selector.Matcher) ServerOption

WithAuth adds an auth provider to the server (see github.com/autom8ter/protoc-gen-authenticate) If no selectors are provided, the auth provider will be used for all requests This method can be called multiple times to add multiple auth providers

func WithAuthz added in v0.3.0

func WithAuthz(authorizer authorizer.Authorizer, opts ...authorizer.Opt) ServerOption

WithAuthz adds an authorizer to the server (see github.com/autom8ter/protoc-gen-authorize) This method can be called multiple times to add multiple authorizers Options can be added to add a userExtractor and selectors

func WithCache

func WithCache(provider providers.Cache) ServerOption

WithCache adds a cache provider

func WithCors added in v0.11.0

func WithCors(opts *cors.Options) ServerOption

WithCors adds cors middleware to the rest-gateway

func WithCustomHTTPRoute

func WithCustomHTTPRoute(method, path string, handler runtime.HandlerFunc) ServerOption

WithCustomHTTPRoute adds a custom http route to the rest-gateway

func WithDatabase

func WithDatabase(provider providers.Database) ServerOption

WithDatabase adds a database provider

func WithEmail added in v0.9.1

func WithEmail(provider providers.Emailer) ServerOption

WithEmail adds an email provider

func WithGatewayOpts

func WithGatewayOpts(opts ...runtime.ServeMuxOption) ServerOption

WithGatewayOpts adds options to the grpc gateway

func WithGrpcHealthCheck added in v0.8.0

func WithGrpcHealthCheck(srv grpc_health_v1.HealthServer) ServerOption

WithGrpcHealthCheck adds a grpc health check to the server

func WithLogger

func WithLogger(provider providers.Logger) ServerOption

WithLogger adds a logging provider

func WithMetrics

func WithMetrics(metrics providers.Metrics) ServerOption

WithMetrics adds a metrics provider to the server

func WithPaymentProcessor added in v0.9.1

func WithPaymentProcessor(processor providers.PaymentProcessor) ServerOption

WithPaymentProcessor adds a payment processor to the server

func WithRateLimit

func WithRateLimit(rateLimit limiter.Limiter, selectors ...selector.Matcher) ServerOption

WithRateLimit adds a rate limiter to the server (see protoc-gen-ratelimit) If no selectors are provided, the rate limiter will be used for all requests This method can be called multiple times to add multiple rate limiters

func WithStorage added in v0.9.4

func WithStorage(provider providers.Storage) ServerOption

WithStorage adds a storage provider

func WithStream

func WithStream(provider providers.Stream) ServerOption

WithStream adds a stream provider

func WithStreamInterceptors

func WithStreamInterceptors(interceptors ...grpc.StreamServerInterceptor) ServerOption

WithStreamInterceptors adds interceptors to the grpc server

func WithTagsProvider added in v0.11.0

func WithTagsProvider(tagger providers.TagsProvider) ServerOption

WithTagsProvider adds a context tagger to the server

func WithUnaryInterceptors

func WithUnaryInterceptors(interceptors ...grpc.UnaryServerInterceptor) ServerOption

WithUnaryInterceptors adds unary interceptors to the server

func WithValidation added in v0.9.0

func WithValidation() ServerOption

WithValidation enables grpc validation interceptors for validating requests

type Service

type Service interface {
	// Register registers a service with the server
	Register(ctx context.Context, cfg ServiceRegistrationConfig) error
}

Service is a an interface that registers a service with the server

type ServiceRegistration

type ServiceRegistration func(ctx context.Context, cfg ServiceRegistrationConfig) error

ServiceRegistration is a function that registers a service with the server

func (ServiceRegistration) Register

Register implements the Service interface

type ServiceRegistrationConfig

type ServiceRegistrationConfig struct {
	GrpcServer  *grpc.Server
	RestGateway *runtime.ServeMux
	Providers   providers.All
}

ServiceRegistrationConfig is the config passed to a service registration function

Directories

Path Synopsis
gen
echo
Package echov1 is a reverse proxy.
Package echov1 is a reverse proxy.
internal
gcs
mocks
Package mocks is a generated GoMock package.
Package mocks is a generated GoMock package.
s3

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL