Locus

https://hexdocs.pm/locus/
Admin
Locus is an Erlang/OTP and Elixir library that allows pinpointing the country, city, or ASN of IP...
Tokens:27,152
Snippets:277
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### start(Id, Origin, Opts)

Source: https://hexdocs.pm/locus/locus_database.html

Starts the database loader with the given ID, origin, and options. Returns ok on success or an error tuple.

```APIDOC
## start(Id, Origin, Opts)

### Description
Starts the database loader with the given ID, origin, and options.

### Function Signature
```erlang
-spec start(atom(), origin(), [opt()]) ->
               ok |
               {error, already_started} |
               {error, {invalid_opt, term()}} |
               {error, application_not_running}.
```

### Parameters
- **Id** (atom()) - Required - Identifier for the database loader.
- **Origin** (origin()) - Required - Origin of the database.
- **Opts** ([opt()]) - Required - List of options.

### Returns
- **ok** - Success.
- **{error, already_started}** - If already started.
- **{error, {invalid_opt, term()}}** - If an invalid option is provided.
- **{error, application_not_running}** - If the application is not running.
```

--------------------------------

### Start database loader in Erlang with locus:start_loader

Source: https://hexdocs.pm/locus/index.html

Starts the database loader for a country database using MaxMind. Comments show alternative sources: HTTP(S) URL, local path, or a custom_fetcher tuple.

```erlang
ok = locus:start_loader(country, {maxmind, "GeoLite2-Country"}).
% You can also use:
% * an HTTP(S) URL,
% * or a local path, e.g. "/usr/share/GeoIP/GeoLite2-City.mmdb"
% * or a {custom_fetcher, Module, Args} tuple, with Module
%   implementing the locus_custom_fetcher behaviour.
```

--------------------------------

### start_loader(DatabaseId, LoadFrom, Opts)

Source: https://hexdocs.pm/locus/locus.html

Starts a database loader under id `DatabaseId` with options `Opts`.

```APIDOC
## start_loader(DatabaseId, LoadFrom, Opts)

### Description
Starts a database loader under id `DatabaseId` with options `Opts`.

### Function Signature
start_loader(DatabaseId, LoadFrom, Opts)

### Parameters
- **DatabaseId** (term) - Required - The identifier for the loader.
- **LoadFrom** (term) - Required - The source to load the database from.
- **Opts** (keyword list) - Required - Options for the loader.

### Returns
- **{:ok, pid}** - The process id of the loader.
- **{:error, reason}** - If the loader fails to start.
```

--------------------------------

### on_app_start()

Source: https://hexdocs.pm/locus/locus_logger.html

Called when the application starts. It initializes logging for locus_database events.

```APIDOC
## on_app_start()

### Description
Called when the application starts. It initializes logging for locus_database events.

### Function Signature
`on_app_start() -> ok`

### Parameters
None

### Returns
- `ok` (atom) - Indicates successful initialization.
```

--------------------------------

### start_link/3 function specification

Source: https://hexdocs.pm/locus/locus_maxmind_download.html

Starts the download process linked to the caller.

```erlang
-spec start_link(atom(), locus_http_download:headers(), [opt()]) -> {ok, pid()}.
```

--------------------------------

### start_link(URL, Headers, Opts)

Source: https://hexdocs.pm/locus/locus_http_download.html

Starts the download by linking to a new process. This is the primary function to initiate an HTTP(S) download without blocking the caller.

```APIDOC
## start_link(URL, Headers, Opts)

### Description
Starts the HTTP(S) download process with the given URL, headers, and options. It returns the process ID (pid) once started.

### Function Signature
```erlang
-spec start_link(url(), headers(), [opt()]) -> {ok, pid()}.
```

### Parameters
#### Arguments
- **URL** (url()) - Required - The URL to download from, as a string.
- **Headers** (headers()) - Required: A list of {string(), string()} tuples representing HTTP headers.
- **Opts** ([opt()]) - Required: List of options controlling the download (see the opt() type for details).

### Return Value
- `{ok, pid()}` - The process ID of the started download process.
```

--------------------------------

### start_link(Id, Origin, Opts)

Source: https://hexdocs.pm/locus/locus_database.html

Starts the database loader and links to the calling process. Returns a tuple with the process ID.

```APIDOC
## start_link(Id, Origin, Opts)

### Description
Starts the database loader and links to the calling process.

### Function Signature
```erlang
-spec start_link(atom(), origin(), [opt()]) -> {ok, pid()}.
```

### Parameters
- **Id** (atom()) - Required - Identifier for the database loader.
- **Origin** (origin()) - Required - Origin of the database.
- **Opts** ([opt()]) - Required - List of options.

### Returns
- **{ok, pid()}** - Success with the process ID.
```

--------------------------------

### Start database loader in Elixir application.ex

Source: https://hexdocs.pm/locus/index.html

Starts the database loader for a city database in an Elixir application's start/2 callback. Comments show examples for ASN and country databases.

```elixir
def start(_type, _args) do
  # :locus.start_loader(:asn, {:maxmind, "GeoLite2-ASN"})
  # :locus.start_loader(:country, {:maxmind, "GeoLite2-Country"})
  :locus.start_loader(:city, {:maxmind, "GeoLite2-City"})

  ...
```

--------------------------------

### event_download_started() type definition

Source: https://hexdocs.pm/locus/locus_http_download.html

Defines the event for a download that has started.

```erlang
-type event_download_started() :: {download_started, headers()}.
```

--------------------------------

