DurableServer

https://hexdocs.pm/durable_server/0.1.2/
Admin
DurableServer provides durable, distributed GenServer processes backed by pluggable storage that...
Tokens:7,594
Snippets:121
Trust Score:9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Simple init/1 Example

Source: https://hexdocs.pm/durable_server/DurableServer.html

An example of implementing the init/1 callback.

```elixir
def init(state) do
  {:ok, state, permanent: true}
end
```

--------------------------------

### init/2 with Runtime Info Example

Source: https://hexdocs.pm/durable_server/DurableServer.html

An example of implementing the init/2 callback with runtime information.

```elixir
def init(state, info) do
  # Access built-in values
  %{key: key, task_supervisor: task_sup} = info

  # Access user-defined values from supervisor's init_info
  api_client = info.api_client

  {:ok, Map.merge(state, %{task_sup: task_sup, api_client: api_client})}
end
```

--------------------------------

### Advanced Example: Session Manager

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of a DurableServer implementing session management with state migration.

```elixir
defmodule UserSessionServer do
  use DurableServer, vsn: 2

  def dump_state(state), do: Map.take(state, [:user_id, :session, :last_activity_at])

  # migration logic for version 1 -> 2
  def load_state(vsn, dumped_state) do
    case vsn do
      1 ->
        # migrate to v2 logic

      _ ->
        %{ 
          user_id: Map.fetch!(dumped_state, ["user_id"]),
          session: Map.get(dumped_state, "session" || %{},
          last_activity: dumped_state["last_activity_at"],
        }
      end
  end

  def init(%{} = loaded_state) do
    init_state = %{loaded_state | last_activity_at: System.system_time(:millisecond)}
    {:ok, init_state, sync_every_ms: 30_000}
  end

  def handle_call({:update_session, func}, _from, state) do
    %{} = new_session = func.(state.session)
    new_state = %{state | session: new_session, last_activity: System.system_time(:millisecond)}
    {:reply, :ok, new_state}
  end

  def handle_call(:get_session, _from, state) do
    {:reply, state.session, %{state | last_activity: System.system_time(:millisecond)}}
  end

  def handle_call(:logout, _from, state) do
    {:stop, :normal, :ok, %{state | last_activity: System.system_time(:millisecond)}}
  end
end

```

--------------------------------

### Sticky Placement Configuration Example

Source: https://hexdocs.pm/durable_server/DurableServer.html

An example of configuring sticky placement for a DurableServer supervisor, specifying fallback strategies based on environment variables like FLY_MACHINE_ID and FLY_REGION with cumulative delay times.

```Elixir
{DurableServer.Supervisor,
 name: MyDurableSup,
 prefix: "durable/",
 sticky_placement: %{
   MyDatabaseServer => [
     FLY_MACHINE_ID: 10_000,
     FLY_REGION: 20_000,
     any: 0
   ]
 }}
```

--------------------------------

### Monitor all keys with a prefix

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of monitoring all keys that start with a given prefix within a Group.

```elixir
# Monitor all keys with a prefix
:ok = Group.monitor(MyDurableSup, "user/")
```

--------------------------------

### Example implementation of load_state

Source: https://hexdocs.pm/durable_server/DurableServer.html

An example of how to implement the load_state callback to convert state and add ephemeral data.

```Elixir
def load_state(_old_vsn, dumped_state) do
  # Convert string keys to atoms and add ephemeral state
  %{
    count: Map.fetch!(dumped_state, "count"),
    temp_data: nil,
    status: :initialized
  }
end
```

--------------------------------

### DurableServer dump_state callback example

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of implementing the dump_state callback to persist only specific parts of the state.

```elixir
def dump_state(%{count: count, temp_data: _temp} = state) do
  # Only persist count, filter out temp_data
  %{count: count}
end
```

--------------------------------

### Basic Usage

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of defining and using a basic DurableServer for a counter.

