nethernet

README

nethernet-go

An implementation of NetherNet, the new transport layer introduced in Minecraft: Bedrock Edition based on WebRTC written in Go.

Getting started

Using a fork of pion/sctp

Because Mojang seems to have made several changes to their dcSCTP implementation, you need to use a fork of pion/sctp.

To use the fork, put the following (for example) replace directive in go.mod of your main module and run go mod tidy.

replace github.com/pion/sctp => github.com/lactyy/sctp latest

This workaround is planned to be removed in future release.

Documentation

Index

• Constants
• Variables
• type Addr
  • func (addr *Addr) Network() string
  • func (addr *Addr) String() string
• 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) ReadPacket() ([]byte, error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (*Conn) SetDeadline(time.Time) error
  • func (*Conn) SetReadDeadline(time.Time) error
  • func (*Conn) SetWriteDeadline(time.Time) error
  • func (c *Conn) Write(b []byte) (n int, err error)
• type Credentials
• type Dialer
  • func (d Dialer) DialContext(ctx context.Context, networkID uint64, signaling Signaling) (*Conn, error)
• type ICEServer
• type ListenConfig
  • func (conf ListenConfig) Listen(networkID uint64, signaling Signaling) (*Listener, error)
• type Listener
  • func (l *Listener) Accept() (net.Conn, error)
  • func (l *Listener) Addr() net.Addr
  • func (l *Listener) Close() error
  • func (l *Listener) ID() int64
  • func (l *Listener) PongData([]byte)
• type Signal
  • func (s *Signal) MarshalText() ([]byte, error)
  • func (s *Signal) String() string
  • func (s *Signal) UnmarshalText(b []byte) (err error)
• type Signaling

Constants

const (
	// SignalTypeOffer is sent by client to request a connection to the remote host. Signals that have
	// SignalTypeOffer usually has a data of local description of its connection.
	SignalTypeOffer = "CONNECTREQUEST"
	// SignalTypeAnswer is sent by server to respond to Signals that have SignalTypeOffer. Signals that
	// have SignalTypeAnswer usually has a data of local description of the host.
	SignalTypeAnswer = "CONNECTRESPONSE"
	// SignalTypeCandidate is sent by both server and client to notify a local candidate to
	// remote connection. This is usually sent after SignalTypeOffer or SignalTypeAnswer by server/client.
	// Signals that have SignalTypeCandidate usually has a data of local candidate gathered with additional
	// credentials received from the Signaling implementation.
	SignalTypeCandidate = "CANDIDATEADD"
	// SignalTypeError is sent by both server and client to notify an error has occurred.
	// Signals that have SignalTypeError has a Data of the code of error occurred, which is listed
	// on the following constants.
	SignalTypeError = "CONNECTERROR"
)

const (
	ErrorCodeNone = iota
	ErrorCodeDestinationNotLoggedIn
	ErrorCodeNegotiationTimeout
	ErrorCodeWrongTransportVersion
	ErrorCodeFailedToCreatePeerConnection
	ErrorCodeICE
	ErrorCodeConnectRequest
	ErrorCodeConnectResponse
	ErrorCodeCandidateAdd
	ErrorCodeInactivityTimeout
	ErrorCodeFailedToCreateOffer
	ErrorCodeFailedToCreateAnswer
	ErrorCodeFailedToSetLocalDescription
	ErrorCodeFailedToSetRemoteDescription
	ErrorCodeNegotiationTimeoutWaitingForResponse
	ErrorCodeNegotiationTimeoutWaitingForAccept
	ErrorCodeIncomingConnectionIgnored
	ErrorCodeSignalingParsingFailure
	ErrorCodeSignalingUnknownError
	ErrorCodeSignalingUnicastMessageDeliveryFailed
	ErrorCodeSignalingBroadcastDeliveryFailed
	ErrorCodeSignalingMessageDeliveryFailed
	ErrorCodeSignalingTurnAuthFailed
	ErrorCodeSignalingFallbackToBestEffortDelivery
	ErrorCodeNoSignalingChannel
	ErrorCodeNotLoggedIn
	ErrorCodeSignalingFailedToSend
)

Variables

var ErrSignalingCanceled = errors.New("minecraft/nethernet: canceled")

Types

type Addr

type Addr struct {
	ConnectionID uint64
	NetworkID    uint64
	Candidates   []webrtc.ICECandidate
}

Addr represents a net.Addr from the ConnectionID and NetworkID. It also includes a slice of remote Candidates signaled from the remote connection.

func (*Addr) Network

func (addr *Addr) Network() string

func (*Addr) String

func (addr *Addr) String() string

type Conn

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

func (*Conn) Close

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

Close closes the Conn.

func (*Conn) LocalAddr

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

LocalAddr returns an Addr of local network ID. It also contains locally-gathered ICE candidates.

func (*Conn) Read

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

func (*Conn) ReadPacket

func (c *Conn) ReadPacket() ([]byte, error)

func (*Conn) RemoteAddr

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

RemoteAddr returns an Addr of remote network ID. It also contains remotely-signaled ICE candidates.

func (*Conn) SetDeadline

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

func (*Conn) SetReadDeadline

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

func (*Conn) SetWriteDeadline

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

func (*Conn) Write

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

type Credentials

type Credentials struct {
	ExpirationInSeconds int         `json:"ExpirationInSeconds"`
	ICEServers          []ICEServer `json:"TurnAuthServers"`
}

type Dialer

type Dialer struct {
	// NetworkID and ConnectionID are the local IDs of a Conn being established. If
	// left as zero, a random value will automatically set from rand.Uint64.
	NetworkID, ConnectionID uint64

	// API specifies custom configuration for WebRTC transports, and data channels.
	API *webrtc.API

	// Log is used to output several messages at many log levels. If left as nil, the
	// default [slog.Logger] will be set from [slog.Default].
	Log *slog.Logger
}

func (Dialer) DialContext

func (d Dialer) DialContext(ctx context.Context, networkID uint64, signaling Signaling) (*Conn, error)

DialContext establishes a connection with the remote network ID. An implementation of Signaling is used to signal an offer and local candidates, and receiving answer and remote candidates. The context.Context may be used to cancel the connection as soon as possible. A Conn may be returned, that is ready to receive and send packets.

type ICEServer

type ICEServer struct {
	Username string   `json:"Username"`
	Password string   `json:"Password"`
	URLs     []string `json:"Urls"`
}

type ListenConfig

type ListenConfig struct {
	// Log is used to output several messages at many log levels. If left as nil, the
	// default [slog.Logger] will be set from [slog.Default].
	Log *slog.Logger

	// API specifies custom configuration for WebRTC transports, and data channels.
	API *webrtc.API
}

func (ListenConfig) Listen

func (conf ListenConfig) Listen(networkID uint64, signaling Signaling) (*Listener, error)

Listen listens on the local network ID. The Signaling implementation is used to receive signals from the remote connections. A Listener will be returned, that is ready to accept established Conn.

type Listener

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

Listener implements a NetherNet connection listener.

func (*Listener) Accept

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

Accept waits for and returns the next Conn to the listener. An error may be returned, if the listener has been closed.

func (*Listener) Addr

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

Addr returns an Addr of network ID of Listener.

func (*Listener) Close

func (l *Listener) Close() error

Close closes the Listener.

func (*Listener) ID

func (l *Listener) ID() int64

ID returns the network ID of Listener.

func (*Listener) PongData

func (l *Listener) PongData([]byte)

PongData is a stub.

type Signal

type Signal struct {
	// Type is the type of Signal. It is one of the constants defined above.
	Type string
	// ConnectionID is the unique ID of the connection that has sent the Signal.
	// It is encoded in String as a second segment to identify a connection uniquely.
	ConnectionID uint64
	// Data is the actual data of the Signal.
	Data string

	// NetworkID is used internally by the implementations of Signaling type
	// to reference a remote network with a number.
	NetworkID uint64
}

func (*Signal) MarshalText

func (s *Signal) MarshalText() ([]byte, error)

func (*Signal) String

func (s *Signal) String() string

func (*Signal) UnmarshalText

func (s *Signal) UnmarshalText(b []byte) (err error)

type Signaling

type Signaling interface {
	ReadSignal(cancel <-chan struct{}) (*Signal, error)
	WriteSignal(signal *Signal) error

	// Credentials will currently block until a credentials has received from the signaling service. This is usually
	// present in WebSocket signaling connection. A nil *Credentials may be returned if no credentials or
	// the implementation is not capable to do that.
	Credentials() (*Credentials, error)
}