### start_link/4 function specification

Source: https://hexdocs.pm/locus/locus_loader.html

Starts the loader process linked to the calling process.

```erlang
-spec start_link(atom(), origin(), [loader_opt()], [fetcher_opt()]) -> {ok, pid()}.
```

--------------------------------

### start_link/3 function specification

Source: https://hexdocs.pm/locus/locus_filesystem_store.html

Specifies the start_link function to start the process with the given path, content, and modification datetime.

```erlang
-spec start_link(path(), iodata(), calendar:datetime()) -> {ok, pid()}.
```

--------------------------------

### async_get_version_or_subscribe(Id)

Source: https://hexdocs.pm/locus/locus_database.html

Asynchronously gets the version or subscribes to updates for the given ID. Returns a reference for later retrieval.

```APIDOC
## async_get_version_or_subscribe(Id)

### Description
Asynchronously gets the version or subscribes to updates for the given ID.

### Function Signature
```erlang
-spec async_get_version_or_subscribe(atom()) -> {await, reference()}.
```

### Parameters
- **Id** (atom()) - Required - Identifier for the database.

### Returns
- **{await, reference()}** - A reference to await the result.
```

--------------------------------

### Look up IP address in Erlang with locus:lookup

Source: https://hexdocs.pm/locus/index.html

Performs a country lookup for an IP address. Comments show example calls and possible return values: {ok, Entry}, not_found, or {error, _}. The displayed result is a map with continent, country, and registered_country details.

```erlang

% > locus:lookup(country, "93.184.216.34").
% > locus:lookup(country, "2606:2800:220:1:248:1893:25c8:1946").

% * '{ok, Entry}' in case of success;
% * 'not_found' if no entry was found
% * '{error, _}' if something bad happened

{ok,#{<<"continent">> =>
          #{<<"code">> => <<"NA">>,
            <<"geoname_id">> => 6255149,
            <<"names">> =>
                #{<<"de">> => <<"Nordamerika">>,
                  <<"en">> => <<"North America">>,
                  <<"es">> => <<"Norteamérica"/utf8>>,
                  <<"fr">> => <<"Amérique du Nord"/utf8>>,
                  <<"ja">> => <<"北アメリカ"/utf8>>,
                  <<"pt-BR">> => <<"América do Norte"/utf8>>,
                  <<"ru">> => <<"Северная Америка"/utf8>>,
                  <<"zh-CN">> => <<"北美洲"/utf8>>}},
      <<"country">> =>
          #{<<"geoname_id">> => 6252001,
            <<"iso_code">> => <<"US">>,
            <<"names">> =>
                #{<<"de">> => <<"USA">>,
                  <<"en">> => <<"United States">>,
                  <<"es">> => <<"Estados Unidos">>,
                  <<"fr">> => <<"États-Unis"/utf8>>,
                  <<"ja">> => <<"アメリカ合衆国"/utf8>>,
                  <<"pt-BR">> => <<"Estados Unidos">>,
                  <<"ru">> => <<"США"/utf8>>,
                  <<"zh-CN">> => <<"美国"/utf8>>}},
      <<"registered_country">> =>
          #{<<"geoname_id">> => 6252001,
            <<"iso_code">> => <<"US">>,
            <<"names">> =>
                #{<<"de">> => <<"USA">>,
                  <<"en">> => <<"United States">>,
                  <<"es">> => <<"Estados Unidos">>,
                  <<"fr">> => <<"États-Unis"/utf8>>,
                  <<"ja">> => <<"アメリカ合衆国"/utf8>>,
                  <<"pt-BR">> => <<"Estados Unidos">>,
                  <<"ru">> => <<"США"/utf8>>,
                  <<"zh-CN">> => <<"美国"/utf8>>}}}}
```

--------------------------------

### start_loader(DatabaseId, LoadFrom)

Source: https://hexdocs.pm/locus/locus.html

Like `start_loader/3` but with default options.

```APIDOC
## start_loader(DatabaseId, LoadFrom)

### Description
Like `start_loader/3` but with default options.

### Function Signature
start_loader(DatabaseId, LoadFrom)

### Parameters
- **DatabaseId** (term) - Required - The identifier for the loader.
- **LoadFrom** (term) - Required - The source to load the database from.

### Returns
- **{:ok, pid}** - The process id of the loader.
- **{:error, reason}** - If the loader fails to start.
```

--------------------------------

### init/1 function specification

Source: https://hexdocs.pm/locus/locus_http_download.html

Initializes the download process.

```erlang
-spec init([InitArg, ...]) -> {ok, state()}
              when
                  InitArg :: OwnerPid | URL | Headers | Opts,
                  OwnerPid :: pid(),
                  URL :: url(),
                  Headers :: headers(),
                  Opts :: [opt()].
```

--------------------------------

### proc_lib_init/1 function specification

Source: https://hexdocs.pm/locus/locus_maxmind_download.html

Initializes the process using proc_lib.

```erlang
-spec proc_lib_init([InitArg, ...]) -> no_return()
                       when
                           InitArg :: OwnerPid | Edition | RequestHeaders | Opts,
                           OwnerPid :: pid(),
                           Edition :: atom(),
                           RequestHeaders :: locus_http_download:headers(),
                           Opts :: [opt()].
```

--------------------------------

### reason_for_download_failing_to_start() type definition

Source: https://hexdocs.pm/locus/locus_http_download.html

Defines the possible reasons for a download failure at startup.

