Documentation

Overview

    Package tun2 tunnels HTTP requests over existing, long-lived connections using smux[1] and optionally kcp[2] to enable more reliable transport.

    Currently this only works on a per-domain basis, but it is designed to be flexible enough to support path-based routing as an addition in the future.

    [1]: https://github.com/xtaci/smux [2]: https://github.com/xtaci/kcp-go

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var (
    	ErrCantOpenSessionStream = errors.New("tun2: connection can't open session stream")
    	ErrCantWriteRequest      = errors.New("tun2: connection stream can't write request")
    	ErrCantReadResponse      = errors.New("tun2: connection stream can't read response")
    )

      Connection-specific errors

      View Source
      var (
      	ErrNoSuchBackend             = errors.New("tun2: there is no such backend")
      	ErrAuthMismatch              = errors.New("tun2: authenication doesn't match database records")
      	ErrCantRemoveWhatDoesntExist = errors.New("tun2: this connection does not exist, cannot remove it")
      )

        Error values

        Functions

        This section is empty.

        Types

        type Auth

        type Auth struct {
        	Token  string `json:"token"`
        	Domain string `json:"domain"`
        }

          Auth is the authentication info the client passes to the server.

          type Backend

          type Backend struct {
          	ID     string
          	Proto  string
          	User   string
          	Domain string
          	Phi    float32
          	Host   string
          	Usable bool
          }

            Backend is the public state of an individual Connection.

            type Client

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

              Client connects to a remote tun2 server and sets up authentication before routing individual HTTP requests to discrete streams that are reverse proxied to the eventual backend.

              func NewClient

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

                NewClient constructs an instance of Client with a given ClientConfig.

                func (*Client) Connect

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

                  Connect dials the remote server and negotiates a client session with its configured server address. This will then continuously proxy incoming HTTP requests to the backend HTTP server.

                  This is a blocking function.

                  type ClientConfig

                  type ClientConfig struct {
                  	TLSConfig  *tls.Config
                  	ConnType   string
                  	ServerAddr string
                  	Token      string
                  	Domain     string
                  	BackendURL string
                  	// contains filtered or unexported fields
                  }

                    ClientConfig configures client with settings that the user provides.

                    type Connection

                    type Connection struct {
                    	Auth *Auth
                    
                    	sync.Mutex
                    	// contains filtered or unexported fields
                    }

                      Connection is a single active client -> server connection and session containing many streams over TCP+TLS or KCP+TLS. Every stream beyond the control stream is assumed to be passed to the underlying backend server.

                      All Connection methods assume this is locked externally.

                      func (*Connection) Close

                      func (c *Connection) Close() error

                        Close destroys resouces specific to the connection.

                        func (*Connection) F

                        func (c *Connection) F() ln.F

                          F logs key->value pairs as an ln.Fer

                          func (*Connection) OpenStream

                          func (c *Connection) OpenStream(ctx context.Context) (net.Conn, error)

                            OpenStream creates a new stream (connection) to the backend server.

                            func (*Connection) Ping

                            func (c *Connection) Ping() error

                              Ping ends a "ping" to the client. If the client doesn't respond or the connection dies, then the connection needs to be cleaned up.

                              func (*Connection) RoundTrip

                              func (c *Connection) RoundTrip(req *http.Request) (*http.Response, error)

                                RoundTrip forwards a HTTP request to the remote backend and then returns the response, if any.

                                type Server

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

                                  Server routes frontend HTTP traffic to backend TCP traffic.

                                  func NewServer

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

                                    NewServer creates a new Server instance with a given config, acquiring all relevant resources.

                                    func (*Server) Close

                                    func (s *Server) Close()

                                      Close stops the background tasks for this Server.

                                      func (*Server) GetAllBackends

                                      func (s *Server) GetAllBackends() []Backend

                                        GetAllBackends fetches every backend connected to this server.

                                        func (*Server) GetBackendsForDomain

                                        func (s *Server) GetBackendsForDomain(domain string) []Backend

                                          GetBackendsForDomain fetches all backends connected to this server associated to a single public domain name.

                                          func (*Server) GetBackendsForUser

                                          func (s *Server) GetBackendsForUser(uname string) []Backend

                                            GetBackendsForUser fetches all backends connected to this server owned by a given user by username.

                                            func (*Server) HandleConn

                                            func (s *Server) HandleConn(ctx context.Context, c net.Conn)

                                              HandleConn starts up the needed mechanisms to relay HTTP traffic to/from the currently connected backend.

                                              func (*Server) KillBackend

                                              func (s *Server) KillBackend(id string) error

                                                KillBackend forcibly disconnects a given backend but doesn't offer a way to "ban" it from reconnecting.

                                                func (*Server) Listen

                                                func (s *Server) Listen(l net.Listener)

                                                  Listen passes this Server a given net.Listener to accept backend connections.

                                                  func (*Server) RoundTrip

                                                  func (s *Server) RoundTrip(req *http.Request) (*http.Response, error)

                                                    RoundTrip sends a HTTP request to a backend and then returns its response.

                                                    func (*Server) Wait

                                                    func (s *Server) Wait()

                                                      Wait blocks until the server context is cancelled.

                                                      type ServerConfig

                                                      type ServerConfig struct {
                                                      	SmuxConf *smux.Config
                                                      	Storage  Storage
                                                      }

                                                        ServerConfig ...

                                                        type Storage

                                                        type Storage interface {
                                                        	HasToken(ctx context.Context, token string) (user string, scopes []string, err error)
                                                        	HasRoute(ctx context.Context, domain string) (user string, err error)
                                                        }

                                                          Storage is the minimal subset of features that tun2's Server needs out of a persistence layer.