tunnel

package
v1.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 4, 2024 License: BSD-3-Clause, BSD-3-Clause Imports: 26 Imported by: 0

README

Tunnel GoDoc Go Report Card Build Status

Tunnel is a server/client package that enables to proxy public connections to your local machine over a tunnel connection from the local machine to the public server. What this means is, you can share your localhost even if it doesn't have a Public IP or if it's not reachable from outside.

It uses the excellent yamux package to multiplex connections between server and client.

The project is under active development, please vendor it if you want to use it.

Usage

The tunnel package consists of two parts. The server and the client.

Server is the public facing part. It's type that satisfies the http.Handler. So it's easily pluggable into existing servers.

Let assume that you setup your DNS service so all *.example.com domains route to your server at the public IP 203.0.113.0. Let us first create the server part:

package main

import (
	"net/http"

	"github.com/koding/tunnel"
)

func main() {
	cfg := &tunnel.ServerConfig{}
	server, _ := tunnel.NewServer(cfg)
	server.AddHost("sub.example.com", "1234")
	http.ListenAndServe(":80", server)
}

Once you create the server, you just plug it into your server. The only detail here is to map a virtualhost to a secret token. The secret token is the only part that needs to be known for the client side.

Let us now create the client side part:

package main

import "github.com/koding/tunnel"

func main() {
	cfg := &tunnel.ClientConfig{
		Identifier: "1234",
		ServerAddr: "203.0.113.0:80",
	}

	client, err := tunnel.NewClient(cfg)
	if err != nil {
		panic(err)
	}

	client.Start()
}

The Start() method is by default blocking. As you see you, we just passed the server address and the secret token.

Now whenever someone hit sub.example.com, the request will be proxied to the machine where client is running and hit the local server running 127.0.0.1:80 (assuming there is one). If someone hits sub.example.com:3000 (assume your server is running at this port), it'll be routed to 127.0.0.1:3000

That's it.

There are many options that can be changed, such as a static local address for your client. Have alook at the documentation

Protocol

The server/client protocol is written in the spec.md file. Please have a look for more detail.

License

The BSD 3-Clause License - see LICENSE for more details

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// DefaultProxyFuncs holds global default proxy functions for all transport protocols.
	DefaultProxyFuncs = ProxyFuncs{
		HTTP: new(HTTPProxy).Proxy,
		WS:   new(HTTPProxy).Proxy,
	}
	// DefaultProxy is a ProxyFunc that uses DefaultProxyFuncs.
	DefaultProxy = Proxy(ProxyFuncs{})
)
View Source 
var ErrRedialAborted = errors.New("unable to restore the connection, aborting")

ErrRedialAborted is emitted on ClientClosed event, when backoff policy used by a client decided no more reconnection attempts must be made.

Functions

func GetConfig 

func GetConfig(configPath *string, config any) error

func GetExecutableDir 

func GetExecutableDir() string

func Join 

func Join(local, remote net.Conn, log logging.Logger)

Join copies data between local and remote connections. It reads from one connection and writes to the other. It's a building block for ProxyFunc implementations.

Types

type Backoff 

type Backoff interface {
	// Next returns the duration to sleep before retrying reconnections.
	// If the returned value is negative, the retry is aborted.
	NextBackOff() time.Duration

	// Reset is used to signal a reconnection was successful and next
	// call to Next should return desired time duration for 1st reconnection
	// attempt.
	Reset()
}

Backoff defines behavior of staggering reconnection retries.

type Client 

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

Client is responsible for creating a control connection to a tunnel server, creating new tunnels and proxy them to tunnel server.

func NewClient 

func NewClient(cfg *ClientConfig) (*Client, error)

NewClient creates a new tunnel that is established between the serverAddr and localAddr. It exits if it can't create a new control connection to the server. If localAddr is empty client will always try to proxy to a local port.

func (*Client) Close 

func (c *Client) Close() error

Close closes the client and shutdowns the connection to the tunnel server

func (*Client) Start 

func (c *Client) Start()

