uot

README

UDP-Over-TCP

UDP-Over-TCP is a proxy library written in Go. It works on transport layer, which transfers payload of UDP packet over TCP. It does not involving IP or TCP/UDP packet headers.

For example: app sends hello to github.com over UDP and github.com replies nice. When using UDP-Over-TCP, the communication is as follow:

sequenceDiagram
app ->> client: [udp] github.com hello
client ->> server: [tcp] github.com hello
server ->> github.com: [udp] hello
github.com -->> server: [udp] nice
server -->> client: [tcp] nice
client -->> app: [udp] nice

Installation

go get -u github.com/justlovediaodiao/udp-over-tcp

Import in your code:

import "github.com/justlovediaodiao/udp-over-tcp"

Quick start

• client

import "github.com/justlovediaodiao/udp-over-tcp"

func main() {
    // example code, ignore err check.
    conn, err := net.ListenPacket("udp", ":8080")
    client := uot.Client{
		Dialer: func(addr string) (uot.Conn, error) {
			conn, err := net.Dial("tcp", addr)
			if err != nil {
				return nil, err
			}
			return uot.DefaultOutConn(conn), nil
		},
    }
    client.Serve(uot.DefaultPacketConn(conn), "127.0.0.1:8088")
}

Above code listen udp packet on :8080 and forward to 127.0.0.1:8088 over tcp.

• server

import "github.com/justlovediaodiao/tcp-over-udp"

func main() {
    l, err := net.Listen("tcp", ":8088")
    var server uot.Server
    for {
		conn, err := l.Accept()
		go server.Serve(uot.DefaultInConn(conn))
	}
}

Above code listen tcp on :8088 and forward to target address over udp.

Usage

Implement PacketConn and Conn interface to define protocol.

PacketConn is udp packet connection. It's used by client, read udp packet, resolve target address and raw packet data.

Conn is tcp connection.

• In client side, send target address to server, then pack packets and forward to server. Read and unpack response packets from server.
• In server side, read target address from client, then unpack packets and forward to target address. Pack and write response packets to client.

Default Protocol

The library provides a default implement.

Protocol define of defaultPacketConn:

socks udp packet format, see RFC 1928 section 7.

Protocol define of defaultConn:

Request:

[handshake][packet...]

• handshake: target address of packet, which is a socks address defined in RFC 1928 section 4.
• packet:

[size][payload]

• size: 2-byte, length of payload.
• payload: raw udp packet.

Response:

[packet...]

same as Request, but with no handsahke.

Documentation

Index

• Constants
• type Client
  • func (c *Client) Serve(conn PacketConn, server string)
• type Conn
  • func DefaultInConn(conn net.Conn) Conn
  • func DefaultOutConn(conn net.Conn) Conn
• type PacketConn
  • func DefaultPacketConn(conn net.PacketConn) PacketConn
• type Server
  • func (s *Server) Serve(conn Conn) error
• type SocksAddr
  • func ParseSocksAddr(s string) SocksAddr
  • func ReadSocksAddr(r io.Reader) (SocksAddr, error)
  • func (addr SocksAddr) String() string

Constants

const MaxPacketSize = 65535 - 20 - 8

MaxPacketSize is max udp packet payload size. It is 65535 - 20(IP header) - 8(UDP header).

Types

type Client

type Client struct {
	// Dialer dial tcp to server and return a Conn.
	Dialer func(string) (Conn, error)
	// Timeout is used to close an inactive connection, default 5min.
	// Since udp is not connection based, we donot know when a udp connection closed.
	Timeout time.Duration
	// BufSize is max buffered udp packet count, default 8.
	// Since there's no Congestion-Control in udp,
	// if a large number of UDP packets arrived, there's no time to send it to remote over tcp.
	// if buffer is full, new udp packet will be dropped.
	BufSize int
	// Logf is log func, default nil, no log output.
	Logf func(string, ...interface{})
}

Client is client.

func (*Client) Serve

func (c *Client) Serve(conn PacketConn, server string)

Serve read udp packet and send to server over tcp. read response from server and send to address on the packet.

type Conn

type Conn interface {
	net.Conn
	// Handshake handle with target address of udp packet.
	// In server side, Handshake receives a nil net.Addr, read and return the target net.Addr.
	// In client side, Handshake receives a non-nil net.Addr, send target address to server.
	Handshake(net.Addr) (net.Addr, error)
}

Conn is an udp-over-tcp connection.

func DefaultInConn

func DefaultInConn(conn net.Conn) Conn

DefaultInConn return a default server side Conn.

func DefaultOutConn

func DefaultOutConn(conn net.Conn) Conn

DefaultOutConn return a default client side Conn.

type PacketConn

type PacketConn interface {
	net.PacketConn
	// ReadPacket is similar with ReadFrom.
	// It returns readed packet length, target address of udp packet, remote address, error.
	ReadPacket(p []byte) (n int, target net.Addr, addr net.Addr, err error)
	// WritePacket is similar with WriteTo.
	// It writes packet to addr. target is origin packet addr.
	WritePacket(p []byte, target net.Addr, addr net.Addr) (n int, err error)
}

PacketConn is client side udp connection.

func DefaultPacketConn

func DefaultPacketConn(conn net.PacketConn) PacketConn

DefaultPacketConn return a default packet conn.

type Server

type Server struct {
	// Logf is log func, default nil, no log output.
	Logf func(string, ...interface{})
}

Server server.

func (*Server) Serve

func (s *Server) Serve(conn Conn) error

Serve read packet over tcp connection and send to target address in udp. read response from target address and send to address on the connection.

type SocksAddr

type SocksAddr []byte

SocksAddr is socks addr defined in RFC 1928.

func ParseSocksAddr

func ParseSocksAddr(s string) SocksAddr

ParseSocksAddr parses the address in string s. Returns nil if failed.

func ReadSocksAddr

func ReadSocksAddr(r io.Reader) (SocksAddr, error)

ReadSocksAddr read socks addr.

func (SocksAddr) String

func (addr SocksAddr) String() string

String return address string.