# `TzWorld.Downloader`
[🔗](https://github.com/kipcole9/tz_world/blob/v2.3.0/lib/tz_world/downloader.ex#L1)

Function to support downloading the latest
timezones geo JSON data

# `certificate_locations`

# `current_release`

Returns the current installed timezones geo JSON
data.

# `get`

```elixir
@spec get(String.t() | {String.t(), list()}, options :: Keyword.t()) ::
  {:ok, binary()} | {:not_modified, any()} | {:error, any()}
```

Securely download https content from
a URL.

This function uses the built-in `:httpc`
client but enables certificate verification
which is not enabled by `:httc` by default.

See also https://erlef.github.io/security-wg/secure_coding_and_deployment_hardening/ssl

### Arguments

* `url` is a binary URL or a `{url, list_of_headers}` tuple. If
  provided the headers are a list of `{'header_name', 'header_value'}`
  tuples. Note that the name and value are both charlists, not
  strings.

* `options` is a keyword list of options.

### Options

* `:verify_peer` is a boolean value indicating
  if peer verification should be done for this request.
  The default is `true` in which case the default
  `:ssl` options follow the [erlef guidelines](https://erlef.github.io/security-wg/secure_coding_and_deployment_hardening/ssl)
  noted above.

* `:timeout` is the number of milliseconds available
  for the request to complete. The default is
  "120000". This option may also be
  set with the `CLDR_HTTP_TIMEOUT` environment variable.

* `:connection_timeout` is the number of milliseconds
  available for the a connection to be estabklished to
  the remote host. The default is "60000".
  This option may also be set with the
  `CLDR_HTTP_CONNECTION_TIMEOUT` environment variable.

### Returns

* `{:ok, body}` if the return is successful.

* `{:not_modified, headers}` if the request would result in
  returning the same results as one matching an etag.

* `{:error, error}` if the download is
   unsuccessful. An error will also be logged
   in these cases.

### Unsafe HTTPS

If the environment variable `CLDR_UNSAFE_HTTPS` is
set to anything other than `FALSE`, `false`, `nil`
or `NIL` then no peer verification of certificates
is performed. Setting this variable is not recommended
but may be required is where peer verification for
unidentified reasons. Please [open an issue](https://github.com/elixir-cldr/cldr/issues)
if this occurs.

### Certificate stores

In order to keep dependencies to a minimum,
`get/1` attempts to locate an already installed
certificate store. It will try to locate a
store in the following order which is intended
to satisfy most host systems. The certificate
store is expected to be a path name on the
host system.

```elixir
# A certificate store configured by the
# developer
Application.get_env(:ex_cldr, :cacertfile)

# Populated if hex package `CAStore` is configured
CAStore.file_path()

# Populated if hex package `certfi` is configured
:certifi.cacertfile()

# Debian/Ubuntu/Gentoo etc.
"/etc/ssl/certs/ca-certificates.crt",

# Fedora/RHEL 6
"/etc/pki/tls/certs/ca-bundle.crt",

# OpenSUSE
"/etc/ssl/ca-bundle.pem",

# OpenELEC
"/etc/pki/tls/cacert.pem",

# CentOS/RHEL 7
"/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem",

# Open SSL on MacOS
"/usr/local/etc/openssl/cert.pem",

# MacOS & Alpine Linux
"/etc/ssl/cert.pem"
```

# `get_and_load_latest_release`

# `get_latest_release`

# `get_url`

# `get_with_headers`
*since 2.21.0* 

```elixir
@spec get_with_headers(String.t() | {String.t(), list()}, options :: Keyword.t()) ::
  {:ok, list(), binary()} | {:not_modified, any()} | {:error, any()}
```

Securely download https content from
a URL.

This function uses the built-in `:httpc`
client but enables certificate verification
which is not enabled by `:httc` by default.

See also https://erlef.github.io/security-wg/secure_coding_and_deployment_hardening/ssl

### Arguments

* `url` is a binary URL or a `{url, list_of_headers}` tuple. If
  provided the headers are a list of `{'header_name', 'header_value'}`
  tuples. Note that the name and value are both charlists, not
  strings.

* `options` is a keyword list of options.

### Options

* `:verify_peer` is a boolean value indicating
  if peer verification should be done for this request.
  The default is `true` in which case the default
  `:ssl` options follow the [erlef guidelines](https://erlef.github.io/security-wg/secure_coding_and_deployment_hardening/ssl)
  noted above.

* `:timeout` is the number of milliseconds available
  for the request to complete. The default is
  "120000". This option may also be
  set with the `CLDR_HTTP_TIMEOUT` environment variable.

* `:connection_timeout` is the number of milliseconds
  available for the a connection to be estabklished to
  the remote host. The default is "60000".
  This option may also be set with the
  `CLDR_HTTP_CONNECTION_TIMEOUT` environment variable.

* `:https_proxy` is the URL of an https proxy to be used. The
  default is `nil`.

### Returns

* `{:ok, body, headers}` if the return is successful.

* `{:not_modified, headers}` if the request would result in
  returning the same results as one matching an etag.

* `{:error, error}` if the download is
   unsuccessful. An error will also be logged
   in these cases.

### Unsafe HTTPS

If the environment variable `CLDR_UNSAFE_HTTPS` is
set to anything other than `FALSE`, `false`, `nil`
or `NIL` then no peer verification of certificates
is performed. Setting this variable is not recommended
but may be required is where peer verification for
unidentified reasons. Please [open an issue](https://github.com/elixir-cldr/cldr/issues)
if this occurs.

### Https Proxy

`Cldr.Http.get/2` will look for a proxy URL in the following
locales in the order presented:

* `options[:https_proxy]`
* `ex_cldr` compile-time configuration under the
  key `:ex_cldr[:https_proxy]`
* The environment variable `HTTPS_PROXY`
* The environment variable `https_proxy`

### Certificate stores

In order to keep dependencies to a minimum,
`get/1` attempts to locate an already installed
certificate store. It will try to locate a
store in the following order which is intended
to satisfy most host systems. The certificate
store is expected to be a path name on the
host system.

```elixir
# A certificate store configured by the
# developer
Application.get_env(:ex_cldr, :cacertfile)

# Populated if hex package `CAStore` is configured
CAStore.file_path()

# Populated if hex package `certfi` is configured
:certifi.cacertfile()

# Debian/Ubuntu/Gentoo etc.
"/etc/ssl/certs/ca-certificates.crt",

# Fedora/RHEL 6
"/etc/pki/tls/certs/ca-bundle.crt",

# OpenSUSE
"/etc/ssl/ca-bundle.pem",

# OpenELEC
"/etc/pki/tls/cacert.pem",

# CentOS/RHEL 7
"/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem",

# Open SSL on MacOS
"/usr/local/etc/openssl/cert.pem",

# MacOS & Alpine Linux
"/etc/ssl/cert.pem"
```

# `latest_release`

Return the `{release_number, download_url}` of
the latest timezones geo JSON data

# `otp_version`

# `stream_get_url`

Download `url` and write the response body directly to `path` without
buffering it in memory.

Returns `{:ok, path}` on success, `{:error, reason}` otherwise.

# `update_release`

Updates the timezone geo JSON data if there
is a more recent release.

## Arguments

* `options` is a keyword list of options. The
  default is `[include_oceans: false, force: false]`.

## Options

* `:include_oceans` is a boolean that indicates whether
  to include time zone data for the world's oceans. The
  default is `false`.

* `:force` is a boolean that indicates whether to force
  an update of the data, even if the current data is the
  latest release.  This option is useful when switching
  from the data without oceans to the data with oceans
  (or the other way arouond).

# `update_release`

---

*Consult [api-reference.md](api-reference.md) for complete listing*