locus

%% Copyright (c) 2017-2022 Guilherme Andrade
%%
%% Permission is hereby granted, free of charge, to any person obtaining a
%% copy  of this software and associated documentation files (the "Software"),
%% to deal in the Software without restriction, including without limitation
%% the rights to use, copy, modify, merge, publish, distribute, sublicense,
%% and/or sell copies of the Software, and to permit persons to whom the
%% Software is furnished to do so, subject to the following conditions:
%%
%% The above copyright notice and this permission notice shall be included in
%% all copies or substantial portions of the Software.
%%
%% THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
%% IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
%% FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
%% AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
%% LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
%% FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
%% DEALINGS IN THE SOFTWARE.
%%
%% locus is an independent project and has not been authorized, sponsored,
%% or otherwise approved by MaxMind.

%% @reference <a target="_parent" href="https://maxmind.github.io/MaxMind-DB/">
%% MaxMind DB File Format Specification</a>

%% @doc API for working with MMDB
-module(locus_mmdb).

-ifdef(TEST).
-include_lib("eunit/include/eunit.hrl").
-endif.

%% ------------------------------------------------------------------
%% API Function Exports
%% ------------------------------------------------------------------

-export([unpack_database/1,
         unpack_tree_data_and_data_section/2,
         lookup_address/2]).

-ignore_xref(
        [unpack_tree_data_and_data_section/2]).

%% ------------------------------------------------------------------
%% Debug API Function Exports
%% ------------------------------------------------------------------

-export([parse_all_data_section_values/1,
         parse_data_section_value/2]).

-ignore_xref(
        [parse_all_data_section_values/1,
         parse_data_section_value/2]).

%% ------------------------------------------------------------------
%% API Type Definitions
%% ------------------------------------------------------------------

-type database()
    :: #{ metadata := locus_mmdb_metadata:t(),
          tree := locus_mmdb_tree:t(),
          data_section := binary()
        }.
-export_type([database/0]).

-type unpack_error()
    :: {bad_metadata, locus_mmdb_metadata:parse_or_validation_error()}

    | failed_to_unpack_tree_data_and_data_section()

    | {bad_tree,
       {{because, locus_mmdb_tree:bad_tree_error()},
        {with_metadata, locus_mmdb_metadata:t()}}}.

-export_type([unpack_error/0]).

-type failed_to_unpack_tree_data_and_data_section()
    :: {intermediate_128bits_of_zero_not_found_after_tree,
        {{not_zeroes, binary()},
         {at_offset, non_neg_integer()},
         {with_metadata, locus_mmdb_metadata:t()}}}

    |  {missing_data_after_tree,
        {{required, {128, bits}},
         {but_got, {0..127, bits}},
         {at_offset, non_neg_integer()},
         {with_metadata, locus_mmdb_metadata:t()}}}

    | {not_enough_data_for_tree,
       {{required, {pos_integer(), bytes}},
        {but_got, {non_neg_integer(), bytes}},
        {with_metadata, locus_mmdb_metadata:t()}}}.

-export_type([failed_to_unpack_tree_data_and_data_section/0]).

%% ------------------------------------------------------------------
%% API Function Definitions
%% ------------------------------------------------------------------

%% @doc Unpacks an `EncodedDatabase' binary into a ready-to-use `Database'.
-spec unpack_database(EncodedDatabase) -> {ok, Database} | {error, ErrorReason}
        when EncodedDatabase :: binary(),
             Database :: database(),
             ErrorReason :: unpack_error().
unpack_database(<<EncodedDatabase/bytes>>) ->
    try
        unpack_database_(EncodedDatabase)
    catch
        Class:Reason:Stacktrace ->
            SaferReason = locus_util:purge_term_of_very_large_binaries(Reason),
            SaferStacktrace = locus_util:purge_term_of_very_large_binaries(Stacktrace),
            erlang:raise(Class, SaferReason, SaferStacktrace)
    end.

%% @doc Unpacks a single `TreeAndDataSection' binary into
%% separate `TreeData' and `DataSection' binaries, leveraging
%% `Metadata' to calculate the size of `TreeData'.
%%
%% You can then use `TreeData' on your own or leverage it
%% to instantiate a new `locus_mmdb_tree:t()',
%% through {@link locus_mmdb_tree:new/5}.
%%
%% As for `DataSection', you can also either use it on your own
%% or pass it to the API defined under {@link locus_mmdb_data_codec}.
%%
%% For how to obtain `Metadata' and `TreeAndDataSection'
%% in the first place, see {@link locus_mmdb_metadata:parse_and_validate/1}.
%%
-spec unpack_tree_data_and_data_section(Metadata, TreeAndDataSection)
        -> {ok, TreeData, DataSection} | {error, Reason}
        when Metadata :: locus_mmdb_metadata:t(),
             TreeAndDataSection :: binary(),
             TreeData :: binary(),
             DataSection :: binary(),
             Reason ::  failed_to_unpack_tree_data_and_data_section().
