supervisor

Documentation

Overview

Package supervisor spawns and supervises one system ssh process per port mapping, restarting dead mappings with exponential backoff and supporting per-tunnel lifecycle control.

Index

• type Manager
  • func NewManager(cfg *config.Config, opts Options) *Manager
  • func (m *Manager) RestartTunnel(name string) error
  • func (m *Manager) Run(ctx context.Context) error
  • func (m *Manager) Snapshot() []status.TunnelStatus
  • func (m *Manager) StartTunnel(name string) error
  • func (m *Manager) StopTunnel(name string) error
• type Options
• type PortProber

Types

type Manager

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

Manager supervises the tunnels declared in a Config. A Manager is not safe for concurrent use until Run has been called; afterwards StartTunnel, StopTunnel, RestartTunnel, and Snapshot are safe from any goroutine.

func NewManager

func NewManager(cfg *config.Config, opts Options) *Manager

NewManager returns a Manager supervising the tunnels in cfg.

func (*Manager) RestartTunnel

func (m *Manager) RestartTunnel(name string) error

RestartTunnel stops name, resets its restart attempts, and starts it again.

func (*Manager) Run

func (m *Manager) Run(ctx context.Context) error

Run supervises all Wanted tunnels, blocking until ctx is cancelled, then gracefully stops every child and returns nil.

func (*Manager) Snapshot

func (m *Manager) Snapshot() []status.TunnelStatus

Snapshot returns the current status of every tunnel.

func (*Manager) StartTunnel

func (m *Manager) StartTunnel(name string) error

StartTunnel makes name Wanted and starts supervising it. It is a no-op if the tunnel is already running. Unknown names return an error.

func (*Manager) StopTunnel

func (m *Manager) StopTunnel(name string) error

StopTunnel makes name not-Wanted, stops its ssh children, and blocks until the tunnel's supervision loop has fully exited.

type Options

type Options struct {
	SSHBin        string        // ssh binary; default "ssh"
	BackoffBase   time.Duration // default 1s
	BackoffCap    time.Duration // default 60s
	BackoffJitter float64       // multiplicative ± jitter; default 0.2
	FailedAfter   int           // attempt count that flips the message to "failed - retrying with backoff"; default 5
	DialInterval  time.Duration // port probe polling interval; default 250ms
	DialTimeout   time.Duration // port probe timeout; default 300ms
	Log           *log.Logger   // nil = discard
	Selected      []string      // explicit tunnel names; override Enabled

	// PortProber reports whether a TCP connection to addr can be established.
	// A nil return means the local port is occupied. Defaults to a
	// net.Dialer with DialTimeout.
	PortProber PortProber

	// ReclaimPort terminates the process listening on a colliding local port
	// when the tunnel has reclaim: true. Defaults to an lsof-based
	// implementation that refuses to kill processes owned by other users.
	ReclaimPort func(local int) error
}

Options configures a Manager. Zero values select the documented defaults.

type PortProber

type PortProber func(ctx context.Context, addr string) error

PortProber reports whether a TCP connection to addr can be established. A nil return means the port is already in use.