```erlang
-type reason_for_download_failing_to_start() ::
          full_http_response() |
          too_many_redirections |
          {invalid_redirection, term()} |
          {error, term()} |
          timeout.
```

--------------------------------

### init/1 function specification

Source: https://hexdocs.pm/locus/locus_maxmind_download.html

Initializes the process.

```erlang
-spec init(_) -> no_return().
```

--------------------------------

### new(TreeData, NodeCount, RecordSize, IpVersion, DataSectionSize)

Source: https://hexdocs.pm/locus/locus_mmdb_tree.html

Instantiates a new Tree out of TreeData, a few metadata properties and DataSectionSize. Returns {ok, Tree} or {error, Reason}.

```APIDOC
## new(TreeData, NodeCount, RecordSize, IpVersion, DataSectionSize)

### Description
Instantiates a new `Tree` out of `TreeData`, a few metadata properties and `DataSectionSize`.

### Function Signature
```erlang
-spec new(TreeData, NodeCount, RecordSize, IpVersion, DataSectionSize) -> {ok, Tree} | {error, Reason}
             when
                 TreeData :: binary(),
                 NodeCount :: non_neg_integer(),
                 RecordSize :: non_neg_integer(),
                 IpVersion :: 4 | 6,
                 DataSectionSize :: non_neg_integer(),
                 Tree :: t(),
                 Reason :: term().
```

### Parameters
- **TreeData** (binary()) - Required - The binary data of the tree.
- **NodeCount** (non_neg_integer()) - Required - The number of nodes in the tree.
- **RecordSize** (non_neg_integer()) - Required - The record size in bits.
- **IpVersion** (4 | 6) - Required - The IP version (4 or 6).
- **DataSectionSize** (non_neg_integer()) - Required - The size of the data section.

### Returns
- `{ok, Tree}` - The newly created tree.
- `{error, Reason}` - An error occurred, with Reason being any term.
```

--------------------------------

### opt() type definition

Source: https://hexdocs.pm/locus/locus_maxmind_download.html

Defines the configuration options for the download, including license keys and dates.

```erlang
-type opt() :: {license_key, binary() | string()} | {date, calendar:date()} | locus_http_download:opt().
```

--------------------------------

### start_loader/2 function specification

Source: https://hexdocs.pm/locus/locus.html

Specifies the start_loader function for initializing a database loader with default options.

```erlang
-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.
```

--------------------------------

### event_download_failed_to_start() type definition

Source: https://hexdocs.pm/locus/locus_http_download.html

Defines the event for a download that failed to initiate.

```erlang
-type event_download_failed_to_start() ::
          {download_failed_to_start, reason_for_download_failing_to_start()}.
```

--------------------------------

### Spec: init/1

Source: https://hexdocs.pm/locus/locus_custom_fetcher.html

Spec for init/1 requiring at least one init arg and continuing with fetch.

```erlang
-spec init([InitArg, ...]) -> {ok, state(), {continue, fetch}}
              when
                  InitArg :: OwnerPid | Source | Module | Args | PreviousFetchMetadata,
                  OwnerPid :: pid(),
                  Source :: source(),
                  Module :: module(),
                  Args :: term(),
                  PreviousFetchMetadata :: successful_fetch_metadata() | undefined.
```

--------------------------------

### Spec: start_link/4

Source: https://hexdocs.pm/locus/locus_custom_fetcher.html

Spec for start_link/4 returning {ok, pid()}.

```erlang
-spec start_link(source(), module(), term(), successful_fetch_metadata() | undefined) -> {ok, pid()}.
```

--------------------------------

### version(BuildEpoch)

Source: https://hexdocs.pm/locus/locus_database.html

Returns the database version based on its build epoch (UNIX timestamp).

```APIDOC
## version(BuildEpoch)

### Description
Returns the database version based on its build epoch (UNIX timestamp).

### Function Signature
```erlang
-spec version(BuildEpoch) -> Version
                 when BuildEpoch :: non_neg_integer(), Version :: calendar:datetime().
```

### Parameters
- **BuildEpoch** (non_neg_integer()) - Required - UNIX timestamp of the build.

### Returns
- **Version** (calendar:datetime()) - The database version.
```

--------------------------------

### init/1 function specification

Source: https://hexdocs.pm/locus/locus_filesystem_store.html

Specifies the init callback for initializing the process with owner PID, path, content, and modification datetime.

```erlang
-spec init([InitArg, ...]) -> {ok, state()}
              when
                  InitArg :: OwnerPid | Path | Content | ModificationDT,
                  OwnerPid :: pid(),
                  Path :: path(),
                  Content :: iodata(),
                  ModificationDT :: calendar:datetime().
```

--------------------------------

### Configure MaxMind license key in config/config.exs (Elixir)

Source: https://hexdocs.pm/locus/index.html

Sets the MaxMind license key in an Elixir config/config.exs file. Skip this step if not loading databases directly from MaxMind.

```elixir
config :locus,
  license_key: "YOUR_LICENSE_KEY"
```

--------------------------------

### unpack_database(EncodedDatabase)

Source: https://hexdocs.pm/locus/locus_mmdb.html

Unpacks an encoded MMDB database binary into a ready-to-use database. Returns the database or an error.

```APIDOC
## unpack_database(EncodedDatabase)

### Description
Unpacks an `EncodedDatabase` binary into a ready-to-use `Database`.

### Function Signature
```erlang
-spec unpack_database(EncodedDatabase) -> {ok, Database} | {error, ErrorReason}
                         when
                             EncodedDatabase :: binary(),
                             Database :: database(),
                             ErrorReason :: unpack_error().
