Astro.Ephemeris.Downloader (Astro v2.2.1)

Copy Markdown View Source

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

Summary

Functions

download(path)

Downloads the ephemeris file to path.

ensure_ephemeris(path)

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

ephemeris_path()

Returns the resolved ephemeris file path.

Functions

download(path)

@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(path)

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

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