grpc

Documentation

Overview

Package grpc provides server-side gRPC bootstrap helpers for the config module.

It wraps grpc.Server creation so services can be started with shared configuration loading, tracing, TLS, mTLS, and graceful lifecycle handling.

The package is transport-oriented: it does not depend on a concrete generated service. Any service generated in the proto package can be registered through Register.

Before the server starts serving, Serve loads configuration through utilities.LoadEnv("."), so values such as server.grpc.port, TLS, and mTLS settings can be sourced from application.yml or application.json plus environment overrides.

Basic usage:

package main

import (
	"context"
	"log"

	pb "github.com/PointerByte/GoForge/config/proto"
	servergrpc "github.com/PointerByte/GoForge/config/server/grpc"
	grpcstd "google.golang.org/grpc"
)

type greeterServer struct {
	pb.UnimplementedGreeterServer
}

func (s greeterServer) SayHello(_ context.Context, req *pb.HelloRequest) (*pb.HelloReply, error) {
	return &pb.HelloReply{Message: "hello " + req.GetName()}, nil
}

func (s greeterServer) CreateChat(stream pb.Greeter_CreateChatServer) error {
	return nil
}

func (s greeterServer) StreamAlerts(stream pb.Greeter_StreamAlertsServer) error {
	return nil
}

func main() {
	srv := servergrpc.NewIConfig(nil, nil)
	srv.SetAddress(":50051")

	err := srv.Register(func(r grpcstd.ServiceRegistrar) {
		pb.RegisterGreeterServer(r, greeterServer{})
	})
	if err != nil {
		log.Fatal(err)
	}

	log.Fatal(srv.Serve())
}

If you already have your own listener, inject it with SetListener instead of SetAddress.

JWT can be attached explicitly with the security gRPC interceptors:

import (
	servergrpc "github.com/PointerByte/GoForge/config/server/grpc"
	"github.com/PointerByte/GoForge/security/middlewares"
)

srv := servergrpc.NewIConfig(nil, nil,
	servergrpc.WithUnaryInterceptors(middlewares.RequireJWTUnaryServerInterceptor()),
	servergrpc.WithStreamInterceptors(middlewares.RequireJWTStreamServerInterceptor()),
)

Package grpc is a generated GoMock package.

Index

• func SetTLSConfig(config *tls.Config)
• type Config
  • func (su *Config) GetListener() net.Listener
  • func (su *Config) GetServer() *grpc.Server
  • func (su *Config) GracefulStop()
  • func (su *Config) Register(register RegisterServiceFunc) error
  • func (su *Config) Serve() error
  • func (su *Config) SetAddress(address string)
  • func (su *Config) SetListener(listener net.Listener)
  • func (su *Config) Stop()
• type ConfigOption
  • func WithStreamInterceptors(interceptors ...grpc.StreamServerInterceptor) ConfigOption
  • func WithUnaryInterceptors(interceptors ...grpc.UnaryServerInterceptor) ConfigOption
• type IConfig
  • func NewIConfig(mocks IConfig, server *grpc.Server, options ...ConfigOption) IConfig
• type MockIConfig
  • func NewMockIConfig(ctrl *gomock.Controller) *MockIConfig
  • func (m *MockIConfig) EXPECT() *MockIConfigMockRecorder
  • func (m *MockIConfig) GetListener() net.Listener
  • func (m *MockIConfig) GetServer() *grpc.Server
  • func (m *MockIConfig) GracefulStop()
  • func (m *MockIConfig) Register(register RegisterServiceFunc) error
  • func (m *MockIConfig) Serve() error
  • func (m *MockIConfig) SetAddress(address string)
  • func (m *MockIConfig) SetListener(listener net.Listener)
  • func (m *MockIConfig) Stop()
• type MockIConfigMockRecorder
  • func (mr *MockIConfigMockRecorder) GetListener() *gomock.Call
  • func (mr *MockIConfigMockRecorder) GetServer() *gomock.Call
  • func (mr *MockIConfigMockRecorder) GracefulStop() *gomock.Call
  • func (mr *MockIConfigMockRecorder) Register(register interface{}) *gomock.Call
  • func (mr *MockIConfigMockRecorder) Serve() *gomock.Call
  • func (mr *MockIConfigMockRecorder) SetAddress(address interface{}) *gomock.Call
  • func (mr *MockIConfigMockRecorder) SetListener(listener interface{}) *gomock.Call
  • func (mr *MockIConfigMockRecorder) Stop() *gomock.Call
• type RegisterServiceFunc

Functions

func SetTLSConfig

func SetTLSConfig(config *tls.Config)

SetTLSConfig sets the TLS configuration that NewIConfig should attach to internally created gRPC servers.

When a custom grpc.Server is injected into NewIConfig, this configuration is ignored because the server has already been created by the caller.

Types

type Config

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

func (*Config) GetListener

func (su *Config) GetListener() net.Listener

func (*Config) GetServer

func (su *Config) GetServer() *grpc.Server

func (*Config) GracefulStop

func (su *Config) GracefulStop()

func (*Config) Register

func (su *Config) Register(register RegisterServiceFunc) error

func (*Config) Serve

func (su *Config) Serve() error

func (*Config) SetAddress

func (su *Config) SetAddress(address string)

func (*Config) SetListener

func (su *Config) SetListener(listener net.Listener)

func (*Config) Stop