```

### Parameters
- **EncodedDatabase** (binary()) - Required - The encoded MMDB database binary.

### Returns
- `{ok, Database}` - The unpacked database.
- `{error, ErrorReason}` - An error occurred. See `unpack_error()` type.
```

--------------------------------

### Configure MaxMind license key in sys.config (Erlang)

Source: https://hexdocs.pm/locus/index.html

Sets the MaxMind license key in an Erlang sys.config file. Skip this step if not loading databases directly from MaxMind.

```erlang
[{locus, [{license_key, "YOUR_LICENSE_KEY"}]}].
```

--------------------------------

### Rename get_version/1 to get_info/2

Source: https://hexdocs.pm/locus/migration.html

Replace calls to `get_version/1` with `get_info/2`, passing `version` as the second argument.

```erlang
% before
{ok, LoadedVersion} = locus:get_version(country),

% after
{ok, LoadedVersion} = locus:get_info(country, version),
```

--------------------------------

### Rename pre_readiness_update_period option

Source: https://hexdocs.pm/locus/migration.html

Replace the `{pre_readiness_update_period, Interval}` loader option with `{error_retries, {backoff, Interval}}` if exponential backoff is not desired.

```erlang
% before
{pre_readiness_update_period, Interval}

% after
{error_retries, {backoff, Interval}}
```

--------------------------------

### Spec: description/2

Source: https://hexdocs.pm/locus/locus_custom_fetcher.html

Spec for description/2 returning description().

```erlang
-spec description(module(), term()) -> description().
```

--------------------------------

### Spec: source/2

Source: https://hexdocs.pm/locus/locus_custom_fetcher.html

Spec for source/2 returning a source.

```erlang
-spec source(module(), term()) -> source().
```

--------------------------------

### Wait for database to load with locus:await_loader

Source: https://hexdocs.pm/locus/index.html

Optionally waits for the country database to load, returning {ok, DatabaseVersion} or {error, Reason}.

```erlang
{ok, _DatabaseVersion} = locus:await_loader(country). % or `{error, Reason}`
```

--------------------------------

### Rename post_readiness_update_period option

Source: https://hexdocs.pm/locus/migration.html

Replace the `{post_readiness_update_period, Interval}` loader option with `{update_period, Interval}`.

```erlang
% before
{post_readiness_update_period, Interval}

% after
{update_period, Interval}
```

--------------------------------

### get_info(DatabaseId)

Source: https://hexdocs.pm/locus/locus.html

Returns the properties of a currently loaded database.

```APIDOC
## get_info(DatabaseId)

### Description
Returns the properties of a currently loaded database.

### Function Signature
get_info(DatabaseId)

### Parameters
- **DatabaseId** (term) - Required - The identifier of the database.

### Returns
- **database_info()** - A map or struct containing database properties.
```

--------------------------------

### find(Id)

Source: https://hexdocs.pm/locus/locus_database.html

Finds the loaded database for the given ID. Returns the database, source, and version, or an error.

```APIDOC
## find(Id)

### Description
Finds the loaded database for the given ID.

### Function Signature
```erlang
-spec find(atom()) ->
              {ok, locus_mmdb:database(), locus_loader:source(), calendar:datetime()} |
              {error, database_not_loaded} |
              {error, database_unknown}.
```

### Parameters
- **Id** (atom()) - Required - Identifier for the database.

### Returns
- **{ok, Database, Source, Version}** - Success with the database, source, and version.
- **{error, database_not_loaded}** - If the database is not loaded.
- **{error, database_unknown}** - If the database is unknown.
```

--------------------------------

### Check database with locus CLI

Source: https://hexdocs.pm/locus/index.html

Run the locus CLI check command on a database file. The script exits with code 1 on failure and 0 otherwise. Warnings can be treated as errors with the --warnings-as-errors flag. Use ./locus check --help for options.

```shell
./locus check GeoLite2-City.mmdb
# Loading database from "GeoLite2-City.mmdb"...
# Database version {{2019,11,6},{11,58,0}} successfully loaded
# Checking database for flaws...
# Database is wholesome.

```

--------------------------------

### get_info/2 specification

Source: https://hexdocs.pm/locus/locus.html

Retrieves a specific property (metadata, source, or version) from a loaded database identified by an atom.

```erlang
-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.
```

--------------------------------

### validate_opts(MixedOpts)

Source: https://hexdocs.pm/locus/locus_http_download.html

Validates the options list and returns normalized options or an error. This function can be called directly to validate options before using start_link.

```APIDOC
## validate_opts(MixedOpts)

### Description
Validates the given options, separating or normalizing them. It returns the validated options and a possibly filtered list, or an error for invalid options.

### Function Signature
```erlang
-spec validate_opts(proplists:proplist()) ->
   {ok, {[opt()], proplists:proplist()}} | {error, BadOpt :: term()}.
```

### Parameters
- **MixedOpts** (proplists:proplist()) - Required: A list of options (may contain both accepted and unknown options).

### Return Value
- `{ok, {[opt()], proplists:proplist()}}` - On success: tuple of valid options and the rest of the list.
- `{error, BadOpt :: term()}` - On error: includes the bad option.
```

--------------------------------

### description/1

Source: https://hexdocs.pm/locus/locus_custom_fetcher.html

Callback that returns a description of the fetcher, including whether the database is stored remotely and where it is fetched from.

