anygatecloud/strom
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add godoc comments to all exported functions and methods

Browse Source
This commit is contained in:
adman
2026-07-30 00:20:55 +02:00
parent 56c97a2b3f
commit 0d6b6e1ab9
50 changed files with 186 additions and 408 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mc/proto/connection.go
+13
View File
@@ -73,6 +73,7 @@ type Conn struct {
Log *slog.Logger
}
// StartConn starts the connection event loop, registering the receive routine and login tick handler.
func (c *Conn) StartConn() (err error) {
c.RegisterEventSource(c.ActivateReceiveRoutine())
c.RegisterCritical(c.OnLoginTick)
@@ -81,6 +82,7 @@ func (c *Conn) StartConn() (err error) {
return
}
// OnLoginTick handles a login tick by receiving a packet and firing it as an event.
func (c *Conn) OnLoginTick(_ LoginTick) (err error) {
packet, err := c.Receive()
if err != nil {
@@ -90,30 +92,35 @@ func (c *Conn) OnLoginTick(_ LoginTick) (err error) {
return
}
// SetState sets the connection's protocol state.
func (c *Conn) SetState(state proto_base.State) {
c.stateMutex.Lock()
defer c.stateMutex.Unlock()
c.state = state
}
// State returns the current connection protocol state.
func (c *Conn) State() proto_base.State {
c.stateMutex.RLock()
defer c.stateMutex.RUnlock()
return c.state
}
// SetAsyncPackets enables or disables asynchronous packet handling in the receive routine.
func (c *Conn) SetAsyncPackets(asyncPackets bool) {
c.asyncPacketsMutex.Lock()
defer c.asyncPacketsMutex.Unlock()
c.asyncPackets = asyncPackets
}
// GetAsyncPackets returns whether asynchronous packet handling is enabled.
func (c *Conn) GetAsyncPackets() bool {
c.asyncPacketsMutex.RLock()
defer c.asyncPacketsMutex.RUnlock()
return c.asyncPackets
}
// SetVersion sets the connection's Minecraft version by version name and looks up the corresponding protocol version.
func (c *Conn) SetVersion(version string) (err error) {
versionData, err := data.LookUpVersionByName(version)
if err != nil {
@@ -124,6 +131,7 @@ func (c *Conn) SetVersion(version string) (err error) {
return
}
// SetProtocolVersion sets the connection's version by protocol version number and looks up the corresponding version name.
func (c *Conn) SetProtocolVersion(version int32) (err error) {
versionData, err := data.LookUpVersionByProtocolVersion(version)
if err != nil {
@@ -202,6 +210,7 @@ func SimplePacketToBytes(packet proto_base.EncodeDecodeAble) (b []byte, err erro
return
}
// SimplePacketToBytesLenPrefix is like SimplePacketToBytes but also prepends the length-prefix framing.
func SimplePacketToBytesLenPrefix(packet proto_base.EncodeDecodeAble) (b []byte, err error) {
b, err = SimplePacketToBytes(packet)
if err != nil {
@@ -282,6 +291,7 @@ func (c *Conn) sendRegisteredPacket(packet proto_base.EncodeDecodeAble) (err err
return c.SendRaw(packetBuff.Bytes())
}
// Send encodes and sends a packet to the remote peer, translating protocol versions if needed.
func (c *Conn) Send(packet proto_base.EncodeDecodeAble) (err error) {
switch packet := packet.(type) {
case *UnCodablePacket:
@@ -292,6 +302,7 @@ func (c *Conn) Send(packet proto_base.EncodeDecodeAble) (err error) {
return
}
// Receive reads and decodes a raw packet from the remote peer.
func (c *Conn) Receive() (packet proto_base.EncodeDecodeAble, err error) {
if c.R == nil {
return
@@ -335,10 +346,12 @@ func (c *Conn) Receive() (packet proto_base.EncodeDecodeAble, err error) {
}
return
}
// NewConn creates a new Conn with default settings and a background context.
func NewConn() (ret *Conn) {
return NewConnCtx(context.Background())
}
// NewConnCtx creates a new Conn with the given context, setting the handshaking state and latest version.
func NewConnCtx(ctx context.Context) (ret *Conn) {
ret = &Conn{}
ret.SetState(proto_base.Handshaking)
mc/proto/packet_lookup.go
+6
View File
@@ -22,6 +22,7 @@ func init() {
}
}
// LookUpTypeByPacketInfo looks up a packet's type information by direction, state, packet id, and protocol version.
func LookUpTypeByPacketInfo(direction proto_base.Direction, state proto_base.State, pid, version int32) (p proto_base.PacketInfo, ok bool) {
pP, ok := pidMap[PidEtc{direction, state, pid, version}]
if !ok {
@@ -39,6 +40,7 @@ func LookUpTypeByPacketInfo(direction proto_base.Direction, state proto_base.Sta
return
}
// LookUpTypeByPacketInfoAndCopyType looks up a packet and returns a newly allocated instance of its type.
func LookUpTypeByPacketInfoAndCopyType(direction proto_base.Direction, state proto_base.State, pid, version int32) (p proto_base.EncodeDecodeAble, ok bool) {
i, ok := LookUpTypeByPacketInfo(direction, state, pid, version)
if !ok {
@@ -48,6 +50,7 @@ func LookUpTypeByPacketInfoAndCopyType(direction proto_base.Direction, state pro
return
}
// LookupPacketInfoByType looks up a packet's type information by matching against the type of the given packet value.
func LookupPacketInfoByType(packet proto_base.EncodeDecodeAble) (p proto_base.PacketInfo, ok bool) {
undecodedPacket, isUndecoable := packet.(*UnCodablePacket)
if isUndecoable {
@@ -64,6 +67,7 @@ func LookupPacketInfoByType(packet proto_base.EncodeDecodeAble) (p proto_base.Pa
return
}
// LookupPacketInfoByTypeAndState looks up a packet's type information by type and state.
func LookupPacketInfoByTypeAndState(packet proto_base.EncodeDecodeAble, state proto_base.State) (p proto_base.PacketInfo, ok bool) {
for _, p := range proto_generated.Packets {
if state == p.State && reflect.TypeOf(p.Type) == reflect.TypeOf(packet) {
@@ -73,6 +77,7 @@ func LookupPacketInfoByTypeAndState(packet proto_base.EncodeDecodeAble, state pr
return
}
// LookupPacketInfoByNameProtocolVersionAndState looks up a packet's type information by name, protocol version, and state.
func LookupPacketInfoByNameProtocolVersionAndState(name string, version int32, state proto_base.State) (p proto_base.PacketInfo, ok bool) {
for _, p := range proto_generated.Packets {
if state == p.State && p.Name == name && p.ProtocolVersion == version {
@@ -82,6 +87,7 @@ func LookupPacketInfoByNameProtocolVersionAndState(name string, version int32, s
return
}
// LookupPacketInfoByNameProtocolVersionStateAndDirection looks up a packet's type information by name, protocol version, state, and direction.
func LookupPacketInfoByNameProtocolVersionStateAndDirection(name string, version int32, state proto_base.State, direction proto_base.Direction) (p proto_base.PacketInfo, ok bool) {
for _, p := range proto_generated.Packets {
if state == p.State && p.Name == name && p.ProtocolVersion == version && p.Direction == direction {
mc/proto/raw_conn.go
+5
View File
@@ -27,18 +27,21 @@ type RawConn struct {
MaxPacketSize int32
}
// SetCompressionThreshold sets the packet compression threshold. Values below 0 disable compression.
func (c *RawConn) SetCompressionThreshold(threshold int32) {
c.CompressionThresholdMut.Lock()
defer c.CompressionThresholdMut.Unlock()
c.compressionThreshold = threshold
}
// GetCompressionThreshold returns the current compression threshold.
func (c *RawConn) GetCompressionThreshold() int32 {
c.CompressionThresholdMut.RLock()
defer c.CompressionThresholdMut.RUnlock()
return c.compressionThreshold
}
// SendRaw sends raw packet bytes over the connection, applying compression if the threshold is met.
func (c *RawConn) SendRaw(rawPacketBytes []byte) (err error) {
if c.MaxPacketSize > 0 && int32(len(rawPacketBytes)) > c.MaxPacketSize {
err = errors.New("packet too large")
@@ -90,6 +93,7 @@ func (c *RawConn) SendRaw(rawPacketBytes []byte) (err error) {
return
}
// ReceiveRaw reads and decompresses (if needed) a raw packet from the connection.
func (c *RawConn) ReceiveRaw() (packetBytes []byte, err error) {
rawPacketLen, err := proto_base.DecodeVarInt(c.R)
if err != nil {
@@ -142,6 +146,7 @@ func (c *RawConn) ReceiveRaw() (packetBytes []byte, err error) {
return
}
// SetSecret enables AES/CFB8 encryption on the connection using the shared secret.
func (c *RawConn) SetSecret(sharedSecret []byte) (err error) {
var b cipher.Block
b, err = aes.NewCipher(sharedSecret)
mc/proto/replay/reader.go
+1
View File
@@ -16,6 +16,7 @@ type Reader struct {
Version int32
}
// NewReader creates a new replay Reader from an io.Reader.
func NewReader(r io.Reader) *Reader {
return &Reader{r: r}
}
mc/proto/replay/writer.go
+1
View File
@@ -13,6 +13,7 @@ type Writer struct {
w io.Writer
}
// NewWriter creates a new replay Writer from an io.Writer.
func NewWriter(w io.Writer) *Writer {
return &Writer{w: w}
}
mc/proto/smart_convert.go
+2
View File
@@ -11,6 +11,7 @@ import (
"github.com/admin-else/strom/mc/proto_generated"
)
// SmartConvertibleTo reports whether a value of type from can be recursively converted to type to.
func SmartConvertibleTo(from, to reflect.Type) bool {
switch from.Kind() {
case reflect.Struct:
@@ -36,6 +37,7 @@ func SmartConvertibleTo(from, to reflect.Type) bool {
}
}
// SmartConvert recursively converts a reflect.Value from one type to another compatible type.
func SmartConvert(from reflect.Value, to reflect.Type) (ret reflect.Value) {
switch from.Kind() {
case reflect.Struct: