netmc

Documentation

Index

• Variables
• func Assert[T any](c any) (T, bool)
• func CloseUnknown(c MinecraftConn) error
• func CloseWith(c MinecraftConn, packet proto.Packet) (err error)
• func Closed(c interface{ ... }) bool
• func KnownDisconnect(c MinecraftConn) bool
• func SendKeepAlive(c interface{ ... }) error
• type MinecraftConn
  • func NewMinecraftConn(ctx context.Context, base net.Conn, direction proto.Direction, ...) (conn MinecraftConn, startReadLoop func())
• type PacketWriter
• type Reader
  • func NewReader(conn net.Conn, direction proto.Direction, readTimeout time.Duration, ...) Reader
• type SessionHandler
• type StateChanger
• type Writer
  • func NewWriter(conn net.Conn, direction proto.Direction, writeTimeout time.Duration, ...) Writer

Variables

var ErrClosedConn = errors.New("connection is closed")

ErrClosedConn indicates a connection is already closed.

var ErrReadPacketRetry = errors.New("error reading packet, retry")

ErrReadPacketRetry is returned by ReadPacket when the reader should retry reading the next packet.

Functions

func Assert

func Assert[T any](c any) (T, bool)

Assert is a utility func that asserts a connection implements an interface T.

e.g. usage `Assert[GameProfileProvider](connection)`

func CloseUnknown

func CloseUnknown(c MinecraftConn) error

CloseUnknown closes the connection on for an unexpected disconnect. Use MinecraftConn.Close to prevent logging of disconnects that are expected.

func CloseWith

func CloseWith(c MinecraftConn, packet proto.Packet) (err error)

CloseWith closes the connection after writing the packet.

func Closed

func Closed(c interface{ Context() context.Context }) bool

Closed returns true if the connection is closed.

func KnownDisconnect

func KnownDisconnect(c MinecraftConn) bool

KnownDisconnect returns true if the connection was or will be expectedly closed by the server.

func SendKeepAlive

func SendKeepAlive(c interface {
	State() *state.Registry
	WritePacket(proto.Packet) error
}) error

SendKeepAlive sends a keep-alive packet to the connection if in Play state. This prevents a connection timeout.

Types

type MinecraftConn

type MinecraftConn interface {
	// Context returns the context of the connection.
	// This Context is canceled on Close and can be used to attach more context values to a connection.
	Context() context.Context
	// Close closes the connection, if not already, and calls SessionHandler.Disconnected.
	// It is okay to call this method multiple times.
	// If the connection is in a closing state Close blocks until the connection completed the close.
	// To check whether a connection is closed use Closed.
	Close() error

	// State returns the current state of the connection.
	State() *state.Registry

	// Protocol returns the protocol version of the connection.
	Protocol() proto.Protocol

	// RemoteAddr returns the remote address of the connection.
	RemoteAddr() net.Addr
	// LocalAddr returns the local address of the connection.
	LocalAddr() net.Addr

	// Type returns the connection type of the connection.
	Type() phase.ConnectionType
	// SetType sets the connection type of the connection.
	SetType(phase.ConnectionType)

	// ActiveSessionHandler returns the session handler of the connection.
	ActiveSessionHandler() SessionHandler
	// SetActiveSessionHandler sets the session handler for this connection,
	// calls Deactivated() on the previous handler and Activated() on the new handler.
	SetActiveSessionHandler(*state.Registry, SessionHandler)
	// SwitchSessionHandler switches the active session handler to the respective registry one.
	// Returns true if the session handler was switched or is already in the respective state.
	// Returns false if the session handler does not exist for the state.
	SwitchSessionHandler(*state.Registry) bool
	// AddSessionHandler adds a session handler for the respective registry that will be used
	// when calling SwitchSessionHandler on the same registry.
	AddSessionHandler(*state.Registry, SessionHandler)

	// SetAutoReading sets whether the connection should automatically read packets from the underlying connection.
	// Default is true.
	SetAutoReading(bool)

	StateChanger
	PacketWriter

	Reader() Reader // Only use if you know what you are doing!
	Writer() Writer
	EnablePlayPacketQueue()
}