```APIDOC
## description/1

### Description
Callback that returns a description of the fetcher, including whether the database is stored remotely and where it is fetched from.

### Callback Signature
```
-callback description(Args) -> description() when Args :: term().
```

### Parameters
- **Args** (term) - Required - Arguments passed to the fetcher.

### Return Values
- **description()** - A map with keys `database_is_stored_remotely` (boolean) and `database_is_fetched_from` (term).
```

--------------------------------

### loader_child_spec(DatabaseId, LoadFrom, Opts)

Source: https://hexdocs.pm/locus/locus.html

Returns a supervisor child spec for a database loader with a default child id. Accepts a DatabaseId atom, a LoadFrom source (database edition, URL, or custom fetcher), and a list of options.

```APIDOC
## loader_child_spec(DatabaseId, LoadFrom, Opts)

### Description
Returns a supervisor child spec for a database loader with a default child id. This is a convenience variant of loader_child_spec/4 that uses a default child id.

### Function Signature
```erlang
-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().
```

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

### Returns
- **ChildSpec** (locus_database:static_child_spec()) - A supervisor:child_spec/0.

### See Also
- loader_child_spec/2
- loader_child_spec/4
- await_loader/1
- await_loader/2
- start_loader/3
```

--------------------------------

### run(Database)

Source: https://hexdocs.pm/locus/locus_mmdb_check.html

Checks for errors and quirks within the given MMDB database. Returns ok if no issues are found, or a tuple with warnings and/or errors.

```APIDOC
## run(Database)

### Description
Checks for errors and quirks within the given MMDB database. Returns ok if no issues are found, or a tuple with warnings and/or errors.

### Function Signature
```erlang
-spec run(locus_mmdb:database()) ->
             ok | {warnings, [warning(), ...]} | {errors, [error(), ...], [warning()]}.
```

### Parameters
- **Database** (locus_mmdb:database()) - Required - The MMDB database to check.

### Return Values
- `ok` - No issues found.
- `{warnings, [warning()]}` - Warnings found, no errors.
- `{errors, [error()], [warning()]}` - Errors found, possibly with warnings.

### Types
#### error()
One of: `bad_node_index_in_tree()`, `bad_data_index_in_tree()`, `excessively_long_path_in_tree()`, `loop_in_data_section()`, `invalid_position_in_data_section()`, `bad_chunk_in_data_section()`, `map_key_of_wrong_type_in_data_section()`, `invalid_utf8_string_in_data_section()`.

#### warning()
`unprintable_utf8_string_in_data_section()`.

```

--------------------------------

### Use atom keys for metadata

Source: https://hexdocs.pm/locus/migration.html

Change code matching/using `metadata` from `locus:get_info/1` or `locus:get_info/2` to use atom keys instead of binary ones. Note that `binary_format_major_version` and `binary_format_minor_version` are combined into `binary_format_version` as a tuple.

```erlang
% before:
{ok, Metadata} = locus:get_info(country, metadata),
#{<<"binary_format_major_version">> := Major,
  <<"binary_format_minor_version">> := Minor,
  <<"node_count">> := _,
  <<"record_size">> := _,
  <<"ip_version">> := _,
  <<"database_type">> := _,
  <<"languages">> := _,
  <<"build_epoch">> := _,
  <<"description">> := _} = Metadata,

% after:
{ok, Metadata} = locus:get_info(country, metadata),
#{binary_format_version := {Major, Minor}, % Notice how this was two keys before
  node_count := _,
  record_size := _,
  ip_version := _,
  database_type := _,
  languages := _,
  build_epoch := _,
  description := _} = Metadata,
```

--------------------------------

### await_loaders/2 function specification

Source: https://hexdocs.pm/locus/locus.html

Concurrently awaits readiness for multiple database loaders.

```erlang
-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()].
```

--------------------------------

### await_loaders(DatabaseIds, Timeout)

Source: https://hexdocs.pm/locus/locus.html

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

```APIDOC
## await_loaders(DatabaseIds, Timeout)

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

### Function Signature
await_loaders(DatabaseIds, Timeout)

### Parameters
- **DatabaseIds** (list) - Required - A list of database identifiers to await.
- **Timeout** (integer) - Required - The timeout in milliseconds.

### Returns
- **:ok** - When all databases are ready.
- **{:error, reason}** - If the timeout is triggered or an error occurs.
```

--------------------------------

### parse_all(FullData, Raw)

Source: https://hexdocs.pm/locus/locus_mmdb_data_codec.html

Parses all data from the given binary and returns a list of values or raw values depending on the Raw flag.

```APIDOC
## parse_all(FullData, Raw)

### Description
Parses all data from the given binary and returns a list of values or raw values depending on the Raw flag.

### Function Signature
```erlang
-spec parse_all(binary(), boolean()) -> [locus_mmdb_data:value() | locus_mmdb_data_raw:value()].
```

### Parameters
- **FullData** (binary()) - Required - The full data binary to parse.
- **Raw** (boolean()) - Required - If true, returns raw values; otherwise returns parsed values.

### Returns
- List of values (locus_mmdb_data:value() or locus_mmdb_data_raw:value()).
```

--------------------------------

### Callback: fetch/1

Source: https://hexdocs.pm/locus/locus_custom_fetcher.html

Callback that returns fetched success or error.

```erlang
-callback fetch(Args) -> {fetched, Success} | {error, Reason}
                   when Args :: term(), Success :: success(), Reason :: term().
```

--------------------------------

### get_info(DatabaseId, Property)

Source: https://hexdocs.pm/locus/locus.html

Returns a specific property of a currently loaded database.

