Macaw.Data.Source behaviour (macaw_data v0.13.0)
View SourceThe source contract (spec/01 §2): anything a component's slot reads. One contract
serves feeds, queries, derived sources, state sources and exports. It is a strict
superset of visualize's Visualize.Feed: an existing feed is a source with no
parameters.
A source is a struct whose module implements this behavior:
describe(source, context): what the source is, aMacaw.Data.Source.Description. It takes the host's configuration for the source ascontext, never a viewer, so it is answered at boot and cached by schema version;fetch(source, request): one answer, aMacaw.Data.Delivery, for aMacaw.Data.Source.Request;subscribe(source, pid)andunsubscribe(source, ref), optional, for a source that pushes (spec/01 §4).
Errors are values: every callback answers {:error, reason} rather than raising.
The functions here dispatch to a source's module. fetch/3 checks the request's
parameters against the description's before the call (Macaw.Data.Parameter.validate/2):
a request with a bad parameter never reaches the source, and the source receives every
parameter, defaults filled in.
Summary
Types
A source: a struct whose module implements Macaw.Data.Source.
Callbacks
What the source is, from the host's configuration for it; never a viewer.
One answer for a request.
The source's pushes sent to pid, tagged with the answered reference (spec/01 §4).
A subscription stopped.
Functions
The source's description, {:ok, description} or {:error, reason}. An answer that is
neither is {:error, {:bad_describe, answer}}: a source's fault the caller can show. A
term that is no source, no struct or one whose module has no describe/2, is
{:error, :not_a_source}, which holds nothing of the term: it may hold credentials.
A map of sources by name, with the host's context for each, as the describe function
Macaw.Data.Schema.Cache.resolve/4 takes: a name's present schema,
{:error, :no_source} for a name not in the map, or {:error, :not_a_source} for an
entry that is no {source, context} pair of a source.
One answer for a request, checked first against the description:
{:error, {:params, faults}} without calling the source when a parameter is unknown,
missing or not legal (Macaw.Data.Parameter.validate/2), and {:error, {:order, faults}} when the request's order names a field the schema does not describe, or one
of a type with no order (Macaw.Data.Source.Order.faults/2), and {:error, {:window, faults}} when the request's window or a region field's range is inverted, its from
after its to (Macaw.Data.Window.check/2's {path, {:window, :inverted}},
macaw_data#122). Otherwise the source is called with every parameter, defaults filled
in. An answer that is neither {:ok, delivery} nor {:error, reason} is {:error, {:bad_fetch, answer}}.
The source's pushes sent to pid (spec/01 §4): {:ok, ref}, {:error, :no_push} for a
source whose module does not implement subscribe/2, or {:error, :not_a_source} for a
term that is no source.
A subscription stopped; :ok for a source that does not push, and for a term that is no source.
Types
@type t() :: struct()
A source: a struct whose module implements Macaw.Data.Source.
Callbacks
@callback describe(source :: t(), context :: term()) :: {:ok, Macaw.Data.Source.Description.t()} | {:error, term()}
What the source is, from the host's configuration for it; never a viewer.
@callback fetch(source :: t(), Macaw.Data.Source.Request.t()) :: {:ok, Macaw.Data.Delivery.t()} | {:error, term()}
One answer for a request.
The source's pushes sent to pid, tagged with the answered reference (spec/01 §4).
A subscription stopped.
Functions
@spec describe(t(), term()) :: {:ok, Macaw.Data.Source.Description.t()} | {:error, term()}
The source's description, {:ok, description} or {:error, reason}. An answer that is
neither is {:error, {:bad_describe, answer}}: a source's fault the caller can show. A
term that is no source, no struct or one whose module has no describe/2, is
{:error, :not_a_source}, which holds nothing of the term: it may hold credentials.
@spec describer(%{required(term()) => {t(), term()}}) :: (term() -> {:ok, Macaw.Data.Schema.t()} | {:error, term()})
A map of sources by name, with the host's context for each, as the describe function
Macaw.Data.Schema.Cache.resolve/4 takes: a name's present schema,
{:error, :no_source} for a name not in the map, or {:error, :not_a_source} for an
entry that is no {source, context} pair of a source.
@spec fetch(t(), Macaw.Data.Source.Description.t(), Macaw.Data.Source.Request.t()) :: {:ok, Macaw.Data.Delivery.t()} | {:error, term()}
One answer for a request, checked first against the description:
{:error, {:params, faults}} without calling the source when a parameter is unknown,
missing or not legal (Macaw.Data.Parameter.validate/2), and {:error, {:order, faults}} when the request's order names a field the schema does not describe, or one
of a type with no order (Macaw.Data.Source.Order.faults/2), and {:error, {:window, faults}} when the request's window or a region field's range is inverted, its from
after its to (Macaw.Data.Window.check/2's {path, {:window, :inverted}},
macaw_data#122). Otherwise the source is called with every parameter, defaults filled
in. An answer that is neither {:ok, delivery} nor {:error, reason} is {:error, {:bad_fetch, answer}}.
The source's pushes sent to pid (spec/01 §4): {:ok, ref}, {:error, :no_push} for a
source whose module does not implement subscribe/2, or {:error, :not_a_source} for a
term that is no source.
A subscription stopped; :ok for a source that does not push, and for a term that is no source.