unpack_tree_data_and_data_section(Metadata, TreeAndDataSection) ->
    #{node_count := NodeCount, record_size := RecordSize} = Metadata,
    TreeSize = ((RecordSize * 2) div 8) * NodeCount,

    case TreeAndDataSection of
        <<TreeData:TreeSize/bytes, 0:128, DataSection/bytes>> ->
            {ok, TreeData, DataSection};
        <<_:TreeSize/bytes, NotZeroes:128/bits, _NotZeroes/bytes>> ->
            {error, {intermediate_128bits_of_zero_not_found_after_tree,
                     {{not_zeroes, NotZeroes},
                      {at_offset, TreeSize},
                      {with_metadata, Metadata}}}};
        <<_:TreeSize/bytes, MissingData/bits>> ->
            {error, {missing_data_after_tree,
                     {{required, {128, bits}},
                      {but_got, {bit_size(MissingData), bits}},
                      {at_offset, TreeSize},
                      {with_metadata, Metadata}}}};
        <<MissingTree/bytes>> ->
            {error, {not_enough_data_for_tree,
                     {{required, {TreeSize, bytes}},
                      {but_got, {byte_size(MissingTree), bytes}},
                      {with_metadata, Metadata}}}}
    end.

%% @doc Looks up for an entry matching `Address' within `Database'
-spec lookup_address(Address, Database) -> {ok, Entry} | not_found | {error, ErrorReason}
    when Address :: inet:ip_address() | string() | unicode:unicode_binary(),
         Database :: database(),
         Entry :: locus_mmdb_data:value(),
         ErrorReason :: (database_unknown | database_not_loaded |
                         {invalid_address, Address} |
                         ipv4_database).
lookup_address(Address, Database) ->
    case locus_util:parse_ip_address(Address) of
        {ok, ParsedAddress} ->
            lookup_parsed_address(ParsedAddress, Database);
        {error, einval} ->
            {error, {invalid_address, Address}}
    end.

%% ------------------------------------------------------------------
%% Debug API Function Definitions
%% ------------------------------------------------------------------

-spec parse_all_data_section_values(file:name_all())
        -> [locus_mmdb_data_raw:value()].
%% @private
parse_all_data_section_values(Filename) ->
    {ok, EncodedDatabase} = file:read_file(Filename),
    {ok, Database} = unpack_database_(EncodedDatabase),
    #{data_section := DataSection} = Database,
    locus_mmdb_data_codec:parse_all(DataSection, _Raw = true).

-spec parse_data_section_value(file:name_all(), locus_mmdb_data_codec:index())
        -> locus_mmdb_data_raw:value().
%% @private
parse_data_section_value(Filename, Index) ->
    {ok, EncodedDatabase} = file:read_file(Filename),
    {ok, Database} = unpack_database_(EncodedDatabase),
    #{data_section := DataSection} = Database,
    {Entry, _RemainingData} = locus_mmdb_data_codec:parse_on_index(Index, DataSection,
                                                                   _Raw = true),
    Entry.

%% ------------------------------------------------------------------
%% Internal Function Definitions
%% ------------------------------------------------------------------

unpack_database_(EncodedDatabase) ->
    case locus_mmdb_metadata:parse_and_validate(EncodedDatabase) of
        {ok, Metadata, OtherSections} ->
            TreeAndDataSection = OtherSections,
            unpack_tree_and_data_section(Metadata, TreeAndDataSection);
        {error, Reason} ->
            {error, {bad_metadata, Reason}}
    end.

unpack_tree_and_data_section(Metadata, TreeAndDataSection) ->
    case unpack_tree_data_and_data_section(Metadata, TreeAndDataSection) of
        {ok, TreeData, DataSection} ->
            instantiate_database(Metadata, TreeData, DataSection);
        {error, _} = Error ->
            Error
    end.

instantiate_database(Metadata, TreeData, DataSection) ->
    #{node_count := NodeCount, record_size := RecordSize, ip_version := IpVersion} = Metadata,

    case locus_mmdb_tree:new(TreeData, NodeCount, RecordSize, IpVersion,
                             byte_size(DataSection))
    of
        {ok, Tree} ->
            {ok, #{metadata => Metadata,
                   tree => Tree,
                   data_section => DataSection}};
        {error, Reason} ->
            {error, {bad_tree,
                     {{because, Reason},
                      {with_metadata, Metadata}}}}
    end.

lookup_parsed_address(ParsedAddress, Database) ->
    #{tree := Tree, data_section := DataSection} = Database,

    case locus_mmdb_tree:lookup(ParsedAddress, Tree) of
        {ok, DataIndex} ->
            lookup_address_data(DataIndex, DataSection);
        not_found ->
            not_found;
        {error, _} = Error ->
            Error
    end.

lookup_address_data(DataIndex, DataSection) ->
    try locus_mmdb_data_codec:parse_on_index(DataIndex, DataSection, _Raw = false) of
        {Entry, _RemainingData} ->
            {ok, Entry}
    catch
        Class:Reason:Stacktrace ->
            SaferReason = locus_util:purge_term_of_very_large_binaries(Reason),
            SaferStacktrace = locus_util:purge_term_of_very_large_binaries(Stacktrace),
            erlang:raise(Class, SaferReason, SaferStacktrace)
    end.