client

package
v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Apr 15, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// ConfigDirName is the name of the configuration directory.
	ConfigDirName = ".wormhole"
	// ConfigFileName is the name of the configuration file.
	ConfigFileName = "config.yaml"
)

Variables

This section is empty.

Functions

func ApplyPersistentConfig

func ApplyPersistentConfig(cfg *Config, persistent *PersistentConfig, flags *FlagValues)

ApplyPersistentConfig applies the persistent configuration to the runtime config. Command-line flags take precedence over persistent config.

func ClearToken

func ClearToken() error

ClearToken removes the saved token from persistent config.

func SavePersistentConfig

func SavePersistentConfig(cfg *PersistentConfig) error

SavePersistentConfig saves the persistent configuration to disk.

func UpdatePersistentConfig

func UpdatePersistentConfig(cfg *Config, saveToken bool) error

UpdatePersistentConfig updates the persistent config from the runtime config. This is typically called after successful authentication to save the token.

Types

type ActiveTunnel added in v0.6.0

type ActiveTunnel struct {
	Def       TunnelDef
	TunnelID  string
	PublicURL string
	TCPPort   uint32
}

Client is the wormhole client. ActiveTunnel holds runtime state for a registered tunnel.

type Client

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

func NewClient

func NewClient(config Config) *Client

NewClient creates a new client instance.

func (*Client) Close

func (c *Client) Close() error

Close closes the client. It performs graceful shutdown by sending a CloseRequest to the server before tearing down the connection.

func (*Client) CloseTunnel added in v0.4.2

func (c *Client) CloseTunnel(ctx context.Context, tunnelID, reason string) error

CloseTunnel sends a CloseRequest to the server to gracefully close a tunnel.

func (*Client) GetInspector

func (c *Client) GetInspector() *inspector.Inspector

GetInspector returns the inspector instance.

func (*Client) GetP2PManager

func (c *Client) GetP2PManager() *p2p.Manager

GetP2PManager returns the P2P manager instance.

func (*Client) GetStats

func (c *Client) GetStats() Stats

GetStats returns client statistics.

func (*Client) IsConnected

func (c *Client) IsConnected() bool

IsConnected returns whether the client is connected.

func (*Client) IsP2PMode

func (c *Client) IsP2PMode() bool

IsP2PMode returns whether the client is using P2P mode.

func (*Client) ListActiveTunnels added in v0.6.0

func (c *Client) ListActiveTunnels() []ActiveTunnel

ListActiveTunnels returns a copy of the currently active tunnels.

func (*Client) ReloadTunnels added in v0.6.0

func (c *Client) ReloadTunnels(ctx context.Context, newDefs []TunnelDef)

ReloadTunnels updates the active tunnel set based on a new list of definitions. New tunnels are registered; removed tunnels are closed via CloseRequest. This is designed to be called when a SIGHUP reloads the config file.

func (*Client) RequestStats added in v0.4.2

func (c *Client) RequestStats(ctx context.Context) (*proto.StatsResponse, error)

RequestStats sends a StatsRequest to the server and returns the session statistics.

func (*Client) Start

func (c *Client) Start(ctx context.Context) error

Start starts the client.

func (*Client) StartControlServer added in v0.6.0

func (c *Client) StartControlServer(ctrlHost string, ctrlPort int) error

StartControlServer starts a lightweight HTTP control server that exposes the running client's tunnel state for use by `wormhole tunnels list`.

The server binds to ctrlHost:ctrlPort. If ctrlPort is 0 this is a no-op.

func (*Client) StartInspector

func (c *Client) StartInspector(port int) error

StartInspector starts the inspector UI server.

type Config

