mmdbwriter

The storeDecoder uses an internal cache and a result buffer to manage valueRef ownership during the decoding process. To prevent memory leaks in the underlying valueStore, follow these rules:

• UnmarshalMaxMindDBCursor(cursor): Decodes the value at the current cursor. If a result was already stored from a previous call that wasn't taken, it is automatically released.
• takeResult(): Transfers ownership of the most recently decoded top-level valueRef to the caller. Once called, the decoder's internal result is set to nilValueRef.
• close(): This is critical. It releases the current result and all references stored in the internal cache (used for deduplication/interning during the decode process). Always call this when the decoder is no longer needed.

You can trigger an ownership and reference-count audit of the tree structure to ensure internal invariants are maintained. Auditing is an expensive operation and is intended for testing or verifying tree integrity after complex operations.

Auditing can be enabled in two ways:

1. Via Options: Configure the Tree with Options.RefcountAudit during initialization.
2. Via Environment Variable: Set the MMDBWRITER_REFCOUNT_AUDIT environment variable.

If auditing is enabled, the Tree will automatically run maybeAuditValueStore() after insert operations reach the store or after a successful load, provided all temporary references have been released. A failure during this process returns a *RefcountAuditError.

The InsertRange family of functions allows you to insert data into all subnets within a continuous range of IP addresses defined by a start and end address.

• InsertRange(start, end netip.Addr, value mmdbtype.DataType): Replaces values in the range.
• InsertRangeFunc(...): Uses a callback for custom logic.
• InsertRangePureFunc(...): Uses a pure callback for custom logic.

Subnets are inserted sequentially. For InsertFunc and InsertRangeFunc, the InsertedNetwork field in the metadata will reflect the specific individual subnet being processed, not the entire range.

start := netip.MustParseAddr("192.0.2.1")
end := netip.MustParseAddr("192.0.2.255")
err := tree.InsertRange(start, end, myData)

The WriteTo(w io.Writer) method serializes the tree into the MaxMind DB binary format and writes it to the provided io.Writer.

Process:

1. It automatically calls finalize() if the tree has not been finalized yet.
2. It writes the node section.
3. It writes the data section.
4. It writes the metadata section.

Returns the total number of bytes written and any error encountered.

f, _ := os.Create("output.mmdb")
defer f.Close()

bytesWritten, err := tree.WriteTo(f)
if err != nil {
	// handle error
}

Use Get(ip netip.Addr) to look up the value associated with an IP address.

• Return Values: Returns the netip.Prefix that matched the IP and the mmdbtype.DataType associated with it. If no match is found, it returns an empty prefix and a nil value.
• Concurrency Warning: Get is not safe to call concurrently with any other Tree method (including other Get calls) because lookups materialize shared views lazily. The caller must provide synchronization.
• Data Immutability: The returned values are shared, read-only views. If you need to modify the returned value, you must call Copy on it first.

prefix, value := tree.Get(netip.MustParseAddr("192.0.2.1"))
if value != nil {
	// use value
}

The Load(path string, opts Options) function allows you to import an existing MaxMind DB file into a Tree.

Behavioral Notes:

• It interns records directly into the value store to avoid intermediate memory overhead.
• If opts are partially provided, they are merged with the metadata found in the existing database file (e.g., DatabaseType, Description, Languages, RecordSize, IPVersion).
• If a non-nil Options.Inserter is provided, it receives a materialized view of each decoded record. The inserter must treat these values as immutable and copy them before modification.

tree, err := mmdbwriter.Load("/path/to/database.mmdb", opts)
if err != nil {
	// handle error
}

When performing a reference-count audit on a Tree, the library may return a *RefcountAuditError. This error indicates that the tree's internal invariants have been violated, signaling either a bug within the mmdbwriter library itself or memory corruption.

Because this error represents a fundamental violation of the database structure rather than invalid user input, retrying the failed operation will not resolve the issue. You should treat this as a critical failure of the tree's integrity.

var err error
// ... perform tree operations ...
if err != nil {
	if _, ok := err.(*RefcountAuditError); ok {
		// Handle internal library bug or memory corruption
	}
}

Use New(opts Options) to initialize a new MaxMind DB search tree. The function validates the provided options, such as ensuring RecordSize is one of the supported values (24, 28, 32) and that BuildEpoch is non-negative. If IPVersion is 6 and DisableIPv4Aliasing is not set, it automatically handles IPv4 aliases.

tree, err := mmdbwriter.New(opts)
if err != nil {
	// handle error
}

The dataWriter type implements the mmdbtype.Writer interface, allowing it to be used by mmdbtype.Pointer and mmdbtype.String objects via their WriteTo methods.

When using these methods, the dataWriter writes the full value and does not record an offset. This is a safety measure to prevent an offset for a reference that the caller later releases from being recycled and pointing at unrelated data.

To satisfy the interface, use:

• WriteOrWritePointer(value mmdbtype.DataType) (int64, error)
• WriteOrWritePointerString(value mmdbtype.String) (int64, error)

// Example of how mmdbtype.Pointer uses the writer interface
// (Conceptual usage based on the implementation)
size, err := dw.WriteOrWritePointer(someDataType)