Lightning.Adaptors.Store (Lightning v2.19.0)

View Source

Cached reads over Lightning.Adaptors.Catalogue.

Every read checks the instance's Cachex first and falls back to the catalogue table. Reads never fill the catalogue, so a row with no schema means the source has none and schema/2 answers "{}", while an unknown name returns {:error, :not_found}. icon/3 returns a path on disk, fetching the bytes from the strategy on the first miss. catalogue/1 caches the picker payload already rendered, together with the ETag stamp that describes it.

The first load

Reads never wait for the first load. A read that comes back empty or not-found asks whether the catalogue has ever loaded, and answers {:error, :not_ready} when it has not. An empty answer from a catalogue that has loaded is a real answer and is returned as-is. That includes the empty catalogue a source with no adaptors leaves behind, which the Scheduler reports as loaded despite there being no row to find.

Waiting for the first load is opt-in, through ensure_loaded/2.

Summary

Types

catalogue()
icon_meta()
package_meta()
rendered_entry()

One Lightning.Adaptors.Catalogue.catalogue_entry/0 with its icon fields rendered to URLs, as the catalogue endpoint serves it.

sup()

Functions

catalogue(sup)

Returns the picker catalogue for the active source as {stamp, rendered_entries}.

ensure_loaded(sup, opts \\ [])

Waits until the catalogue has loaded at least once, triggering the first load if needed. :timeout bounds the wait, defaulting to Lightning.Adaptors.Config.first_load_timeout/0.

icon(sup, name, shape)

Returns the on-disk path of one icon shape for the adaptor, or {:error, :not_found} when the adaptor row has no such icon.

icon_meta(sup, name)

Returns the extension and sha256 of each icon shape for the adaptor, without touching disk, or {:error, :not_found} for an unknown name.

packages(sup)

Returns every adaptor for the active source, without the schema_data, dependencies and peer_dependencies columns.

schema(sup, name)

Returns the adaptor's credential schema as a JSON binary, not decoded. An adaptor with no schema yields "{}"; an unknown name {:error, :not_found}.

warm_from_repo(sup)

Overwrites the cached package list, icon metadata and catalogue from the database. An empty catalogue is left uncached, as catalogue/1 does.

Types

catalogue()

@type catalogue() :: {{DateTime.t() | nil, non_neg_integer()}, [rendered_entry()]}

icon_meta()

@type icon_meta() :: %{
  icon_square_ext: String.t() | nil,
  icon_rectangle_ext: String.t() | nil,
  icon_square_sha256: binary() | nil,
  icon_rectangle_sha256: binary() | nil
}

package_meta()

@type package_meta() :: Lightning.Adaptors.Catalogue.package_meta()

rendered_entry()

@type rendered_entry() :: %{
  name: String.t(),
  latest_version: String.t(),
  versions: [String.t()],
  repository: String.t() | nil,
  icon_urls: %{square: String.t() | nil, rectangle: String.t() | nil}
}

One Lightning.Adaptors.Catalogue.catalogue_entry/0 with its icon fields rendered to URLs, as the catalogue endpoint serves it.

sup()

@type sup() :: atom()

Functions

catalogue(sup)

@spec catalogue(sup()) :: {:ok, catalogue()} | {:error, term()}

Returns the picker catalogue for the active source as {stamp, rendered_entries}.

The ETag stamp and the payload it describes are cached as one entry so a 304 can be answered without re-reading the projection, and so the two can never drift apart.

ensure_loaded(sup, opts \\ [])

@spec ensure_loaded(
  sup(),
  keyword()
) :: :ok | {:error, :timeout | :unavailable | :not_ready}

Waits until the catalogue has loaded at least once, triggering the first load if needed. :timeout bounds the wait, defaulting to Lightning.Adaptors.Config.first_load_timeout/0.

Returns :ok, {:error, :timeout} if the load did not finish in time, {:error, :unavailable} if no Scheduler is reachable, or {:error, :not_ready} if the load ran and could neither write a row nor report a complete cycle.

icon(sup, name, shape)

@spec icon(sup(), String.t(), :square | :rectangle) ::
  {:ok, Path.t()} | {:error, :not_found | term()}

Returns the on-disk path of one icon shape for the adaptor, or {:error, :not_found} when the adaptor row has no such icon.

icon_meta(sup, name)

@spec icon_meta(sup(), String.t()) ::
  {:ok, icon_meta()} | {:error, :not_found | :not_ready}

Returns the extension and sha256 of each icon shape for the adaptor, without touching disk, or {:error, :not_found} for an unknown name.

packages(sup)

@spec packages(sup()) :: {:ok, [package_meta()]} | {:error, term()}

Returns every adaptor for the active source, without the schema_data, dependencies and peer_dependencies columns.

schema(sup, name)

@spec schema(sup(), String.t()) :: {:ok, String.t()} | {:error, term()}

Returns the adaptor's credential schema as a JSON binary, not decoded. An adaptor with no schema yields "{}"; an unknown name {:error, :not_found}.

warm_from_repo(sup)

@spec warm_from_repo(sup()) :: :ok

Overwrites the cached package list, icon metadata and catalogue from the database. An empty catalogue is left uncached, as catalogue/1 does.