```APIDOC
## get_info(DatabaseId, Property)

### Description
Returns a specific property of a currently loaded database.

### Function Signature
get_info(DatabaseId, Property)

### Parameters
- **DatabaseId** (term) - Required - The identifier of the database.
- **Property** (atom) - Required - The property to retrieve.

### Returns
- **term** - The value of the requested property.
```

--------------------------------

### await_loader(DatabaseId)

Source: https://hexdocs.pm/locus/locus.html

Blocks caller execution until readiness is achieved or a default timeout of 30 seconds is triggered.

```APIDOC
## await_loader(DatabaseId)

### Description
Blocks caller execution until readiness is achieved or a default timeout of 30 seconds is triggered.

### Function Signature
await_loader(DatabaseId)

### Parameters
- **DatabaseId** (term) - Required - The identifier of the database to await.

### Returns
- **:ok** - When the database is ready.
- **{:error, reason}** - If the timeout is triggered or an error occurs.
```

--------------------------------

### handle_info/2 function specification

Source: https://hexdocs.pm/locus/locus_maxmind_download.html

Handles system messages and process signals.

```erlang
-spec handle_info(term(), state()) ->
                     {noreply, state()} |
                     {stop, normal, state()} |
                     {stop, {database_download_stopped, pid(), term()}, state()} |
                     {stop, {checksum_download_stopped, pid(), term()}, state()} |
                     {stop, unexpected_info, state()}.
```

--------------------------------

### fetch/1

Source: https://hexdocs.pm/locus/locus_custom_fetcher.html

Callback that fetches data. It returns either fetched data or an error.

```APIDOC
## fetch/1

### Description
Callback that fetches data. It returns either fetched data or an error.

### Callback Signature
```
-callback fetch(Args) -> {fetched, Success} | {error, Reason}
                   when Args :: term(), Success :: success(), Reason :: term().
```

### Parameters
- **Args** (term) - Required - Arguments passed to the fetcher.

### Return Values
- **{fetched, Success}** - Indicates a successful fetch with the fetched data.
- **{error, Reason}** - Indicates an error occurred.
```

--------------------------------

### Callback: description/1

Source: https://hexdocs.pm/locus/locus_custom_fetcher.html

Callback that returns a description map for given Args.

```erlang
-callback description(Args) -> description() when Args :: term().
```

--------------------------------

### Type definition: event_load_attempt_started/0

Source: https://hexdocs.pm/locus/locus_custom_fetcher.html

A tuple type wrapping source() with the atom load_attempt_started.

```erlang
-type event_load_attempt_started() :: {load_attempt_started, source()}.
```

--------------------------------

### origin type definition

Source: https://hexdocs.pm/locus/locus_loader.html

Defines the possible origins for database loading.

```erlang
-type origin() ::
          {maxmind, atom()} |
          {http, locus_http_download:url()} |
          {filesystem, locus_filesystem_load:path()} |
          locus:custom_fetcher().
```

--------------------------------

### event_download_dismissed() type definition

Source: https://hexdocs.pm/locus/locus_http_download.html

Defines the event for a dismissed download.

```erlang
-type event_download_dismissed() :: {download_dismissed, full_http_response()}.
```

--------------------------------

### Spec: handle_info/2

Source: https://hexdocs.pm/locus/locus_custom_fetcher.html

Spec for handle_info/2 stopping with unexpected_info and state.

```erlang
-spec handle_info(term(), state()) -> {stop, unexpected_info, state()}.
```

--------------------------------

### validate_opts/1 function specification

Source: https://hexdocs.pm/locus/locus_maxmind_download.html

Validates the provided options for the download process.

```erlang
-spec validate_opts(proplists:proplist()) ->
                       {ok, {[opt()], proplists:proplist()}} | {error, BadOpt :: term()}.
```

--------------------------------

### Spec: code_change/3

Source: https://hexdocs.pm/locus/locus_custom_fetcher.html

Spec for code_change/3 returning ok with state.

```erlang
-spec code_change(term(), state(), term()) -> {ok, state()}.
```

--------------------------------

### event_download_finished() type definition

Source: https://hexdocs.pm/locus/locus_http_download.html

Defines the event for a completed download, including success or error states.

```erlang
-type event_download_finished() ::
          {download_finished, BodySize :: non_neg_integer(), {ok, TrailingHeaders :: headers()}} |
          {download_finished, BodySize :: non_neg_integer(), {error, term()}} |
          {download_finished, BodySize :: non_neg_integer(), {error, timeout}}.
```

--------------------------------

### loader_child_spec(DatabaseId, LoadFrom)

Source: https://hexdocs.pm/locus/locus.html

Like `loader_child_spec/3` but with default options.

```APIDOC
## loader_child_spec(DatabaseId, LoadFrom)

### Description
Like `loader_child_spec/3` but with default options.

### Function Signature
loader_child_spec(DatabaseId, LoadFrom)

### Parameters
- **DatabaseId** (term) - Required - The identifier for the loader.
- **LoadFrom** (term) - Required - The source to load the database from.

### Returns
- **Supervisor.child_spec()** - A supervisor child spec.
```

--------------------------------

### Spec: terminate/2

Source: https://hexdocs.pm/locus/locus_custom_fetcher.html

Spec for terminate/2 returning ok.

```erlang
-spec terminate(term(), state()) -> ok.
```

--------------------------------

### loader_child_spec(ChildId, DatabaseId, LoadFrom, Opts)

Source: https://hexdocs.pm/locus/locus.html

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

