mmdbwriter

README

Go MaxMind DB Writer

This is a Go writer for the MaxMind DB format.

This is still a work in progress and does not support all of the features of the Perl writer. The API is subject to change.

Examples

See the examples folder for examples of how to use this library or our blog post, Enriching MMDB files with your own data using Go.

Copyright and License

This software is Copyright (c) 2020 by MaxMind, Inc.

This is free software, licensed under the Apache License, Version 2.0 or the MIT License, at your option.

Documentation

Overview

Package mmdbwriter provides the tools to create and write MaxMind DB files.

Index

• type Options
• type Tree
  • func Load(path string, opts Options) (*Tree, error)
  • func New(opts Options) (*Tree, error)
  • func (t *Tree) Get(ip net.IP) (*net.IPNet, mmdbtype.DataType)
  • func (t *Tree) Insert(network *net.IPNet, value mmdbtype.DataType) error
  • func (t *Tree) InsertFunc(network *net.IPNet, inserterFunc inserter.Func) error
  • func (t *Tree) InsertRange(start net.IP, end net.IP, value mmdbtype.DataType) error
  • func (t *Tree) InsertRangeFunc(start net.IP, end net.IP, inserterFunc inserter.Func) error
  • func (t *Tree) WriteTo(w io.Writer) (int64, error)

Types

type Options

type Options struct {
	// BuildEpoch is the database build timestamp as a Unix epoch value. It
	// defaults to the epoch of when New was called.
	BuildEpoch int64

	// DatabaseType is a string that indicates the structure of each data record
	// associated with an IP address. The actual definition of these structures
	// is left up to the database creator.
	DatabaseType string

	// Description is a map where the key is a language code and the value is
	// the description of the database in that language.
	Description map[string]string

	// DisableIPv4Aliasing will disable the IPv4 aliasing in IPv6 trees. This
	// aliasing maps some IPv6 networks to the IPv4 network, e.g.,
	// ::ffff:0:0/96.
	DisableIPv4Aliasing bool

	// IncludeReservedNetworks will allow reserved networks to be added to the
	// database.
	//
	// If this is false, any attempt to insert into these networks will result
	// in an error and inserting a network that contains a reserved network will
	// result in the reserved portion of the network being excluded. Reserved
	// networks that are globally routable to an individual device, such as
	// Teredo, may still be added.
	IncludeReservedNetworks bool

	// IPVersion indicates whether an IPv4 or IPv6 database should be built. An
	// IPv6 database supports both IPv4 and IPv6 lookups. The default value is
	// "6" for IPv6.
	IPVersion int

	// Languages is a slice of strings, each of which is a locale code. A given
	// record may contain data items that have been localized to some or all of
	// these locales. Records should not contain localized data for locales not
	// included in this slice.
	Languages []string

	// RecordSize indicates the number of bits in a record in the search tree.
	// The supported values are 24, 28, and 32. A smaller size will result in a
	// smaller database, but it will limit the maximum size of the database.
	// The default is 28.
	RecordSize int

	// DisableMetadataPointers prevents the use of pointers in the metadata
	// section of the database. This option exists to avoid bugs in reader
	// implementations that do not correctly handle metadata pointers. Its
	// use should primarily be limited to existing database types.
	DisableMetadataPointers bool

	// Inserter is the insert function used when calling `Insert`. It defaults
	// to `inserter.ReplaceWith`, which replaces any conflicting old value
	// entirely with the new.
	Inserter inserter.FuncGenerator
}

Options holds configuration parameters for the writer.

type Tree

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

Tree represents an MaxMind DB search tree.

func Load

func Load(path string, opts Options) (*Tree, error)

Load an existing database into the writer.

func New

func New(opts Options) (*Tree, error)

New creates a new Tree.

func (*Tree) Get

func (t *Tree) Get(ip net.IP) (*net.IPNet, mmdbtype.DataType)

Get the value for the given IP address from the tree. If the nil interface is returned, that means the tree does not have a value for the IP.

func (*Tree) Insert

func (t *Tree) Insert(network *net.IPNet, value mmdbtype.DataType) error

Insert a data value into the tree using the Tree's inserter function (defaults to inserter.ReplaceWith).

This is not safe to call from multiple threads.

func (*Tree) InsertFunc

func (t *Tree) InsertFunc(
	network *net.IPNet,
	inserterFunc inserter.Func,
) error

InsertFunc will insert the output of the function passed to it. The argument passed to the function is the existing value in the record. The inserter function should return the mmdbtype.DataType to be inserted. In both cases, a nil value means an empty record.

You must never modify the argument passed to the function as the value may be shared with other records. If you want a copy of the mmdbtype.DataType to modify, call the Copy method on it, which will make a deep copy. This isn't done automatically before calling the function as not all functions will require the record to be copied and there is a non-trivial performance impact.

The function will be called multiple times per insert when the network has multiple preexisting records associated with it.

This is not safe to call from multiple threads.

func (*Tree) InsertRange

func (t *Tree) InsertRange(
	start net.IP,
	end net.IP,
	value mmdbtype.DataType,
) error

InsertRange is the same as Insert, except it will insert all subnets within the range of IPs specified by `[start,end]`.

func (*Tree) InsertRangeFunc

func (t *Tree) InsertRangeFunc(
	start net.IP,
	end net.IP,
	inserterFunc inserter.Func,
) error

InsertRangeFunc is the same as InsertFunc, except it will insert all subnets within the range of IPs specified by `[start,end]`.

func (*Tree) WriteTo

func (t *Tree) WriteTo(w io.Writer) (int64, error)

WriteTo writes the tree to the provided Writer.