locus (locus v2.3.15)

The main API.

Summary

Types

custom_fetcher()

database_edition()

database_entry()

database_error()

database_info()

database_metadata()

database_source()

database_url()

database_version()

ip_address_prefix()

legacy_maxmind_database_edition()

maxmind_database_edition()

Functions

await_loader(DatabaseId)

Like await_loader/2 but with a default timeout of 30 seconds.

await_loader(DatabaseId, Timeout)

Blocks caller execution until either readiness is achieved or the given timeout is triggered.

await_loaders(DatabaseIds, Timeout)

Like await_loader/2 but concurrently awaits status from more than one database.

check(DatabaseId)

Analyzes a loaded database for corruption or incompatibility.

get_info(DatabaseId)

Returns the properties of a currently loaded database.

get_info(DatabaseId, Property)

Returns a specific property of a currently loaded database.

loader_child_spec(DatabaseId, LoadFrom)

Like loader_child_spec/3 but with default options.

loader_child_spec(DatabaseId, LoadFrom, Opts)

Like loader_child_spec/4 but with default child id.

loader_child_spec(ChildId, DatabaseId, LoadFrom, Opts)

Returns a supervisor child spec for a database loader under id DatabaseId with options Opts.

lookup(DatabaseId, Address)

Looks up info on IPv4 and IPv6 addresses.

start_loader(DatabaseId, LoadFrom)

Like start_loader/3 but with default options.

start_loader(DatabaseId, LoadFrom, Opts)

Starts a database loader under id DatabaseId with options Opts.

stop_loader(DatabaseId)

Stops the database loader under id DatabaseId.

Types

custom_fetcher()

-type custom_fetcher() :: {custom_fetcher, module(), Args :: term()}.

database_edition()

-type database_edition() :: maxmind_database_edition().

database_entry()

-type database_entry() :: locus_mmdb_data:value().

database_error()

-type database_error() :: database_unknown | database_not_loaded.

database_info()

-type database_info() ::
          #{metadata := database_metadata(), source := database_source(), version := database_version()}.

database_metadata()

-type database_metadata() :: locus_mmdb_metadata:t().

database_source()

-type database_source() :: locus_loader:source().

database_url()

-type database_url() :: unicode:chardata().

database_version()

-type database_version() :: calendar:datetime().

ip_address_prefix()

-type ip_address_prefix() :: locus_mmdb_tree:ip_address_prefix().

legacy_maxmind_database_edition()

-type legacy_maxmind_database_edition() :: atom().

maxmind_database_edition()

-type maxmind_database_edition() ::
          {maxmind, atom() | unicode:chardata()} | legacy_maxmind_database_edition().

Functions

await_loader(DatabaseId)

-spec await_loader(DatabaseId) -> {ok, LoadedVersion} | {error, Reason}
                      when
                          DatabaseId :: atom(),
                          LoadedVersion :: database_version(),
                          Reason ::
                              database_unknown |
                              {database_stopped, term()} |
                              {timeout, LoadAttemptFailures},
                          LoadAttemptFailures :: [term()].

Like await_loader/2 but with a default timeout of 30 seconds.

DatabaseId must be an atom and refer to a database loader.

Returns:

{ok, LoadedVersion} when the database is ready to use.
{error, database_unknown} if the database loader for DatabaseId hasn't been started.
{error, {database_stopped, _}} if the database loader for DatabaseId stopped while we waited.
{error, {timeout, [_]}} if all the load attempts performed before timing out have failed.

await_loader(DatabaseId, Timeout)

-spec await_loader(DatabaseId, Timeout) -> {ok, LoadedVersion} | {error, Reason}
                      when
                          DatabaseId :: atom(),
                          Timeout :: timeout(),
                          LoadedVersion :: database_version(),
                          Reason ::
                              database_unknown |
                              {database_stopped, term()} |
                              {timeout, LoadAttemptFailures},
                          LoadAttemptFailures :: [term()].

Blocks caller execution until either readiness is achieved or the given timeout is triggered.

DatabaseId must be an atom and refer to a database loader.
Timeout must be either a non-negative integer (milliseconds) or infinity.

Returns:

{ok, LoadedVersion} when the database is ready to use.
{error, database_unknown} if the database loader for DatabaseId hasn't been started.
{error, {database_stopped, _}} if the database loader for DatabaseId stopped while we waited.
{error, {timeout, [_]}} if all the load attempts performed before timing out have failed.

await_loaders(DatabaseIds, Timeout)

