RemotePersistentTerm behaviour (RemotePersistentTerm v0.10.0)
View SourceFetch data from a remote source and store it in a persistent_term.
Can be configured to periodically check for updates.
use
this module to define a GenServer that will manage the state of your fetcher and keep your term up to date.
Summary
Callbacks
Deserializes the remote term, before storing it.
Retrieve the currently stored term.
Update the persistent_term.
An optional, overridable callback that is executed during start_link/1
.
Functions
Define a GenServer that will manage this specific persistent_term.
Schedule an update of the persistent_term.
Types
Callbacks
Deserializes the remote term, before storing it.
Overridable.
Commonly the remote term is an ETF encoded binary. In this case you will likely want to override this callback with something like:
def deserialize(binary) do
{:ok, :erlang.binary_to_term(binary)}
rescue
_ ->
{:error, "got invalid ETF"}
end
@callback get() :: term() | nil
Retrieve the currently stored term.
Overridable.
Update the persistent_term.
Overridable.
This is called after deserialize/1
.
An optional, overridable callback that is executed during start_link/1
.
Receives the validated options passed to start_link/1
and can be used to set up
any additional state.
For example, if your term is large and expected to change often, you might want to
consider storing it in a different backend like :ets
.
This can be achieved by overidding setup/1
, put/1
and defining a custom get/1
function
in your module.
Functions
Define a GenServer that will manage this specific persistent_term.
Example:
This will define a GenServer that should be placed in your supervision tree.
The GenServer will check for a new version of s3://my-bucket/my-object
every
12 hours and store it in a persistent_term.
Define the module:
defmodule MyRemotePterm do
use RemotePersistentTerm
end
In your supervision tree:
{MyRemotePterm,
[
fetcher_mod: RemotePersistentTerm.Fetcher.S3,
fetcher_opts: [bucket: "my-bucket", key: "my-object"],
refresh_interval: :timer.hours(12)
]}
Options:
:fetcher_mod
- Required. The implementation of theRemotePersistentTerm.Fetcher
behaviour which should be used. Either one of the built in modules or a custom module. The default value isRemotePersistentTerm.Fetcher.S3
.:fetcher_opts
(keyword/0
) - Configuration options for the chosen fetcher implementation. See your chosen implementation module for details." The default value is[]
.:refresh_interval
- How often the term should be updated in milliseconds. To disable automatic refresh, set the value tonil
. Note: updating persistent_terms can be very expensive. See the docs for more info." The default value isnil
.:lazy_init?
(boolean/0
) - If true, the GenServer will start up immediately and the term will be populated in ahandle_continue/2
. This means that there will be a period while the remote term is being downloaded and no data is available. If this is not acceptable, set this value tofalse
(the default). The default value isfalse
.:alias
(atom/0
) - An alias for this term. A value will be generated based on the module name if no value is provided. Used for Telemetry events.:auto_decompress?
(boolean/0
) - Automatidally decompress the term after downloading it if known magic bytes of a supported format are encountered.Currently only supports gzip (0x1F, 0x8B).
The default value is
true
.
Schedule an update of the persistent_term.