```elixir
defmodule MyCounterServer do
  use DurableServer, vsn: 1

  def dump_state(state) do
    %{count: state.count}
  end

  def load_state(_old_vsn, %{"count" => count} = _dumped_state) do
    %{count: count}
  end

  def init(%{count: count} = state) do
    IO.puts("Starting with count #{count}")
    {:ok, Map.merge(state, %{started_at: DateTime.utc_now()}), permanent: true}
  end

  def handle_call(:increment, _from, state) do
    new_state = %{state | count: state.count + 1}
    {:reply, new_state.count, new_state}
  end

  def handle_call(:get_count, _from, state) do
    {:reply, state.count, state}
  end

  def handle_call(:reset, _from, state) do
    {:reply, :ok, %{state | count: 0}}
  end
end

# Start the supervisor first (typically in your application.ex supervision tree):

children = [
  ...,
  {DurableServer.Supervisor, name: MyDurableSup, prefix: "durable/"}
]

# or start directly if you simply want to demo:
{:ok, supervisor_pid} = DurableServer.Supervisor.start_link(
  name: MyDurableSup,
  prefix: "durable/"
)

# Start individual servers through the supervisor
{:ok, {pid, _meta}} = DurableServer.Supervisor.start_child(
  MyDurableSup,
  {MyCounterServer, key: "user_123", initial_state: %{count: 0}}
)

# Use the server
GenServer.call(pid, :increment)  # => 1
GenServer.call(pid, :increment)  # => 2
GenServer.call(pid, :get_count)  # => 2

```

--------------------------------

### Updating Sticky Placement Configuration - Original

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of an original sticky placement configuration before an update.

```elixir
sticky_placement: %{MyServer => [FLY_MACHINE_ID: 60_000, FLY_REGION: 0]}
```

--------------------------------

### Monitor all events

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of monitoring all events within a Group.

```elixir
# Monitor all events
:ok = Group.monitor(MyDurableSup, :all)
```

--------------------------------

### Updating Sticky Placement Configuration - Updated

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of an updated sticky placement configuration, adding an `:any` fallback.

```elixir
sticky_placement: %{MyServer => [FLY_MACHINE_ID: 60_000, FLY_REGION: 120_000, any: 0]}
```

--------------------------------

### Placement Options for start_child

Source: https://hexdocs.pm/durable_server/DurableServer.html

Demonstrates different ways to control remote placement behavior when starting a child process using DurableServer.Supervisor.start_child, including default, local-only, and custom retry counts.

```Elixir
# Default: Try local, then up to 3 remote nodes
DurableServer.Supervisor.start_child(sup, {MyServer, key: "user_1", initial_state: %{}})

# Local only, no remote fallback
DurableServer.Supervisor.start_child(sup, {MyServer, key: "user_1", initial_state: %{}},
  max_placement_retries: 0)

# Try local, then up to 5 remote nodes
DurableServer.Supervisor.start_child(sup, {MyServer, key: "user_1", initial_state: %{}},
  max_placement_retries: 5)
```

--------------------------------

### Accessing init_info in init/2

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of how to access and use custom data passed via :init_info in the init/2 callback of a DurableServer.

```Elixir
def init(state, info) do
  api_client = info.api_client
  timeout = info.config.timeout
  {:ok, %{state | api_client: api_client, timeout: timeout}}
end
```

--------------------------------

### Dispatching to Members

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of dispatching a message to all members of a key.

```elixir
# From a DurableServer, broadcast to all connected channels
Group.dispatch(MyDurableSup, state.key, {:new_message, message})
```

--------------------------------

### Supervisor Configuration with init_info

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of how to configure the DurableServer.Supervisor in a supervision tree, including custom data in :init_info.

```Elixir
    {DurableServer.Supervisor,
     name: MyApp.DurableSup,
     prefix: "myapp/",
     init_info: %{api_client: MyApp.APIClient, config: %{timeout: 5000}}}
```

