feat: add proxy for gin

Author: zhufuyi

pkg/gin/proxy/README.md

@@ -0,0 +1,79 @@
+## Gin Proxy
+
+A production-grade reverse proxy library implemented in Go. It not only provides high performance and multiple load balancing strategies, but also supports **dynamic route management**, allowing you to add or remove backend servers at runtime via API — without restarting the service.
+
+### Core Features
+
+*   **Dynamic Service Discovery**: Add or remove backend nodes in real-time through HTTP APIs.
+*   **High Performance Core**: Built on `net/http/httputil` with deeply optimized connection pooling for effortless high-concurrency handling.
+*   **Rich Load Balancing Strategies**: Includes Round Robin, The Least Connections, and IP Hash.
+*   **Active Health Checks**: Automatically detects and isolates unhealthy nodes, and brings them back online once they recover.
+*   **Multi-route Support**: Distribute traffic to different backend groups based on path prefixes.
+
+### Example of Usage
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/go-dev-frame/sponge/pkg/gin/proxy"
+    "github.com/gin-gonic/gin"
+)
+
+func main() {
+    r := gin.Default()
+
+    p := proxy.New(r) // default configuration, managerPrefixPath = "/endpoints"
+    pass1(p)
+    pass2(p)
+
+    // Other normal routes
+    r.GET("/ping", func(c *gin.Context) {
+        c.JSON(200, gin.H{"message": "pong"})
+    })
+
+    fmt.Println("Gin server with dynamic proxy started on http://localhost:8080")
+
+    r.Run(":8080")
+}
+
+func pass1(p *proxy.Proxy) {
+    prefixPath := "/proxy/"
+    initialTargets := []string{"http://localhost:8081", "http://localhost:8082"}
+    err := p.Pass(prefixPath, initialTargets) // default configuration, balancer = RoundRobin, healthCheckInterval = 5s, healthCheckTimeout = 3s
+    if err != nil {
+        panic(err)
+    }
+}
+
+func pass2(p *proxy.Proxy) {
+    prefixPath := "/personal/"
+    initialTargets := []string{"http://localhost:8083", "http://localhost:8084"}
+    err := p.Pass(prefixPath, initialTargets)
+    if err != nil {
+        panic(err)
+    }
+}
+```
+
+<br>
+
+### Advanced Settings
+
+1. Configure the management endpoints' route prefix, middleware, and logger through function parameters of `proxy.New`.
+    ```go
+    p := proxy.New(r, proxy.Config{
+        proxy.WithManagerEndpoints("/admin", Middlewares...),
+        proxy.WithLogger(zap.NewExample()),
+    })
+    ```
+
+2. Configure the load balancing type, health check interval, and middleware for the endpoints through function parameters of `p.Pass`.
+    ```go
+    err := p.Pass("/proxy/", []string{"http://localhost:8081", "http://localhost:8082"}, proxy.Config{
+        proxy.WithPassBalancer(proxy.BalancerIPHash),
+        proxy.WithPassHealthCheck(time.Second * 5, time.Second * 3),
+        proxy.WithPassMiddlewares(Middlewares...),
+    })
+    ```

pkg/gin/proxy/proxy.go

@@ -0,0 +1,86 @@
+package proxy
+
+import (
+	"fmt"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/go-dev-frame/sponge/pkg/proxykit"
+)
+
+// Proxy is a proxy server.
+type Proxy struct {
+	r       *gin.Engine
+	manager *proxykit.RouteManager
+}
+
+// New creates a new Proxy instance.
+func New(r *gin.Engine, opts ...Option) *Proxy {
+	o := defaultOptions()
+	o.apply(opts...)
+
+	if o.zapLogger != nil {
+		proxykit.SetLogger(o.zapLogger)
+	}
+
+	manager := proxykit.NewRouteManager()
+
+	// setup manager endpoints routes
+	managerRelativePath := o.managerPrefixPath
+	var managerGroup *gin.RouterGroup
+	if len(o.managerMiddlewares) > 0 {
+		managerGroup = r.Group(managerRelativePath, o.managerMiddlewares...)
+	} else {
+		managerGroup = r.Group(managerRelativePath)
+	}
+	{
+		managerGroup.POST("/add", gin.WrapF(manager.HandleAddBackends))
+		managerGroup.POST("/remove", gin.WrapF(manager.HandleRemoveBackends))
+		managerGroup.GET("/list", gin.WrapF(manager.HandleListBackends))
+		managerGroup.GET("", gin.WrapF(manager.HandleGetBackend))
+	}
+
+	return &Proxy{
+		r:       r,
+		manager: manager,
+	}
+}
+
+// Pass registers proxy endpoints to gin engine.
+func (p *Proxy) Pass(prefixPath string, endpoints []string, opts ...PassOption) error {
+	o := defaultPassOptions()
+	o.apply(opts...)
+
+	backends, err := proxykit.ParseBackends(prefixPath, endpoints)
+	if err != nil {
+		return fmt.Errorf("parse backends error: %v", err)
+	}
+	proxykit.StartHealthChecks(backends, proxykit.HealthCheckConfig{
+		Interval: o.healthCheckInterval,
+		Timeout:  o.healthCheckTimeout,
+	})
+
+	var balancer proxykit.Balancer
+	switch o.balancerType {
+	case BalancerRoundRobin:
+		balancer = proxykit.NewRoundRobin(backends)
+	case BalancerLeastConn:
+		balancer = proxykit.NewLeastConnections(backends)
+	case BalancerIPHash:
+		balancer = proxykit.NewIPHash(backends)
+	default:
+		return fmt.Errorf("unsupported balancer type: %s", o.balancerType)
+	}
+
+	apiRoute, err := p.manager.AddRoute(prefixPath, balancer)
+	if err != nil {
+		return fmt.Errorf("could not add initial route: %v", err)
+	}
+
+	// setup proxy endpoints routes
+	proxyRelativePath := proxykit.AnyRelativePath(prefixPath) // /prefixPath/*path
+	proxyHandlerFuncs := append(o.passMiddlewares, gin.WrapH(apiRoute.Proxy))
+	p.r.Any(proxyRelativePath, proxyHandlerFuncs...)
+
+	return nil
+}

pkg/gin/proxy/proxy_option.go

@@ -0,0 +1,109 @@
+package proxy
+
+import (
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// Option set options.
+type Option func(*options)
+
+type options struct {
+	managerPrefixPath  string // default "/endpoints"
+	managerMiddlewares []gin.HandlerFunc
+	zapLogger          *zap.Logger
+}
+
+func (o *options) apply(opts ...Option) {
+	for _, opt := range opts {
+		opt(o)
+	}
+}
+
+func defaultOptions() *options {
+	return &options{
+		managerPrefixPath: "/endpoints",
+	}
+}
+
+// WithManagerEndpoints sets manager prefix path and middlewares, managerPrefixPath default "/endpoints".
+func WithManagerEndpoints(managerPrefixPath string, middlewares ...gin.HandlerFunc) Option {
+	return func(o *options) {
+		if managerPrefixPath != "" {
+			if !strings.HasPrefix(managerPrefixPath, "/") {
+				managerPrefixPath = "/" + managerPrefixPath
+			}
+			managerPrefixPath = strings.TrimSuffix(managerPrefixPath, "/")
+			o.managerPrefixPath = managerPrefixPath
+		}
+		o.managerMiddlewares = middlewares
+	}
+}
+
+// WithLogger sets logger.
+func WithLogger(logger *zap.Logger) Option {
+	return func(o *options) {
+		o.zapLogger = logger
+	}
+}
+
+// -------------------------------------------------------------------------------------------
+
+var (
+	BalancerRoundRobin = "round_robin"
+	BalancerLeastConn  = "least_conn"
+	BalancerIPHash     = "ip_hash"
+)
+
+// PassOption set passOptions.
+type PassOption func(*passOptions)
+
+type passOptions struct {
+	healthCheckInterval time.Duration // default 5s
+	healthCheckTimeout  time.Duration // default 3s
+	balancerType        string        // supported values: "round_robin", "least_conn", "ip_hash", default "round_robin"
+	passMiddlewares     []gin.HandlerFunc
+}
+
+func (o *passOptions) apply(opts ...PassOption) {
+	for _, opt := range opts {
+		opt(o)
+	}
+}
+
+func defaultPassOptions() *passOptions {
+	return &passOptions{
+		healthCheckInterval: 5 * time.Second,
+		healthCheckTimeout:  3 * time.Second,
+		balancerType:        BalancerRoundRobin,
+	}
+}
+
+// WithPassBalancer sets balancer type.
+func WithPassBalancer(balancerType string) PassOption {
+	return func(o *passOptions) {
+		o.balancerType = balancerType
+	}
+}
+
+// WithPassHealthCheck sets health check interval and timeout.
+func WithPassHealthCheck(interval time.Duration, timeout time.Duration) PassOption {
+	return func(o *passOptions) {
+		if interval >= time.Second {
+			o.healthCheckInterval = interval
+		}
+		if timeout >= time.Millisecond*100 {
+			o.healthCheckTimeout = timeout
+		}
+	}
+}
+
+// WithPassMiddlewares sets proxy middlewares.
+func WithPassMiddlewares(middlewares ...gin.HandlerFunc) PassOption {
+	return func(o *passOptions) {
+		o.passMiddlewares = middlewares
+	}
+}

pkg/gin/proxy/proxy_option_test.go

@@ -0,0 +1,117 @@
+package proxy
+
+import (
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func TestDefaultOptions(t *testing.T) {
+	opts := defaultOptions()
+	if opts.managerPrefixPath != "/endpoints" {
+		t.Errorf("expected default prefix /endpoints, got %s", opts.managerPrefixPath)
+	}
+	if opts.managerMiddlewares != nil {
+		t.Errorf("expected nil manager middlewares by default")
+	}
+}
+
+func TestWithManagerEndpoints(t *testing.T) {
+	mw := func(c *gin.Context) {}
+	opts := defaultOptions()
+	opts.apply(WithManagerEndpoints("api", mw))
+
+	if opts.managerPrefixPath != "/api" {
+		t.Errorf("expected /api, got %s", opts.managerPrefixPath)
+	}
+	if len(opts.managerMiddlewares) != 1 {
+		t.Errorf("expected one middleware")
+	}
+}
+
+func TestWithManagerEndpointsWithSlash(t *testing.T) {
+	opts := defaultOptions()
+	opts.apply(WithManagerEndpoints("/api/"))
+
+	if opts.managerPrefixPath != "/api" {
+		t.Errorf("expected /api (trimmed), got %s", opts.managerPrefixPath)
+	}
+}
+
+func TestWithManagerEndpointsEmpty(t *testing.T) {
+	opts := defaultOptions()
+	opts.apply(WithManagerEndpoints(""))
+
+	// should keep default
+	if opts.managerPrefixPath != "/endpoints" {
+		t.Errorf("expected default /endpoints, got %s", opts.managerPrefixPath)
+	}
+}
+
+func TestWithLogger(t *testing.T) {
+	logger, _ := zap.NewDevelopment()
+	opts := defaultOptions()
+	opts.apply(WithLogger(logger))
+
+	if opts.zapLogger == nil {
+		t.Errorf("expected logger to be set")
+	}
+}
+
+func TestDefaultPassOptions(t *testing.T) {
+	opts := defaultPassOptions()
+	if opts.healthCheckInterval != 5*time.Second {
+		t.Errorf("expected default 5s, got %v", opts.healthCheckInterval)
+	}
+	if opts.healthCheckTimeout != 3*time.Second {
+		t.Errorf("expected default 3s, got %v", opts.healthCheckTimeout)
+	}
+	if opts.balancerType != "round_robin" {
+		t.Errorf("expected default round_robin, got %s", opts.balancerType)
+	}
+}
+
+func TestWithPassBalancer(t *testing.T) {
+	opts := defaultPassOptions()
+	opts.apply(WithPassBalancer("least_conn"))
+
+	if opts.balancerType != "least_conn" {
+		t.Errorf("expected least_conn, got %s", opts.balancerType)
+	}
+}
+
+func TestWithPassHealthCheckValid(t *testing.T) {
+	opts := defaultPassOptions()
+	opts.apply(WithPassHealthCheck(2*time.Second, 2*time.Second))
+
+	if opts.healthCheckInterval != 2*time.Second {
+		t.Errorf("expected 2s, got %v", opts.healthCheckInterval)
+	}
+	if opts.healthCheckTimeout != 2*time.Second {
+		t.Errorf("expected 2s, got %v", opts.healthCheckTimeout)
+	}
+}
+
+func TestWithPassHealthCheckInvalid(t *testing.T) {
+	opts := defaultPassOptions()
+	opts.apply(WithPassHealthCheck(time.Millisecond*500, time.Millisecond*50))
+	if opts.healthCheckInterval != 5*time.Second {
+		t.Errorf("invalid interval should not be applied")
+	}
+	if opts.healthCheckTimeout != 3*time.Second {
+		t.Errorf("invalid timeout should not be applied")
+	}
+}
+
+func TestWithPassMiddlewares(t *testing.T) {
+	m1 := func(c *gin.Context) {}
+	m2 := func(c *gin.Context) {}
+	opts := defaultPassOptions()
+	opts.apply(WithPassMiddlewares(m1, m2))
+
+	if len(opts.passMiddlewares) != 2 {
+		t.Errorf("expected 2 middlewares, got %d", len(opts.passMiddlewares))
+	}
+}