MMDB2 Decoder

v1.1.0

MMDB2 Decoder v1.1.0 MMDB2Decoder View Source

MMDB2 file format decoder.

Usage

To prepare lookups in a given database you need to parse it and hold the result available for later usage:

iex(1)> database = File.read!("/path/to/database.mmdb")
iex(2)> {:ok, meta, tree, data} = MMDB2Decoder.parse_database(database)

Using the returned database contents you can start looking up individual entries:

iex(3)> {:ok, ip} = :inet.parse(String.to_charlist("127.0.0.1"))
iex(4)> MMDB2Decoder.lookup(ip, meta, tree, data)
{:ok, %{...}}

For more details on the lookup methods (and a function suitable for direct piping) please see the individual function documentations.

Floating Point Precision

Please be aware that all values of the type float are rounded to 4 decimal digits and double values to 8 decimal digits.

This might be changed in the future if there are datasets known to return values with a higher precision.

Link to this section Summary

Types

decode_option()
decode_options()
decoded_value()
lookup_result()
lookup_value()
parse_result()

Functions

lookup(ip, meta, tree, data, options \\ [])

Looks up the data associated with an IP tuple.

lookup!(ip, meta, tree, data, options \\ [])

Calls lookup/4 and raises if an error occurs.

parse_database(contents)

Parses a database binary and splits it into metadata, lookup tree and data.

pipe_lookup(parse_result, ip, options \\ [])

Utility method to pipe parse_database/1 directly to lookup/4.

pipe_lookup!(parse_result, ip, options \\ [])

Calls pipe_lookup/2 and raises if an error from parse_database/1 is given or occurs during lookup/4.

Link to this section Types

Link to this type

decode_option() View Source 
decode_option() ::
  {:double_precision, Float.precision_range()}
  | {:float_precision, Float.precision_range()}
  | {:map_keys, :atoms | :atoms! | :strings}

Link to this type

decode_options() View Source 
decode_options() :: [decode_option()]

Link to this type

decoded_value() View Source 
decoded_value() ::
  :cache | :end | binary() | boolean() | list() | map() | number()

Link to this type

lookup_result() View Source 
lookup_result() :: {:ok, lookup_value()} | {:error, term()}

Link to this type

lookup_value() View Source 
lookup_value() :: decoded_value() | nil

Link to this type

parse_result() View Source 
parse_result() ::
  {:ok, MMDB2Decoder.Metadata.t(), binary(), binary()} | {:error, term()}

Link to this section Functions

Link to this function

lookup(ip, meta, tree, data, options \\ []) View Source 
lookup(
  :inet.ip_address(),
  MMDB2Decoder.Metadata.t(),
  binary(),
  binary(),
  decode_options()
) :: lookup_result()

Looks up the data associated with an IP tuple.

This is probably the main function you will use. The ip address is expected to be a 4- or 8-element tuple describing an IPv4 or IPv6 address. To obtain this tuple from a string you can use :inet.ip_address/1.

Usage 

iex> MMDB2Decoder.lookup({127, 0, 0, 1}, meta, tree, data)
{
  :ok,
  %{
    continent: %{...},
    country: %{...},
    registered_country: %{...}
  }
}

The values for meta, tree and data can be obtained by parsing the file contents of a database using parse_database/1.

Link to this function

lookup!(ip, meta, tree, data, options \\ []) View Source 
lookup!(
  :inet.ip_address(),
  MMDB2Decoder.Metadata.t(),
  binary(),
  binary(),
  decode_options()
) :: lookup_value() | no_return()

Calls lookup/4 and raises if an error occurs.

Link to this function

parse_database(contents) View Source 
parse_database(binary()) :: parse_result()

Parses a database binary and splits it into metadata, lookup tree and data.

It is expected that you pass the real contents of the file, not the name of the database or the path to it.

Usage 

iex> MMDB2Decoder.parse_database(File.read!("/path/to/database.mmdb"))
{
  :ok,
  %MMDB2Decoder.Metadata{...},
  <<...>>,
  <<...>>
}

If parsing the database fails you will receive an appropriate error tuple:

iex> MMDB2Decoder.parse_database("invalid-database-contents")
{:error, :no_metadata}
Link to this function

pipe_lookup(parse_result, ip, options \\ []) View Source 
pipe_lookup(parse_result(), :inet.ip_address(), decode_options()) ::
  lookup_result()

Utility method to pipe parse_database/1 directly to lookup/4.

Usage

Depending on how you handle the parsed database contents you may want to pass the results directly to the lookup.

iex> "/path/to/database.mmdb"
...> |> File.read!()
...> |> MMDB2Decoder.parse_database()
...> |> MMDB2Decoder.pipe_lookup({127, 0, 0, 1})
{:ok, %{...}}
Link to this function

pipe_lookup!(parse_result, ip, options \\ []) View Source 
pipe_lookup!(parse_result(), :inet.ip_address(), decode_options()) ::
  lookup_value() | no_return()

Calls pipe_lookup/2 and raises if an error from parse_database/1 is given or occurs during lookup/4.