tunnelclient

Documentation

Overview

Package tunnelclient provides the reusable Tunlease claim and reverse-tunnel client used by both the standalone CLI and embedding applications.

Index

• Constants
• func NormalizePath(path string) (string, error)
• type APIError
  • func (e *APIError) Error() string
• type Claim
• type Client
  • func New(cfg Config) (*Client, error)
  • func (c *Client) Gateway() string
  • func (c *Client) List(ctx context.Context) ([]Claim, error)
  • func (c *Client) Release(ctx context.Context, claimID string) error
  • func (c *Client) Start(ctx context.Context, paths []string, localPort int) (*Session, error)
• type Config
• type Event
• type EventType
• type Session
  • func (s *Session) Claim() Claim
  • func (s *Session) Close() error
  • func (s *Session) Done() <-chan struct{}
  • func (s *Session) Err() error
  • func (s *Session) Events() <-chan Event

Constants

const (
	MaxPathsPerClaim = 8
	MaxPathLength    = 512
)

const DefaultControlPrefix = "/_tunlease"

New validates config and creates a reusable client. DefaultControlPrefix is the URL path prefix the gateway serves its control plane under on a same-domain deployment. The client adds it automatically so users only need to give the gateway's domain.

Functions

func NormalizePath

func NormalizePath(path string) (string, error)

NormalizePath validates a callback path and removes a trailing slash. A trailing /* matches one child segment; /** matches the whole subtree.

Types

type APIError

type APIError struct {
	Status    int    `json:"-"`
	Code      string `json:"error"`
	Detail    string `json:"detail"`
	ClaimedBy string `json:"claimed_by"`
}

APIError is a structured error returned by the gateway.

func (*APIError) Error

func (e *APIError) Error() string

type Claim

type Claim struct {
	ID        string     `json:"claim_id"`
	Owner     string     `json:"owner"`
	Paths     []string   `json:"paths"`
	StartedAt time.Time  `json:"started_at"`
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
}

Claim describes one active tunnel and its exclusively owned paths.

type Client

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

Client talks to a Tunlease gateway and opens reverse tunnels.

func New

func New(cfg Config) (*Client, error)

func (*Client) Gateway

func (c *Client) Gateway() string

Gateway returns the normalized gateway base URL used by the client.

func (*Client) List

func (c *Client) List(ctx context.Context) ([]Claim, error)

List returns every active claim visible to the caller.

func (*Client) Release

func (c *Client) Release(ctx context.Context, claimID string) error

Release releases a claim by ID.

func (*Client) Start

func (c *Client) Start(ctx context.Context, paths []string, localPort int) (*Session, error)

Start claims paths by establishing a tunnel. The paths remain owned until ctx is cancelled or Close is called.

type Config

type Config struct {
	Gateway string
	Token   string
	// Insecure skips TLS certificate verification of the gateway connection
	// (API + tunnel WebSocket). Use only on trusted development networks.
	// Ignored when HTTPClient is provided.
	Insecure bool
	// DefaultScheme is used when Gateway has no scheme. Defaults to "https".
	// Set to "http" for a gateway without TLS (e.g. a local demo).
	DefaultScheme string
	HTTPClient    *http.Client
}

Config configures a Client. HTTPClient is optional.

type Event

type Event struct {
	Type     EventType
	Claim    Claim
	Err      error
	Method   string
	Path     string
	Status   int
	Duration time.Duration
}

Event describes a best-effort, non-terminal lifecycle notification. Slow consumers may miss events; Claim, Done, and Err are authoritative.

type EventType

type EventType string

EventType identifies a lifecycle change emitted by a Session.

const (
	EventTunnelDisconnected EventType = "tunnel_disconnected"
	EventTunnelReconnected  EventType = "tunnel_reconnected"
	EventLocalTargetError   EventType = "local_target_error"
	EventRequestActivity    EventType = "request_activity"
)

type Session

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

Session owns one active tunnel and its paths.

func (*Session) Claim

func (s *Session) Claim() Claim

Claim returns the current live tunnel. Its ID changes after reconnect.

func (*Session) Close

func (s *Session) Close() error

Close releases the paths and waits for the tunnel to stop.

func (*Session) Done

func (s *Session) Done() <-chan struct{}

Done closes when the session has released its tunnel or failed terminally.

func (*Session) Err

func (s *Session) Err() error

Err returns the terminal session error, or nil after a normal close.

func (*Session) Events

func (s *Session) Events() <-chan Event

Events reports best-effort, non-terminal lifecycle notifications. Consumers must not depend on receiving every event for correctness.