# `Astro.Ephemeris.Downloader`
[🔗](https://github.com/kipcole9/astro/blob/v2.4.0/lib/astro/ephemeris/downloader.ex#L1)

Downloads JPL DE-series SPK binary ephemeris files from NASA NAIF.

The default ephemeris file (`de440s.bsp`, ~32 MB) is not bundled with
the hex package. It is downloaded automatically at application start
the first time `Astro` is run, and cached on disk for subsequent runs.

### Cache location

By default the file is cached under the user cache directory as
resolved by `:filename.basedir(:user_cache, "astro")`. If that
directory cannot be created (for example, the OS user has no
writable home directory — a common situation for service accounts
in containers), Astro falls back to `<System.tmp_dir!()>/astro` and
logs a warning. The cache location can be overridden by setting
the `:ephemeris` application environment key:

    config :astro,
      ephemeris: "/path/to/de440s.bsp"

When the configured path already contains a valid ephemeris file no
download is performed. Setting an explicit path is the recommended
approach for production deployments, since the user-cache fallback
to `tmp` is ephemeral.

### Source URL

The default download source is the NASA NAIF generic kernels archive:

    https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/de440s.bsp

This can be overridden by setting the `:ephemeris_url` application
environment key (for example, when mirroring the file inside an
air-gapped environment).

# `download`

```elixir
@spec download(String.t()) :: {:ok, String.t()} | {:error, term()}
```

Downloads the ephemeris file to `path`.

The destination directory is created if it does not already exist.
On HTTP error or network failure the partial file (if any) is removed.

### Arguments

* `path` is the destination file path.

### Returns

* `{:ok, path}` on success.

* `{:error, reason}` if the download failed. `reason` is a tuple
  describing the failure, e.g. `{:http_status, 404}`,
  `{:cache_dir_unwritable, dir, posix_reason}`, or an `:httpc`
  error term.

# `ensure_ephemeris`

```elixir
@spec ensure_ephemeris(String.t()) :: {:ok, String.t()} | {:error, term()}
```

Ensures the ephemeris file is available on disk, downloading it if necessary.

### Arguments

* `path` is the destination file path.

### Returns

* `{:ok, path}` if the file already exists or was downloaded successfully.

* `{:error, reason}` if the file is missing and the download failed.

# `ephemeris_path`

```elixir
@spec ephemeris_path() :: String.t()
```

Returns the resolved ephemeris file path.

Resolution order:

* The `:ephemeris` application environment key, if set.

* `priv/de440s.bsp` if it exists (used during library development
  and when running from a checkout).

* The user cache directory as resolved by
  `:filename.basedir(:user_cache, "astro")`.

* `<System.tmp_dir!()>/astro` if the user cache directory cannot
  be created.

### Returns

* A binary path string.

---

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