-spec await_loaders(DatabaseIds, Timeout) ->
                       {ok, Successes} | {error, {ErrorPerDatabase, PartialSuccesses}}
                       when
                           DatabaseIds :: [DatabaseId],
                           Timeout :: timeout(),
                           Successes :: LoadedVersionPerDatabase,
                           PartialSuccesses :: LoadedVersionPerDatabase,
                           LoadedVersionPerDatabase :: #{DatabaseId => LoadedVersion},
                           LoadedVersion :: database_version(),
                           ErrorPerDatabase :: #{DatabaseId := Reason},
                           Reason ::
                               database_unknown |
                               {database_stopped, term()} |
                               {timeout, LoadAttemptFailures},
                           LoadAttemptFailures :: [term()].

Like await_loader/2 but concurrently awaits status from more than one database.

DatabaseIds must be a list of atoms referring to database loaders.
Timeout must be either a non-negative integer (milliseconds) or infinity.

Returns:

{ok, #{DatabaseId => LoadedVersion}} when all the databases are ready to use.
{error, {#{DatabaseId => ErrorReason}, _}} in case of errors.

check(DatabaseId)

-spec check(DatabaseId) ->
               ok |
               {error, Error} |
               {validation_warnings, [ValidationWarning, ...]} |
               {validation_errors, [ValidationError, ...], [ValidationWarning]}
               when
                   DatabaseId :: atom(),
                   Error :: database_unknown | database_not_loaded,
                   ValidationWarning :: locus_mmdb_check:warning(),
                   ValidationError :: locus_mmdb_check:error().

Analyzes a loaded database for corruption or incompatibility.

DatabaseId must be an atom and refer to a database loader.

Returns:

ok if the database is wholesome.
{error, database_unknown} if the database loader for DatabaseId hasn't been started.
{error, database_not_loaded} if the database hasn't yet been loaded.
{validation_warnings, [CheckWarning, ...]} in case something smells within the database (check the definitions in locus_mmdb_check).
{validation_errors, [CheckError], [...]} in case of corruption or incompatibility (check the definitions in locus_mmdb_check).

get_info(DatabaseId)

-spec get_info(DatabaseId) -> {ok, Info} | {error, Error}
                  when
                      DatabaseId :: atom(),
                      Info :: database_info(),
                      Error :: database_unknown | database_not_loaded.

Returns the properties of a currently loaded database.

DatabaseId must be an atom and refer to a database loader.

Returns:

{ok, t:database_info/0} in case of success.
{error, database_unknown} if the database loader for DatabaseId hasn't been started.
{error, database_not_loaded} if the database hasn't yet been loaded.

get_info(DatabaseId, Property)

-spec get_info(DatabaseId, Property) -> {ok, Value} | {error, Error}
                  when
                      DatabaseId :: atom(),
                      Property :: metadata | source | version,
                      Value :: database_metadata() | database_source() | database_version(),
                      Error :: database_unknown | database_not_loaded.

Returns a specific property of a currently loaded database.

DatabaseId must be an atom and refer to a database loader.
Property must be either metadata, source or version.

Returns:

{ok, Value} in case of success.
{error, database_unknown} if the database loader for DatabaseId hasn't been started.
{error, database_not_loaded} if the database hasn't yet been loaded.

loader_child_spec(DatabaseId, LoadFrom)

-spec loader_child_spec(DatabaseId, LoadFrom) -> ChildSpec | no_return()
                           when
                               DatabaseId :: atom(),
                               LoadFrom :: DatabaseEdition | DatabaseURL | CustomFetcher,
                               DatabaseEdition :: database_edition(),
                               DatabaseURL :: database_url(),
                               CustomFetcher :: custom_fetcher(),
                               ChildSpec :: locus_database:static_child_spec().

Like loader_child_spec/3 but with default options.

DatabaseId must be an atom.
LoadFrom must be either:
- a database_edition/0 tuple, or
- a DatabaseURL containing either a string or binary representation of a HTTP(s) URL or local path, or
- a {custom_fetcher, Module, Args} tuple, with Module implementing the locus_custom_fetcher behaviour

Returns:

A supervisor:child_spec/0.

loader_child_spec(DatabaseId, LoadFrom, Opts)

-spec loader_child_spec(DatabaseId, LoadFrom, Opts) -> ChildSpec | no_return()
                           when
                               DatabaseId :: atom(),
                               LoadFrom :: DatabaseEdition | DatabaseURL | CustomFetcher,
                               DatabaseEdition :: database_edition(),
                               DatabaseURL :: database_url(),
                               CustomFetcher :: custom_fetcher(),
                               Opts :: [locus_database:opt()],
                               ChildSpec :: locus_database:static_child_spec().

Like loader_child_spec/4 but with default child id.

DatabaseId must be an atom.
LoadFrom must be either:
- a database_edition/0 tuple, or
- a DatabaseURL containing either a string or binary representation of a HTTP(s) URL or local path, or
- a {custom_fetcher, Module, Args} tuple, with Module implementing the locus_custom_fetcher behaviour
Opts must be a list of locus_database:opt/0 values

Returns:

A supervisor:child_spec/0.

loader_child_spec(ChildId, DatabaseId, LoadFrom, Opts)

-spec loader_child_spec(ChildId, DatabaseId, LoadFrom, Opts) -> ChildSpec | no_return()
                           when
                               ChildId :: term(),
                               DatabaseId :: atom(),
                               LoadFrom :: DatabaseEdition | DatabaseURL | CustomFetcher,
                               DatabaseEdition :: database_edition(),
                               DatabaseURL :: database_url(),
                               CustomFetcher :: custom_fetcher(),
                               Opts :: [locus_database:opt()],
                               ChildSpec :: locus_database:static_child_spec().

Returns a supervisor child spec for a database loader under id DatabaseId with options Opts.

DatabaseId must be an atom.
LoadFrom must be either:
- a database_edition/0 tuple, or
- a DatabaseURL containing either a string or binary representation of a HTTP(s) URL or local path, or
- a {custom_fetcher, Module, Args} tuple, with Module implementing the locus_custom_fetcher behaviour
Opts must be a list of locus_database:opt/0 values

Returns:

A supervisor:child_spec/0.

lookup(DatabaseId, Address)

-spec lookup(DatabaseId, Address) -> {ok, Entry} | not_found | {error, Error}
                when
                    DatabaseId :: atom(),
                    Address :: inet:ip_address() | string() | binary(),
                    Entry :: database_entry(),
                    Error ::
                        database_unknown | database_not_loaded |
                        {invalid_address, Address} |
                        ipv4_database.

Looks up info on IPv4 and IPv6 addresses.

DatabaseId must be an atom and refer to a database loader.
Address must be either a inet:ip_address/0 tuple, or a string/binary containing a valid representation of the address.

Returns:

{ok, Entry} in case of success.
not_found if no data was found for this Address.
{error, invalid_address} if Address is not either a inet:ip_address/0 tuple or a valid textual representation of an IP address.
{error, database_unknown} if the database loader for DatabaseId hasn't been started.
{error, database_not_loaded} if the database hasn't yet been loaded.
{error, ipv4_database} if Address represents an IPv6 address and the database only supports IPv4 addresses.

start_loader(DatabaseId, LoadFrom)

-spec start_loader(DatabaseId, LoadFrom) -> ok | {error, Error}
                      when
                          DatabaseId :: atom(),
                          LoadFrom :: DatabaseEdition | DatabaseURL | CustomFetcher,
                          DatabaseEdition :: database_edition(),
                          DatabaseURL :: database_url(),
                          CustomFetcher :: custom_fetcher(),
                          Error :: invalid_url | already_started | application_not_running.

Like start_loader/3 but with default options.

DatabaseId must be an atom.
LoadFrom must be either:
- a database_edition/0 tuple, or
- a DatabaseURL containing either a string or binary representation of a HTTP(s) URL or local path, or
- a {custom_fetcher, Module, Args} tuple, with Module implementing the locus_custom_fetcher behaviour

Returns:

ok in case of success.
{error, invalid_url} if the source is invalid.
{error, already_started} if the loader under DatabaseId has already been started.

start_loader(DatabaseId, LoadFrom, Opts)

-spec start_loader(DatabaseId, LoadFrom, Opts) -> ok | {error, Error}
                      when
                          DatabaseId :: atom(),
                          LoadFrom :: DatabaseEdition | DatabaseURL | CustomFetcher,
                          DatabaseEdition :: database_edition(),
                          DatabaseURL :: database_url(),
                          CustomFetcher :: custom_fetcher(),
                          Opts :: [locus_database:opt()],
                          Error ::
                              invalid_url | already_started |
                              {invalid_opt, term()} |
                              application_not_running.

Starts a database loader under id DatabaseId with options Opts.

DatabaseId must be an atom.
LoadFrom must be either:
- a database_edition/0 tuple, or
- a DatabaseURL containing either a string or binary representation of a HTTP(s) URL or local path, or
- a {custom_fetcher, Module, Args} tuple, with Module implementing the locus_custom_fetcher behaviour
Opts must be a list of locus_database:opt/0 values

Returns:

ok in case of success.
{error, invalid_url} if the source is invalid.
{error, already_started} if the loader under DatabaseId has already been started.

stop_loader(DatabaseId)

-spec stop_loader(DatabaseId) -> ok | {error, Error} when DatabaseId :: atom(), Error :: not_found.

Stops the database loader under id DatabaseId.

DatabaseId must be an atom and refer to a database loader.

Returns ok in case of success, {error, not_found} otherwise.