--------------------------------

### Manual State Synchronization with Options

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of combining manual sync with other actions using callback options.

```Elixir
{:noreply, state, {:continue, term}, sync: true}
```

--------------------------------

### Monitor a specific key

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of monitoring a specific key within a Group.

```elixir
# Monitor a specific key
:ok = Group.monitor(MyDurableSup, "user/123")
```

--------------------------------

### Leave Group

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of leaving a group.

```elixir
:ok = Group.leave(MyDurableSup, "room/123")
```

--------------------------------

### Manual State Synchronization

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of manually synchronizing state by returning :sync from a callback.

```Elixir
{:noreply, state, :sync}
```

--------------------------------

### Join a key to a Group

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of joining a key to a Group, allowing discoverability and message dispatch.

```elixir
# Join a key (e.g., from a Phoenix Channel)
:ok = Group.join(MyDurableSup, "room/123", %{type: :channel})
```

--------------------------------

### Re-joining a key to update metadata

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of re-joining a key to a Group to update its associated metadata.

```elixir
# Re-joining updates metadata in place
:ok = Group.join(MyDurableSup, "room/123", %{type: :channel, status: :active})
```

--------------------------------

### Capacity Limits Configuration

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of configuring capacity limits for a DurableServer supervisor, including total children, module-specific children, CPU, memory, and disk usage.

```Elixir
{DurableServer.Supervisor,
 name: MyDurableSup,
 prefix: "durable/",
 max_children: %{
   :total => 100,                     # Max total children on this node
   MyModule => 50                     # Max MyModule children on this node
 },
 max_cpu: 80,                         # Max CPU % before rejecting
 max_memory: 85,                      # Max memory % before rejecting
 max_disk: {90, "/data"}}             # Max disk % on mount point before rejecting
```

--------------------------------

### Shutdown-wrapped stop: normal

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of a shutdown-wrapped stop reason for a normal stop, where the exit signal propagates.

```Elixir
{:stop, {:shutdown, :normal}, state}
```

--------------------------------

### Query all members of a key

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of querying all members (DurableServers and joined processes) associated with a specific key in a Group.

```elixir
# Query all members of a key (DurableServers + joined processes)
members = Group.members(MyDurableSup, "room/123")
# => [{#PID<0.150.0>, %{...}}, {#PID<0.200.0>, %{type: :channel, status: :active}}]
```

--------------------------------

### Shutdown-wrapped stop: delete

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of a shutdown-wrapped stop reason for deleting from storage, where the exit signal propagates.

```Elixir
{:stop, {:shutdown, :delete}, state}
```

--------------------------------

### child_spec function signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The signature for the child_spec function, used for starting the module under a supervisor.

```Elixir
child_spec(init_arg)
```

--------------------------------

### Non-shutdown stop: normal

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of a non-shutdown stop reason for a normal stop, resulting in silent termination.

```Elixir
{:stop, :normal, state}
```

--------------------------------

### Shutdown-wrapped stop: permanent

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of a shutdown-wrapped stop reason for a permanent stop, where the exit signal propagates.

```Elixir
{:stop, {:shutdown, :permanent}, state}
```

--------------------------------

### Non-shutdown stop: delete

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of a non-shutdown stop reason for deleting, resulting in silent termination.

```Elixir
{:stop, :delete, state}
```

--------------------------------

### Error stop

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of an error stop reason, which marks the server as crashed and propagates the exit signal.

```Elixir
{:stop, {:error, reason}, state}
```

--------------------------------

### Handle Group events in mailbox

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of handling {:group, events, info} tuples received in a process's mailbox, specifically for :registered and :unregistered events.

```elixir
def handle_info({:group, events, _info}, state) do
  Enum.each(events, fn
    %Group.Event{type: :registered, key: key, pid: pid, previous_meta: nil} ->
      # A DurableServer started (previous_meta is nil for first registration)
      :ok
    %Group.Event{type: :unregistered, key: key, reason: reason} ->
      # A DurableServer stopped
      :ok
    _ -> :ok
  end)
  {:noreply, state}
end
```

