gravity

package
v1.0.138 Latest Latest
Warning

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

 Go to latest Published: Jan 13, 2026 License: MIT Imports: 35 Imported by: 0

README

Gravity Client

Generic gRPC client for connecting to Gravity servers. This package was extracted from the hadron project to enable reuse across multiple tools and projects.

Package Structure

  • gravity/ - Main gravity client implementation
  • gravity/proto/ - Protocol buffer definitions and generated code
  • gravity/provider/ - Provider interface definitions
  • gravity/network/ - Network interface definitions
  • gravity/api/ - API helper utilities

Module Path Conventions

All packages use the base module path: github.com/agentuity/go-common

  • Proto package: github.com/agentuity/go-common/gravity/proto
  • Provider interfaces: github.com/agentuity/go-common/gravity/provider
  • Network interfaces: github.com/agentuity/go-common/gravity/network
  • API utilities: github.com/agentuity/go-common/gravity/api

Usage

import (
    "github.com/agentuity/go-common/gravity"
    "github.com/agentuity/go-common/gravity/provider"
    "github.com/agentuity/go-common/gravity/network"
)

// Create gravity client with your provider and network implementations
config := gravity.GravityConfig{
    Provider:     myProvider,
    NetworkInterface: myNetworkInterface,
    // ... other config
}

client, err := gravity.New(config)
if err != nil {
    return err
}

if err := client.Start(); err != nil {
    return err
}

Documentation

Index

Constants

View Source 
const (
	StateClosed   = resilience.StateClosed
	StateHalfOpen = resilience.StateHalfOpen
	StateOpen     = resilience.StateOpen
)

Variables

View Source 
var (
	ErrCircuitBreakerOpen    = resilience.ErrCircuitBreakerOpen
	ErrCircuitBreakerTimeout = resilience.ErrCircuitBreakerTimeout
	ErrTooManyFailures       = resilience.ErrTooManyFailures
)
View Source 
var (
	DefaultRetryConfig          = resilience.DefaultRetryConfig
	DefaultRetryableErrors      = resilience.DefaultRetryableErrors
	Retry                       = resilience.Retry
	RetryWithCircuitBreaker     = resilience.RetryWithCircuitBreaker
	ExponentialBackoff          = resilience.ExponentialBackoff
	LinearBackoff               = resilience.LinearBackoff
	RetryWithStats              = resilience.RetryWithStats
	NewCircuitBreaker           = resilience.NewCircuitBreaker
	DefaultCircuitBreakerConfig = resilience.DefaultCircuitBreakerConfig
)

Re-export functions for backward compatibility

View Source 
var ErrConnectionClosed = errors.New("gravity connection closed")

Error variables for consistency with old implementation

Functions

func Provision added in v1.0.96 

func Provision(request ProvisionRequest) (*pb.ProvisionResponse, error)

Provision calls the Provision gRPC method with TLS verification disabled This is a standalone method that should be used for initial provisioning

Types

type CircuitBreaker 

type CircuitBreaker = resilience.CircuitBreaker

Re-export types and functions from resilience package for backward compatibility

type CircuitBreakerConfig 

type CircuitBreakerConfig = resilience.CircuitBreakerConfig

Re-export types and functions from resilience package for backward compatibility

type CircuitBreakerState 

type CircuitBreakerState = resilience.CircuitBreakerState

Re-export types and functions from resilience package for backward compatibility

type CircuitBreakerStats 

type CircuitBreakerStats = resilience.CircuitBreakerStats

Re-export types and functions from resilience package for backward compatibility

type ConnectionPoolConfig 

type ConnectionPoolConfig struct {
	// Connection pool size (4-8 connections as per PLAN.md)
	PoolSize int

	// Streams per connection for packet multiplexing
	StreamsPerConnection int

	// Stream allocation strategy
	AllocationStrategy StreamAllocationStrategy

	// Health check and failover settings
	HealthCheckInterval time.Duration
	FailoverTimeout     time.Duration
}

ConnectionPoolConfig holds configuration for gRPC connection pool optimization

type ErrorRateSample 

type ErrorRateSample = pb.ErrorRateSample

Type aliases for protobuf types to maintain API compatibility

type GRPCConnectionMetrics 

type GRPCConnectionMetrics = pb.GRPCConnectionMetrics

Type aliases for protobuf types to maintain API compatibility

type GravityClient 

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

GravityClient implements the provider.Server interface using gRPC transport

func New 

func New(config GravityConfig) (*GravityClient, error)

New creates a new gRPC-based Gravity server client

func (*GravityClient) Close 

func (g *GravityClient) Close() error

Close will shutdown the client

