tunnelsdk

Documentation

Index

• Constants
• type Client
  • func New(serverURL *url.URL) *Client
  • func (c *Client) ClientRegister(ctx context.Context, req ClientRegisterRequest) (ClientRegisterResponse, error)
  • func (c *Client) LaunchTunnel(ctx context.Context, cfg TunnelConfig) (*Tunnel, error)
  • func (c *Client) Request(ctx context.Context, method, path string, body interface{}) (*http.Response, error)
• type ClientRegisterRequest
• type ClientRegisterResponse
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Friendly() string
  • func (e *Error) StatusCode() int
• type Key
  • func FromNoisePrivateKey(k device.NoisePrivateKey) Key
  • func FromNoisePublicKey(k device.NoisePublicKey) Key
  • func GeneratePrivateKey() (Key, error)
  • func ParsePrivateKey(key string) (Key, error)
  • func ParsePublicKey(key string) (Key, error)
  • func (k Key) Hash() string
  • func (k Key) HexString() string
  • func (k Key) IsPrivate() bool
  • func (k Key) IsZero() bool
  • func (k Key) NoisePrivateKey() (device.NoisePrivateKey, error)
  • func (k Key) NoisePublicKey() device.NoisePublicKey
  • func (k Key) PublicKey() (Key, error)
  • func (k Key) String() string
• type Response
• type Tunnel
  • func (t *Tunnel) Close() error
  • func (t *Tunnel) Wait() <-chan struct{}
• type TunnelConfig
• type TunnelVersion

Constants

const TunnelPort = 8090

TunnelPort is the port in the virtual wireguard network stack that the listener is listening on.

Types

type Client

type Client struct {
	HTTPClient *http.Client
	URL        *url.URL
}

Client provides HTTP methods for the tunneld API and a full wireguard tunnel client implementation.

func New

func New(serverURL *url.URL) *Client

New creates a tunneld client for the provided URL.

func (*Client) ClientRegister

func (c *Client) ClientRegister(ctx context.Context, req ClientRegisterRequest) (ClientRegisterResponse, error)

func (*Client) LaunchTunnel

func (c *Client) LaunchTunnel(ctx context.Context, cfg TunnelConfig) (*Tunnel, error)

LaunchTunnel makes a request to the tunneld server to register the client's tunnel using the client's public key, then establishes a wireguard connection to the server and returns a *Tunnel. Connections can be accepted from tunnel.Listener.

func (*Client) Request

func (c *Client) Request(ctx context.Context, method, path string, body interface{}) (*http.Response, error)

Request performs an HTTP request with the body provided. The caller is responsible for closing the response body.

type ClientRegisterRequest

type ClientRegisterRequest struct {
	Version   TunnelVersion         `json:"version"`
	PublicKey device.NoisePublicKey `json:"public_key"`
}

type ClientRegisterResponse

type ClientRegisterResponse struct {
	Version        TunnelVersion `json:"version"`
	ReregisterWait time.Duration `json:"reregister_wait"`
	// TunnelURLs contains a list of valid URLs that will be forwarded from the
	// server to this tunnel client once connected. The first URL is the
	// preferred URL, and the other URLs are provided for compatibility
	// purposes only.
	//
	// The order of the URLs changes based on the Version field in the request.
	TunnelURLs []string   `json:"tunnel_urls"`
	ClientIP   netip.Addr `json:"client_ip"`

	ServerEndpoint  string                `json:"server_endpoint"`
	ServerIP        netip.Addr            `json:"server_ip"`
	ServerPublicKey device.NoisePublicKey `json:"server_public_key"`
	WireguardMTU    int                   `json:"wireguard_mtu"`
}

type Error

type Error struct {
	Response
	// contains filtered or unexported fields
}

Error represents an unaccepted or invalid request to the API.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Friendly

func (e *Error) Friendly() string

func (*Error) StatusCode

func (e *Error) StatusCode() int

type Key

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

Key is a Wireguard private or public key.

func FromNoisePrivateKey

func FromNoisePrivateKey(k device.NoisePrivateKey) Key

FromNoisePrivateKey converts a device.NoisePrivateKey to a Key.

func FromNoisePublicKey

func FromNoisePublicKey(k device.NoisePublicKey) Key

FromNoisePublicKey converts a device.NoisePublicKey to a Key.

func GeneratePrivateKey

func GeneratePrivateKey() (Key, error)

GenerateWireguardPrivateKey generates a new wireguard private key using secure cryptography. The caller should store the key (using key.String()) in a safe place like the user's home directory, and use it in the future rather than generating a new key each time.

func ParsePrivateKey

func ParsePrivateKey(key string) (Key, error)

ParsePrivateKey parses a private key generated using key.String().

func ParsePublicKey

func ParsePublicKey(key string) (Key, error)

ParsePublicKey parses a public key generated using key.String().

func (Key) Hash

func (k Key) Hash() string

Hash returns the SHA512 hash of the key.

func (Key) HexString

func (k Key) HexString() string

HexString returns the hex string representation of the key.

func (Key) IsPrivate

func (k Key) IsPrivate() bool

IsPrivate returns true if the key is a private key.

func (Key) IsZero

func (k Key) IsZero() bool

IsZero returns true if the Key is the zero value.

func (Key) NoisePrivateKey

func (k Key) NoisePrivateKey() (device.NoisePrivateKey, error)

NoisePrivateKey returns the device.NoisePrivateKey for the key. If the key is not a private key, an error is returned.

func (Key) NoisePublicKey

func (k Key) NoisePublicKey() device.NoisePublicKey

NoisePublicKey returns the device.NoisePublicKey for the key. If the key is a private key, it is converted to a public key automatically.

func (Key) PublicKey

func (k Key) PublicKey() (Key, error)

PublicKey returns the public key component of the Wireguard private key. If the key is not a private key, an error is returned.

func (Key) String

func (k Key) String() string

String returns a base64 encoded string representation of the key.

type Response

type Response struct {
	Message string `json:"message"`
	Detail  string `json:"detail,omitempty"`
}

type Tunnel

type Tunnel struct {
	URL       *url.URL
	OtherURLs []*url.URL
	Listener  net.Listener
	// contains filtered or unexported fields
}

func (*Tunnel) Close

func (t *Tunnel) Close() error

func (*Tunnel) Wait

func (t *Tunnel) Wait() <-chan struct{}

type TunnelConfig

type TunnelConfig struct {
	Log slog.Logger
	// Version denotes which version of the tunnel URL specification to use.
	// Undefined version is treated as the latest version.
	Version TunnelVersion
	// PrivateKey is the Wireguard private key. You can use GeneratePrivateKey
	// to generate a new key. It should be stored in a safe place for future
	// tunnel sessions, otherwise you will get a new hostname.
	PrivateKey Key
}

type TunnelVersion

type TunnelVersion int

TunnelVersion is the version of the tunnel URL specification.

const (
	// TunnelVersion1 is the "old style" tunnel URL. Each hostname base is 32
	// characters long and is base16 (hex) encoded.
	TunnelVersion1 TunnelVersion = 1
	// TunnelVersion2 is the "new style" tunnel URL. Each hostname base is ~12
	// characters long and is base32 encoded.
	TunnelVersion2 TunnelVersion = 2

	TunnelVersionLatest = TunnelVersion2
)