utp

README

Go μTP

Go implementation of the Micro Transport Protocol.

Getting Started

First you will need a net.PacketConn. This can be anything implementing the interface. There are no abstraction-breaking checks for a particular implementation. Then use utp.NewSocket to get started.

func createSocket() *utp.Socket {
    // Create a UDP socket listening on all addresses
    pc, err := net.ListenPacket("udp", "0.0.0.0:0")
    if err != nil {
        panic(err)
    }

    // Call utp.New to create a *utp.Socket from the net.PacketConn
    s := utp.NewSocket(pc)
    return s
}

// As a server
func useAsServer(s *utp.Socket) error {
    for {
        conn, err := s.Accept()
        go func() {
            defer conn.Close()
            // handle the conn
        }
    }
}

// As a client
func useAsClient(s *utp.Socket, raddr net.Addr) error {
    conn, err := s.DialContext(ctx, raddr)
    if err != nil {
        return err
    }
    defer conn.Close
    // send some data to the other party
    _, err := conn.Write([]byte("hello world"))
    return err
}

Instrumentation

All logging and metrics are provided by the stdctx library. If you want logs or metrics just configure a context as described there, and pass it in.

Contributing

just is used to run commands.

just test runs the tests.

Contributions are welcome.

Roadmap

Long term it would be best for the implementation to change to be more testable. The Socket and Conn objects are the right API (adhearing to net.Listener/net.Dialer and net.Conn respectively), but they are difficult to test. There needs to be a state machine object, which doesn't have go routines or timers internally, so that arbitrary stimulus at arbitrary states can be tested.

Fork

Orginally forked from github.com/anacrolix/utp. There were a number of reasons for forking:

• The pure go implementation is deprecated in favor of a C-Go port of libutp. This fork will continue to be pure Go.
• The API was very UDP specifc, taking string addresses in several places.
• Legacy logging, and instrumentation.
• High quality user experience on top of INET256.

Documentation

Overview

Package utp implements uTP, the micro transport protocol as used with Bittorrent. It opts for simplicity and reliability over strict adherence to the (poor) spec. It allows using the underlying OS-level transport despite dispatching uTP on top to allow for example, shared socket use with DHT. Additionally, multiple uTP connections can share the same OS socket, to truly realize uTP's claim to be light on system and network switching resources.

Socket is a wrapper of net.PacketConn, and performs dispatching of uTP packets to attached uTP Conns. Dial and Accept is done via Socket. Conn implements net.Conn over uTP, via aforementioned Socket.

Index

• Constants
• Variables
• func IsAckTimeout(err error) bool
• func IsTimeout(err error) bool
• func WriteStatus(w io.Writer)
• type Conn
  • func (c *Conn) Close() (err error)
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) Read(b []byte) (n int, err error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) String() string
  • func (c *Conn) Write(p []byte) (n int, err error)
• type ConnOption
• type ErrTimeout
  • func (e ErrTimeout) Error() string
  • func (e ErrTimeout) Temporary() bool
  • func (e ErrTimeout) Timeout() bool
• type Socket
  • func NewSocket(pc net.PacketConn, opts ...SocketOption) *Socket
  • func (s *Socket) Accept() (net.Conn, error)
  • func (s *Socket) Addr() net.Addr
  • func (s *Socket) Close() error
  • func (s *Socket) CloseNow() error
  • func (s *Socket) DialContext(ctx context.Context, addr net.Addr) (nc net.Conn, err error)
  • func (s *Socket) LocalAddr() net.Addr
  • func (s *Socket) ReadFrom(p []byte) (n int, addr net.Addr, err error)
  • func (c *Socket) SetDeadline(t time.Time) error
  • func (c *Socket) SetReadDeadline(t time.Time) error
  • func (c *Socket) SetWriteDeadline(t time.Time) error
  • func (s *Socket) WriteTo(b []byte, addr net.Addr) (n int, err error)
• type SocketOption
  • func WithBackground(ctx context.Context) SocketOption
  • func WithBacklogLen(n int) SocketOption
  • func WithConnOption(o ConnOption) SocketOption
  • func WithInitialLatency(d time.Duration) SocketOption
  • func WithPacketReadTimeout(d time.Duration) SocketOption
  • func WithWriteTimeout(d time.Duration) SocketOption