Start starts the client and connects to the server with the identifier. client.FetchIdentifier() will be used if it's not nil. It's supports reconnecting with exponential backoff intervals when the connection to the server disconnects. Call client.Close() to shutdown the client completely. A successful connection will cause StartNotify() to receive a value.

func (*Client) StartNotify 

func (c *Client) StartNotify() <-chan bool

StartNotify returns a channel that receives a single value when the client established a successful connection to the server.

type ClientConfig 

type ClientConfig struct {
	// Identifier of connecting client.It must be signed with SignatureKey to be valid
	// Required if FetchIdentifier is not set.
	Identifier string

	// Key used to signIdentifier Identifier
	SignatureKey string

	// FetchIdentifier can be used to fetch identifier. Required if Identifier
	// is not set.
	FetchIdentifier func() (string, error)

	// ServerAddr defines the TCP address of the tunnel server to be connected.
	// Required if FetchServerAddr is not set.
	ServerAddr string

	// FetchServerAddr can be used to fetch tunnel server address.
	// Required if ServerAddress is not set.
	FetchServerAddr func() (string, error)

	// FetchSignatureKey can be used to fetch secret key used to sign client ID.
	FetchSignatureKey func() (string, error)

	// Dial provides custom transport layer for client server communication.
	//
	// If nil, default implementation is to return net.Dial("tcp", address).
	//
	// It can be used for connection monitoring, setting different timeouts or
	// securing the connection.
	Dial func(network, address string) (net.Conn, error)

	// Proxy defines custom proxing logic. This is optional extension point
	// where you can provide your local server selection or communication rules.
	Proxy ProxyFunc

	// StateChanges receives state transition details each time client
	// connection state changes. The channel is expected to be sufficiently
	// buffered to keep up with event pace.
	//
	// If nil, no information about state transitions are dispatched
	// by the library.
	StateChanges chan<- *ClientStateChange

	// Backoff is used to control behavior of staggering reconnection loop.
	//
	// If nil, default backoff policy is used which makes a client to never
	// give up on reconnection.
	//
	// If custom backoff is used, client will emit ErrRedialAborted set
	// with ClientClosed event when no more reconnection attempts should
	// be made.
	Backoff Backoff

	// YamuxConfig defines the config which passed to every new yamux.Session. If nil
	// yamux.DefaultConfig() is used.
	YamuxConfig *yamux.Config

	// Log defines the logger
	Log *zap.Logger

	FetchLocalAddr func(port int) (string, error)

	// Settings sent to server for given client
	// TODO separate proto and client config types. Fill proto from config upon creation
	ConnectionConfig proto.ConnectionConfig

	// Custom control path
	ControlPath string

	// Custom HTTP method of control protocol
	ControlMethod string
}

ClientConfig defines the configuration for the Client

type ClientState 

type ClientState uint32

ClientState represents client connection state to tunnel server. 

const (
	ClientUnknown ClientState = iota
	ClientStarted
	ClientConnecting
	ClientConnected
	ClientDisconnected
	ClientClosed // keep it always last
)

ClientState enumeration.

func (ClientState) String 

func (i ClientState) String() string

type ClientStateChange 

type ClientStateChange struct {
	Identifier string
	Previous   ClientState
	Current    ClientState
	Error      error
}

ClientStateChange represents single client state transition.

func (*ClientStateChange) String 

func (cs *ClientStateChange) String() string

Strings implements the fmt.Stringer interface.

type HTTPProxy 

type HTTPProxy struct {
	// TargetHost defines the TCP address of the local server.
	// This is optional if you want to specify a single TCP address.
	TargetHost string

	// ErrorResp is custom response send to tunnel server when client cannot
	// establish connection to local server. If not set a default "no local server"
	// response is sent.
	ErrorResp *http.Response
	// Log is a custom logger that can be used for the proxy.
	// If not set a "http" logger is used.
	Log *zap.Logger
}

HTTPProxy forwards HTTP traffic.

We take original request, replace host and protocol with target host and execute it. Returned data redirected to the yamux tunnel When connection to local server cannot be established proxy responds with http error message.

func (*HTTPProxy) Proxy 

func (p *HTTPProxy) Proxy(remote net.Conn, msg *proto.ControlMessage)