func (su *Config) Stop()

type ConfigOption

type ConfigOption func(*Config)

ConfigOption customizes internally created gRPC servers.

func WithStreamInterceptors

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

WithStreamInterceptors appends stream interceptors to the default traces and logger interceptor chain.

func WithUnaryInterceptors

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

WithUnaryInterceptors appends unary interceptors to the default traces and logger interceptor chain.

type IConfig

type IConfig interface {
	// SetAddress defines the TCP address that will be used when Serve needs to create its own listener.
	SetAddress(address string)

	// SetListener defines an external listener. If present, Serve uses it instead of creating a new one.
	SetListener(listener net.Listener)

	// Register injects one generated registration function against the underlying grpc.Server.
	Register(register RegisterServiceFunc) error

	// Serve starts the gRPC server using the configured listener or address.
	Serve() error

	// GracefulStop stops the server gracefully.
	GracefulStop()

	// Stop stops the server immediately.
	Stop()

	// GetServer returns the underlying grpc.Server.
	GetServer() *grpc.Server

	// GetListener returns the currently configured listener.
	GetListener() net.Listener
}

IConfig defines the basic operations required to configure and run a unary gRPC server.

The implementation is transport-oriented and does not depend on a specific proto service. Generated registrations from the proto package can be injected through Register.

func NewIConfig

func NewIConfig(mocks IConfig, server *grpc.Server, options ...ConfigOption) IConfig

NewIConfig creates a new unary gRPC server wrapper.

The server parameter lets callers inject an already constructed *grpc.Server when they need explicit control over server options before handing execution to this package.

If server is nil, the function creates a default grpc.Server with the package interceptors for traces and logging.

If server is not nil, that instance is used as-is and its existing configuration is preserved.

If mocks is provided, all operations delegate to it, which is useful for tests generated with mockgen.

Common usage:

srv := unitary.NewIConfig(nil, nil)
srv.SetAddress(":50051")
err := srv.Register(func(r grpc.ServiceRegistrar) {
	proto.RegisterGreeterServer(r, handler)
})
if err != nil {
	return err
}
return srv.Serve()

Example with a custom gRPC server:

custom := grpc.NewServer()
srv := unitary.NewIConfig(nil, custom)

type MockIConfig

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

MockIConfig is a mock of IConfig interface.

func NewMockIConfig

func NewMockIConfig(ctrl *gomock.Controller) *MockIConfig

NewMockIConfig creates a new mock instance.

func (*MockIConfig) EXPECT

func (m *MockIConfig) EXPECT() *MockIConfigMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockIConfig) GetListener

func (m *MockIConfig) GetListener() net.Listener

GetListener mocks base method.

func (*MockIConfig) GetServer

func (m *MockIConfig) GetServer() *grpc.Server

GetServer mocks base method.

func (*MockIConfig) GracefulStop

func (m *MockIConfig) GracefulStop()

GracefulStop mocks base method.

func (*MockIConfig) Register

func (m *MockIConfig) Register(register RegisterServiceFunc) error

Register mocks base method.

func (*MockIConfig) Serve

func (m *MockIConfig) Serve() error

Serve mocks base method.

func (*MockIConfig) SetAddress

func (m *MockIConfig) SetAddress(address string)

SetAddress mocks base method.

func (*MockIConfig) SetListener

func (m *MockIConfig) SetListener(listener net.Listener)

SetListener mocks base method.

func (*MockIConfig) Stop

func (m *MockIConfig) Stop()

Stop mocks base method.

type MockIConfigMockRecorder

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

MockIConfigMockRecorder is the mock recorder for MockIConfig.

func (*MockIConfigMockRecorder) GetListener

func (mr *MockIConfigMockRecorder) GetListener() *gomock.Call

GetListener indicates an expected call of GetListener.

func (*MockIConfigMockRecorder) GetServer

func (mr *MockIConfigMockRecorder) GetServer() *gomock.Call

GetServer indicates an expected call of GetServer.

func (*MockIConfigMockRecorder) GracefulStop

func (mr *MockIConfigMockRecorder) GracefulStop() *gomock.Call

GracefulStop indicates an expected call of GracefulStop.

func (*MockIConfigMockRecorder) Register

func (mr *MockIConfigMockRecorder) Register(register interface{}) *gomock.Call

Register indicates an expected call of Register.

func (*MockIConfigMockRecorder) Serve

func (mr *MockIConfigMockRecorder) Serve() *gomock.Call

Serve indicates an expected call of Serve.

func (*MockIConfigMockRecorder) SetAddress

func (mr *MockIConfigMockRecorder) SetAddress(address interface{}) *gomock.Call

SetAddress indicates an expected call of SetAddress.

func (*MockIConfigMockRecorder) SetListener

func (mr *MockIConfigMockRecorder) SetListener(listener interface{}) *gomock.Call

SetListener indicates an expected call of SetListener.

func (*MockIConfigMockRecorder) Stop

func (mr *MockIConfigMockRecorder) Stop() *gomock.Call

Stop indicates an expected call of Stop.

type RegisterServiceFunc

type RegisterServiceFunc func(grpc.ServiceRegistrar)

RegisterServiceFunc allows registering any generated gRPC service from the proto package. Example:

srv.Register(func(r grpc.ServiceRegistrar) {
  proto.RegisterGreeterServer(r, handler)
})