hypro

README

🧚 hypro

HYpertext-transfer-protocol PROxy

Hypro is a simple HTTP tunnel powered by go and gRPC.

 HTTP Server
     |
Reverse Proxy (Server)
     |
 gRPC Stream
     |
Reverse Proxy (Client)
     |
   Target

Install

# Server
go install github.com/chuangbo/hypro/cmd/hypro-server
# Client
go install github.com/chuangbo/hypro/cmd/hypro

Usage

1. DNS

   Add a DNS A record to your server:

   example.com => YOUR_SERVER_IP

   And then add a wildcard DNS A record to your server:

   *.example.com => YOUR_SERVER_IP

2. Server

   hypro-server
   

3. Client

   hypro -server example.com -insecure -domain myapp.example.com -target http://localhost:8080
   

Secure Connection

1. Create self-sign certificate

   # Generate CA key:
   openssl ecparam -name prime256v1 -noout -genkey -out ca.key
   
   # Generate CA certificate:
   openssl req -new -x509 -days 3650 -key ca.key -out ca.crt -subj "/C=NZ/ST=AKL/L=Auckland/O=HyproCompany/OU=HyproApp/CN=HyproRootCA"
   
   # Generate server key:
   openssl ecparam -name prime256v1 -noout -genkey -out server.key
   
   # Generate server signing request:
   openssl req -new -key server.key -out server.csr -subj "/C=NZ/ST=AKL/L=Auckland/O=HyproCompany/OU=HyproApp/CN=$(SERVER_NAME)"
   
   # Self-sign server certificate:
   openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt
   

2. Server

   hypro-server -cert server.crt -key server.key
   

3. Client

   hypro -server example.com -cert server.crt -domain myapp.example.com -target http://localhost:8080
   

Documentation

https://godoc.org/github.com/chuangbo/hypro

Build from source

go install google.golang.org/protobuf/cmd/protoc-gen-go
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc
make

License

MIT

Copyright (c) 2018-present, Chuangbo Li

Todos

• Tests
• Benchmarks
• Reuse connections
• Reconnect to the server
• 12-factor
• Graceful reload
• Max connections
• Record / Redo requests
• Cluster

Documentation

Index

• Constants
• func DialAndServe(domain string, port int, handler http.Handler) error
• func DialAndServeReverseProxy(server string, port int, certFile string, domain, target string, insecure bool) error
• func ListenAndServe(grpcAddr, httpAddr, certFile, keyFile string) error
• type Client
  • func Dial(domain string, port int) (*Client, error)
  • func (c *Client) CheckVersion() error
  • func (c *Client) Close() error
  • func (c *Client) CreateTunnel() error
  • func (c *Client) Dial() error
  • func (c *Client) DialAndServe(handler http.Handler) error
  • func (c *Client) DialAndServeReverseProxy(target string) error
  • func (c *Client) GetTransportCredentials() (creds credentials.TransportCredentials, err error)
  • func (c *Client) Listener() (net.Listener, error)
  • func (c *Client) Register() error
  • func (c *Client) Shutdown() error
  • func (c *Client) Worker(errCh chan<- error)
• type Server
  • func (s *Server) Authenticated(host, token string) bool
  • func (s *Server) CheckVersion(ctx context.Context, req *pb.CheckVersionRequest) (*pb.CheckVersionResponse, error)
  • func (s *Server) CreateTunnel(stream pb.Tunnel_CreateTunnelServer) error
  • func (s *Server) DialContext(ctx context.Context, network, addr string) (net.Conn, error)
  • func (s *Server) ListenAndServe() error
  • func (s *Server) Register(ctx context.Context, req *pb.RegisterRequest) (*pb.RegisterResponse, error)
  • func (s *Server) Shutdown() error
  • func (s *Server) TunnelExists(host string) bool

Constants

const (
	// Version is the current hypro version
	Version = "0.2.0"
	// MinClientVersion is the current hypro proto version
	MinClientVersion = "0.2.0"
)