type Config struct {
	// ServerAddr is the server address to connect to.
	ServerAddr string

	// LocalPort is the local port to expose.
	LocalPort int

	// LocalHost is the local host to forward to.
	LocalHost string

	// Subdomain is the requested subdomain (optional).
	Subdomain string

	// Token is the authentication token (optional).
	Token string

	// InspectorPort is the port for the inspector UI (0 to disable).
	InspectorPort int

	// InspectorHost is the host the inspector UI binds to (default: 127.0.0.1).
	InspectorHost string

	// TLSEnabled enables TLS for server connection.
	TLSEnabled bool

	// TLSInsecure skips TLS certificate verification.
	TLSInsecure bool

	// TLSCACert is the path to a custom CA certificate for verifying the server.
	TLSCACert string

	// Protocol is the tunnel protocol type (e.g. "http", "tcp", "udp", "ws", "grpc").
	// Defaults to "http" if empty.
	Protocol string

	// Hostname is the custom hostname for routing (optional).
	Hostname string

	// PathPrefix is the path-based routing prefix (optional).
	PathPrefix string

	// MuxConfig is the multiplexer configuration.
	MuxConfig tunnel.MuxConfig

	// ReconnectInterval is the initial reconnect interval.
	ReconnectInterval time.Duration

	// MaxReconnectInterval is the maximum reconnect interval.
	MaxReconnectInterval time.Duration

	// ReconnectBackoff is the backoff multiplier for reconnection.
	ReconnectBackoff float64

	// MaxReconnectAttempts is the maximum number of reconnection attempts (0 for unlimited).
	MaxReconnectAttempts int

	// HeartbeatInterval is the interval between heartbeats.
	HeartbeatInterval time.Duration

	// HeartbeatTimeout is the timeout for heartbeat responses.
	HeartbeatTimeout time.Duration

	// P2PEnabled enables P2P direct connection attempts.
	P2PEnabled bool

	// P2PConfig is the P2P manager configuration.
	P2PConfig p2p.ManagerConfig

	// Tunnels holds additional tunnel definitions for multi-tunnel mode.
	// When non-empty, all tunnels are registered during connect.
	// The primary tunnel (LocalPort/Protocol/etc.) is still registered first
	// if LocalPort > 0; additional ones come from this slice.
	Tunnels []TunnelDef

	// CtrlPort is the port for the local control HTTP server.
	// 0 disables the control server (default).
	// The control server exposes /tunnels for `wormhole tunnels list`.
	CtrlPort int

	// CtrlHost is the host the control server binds to (default: 127.0.0.1).
	CtrlHost string
}

Config holds the client configuration.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the default client configuration.

type FileConfig added in v0.6.0

type FileConfig struct {
	// Server is the wormhole server address (host:port).
	Server string `yaml:"server"`

	// TLS enables TLS for the control connection.
	TLS bool `yaml:"tls"`

	// TLSInsecure skips certificate verification (dev only).
	TLSInsecure bool `yaml:"tls_insecure"`

	// TLSCACert is the path to a custom CA certificate.
	TLSCACert string `yaml:"tls_ca"`

	// Token is the authentication token.
	Token string `yaml:"token"`

	// P2P enables P2P connections (default true).
	P2P *bool `yaml:"p2p"`

	// CtrlPort is the local control server port (0 = disabled).
	CtrlPort int `yaml:"ctrl_port"`

	// CtrlHost is the local control server host (default: 127.0.0.1).
	CtrlHost string `yaml:"ctrl_host"`

	// Tunnels maps tunnel names to their definitions.
	Tunnels map[string]FileTunnelDef `yaml:"tunnels"`
}

FileConfig is the YAML schema for a wormhole configuration file.

Example:

server: tunnel.example.com:7000
tls: true
token: my-team-token

tunnels:
  web:
    local_port: 8080
    protocol: http
    subdomain: myapp
  api:
    local_port: 3000
    hostname: api.example.com
  db:
    local_port: 5432
    protocol: tcp

func LoadFileConfig added in v0.6.0

func LoadFileConfig(path string) (*FileConfig, error)

LoadFileConfig reads and parses a YAML configuration file.

func (*FileConfig) ToClientConfig added in v0.6.0

