client

package
v1.29.4 Latest Latest
Warning

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

 Go to latest Published: Jun 12, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CapabilityFlagBinaryProtocol = 1 << iota
	CapabilityFlagCompression
	CapabilityFlagStreaming
	CapabilityFlagFlowControl
	CapabilityFlagHTTPBinary
	CapabilityFlagHTTPStreaming
	CapabilityFlagTCPOverWS
	CapabilityFlagTCPMultiplex
	CapabilityFlagHTTPBodyStream // semantic HTTP head+body chunking (not WS-level message chunking)
	// CapabilityFlagTCPEarlyStreamRegister: client registers a TCP stream placeholder when the
	// per-stream data channel opens (before tcp:connect). New servers skip a relay-setup delay when
	// this is negotiated; old clients omit it and rely on tcp:connect ordering + slack delay.
	CapabilityFlagTCPEarlyStreamRegister
)

CapabilityFlags represents protocol capability flags

Variables

This section is empty.

Functions

func ApplyTunnelSpecToAuthentication added in v1.28.0 

func ApplyTunnelSpecToAuthentication(auth *Authentication, spec *TunnelSpec) error

ApplyTunnelSpecToAuthentication overwrites auth tunnel fields from a server YAML spec (monitor handshake).

func MatchTunnelSpecIndex added in v1.28.0 

func MatchTunnelSpecIndex(auth *Authentication, specs []TunnelSpec) int

MatchTunnelSpecIndex returns the index of the tunnel spec that matches the incoming auth, or -1.

func ParseUpstream added in v1.28.0 

func ParseUpstream(upstream string) (host string, port int, err error)

ParseUpstream parses an upstream like the CLI: port only ("9000") or "host:port".

func SyncOptsFromTunnelSpec added in v1.28.0 

func SyncOptsFromTunnelSpec(o *Options, spec *TunnelSpec) error

SyncOptsFromTunnelSpec updates client Options from a server tunnel spec (bootstrap session).

Types

type AlertConfig 

type AlertConfig struct {
	Provider string `json:"provider"`
	URL      string `json:"url"`
	Interval int    `json:"interval,omitempty"`
}

type AuthenticateResponse 

type AuthenticateResponse struct {
	OK          bool    `json:"ok"`
	Message     string  `json:"message,omitempty"`
	Version     string  `json:"version,omitempty"`
	URL         string  `json:"url,omitempty"`
	Config      *Config `json:"config,omitempty"`
	ClientId    string  `json:"clientId,omitempty"`    // Client ID from server
	ContainerId string  `json:"containerId,omitempty"` // Container ID from server
}

type Authentication 

type Authentication struct {
	Version      string        `json:"version"`
	Type         string        `json:"type"`
	Port         int           `json:"port"`
	SubDomain    string        `json:"subDomain,omitempty"`
	TunnelPort   int           `json:"tunnelPort,omitempty"`
	Timestamp    int64         `json:"timestamp"`
	AuthType     string        `json:"authType,omitempty"`
	ClientId     string        `json:"clientId,omitempty"`
	Signature    string        `json:"signature"`
	Capabilities *Capabilities `json:"capabilities,omitempty"`
	OpaqueChild  bool          `json:"opaqueChild,omitempty"`
	// HTTPIngressBasic: when the server tunnel spec does not define edge auth, enforce this Basic policy on the public URL (same credentials the client uses toward upstream).
	HTTPIngressBasic *HTTPTunnelAuth `json:"httpIngressBasic,omitempty"`
}

func AuthSnapshotFromOptions added in v1.28.0 

func AuthSnapshotFromOptions(o *Options) *Authentication

AuthSnapshotFromOptions builds a minimal Authentication for matching this process against server tunnel rows.

type BinaryMessage 

type BinaryMessage struct {
	Type     uint8  // Message type
	StreamID string // Stream ID
	Sequence uint32 // Sequence number
	Flags    uint8  // Flags
	Data     []byte // Payload data
}

BinaryMessage represents a binary protocol message

type Capabilities 

type Capabilities struct {
	Flags    int                 `json:"flags"`
	Version  string              `json:"version"`
	Features *CapabilityFeatures `json:"features,omitempty"`
}

func GetClientCapabilities 

func GetClientCapabilities(version string) *Capabilities

GetClientCapabilities returns the client capabilities based on version For version 2.0.0+, returns full capabilities For older versions, returns nil (legacy protocol)

type CapabilityFeatures 

type CapabilityFeatures struct {
	Compression *CompressionFeatures `json:"compression,omitempty"`
	ChunkSize   *ChunkSizeFeatures   `json:"chunkSize,omitempty"`
	FlowControl *FlowControlFeatures `json:"flowControl,omitempty"`
}

type ChunkSizeFeatures 

