client

Documentation

Index

• Constants
• func ApplyTunnelSpecToAuthentication(auth *Authentication, spec *TunnelSpec) error
• func MatchTunnelSpecIndex(auth *Authentication, specs []TunnelSpec) int
• func ParseUpstream(upstream string) (host string, port int, err error)
• func SyncOptsFromTunnelSpec(o *Options, spec *TunnelSpec) error
• type AlertConfig
• type AuthenticateResponse
• type Authentication
  • func AuthSnapshotFromOptions(o *Options) *Authentication
• type BinaryMessage
• type Capabilities
  • func GetClientCapabilities(version string) *Capabilities
• type CapabilityFeatures
• type ChunkSizeFeatures
• type Client
  • func New(opts *Options) *Client
  • func (c *Client) Run() error
• type CompressionFeatures
• type Config
• type FlowControlFeatures
• type HTTPIncomingAuthRule
• type HTTPTunnelAuth
• type NotificationConfig
• type Options
  • func ChildOptionsFromSpec(base *Options, spec *TunnelSpec) (*Options, error)
• type RequestData
• type ResponseData
• type TCPConnectData
• type TCPData
• type TCPReadyData
• type TunnelSpec

Constants

const (
	CapabilityFlagBinaryProtocol = 1 << iota
	CapabilityFlagCompression
	CapabilityFlagStreaming
	CapabilityFlagFlowControl
	CapabilityFlagHTTPBinary
	CapabilityFlagHTTPStreaming
	CapabilityFlagTCPOverWS
	CapabilityFlagTCPMultiplex
	CapabilityFlagHTTPBodyStream // semantic HTTP head+body chunking (not WS-level message chunking)
)

CapabilityFlags represents protocol capability flags

Functions

func ApplyTunnelSpecToAuthentication

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

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

func MatchTunnelSpecIndex

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

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

func ParseUpstream

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

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

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

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

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
	Port                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

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

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 -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).