func (*GravityClient) Disconnected added in v1.0.102 

func (g *GravityClient) Disconnected(ctx context.Context)

Disconnected will wait for the client to be disconnected or the ctx to be cancelled

func (*GravityClient) GetAPIURL 

func (g *GravityClient) GetAPIURL() string

GetAPIURL returns the API URL received from gravity server

func (*GravityClient) GetConnectionPoolStats 

func (g *GravityClient) GetConnectionPoolStats() map[string]any

GetConnectionPoolStats returns current connection pool statistics for monitoring

func (*GravityClient) GetDeploymentMetadata 

func (g *GravityClient) GetDeploymentMetadata(ctx context.Context, deploymentID, orgID string) (*pb.DeploymentMetadataResponse, error)

GetDeploymentMetadata makes a gRPC call to get deployment metadata This is used by HTTP API server for provision requests

func (*GravityClient) GetHealthScore 

func (g *GravityClient) GetHealthScore() float64

GetHealthScore returns the overall health score (0-100)

func (*GravityClient) GetIPv6Address 

func (g *GravityClient) GetIPv6Address() string

GetIPv6Address returns the IPv6 address for external use

func (*GravityClient) GetInboundPackets 

func (g *GravityClient) GetInboundPackets() <-chan *PooledBuffer

func (*GravityClient) GetSandboxMetadata added in v1.0.138 

func (g *GravityClient) GetSandboxMetadata(ctx context.Context, sandboxID, orgID string, generateCertificate bool) (*pb.SandboxMetadataResponse, error)

GetSandboxMetadata makes a gRPC call to get sandbox metadata This is used by HTTP API server for sandbox creation when a port is specified

func (*GravityClient) GetSecret 

func (g *GravityClient) GetSecret() string

GetSecret returns the authentication secret for external use

func (*GravityClient) GetServerMetrics 

func (g *GravityClient) GetServerMetrics(reset bool) *pb.ServerMetrics

GetServerMetrics returns current server metrics with performance data

func (*GravityClient) GetTLSConfig 

func (g *GravityClient) GetTLSConfig() *tls.Config

GetTLSConfig returns the TLS configuration for external use (like HTTP server)

func (*GravityClient) GetTextMessages 

func (g *GravityClient) GetTextMessages() <-chan *PooledBuffer

func (*GravityClient) IsConnected 

func (g *GravityClient) IsConnected() bool

func (*GravityClient) Pause 

func (g *GravityClient) Pause(reason string) error

Pause sends a pause event to the gravity server

func (*GravityClient) Resume 

func (g *GravityClient) Resume(reason string) error

Resume sends a resume event to the gravity server

func (*GravityClient) SendPacket 

func (g *GravityClient) SendPacket(data []byte) error

func (*GravityClient) SendRouteDeploymentRequest 

func (g *GravityClient) SendRouteDeploymentRequest(deploymentID, hostname, virtualIP string, timeout time.Duration) (*pb.RouteDeploymentResponse, error)

SendRouteDeploymentRequest sends a route deployment request and waits for response (sync)

func (*GravityClient) SendRouteSandboxRequest added in v1.0.136 

func (g *GravityClient) SendRouteSandboxRequest(sandboxID, virtualIP string, timeout time.Duration) (*pb.RouteSandboxResponse, error)

SendRouteSandboxRequest sends a route sandbox request and waits for response (sync)

func (*GravityClient) Start 

func (g *GravityClient) Start() error

Start establishes gRPC connections and starts the client

func (*GravityClient) Unprovision 

func (g *GravityClient) Unprovision(deploymentID string) error

Unprovision sends an unprovision request to the gravity server

func (*GravityClient) WritePacket 

func (g *GravityClient) WritePacket(payload []byte) error

WritePacket sends a tunnel packet via gRPC tunnel stream using load balancing

type GravityConfig 

type GravityConfig struct {
	Context              context.Context
	Logger               logger.Logger
	Provider             provider.Provider
	URL                  string
	Cert                 string
	Key                  string
	CACert               string
	IP4Address           string
	IP6Address           string
	InstanceID           string
	AuthToken            string
	ClientVersion        string
	ClientName           string
	Capabilities         *pb.ClientCapabilities
	PingInterval         time.Duration
	ReportInterval       time.Duration
	WorkingDir           string
	TraceLogPackets      bool
	NetworkInterface     network.NetworkInterface
	ConnectionPoolConfig *ConnectionPoolConfig
	ReportStats          bool
	SkipAutoReconnect    bool
}

GravityConfig contains configuration for the Gravity client

type HealthSample 

type HealthSample = pb.HealthSample