```APIDOC
## loader_child_spec(ChildId, DatabaseId, LoadFrom, Opts)

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

### Function Signature
loader_child_spec(ChildId, DatabaseId, LoadFrom, Opts)

### Parameters
- **ChildId** (term) - Required - The child id for the supervisor.
- **DatabaseId** (term) - Required - The identifier for the loader.
- **LoadFrom** (term) - Required - The source to load the database from.
- **Opts** (keyword list) - Required - Options for the loader.

### Returns
- **Supervisor.child_spec()** - A supervisor child spec.
```

--------------------------------

### Spec: handle_continue/2

Source: https://hexdocs.pm/locus/locus_custom_fetcher.html

Spec for handle_continue/2 with fetch atom, returning normal stop and state.

```erlang
-spec handle_continue(fetch, state()) -> {stop, normal, state()}.
```

--------------------------------

### success() type definition

Source: https://hexdocs.pm/locus/locus_maxmind_download.html

Defines the success type for the download operation.

```erlang
-type success() :: locus_http_download:success().
```

--------------------------------

### handle_info/2 function specification

Source: https://hexdocs.pm/locus/locus_loader.html

Handles system messages and other info messages.

```erlang
-spec handle_info(term(), state()) -> {noreply, state()} | {stop, term(), state()}.
```

--------------------------------

### source type definition

Source: https://hexdocs.pm/locus/locus_loader.html

Defines the various sources from which data can be loaded.

```erlang
-type source() ::
          {remote, provider_source()} |
          {remote, locus_http_download:url()} |
          locus_filesystem_load:source() |
          locus_custom_fetcher:source().
```

--------------------------------

### await_loader(DatabaseId, Timeout)

Source: https://hexdocs.pm/locus/locus.html

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

```APIDOC
## await_loader(DatabaseId, Timeout)

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

### Function Signature
await_loader(DatabaseId, Timeout)

### Parameters
- **DatabaseId** (term) - Required - The identifier of the database to await.
- **Timeout** (integer) - Required - The timeout in milliseconds.

### Returns
- **:ok** - When the database is ready.
- **{:error, reason}** - If the timeout is triggered or an error occurs.
```

--------------------------------

### unpack_tree_data_and_data_section(Metadata, TreeAndDataSection)

Source: https://hexdocs.pm/locus/locus_mmdb.html

Unpacks a single TreeAndDataSection binary into separate TreeData and DataSection binaries, leveraging Metadata to calculate the size of TreeData.

```APIDOC
## unpack_tree_data_and_data_section(Metadata, TreeAndDataSection)

### Description
Unpacks a single `TreeAndDataSection` binary into separate `TreeData` and `DataSection` binaries, leveraging `Metadata` to calculate the size of `TreeData`.

### Function Signature
```erlang
-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().
```

### Parameters
- **Metadata** (locus_mmdb_metadata:t()) - Required - The metadata used to calculate the size of the tree data.
- **TreeAndDataSection** (binary()) - Required - The binary containing both tree data and data section.

### Returns
- `{ok, TreeData, DataSection}` - The unpacked tree data and data section binaries.
- `{error, Reason}` - An error occurred. See `failed_to_unpack_tree_data_and_data_section()` type.
```

--------------------------------

### event_download_redirected() type definition

Source: https://hexdocs.pm/locus/locus_http_download.html

Defines the event for a download redirection.

```erlang
-type event_download_redirected() :: {download_redirected, redirection()}.
```

--------------------------------

### event() type definition

Source: https://hexdocs.pm/locus/locus_maxmind_download.html

Defines the event type for the download process, including checksum events.

```erlang
-type event() :: locus_http_download:event() | {checksum, locus_http_download:event()}.
```

--------------------------------

### path() type definition

Source: https://hexdocs.pm/locus/locus_filesystem_store.html

Defines the path type as a filename compatible with file:filename_all().

```erlang
-type path() :: file:filename_all().
```

--------------------------------

### Look up IP address in Elixir with :locus.lookup

Source: https://hexdocs.pm/locus/index.html

Performs a city lookup for an IP address in an IEx session. The result is a map with city details, truncated with ellipsis.

```elixir
iex> :locus.lookup(:city, "93.184.216.34")
{:ok,
 %{
   "city" => %{"geoname_id" => 4945936, "names" => %{"en" => "Norwell"}},
   ...
 }}
```

--------------------------------

### get_info(DatabaseId) - type specification

Source: https://hexdocs.pm/locus/locus.html

Type specification for the get_info function, which returns the properties of a currently loaded database. Returns a success tuple or an error.

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

--------------------------------

### static_child_spec(ChildId, DatabaseId, Origin, Opts)

Source: https://hexdocs.pm/locus/locus_database.html

Returns a static child spec for the database loader.

```APIDOC
## static_child_spec(ChildId, DatabaseId, Origin, Opts)

### Description
Returns a static child spec for the database loader.

### Function Signature
```erlang
-spec static_child_spec(term(), atom(), origin(), [opt()]) -> static_child_spec().
```

### Parameters
- **ChildId** (term()) - Required - Identifier for the child.
- **DatabaseId** (atom()) - Required - Identifier for the database.
- **Origin** (origin()) - Required - Origin of the database.
- **Opts** ([opt()]) - Required - List of options.

### Returns
- **static_child_spec()** - The static child spec.
```

--------------------------------

### await_loader/1 spec

Source: https://hexdocs.pm/locus/locus.html

