raknet

README

go-raknet

go-raknet is a library that implements a basic version of the RakNet protocol, which is used for Minecraft (Bedrock Edition). It implements Unreliable, Reliable and ReliableOrdered packets and sends user packets as ReliableOrdered.

go-raknet attempts to abstract away direct interaction with RakNet, and provides simple to use, idiomatic Go API used to listen for connections or connect to servers.

Getting started

Prerequisites

As of go-raknet version 1.14.0, go-raknet requires at least Go 1.22. Version 1.12.1 of go-raknet is the last version of the library that supports Go 1.18 and above.

Usage

go-raknet can be used for both clients and servers, (and proxies, when combined) in a way very similar to the standard net.TCP* functions.

Basic RakNet server:

package main

import (
	"github.com/DannerTomas/go-raknet"
)

func main() {
    listener, _ := raknet.Listen("0.0.0.0:19132")
    defer listener.Close()
    for {
        conn, _ := listener.Accept()
        
        b := make([]byte, 1024*1024*4)
        _, _ = conn.Read(b)
        _, _ = conn.Write([]byte{1, 2, 3})
        
        conn.Close()
    }
}

Basic RakNet client:

package main

import (
	"github.com/DannerTomas/go-raknet"
)

func main() {
    conn, _ := raknet.Dial("mco.mineplex.com:19132")
    defer conn.Close()
    
    b := make([]byte, 1024*1024*4)
    _, _ = conn.Write([]byte{1, 2, 3})
    _, _ = conn.Read(b)
}

Documentation

Contact

Documentation

Index

• Variables
• func Ping(address string) (response []byte, err error)
• func PingContext(ctx context.Context, address string) (response []byte, err error)
• func PingTimeout(address string, timeout time.Duration) ([]byte, error)
• type Conn
  • func Dial(address string) (*Conn, error)
  • func DialContext(ctx context.Context, address string) (*Conn, error)
  • func DialTimeout(address string, timeout time.Duration) (*Conn, error)
  • func (conn *Conn) Close() error
  • func (conn *Conn) Latency() time.Duration
  • func (conn *Conn) LocalAddr() net.Addr
  • func (conn *Conn) Read(b []byte) (n int, err error)
  • func (conn *Conn) ReadPacket() (b []byte, err error)
  • func (conn *Conn) RemoteAddr() net.Addr
  • func (conn *Conn) SetDeadline(time.Time) error
  • func (conn *Conn) SetReadDeadline(time.Time) error
  • func (conn *Conn) SetWriteDeadline(time.Time) error
  • func (conn *Conn) Write(b []byte) (n int, err error)
• type Dialer
  • func (dialer Dialer) Dial(address string) (*Conn, error)
  • func (dialer Dialer) DialContext(ctx context.Context, address string) (*Conn, error)
  • func (dialer Dialer) DialTimeout(address string, timeout time.Duration) (*Conn, error)
  • func (dialer Dialer) Ping(address string) ([]byte, error)
  • func (dialer Dialer) PingContext(ctx context.Context, address string) (response []byte, err error)
  • func (dialer Dialer) PingTimeout(address string, timeout time.Duration) ([]byte, error)
• type ListenConfig
  • func (conf ListenConfig) Listen(address string) (*Listener, error)
• type Listener
  • func Listen(address string) (*Listener, error)
  • func (listener *Listener) Accept() (net.Conn, error)
  • func (listener *Listener) Addr() net.Addr
  • func (listener *Listener) Close() error
  • func (listener *Listener) ID() int64
  • func (listener *Listener) PongData(data []byte)
• type UpstreamDialer
• type UpstreamPacketListener

Examples

• Dial
• Listen
• Ping

Variables

var (
	// ErrBufferTooSmall is returned when Conn.Read is called with a byte slice
	// that is too small to contain the packet to be read.
	ErrBufferTooSmall = errors.New("a message sent was larger than the buffer used to receive the message into")
	// ErrListenerClosed is returned when Listener.Accept is called on a closed
	// listener.
	ErrListenerClosed = errors.New("use of closed listener")
	// ErrNotSupported is returned for deadline methods of a Conn, which are not
	// supported on a raknet.Conn.
	ErrNotSupported = errors.New("feature not supported")
)

Functions

func Ping

