-type blob_format() :: tgz | tarball | gzip | gzipped_mmdb | mmdb | unknown.

-type cacher_msg() :: locus_filesystem_store:msg().

-type error_retry_behaviour() ::
          {backoff, milliseconds_interval()} | {exponential_backoff, exponential_backoff_params()}.

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

-type event_cache_attempt_finished() ::
          {cache_attempt_finished, locus_filesystem_store:path(), ok} |
          {cache_attempt_finished, locus_filesystem_store:path(), {error, term()}}.

-type exponential_backoff_params() ::
          #{min_interval := milliseconds_interval(),
            max_interval := milliseconds_interval(),
            growth_base := milliseconds_interval(),
            growth_exponent := number()}.

-type fetcher_msg() ::
          locus_http_download:msg() | locus_filesystem_load:msg() | locus_custom_fetcher:msg().

-type fetcher_opt() :: locus_maxmind_download:opt() | locus_http_download:opt().

-type fetcher_success() ::
          locus_http_download:success() |
          locus_filesystem_load:success() |
          locus_custom_fetcher:success().

-type loader_opt() ::
          {update_period, milliseconds_interval()} |
          {error_retries, error_retry_behaviour()} |
          no_cache |
          {database_cache_file, file:filename_all()}.

-type maxmind_origin_params() :: #{license_key := unicode:unicode_binary(), date => calendar:date()}.

-type milliseconds_interval() :: pos_integer().

-type msg() ::
          {event, event()} |
          {load_success, source(), calendar:datetime(), locus_mmdb:database()} |
          {load_failure, source(), Reason :: term()}.

-type opt() :: loader_opt() | fetcher_opt().

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

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

-type settings() ::
          #settings{update_period :: pos_integer(),
                    error_retry_behaviour :: error_retry_behaviour(),
                    error_retry_behaviour_applies_after_readiness :: boolean(),
                    use_cache :: boolean(),
                    database_cache_file :: file:filename_all() | undefined}.

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

-opaque state()

-type uniformly_distributed_update_period() :: #{min := pos_integer(), max := pos_integer()}.

-type update_period() :: pos_integer() | uniformly_distributed_update_period().