Constants

const (
	DefaultBacklogLen = 50
)

Variables

var (
	ErrClosed = net.ErrClosed
)

Functions

func IsAckTimeout

func IsAckTimeout(err error) bool

func IsTimeout

func IsTimeout(err error) bool

func WriteStatus

func WriteStatus(w io.Writer)

Types

type Conn

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

Conn is a uTP stream and implements net.Conn. It owned by a Socket, which handles dispatching packets to and from Conns.

func (*Conn) Close

func (c *Conn) Close() (err error)

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

func (*Conn) Read

func (c *Conn) Read(b []byte) (n int, err error)

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

func (*Conn) String

func (c *Conn) String() string

func (*Conn) Write

func (c *Conn) Write(p []byte) (n int, err error)

type ConnOption

type ConnOption func(*connConfig)

ConnOption is used to configure Conn specific options

type ErrTimeout

type ErrTimeout struct {
	IsAck bool
	Msg   string
}

func (ErrTimeout) Error

func (e ErrTimeout) Error() string

func (ErrTimeout) Temporary

func (e ErrTimeout) Temporary() bool

func (ErrTimeout) Timeout

func (e ErrTimeout) Timeout() bool

type Socket

type Socket struct {

	// If a read error occurs on the underlying net.PacketConn, it is put
	// here. This is because reading is done in its own goroutine to dispatch
	// to uTP Conns.
	ReadErr error
	// contains filtered or unexported fields
}

A Socket wraps a net.PacketConn, diverting uTP packets to its child uTP Conns.

func NewSocket

func NewSocket(pc net.PacketConn, opts ...SocketOption) *Socket

NewSocket creates a net.PacketConn with the given network and address, and returns a Socket dispatching on it. Create a Socket, using the provided net.PacketConn. If you want to retain use of the net.PacketConn after the Socket closes it, override the net.PacketConn's Close method, or use NetSocketFromPacketConnNoClose.

func (*Socket) Accept

func (s *Socket) Accept() (net.Conn, error)

Accept and return a new uTP connection.

func (*Socket) Addr

func (s *Socket) Addr() net.Addr

The address we're listening on for new uTP connections.

func (*Socket) Close

func (s *Socket) Close() error

func (*Socket) CloseNow

func (s *Socket) CloseNow() error

func (*Socket) DialContext

func (s *Socket) DialContext(ctx context.Context, addr net.Addr) (nc net.Conn, err error)

func (*Socket) LocalAddr

func (s *Socket) LocalAddr() net.Addr

LocalAddr returns the local address of the underlying socket.

func (*Socket) ReadFrom

func (s *Socket) ReadFrom(p []byte) (n int, addr net.Addr, err error)

ReadFrom DEPRECATED:

func (*Socket) SetDeadline

func (c *Socket) SetDeadline(t time.Time) error

func (*Socket) SetReadDeadline

func (c *Socket) SetReadDeadline(t time.Time) error

func (*Socket) SetWriteDeadline

func (c *Socket) SetWriteDeadline(t time.Time) error

func (*Socket) WriteTo

func (s *Socket) WriteTo(b []byte, addr net.Addr) (n int, err error)

WriteTo DEPRECATED

type SocketOption

type SocketOption func(*socketConfig)

SocketOption configures a Socket

func WithBackground

func WithBackground(ctx context.Context) SocketOption

WithBackground sets the background context. This can be used to enable instrumentation with the stdctx library.

func WithBacklogLen

func WithBacklogLen(n int) SocketOption

Maximum received SYNs that haven't been accepted. If more SYNs are received, a pseudo randomly selected SYN is replied to with a reset to make room.

func WithConnOption

func WithConnOption(o ConnOption) SocketOption

func WithInitialLatency

func WithInitialLatency(d time.Duration) SocketOption

This is the latency we assume on new connections. It should be higher than the latency we expect on most connections to prevent excessive resending to peers that take a long time to respond, before we've got a better idea of their actual latency.

func WithPacketReadTimeout

func WithPacketReadTimeout(d time.Duration) SocketOption

func WithWriteTimeout

func WithWriteTimeout(d time.Duration) SocketOption

If a write isn't acked within this period, destroy the connection.