--------------------------------

### Non-shutdown stop: permanent

Source: https://hexdocs.pm/durable_server/DurableServer.html

Example of a non-shutdown stop reason for a permanent stop, resulting in silent termination.

```Elixir
{:stop, :permanent, state}
```

--------------------------------

### Application Configuration Note

Source: https://hexdocs.pm/durable_server/DurableServer.html

Note for releases regarding the addition of :os_mon to extra_applications in mix.exs.

```elixir
def application do
  [
    mod: {My.Application, []},
    extra_applications: [:logger, :runtime_tools, :os_mon]
  ]
end

```

--------------------------------

### start_link function signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The signature for the start_link function.

```Elixir
start_link(info)
```

--------------------------------

### Custom environment variables for sticky placement

Source: https://hexdocs.pm/durable_server/DurableServer.html

Configures sticky placement using custom environment variables like DATACENTER and AVAILABILITY_ZONE, with a fallback to any node.

```elixir
sticky_placement: %{
  MyServer => [
    DATACENTER: 15_000,
    AVAILABILITY_ZONE: 30_000,
    any: 0
  ]
}
```

--------------------------------

### init/1 Callback Signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The signature for the init/1 callback in DurableServer.

```elixir
@callback init(loaded_state :: map()) ::
  :ignore | {:ok, state :: term()} | {:ok, state :: term(), [init_option()]}
```

--------------------------------

### init/2 Callback Signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The signature for the init/2 callback in DurableServer.

```elixir
@callback init(loaded_state :: map(), info :: map()) ::
  :ignore | {:ok, state :: term()} | {:ok, state :: term(), [init_option()]}
```

--------------------------------

### Machine stickiness with region fallback (no `:any`)

Source: https://hexdocs.pm/durable_server/DurableServer.html

Configures sticky placement where a server tries to stay on the same machine, falling back to the same region if the machine is unavailable. Nodes in other regions can never claim the server.

```elixir
sticky_placement: %{
  MyServer => [
    FLY_MACHINE_ID: 20_000,
    FLY_REGION: 0
  ]
}
```

--------------------------------

### Default Sticky Placement for all modules

Source: https://hexdocs.pm/durable_server/DurableServer.html

Applies a default sticky placement configuration to all modules within a DurableServer supervisor.

```elixir
{DurableServer.Supervisor,
 name: MyDurableSup,
 prefix: "durable/",
 default_sticky_placement: [
   FLY_REGION: 20_000,
   any: 0
 ]}
```

--------------------------------

### Region stickiness, falling back to any node

Source: https://hexdocs.pm/durable_server/DurableServer.html

Configures sticky placement where a server prioritizes the same region, but can fall back to any available node after a delay.

```elixir
sticky_placement: %{
  MyServer => [
    FLY_REGION: 20_000,
    any: 0
  ]
}
```

--------------------------------

### Strict region pinning (no fallback)

Source: https://hexdocs.pm/durable_server/DurableServer.html

Configures sticky placement to strictly pin a server to a specific region, with no fallback. The server will only run on nodes with the matching FLY_REGION.

```elixir
sticky_placement: %{
  MyServer => [
    FLY_REGION: 0
  ]
}
```

--------------------------------

### handle_continue Callback Signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The signature for the handle_continue callback in DurableServer.

```elixir
@callback handle_continue(continue :: term(), state :: term()) ::
  {:noreply, new_state}
  | {:noreply, new_state, timeout_action()}
  | {:noreply, new_state, callback_options()}
  | {:noreply, new_state, timeout_action(), callback_options()}
  | {:stop, reason :: term(), new_state}
  | {:stop, {:shutdown, :delete}, new_state}
  | {:stop, {:shutdown, :permanent}, new_state}
  | {:stop, :delete, new_state}
  | {:stop, :permanent, new_state}
when new_state: term()
```

