grpcpool

README

gRPC Connection Pool

This package provides a connection pool for gRPC clients in Go, allowing efficient management and reuse of gRPC connections.

Features

• Configurable minimum and maximum number of connections
• Automatic connection creation and cleanup
• Idle timeout for unused connections
• Concurrent-safe connection management
• Simple API for getting and releasing connections

Installation

To install the gRPC connection pool package, use the following command:

go get github.com/t34-dev/go-grpc-pool

Ensure that you have Go modules enabled in your project.

Usage

Here's a basic example of how to use the gRPC connection pool in your project:

package main

import (
	"context"
	"log"
	"time"

	"github.com/t34-dev/go-grpc-pool"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
)

func main() {
	// Define a factory function to create gRPC connections
	factory := func() (*grpc.ClientConn, error) {
		return grpc.Dial("localhost:50053",
			grpc.WithTransportCredentials(insecure.NewCredentials()),
			grpc.WithBlock(),
			grpc.WithTimeout(5*time.Second))
	}

	// Create a new connection pool
	pool, err := grpcpool.NewPool(factory, grpcpool.PoolOptions{
		MinConn:     2,
		MaxConn:     10,
		IdleTimeout: 5 * time.Minute,
		WaitGetConn: 20 * time.Second,
	})
	if err != nil {
		log.Fatalf("Failed to create pool: %v", err)
	}
	defer pool.Close()

	// Get a connection from the pool
	conn, err := pool.Get()
	if err != nil {
		log.Fatalf("Failed to get connection: %v", err)
	}
	defer conn.Free() // Return the connection to the pool when done

	// Use the connection to make gRPC calls
	client := yourpackage.NewYourServiceClient(conn.GetConn())
	resp, err := client.YourMethod(context.Background(), &yourpackage.YourRequest{})
	if err != nil {
		log.Fatalf("Error calling YourMethod: %v", err)
	}

	log.Printf("Response: %v", resp)
}

Configuration

The PoolOptions struct allows you to configure the connection pool:

• MinConn: Minimum number of connections to maintain in the pool
• MaxConn: Maximum number of connections allowed in the pool
• IdleTimeout: Duration after which idle connections are closed
• WaitGetConn: Maximum duration to wait for an available connection
• Logger: Optional logger interface for debugging

Testing

To run the tests for this package, use the following command:

make test

Development

To generate protobuf files (if needed):

make protoc

To run the example server:

make server

To run the example client:

make client

License

This project is licensed under the ISC License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Developed with ❤️ by T34

Documentation

Index

• Variables
• type Connection
  • func (c *Connection) Free()
  • func (c *Connection) GetConn() *grpc.ClientConn
  • func (c *Connection) IsReady() bool
• type Logger
• type Pool
  • func NewPool(factory connectionFactory, options PoolOptions) (*Pool, error)
  • func (p *Pool) Close()
  • func (p *Pool) Get() (*Connection, error)
  • func (p *Pool) GetStats() poolStats
  • func (p *Pool) Init() error
• type PoolOptions

Variables

var (
	ErrOptionMinOrMax  = errors.New("invalid MinConn or MaxConn")
	ErrConnection      = errors.New("connection error")
	ErrInitFailed      = errors.New("failed to initialize connection")
	ErrClosed          = errors.New("client pool is closed")
	ErrNoAvailableConn = errors.New("no available connections")
	ErrTimeout         = errors.New("client pool timeout exceeded")
	ErrAlreadyClosed   = errors.New("connection was already closed")
	ErrFullPool        = errors.New("attempt to destroy ClientConn in a full pool")
)

Error variables for common error scenarios

Types

type Connection

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

Connection represents a single gRPC connection in the pool

func (*Connection) Free

func (c *Connection) Free()

Free marks the connection as not in use and updates the last used timestamp

func (*Connection) GetConn

func (c *Connection) GetConn() *grpc.ClientConn

GetConn returns the underlying gRPC client connection

func (*Connection) IsReady

func (c *Connection) IsReady() bool

IsReady checks if the connection is ready for use

type Logger

type Logger interface {
	Debug(msg ...interface{})
	Error(msg ...interface{})
}

Logger - interface for logger

type Pool

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

Pool represents a pool of gRPC client connections

func NewPool

func NewPool(factory connectionFactory, options PoolOptions) (*Pool, error)

NewPool creates a new connection pool with the given factory and options

func (*Pool) Close

func (p *Pool) Close()

Close shuts down the pool and all its connections

func (*Pool) Get

func (p *Pool) Get() (*Connection, error)

Get retrieves an available connection from the pool or creates a new one if possible

func (*Pool) GetStats

func (p *Pool) GetStats() poolStats

GetStats returns the current statistics of the connection pool

func (*Pool) Init

func (p *Pool) Init() error

Init initializes the pool with the minimum number of connections

type PoolOptions

type PoolOptions struct {
	MinConn     int
	MaxConn     int
	WaitGetConn time.Duration
	IdleTimeout time.Duration
	Logger      Logger
}

PoolOptions contains configuration options for the connection pool