func (fc *FileConfig) ToClientConfig(base Config) Config

ToClientConfig converts a FileConfig into a client.Config. The first tunnel (alphabetically) becomes the primary tunnel; remaining tunnels are placed in Config.Tunnels.

type FileTunnelDef added in v0.6.0

type FileTunnelDef struct {
	// LocalPort is the local port to expose.
	LocalPort int `yaml:"local_port"`

	// LocalHost is the local host to forward to (default: 127.0.0.1).
	LocalHost string `yaml:"local_host"`

	// Protocol is the tunnel protocol (default: http).
	Protocol string `yaml:"protocol"`

	// Subdomain requests a specific subdomain.
	Subdomain string `yaml:"subdomain"`

	// Hostname is a custom hostname for routing.
	Hostname string `yaml:"hostname"`

	// PathPrefix is a path-based routing prefix.
	PathPrefix string `yaml:"path_prefix"`
}

FileTunnelDef is the YAML schema for a single tunnel definition.

type FlagValues

type FlagValues struct {
	ServerAddrSet    bool
	TokenSet         bool
	SubdomainSet     bool
	TLSSet           bool
	TLSInsecureSet   bool
	TLSCACertSet     bool
	InspectorPortSet bool
	P2PEnabledSet    bool
}

FlagValues tracks which command-line flags were explicitly set.

type PersistentConfig

type PersistentConfig struct {
	// ServerAddr is the default server address.
	ServerAddr string `yaml:"server_addr,omitempty"`

	// Token is the authentication token.
	Token string `yaml:"token,omitempty"`

	// Subdomain is the preferred subdomain.
	Subdomain string `yaml:"subdomain,omitempty"`

	// TLSEnabled enables TLS for server connection.
	TLSEnabled bool `yaml:"tls_enabled,omitempty"`

	// TLSInsecure skips TLS certificate verification.
	TLSInsecure bool `yaml:"tls_insecure,omitempty"`

	// InspectorPort is the default inspector UI port.
	InspectorPort int `yaml:"inspector_port,omitempty"`

	// P2PEnabled enables P2P direct connection attempts.
	P2PEnabled *bool `yaml:"p2p_enabled,omitempty"`
}

PersistentConfig represents the configuration that is persisted to disk. Only a subset of Config fields are persisted (user-facing settings).

func LoadPersistentConfig

func LoadPersistentConfig() (*PersistentConfig, error)

LoadPersistentConfig loads the persistent configuration from disk. Returns an empty config if the file doesn't exist.

type Stats

type Stats struct {
	BytesIn        uint64
	BytesOut       uint64
	Requests       uint64
	Reconnects     uint64
	ConnectionTime time.Time
}

Stats contains client statistics.

type TunnelDef added in v0.6.0

type TunnelDef struct {
	// Name is the unique identifier for this tunnel definition.
	Name string

	// LocalPort is the local port to expose.
	LocalPort int

	// LocalHost is the local host to forward to (defaults to 127.0.0.1).
	LocalHost string

	// Protocol is the tunnel protocol: http, tcp, udp, ws, grpc (default: http).
	Protocol string

	// Subdomain is the requested subdomain (optional).
	Subdomain string

	// Hostname is a custom hostname for routing (optional).
	Hostname string

	// PathPrefix is a path-based routing prefix (optional).
	PathPrefix string
}

TunnelDef describes a single tunnel in multi-tunnel mode (config file).

type TunnelInfo added in v0.6.0

type TunnelInfo struct {
	Name      string `json:"name"`
	TunnelID  string `json:"tunnel_id"`
	PublicURL string `json:"public_url"`
	LocalPort int    `json:"local_port"`
	LocalHost string `json:"local_host"`
	Protocol  string `json:"protocol"`
	TCPPort   uint32 `json:"tcp_port,omitempty"`
}

TunnelInfo is the JSON representation of an active tunnel for the control API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL