pilot

package module
v1.0.8 Latest Latest
Warning

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

 Go to latest Published: Jan 17, 2026 License: MIT Imports: 43 Imported by: 0

README

Pilot

Pilot Logo Go Version License Build Status

🚀 A high-performance gRPC dynamic gateway

It provides an intelligent proxy from HTTP to gRPC, supporting dynamic service discovery, load balancing, and automatic route generation.

🌐 Language / 语言

Language 文档
🇺🇸 English English Documentation
🇨🇳 简体中文 中文文档

✨ Quick Features

🌐 Core Features
  • HTTP to gRPC Proxy: Seamlessly converts HTTP requests to gRPC calls
  • Dynamic Route Generation: Automatically generates HTTP routing rules based on protobuf annotations
  • Service Discovery: Supports etcd as service registry
  • Load Balancing: Intelligent load balancing based on consistent hashing
  • Hot Updates: Service registration/deregistration without gateway restart
🛡️ High Availability Features
  • Health Check: Automatically detects service instance health status
  • Failover: Automatic switching when service instances fail
  • Connection Pool Management: Efficient gRPC connection reuse
  • Graceful Shutdown: Supports zero-downtime updates
🚀 Performance Optimizations
  • Object Pooling: Reduces memory allocation and GC pressure
  • Concurrency Control: Performance guarantees under high concurrency
  • Caching Mechanism: Route information and method descriptor caching
  • Stream Processing: Supports large file transfers

🏗️ Architecture Overview

graph TB
    A[HTTP Client] --> B[Pilot Gateway]
    B --> C[Router]
    B --> D[Service Discovery]
    D --> E[etcd Cluster]
    
    C --> F[Load Balancer]
    F --> G[Service Instance 1]
    F --> H[Service Instance 2]
    F --> I[Service Instance N]
    
    subgraph "Pilot Core"
        C
        D
        F
    end
    
    subgraph "Backend Services"
        G
        H
        I
    end

🚀 Quick Start

Requirements
  • Go 1.25+
  • etcd 3.6+
  • Protocol Buffers 3.x
Installation
# Clone the project
git clone https://github.com/kieran091/pilot.git
cd pilot

# Install dependencies
go mod tidy

# Build
go build -o pilot
Basic Usage
  1. Define your gRPC service with HTTP annotations
  2. Start your gRPC server with service registration
  3. Launch Pilot gateway
  4. Make HTTP requests that automatically proxy to gRPC

For detailed documentation, please choose your language above.

🌳 Advanced Features

  • RCU-Based Prefix Tree: High-performance routing with lock-free reads
  • Consistent Hashing: Intelligent load balancing across service instances
  • Dynamic Configuration: Hot reload of routing rules and service topology
  • Protocol Buffer Caching: Efficient method descriptor management
  • Comprehensive Middleware: Authentication, logging, rate limiting support

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⭐ If this project helps you, please give us a Star!

Made with ❤️ by Pilot Team

Documentation

Overview

Package pilot

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config 

type Config struct {
	Server    *ServerConfig           `json:"server" yaml:"server"`
	Discovery *ServiceDiscoveryConfig `json:"discovery" yaml:"discovery"`
}

type ConsistentHash 

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

ConsistentHash implements a consistent hashing mechanism for load balancing.

func NewConsistentHash 

func NewConsistentHash(replicas int) *ConsistentHash

type Context 

type Context struct {
	Request *http.Request
	Writer  *responseWriter
	// contains filtered or unexported fields
}

func NewContext 

func NewContext(w http.ResponseWriter, r *http.Request) *Context

func (*Context) Abort 

func (c *Context) Abort()

func (*Context) AddError 

func (c *Context) AddError(err error)

func (*Context) ClientIP added in v1.0.4 

func (c *Context) ClientIP() string

func (*Context) Duration 

func (c *Context) Duration() time.Duration

func (*Context) Get 

func (c *Context) Get(key string) (any, bool)

func (*Context) GetMethodName 

func (c *Context) GetMethodName() string

func (*Context) GetService 

func (c *Context) GetService() string

func (*Context) IsAborted 

func (c *Context) IsAborted() bool

func (*Context) Next 

func (c *Context) Next()

func (*Context) Param 

func (c *Context) Param(key string) string

func (*Context) Set 

func (c *Context) Set(key string, value any)

func (*Context) SetMethodName 

func (c *Context) SetMethodName(methodName string)

func (*Context) SetParams 

func (c *Context) SetParams(key, value string)

func (*Context) SetService 

func (c *Context) SetService(service string)

type Engine 

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

func NewEngine 

func NewEngine(cfg *Config, opts ...EngineOption) (*Engine, error)

func (*Engine) Start 

func (e *Engine) Start() error

func (*Engine) Stop 

func (e *Engine) Stop() error

func (*Engine) Use 

func (e *Engine) Use(mw ...HandlerFunc)

type EngineOption 

type EngineOption func(*Engine)

func WithContext 

func WithContext(ctx context.Context) EngineOption

func WithWatcher 

func WithWatcher(w discovery.Watcher) EngineOption

type EtcdRegistryConfig added in v1.0.4 

type EtcdRegistryConfig struct {
	Endpoints     []string      `json:"endpoints" yaml:"endpoints"`
	DiscoveryPath string        `json:"discoveryPath" yaml:"discoveryPath"`
	DialTimeout   time.Duration `json:"dialTimeout" yaml:"dialTimeout"`
}

type GRPCInvoker 

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

GRPCInvoker is a dynamic gRPC client that can invoke methods based on protobuf descriptors.

func NewGRPCInvoker 

func NewGRPCInvoker(addr string, fds *descriptorpb.FileDescriptorSet) (*GRPCInvoker, error)

func (*GRPCInvoker) Close 

func (inv *GRPCInvoker) Close() error

Close closes the underlying gRPC connection.

func (*GRPCInvoker) Invoke 

func (inv *GRPCInvoker) Invoke(ctx context.Context, service, method string, input []byte) ([]byte, error)

Invoke calls a gRPC method by its name with the given input in JSON format. It returns the response in JSON format.

type HandlerFunc 

type HandlerFunc func(ctx *Context)

func Log 

func Log() HandlerFunc

func Recovery 

func Recovery() HandlerFunc

type InvokerFunc 

type InvokerFunc func(ctx *Context, key string, input []byte) ([]byte, error)

type MethodInfo 

type MethodInfo struct {
	MethodDesc protoreflect.MethodDescriptor
	InputDesc  protoreflect.MessageDescriptor
	OutputDesc protoreflect.MessageDescriptor
	FullMethod string
	// contains filtered or unexported fields
}

MethodInfo holds information about a gRPC method, including its descriptors and message pools.

type NodeType 

type NodeType uint8
const (
	Static NodeType = iota
	Param
	Wildcard
)

type RegisterOption 

type RegisterOption func(registrar *ServiceRegistrar)

RegisterOption defines options for service registration

func WithFile 

func WithFile(filePath string) RegisterOption

WithFile adds a proto file to be compiled for service registration

func WithProtoPath 

func WithProtoPath(protoPath string) RegisterOption

WithProtoPath adds a proto import path for the compiler to resolve imports

type Route 

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

Route represents an Server-to-gRPC routing configuration

type RouteTree 

type RouteTree[T any] struct {
	// contains filtered or unexported fields
}

func NewRouteTree 

func NewRouteTree[T any]() *RouteTree[T]

func (*RouteTree[T]) Delete 

func (r *RouteTree[T]) Delete(path string) bool

func (*RouteTree[T]) Insert 

func (r *RouteTree[T]) Insert(path string, val T) error

func (*RouteTree[T]) Lookup 

func (r *RouteTree[T]) Lookup(path string) (T, map[string]string, bool)

func (*RouteTree[T]) Update 

func (r *RouteTree[T]) Update(path string, updater func(old T) (T, bool)) bool

type Router 

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

Router manages Server-to-gRPC routing with service discovery and load balancing

func NewRouter 

func NewRouter() *Router

func (*Router) Close 

func (r *Router) Close()

Close gracefully shuts down the router and all its service endpoints

func (*Router) ServeHTTP 

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

type ServerConfig added in v1.0.4 

type ServerConfig struct {
	Addr           string        `json:"addr" yaml:"addr"`
	ReadTimeout    time.Duration `json:"readTimeout" yaml:"readTimeout"`
	WriteTimeout   time.Duration `json:"writeTimeout" yaml:"writeTimeout"`
	MaxHeaderBytes int           `json:"maxHeaderBytes" yaml:"maxHeaderBytes"`
	MaxBodyBytes   int           `json:"maxBodyBytes" yaml:"maxBodyBytes"`
}

type ServiceDiscoveryConfig added in v1.0.4 

type ServiceDiscoveryConfig struct {
	Mode discovery.Mode      `json:"mode" yaml:"mode"`
	Etcd *EtcdRegistryConfig `json:"etcd" yaml:"etcd"`
}

type ServiceEndpoint 

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

ServiceEndpoint manages multiple instances of a service with load balancing

func (*ServiceEndpoint) Close 

func (se *ServiceEndpoint) Close()

func (*ServiceEndpoint) GetInvoker 

func (se *ServiceEndpoint) GetInvoker(service, method string) InvokerFunc

GetInvoker returns an InvokerFunc that uses consistent hashing to select the appropriate service instance.

type ServiceRegistrar 

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

func NewServiceRegistrar 

func NewServiceRegistrar(serviceName, listenOn string, registry discovery.Registry) *ServiceRegistrar

func (*ServiceRegistrar) Deregister 

func (sr *ServiceRegistrar) Deregister(ctx context.Context) error

Deregister removes the service registration

func (*ServiceRegistrar) Register 

func (sr *ServiceRegistrar) Register(ctx context.Context, opts ...RegisterOption) error

Register compiles the proto files, extracts Server rules, and registers the service

type ServiceRegistry 

type ServiceRegistry map[string]*ServiceEndpoint

ServiceRegistry maps service names to their corresponding endpoints

Source Files

View all Source files

Directories

Path Synopsis
etcd
example
apps/gateway command
apps/user command
apps/user/pb/user

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.