Specifies the `await_loader/1` function. It waits for a database loader to be ready, with a default timeout of 30 seconds. Returns `{ok, LoadedVersion}` on success, or an error tuple for unknown database, stopped loader, or timeout.

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

```

--------------------------------

### lookup(DatabaseId, Address)

Source: https://hexdocs.pm/locus/locus.html

Looks up info on IPv4 and IPv6 addresses.

```APIDOC
## lookup(DatabaseId, Address)

### Description
Looks up info on IPv4 and IPv6 addresses.

### Function Signature
lookup(DatabaseId, Address)

### Parameters
- **DatabaseId** (term) - Required - The identifier of the database to query.
- **Address** (string) - Required - The IP address to look up.

### Returns
- **{:ok, result}** - The lookup result.
- **{:error, reason}** - If the lookup fails.
```

--------------------------------

### validate(Fun, WalkManager, Journal, Tree)

Source: https://hexdocs.pm/locus/locus_mmdb_tree.html

Validates the tree using the provided function, walk manager, journal, and tree. Returns ok on success.

```APIDOC
## validate(Fun, WalkManager, Journal, Tree)

### Description
Validates the tree using the provided function, walk manager, journal, and tree.

### Function Signature
```erlang
-spec validate(fun((locus_mmdb_data_codec:index()) -> ok | {error, term()}),
               locus_mmdb_tree_walk_manager:handle(),
               locus_mmdb_check_journal:t(),
               t()) ->
                  ok.
```

### Parameters
- **Fun** (fun((locus_mmdb_data_codec:index()) -> ok | {error, term()})) - Required - A function that processes each data index.
- **WalkManager** (locus_mmdb_tree_walk_manager:handle()) - Required - The walk manager handle.
- **Journal** (locus_mmdb_check_journal:t()) - Required - The check journal.
- **Tree** (t()) - Required - The tree to validate.

### Returns
- `ok` - Validation succeeded.
```

--------------------------------

### lookup_address(Address, Database)

Source: https://hexdocs.pm/locus/locus_mmdb.html

Looks up for an entry matching the given address within the database. Returns the entry if found, not_found if no match, or an error tuple.

```APIDOC
## lookup_address(Address, Database)

### Description
Looks up for an entry matching `Address` within `Database`.

### Function Signature
```erlang
-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.
```

### Parameters
- **Address** (inet:ip_address() | string() | unicode:unicode_binary()) - Required - The IP address to look up.
- **Database** (database()) - Required - The database to search.

### Returns
- `{ok, Entry}` - The entry matching the address.
- `not_found` - No entry found.
- `{error, ErrorReason}` - An error occurred. Possible reasons: `database_unknown`, `database_not_loaded`, `{invalid_address, Address}`, `ipv4_database`.
```

--------------------------------

### stop(Id, Reason)

Source: https://hexdocs.pm/locus/locus_database.html

Stops the database loader with the given ID and reason. Returns ok or an error if not found.

```APIDOC
## stop(Id, Reason)

### Description
Stops the database loader with the given ID and reason.

### Function Signature
```erlang
-spec stop(atom(), term()) -> ok | {error, not_found}.
```

### Parameters
- **Id** (atom()) - Required - Identifier for the database loader.
- **Reason** (term()) - Required - Reason for stopping.

### Returns
- **ok** - Success.
- **{error, not_found}** - If the loader is not found.
```

--------------------------------

### database_info type definition

Source: https://hexdocs.pm/locus/locus.html

Defines the `database_info` type as a map with required keys `metadata`, `source`, and `version`.

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

```

--------------------------------

### event type definition

Source: https://hexdocs.pm/locus/locus_loader.html

Defines the various events that can occur during the loading process.

```erlang
-type event() ::
          locus_maxmind_download:event() |
          locus_http_download:event() |
          locus_filesystem_load:event() |
          locus_custom_fetcher:event() |
          event_cache_attempt_finished().
```

--------------------------------

### provider_source type definition

Source: https://hexdocs.pm/locus/locus_loader.html

Defines the source for provider-based databases.

```erlang
-type provider_source() :: {maxmind, atom()}.
```

--------------------------------

### loader_child_spec/2 specification

Source: https://hexdocs.pm/locus/locus.html

Generates a supervisor child specification for a database loader using default options.

```erlang
-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().
```

--------------------------------

### check(DatabaseId)

Source: https://hexdocs.pm/locus/locus.html

Analyzes a loaded database for corruption or incompatibility.

```APIDOC
## check(DatabaseId)

### Description
Analyzes a loaded database for corruption or incompatibility.

### Function Signature
check(DatabaseId)

### Parameters
- **DatabaseId** (term) - Required - The identifier of the database to check.

### Returns
- **:ok** - If the database is valid.
- **{:error, reason}** - If the database is corrupted or incompatible.
```

--------------------------------

### loader_child_spec(DatabaseId, LoadFrom, Opts)

Source: https://hexdocs.pm/locus/locus.html

Like `loader_child_spec/4` but with default child id.

```APIDOC
## loader_child_spec(DatabaseId, LoadFrom, Opts)

### Description
Like `loader_child_spec/4` but with default child id.

### Function Signature
loader_child_spec(DatabaseId, LoadFrom, Opts)

### Parameters
- **DatabaseId** (term) - Required - The identifier for the loader.
- **LoadFrom** (term) - Required - The source to load the database from.
- **Opts** (keyword list) - Required - Options for the loader.

### Returns
- **Supervisor.child_spec()** - A supervisor child spec.
```
Tokens:
Raw