Type aliases for protobuf types to maintain API compatibility

type HistoricalMetrics 

type HistoricalMetrics = pb.HistoricalMetrics

Type aliases for protobuf types to maintain API compatibility

type LatencySample 

type LatencySample = pb.LatencySample

Type aliases for protobuf types to maintain API compatibility

type MessageStatistics 

type MessageStatistics = pb.MessageStatistics

Type aliases for protobuf types to maintain API compatibility

type PooledBuffer 

type PooledBuffer struct {
	Buffer []byte
	Length int
}

PooledBuffer represents a buffer from the pool

type ProvisionRequest added in v1.0.96 

type ProvisionRequest struct {
	Context          context.Context
	GravityURL       string
	InstanceID       string
	Region           string
	AvailabilityZone string
	Provider         string
	PrivateIP        string
	Token            string
	PublicKey        string
	Hostname         string
	ErrorMessage     string
	Ephemeral        bool
	Capabilities     *pb.ClientCapabilities
}

type RetryConfig 

type RetryConfig = resilience.RetryConfig

Re-export types and functions from resilience package for backward compatibility

type RetryStats 

type RetryStats = resilience.RetryStats

Re-export types and functions from resilience package for backward compatibility

type RetryableFunc 

type RetryableFunc = resilience.RetryableFunc

Re-export types and functions from resilience package for backward compatibility

type ServerMetrics 

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

ServerMetrics represents enhanced server performance metrics with gRPC-specific data This wraps the protobuf ServerMetrics with a mutex for thread safety

func NewServerMetrics 

func NewServerMetrics() *ServerMetrics

NewServerMetrics creates a new ServerMetrics instance

func (*ServerMetrics) AddHistoricalSample 

func (sm *ServerMetrics) AddHistoricalSample()

AddHistoricalSample adds a sample to historical data

func (*ServerMetrics) GetHealthScore 

func (sm *ServerMetrics) GetHealthScore() float64

GetHealthScore calculates an overall health score (0-100)

func (*ServerMetrics) GetSnapshot 

func (sm *ServerMetrics) GetSnapshot() *pb.ServerMetrics

GetSnapshot returns a read-only snapshot of current metrics

func (*ServerMetrics) RecordMessage 

func (sm *ServerMetrics) RecordMessage(messageType string, bytes int64, sent bool)

RecordMessage records a message transmission

func (*ServerMetrics) Reset 

func (sm *ServerMetrics) Reset()

Reset resets all metrics to initial state

func (*ServerMetrics) UpdateConnection 

func (sm *ServerMetrics) UpdateConnection(connected bool)

UpdateConnection updates connection-related metrics

func (*ServerMetrics) UpdateGRPCMetrics 

func (sm *ServerMetrics) UpdateGRPCMetrics(grpcMetrics *GRPCConnectionMetrics)

UpdateGRPCMetrics updates gRPC-specific metrics

func (*ServerMetrics) UpdatePerformanceMetrics 

func (sm *ServerMetrics) UpdatePerformanceMetrics(perfMetrics *pb.PerformanceMetrics)

UpdatePerformanceMetrics updates performance metrics from the collector

func (*ServerMetrics) UpdateSystemMetrics 

func (sm *ServerMetrics) UpdateSystemMetrics()

UpdateSystemMetrics updates system resource metrics

type ServerMetricsSnapshot 

type ServerMetricsSnapshot = pb.ServerMetrics

Type aliases for protobuf types to maintain API compatibility

type StreamAllocationStrategy 

type StreamAllocationStrategy int

StreamAllocationStrategy defines how streams are selected for load distribution 

const (
	RoundRobin StreamAllocationStrategy = iota
	HashBased
	LeastConnections
	WeightedRoundRobin
)

func (StreamAllocationStrategy) String 

func (s StreamAllocationStrategy) String() string

String method for StreamAllocationStrategy enum

type StreamInfo 

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

StreamInfo tracks individual stream health and load

type StreamManager 

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

StreamManager manages multiple gRPC streams for multiplexing with advanced load balancing

type StreamMetrics 

type StreamMetrics struct {
	PacketsSent     int64
	PacketsReceived int64
	LastLatency     time.Duration
	ErrorCount      int64
	LastError       time.Time
}

StreamMetrics tracks performance metrics for individual streams

type SystemResourceMetrics 

type SystemResourceMetrics = pb.SystemResourceMetrics

Type aliases for protobuf types to maintain API compatibility

type ThroughputSample 

type ThroughputSample = pb.ThroughputSample

Type aliases for protobuf types to maintain API compatibility

Source Files

View all Source files

Directories

Path Synopsis

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.