decoder

Documentation

Overview

Package decoder decodes values in the data section.

Package decoder decodes values in the data section.

Package decoder decodes values in the data section.

Index

• type DataDecoder
  • func NewDataDecoder(buffer []byte) DataDecoder
• type Decoder
  • func NewDecoder(d DataDecoder, offset uint, options ...DecoderOption) *Decoder
  • func (d *Decoder) Offset() uint
  • func (d *Decoder) PeekKind() (Kind, error)
  • func (d *Decoder) ReadBool() (bool, error)
  • func (d *Decoder) ReadBytes() ([]byte, error)
  • func (d *Decoder) ReadFloat32() (float32, error)
  • func (d *Decoder) ReadFloat64() (float64, error)
  • func (d *Decoder) ReadInt32() (int32, error)
  • func (d *Decoder) ReadMap() (iter.Seq2[[]byte, error], uint, error)
  • func (d *Decoder) ReadSlice() (iter.Seq[error], uint, error)
  • func (d *Decoder) ReadString() (string, error)
  • func (d *Decoder) ReadUint128() (hi, lo uint64, err error)
  • func (d *Decoder) ReadUint16() (uint16, error)
  • func (d *Decoder) ReadUint32() (uint32, error)
  • func (d *Decoder) ReadUint64() (uint64, error)
  • func (d *Decoder) SkipValue() error
• type DecoderOption
• type Kind
  • func (k Kind) IsContainer() bool
  • func (k Kind) IsScalar() bool
  • func (k Kind) String() string
• type ReflectionDecoder
  • func New(buffer []byte) ReflectionDecoder
  • func (d *ReflectionDecoder) Decode(offset uint, v any) error
  • func (d *ReflectionDecoder) DecodePath(offset uint, path []any, v any) error
  • func (d *ReflectionDecoder) VerifyDataSection(offsets map[uint]bool) error
• type Unmarshaler

Examples

• Decoder.PeekKind
• Kind.IsContainer
• Kind.IsScalar
• Kind.String

Types

type DataDecoder

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

DataDecoder is a decoder for the MMDB data section. This is exported so mmdbdata package can use it, but still internal.

func NewDataDecoder

func NewDataDecoder(buffer []byte) DataDecoder

NewDataDecoder creates a DataDecoder.

type Decoder

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

Decoder allows decoding of a single value stored at a specific offset in the database.

func NewDecoder

func NewDecoder(d DataDecoder, offset uint, options ...DecoderOption) *Decoder

NewDecoder creates a new Decoder with the given DataDecoder, offset, and options.

func (*Decoder) Offset

func (d *Decoder) Offset() uint

Offset returns the current offset position in the database. This can be used by custom unmarshalers for caching purposes.

func (*Decoder) PeekKind

func (d *Decoder) PeekKind() (Kind, error)

PeekKind returns the kind of the current value without consuming it. This allows for look-ahead parsing similar to jsontext.Decoder.PeekKind().

Example

ExampleDecoder_PeekKind demonstrates how to use PeekKind for look-ahead parsing without consuming values.

// Create test data with different types
testCases := [][]byte{
	{0x44, 't', 'e', 's', 't'}, // String
	{0xE0},                     // Empty map
	{0x00, 0x04},               // Empty slice (extended type)
	{0x01, 0x07},               // Bool true (extended type)
}

typeNames := []string{"String", "Map", "Slice", "Bool"}

for i, buffer := range testCases {
	decoder := NewDecoder(NewDataDecoder(buffer), 0)

	// Peek at the kind without consuming it
	typ, err := decoder.PeekKind()
	if err != nil {
		panic(err)
	}

	fmt.Printf("Type %d: %s (value: %d)\n", i+1, typeNames[i], typ)

	// PeekKind doesn't consume, so we can peek again
	typ2, err := decoder.PeekKind()
	if err != nil {
		panic(err)
	}

	if typ != typ2 {
		fmt.Println("ERROR: PeekKind consumed the value!")
	}
}

Output:

Type 1: String (value: 2)
Type 2: Map (value: 7)
Type 3: Slice (value: 11)
Type 4: Bool (value: 14)

func (*Decoder) ReadBool

func (d *Decoder) ReadBool() (bool, error)

ReadBool reads the value pointed by the decoder as a bool.

Returns an error if the database is malformed or if the pointed value is not a bool.

func (*Decoder) ReadBytes

func (d *Decoder) ReadBytes() ([]byte, error)

ReadBytes reads the value pointed by the decoder as bytes.

Returns an error if the database is malformed or if the pointed value is not bytes.

func (*Decoder) ReadFloat32

func (d *Decoder) ReadFloat32() (float32, error)

ReadFloat32 reads the value pointed by the decoder as a float32.

Returns an error if the database is malformed or if the pointed value is not a float.

func (*Decoder) ReadFloat64

func (d *Decoder) ReadFloat64() (float64, error)

ReadFloat64 reads the value pointed by the decoder as a float64.

Returns an error if the database is malformed or if the pointed value is not a double.

func (*Decoder) ReadInt32

func (d *Decoder) ReadInt32() (int32, error)

ReadInt32 reads the value pointed by the decoder as a int32.

Returns an error if the database is malformed or if the pointed value is not an int32.

func (*Decoder) ReadMap

func (d *Decoder) ReadMap() (iter.Seq2[[]byte, error], uint, error)

ReadMap returns an iterator to read the map along with the map size. The size can be used to pre-allocate a map with the correct capacity for better performance. The first value from the iterator is the key. Please note that this byte slice is only valid during the iteration. This is done to avoid an unnecessary allocation. You must make a copy of it if you are storing it for later use. The second value is an error indicating that the database is malformed or that the pointed value is not a map.

