client

Documentation

Overview

Package client implements the expose tunnel client that registers with the server, maintains a WebSocket session, and proxies traffic to a local port.

Index

• Variables
• func ResolveMachineID(hostname string) string
• type Client
  • func New(cfg config.ClientConfig, logger *slog.Logger) *Client
  • func (c *Client) Run(ctx context.Context) error
  • func (c *Client) SetAutoUpdate(enabled bool)
  • func (c *Client) SetDisplay(d *Display)
  • func (c *Client) SetLifecycleHooks(hooks LifecycleHooks)
  • func (c *Client) SetLogger(l *slog.Logger)
  • func (c *Client) SetTrafficSink(sink TrafficRecorder)
  • func (c *Client) SetVersion(v string)
• type Display
  • func NewDisplay(color bool) *Display
  • func (d *Display) Cleanup()
  • func (d *Display) LogRequest(method, path string, status int, duration time.Duration, ...)
  • func (d *Display) RecordTraffic(direction traffic.Direction, bytes int64)
  • func (d *Display) SetLocalHealthTarget(localAddr string)
  • func (d *Display) ShowBanner(version string)
  • func (d *Display) ShowInfo(msg string)
  • func (d *Display) ShowLatency(rtt time.Duration)
  • func (d *Display) ShowReconnecting(reason string)
  • func (d *Display) ShowTunnelInfo(publicURL, localAddr, tlsMode, tunnelID string, protected bool, ...)
  • func (d *Display) ShowUpdateStatus(latestVersion string)
  • func (d *Display) ShowVersions(clientVersion, serverVersion string, wafEnabled bool)
  • func (d *Display) ShowWAFStats(blocked int64)
  • func (d *Display) ShowWarning(msg string)
  • func (d *Display) ToggleSessionDetails()
  • func (d *Display) TrackWSClose(id string)
  • func (d *Display) TrackWSOpen(id, path string, headers map[string][]string)
• type LifecycleHooks
• type RegisterFailureEvent
• type SessionDisconnectEvent
• type TrafficRecorder
• type TrafficSinkFunc
  • func (f TrafficSinkFunc) RecordTraffic(direction traffic.Direction, bytes int64)
• type TunnelReadyEvent

Variables

var ErrAutoUpdated = errors.New("binary updated; restart required")

ErrAutoUpdated is returned from Client.Run when the binary was replaced by the auto-updater and the caller should restart the process.

Functions

func ResolveMachineID

func ResolveMachineID(hostname string) string

ResolveMachineID returns a stable machine identifier for client-side naming and registration metadata, falling back to the provided hostname.

Types

type Client

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

Client connects to the expose server and proxies public traffic to a local port.

func New

func New(cfg config.ClientConfig, logger *slog.Logger) *Client

New creates a Client with the given configuration and logger.

func (*Client) Run

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

func (*Client) SetAutoUpdate

func (c *Client) SetAutoUpdate(enabled bool)

SetAutoUpdate enables background self-update. When enabled the client periodically checks for new releases and also reacts to server version changes detected during reconnection. If an update is applied the Run method returns ErrAutoUpdated.

func (*Client) SetDisplay

func (c *Client) SetDisplay(d *Display)

SetDisplay configures the interactive terminal display. When set, the client renders an ngrok-style interface instead of plain structured log output for tunnel status and request logging.

func (*Client) SetLifecycleHooks

func (c *Client) SetLifecycleHooks(hooks LifecycleHooks)

SetLifecycleHooks configures optional callbacks for tunnel lifecycle events.

func (*Client) SetLogger

func (c *Client) SetLogger(l *slog.Logger)

SetLogger replaces the client's logger.

func (*Client) SetTrafficSink

func (c *Client) SetTrafficSink(sink TrafficRecorder)

func (*Client) SetVersion

func (c *Client) SetVersion(v string)

SetVersion sets the client version string for server exchange.

type Display

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

Display renders an ngrok-inspired terminal interface for the tunnel client. It redraws the entire screen on every state change so the header, counters, and request log are always visible. Safe for concurrent use.

func NewDisplay

func NewDisplay(color bool) *Display

NewDisplay creates a Display that writes to stdout. When color is true, ANSI escape codes are used for styling.

func (*Display) Cleanup

func (d *Display) Cleanup()

Cleanup restores the terminal cursor. Call on shutdown.

func (*Display) LogRequest

func (d *Display) LogRequest(method, path string, status int, duration time.Duration, headers map[string][]string)

LogRequest records an HTTP request and redraws. headers is used to extract the client IP (X-Forwarded-For) for tracking unique visitors. Pass nil if headers are not available.

func (*Display) RecordTraffic

func (d *Display) RecordTraffic(direction traffic.Direction, bytes int64)

func (*Display) SetLocalHealthTarget

func (d *Display) SetLocalHealthTarget(localAddr string)

func (*Display) ShowBanner

func (d *Display) ShowBanner(version string)

ShowBanner sets the version string and draws the initial screen.

func (*Display) ShowInfo

func (d *Display) ShowInfo(msg string)

ShowInfo sets the most recent info notice and redraws.

func (*Display) ShowLatency

func (d *Display) ShowLatency(rtt time.Duration)

ShowLatency updates the displayed round-trip latency and redraws.

func (*Display) ShowReconnecting

func (d *Display) ShowReconnecting(reason string)

ShowReconnecting sets the status to reconnecting and redraws.

func (*Display) ShowTunnelInfo

func (d *Display) ShowTunnelInfo(publicURL, localAddr, tlsMode, tunnelID string, protected bool, transport string)

ShowTunnelInfo updates the tunnel connection details and redraws.

func (*Display) ShowUpdateStatus

func (d *Display) ShowUpdateStatus(latestVersion string)

ShowUpdateStatus sets the available update version and redraws. Pass an empty string to indicate the client is up to date.

func (*Display) ShowVersions

func (d *Display) ShowVersions(clientVersion, serverVersion string, wafEnabled bool)

ShowVersions sets the client and server version strings and redraws.

func (*Display) ShowWAFStats

func (d *Display) ShowWAFStats(blocked int64)

ShowWAFStats updates the displayed WAF-blocked request count and redraws.

func (*Display) ShowWarning

func (d *Display) ShowWarning(msg string)

ShowWarning sets the most recent warning notice and redraws.

func (*Display) ToggleSessionDetails

func (d *Display) ToggleSessionDetails()

ToggleSessionDetails shows or hides the extra session detail row.

func (*Display) TrackWSClose

func (d *Display) TrackWSClose(id string)

TrackWSClose removes a WebSocket stream and redraws. A debounced display floor prevents the counter from briefly dipping during a page refresh (close + immediate reopen).

func (*Display) TrackWSOpen

func (d *Display) TrackWSOpen(id, path string, headers map[string][]string)

TrackWSOpen registers a new WebSocket stream and redraws. headers is used to extract the client IP for tracking unique visitors.

type LifecycleHooks

type LifecycleHooks struct {
	OnTunnelReady     func(TunnelReadyEvent)
	OnRegisterFailure func(RegisterFailureEvent)
	OnSessionDrop     func(SessionDisconnectEvent)
}

LifecycleHooks allows callers to observe client lifecycle transitions without scraping log output.

type RegisterFailureEvent

type RegisterFailureEvent struct {
	Err       error
	RetryIn   time.Duration
	WillRetry bool
}

RegisterFailureEvent is emitted when tunnel registration fails.

type SessionDisconnectEvent

type SessionDisconnectEvent struct {
	Err error
}

SessionDisconnectEvent is emitted when an active tunnel session drops and the client will attempt to reconnect.

type TrafficRecorder

type TrafficRecorder interface {
	RecordTraffic(direction traffic.Direction, bytes int64)
}

type TrafficSinkFunc

type TrafficSinkFunc func(direction traffic.Direction, bytes int64)

func (TrafficSinkFunc) RecordTraffic

func (f TrafficSinkFunc) RecordTraffic(direction traffic.Direction, bytes int64)

type TunnelReadyEvent

type TunnelReadyEvent struct {
	TunnelID      string
	PublicURL     string
	Transport     string
	ServerVersion string
	ServerTLSMode string
	WAFEnabled    bool
}

TunnelReadyEvent is emitted when a client successfully registers and has an active tunnel session ready.