-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/1 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.

See also: await_loader/2.

-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 default 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.

See also: await_loader/1, await_loaders/2.

-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 it can concurrently await status from more than one database.

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

Returns:

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

See also: await_loader/2.

-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)

-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, database_info()} 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.

See also: get_info/2.

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

See also: get_info/1.

-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/2 but with default options

• DatabaseId must be an atom.
• LoadFrom must be either:
  • a database_edition() 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().

See also: await_loader/1, await_loader/2, loader_child_spec/3, start_loader/2.

-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/3 but with default child id

• DatabaseId must be an atom.
• LoadFrom must be either:
  • a database_edition() 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() values

Returns:

• A supervisor:child_spec().

See also: await_loader/1, await_loader/2, loader_child_spec/2, loader_child_spec/4, start_loader/3.

-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() 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() values

Returns:

• A supervisor:child_spec().

See also: await_loader/1, await_loader/2, loader_child_spec/3, start_loader/3.

-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 an inet:ip_address() 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() 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.

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

See also: await_loader/1, await_loader/2, start_loader/3.

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

See also: await_loader/1, await_loader/2, start_loader/2.

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