Skip to content

🔮 A dynamic reverse proxy Golang package for NAT or firewall traversal. Let's build your own tunnel with several lines of code. 动态的Golang反向代理库,用于内网穿透或防火墙穿透。几行代码就能构建你自己的穿透通道。

License

Notifications You must be signed in to change notification settings

piaodazhu/proxylite

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Aug 13, 2023
422a879 · Aug 13, 2023

History

7 Commits
Aug 13, 2023
Aug 13, 2023
Aug 13, 2023
Aug 13, 2023
Aug 13, 2023
Aug 13, 2023
Aug 13, 2023
Aug 13, 2023
Aug 13, 2023
Aug 13, 2023
Aug 13, 2023
Aug 13, 2023
Aug 13, 2023

Repository files navigation

English|中文

proxylite

proxylite is a dynamic TCP reverse proxy Golang package for NAT or firewall traversal. It is god damn easy to integrate network traversal feature into your project with proxylite.

Different from well-known frp, proxylite is not a set of runnable programs, but a lightweight package, which provides good flexibility and is easy to integrate in golang projects. Of course, build a set of runnable programs is also a piece of cake.

Why proxylite

One day, I needed to add TCP NAT traversal to my project, so I tried to introduce frp to implement this feature. But I realized that frp needs to read configuration files and start processes, which is not a good fit for my needs:

  • First of all, starting a process introduces a new independent service to the project, which makes it more difficult to maintain.
  • Also, this approach does not allow for easy collection of logging information.
  • Most importantly, I needed to dynamically establish on-demand connections, and editing the configuration file and then restarting the process was clearly inelegant.

So why not write a package to make this more elegant? proxylite was born. Its main features are listed below:

  1. Easy to integrate into code. Both server and client structures are provided. Just import this package then register tunnels whenever you want.
  2. Dynamic on-demand reverse proxy. One registration, one port, one user, one tcp connection.
  3. Service registration and discovery.
  4. Customized hooks are support. (Under development)

Concepts

  +---------------------------------+   +-----------------------------------+
  | Inner Service <--- Inner Client +---+> Listenning Port <--- Outer Port <+---- User 
  +---------------------------------+   +-----------------------------------+
               NAT Nodes             ...             Public Server               Any User

Quick Start

First, you should import proxylite:

import "github.com/piaodazhu/proxylite"

Let's create a server:

package main
import "github.com/piaodazhu/proxylite"

func main() {
	server := proxylite.NewProxyLiteServer()
	server.AddPort(9930, 9932)
	panic(server.Run(":9933"))
}

These code create a proxylite server, and add avaliable outer port 9930-9932 (Note that it is not 9930 and 9932, but from 9930 to 9932), then run the server. The server is blocked listening on port 9939, inner client will dial this port and server discovery also bind this port.

Then, we create a inner client:

package main

import (
	"log"

	"github.com/piaodazhu/proxylite"
)

func main() {
	client := proxylite.NewProxyLiteClient("0.0.0.0:9933")
	err := client.RegisterInnerService(
		proxylite.RegisterInfo{
			OuterPort: 9931,
			InnerAddr: ":22",
			Name:      "ssh",
			Message:   "ssh login",
		},
	)
    if err != nil {
        log.Fatal(err)
        return
    }

	entry, ok := client.GetRegisterEntryByName("ssh")
	if !ok {
        log.Fatal("registration failed")
		return
	}
	<-entry.Done
    log.Print("BYE :)")
}

These code create a inner client, binding with server "0.0.0.0:9933". Then we register a inner service to the server:

proxylite.RegisterInfo{
    OuterPort: 9931,    // means we want map server's 9931 port to our inner service 
    InnerAddr: ":22",   // means inner service is 127.0.0.1:22. e.g. default ssh port.
    Name:      "ssh",   // service name
    Message:   "ssh login", // customized information
},

Then we get the registration entry if the registration is success. Finally we wait it done by reading channel.

Tutorial

Server

func NewProxyLiteServer(portIntervals ...[2]int) *ProxyLiteServer

Create a Proxy server with avaliable ports intervals.

func (s *ProxyLiteServer) AddPort(from, to int) bool

Create a Proxy server with avaliable ports intervals. Return false if port is invalid.

func (s *ProxyLiteServer) SetLogger(logger *log.Logger)

Set customized logrus logger the the server.

func (s *ProxyLiteServer) Run(addr string) error

Run the server and let it listen on given address.

client

func NewProxyLiteClient(serverAddr string) *ProxyLiteClient

Create a inner client binding with a proxy server.

func (c *ProxyLiteClient) AvaliablePorts() ([]int, bool)

Get avaliable ports from proxy server.

func (c *ProxyLiteClient) AnyPort() (int, bool)

Get a random avaliable port from proxy server.

type ServiceInfo struct {
	Port    int
	Name    string
	Message string
	Busy    bool
	Birth   time.Time
}

func (c *ProxyLiteClient) ActiveServices() ([]ServiceInfo, error)

Discover all active services from proxy server.

type RegisterInfo struct {
	OuterPort int
	InnerAddr string
	Name      string
	Message   string
}

func (c *ProxyLiteClient) RegisterInnerService(info RegisterInfo) error

Register inner server to proxy server's outer port.

type RegisterEntry struct {
	// Basic Info
	Info   RegisterInfo
	// Cancel function
	Cancel func()
	// Done channel
	Done   <-chan struct{}
}

func (c *ProxyLiteClient) GetRegisterEntryByName(name string) (*RegisterEntry, bool) 
func (c *ProxyLiteClient) GetRegisterEntryByPort(port int) (*RegisterEntry, bool)

Get RegisterEntry by name or port. RegisterEntry can be used to canncel tunnel or wait done.

func (c *ProxyLiteClient) SetLogger(logger *log.Logger)

Set customized logrus logger for the inner client.

Others

func AskFreePort(addr string) ([]int, error)

Ask avaliable free port from proxy server with given address.

func DiscoverServices(addr string) ([]ServiceInfo, error)

Discover all active services from proxy server with given address.

Contributing

Feel free to open issues or pull requests to make this project better. 🌈

About

🔮 A dynamic reverse proxy Golang package for NAT or firewall traversal. Let's build your own tunnel with several lines of code. 动态的Golang反向代理库,用于内网穿透或防火墙穿透。几行代码就能构建你自己的穿透通道。

Topics

Resources

License

Stars

Watchers

Forks

Languages