func (*Decoder) ReadSlice

func (d *Decoder) ReadSlice() (iter.Seq[error], uint, error)

ReadSlice returns an iterator over the values of the slice along with the slice size. The size can be used to pre-allocate a slice with the correct capacity for better performance. The iterator returns an error if the database is malformed or if the pointed value is not a slice.

func (*Decoder) ReadString

func (d *Decoder) ReadString() (string, error)

ReadString reads the value pointed by the decoder as a string.

Returns an error if the database is malformed or if the pointed value is not a string.

func (*Decoder) ReadUint128

func (d *Decoder) ReadUint128() (hi, lo uint64, err error)

ReadUint128 reads the value pointed by the decoder as a uint128.

Returns an error if the database is malformed or if the pointed value is not an uint128.

func (*Decoder) ReadUint16

func (d *Decoder) ReadUint16() (uint16, error)

ReadUint16 reads the value pointed by the decoder as a uint16.

Returns an error if the database is malformed or if the pointed value is not an uint16.

func (*Decoder) ReadUint32

func (d *Decoder) ReadUint32() (uint32, error)

ReadUint32 reads the value pointed by the decoder as a uint32.

Returns an error if the database is malformed or if the pointed value is not an uint32.

func (*Decoder) ReadUint64

func (d *Decoder) ReadUint64() (uint64, error)

ReadUint64 reads the value pointed by the decoder as a uint64.

Returns an error if the database is malformed or if the pointed value is not an uint64.

func (*Decoder) SkipValue

func (d *Decoder) SkipValue() error

SkipValue skips over the current value without decoding it. This is useful in custom decoders when encountering unknown fields. The decoder will be positioned after the skipped value.

type DecoderOption

type DecoderOption func(*decoderOptions)

DecoderOption configures a Decoder.

type Kind

type Kind int

Kind constants for the different MMDB data kinds.

const (
	// KindExtended indicates an extended kind.
	KindExtended Kind = iota
	// KindPointer is a pointer to another location in the data section.
	KindPointer
	// KindString is a UTF-8 string.
	KindString
	// KindFloat64 is a 64-bit floating point number.
	KindFloat64
	// KindBytes is a byte slice.
	KindBytes
	// KindUint16 is a 16-bit unsigned integer.
	KindUint16
	// KindUint32 is a 32-bit unsigned integer.
	KindUint32
	// KindMap is a map from strings to other data types.
	KindMap
	// KindInt32 is a 32-bit signed integer.
	KindInt32
	// KindUint64 is a 64-bit unsigned integer.
	KindUint64
	// KindUint128 is a 128-bit unsigned integer.
	KindUint128
	// KindSlice is an array of values.
	KindSlice
	// KindContainer is a data cache container.
	KindContainer
	// KindEndMarker marks the end of the data section.
	KindEndMarker
	// KindBool is a boolean value.
	KindBool
	// KindFloat32 is a 32-bit floating point number.
	KindFloat32
)

MMDB data kind constants.

func (Kind) IsContainer

func (k Kind) IsContainer() bool

IsContainer returns true if the Kind represents a container type (Map or Slice).

Example

ExampleKind_IsContainer demonstrates container type detection.

kinds := []Kind{KindString, KindMap, KindSlice, KindUint32}

for _, k := range kinds {
	if k.IsContainer() {
		fmt.Printf("%s is a container type\n", k.String())
	} else {
		fmt.Printf("%s is not a container type\n", k.String())
	}
}

Output:

String is not a container type
Map is a container type
Slice is a container type
Uint32 is not a container type

func (Kind) IsScalar

func (k Kind) IsScalar() bool

IsScalar returns true if the Kind represents a scalar value type.

Example

ExampleKind_IsScalar demonstrates scalar type detection.

kinds := []Kind{KindString, KindMap, KindUint32, KindPointer}

for _, k := range kinds {
	if k.IsScalar() {
		fmt.Printf("%s is a scalar value\n", k.String())
	} else {
		fmt.Printf("%s is not a scalar value\n", k.String())
	}
}

Output:

String is a scalar value
Map is not a scalar value
Uint32 is a scalar value
Pointer is not a scalar value

func (Kind) String

func (k Kind) String() string

String returns a human-readable name for the Kind.

Example

ExampleKind_String demonstrates human-readable Kind names.

kinds := []Kind{KindString, KindMap, KindSlice, KindUint32, KindBool}

for _, k := range kinds {
	fmt.Printf("%s\n", k.String())
}

Output:

String
Map
Slice
Uint32
Bool

type ReflectionDecoder

type ReflectionDecoder struct {
	DataDecoder
}

ReflectionDecoder is a decoder for the MMDB data section.

func New

func New(buffer []byte) ReflectionDecoder

New creates a ReflectionDecoder.

func (*ReflectionDecoder) Decode

func (d *ReflectionDecoder) Decode(offset uint, v any) error

Decode decodes the data value at offset and stores it in the value pointed at by v.

func (*ReflectionDecoder) DecodePath

func (d *ReflectionDecoder) DecodePath(
	offset uint,
	path []any,
	v any,
) error

DecodePath decodes the data value at offset and stores the value associated with the path in the value pointed at by v.

func (*ReflectionDecoder) VerifyDataSection

func (d *ReflectionDecoder) VerifyDataSection(offsets map[uint]bool) error

VerifyDataSection verifies the data section against the provided offsets from the tree.

type Unmarshaler

type Unmarshaler interface {
	UnmarshalMaxMindDB(d *Decoder) error
}

Unmarshaler is implemented by types that can unmarshal MaxMind DB data. This is used internally for reflection-based decoding.