func Ping(address string) (response []byte, err error)

Ping sends a ping to an address and returns the response obtained. If successful, a non-nil response byte slice containing the data is returned. If the ping failed, an error is returned describing the failure. Note that the packet sent to the server may be lost due to the nature of UDP. If this is the case, an error is returned which implies a timeout occurred. Ping will time out after 5 seconds.

Example

const address = "mco.mineplex.com:19132"

// Ping the target address. This will ping with a timeout of 5 seconds. raknet.PingContext and
// raknet.PingTimeout may be used to cancel at any other time.
data, err := raknet.Ping(address)
if err != nil {
	panic("error pinging " + address + ": " + err.Error())
}
str := string(data)

fmt.Println(str[:4])

Output:

MCPE

func PingContext

func PingContext(ctx context.Context, address string) (response []byte, err error)

PingContext sends a ping to an address and returns the response obtained. If successful, a non-nil response byte slice containing the data is returned. If the ping failed, an error is returned describing the failure. Note that the packet sent to the server may be lost due to the nature of UDP. If this is the case, PingContext could last indefinitely, hence a timeout should always be attached to the context passed. PingContext cancels as soon as the deadline expires.

func PingTimeout

func PingTimeout(address string, timeout time.Duration) ([]byte, error)

PingTimeout sends a ping to an address and returns the response obtained. If successful, a non-nil response byte slice containing the data is returned. If the ping failed, an error is returned describing the failure. Note that the packet sent to the server may be lost due to the nature of UDP. If this is the case, an error is returned which implies a timeout occurred. PingTimeout will time out after the duration passed.

Types

type Conn

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

Conn represents a connection to a specific client. It is not a real connection, as UDP is connectionless, but rather a connection emulated using RakNet. Methods may be called on Conn from multiple goroutines simultaneously.

func Dial

func Dial(address string) (*Conn, error)

Dial attempts to dial a RakNet connection to the address passed. The address may be either an IP address or a hostname, combined with a port that is separated with ':'. Dial will attempt to dial a connection within 10 seconds. If not all packets are received after that, the connection will time out and an error will be returned. Dial fills out a Dialer struct with a default error logger.

Example

const address = "mco.mineplex.com:19132"

// Dial a connection to the target address. This will time out after up to 10 seconds. raknet.DialTimeout
// and raknet.DialContext may be used to cancel at any other time.
conn, err := raknet.Dial(address)
if err != nil {
	panic("error connecting to " + address + ": " + err.Error())
}

// Read a packet from the connection dialed.
p := make([]byte, 1500)
n, err := conn.Read(p)
if err != nil {
	panic("error reading packet from " + address + ": " + err.Error())
}
p = p[:n]

// Write a packet to the connection.
data := []byte("Hello World!")
if _, err := conn.Write(data); err != nil {
	panic("error writing packet to " + address + ": " + err.Error())
}

// Close the connection after you're done with it.
if err := conn.Close(); err != nil {
	panic("error closing connection: " + err.Error())
}

func DialContext

func DialContext(ctx context.Context, address string) (*Conn, error)

DialContext attempts to dial a RakNet connection to the address passed. The address may be either an IP address or a hostname, combined with a port that is separated with ':'. DialContext will use the deadline (ctx.Deadline) of the context.Context passed for the maximum amount of time that the dialing can take. DialContext will terminate as soon as possible when the context.Context is closed.

func DialTimeout

func DialTimeout(address string, timeout time.Duration) (*Conn, error)

DialTimeout attempts to dial a RakNet connection to the address passed. The address may be either an IP address or a hostname, combined with a port that is separated with ':'. DialTimeout will attempt to dial a connection within the timeout duration passed. If not all packets are received after that, the connection will time out and an error will be returned.

func (*Conn) Close

func (conn *Conn) Close() error

Close closes the connection. All blocking Read or Write actions are cancelled and will return an error, as soon as the closing of the connection is acknowledged by the client.

func (*Conn) Latency

func (conn *Conn) Latency() time.Duration

Latency returns a rolling average of rtt between the sending and the receiving end of the connection. The rtt returned is updated continuously and is half the average round trip time (RTT).

func (*Conn) LocalAddr

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

LocalAddr returns the local address of the connection, which is always the same as the listener's.

func (*Conn) Read

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

Read reads from the connection into the byte slice passed. If successful, the amount of bytes read n is returned, and the error returned will be nil. Read blocks until a packet is received over the connection, or until the session is closed or the read times out, in which case an error is returned.

func (*Conn) ReadPacket

func (conn *Conn) ReadPacket() (b []byte, err error)

ReadPacket attempts to read the next packet as a byte slice. ReadPacket blocks until a packet is received over the connection, or until the session is closed or the read times out, in which case an error is returned.

func (*Conn) RemoteAddr

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

RemoteAddr returns the remote address of the connection, meaning the address this connection leads to.

func (*Conn) SetDeadline

func (conn *Conn) SetDeadline(time.Time) error

SetDeadline is unimplemented. It always returns ErrNotSupported.

func (*Conn) SetReadDeadline

func (conn *Conn) SetReadDeadline(time.Time) error

SetReadDeadline is unimplemented. It always returns ErrNotSupported.

func (*Conn) SetWriteDeadline

func (conn *Conn) SetWriteDeadline(time.Time) error

SetWriteDeadline is unimplemented. It always returns ErrNotSupported.

func (*Conn) Write

func (conn *Conn) Write(b []byte) (n int, err error)

Write writes a buffer b over the RakNet connection. The amount of bytes written n is always equal to the length of the bytes written if writing was successful. If not, an error is returned and n is 0. Write may be called simultaneously from multiple goroutines, but will write one by one.

type Dialer

type Dialer struct {
	// ErrorLog is a logger that errors from packet decoding are logged to. By
	// default, ErrorLog is set to a new slog.Logger with a slog.Handler that
	// is always disabled. Error messages are thus not logged by default.
	ErrorLog *slog.Logger

	// UpstreamDialer is a dialer that will override the default dialer for
	// opening outgoing connections. The default is a net.Dial("udp", ...).
	UpstreamDialer UpstreamDialer
}

Dialer allows dialing a RakNet connection with specific configuration, such as the protocol version of the connection and the logger used.

func (Dialer) Dial

func (dialer Dialer) Dial(address string) (*Conn, error)

Dial attempts to dial a RakNet connection to the address passed. The address may be either an IP address or a hostname, combined with a port that is separated with ':'. Dial will attempt to dial a connection within 10 seconds. If not all packets are received after that, the connection will timeout and an error will be returned.

func (Dialer) DialContext

func (dialer Dialer) DialContext(ctx context.Context, address string) (*Conn, error)

DialContext attempts to dial a RakNet connection to the address passed. The address may be either an IP address or a hostname, combined with a port that is separated with ':'. DialContext will use the deadline (ctx.Deadline) of the context.Context passed for the maximum amount of time that the dialing can take. DialContext will terminate as soon as possible when the context.Context is closed.

func (Dialer) DialTimeout

func (dialer Dialer) DialTimeout(address string, timeout time.Duration) (*Conn, error)

DialTimeout attempts to dial a RakNet connection to the address passed. The address may be either an IP address or a hostname, combined with a port that is separated with ':'. DialTimeout will attempt to dial a connection within the timeout duration passed. If not all packets are received after that, the connection will time out and an error will be returned.

func (Dialer) Ping

func (dialer Dialer) Ping(address string) ([]byte, error)

Ping sends a ping to an address and returns the response obtained. If successful, a non-nil response byte slice containing the data is returned. If the ping failed, an error is returned describing the failure. Note that the packet sent to the server may be lost due to the nature of UDP. If this is the case, an error is returned which implies a timeout occurred. Ping will time out after 5 seconds.

func (Dialer) PingContext

func (dialer Dialer) PingContext(ctx context.Context, address string) (response []byte, err error)

PingContext sends a ping to an address and returns the response obtained. If successful, a non-nil response byte slice containing the data is returned. If the ping failed, an error is returned describing the failure. Note that the packet sent to the server may be lost due to the nature of UDP. If this is the case, PingContext could last indefinitely, hence a timeout should always be attached to the context passed. PingContext cancels as soon as the deadline expires.

func (Dialer) PingTimeout

func (dialer Dialer) PingTimeout(address string, timeout time.Duration) ([]byte, error)