MinecraftConn is a Minecraft connection of a client or server. The connection is unusable after Close was called and must be recreated.

func NewMinecraftConn

func NewMinecraftConn(
	ctx context.Context,
	base net.Conn,
	direction proto.Direction,
	readTimeout time.Duration,
	writeTimeout time.Duration,
	compressionLevel int,
) (conn MinecraftConn, startReadLoop func())

NewMinecraftConn returns a new MinecraftConn and the func to start the blocking read-loop.

type PacketWriter

type PacketWriter interface {
	// WritePacket writes a packet to the connection's
	// write buffer and flushes the complete buffer afterward.
	//
	// The connection will be closed on any error encountered!
	WritePacket(p proto.Packet) (err error)
	// Write encodes and writes payload to the connection's
	// write buffer and flushes the complete buffer afterward.
	Write(payload []byte) (err error)

	// BufferPacket writes a packet into the connection's write buffer.
	BufferPacket(packet proto.Packet) (err error)
	// BufferPayload writes payload (containing packet id + data) to the connection's write buffer.
	BufferPayload(payload []byte) (err error)
	// Flush flushes the buffered data to the connection.
	Flush() error
}

PacketWriter is the interface for writing packets to the underlying connection.

type Reader

type Reader interface {
	// ReadPacket reads the next packet from the connection.
	// If the reader should retry reading the next packet, it returns ErrReadPacketRetry.
	// If the reader returns an error, it returns the connection is in a broken and should be closed.
	ReadPacket() (*proto.PacketContext, error)
	// ReadBuffered reads the remaining buffered bytes from the reader.
	// This is useful for emptying the Reader when it is not needed anymore.
	ReadBuffered() ([]byte, error)
	StateChanger
}

Reader is a packet reader.

func NewReader

func NewReader(conn net.Conn, direction proto.Direction, readTimeout time.Duration, log logr.Logger) Reader

NewReader returns a new packet reader.

type SessionHandler

type SessionHandler interface {
	HandlePacket(pc *proto.PacketContext) // Called to handle incoming known or unknown packet.
	Disconnected()                        // Called when connection is closing, to teardown the session.

	Activated()   // Called when the connection is now managed by this SessionHandler.
	Deactivated() // Called when the connection is no longer managed by this SessionHandler.
}

SessionHandler handles received packets from the associated connection.

Since connections transition between states packets need to be handled differently, this behaviour is divided between sessions by session handlers.

type StateChanger

type StateChanger interface {
	// SetProtocol switches the connection's protocol version.
	SetProtocol(proto.Protocol)
	// SetState switches the connection's state.
	SetState(state *state.Registry)
	// SetCompressionThreshold sets the compression threshold of the connection.
	// packet.SetCompression should be sent beforehand.
	SetCompressionThreshold(threshold int) error
	// EnableEncryption takes the secret key negotiated between the client and
	// the server to enable encryption on the connection.
	EnableEncryption(secret []byte) error
}

StateChanger updates state of a connection.

type Writer

type Writer interface {
	// WritePacket writes a packet to the connection's write buffer.
	WritePacket(packet proto.Packet) (n int, err error)
	// Write encodes payload and writes it to the underlying writer.
	// The payload must not already be compressed nor encrypted and must
	// start with the packet's id VarInt and then the packet's data.
	Write(payload []byte) (n int, err error)
	// Flush flushes the connection's write buffer.
	Flush() (err error)

	StateChanger
	Direction() proto.Direction
}

Writer is a packet writer.

func NewWriter

func NewWriter(conn net.Conn, direction proto.Direction, writeTimeout time.Duration, compressionLevel int, log logr.Logger) Writer

NewWriter returns a new packet writer.