Localize.Locale.Provider.Cache (Localize v1.4.0)

On-disk cache for downloaded locale data files.

This module is responsible for reading and writing locale ETF files under the directory returned by Localize.Locale.Provider.locale_cache_dir/0, and for detecting when a cached file is stale: of another version than Localize.version/0, or not the bytes the release's hash manifest records for it.

Primary API

get/1 — returns cached locale data, or an error tuple if the file is missing or stale.
store/2 — writes locale data to the cache directory.
stale?/1 — checks whether a cached locale file is stale.
path/1 — returns the absolute path for a locale's cache file.

Summary

Types

locale_id()

A locale identifier as an atom.

Functions

get(locale_id)

Retrieves locale data from the cache directory.

path(locale_id)

Returns the absolute cache file path for the given locale.

stale?(locale_id)

Returns whether a cached locale file is stale.

store(locale_id, content)

Stores locale content in the cache directory.

Types

locale_id()

@type locale_id() :: atom()

A locale identifier as an atom.

Functions

get(locale_id)

@spec get(locale_id()) :: {:ok, map()} | {:error, Exception.t()}

Retrieves locale data from the cache directory.

Reads the locale's cache file, decodes it, and validates that its :version field matches Localize.version/0 and that its bytes match the SHA-256 hash the release's manifest records for it.

Arguments

locale_id is a locale identifier atom.

Returns

{:ok, locale_data} if the cache file is present, its version matches the current version and its bytes match the manifest.
{:error, Localize.LocaleIsStaleError.t()} if the cache file is present but its version or its bytes do not match.
{:error, Localize.LocaleNotFoundInCacheError.t()} if the cache file is not present.
{:error, exception} if locale_id is not an atom.

Examples

iex> {:error, error} = Localize.Locale.Provider.Cache.get(:"zz-ZZ")
iex> error.__struct__
Localize.LocaleNotFoundInCacheError

path(locale_id)

@spec path(locale_id()) :: String.t()

Returns the absolute cache file path for the given locale.

Arguments

locale_id is a locale identifier atom.

Returns

A string path to the locale's cache file.

Examples

iex> path = Localize.Locale.Provider.Cache.path(:en)
iex> String.ends_with?(path, "en.etf")
true

stale?(locale_id)

@spec stale?(locale_id()) :: boolean()

Returns whether a cached locale file is stale.

A cache file is considered stale if its :version field does not equal Localize.version/0, or if its bytes do not match the SHA-256 hash the release's manifest records for the locale. A file that is missing, unreadable, or undecodable (corrupt) is also considered stale.

Arguments

locale_id is a locale identifier atom.

Returns

true if the cache file is missing, unreadable, or its version or bytes do not match.
false if the cache file is present, its version matches and its bytes match the manifest.

Examples

iex> Localize.Locale.Provider.Cache.stale?(:"xx-NOPE")
true

store(locale_id, content)

@spec store(locale_id(), binary()) :: {:ok, String.t()} | {:error, Exception.t()}

Stores locale content in the cache directory.

Creates the cache directory if it does not already exist and writes content to the locale's cache file. content should be the raw binary form of the locale ETF file.

Arguments

locale_id is a locale identifier atom.
content is a binary containing the encoded locale data.

Returns

{:ok, path} where path is the absolute path the content was written to.
{:error, Localize.LocaleCacheWriteError.t()} on failure.
{:error, exception} if locale_id is not an atom or content is not a binary.

Examples

A store writes the cache file, so the example shows the answer that writes nothing, for content that is not a binary:

iex> Localize.Locale.Provider.Cache.store(:en, :not_a_binary) |> elem(0)
:error