type ChunkSizeFeatures struct {
	Min     int `json:"min"`
	Max     int `json:"max"`
	Default int `json:"default"`
}

type Client 

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

Client wraps a websocket tunnel session and manages forwarding/heartbeat.

func New 

func New(opts *Options) *Client

New constructs a Client with sane defaults.

func (*Client) Run 

func (c *Client) Run() error

Run boots the websocket tunnel and blocks until an unrecoverable error happens.

type CompressionFeatures 

type CompressionFeatures struct {
	Algorithms []string `json:"algorithms"`
	Preferred  string   `json:"preferred,omitempty"`
}

type Config 

type Config struct {
	Version                string              `json:"version,omitempty"`
	Notification           *NotificationConfig `json:"notification,omitempty"`
	NegotiatedCapabilities *Capabilities       `json:"negotiatedCapabilities,omitempty"`
	Tunnels                []TunnelSpec        `json:"tunnels,omitempty"`
}

type FlowControlFeatures 

type FlowControlFeatures struct {
	WindowSize int `json:"windowSize"`
}

type HTTPIncomingAuthRule added in v1.28.0 

type HTTPIncomingAuthRule struct {
	Enable bool             `yaml:"enable" json:"enable"`
	Users  []HTTPTunnelAuth `yaml:"users" json:"users,omitempty"`
}

HTTPIncomingAuthRule controls incoming Authorization checks for tunneled HTTP requests.

type HTTPTunnelAuth added in v1.28.0 

type HTTPTunnelAuth struct {
	Type     string `yaml:"type" json:"type"` // basic | bearer
	Username string `yaml:"username" json:"username,omitempty"`
	Password string `yaml:"password" json:"password,omitempty"`
	Token    string `yaml:"token" json:"token,omitempty"`
}

HTTPTunnelAuth configures allowed Authorization values for incoming HTTP requests at the server.

type NotificationConfig 

type NotificationConfig struct {
	Provider string       `json:"provider"`
	URL      string       `json:"url"`
	Interval int          `json:"interval,omitempty"`
	Alert    *AlertConfig `json:"alert,omitempty"`
}

type Options 

type Options struct {
	Type             string
	UpstreamHost     string
	UpstreamPort     int
	UpstreamUsername string // HTTP tunnel: Basic auth when dialing upstream (optional)
	UpstreamPassword string
	AuthType         string
	Token            string
	ClientId         string
	ClientSecret     string
	SubDomain        string
	// TunnelPort is the public TCP port the server should listen on for type=tcp (0 = server assigns).
	TunnelPort          int
	Server              string
	Remote              string
	RemoteTCPPort       int
	HealthcheckInt      int
	ReportURL           string
	Version             string
	ReconnectMaxRetries int           // Maximum number of reconnection retries, default 1000
	ReconnectInterval   time.Duration // Interval between reconnection attempts, default 3s
	// OpaqueChild: true for sessions auto-spawned from server tunnel list (do not re-spawn; auth omits tunnel list).
	OpaqueChild bool
}

func ChildOptionsFromSpec added in v1.28.0 

func ChildOptionsFromSpec(base *Options, spec *TunnelSpec) (*Options, error)

ChildOptionsFromSpec builds options for an additional monitor session from a server tunnel spec.

type RequestData 

type RequestData struct {
	ID   string `json:"id"`
	Data string `json:"data"`
}

type ResponseData 

type ResponseData struct {
	ID   string `json:"id"`
	Data string `json:"data"`
}

type TCPConnectData 

type TCPConnectData struct {
	ID        string `json:"id"`
	RequestID string `json:"requestId"`
	IP        string `json:"ip"`
}

type TCPData 

type TCPData struct {
	StreamID string `json:"streamId"`
	Data     string `json:"data"`
}

type TCPReadyData 

type TCPReadyData struct {
	Host string `json:"host"`
	Port int    `json:"port"`
}

type TunnelSpec added in v1.28.0 

type TunnelSpec struct {
	Name       string                `yaml:"name" json:"name"`
	Type       string                `yaml:"type" json:"type"`
	Upstream   string                `yaml:"upstream" json:"upstream"`
	SubDomain  string                `yaml:"subDomain" json:"subDomain,omitempty"`   // HTTP: empty = use client `http -s` (or server-assigned when both empty)
	RemotePort int                   `yaml:"remotePort" json:"remotePort,omitempty"` // TCP: 0 or omit = use client `tcp -p`; else pin public listen port on server
	Auth       *HTTPIncomingAuthRule `yaml:"auth" json:"auth,omitempty"`             // HTTP: optional auth policy validated at server before forwarding.
	// Deprecated: use auth.enable + auth.users.
	Auths []HTTPTunnelAuth `yaml:"auths" json:"auths,omitempty"`
}

TunnelSpec is a declared tunnel for a client (server YAML and authenticate config payload).

Source Files

View all Source files

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.