Proxy is a ProxyFunc.

type HTTPRewriteRule 

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

type ProxyFunc 

type ProxyFunc func(remote net.Conn, msg *proto.ControlMessage)

ProxyFunc is responsible for forwarding a remote connection to local server and writing the response back.

func Proxy 

func Proxy(p ProxyFuncs) ProxyFunc

Proxy returns a ProxyFunc that uses custom function if provided, otherwise falls back to DefaultProxyFuncs.

type ProxyFuncs 

type ProxyFuncs struct {
	// HTTP is custom implementation of HTTP proxing.
	HTTP ProxyFunc
	// TCP is custom implementation of TCP proxing.
	TCP ProxyFunc
	// WS is custom implementation of web socket proxing.
	WS ProxyFunc
}

ProxyFuncs is a collection of ProxyFunc.

type Server 

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

Server is responsible for proxying public connections to the client over a tunnel connection. It also listens to control messages from the client.

func NewServer 

func NewServer(cfg *ServerConfig) (*Server, error)

NewServer creates a new Server. The defaults are used if config is nil.

func (*Server) AddHost 

func (s *Server) AddHost(host, identifier string, rewrites []HTTPRewriteRule)

AddHost adds the given virtual host and maps it to the identifier.

func (*Server) DeleteHost 

func (s *Server) DeleteHost(host string)

DeleteHost deletes the given virtual host. Once removed any request to this host is denied.

func (*Server) OnConnect 

func (s *Server) OnConnect(identifier string, fn func() error)

OnConnect invokes a callback for client with given identifier, when it establishes a control session. After a client is connected, the associated function is also removed and needs to be added again.

func (*Server) OnDisconnect 

func (s *Server) OnDisconnect(identifier string, fn func() error)

OnDisconnect calls the function when the client connected with the associated identifier disconnects from the server. After a client is disconnected, the associated function is also removed and needs to be added again.

func (*Server) ServeHTTP 

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

type ServerConfig 

type ServerConfig struct {
	// StateChanges receives state transition details each time client
	// connection state changes. The channel is expected to be sufficiently
	// buffered to keep up with event pace.
	//
	// If nil, no information about state transitions are dispatched
	// by the library.
	StateChanges chan<- *ClientStateChange

	// Director is a function that modifies HTTP request into a new HTTP request
	// before sending to client. If nil no modifications are done.
	Director func(*http.Request)

	// Log defines the logger. If nil a default zap production is used.
	Log *zap.Logger

	// YamuxConfig defines the config which passed to every new yamux.Session. If nil
	// yamux.DefaultConfig() is used.
	YamuxConfig *yamux.Config

	// Key used to signIdentifier Identifier
	SignatureKey string

	// List of regex rules for valid hosts
	AllowedHosts []string

	//List of allowed clients. Allows any if list is empty
	AllowedClients []string

	ControlPath string

	ControlMethod string
}

ServerConfig defines the configuration for the Server

type TCPProxy 

type TCPProxy struct {
	// LocalAddr defines the TCP address of the local server.
	// This is optional if you want to specify a single TCP address.
	LocalAddr string
	// FetchLocalAddr is used for looking up TCP address of the server.
	// This is optional if you want to specify a dynamic TCP address based on incommig port.
	FetchLocalAddr func(port int) (string, error)
	// Log is a custom logger that can be used for the proxy.
	// If not set a "tcp" logger is used.
	Log logging.Logger
}

TCPProxy forwards TCP streams.

If port-based routing is used, LocalAddr or FetchLocalAddr field is required for tunneling to function properly. Otherwise you'll be forwarding traffic to random ports and this is usually not desired.

If IP-based routing is used then tunnel server connection request is proxied to 127.0.0.1:incomingPort where incomingPort is control message LocalPort. Usually this is tunnel server's public exposed Port. This behaviour can be changed by setting LocalAddr or FetchLocalAddr. FetchLocalAddr takes precedence over LocalAddr.

func (*TCPProxy) Proxy 

func (p *TCPProxy) Proxy(remote net.Conn, msg *proto.ControlMessage)

Proxy is a ProxyFunc.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.