PingTimeout sends a ping to an address and returns the response obtained. If successful, a non-nil response byte slice containing the data is returned. If the ping failed, an error is returned describing the failure. Note that the packet sent to the server may be lost due to the nature of UDP. If this is the case, an error is returned which implies a timeout occurred. PingTimeout will time out after the duration passed.

type ListenConfig

type ListenConfig struct {
	// ErrorLog is a logger that errors from packet decoding are logged to. By
	// default, ErrorLog is set to a new slog.Logger with a slog.Handler that
	// is always disabled. Error messages are thus not logged by default.
	ErrorLog *slog.Logger

	// UpstreamPacketListener adds an abstraction for net.ListenPacket.
	UpstreamPacketListener UpstreamPacketListener

	// DisableCookies specifies if cookies should be generated and verified for
	// new incoming connections. This is a security measure against IP spoofing,
	// but some server providers (OVH in particular) have existing protection
	// systems that interfere with this. In this case, DisableCookies should be
	// set to true.
	DisableCookies bool
	// BlockDuration specifies how long IP addresses should be blocked if an
	// error is encountered during the handling of packets from an address.
	// BlockDuration defaults to 10s. If set to a negative value, IP addresses
	// are never blocked on errors.
	BlockDuration time.Duration
}

ListenConfig may be used to pass additional configuration to a Listener.

func (ListenConfig) Listen

func (conf ListenConfig) Listen(address string) (*Listener, error)

Listen listens on the address passed and returns a listener that may be used to accept connections. If not successful, an error is returned. The address follows the same rules as those defined in the net.TCPListen() function. Specific features of the listener may be modified once it is returned, such as the used log and/or the accepted protocol.

type Listener

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

Listener implements a RakNet connection listener. It follows the same methods as those implemented by the TCPListener in the net package. Listener implements the net.Listener interface.

func Listen

func Listen(address string) (*Listener, error)

Listen listens on the address passed and returns a listener that may be used to accept connections. If not successful, an error is returned. The address follows the same rules as those defined in the net.TCPListen() function. Specific features of the listener may be modified once it is returned, such as the used log and/or the accepted protocol.

Example

const address = ":19132"

// Start listening on an address.
l, err := raknet.Listen(address)
if err != nil {
	panic(err)
}

for {
	// Accept a new connection from the Listener. Accept will only return an error if the Listener is
	// closed. (So only after a call to Listener.Close.)
	conn, err := l.Accept()
	if err != nil {
		return
	}

	// Read a packet from the connection accepted.
	p := make([]byte, 1500)
	n, err := conn.Read(p)
	if err != nil {
		panic("error reading packet from " + conn.RemoteAddr().String() + ": " + err.Error())
	}
	p = p[:n]

	// Write a packet to the connection.
	data := []byte("Hello World!")
	if _, err := conn.Write(data); err != nil {
		panic("error writing packet to " + conn.RemoteAddr().String() + ": " + err.Error())
	}

	// Close the connection after you're done with it.
	if err := conn.Close(); err != nil {
		panic("error closing connection: " + err.Error())
	}
}

func (*Listener) Accept

func (listener *Listener) Accept() (net.Conn, error)

Accept blocks until a connection can be accepted by the listener. If successful, Accept returns a connection that is ready to send and receive data. If not successful, a nil listener is returned and an error describing the problem.

func (*Listener) Addr

func (listener *Listener) Addr() net.Addr

Addr returns the address the Listener is bound to and listening for connections on.

func (*Listener) Close

func (listener *Listener) Close() error

Close closes the listener so that it may be cleaned up. It makes sure the goroutine handling incoming packets is able to be freed.

func (*Listener) ID

func (listener *Listener) ID() int64

ID returns the unique ID of the listener. This ID is usually used by a client to identify a specific server during a single session.

func (*Listener) PongData

func (listener *Listener) PongData(data []byte)

PongData sets the pong data that is used to respond with when a client sends a ping. It usually holds game specific data that is used to display in a server list. If a data slice is set with a size bigger than math.MaxInt16, the function panics.

type UpstreamDialer

type UpstreamDialer interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

UpstreamDialer is an interface for anything compatible with net.Dialer.

type UpstreamPacketListener

type UpstreamPacketListener interface {
	ListenPacket(network, address string) (net.PacketConn, error)
}

UpstreamPacketListener allows for a custom PacketListener implementation.