NervesHubLink.Downloader (nerves_hub_link v2.9.0)

Handles downloading files via HTTP.

Several interesting properties about the download are internally cached, such as:

the URI of the request
the total content amounts of bytes of the file being downloaded
the total amount of bytes downloaded at any given time

Using this information, it can restart a download using the Range HTTP header.

This process's only focus is obtaining data reliably. It doesn't have any side effects on the system.

You can configure various options related to how the Downloader handles timeouts, disconnections, and other aspects of the retry logic by adding the following configuration to your application's config file:

config :nerves_hub_link, :retry_config,
  max_disconnects: 20,
  idle_timeout: 75_000,
  max_timeout: 10_800_000

For more information about the configuration options, see the RetryConfig module.

Summary

Types

event_handler_fun()

handler_event()

initialized_download()

option()

options()

resume_rescheduled()

retry_args()

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

start_download(url, fun, opts \\ [])

Begins downloading a file at url handled by fun.

Types

event_handler_fun()

@type event_handler_fun() :: (handler_event() -> any())

handler_event()

@type handler_event() ::
  {:data, data :: binary(), percent_complete :: float()}
  | {:error, any()}
  | :complete

initialized_download()

@type initialized_download() :: %NervesHubLink.Downloader{
  completed: term(),
  conn: Mint.HTTP.t(),
  content_length: non_neg_integer(),
  downloaded_length: non_neg_integer(),
  handler_fun: event_handler_fun(),
  max_timeout: term(),
  request_ref: reference(),
  response_headers: Mint.Types.headers(),
  resume_from_bytes: term(),
  retry_args: term(),
  retry_number: non_neg_integer(),
  retry_timeout: term(),
  status: nil | Mint.Types.status(),
  uri: URI.t(),
  worst_case_timeout: term(),
  worst_case_timeout_remaining_ms: term()
}

option()

@type option() ::
  {:resume_from_bytes, integer()}
  | {:retry_config, NervesHubLink.Downloader.RetryConfig.t()}

options()

@type options() :: [option()]

resume_rescheduled()

@type resume_rescheduled() :: t()

retry_args()

@type retry_args() :: NervesHubLink.Downloader.RetryConfig.t()

t()

@type t() :: %NervesHubLink.Downloader{
  completed: boolean(),
  conn: nil | Mint.HTTP.t(),
  content_length: non_neg_integer(),
  downloaded_length: non_neg_integer(),
  handler_fun: event_handler_fun(),
  max_timeout: timer(),
  request_ref: nil | reference(),
  response_headers: Mint.Types.headers(),
  resume_from_bytes: nil | non_neg_integer(),
  retry_args: retry_args(),
  retry_number: non_neg_integer(),
  retry_timeout: nil | timer(),
  status: nil | Mint.Types.status(),
  uri: nil | URI.t(),
  worst_case_timeout: nil | timer(),
  worst_case_timeout_remaining_ms: nil | non_neg_integer()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

start_download(url, fun, opts \\ [])

@spec start_download(String.t() | URI.t(), event_handler_fun(), [option()]) ::
  GenServer.on_start()

Begins downloading a file at url handled by fun.

Example

  iex> pid = self()
  #PID<0.110.0>
  iex> fun = fn {:data, data, _percent} -> File.write("index.html", data)
  ...> {:error, error} -> IO.puts("error streaming file: #{inspect(error)}")
  ...> :complete -> send pid, :complete
  ...> end
  #Function<44.97283095/1 in :erl_eval.expr/5>
  iex> NervesHubLink.Downloader.start_download("https://httpbin.com/", fun)
  {:ok, #PID<0.111.0>}
  iex> flush()
  :complete