--------------------------------

### handle_info Callback Signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The signature for the handle_info callback in DurableServer.

```elixir
@callback handle_info(msg :: :timeout | term(), state :: term()) ::
  {:noreply, new_state}
  | {:noreply, new_state, timeout_action()}
  | {:noreply, new_state, callback_options()}
  | {:noreply, new_state, timeout_action(), callback_options()}
  | {:stop, reason :: term(), new_state}
  | {:stop, {:shutdown, :delete}, new_state}
  | {:stop, {:shutdown, :permanent}, new_state}
  | {:stop, :delete, new_state}
  | {:stop, :permanent, new_state}
when new_state: term()
```

--------------------------------

### get_server_metadata function signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The signature for the get_server_metadata function.

```Elixir
get_server_metadata(store, path)
```

--------------------------------

### fetch_stored_state function signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The signature for the fetch_stored_state function.

```Elixir
fetch_stored_state(source, request, opts \\ [])
```

--------------------------------

### clear_restart_attempt function signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The signature for the clear_restart_attempt function.

```Elixir
clear_restart_attempt(store, data)
```

--------------------------------

### fatal_exit! function signature with PID

Source: https://hexdocs.pm/durable_server/DurableServer.html

The signature for the fatal_exit! function when a PID is provided.

```Elixir
fatal_exit!(pid, reason)
```

--------------------------------

### fatal_exit! function signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The signature for the fatal_exit! function.

```Elixir
fatal_exit!(reason)
```

--------------------------------

### handle_call Callback Signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The signature for the handle_call callback in DurableServer.

```elixir
@callback handle_call(request :: term(), from :: GenServer.from(), state :: term()) ::
  {:reply, reply, new_state}
  | {:reply, reply, new_state, timeout_action()}
  | {:reply, reply, new_state, callback_options()}
  | {:reply, reply, new_state, timeout_action(), callback_options()}
  | {:noreply, new_state}
  | {:noreply, new_state, timeout_action()}
  | {:noreply, new_state, callback_options()}
  | {:noreply, new_state, timeout_action(), callback_options()}
  | {:stop, reason, reply, new_state}
  | {:stop, {:shutdown, :delete}, reply, new_state}
  | {:stop, {:shutdown, :permanent}, reply, new_state}
  | {:stop, :delete, reply, new_state}
  | {:stop, :permanent, reply, new_state}
  | {:stop, reason, new_state}
  | {:stop, {:shutdown, :delete}, new_state}
  | {:stop, {:shutdown, :permanent}, new_state}
  | {:stop, :delete, new_state}
  | {:stop, :permanent, new_state}
when reply: term(), new_state: term(), reason: term()
```

--------------------------------

### load_state callback signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The type signature for the load_state callback.

```Elixir
@callback load_state(old_vsn :: pos_integer() | nil, persisted_state :: map()) :: map()
```

--------------------------------

### terminate callback signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The type signature for the terminate callback.

```Elixir
@callback terminate(reason :: term(), state :: term()) :: term()
```

--------------------------------

### handle_cast Callback Signature

Source: https://hexdocs.pm/durable_server/DurableServer.html

The signature for the handle_cast callback in DurableServer.

```elixir
@callback handle_cast(request :: term(), state :: term()) ::
  {:noreply, new_state}
  | {:noreply, new_state, timeout_action()}
  | {:noreply, new_state, callback_options()}
  | {:noreply, new_state, timeout_action(), callback_options()}
  | {:stop, reason :: term(), new_state}
  | {:stop, {:shutdown, :delete}, new_state}
  | {:stop, {:shutdown, :permanent}, new_state}
  | {:stop, :delete, new_state}
  | {:stop, :permanent, new_state}
when new_state: term()
```
Tokens:
Raw