Functions

func DialAndServe

func DialAndServe(domain string, port int, handler http.Handler) error

DialAndServe dials to the hypro server domain:port and then serve on handler on the hypro tunnel Listener

func DialAndServeReverseProxy

func DialAndServeReverseProxy(server string, port int, certFile string, domain, target string, insecure bool) error

DialAndServeReverseProxy dials to the hypro server domain:port and then starts httputil.NewSingleHostReverseProxy on the hypro tunnel Listener

func ListenAndServe

func ListenAndServe(grpcAddr, httpAddr, certFile, keyFile string) error

ListenAndServe listens on grpcAddr and http on httpAddr serving hypro tunnel services and http forwarding to the client

Types

type Client

type Client struct {
	Domain           string
	Server, CertFile string
	ServerPort       int
	Insecure         bool
	// contains filtered or unexported fields
}

Client is a reverse proxy listen on hypro grpc tunnel

func Dial

func Dial(domain string, port int) (*Client, error)

Dial connects hypro server at domain:port

func (*Client) CheckVersion

func (c *Client) CheckVersion() error

CheckVersion get the versions from server and check

func (*Client) Close

func (c *Client) Close() error

Close closes the connection to the server

func (*Client) CreateTunnel

func (c *Client) CreateTunnel() error

CreateTunnel connects to the server and forward to reverse proxy as new net.Conn

func (*Client) Dial

func (c *Client) Dial() error

Dial connects hypro server at domain:port

func (*Client) DialAndServe

func (c *Client) DialAndServe(handler http.Handler) error

DialAndServe connect to hypro grpc server to receive http request, and serve handler

func (*Client) DialAndServeReverseProxy

func (c *Client) DialAndServeReverseProxy(target string) error

DialAndServeReverseProxy connect to hypro grpc server to receive http request, and serve as reverse proxy to the target

func (*Client) GetTransportCredentials

func (c *Client) GetTransportCredentials() (creds credentials.TransportCredentials, err error)

GetTransportCredentials returns tls credentials from cert file or system root ca

func (*Client) Listener

func (c *Client) Listener() (net.Listener, error)

Listener returns net.Listener which accepts connection from hypro server

func (*Client) Register

func (c *Client) Register() error

Register the sub domain at the server.

func (*Client) Shutdown

func (c *Client) Shutdown() error

Shutdown the server gracefully

func (*Client) Worker

func (c *Client) Worker(errCh chan<- error)

Worker creates tunnels

type Server

type Server struct {
	// the server needs the port to generate full address for the registered domain
	GRPCAddr, HTTPAddr, HTTPPort string

	CertFile, KeyFile string

	pb.UnimplementedTunnelServer
	// contains filtered or unexported fields
}

Server is

func (*Server) Authenticated

func (s *Server) Authenticated(host, token string) bool

Authenticated checks valid token from grpc metadata

func (*Server) CheckVersion

func (s *Server) CheckVersion(ctx context.Context, req *pb.CheckVersionRequest) (*pb.CheckVersionResponse, error)

CheckVersion returns the server version and proto version

func (*Server) CreateTunnel

func (s *Server) CreateTunnel(stream pb.Tunnel_CreateTunnelServer) error

CreateTunnel accept and keep connection between client and server TODO: use metadata or custom auth to bind

func (*Server) DialContext

func (s *Server) DialContext(ctx context.Context, network, addr string) (net.Conn, error)

DialContext return a pre-connected proxy connection which actually r/w from grpc

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe listen on grpc addr and tcp on http addr to provide hypro http proxy through grpc connection with the users

func (*Server) Register

func (s *Server) Register(ctx context.Context, req *pb.RegisterRequest) (*pb.RegisterResponse, error)

Register the client

func (*Server) Shutdown

func (s *Server) Shutdown() error

Shutdown close the server

func (*Server) TunnelExists

func (s *Server) TunnelExists(host string) bool

TunnelExists checks if the tunnel registered and connected