Forem: Pulkit Goyal

Managing Distributed State with GenServers in Phoenix and Elixir

Pulkit Goyal — Tue, 12 Nov 2024 14:11:08 +0000

Phoenix and Elixir are designed at their core to build real-time, fault-tolerant applications. With its elegant syntax and the robustness of the Erlang VM, Elixir is an ideal candidate for tackling the challenges of distributed state management.

This two-part series will guide Phoenix/Elixir developers through the intricacies of working with Phoenix in a distributed setup.

The focus of this first post will be on GenServers — the key components behind state management in distributed systems. We will explore how GenServers can be leveraged to maintain state across nodes in a Phoenix application, ensuring data consistency and fault tolerance. We’ll break down the complexities of GenServers and distributed state management into manageable and understandable segments.

Overview of Our Phoenix Application

Let's focus on distributed state management in the context of a CRUD API. Imagine you have a popular API service built with Phoenix that handles a large number of requests from various clients. To prevent abuse and ensure fair usage, you want to implement a rate limiter that restricts the number of requests a client can make within a specific timeframe, such as 100 requests per minute.

You can implement this simply using the "token bucket" strategy. In this strategy, a bucket is maintained for each client that is filled with tokens at a constant rate. Each API call consumes a single token from the bucket and is blocked if there are no tokens available.

In the next section, we will set up a token bucket for a single-node scenario using a GenServer.

A Single-Node Rate Limiter Implementation Using GenServer for Elixir

GenServers are a cornerstone within the Elixir ecosystem for managing state and encapsulating functionality. They are the go-to structure for maintaining state within an application because they can hold state throughout their lifecycle and be interacted with asynchronously.

defmodule MyApp.TokenBucketRateLimiter do
  use GenServer

  # tokens per second
  @rate 1
  # maximum tokens in the bucket
  @bucket_size 10

  def start_link([]), do: GenServer.start_link(__MODULE__, nil, name: __MODULE__)

  @impl true
  def init(nil), do: {:ok, %{buckets: %{}}}

  def allow?(client_id) do
    GenServer.call(__MODULE__, {:allow?, client_id})
  end

  @impl true
  def handle_call({:allow?, client_id}, _from, state) do
    current_time = System.monotonic_time(:second)
    {reply, updated_bucket} =
      state.buckets
      |> get_or_init_bucket(client_id)
      |> update_bucket(current_time)
      |> maybe_consume_token(current_time)

    state = put_in(state, [:buckets, client_id], updated_bucket)
    {:reply, reply, state}
  end

  defp maybe_consume_token(%{tokens: tokens} = bucket, current_time)
       when tokens >= 1 do
    updated_bucket = %{bucket | tokens: tokens - 1, last_checked: current_time}
    {true, updated_bucket}
  end

  defp maybe_consume_token(bucket, _current_time), do: {false, bucket}

  defp get_or_init_bucket(buckets, client_id) do
    Map.get(buckets, client_id, %{
      tokens: @bucket_size,
      last_checked: current_time
    })
  end

  defp update_bucket(bucket, current_time) do
    # Add tokens based on the last time the bucket was checked
    time_passed = current_time - bucket.last_checked
    new_tokens = time_passed * @rate
    updated_tokens = min(bucket.tokens + new_tokens, @bucket_size)
    %{bucket | tokens: updated_tokens, last_checked: current_time}
  end
end

This works well in a single-node setup because the GenServer holds the token state for the entire application across web requests. We can add it to the application's supervision tree to start the API rate limiter automatically:

defmodule MyApp.Application do
  use Application

  @impl true
  def start(_type, _args) do
    children = [
      # Other Children...
      MyApp.TokenBucketRateLimiter
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end

  # ...
end

The first time allow? is called with a new client ID, it initializes the bucket to 10 tokens, and then each allow? with the same client ID consumes one token per request. Eventually, the eleventh request in the same second is rejected because there are no more tokens. If the client tries again after a while, the requests are allowed again.

iex> 1..11 |> Enum.map(fn _i -> MyApp.TokenBucketRateLimiter.allow?("some client id") end)
[true, true, true, true, true, true, true, true, true, true, false]

iex> Process.sleep(1000)
:ok
iex> MyApp.TokenBucketRateLimiter.allow?("some client id")
true

But as the app scales and we deploy it across multiple nodes (e.g., in a Kubernetes cluster or across different regions), we face the challenge of coordinating rate limiting across all nodes.

Each node needs to be aware of the request counts from other nodes to enforce the rate limit consistently. Without a distributed solution, each node would only track requests it directly handles, leading to inconsistent rate limiting.

You might think that maintaining request limits in memory is not feasible at a scale that requires multiple nodes. But since each client's state is just a single integer for the token size and a single integer for the timestamp, this doesn't require a large amount of memory (2 * 64 bytes per client). Even if there are 100k concurrent clients, less than 15MB of in-memory state is required.

Understanding GenServers in a Distributed Elixir Environment

Distributed systems pose unique challenges, particularly when it comes to state management. Network partitions, node failures, and latency are just a few issues that can disrupt state consistency across nodes. Ensuring that all nodes have the correct state or can recover it when things go wrong is critical for a system's reliability.

GenServers can be distributed across nodes in a cluster, allowing them to share state and handle requests from different parts of a system. By leveraging the built-in distribution mechanisms of the BEAM VM, GenServers can communicate across nodes with the same ease as within a single node.

In the next section, we will use some strategies to support rate limiting across multiple nodes in the cluster.

Implementing Distributed GenServers Using a Single Global Process

The simplest strategy to support a rate limiter across a whole cluster is to start a single global process that manages the limits.
This is simple to do using Erlang's :global name registration.

In the single node setup above, we register the GenServer under the name MyApp.TokenBucketRateLimiter (__MODULE__ contains the name of the current module). This registers the process locally on the node. It is also possible to register it globally using a {:global, name} tuple when calling GenServer.start_link/3.
This registers the process under the given name globally across the whole cluster. Note that since we update the process name in start_link, we also have to update it when using any call, cast, and friends.

Let's update the code to do this:

defmodule MyApp.TokenBucketRateLimiter do
  def start_link([]) do
    GenServer.start_link(__MODULE__, nil, name: {:global, __MODULE__})
  end

  def allow?(client_id) do
    GenServer.call({:global, __MODULE__}, {:allow?, client_id})
  end
end

This enforces that only a single process with the global name MyApp.TokenBucketRateLimiter can exist across the cluster. However, this is insufficient, as it will prevent all other application nodes from joining our cluster because the supervision tree cannot start all its processes. Let's try it out by starting a few nodes in the cluster.

The first node starts fine:

   ➜ iex --name node1@127.0.0.1 --cookie asdf -S mix
   iex(node1@127.0.0.1)1>

But as soon as we start a second node and connect it to the cluster, the application crashes:

   ➜ iex --name node2@127.0.0.1 --cookie asdf -S mix
   iex(node2@127.0.0.1)1> Node.connect(:"node1@127.0.0.1")
   [notice] Application my_app exited: shutdown

We need to make sure that the start_link function of the rate limiter doesn't generate any errors when a process already exists on another node. To do this, we can check and modify the start_link function to return :ignore when the process already exists:

def start_link([]) do
  tuple = {:global, __MODULE__}

  case GenServer.whereis(tuple) do
    nil -> GenServer.start_link(__MODULE__, nil, name: tuple)
    _pid -> :ignore
  end
end

Once that's done, we can start multiple nodes in the cluster, and they will all ping a central rate limiter instance to allow or deny incoming requests. The central rate limiter will be the GenServer process that happens to start first, i.e., the first node in the cluster to come up.

While this works, there are several issues with this approach:

The node is a single point of failure now. If the node goes down, the rate limiter will be unreachable until another node starts it. Even worse, this is not handled automatically, so we might be left with no rate limiter process unless a new node is started.
The state is on a single node. This means that if the rate limiter process is terminated/restarted (either due to a programming error or node failure), the state is lost.
All nodes in the cluster have to make a call to the single node on every API call.

Using Multiple Processes Across the Cluster

In order to provide better fault tolerance when managing state across distributed nodes, we can use a combination of techniques, including:

State partitioning: Dividing the state into partitions so that each GenServer instance handles a subset of the data.
Replication: Replicating state across nodes to provide redundancy and increase fault tolerance.
Conflict resolution: Implementing strategies to handle state conflicts, such as using version vectors or CRDTs (Conflict-free Replicated Data Types).

Let's see how we can use CRDTs to provide super-fast data access alongside eventual consistency and data replication guarantees.

We will use the Elixir library DeltaCrdt to manage shared state across multiple nodes in the cluster.

Note: In addition to DeltaCrdt, other libraries like Horde and Swarm can help you to coordinate processes and state across several nodes in the cluster.

Let's add it to mix.exs to get started:

defmodule MyApp.MixProject do
  defp deps do
    [
      # ...
      {:delta_crdt, "~> 0.6.3"}
    ]
  end
end

DeltaCrdt provides a simple-to-use API for managing a map of data that is guaranteed to be conflict-free (across distributed usage) and replicated across multiple nodes. For conflict resolution, it provides AWLWWMap (that stands for 'Add-Wins Last-Write-Wins Map) so that in the case of a conflict, the last write always wins.

The API is simple — you start multiple DeltaCrdt processes (which can be on the same node or multiple nodes) and create a cluster with them using set_neighbours/2:

{:ok, crdt1} = DeltaCrdt.start_link(DeltaCrdt.AWLWWMap)
{:ok, crdt2} = DeltaCrdt.start_link(DeltaCrdt.AWLWWMap)
DeltaCrdt.set_neighbours(crdt1, [crdt2])
DeltaCrdt.read(crdt1)
%{}

Once neighbours are set, adding any data to one CRDT automatically syncs with the second one.

DeltaCrdt.put(crdt1, "foo", "bar")
DeltaCrdt.read(crdt2)
%{"foo" => "bar"}

Starting A One Rate Limiter Per Node

With this out of the way, we can update our implementation of the rate limiter to use DeltaCrdt to sync states. First, we need to make sure all rate limiter processes are discoverable globally, but with unique names. One way to do that is to use the node name when naming the process:

defmodule MyApp.TokenBucketRateLimiter do
  use GenServer

  def start_link([]), do: GenServer.start_link(__MODULE__, nil, name: global_tuple())

  defp global_tuple(node \\ Node.self()), do: {:global, to_string(node) <> to_string(__MODULE__)}
end

Syncing GenServer State With CRDT

Now that all nodes start their own copy of the rate limiter, we need to sync the state. Let's do that by starting a DeltaCrdt process from the GenServer and using the CRDT to make decisions about the rate limits:

defmodule MyApp.TokenBucketRateLimiter do
  use GenServer

  @impl true
  def init(nil) do
    {:ok, crdt} = DeltaCrdt.start_link(DeltaCrdt.AWLWWMap, sync_interval: 100)

    {:ok, %{crdt: crdt}}
  end

  def allow?(client_id), do: GenServer.call(global_tuple(), {:allow?, client_id})

  @impl true
  def handle_call({:allow?, client_id}, _from, state) do
    current_time = System.os_time(:second)

    {reply, updated_bucket} =
      state.crdt
      |> get_or_init_bucket(client_id, current_time)
      |> update_bucket(current_time)
      |> maybe_consume_token(current_time)

    # Update the CRDT with the new bucket state
    DeltaCrdt.put(state.crdt, client_id, updated_bucket)

    {:reply, reply, state}
  end

  defp get_or_init_bucket(crdt, client_id, current_time) do
    case DeltaCrdt.get(crdt, client_id) do
      nil -> default_bucket(current_time)
      bucket -> bucket
    end
  end

  defp default_bucket(time), do: %{tokens: @bucket_size, last_checked: time}
end

The major changes here from the single-node approach are:

Instead of Map.get from the local GenServer state, we use DeltaCrdt.get to get the key from the CRDT instead. This fetches the data from the local copy of the CRDT which is very fast to access and guarantees eventual consistency.
Similar to the above, we use DeltaCrdt.put to update the shared state instead of the local GenServer state when updating the tokens count. This is again a fast operation that updates the local state — but with a guarantee that the changes will be eventually synced with all processes in the cluster.

Clustering the GenServers

While we are almost there, there is one last step left. The CRDTs are currently local and do not sync with other nodes in the GenServer. We need to use the set_neighbours/2 API from DeltaCRDT to set up a sync.

Let's create a new function named update_neighbours inside the GenServer that does this:

defp update_neighbours(crdt) do
  neighbours =
    Node.list()
    |> Enum.map(fn node ->
      node
      |> global_tuple()
      |> GenServer.whereis()
      |> :sys.get_state()
      |> Map.get(:crdt)
    end)

  DeltaCrdt.set_neighbours(crdt, neighbours)
end

Now all we need to do is call this function when the GenServer starts (from init or a handle_continue callback).

The above piece of code takes care of updating CRDT neighbors when a new process starts. But set_neighbours is a one-sided operation (i.e., it sets up puts from the CRDT to its neighbors, but not the other way around). To ensure servers that have already started also update their neighbors, we must call update_neighbours on all cluster processes as soon as any service starts.

Let's add a new refresh_peer_neighbours function to do that (which should then be called after the initialization of the GenServer).

defp refresh_peer_neighbours() do
  Node.list()
  |> Enum.each(fn node ->
    node
    |> global_tuple()
    |> GenServer.whereis()
    |> Process.send(pid, :refresh_neighbours, [])
  end)
end

@impl true
def handle_info(:refresh_neighbours, state) do
  update_neighbours(state.crdt)
  {:noreply, state}
end

Handling Cluster Changes

With all this in place, there is still one final piece of the puzzle. What happens when nodes are added or removed from the cluster? To update the CRDT neighborhood on cluster-level changes, we can use :net_kernel.monitor_nodes(true) from Erlang. This monitors the nodes and refreshes the neighbors on any nodeup or nodedown events:

@impl true
def init(nil) do
  {:ok, crdt} = DeltaCrdt.start_link(DeltaCrdt.AWLWWMap, sync_interval: 100)

  # Monitor for addition of new nodes
  :net_kernel.monitor_nodes(true)

  {:ok, %{crdt: crdt}, {:continue, nil}}
end

@impl true
def handle_info({:nodeup, _node}, state) do
  Process.send_after(self(), :refresh_neighbours, 1_000)
  {:noreply, state}
end

def handle_info({:nodedown, _node}, state) do
  Process.send_after(self(), :refresh_neighbours, 1_000)
  {:noreply, state}
end

This finally brings us to the end of our implementation. There are some edge cases to consider:

Avoiding deadlocks when refreshing neighbours (since we need to fetch the PID of the CRDTs from all nodes).
Handling cases where the RateLimiter does not exist on a node (e.g., when it is being restarted).

Here is the full implementation. Let's take it for a spin:

# Node 1
➜ iex --name node1@127.0.0.1 --cookie asdf -S mix
iex(node1@127.0.0.1)1>

# Node2
➜ iex --name node2@127.0.0.1 --cookie asdf -S mix
iex(node2@127.0.0.1)1> Node.connect(:"node1@127.0.0.1")
true
iex(node2@127.0.0.1)2> MyApp.TokenBucketRateLimiter.allow?("some client id")
true
iex(node2@127.0.0.1)3> MyApp.TokenBucketRateLimiter.crdt() |> DeltaCrdt.get("some client id")
%{tokens: 9, last_checked: 1725358705}

# Back on Node1
iex(node1@127.0.0.1)1> MyApp.TokenBucketRateLimiter.crdt() |> DeltaCrdt.get("some client id")
%{tokens: 9, last_checked: 1725358705}

And that's it for part one of this series!

Wrapping Up

In this first part of our Distributed Phoenix series, we've taken an in-depth look at how GenServers and Delta CRDTs can be leveraged to manage distributed state in a Phoenix application. We've implemented a token bucket rate limiter across multiple nodes, ensuring consistency and fault tolerance even in a distributed setup.

This foundational knowledge is crucial for building scalable, resilient systems that can handle high traffic and maintain data integrity across multiple servers.

In part two, we'll dive deeper into advanced techniques for optimizing distributed systems, including strategies for deploying and scaling distributed applications.

Stay tuned for more insights and practical examples that will help you master the art of distributed applications with Phoenix and Elixir.

P.S. If you'd like to read Elixir Alchemy posts as soon as they get off the press, subscribe to our Elixir Alchemy newsletter and never miss a single post!

LiveState for Elixir: An Overview and How to Build Embeddable Web Apps

Pulkit Goyal — Tue, 03 Sep 2024 13:52:49 +0000

If you have programmed with Phoenix, you already know what a delight it can be to work with LiveView. LiveView simplifies your development process by moving all state management to the server. This reduces the complexity of coordinating states between the client and server.

LiveState aims to extend a LiveView-like development flow to embeddable web apps. But before we delve deeper into LiveState, let’s first understand what embeddable web apps are.

Embeddable Web Apps

Embeddable web apps are applications designed to be embedded within another website. These apps are typically small and focus on a specific feature.

Examples include:

A comments section on a blog post
A contact form on an otherwise static website
A chat bubble or support widget

LiveState brings the ease and efficiency of the LiveView workflow to the development of these embeddable web apps.

What is LiveState for Elixir?

LiveState is a framework that simplifies creating embeddable web applications by maintaining a server's state.

This has several benefits:

Centralized State Management: You can avoid the complexities of synchronizing state between the client and server.
Real-time Updates: LiveState enables real-time updates, ensuring that users always see the most current data without needing to refresh the page.
Reduced Client Complexity: Client-side code can remain simple and lightweight.
Enhanced Security: Sensitive data is less exposed to potential security threats on the client side.

As we will see later in this post, building robust and dynamic embeddable web apps using LiveState is straightforward. With minimal effort, you can leverage the power and simplicity of server-side state management.

More Use Cases

In addition to embeddable web apps, LiveState excels in another important area: highly interactive client components. These components can even exist within a traditional LiveView app, where certain parts of the application are managed using LiveState alongside client-side JavaScript frameworks like React, SolidJS, or LitComponents.

Within a traditional LiveView app, some sections might require more interactivity and a richer client-side experience. LiveState can manage these highly interactive parts using client-side frameworks like React, SolidJS, or LitComponents, while still leveraging the server-side state management benefits of LiveView.

Choosing Between LiveView and LiveState

When deciding whether to use LiveView or LiveState, consider the following:

LiveView: Best suited for applications where most of the interactivity and state management can be handled on the server. This simplifies the client-side code and leverages the power of Elixir and Phoenix to manage state and interactivity efficiently.
LiveState: Ideal for scenarios requiring embeddable features or highly interactive client-side components. If parts of your app need to be embedded in other websites or require rich interactivity that benefits from JavaScript frameworks, LiveState offers a flexible and powerful solution.

Example: Creating An Embeddable Phoenix Web App

Let’s see how LiveState works in practice by integrating it into a Phoenix app to create an embeddable web app. We'll build a LiveState component to manage a to-do list.

We'll also build a Phoenix channel backend and use LitElement for our front-end component. The front-end component will mostly be plumbing — we'll use LiveState to manage the state and events on the Phoenix backend, similar to LiveView.

Step 1: Add Dependencies

First, add the necessary dependencies to your mix.exs file:

defmodule TodoApp.MixProject do
  use Mix.Project

  defp deps do
    [
      # ...
      {:live_state, "~> 0.8.1"},
      {:cors_plug, "~> 3.0"}
    ]
  end
end

Step 2: Update Your Endpoint

Next, update your Endpoint to set up a socket for the channel:

defmodule TodoAppWeb.Endpoint do
  use Phoenix.Endpoint, otp_app: :todo_app

  socket "/socket", TodoAppWeb.LiveStateSocket
end

Step 3: Create the `Phoenix.Socket`

Then create the Phoenix.Socket:

defmodule TodoAppWeb.LiveStateSocket do
  use Phoenix.Socket

  channel "todos:*", TodoAppWeb.TodosChannel
  @impl true
  def connect(_params, socket), do: {:ok, socket}

  @impl true
  def id(_), do: "todos:*"
end

This is a standard Phoenix Socket. If you have worked with channels before, you may already be familiar with how this works. For new users, the channel macro defines a channel matching a given topic.

Note that we use simple implementations for the connect and id callbacks that allow all connections. This keeps the guide straightforward, but in a real-world app, you would likely modify them to accept only authenticated users.

Step 4: Define the Channel

Now, let's define the channel.
This will be the core of our backend, which will be responsible for maintaining the server-side state and handling events dispatched from the client side. It functions similarly to a Phoenix.LiveView in a traditional setup.

defmodule TodoAppWeb.TodosChannel do
  use LiveState.Channel, web_module: TodoAppWeb

  alias LiveState.Event

  @impl true
  def init(_channel, _payload, _socket) do
    {:ok, %{todos: list_todos()}}
  end

  defp list_todos() do
    Todos.list_todos()
    |> Enum.map(&todo/1)
  end

  defp todo(%Todos.Todo{} = todo), do: Map.take(todo, [:id, :title, :completed])
end

This is the most basic setup for the channel. Let's break it down.

A new channel is initialized as soon as a client connects to the WebSocket and subscribes to the todos:* topic. In the init callback, we add all existing todos to the current state, making this state available to the client side.

We will expand on this module later. First, let's look at the final part of our setup: the client component.

Build the Front-End Component with `LitElement`

We'll use LitElement, so navigate to the assets directory and install lit and phx-live-state.

# assets
$ npm install lit phx-live-state --save

If you are new to LitElement and custom HTML elements, now is a good time to review the basic concepts.

Next, create a new custom element to render the todos inside assets/js:

// assets/js/modules/todos/TodoListElement.ts
import { html, LitElement } from "lit";
import { customElement, property, state } from "lit/decorators.js";
import LiveState, { connectElement } from "phx-live-state";

type Todo = {
  id: number;
  title: string;
  completed: boolean;
};

@customElement("todo-list")
export class TodoListElement extends LitElement {
  @property({ type: String })
  url: string = "";

  @state()
  todos: Array<Todo> = [];

  connectedCallback() {
    super.connectedCallback();
    const liveState = new LiveState({
      url: this.url,
      topic: `todos:${window.location.href}`,
    });

    connectElement(liveState, this, {
      properties: ["todos"],
    });
  }

  render() {
    return html`
      <ul style="list-style-type: none">
        ${this.todos?.map(
          (todo) => html`
            <li>
              <input
                type="checkbox"
                id=${`todo-${todo.id}`}
                ?checked=${todo.completed}
              />
              <label for=${`todo-${todo.id}`}>${todo.title}</label>
            </li>
          `
        )}
      </ul>
    `;
  }
}

Let's break this down.

TodoListElement Component

First, we define a new LitElement component named TodoListElement using the @customElement decorator. This component is responsible for fetching and displaying a list of todos.

@property: The url property specifies the endpoint for fetching todos.

@state: The todos array holds the list of to-dos fetched from the server.

LiveState Integration

In the connectedCallback method, we set up LiveState to synchronize our component's state with the server.

LiveState is configured with the specified URL and a topic derived from the current page's URL. Using the page's URL is just an example; it can be utilized on the server side to separate to-dos based on the page the component is embedded on.

The connectElement function links the todos state in our component with the LiveState instance, ensuring real-time updates.

There are additional options available with connectElement that we will discuss later.

Rendering the To-do List

The render method generates the HTML structure for our to-do list, displaying each to-do item with a checkbox and label.

Now you can include this component inside your app's JavaScript file (assets/js/app.js):

import "./modules/todos/TodoListElement";

This will make the component available for use. Since we configured it as a custom HTML element, it's simple to use on a page. You can just use the todo-list element and pass a URL (configured as a property) to it.

<todo-list url="ws://127.0.0.1:4000/socket"></todo-list>

If you already have some to-dos, you should now start seeing them on the page.

Adding New To-dos

Next, let's add a way to create new to-dos.

First, we'll update the client to create new to-dos. Modify the connectedCallback to send an add_todo event and receive the todo_created event from the server.

connectedCallback() {
  // ...
  connectElement(liveState, this, {
    properties: ['todos'],
    events: {
      send: ['add_todo'],
      receive: ['todo_created']
    }
  });
}

Then update the render method to include a form that will send the add_todo event to the server:

render() {
  return html`
    <ul style="list-style-type: none">
      ${this.todos?.map(todo => html`
        <li>
          <input type="checkbox" id=${`todo-${todo.id}`} ?checked=${todo.completed}>
          <label for=${`todo-${todo.id}`}>${todo.title}</label>
        </li>
      `)}
    </ul>
    <div>
      <form @submit=${this.addTodo}>
        <div>
          <label for="todo">Todo</label>
          <input id="todo" name="title" required>
        </div>
        <button>Add Todo</button>
      </form>
    </div>
  `;
}

Notice that we referenced the addTodo method in the form's @submit callback.
Let's add that method as well:

@query('input[name="title"]')
titleInput: HTMLInputElement | undefined;

addTodo(e: Event) {
  this.dispatchEvent(new CustomEvent('add_todo', {
    detail: {
      title: this.titleInput?.value
    }
  }));
  e.preventDefault();
}

The implementation is straightforward. We need to get the value of the title input and dispatch an event. The event name should match what we configured to send inside the connectElement call.

We used another directive, @query, from LitElement to query the title input. This is a convenient method to find the element matching a selector.

Server-Side Handling

On the server side, we need to handle the add_todo event to create a new to-do and update the state. Let's go back to the TodosChannel and add this functionality.

defmodule TodoAppWeb.TodosChannel do
  alias LiveState.Event

  @impl true
  def handle_event("add_todo", todo_params, %{todos: todos}) do
    case Todos.create_todo(todo_params) do
      {:ok, t} ->
        data = todo(t)
        {:reply, [%Event{name: "todo_created", detail: data}], %{todos: todos ++ [data]}}
    end
  end
end

LiveState calls the handle_event callback when events are dispatched from the client. The event's detail is passed from the client as the second argument to the handle_event callback, while the third argument is the existing channel state, which contains the current to-dos.

In our implementation, we simply create a new to-do and send a :reply back to the client. If no reply is needed for certain events, you can return a {:noreply, state} tuple instead.

In the reply, we send a new LiveState.Event and update the state to include the newly created to-do.

When you run the example again, you will notice that you can now add new to-dos using the form, and they will appear on the list.

You can add more events to toggle to-dos, but we won't go into those in this post. If you're interested, check out the full code sample.

Bundle Embed Script

If you have been following closely, you'll notice that we integrated a component directly into a Phoenix app. In a typical Phoenix app, there's usually no need to do this if the component is simple enough, as you can create views using LiveView.

The purpose of this example was to create a script that someone can embed on any website to get access to the <todo-list> element. Creating the embeddable script from here is straightforward. There are various ways to do this depending on your app's configuration. We'll walk through it using esbuild, which Phoenix configures by default for new apps.

First, create a new entry point for our embeddable component that only imports the TodoListElement:

// app/js/modules/todos/index.ts
import "./TodoListElement";

Next, configure esbuild to generate a new JavaScript file from this entry point. Update config/config.exs:

config :esbuild,
  version: "0.17.11",
  # this is the default entrypoint that phoenix generates
  todo_app: [
    args:
      ~w(js/app.js --bundle --target=es2017 --outdir=../priv/static/assets --external:/fonts/* --external:/images/*),
    cd: Path.expand("../assets", __DIR__),
    env: %{"NODE_PATH" => Path.expand("../deps", __DIR__)}
  ],
  # add a new config that bundles only the modules/todos/index.ts file
  todos: [
    args:
      ~w(js/modules/todos/index.ts --bundle --target=es2017 --outdir=../priv/static/assets --external:/fonts/* --external:/images/*),
    cd: Path.expand("../assets", __DIR__),
    env: %{"NODE_PATH" => Path.expand("../deps", __DIR__)}
  ]

If you want the embeddable JavaScript to be generated during development, update config/dev.exs to add a new watcher:

config :todo_app, TodoAppWeb.Endpoint,
  # other endpoint config
  watchers: [
    # ...
    # the default watched generated by phoenix
    esbuild: {Esbuild, :install_and_run, [:todo_app, ~w(--sourcemap=inline --watch)]},
    # a new watcher that just watches the todo element (matches the `todos` from config.exs)
    esbuild_todos: {Esbuild, :install_and_run, [:todos, ~w(--sourcemap=inline --watch)]}
  ]

Restart your server, and you should see a new JavaScript file generated inside priv/static/assets. If you embed this component on an external website, include the new JS file and add the <todo-element> as a regular HTML element.

Integrating With JS Frameworks

We've seen an example of integrating LiveState with LitElement, but this is not a requirement. You can also use vanilla JavaScript, adding the phx-live-state package to directly dispatch and listen to events on the LiveState instance without using connectElement.

To use React, the author of LiveState provides a use-live-state hook that simplifies the integration process.

Using this hook, you can efficiently manage the state and events of your to-do list within a React component. This makes it easy to synchronize the client-side state with the server in real time.

export function TodoList() {
  const [state, pushEvent] = useLiveState(liveState, {});
  return (
    <ul style="list-style-type: none">
      ${state.todos?.map((todo) => (
        <li key={todo.id}>
          <input type="checkbox" id={`todo-${todo.id}`} checked={todo.completed}>
          <label for={`todo-${todo.id}`}>{todo.title}</label>
        </li>
      ))}
    </ul>
  );
};

And that's it for now!

Wrapping Up

LiveState brings the simplicity and power of LiveView to embeddable web apps and highly interactive client components.

By maintaining server state, LiveState ensures centralized state management, real-time updates, reduced client complexity, and enhanced security.

It is especially useful if parts of your Elixir application need to be embedded in other websites or require rich interactivity with JavaScript frameworks.

Happy coding!

P.S. If you'd like to read Elixir Alchemy posts as soon as they get off the press, subscribe to our Elixir Alchemy newsletter and never miss a single post!

How to Use Flume in your Elixir Application

Pulkit Goyal — Tue, 16 Apr 2024 14:33:32 +0000

As your Elixir app grows, you might need advanced control over how and where to perform background tasks or pull them off queues to manage back pressure.

In this post, you will learn how to handle background jobs with Flume, a job processing system that uses GenStage and Redis. It provides durability, back pressure, job scheduling, rate limiting, and batch processing, among other things.

We will expand on each of these features in detail.

But before we go further, let's quickly cover two other major libraries in the same space: Oban and Exq.

Oban and Exq: Flume Alternatives for your Elixir App

Both Oban and Exq serve as excellent alternatives to Flume.

Oban, backed by PostgreSQL or SQLite, also provides a queue-based job processing system.
Exq, on the other hand, is backed by Redis. It provides features similar to Flume, but without built-in rate limiting and batch processing capabilities.

Opt for Oban if you don't want to maintain a Redis instance to manage background jobs (Postgres typically performs adequately unless faced with queues exceeding 100k jobs or more) and do not require rate limiting.

Select Exq when you need a highly efficient queuing backend for processing a substantial volume of jobs, but can forgo advanced features such as rate limiting and batch processing.

If you need all three features (a queuing backend, rate limiting, and batch processing), Flume emerges as the ideal choice.

A small word of warning: If you have experience with Rails, you are likely familiar with Sidekiq, Resque, and Delayed Job for background job processing. But note that Elixir/Erlang already has excellent alternatives built into the language in the form of GenServer, Task, and Supervisor, and an additional background job processing system that adds more infrastructure costs and complexity might not be necessary.

A background job processing system like Flume becomes crucial when you need to manage numerous background tasks, track their progress/status (or at least automatically retry them on failure), or apply common constraints (like queue, priority, or rate limit) to many similar jobs.

Keeping all of that in mind, let's set up Flume for our Elixir app.

Installation and Setting Up

To install Flume in your app, simply add the dependency in your mix.exs file and run mix deps.get:

def deps do
  [
    {:flume, github: "scripbox/flume"}
  ]
end

Next, add Flume to your application’s supervision tree by modifying your application.ex file:

defmodule MyApp.Application do
  use Application

  import Supervisor.Spec

  @impl true
  def start(_type, _args) do
    Supervisor.start_link([
      # ...
      # Start Flume supervisor
      supervisor(Flume, []),
      #...
    ], strategy: :one_for_one, name: MyApp.Supervisor)
  end
end

Finally, configure it inside config/config.exs:

config :flume,
  name: Flume,
  # Redis config
  host: "127.0.0.1",
  port: "6379",
  namespace: "my-app",
  database: 0,
  redis_pool_size: 10

There are some other configuration options as well, but we will get to them later in the post. For now, this is all you need to get things set up and start creating background jobs.
Let's create one now:

defmodule MyApp.OrdersWorker do
  def process(order_id) do
    # process the order
  end
end

To initiate a job, we execute Flume.enqueue/4, specifying a queue name, a module name, a function within that module, and an array of arguments to invoke that function:

Flume.enqueue(:default, MyApp.OrdersWorker, :process, [order_id])

This takes care of serializing the arguments and adds the job to Redis. To actually run the job, we need to define a pipeline that picks off the jobs from Redis. We'll see how to do that in the next section.

Pipelines in Flume for Elixir

Pipelines define when and how the actual job processing happens in Flume. We can define pipelines in config/config.exs when configuring Flume:

config :flume, pipelines: [%{name: "default_pipeline", queue: "default"}]

This directs Flume to commence processing jobs from the queue named default, with a maximum of 500 jobs (by default) running simultaneously. Consequently, Flume will initiate up to 500 concurrent processes/tasks, each executing a single job. The max_demand parameter regulates this behavior. If your jobs are inherently resource-intensive, you can specify a lower number to constrain the quantity of workers:

config :flume, pipelines: [%{name: "default_pipeline", queue: "default", max_demand: 10}]

In addition to the queue, there are more configuration options for advanced pipeline control.

Rate Limiting

We can specify rate limits for a pipeline by configuring it like this:

config :flume, pipelines: [%{
  name: "default_pipeline",
  queue: "default",
  rate_limit_count: 100,
  rate_limit_scale: 60 * 1000
}]

This will ensure that the default pipeline processes at most 100 jobs (rate limit count) per minute (rate limit scale of 60 * 1000 milliseconds). It is also possible to share the same rate limit across multiple pipelines by specifying the optional rate_limit_key when defining the pipeline.

For example, if you have two pipelines that process notifications using the same rate-limited API, you can share the limit across both of them like this:

config :flume, pipelines: [
  %{
    name: "email_pipeline",
    queue: "email",
    rate_limit_count: 100,
    rate_limit_scale: 60 * 1000
    rate_limit_key: "notifications"
  },
  %{
    name: "sms_pipeline",
    queue: "sms",
    rate_limit_count: 100,
    rate_limit_scale: 60 * 1000
    rate_limit_key: "notifications"
  }
]

Now, both of these pipelines will process a total of (at most) 100 jobs per minute.

Don't confuse this with the max_demand parameter, which governs how many "concurrent" jobs can execute simultaneously.
Even with a low max demand, it's entirely possible to rapidly process too many jobs if they tend to be short-lived. Rate limiting operates on a time scale level to ensure that the number of executions does not surpass a specified limit within a given time interval.

Batching

It's also useful to define a batch size with a pipeline:

config :flume, pipelines: [%{
  name: "default_pipeline",
  queue: "default",
  max_demand: 10,
  batch_size: 5,
}]

This will instruct Flume to send up to 5 jobs to the same worker (and start up to 10 workers at the same time).

When using batching, each worker will receive an array of all arguments:

defmodule MyApp.OrdersWorker do
  def process(jobs) do
    # jobs contains up to 5 arrays containing arguments for each individual call:
    # [[order1_id], [order2_id], [order3_id], [order4_id], [order5_id]]
  end
end

The application code determines how to manage these jobs.
For instance, in the case of a mailer job, the process/1 function could utilize a bulk email API to send emails to multiple recipients in a single call, rather than making five separate calls to a standard API.

Runtime Control

It is also possible to pause pipelines at runtime using Flume.pause_all/1 or Flume.pause/2.

To pause all pipelines permanently (across all running nodes), run:

Flume.pause_all(temporary: false, async: true)

If you only want to pause a single pipeline, use Flume.pause with the pipeline's name. It accepts the same options as pause_all:

Flume.pause("default_pipeline", temporary: false, async: true)

It is also possible to pause a pipeline/all pipelines on a single node instead of on all nodes. This can be controlled using the temporary parameter. So, to pause a pipeline on only the current node, run:

Flume.pause("default_pipeline", temporary: true, async: true)

Similar to pause and pause_all, you can run resume or resume_all to restart the pipelines.

Pausing a pipeline can be advantageous in scenarios where you need to temporarily suspend job processing to address issues or perform maintenance tasks. For example, during system upgrades or when debugging critical issues, pausing a pipeline can prevent new jobs from being processed, thereby enabling you to stabilize the system.

Another useful scenario is to manage known service downtimes.
For instance, if your job depends on an external service that is known to be unavailable, you can pause the pipeline until the service resumes normal operation.

Advanced Features in Flume

Flume comes with an exponential back-off for failed jobs (jobs that raise an exception) by default. The default configuration is set to retry a failed job with exponential back-offs starting at 500 milliseconds with a maximum back-off of 10 seconds. A job is retried at most 5 times. This can be controlled using:

config :flume,
  backoff_initial: 30_000,
  backoff_max: 36_00_000,
  max_retries: 10

There are several other configuration options to fine-tune Flume further. Please refer to the Flume guide for more details.

Flume uses :telemetry to emit events/metrics.
By default, the emitted events are:

A [:pipeline_name, :worker, :job] event with the duration (in milliseconds) representing the time taken to execute the job. This is the time that your Worker.perform function takes.
A [:pipeline_name, :worker] event with the duration (in milliseconds) representing the time taken to run the job. This includes the total time taken to decode the event payload and execute the job.
A [:queue_name, :enqueue] event with the serialized job's payload_size (in bytes).
A [:queue_name, :dequeue] event with the count (number of jobs fetched), latency (in milliseconds — time taken to fetch the jobs from Redis), and payload_size (in bytes) after Flume fetches jobs from Redis.

If you are already using AppSignal, you can use something like TelemetryMetricsAppsignal to collect these metrics, report them to AppSignal, and get custom dashboards.

Running Flume On Production

All the usage examples we have seen up to now run Flume on the same server as the web server. While this is good for a development workflow or small production workloads, you might consider moving workers to a separate node for scalability. This can be achieved by configuring Flume pipelines based on environment variables.

To control this, we can create a module that helps parse the environment variable:

defmodule MyApp.FlumeConfigurator do
  @default_pipelines %{
    "default_pipeline" => %{name: "default_pipeline", queue: "default"},
    "notifications_pipeline" => %{
      name: "notifications_pipeline",
      queue: "notifications",
      rate_limit_count: 100,
      rate_limit_scale: 60 * 1000
    },
    "video_transcoding_pipeline" => %{name: "video_transcoding_pipeline", queue: "video_transcoding", max_demand: 5}
  }

  def flume_pipelines() do
    pipelines(System.get_env("FLUME_PIPELINES"))
  end

  defp pipelines(nil), do: []

  defp pipelines(value) when is_binary(value) do
    value
    |> String.split(",", trim: true)
    |> Enum.map(fn name -> Map.fetch!(@default_pipelines, name) end)
  end
end

And then configure Flume pipelines inside runtime.exs/release.exs:

import MyApp.FlumeConfigurator, only: [flume_pipelines: 0]
config :flume, pipelines: flume_pipelines()

That way, if you start your released application without defining FLUME_PIPELINES, Flume will not start any pipelines, but you can still enqueue jobs from your application. Then you can start other workers with FLUME_PIPELINES so that all pipelines kick in:

FLUME_PIPELINES=default_pipeline,notifications_pipeline,video_transcoding_pipeline /path/to/release start

You might want to stop the web server on worker-only nodes: you can control that from the runtime.exs/release.exs file with an environment variable.

Note that this is automatically generated if you use the mix phx.gen.release task to prepare your Phoenix app for release:

if System.get_env("PHX_SERVER") do
  config :pug_n_play_platform, PugNPlayPlatformWeb.Endpoint, server: true
end

Best Practices

When enqueueing background jobs with Flume, all the job arguments are serialized and deserialized, and all the job data needs to make a round trip to the Redis server. This means that it is important to keep the payload of the jobs as low as possible. For example, if you have something that persists in a database, instead of passing the full struct, just pass the ID and retrieve it from the database when performing the job.

Another important thing to keep in mind when running jobs is that they should be idempotent. Jobs can run multiple times in cases of failure, so ensure that a job that runs twice doesn't unnecessarily affect your application or its data (or disable retries).

Wrapping Up

In summary, Flume brings efficiency to background job processing in Elixir applications. Its easy installation, configurable pipelines, and advanced features like rate limiting and telemetry make it a valuable tool for scalable and fault-tolerant systems. Embracing best practices, such as minimizing payload and ensuring idempotency, enhances the effectiveness of your background jobs.

With Flume, you not only leverage Elixir's concurrency and fault tolerance but also gain a powerful ally for managing and optimizing your application's background tasks.

Happy coding!

P.S. If you'd like to read Elixir Alchemy posts as soon as they get off the press, subscribe to our Elixir Alchemy newsletter and never miss a single post!

Keep Your Ruby Code Maintainable with Money-Rails

Pulkit Goyal — Wed, 13 Dec 2023 15:43:52 +0000

When working with money in an application, ensuring everything is accounted for is important.

In this post, we will explore some common methods and best practices of handling money in your Ruby app, and see how you can use money-rails to write maintainable money-handling code.

Let's get started!

Use Cases for Storing Money

There are several use cases where your Ruby app might need to handle money — for example, an e-commerce company that sells products, a SaaS maintaining users' subscriptions, etc.

In this post, we will walk through some examples of how to handle money in an e-commerce app.

Storing Money in a Ruby Database

First, let’s start with strategies for storing money in your database: using a float column, the numeric type, and the integer type.

Using a Float Column

The most obvious way to store money is to use a float column. However, because of the way floating-point numbers are stored, they do not guarantee exactness. Instead, they only approximate the actual value. While this might be sufficient for some applications, there are much better ways to store money.

Using the `numeric` Type

The numeric type can store arbitrary-precision numbers in a database.

A numeric column can store a large range of numbers (up to 131,072 digits before a decimal point and up to 16,383 digits after a decimal point) and is therefore perfectly suited to work with money.

But one important point to note here is that calculations on numeric types are very slow compared to integer/floating-point numbers.

Numeric types should be the go-to data type when you need arbitrary-precision numbers, but, depending on business logic, they are rarely needed unless it's for very specific use cases. Let’s see if we can do better in an e-commerce scenario.

Using the `integer` Type

We need to store the prices of products, with the lowest unit being cents. A product can be priced at $19.99 but never $19.9954321. This means that, instead of working at the dollar level, we will always have an integer value as the price at the cents level. We can easily store an integer without any approximation in the database using one of the integer types (e.g., smallint, integer, bigint).

But please note that this does constrain the represented values (as compared to the numeric type) — the maximum integer value on Postgres 2147483647 will be $21,474,836.47. This should normally be enough for any e-commerce product, but it’s good to know that there’s a limit. If you require higher precision (for example, a 10th of a cent), this is possible by just storing the amount as a mill instead of cents. Keep in mind that this will further decrease the range of values that can be represented in an integer column.

But an integer's big advantage over a numeric type is that calculations are very fast. As long as you can work within the integer (or bigint) range and have clear constraints set, using an integer/bigint is the recommended storage option.

Sorting out storage is just the first step to representing money in our Ruby application, though. You might also need to handle different currencies, formatting the values based on the location of users (e.g., USD is formatted as $1,234.56, whereas the same amount in Euros is formatted as €1.234,56).

While it is possible to implement this manually, a gem like money-rails can handle it out of the box for you.

Enter `money-rails` for Ruby on Rails

Money-Rails integrates the money gem in Rails. It can handle automatic conversion between the database representation of money to Money instances. These instances can then be used to access all helpers available from the money gem (we will get to an overview of those helpers later in this post).

Additionally, money-rails also has helpers for migrations and configurable validation options. Let’s start by creating a product with a price. We'll use the monetize helper to do that:

# db/migrate/20230803062226_create_products.rb
class CreateProducts < ActiveRecord::Migration[7.0]
  def change
    create_table :products do |t|
      t.string :title, null: false
      t.monetize :price, null: false

      t.timestamps
    end
  end
end

t.monetize :price adds price_cents and price_currency columns to the table. In addition to this, we need to mark the price_cents column that money-rails will control in the model.

# app/models/product.rb
class Product < ApplicationRecord
  monetize :price_cents
end

With just a few lines, we now have access to a lot of helpers.
We can create a new product by simply passing a price attribute. The price will automatically be converted to a cent value for the database. When accessing the price later, we will have instances of Money.

irb> product = Product.new(title: "Foo", price: 19.99)
# => #<Product:0x0000000108ff9e30 id: nil, title: "Foo", price_cents: 1999, price_currency: "USD", created_at: nil, updated_at: nil>

irb> product.price
# => #<Money fractional:1999 currency:USD>

You can also pass the attributes directly:

irb> product = Product.new(title: "Foo", price_cents: 1999, price_currency: "EUR")
# => #<Product:0x0000000108ff2130 id: nil, title: "Foo", price_cents: 1999, price_currency: "EUR", created_at: nil, updated_at: nil>

irb> product.price.format
# => "€19,99"

Currency in the `money` Gem for Ruby

Currencies are consistently represented as instances of Money::Currency. This not only includes the name of the currency, but a lot of additional information like the name, symbol, iso code, etc.:

irb(main):042:0> product.price.currency
# => #<Money::Currency id: usd, priority: 1, symbol_first: true, thousands_separator: ,, html_entity: $, decimal_mark: ., name: United States Dollar, symbol: $, subunit_to_unit: 100, exponent: 2, iso_code: USD, iso_numeric: 840, subunit: Cent, smallest_denomination: 1, format: >

Check out the money gem's currency documentation.

Let's say you only have a single currency in your application and don’t need to track currency inside your database. First, set a default currency for money in an initializer:

# config/initializers/money.rb
MoneyRails.configure do |config|
  # set the default currency
  config.default_currency = :usd
end

In the migration, disable the currency column:

# db/migrate/20230803062226_create_products.rb
class CreateProducts < ActiveRecord::Migration[7.0]
  def change
    create_table :products do |t|
      t.string :title, null: false
      t.monetize :price, null: false, currency: { present: false }

      t.timestamps
    end
  end
end

There are many other Money-Rails migration helpers that allow null values for amounts or configure default amounts/currencies.

Validations with `monetize`

You can configure validations on money using the monetize Active Record helper. To do this, update your model to opt in for validations:

class Product < ApplicationRecord
  monetize :price_cents,
           numericality: {
             greater_than_or_equal_to: 0,
             less_than_or_equal_to: 1000
           }
end

Now, if you try to save a product with an invalid price, validation will fail:

irb> product = Product.new(title: "Foo", price: -10)
irb> product.save!
# => raise_validation_error: Validation failed: Price must be greater than or equal to 0 (ActiveRecord::RecordInvalid)

irb> product.errors
# => #<ActiveModel::Errors [#<ActiveModel::Error attribute=price, type=greater_than_or_equal_to, options={:allow_nil=>nil, :value=>-10, :count=>0}>]>

Localization

Money can be configured to either use the location information provided by i18n or to localize based on the amount’s currency. Use the locale_backend to configure this — usually in an initializer like this:

# config/initializers/money.rb
Money.locale_backend = :currency

In the above example, we set it to :currency. This uses the formatting rules defined for each currency:

irb> product = Product.new(title: "Foo", price_cents: 15_999_00, price_currency: "USD")
irb> product.price.format
# => "$15,999.00"

irb> product.price_currency = "EUR"
irb> product.price.format
# => "€15.999,00"

To configure a consistently formatted amount regardless of the amount’s currency, use the :i18n locale backend:

irb> Money.locale_backend = :i18n
irb> I18n.locale = :en

irb> Product.new(title: "Foo", price_cents: 15_999_00, price_currency: "USD").price.format
# => "$15,999.00"
irb> Product.new(title: "Foo", price_cents: 15_999_00, price_currency: "EUR").price.format
# => "€15,999.00"

When using the locale backend i18n, it is also possible to configure the formatting using the translation files:

# config/locale/en.yml
en:
  number:
    currency:
      format:
        delimiter: ","
        format: "%u%n"
        precision: 2
        separator: "."
        significant: false
        strip_insignificant_zeros: false
        unit: "$"

Note that if you are using rails-i18n, configuration is automatically available for many locales.

Computations

Money instances are usable as regular numerical values with all operators, so you can compare values and perform arithmetic operations (using +, -, *, /). This makes it much more intuitive to perform operations on objects containing money.

# Comparisons - both value and currency must be equal for equality
irb> p1 = Product.new(price_cents: 1000, price_currency: "USD")
irb> p2 = Product.new(price_cents: 1000, price_currency: "USD")
irb> p1.price == p2.price
# => true

Since mathematical operators work as expected, you can easily compute sum/average or price discounts.

# Compute invoice total by summing all line item amounts
irb> item = LineItem.new(amount_cents: 1000, amount_currency: "USD")
irb> discount = LineItem.new(amount_cents: -250, amount_currency: "USD")
irb> total = item.amount + discount.amount
# => #<Money fractional:750 currency:USD>

# Find the average price of a product
irb> average = Product.sum(&:price) / Product.count
# => #<Money fractional:1000 currency:USD>

If you need to access the underlying value from a Money instance, you can do that using amount or cents:

irb> Product.new(price_cents: 1000, price_currency: "USD").amount
# => BigDecimal(10)

irb> Product.new(price_cents: 1000, price_currency: "USD").cents
# => 1000 (Integer)

Currency Exchange

If you are working with multiple currencies, you can automatically convert two different currencies based on exchange rates using exchange rate stores.

The default implementation is just an in-memory store. It stores the exchange rates you provide using Money.add_rate.

To use it, first add a rate. Then, you can use the exchange_to method to convert a money object to another currency.

irb> Money.add_rate("USD", "EUR", 0.92)
irb> Product.new(price_cents: 1000, price_currency: "USD").price.exchange_to("EUR")
# => #<Money fractional:920 currency:EUR>

If a conversion rate is not present, it raises a Money::Bank::UnknownRate exception.

irb> Product.new(price_cents: 1000, price_currency: "USD").price.exchange_to("EUR")
# => No conversion rate known for 'USD' -> 'INR' (Money::Bank::UnknownRate)

So, if you are using this in production, you must provide the exchange rate before you perform any conversions.

You can provide a custom exchange rate store to handle this automatically. There are also some exchange rate implementations already available as gems.
For example, you can drop in the eu_central_bank exchange rate store to fetch the latest exchange rates from the European Central Bank.

Once the gem is installed, you can set it as the default bank in the initializer:

# config/initializers/money.rb
require 'eu_central_bank'
eu_bank = EuCentralBank.new
Money.default_bank = eu_bank

# Update rates from the EU Central Bank
# Ideally this should be performed periodically in a cron job.
# If you need conversions rarely, you can call it before using exchange_to.
eu_bank.update_rates

Once set up, you can simply exchange any currency, and it should work:

irb> Product.new(price_cents: 1000, price_currency: "USD").price.exchange_to("EUR")
# => Money.from_cents(92, "EUR")

Wrap Up

In this post, we saw how to store and work with money in a Rails application.

Money-Rails greatly simplifies the whole process and provides helper methods that make working with money safer and more maintainable in the long run.

Many other options are available to customize this for your Ruby on Rails app. Check out the full details in the money and money-rails guides.

Happy coding!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

An Introduction to Exceptions in Elixir

Pulkit Goyal — Tue, 03 Oct 2023 11:00:00 +0000

Exceptions are a core aspect of programming, and a way to signal when something goes wrong with a program. An exception could result from a simple error, or your program might crash because of underlying constraints. Exceptions are not necessarily bad, though — they are fundamental to any working application.

Let’s see what our options are for handling exceptions in Elixir.

Raising Exceptions in Elixir

The Elixir (and Erlang) community is generally quite amenable to exceptions: “let it crash” is a common phrase. This is due, in part, to the excellent OTP primitives in Erlang/Elixir. The OTP primitives allow us to create supervisors that manage and restart processes (or a group of related processes) on failure.

Exceptions can occur when something unexpected happens in your Elixir application. For example, division by zero raises an ArithmeticError.

iex> 1 / 0
** (ArithmeticError) bad argument in arithmetic expression: 1 / 0
    :erlang./(1, 0)
    iex:1: (file)

Exceptions can also be raised manually:

iex> raise "BOOM"
** (RuntimeError) BOOM
    iex:1: (file)

By default, raise creates a RuntimeError. You can also raise other errors by using raise/2:

defmodule Math do
  def div(a, b) do
    if b == 0, do: raise ArgumentError, message: "cannot divide by zero"
    a / b
  end
end

iex> Math.div(1, 0)
** (ArgumentError) cannot divide by zero
    iex:4: Math.div/2
    iex:3: (file)

A function call that doesn’t match a defined function raises an ArgumentError by default:

defmodule Math do
  def div(a, b) when b != 0 do
    a / b
  end
end

iex> Math.div(1, 0)
** (FunctionClauseError) no function clause matching in Math.div/2

    The following arguments were given to Math.div/2:

        # 1
        1

        # 2
        0

Handling Elixir Exceptions

Elixir provides the try-rescue construct to handle exceptions:

try do
  raise "foo"
rescue
  e in RuntimeError -> IO.inspect(e)
end

This prints %RuntimeError{message: "foo"} in the console but doesn’t crash anything. Use this when you want to recover from exceptions in Elixir. It is also possible to skip binding the variable if it is unnecessary. For example:

try do
  raise "foo"
rescue
  RuntimeError -> IO.puts("something bad happened")
end

In both of the above examples, we only rescue RuntimeError. If there is another error, it will still raise an exception. To rescue all exceptions raised inside the try block, use the rescue without an error type, like this:

try do
  1 / 0
rescue
  e -> IO.inspect(e)
end

Running the above prints %ArithmeticError{message: "bad argument in arithmetic expression"}. If you want to perform different actions based on different exceptions, just add more clauses to the rescue branch.

try do
  1 / 0
rescue
  RuntimeError -> IO.puts("Runtime Error")
  ArithmeticError -> IO.puts("Arithmetic Error")
  _e -> IO.puts("Unknown error")
end

While rescuing all errors (without using a specific type) sounds tempting, it is a good practice to rely on specific exceptions because:

You can perform different recovery tasks for different exceptions.
It saves you from future breaking changes or programming errors going unnoticed.

For example, consider the below function:

defmodule Config do
  def get(file) do
    try do
      contents = File.read!(file)
      parse!(contents)
    rescue
      _e -> %{some: "default config"}
    end
  end
end

It reads and parses a config file, returning the result. When written, it uses a generic clause to rescue from missing file-related errors. Let’s say that a while later, the input file gets corrupted somehow (e.g., a simple missing } or an extra , in a JSON file), and now there are parsing errors. Our function will still work without raising any issues, and we will be left guessing why it doesn’t work even though there’s an existing file.

Another common practice in the Elixir community is to use ok/error tuples to signal errors instead of raising exceptions (for both internal and external libraries). So, instead of returning a simple result or raising an exception on an issue, a function in Elixir will return {:ok, result} on success and {:error, reason} on failure.

This means that most of the time, a case block will be preferable to try/rescue. For example, the above File.read! can be replaced by:

case File.read(file) do
  {:ok, contents} -> parse!(contents)
  {:error, reason} -> %{some: "default config"}
end

In practice, you should reach out for try/raise only in exceptional cases, never as a means of control flow. This is quite different from some other popular languages like Ruby or Java, where unexpected operations usually raise an error, then handle control flow for cases like non-existent files.

Re-raising Exceptions

Sometimes, we just want to know that there is an exception but not rescue from it — for example, to log an exception before allowing the process to crash or to wrap the exception into something more useful/understandable to the user.

This is where reraise can be helpful, as it preserves an exception's existing stack trace:

try do
  1 / 0
rescue
  e ->
    IO.puts(Exception.format(:error, e, __STACKTRACE__))
    reraise e, __STACKTRACE__
end

Here, we use the __STACKTRACE__ to retrieve the original trace of the exception, including its origin and the full call stack.

In a real-world application, you might use this to report a metric / send an exception to a third-party exception tracking service, or log something informative to a third-party logging service. For example, you might send telemetry data to AppSignal under these circumstances.

In addition, it is also common practice to have custom exceptions for cases where unexpected things happen in libraries. reraise/3 can be useful here:

defmodule DivisionByZeroError do
  defexception [:message]
end

defmodule Math do
  def div(a, b) do
    try do
      a / b
    rescue
      e in ArithmeticError ->
        reraise DivisionByZeroError, [message: e.message], __STACKTRACE__
    end
  end
end

Now using Math.div(1, 0) will raise a DivisionByZeroError instead of a generic ArithmeticError.

Rescue And Catch in Elixir

In Elixir, try/raise/rescue and try/throw/catch are different. raise and rescue are used for exception handling, whereas throw and catch are used for control flow.

A throw stops code execution (much like a return — the difference being that it bubbles up until a catch is encountered). It is rarely needed and is only an escape hatch to be used when an API doesn’t provide an option to do something.

For example, let's say that there’s an API that produces numbers and invokes a callback:

defmodule Producer do
  def produce(callback) do
    Enum.each((1..100) , fn x -> callback.(x) end)
  end
end

(This is just an example. Assume that with the real API, it is much more expensive to produce each number, and it produces an infinite list of numbers.)

We want to find the first number divisible by 13, since we don’t have any other apparent way of finding that number and stopping the production at that point. Let’s see how we can use throw/catch to do this:

try do
  Producer.produce(fn x ->
    if rem(x, 13) == 0 do
      throw(x)
    end
  end)
catch
  x -> IO.puts("First number divisible by 13 is #{x}")
end

It's worth stating that this is a bit of a contrived case, and most good APIs are designed in such a way that you never need to reach out for throw/catch.

After and Else Blocks in Elixir

You can use after and else blocks with all try blocks. An after block is called after processing all other blocks related to the try, regardless of whether any of the blocks raised an error. This is useful for performing any required clean-up operations.

For example, the below code creates a new producer and makes some results. If there’s an error during production, it will raise an exception. But the after block ensures that the producer is still disposed of regardless.

producer = Producer.new
try do
  Producer.produce!(producer)
after
  Producer.dispose(producer)
end

On the other hand, an else block is called only if the try block is completed without raising an error. The else block receives the try block's result. The return value from the else block is the final return value of the try. For example:

try do
  File.read!("/path/to/file")
rescue
  File.Error -> :not_found
else
  "a" -> :a
  _other -> :other
end

In the above code, if the file exists with content a, the result will be :a. The result is :not_found if the file doesn’t exist, and :other if the content is anything else.

Exceptions and Processes

No discussion about Elixir exceptions is complete without examining their impact on processes. Any unhandled exceptions cause a process to exit.

With this in mind, let’s revisit the “let it crash” strategy. If we don’t handle an exception from a process, it will crash. This is good in a way because:

Since all processes are separate from each other, an exception or unhandled crash from one process can never affect the state of another process.
In most sophisticated Elixir applications, all the processes run under a supervision tree. So, an unexpected exit will restart the process (depending on the supervision strategy) and any linked processes with a clean slate.

In most cases, intermittent issues will resolve themselves in the next run. This is much easier (and usually also cleaner) than handling each failure separately and performing a recovery step.

If you want to learn more about supervisors, I suggest the official Elixir Supervisor and Application guide as a great starting point.

Monitoring Exceptions

As we've seen, exceptions are a fundamental part of any application. Handling them is good, but sometimes, letting them crash a process is even better.

But in all cases, it is better to monitor exceptions happening in the real world so that you can take action if there’s something concerning (for example, a developer error that crashes an app).

This is where AppSignal for Elixir can help. Once set up, it automatically records all errors and can also trigger alerts based on predefined conditions.

Here's an example of an individual error you can get to from the "Errors" -> "Issue list" in AppSignal for debugging:

Check out the AppSignal for Elixir installation guide to get started.

Wrapping Up

In this post, we explored how errors are treated in Elixir and how to recover from them. We also saw that sometimes it is better to just let a process crash and be restarted through the supervisor than to manually perform recovery steps for all possible exceptions.

Elixir’s API makes a clear distinction between functions that raise an exception (usually ending in !) and functions that return a success/error tuple. If you are a library author, it is better to provide both options for users.

Reach out for the tuple-based methods when you need to handle error cases separately. In Elixir, we rarely use try blocks for control flow — the ! functions are for when we want a process to crash on unexpected events.

Until next time, happy coding!

P.S. If you'd like to read Elixir Alchemy posts as soon as they get off the press, subscribe to our Elixir Alchemy newsletter and never miss a single post!

An Introduction to Mocking Tools for Elixir

Pulkit Goyal — Tue, 18 Apr 2023 11:09:36 +0000

A well-written test suite is a big part of any successful application. But let's say you rely on an external dependency for some parts of your app (for example, an external API for fetching user information). It then becomes important to mock that dependency in the test suite to prevent external API calls during testing or to test specific behavior.

Several frameworks help reduce the boilerplate and make mocking safe for Elixir tests. We will explore some of the major mocking tools available in this post.

Let's get started!

Test Without Mocking Tools in Elixir

Depending on the scope of your tests, you might not need to use any external mocking tools. You can use test stubs or roll your own server instead.

Test Stubs

The simplest way to stub/mock out some parts from a function call is to pass around modules that do the actual work and use a different implementation during the tests.

Let’s say you need to access the GitHub API to fetch a user’s profile with an implementation like this:

defmodule GithubAPI do
  def fetch_user(username) do
    case HTTPoison.get("https://api.github.com/users/#{username}") do
      {:ok, response} ->
        parse(response)
      {:error, reason} ->
        {:error, reason}
    end
  end
end

We know the implementation relies on HTTPoison to make actual calls to the GitHub API. To mock it during tests, we can update the implementation to pass around an http_client and use a different one during tests.

Something like this:

defmodule GithubAPI do
  def fetch_user(username, http_client \\ HTTPoison) do
    case http_client.get("https://api.github.com/users/#{username}") do
      #... handle results
    end
  end
end

This approach aligns with the Law of Demeter — a module should only have limited knowledge of the objects (in this case, the HTTP client) it works on. This approach is nice because it decouples the GithubAPI module from the HTTP client implementation.

Our GithubAPI users can continue using it in the same way.
But for unit-testing GithubAPI, we can pass in our custom http_client that returns just the results we need.

For example:

defmodule GithubAPITest do
  defmodule GithubHTTPClientUser do
    def get("https://api.github.com/users/octocat") do
      {:ok, %HTTPoison.Response{status_code: 200, body: ~s<{"login": "octocat"}>}}
    end
    def get("https://api.github.com/users/unknown") do
      {:error, %HTTPoison.Error{message: "Not Found"}}
    end
  end

  test "can fetch a user" do
    {:ok, %Github.User{login: "octocat"}} = GithubAPI.fetch_user("octocat", GithubHTTPClientUser)
  end

  test "handles errors when fetching a user" do
    {:error, %HTTPoison.Error{}} = GithubAPI.fetch_user("unknown", GithubHTTPClientUser)
  end
end

That works, and you have 100% test coverage! 🎉 But as you can already imagine, while this works well for small tests, it will become increasingly difficult to manage if our GithubAPI class grows to include other features.

Another similar strategy is to use application configuration instead of passing around the client modules. This is especially useful when you need to mock out the API from all the tests, even when this API is called from other internal modules.

We can update our code to this:

# github_api.ex
defmodule GithubAPI do
  @http_client Application.compile_env(:my_app, GithubAPI, []) |> Keyword.get(:http_client, HTTPoison)

  def fetch_user(username) do
    case @http_client.get("https://api.github.com/users/#{username}") do
      #... handle results
    end
  end
end

# test/support/mock_github_http_client.ex
defmodule MockGithubHTTPClient do
    # ... All mock implementations here
end

# config/test.exs
config :my_app, GithubAPI, http_client: MockGithubHTTPClient

The good thing is that you don’t need to worry about mocking out GithubAPI calls in each test case by manually passing the HTTP client.

This is especially important when the actual API calls are nested inside other functions. For example, if your application automatically fetches the user from GitHub after a new account is created, you don’t need to mock GithubAPI everywhere you create new users.

But it still has the same disadvantages as the previous strategy. Plus, the mocks must be generic enough to be used throughout the test suite.

Roll Your Own Server

This one is interesting. Since plug and cowboy make it really easy to roll out an HTTP server, instead of mocking out the HTTP Client, we can start our own server during tests and respond with stubs instead.

If you want to learn more, check out:

In the strategies discussed above, quite a bit of boilerplate is involved in setting up the tests.
And if you need a way to validate that a specific function was called with specific arguments, you need to do additional work.

If you just have a small external dependency that you need to mock out, this might work well for you. But if there are complex edge cases and branches that you need to test out, mocking tools can help simplify the complexity of writing and maintaining those mocks in the long run.

Elixir Mocking Tools

Mock

Mock is the first result you will see when searching “Elixir Mock”, and is a wrapper around Erlang’s meck that provides easy mocking macros for Elixir.

With Mock, you can:

Replace any module at will during tests to change return values.
Pass through to the original function.
Validate calls to the mocked functions.
Check the complete call history, including arguments and results for each call.

It is a very powerful tool, and the macro with_mock makes mocking during tests really easy.

Let’s see how we can rewrite our test case to validate GithubAPI.fetch_user:

defmodule GithubAPITest do
  # This is important, Mock doesn't work with async tests!
  use ExUnit.Case, async: false

  import Mock

  test "can fetch a user" do
    with_mock HTTPoison, [get: fn _url -> {:ok, %{status_code: 200, body: ~s({"login": "octocat"})}} end] do
      {:ok, %Github.User{login: "octocat"}} = GithubAPI.fetch_user("octocat")
      assert_called HTTPotion.get("https://api.github.com/users/octocat")
    end
  end
end

Very sleek. There's no need to define and pass boilerplate modules around or fiddle with the config just for tests. Our implementation is completely isolated from the test code and needs no special changes to fit the tests. And if we need to validate that a function was called with specific arguments, we can do that as well with assert_called.

One of the major drawbacks of this strategy is that you cannot use it with async tests. It doesn’t prevent you from using Mock inside asynchronous tests, so this can lead to hard-to-track flaky tests.

In my opinion, Mock works well for certain types of tests.
I usually find myself reaching for it when we need to mock external libraries that we have no control over. For example, let’s say we use an external library to fetch a user’s GitHub profile instead of our custom GithubAPI. Something like this:

def create_user(github_username) do
  Tentacat.Users.find(Tentacat.Client.new(), github_username)
  |> case do
    {:ok, user} ->
      # ... create user
    {:error, error} ->
      # ... handle error
  end
end

Now, if we dig into the library’s documentation/code, we can see that it uses HTTPoison to make the eventual request to the API. But we don’t want to — or have a way to — customize that client just for tests. Here, with_mock can easily help mock out that call so that we don’t request the API.

In fact, a much better approach, in this case, is to use with_mock to simply mock out the Tentacat.Users.find call altogether. That saves you from having to dig into the library's internal code (which can change with any update) and solely relying on mocking out its public interface.

Mox

We saw above how easy it is to mock some methods out and have our tests pass.
We sprinkle these calls in a few places to mock HTTPoison, and we are done.

But what if we later decide that HTTPoison isn’t fast enough and want to switch to another HTTP client implementation? As expected, all our tests will fail — we have to go back and fix them.
Even worse, what if the API for HTTPoison changes, but since we mocked it out, our tests never failed, and we pushed something that didn’t work to production?

Mox helps get around these issues by ensuring explicit contracts.
Read Mocks and Explicit Contracts for more details.

Using our GithubAPI example above, this is how we need to set up the tests with Mox.

Mock the External Client

We first convert our API client into a Behaviour to define the explicit contract the API client should follow.

# lib/my_app/github/api.ex
defmodule MyApp.GithubAPI do
  @callback fetch_user(String.t()) :: {:ok, Github.User.t()} | {:error, Github.Error.t()}

  def fetch_user(username), do: impl().fetch_user(username) do

  defp impl(), do: Application.get_env(:my_app, GithubAPI, GtihubAPI.HTTP)
end

Next, we define the API Client that makes the actual request to fetch the user.

# lib/my_app/github/http.ex
defmodule MyApp.GithubAPI.HTTP do
  @behaviour MyApp.GithubAPI

  @impl true
  def fetch_user(username) do
    case HTTPoison.get("https://api.github.com/users/#{username}") do
      {:ok, response} ->
        # Parse response here...
        {:ok, user}
      {:error, error} ->
        # Handle error here...
        {:error, reason}
    end
  end
end

Finally, in our test helper, we define a mock MyApp.GithubAPI.Mock for the API and set it in our application environment.

# test/test_helper.exs
Mox.defmock(MyApp.GithubAPI.Mock, for: MyApp.GithubAPI)
Application.put_env(:my_app, GithubAPI, MyApp.GithubAPI.Mock)

Now we can refactor the test case to use Mox for mocking out the call to the external API:

# test/my_app/github/api_test.exs
defmodule GithubAPITest do
  use ExUnit.Case, async: true

  import Mox

  setup :verify_on_exit!

  test "can fetch a user" do
    MyApp.GithubAPI.Mock
    |> expect(:fetch_user, fn "octocat" -> {:ok, %Github.User{login: "octocat"}} end)
    assert {:ok, %Github.User{login: "octocat"}} = GithubAPI.fetch_user("octocat")
  end
end

There are several interesting aspects to the above code. Let's break it down.

First, we use the expect function to define an expectation on the API. We expect a single call to fetch_user with the argument "octocat", and we mock it to return a {:ok, %Github.User{}} tuple.

Now, when we call GithubAPI.fetch_user/1 in the test, it will reach for that mocked expectation instead of the default implementation. Thus, we can safely assert the result of the call without making calls to the actual API.

The verify_on_exit! function as setup ensures that all expectations defined with expect are fulfilled when a test case finishes. So if we define an expectation on fetch_user and it isn't actually called (e.g., if the implementation changes later), we see the test fail.

Finally, notice that we don't need to mark the test as non-async here. That’s because Mox supports mocking inside async tests. So you can define two completely different mocks in two test cases, and they will both pass, even if they run simultaneously.

You can also define a global stub to avoid providing mocks in every test. This is useful if your client is being used in several places and you don’t want to explicitly define and validate expectations everywhere.

To do this, just update your ExUnit case template:

defmodule MyApp.Case do
  use ExUnit.CaseTemplate

  setup _context do
    Mox.stub_with(MyApp.GithubAPI.Mock, MyApp.GithubAPI.Stub)
  end
end

And create a stub with some static results:

defmodule MyApp.GithubAPI.Stub do
  @behaviour MyApp.GithubAPI

  @impl true
  def fetch_user("octocat"), do: {:ok, %Github.User{login: "octocat"}}
end

Now every time you use MyApp.Case in a test case, you don't need to manually mock calls to GithubAPI — they will automatically be forwarded to the stubbed module. This works well when you have calls to the GithubAPI that you will hit across several test suites. With a stub, you can be sure that such calls always return a specific and stable response without having to mock them out manually.

Test the External Client

If you are following along closely, you will notice that we didn’t actually test the MyApp.Github.HTTP module at all.
Don’t worry, we won’t leave it untested.

But the recommended way here is to do integration tests instead of using mocking at that level.

We will also configure it so that these tests don’t run when you run the full test suite.

# test/my_app/github/http_test.exs
defmodule MyApp.GithubAPI.HTTPTest do
  use ExUnit.Case, async: true

  # All tests will ping the API
  @moduletag :github_api

  # Write your tests here
end

# test/test_helper.exs
ExUnit.configure exclude: [:github_api]

The next step is to set up your CI pipeline to ensure that these tests run when required.

For example, you can configure it to run on all pull requests targeting main to avoid reaching the external API on every commit. You can also check that your CI pipeline runs before anything is merged to the main branch.

To do this, use the include command line flag when running mix test.

mix test --include github_api

There are several pros to the above strategy. You are now testing all parts of the application, including the calls to the external API (this part is not exactly dependent on Mox, but since we mocked out a significant part of our HTTP client, we must test it separately). We can also define global stubs, specific mocks, and expectations only when required, which makes most of our test suite very clean and concise.

The major drawback is that it requires quite some setup — you need a new behaviour with @callbacks for each public method you want to mock out. You have to implement that behaviour inside your module and finally set up Mox to mock out that implementation during tests.

And since we are now reaching the external API, the tests can be flaky, depending on the API's availability.

Mimic

If you are used to Mocha for other languages, you can check out Mimic. It lets you define stubs and expectations during tests by keeping track of the stubbed module in an ETS table.

It also maintains separate mocks for each process, so you can continue using async tests. It’s a great alternative to Mock — but that also means the same caveat applies: be careful about what you mock.

Here’s how a sample test looks with Mimic:

# test_helper.exs
Mmimc.copy(HTTPoison)
ExUnit.start()

# github_api_test.exs
defmodule GithubAPITest do
  use ExUnit.Case, async: true
  use Mimic

  test "can fetch a user" do
    url = "https://api.github.com/users/octocat"
    expect(HTTPoison, :get, fn ^url -> {:ok, %{status_code: 200, body: ~s({"login": "octocat"})}} end)
    assert {:ok, %Github.User{login: "octocat"}} = GithubAPI.fetch_user("octocat")
  end
end

expect/3 automatically verifies that the function is called.
And all expect and stub calls can be chained to make up clear mocking code.

Use Mocking Carefully for Your Elixir App

Mocking is an important and necessary part of any test suite.
But the thing to remember about mocking is that it is imperative to do it right.

For example, it might be tempting to mock out an internal API to quickly simulate something for a test. And yes, it works for quick unit tests. But then, someone else (or maybe you) comes along a while later and changes that something that you mocked earlier.

Your tests still pass since they use the mocked value. But in practice, the thing is now broken, and it will be caught much later in the feedback loop (or worse still, be shipped to the user as-is).

Wrap Up

In this post, we explored several mocking strategies you can use in Elixir tests. The safest (and the one you should consider using first) is Mox, as it forces mocked modules to have a defined behavior. Mox can therefore catch issues that arise from API changes during compilation.

Reach out for Mimic or Mock when you need to mock external libraries you don't have any control over.

Until next time, happy mocking!

P.S. If you'd like to read Elixir Alchemy posts as soon as they get off the press, subscribe to our Elixir Alchemy newsletter and never miss a single post!

Database Performance Optimization and Scaling in Rails

Pulkit Goyal — Wed, 04 Jan 2023 14:10:08 +0000

Web applications usually rely heavily on databases, for the most part. And as applications grow, databases grow too. We keep scaling web servers and background workers to keep up with the heavy load. But eventually, the database needs to keep up with all the new connections from these processes.

One way to tackle this is to grow a database with an app using vertical scaling. This means adding more CPU power and memory to the database server. But this is usually slow. You might have to copy all your data to the new server and then put the application down to change the database servers that it communicates with.

This is also usually a one-way operation. You can't keep adding/removing CPU power or memory from the database server based on your load.

This post will cover some alternative methods to fine-tune and scale a database under heavy load and improve the performance of your Rails app. We will focus on:

Splitting schema and data between multiple databases
Using read-only replica databases

Let's get going!

Disclaimer: Scaling Isn't Always Needed

As always, with any post about performance optimization and scaling, I would like to put up a standard disclaimer: make sure you have an issue before trying to solve it.

For example, on one of our apps in production, we tackled scaling and optimization only when we started processing more than 3 million background jobs a day.

This will, of course, be different for different apps. But usually, a good indicator of whether you need to optimize is if your database is always running at high CPU or memory usage.

A Separate Database for Your Rails Application

Sometimes, simply using a separate database server for a part of your app is a good solution. For example, your app might do two different things that don’t have a big overlap. Alternatively, maybe there's one very database-heavy feature, but it is only used rarely or by a small section of users. You should go for a separate database server if — and only if — there is a clear distinction between the parts of your app that will use different databases.

For example, a separate database is useful when you're audit logging in a high-frequency app (or have other very high-volume data that isn't necessarily accessed frequently). Let's see how we can set this up.

First, set up the database.yml to configure the second database. Let’s call the second database log. We'll add a log_default entry for the secondary database with a common configuration across all environments:

log_default: &log_default
  host: localhost
  port: <%= ENV["DB_PORT"] || 5432 %>
  adapter: postgresql
  encoding: unicode
  user: <%= ENV["DB_USER"] || "postgres" %>
  password: <%= ENV["DB_PASSWORD"] || "postgres" %>
  migrations_paths: db/log_migrate

The important bit here is the migrations_paths option that tells Rails where to find migrations related to this database.

Then, update database.yml to configure access to the log database for development, test, and production environments:

development:
  primary:
    <<: *default
    database: <%= ENV["DB_NAME"] %>
  log:
    <<: *log_default
    database: <%= ENV["LOG_DB_NAME"] %>

test:
  primary:
    <<: *default
    database: my_app_test
  log:
    <<: *log_default
    database: my_app_log_test

production:
  primary:
    adapter: postgresql
    encoding: unicode
    url: <%= ENV["DATABASE_URL"] %>
  log:
    adapter: postgresql
    encoding: unicode
    migrations_paths: db/log_migrate
    url: <%= ENV["DATABASE_LOG_URL"] %>

As you can see, we move the configuration for each environment one level deeper. The configuration for our primary database lives inside the primary key for each environment. The second database's configuration (that we call log) lives inside the log key. primary is a special keyword that tells Rails to use this database as the default.

The next step is to set up ActiveRecord to use this new database. We first create a base class that establishes a connection to this database (instead of a primary one) using establish_connection:

class LogRecord < ActiveRecord::Base
  self.abstract_class = true
  establish_connection :log
end

And then, we inherit from LogRecord instead of ApplicationRecord for all the records that should access the log DB:

class AuditLog < LogRecord
end

Note that you keep using the rails generators for generating models and migrations by appending the --database log option to target the second database. The migration task now automatically migrates both databases, but if you need to only migrate one, you can use db:migrate:primary or db:migrate:log tasks.

This works great if there is a clear distinction between two parts of the app. But what if you don’t have a clear idea of the database that's creating issues? There are still a couple of options left. Let's check them out.

Using Read-Only Replicas for Rails

Our second scaling option is to access data from read-only replicas while still writing to the primary database. This can improve performance for users who only browse parts of the app without performing any writing operations. Depending on your app's use case, this can be 80% of your users or 10% of them. So, evaluate the behavior of your users or your application use case before going down this route.

For an app with a majority of read-only users (like Twitter, for example), you can gain huge improvements in performance. New read-only replicas can be added/removed at will without affecting the primary database, which opens up options for auto-scalability.

Let's see how to set this up.

Setting up a Read-Only Replica

As usual, we will start with modifications to the database.yml config to include the replica:

production:
  primary:
    adapter: postgresql
    encoding: unicode
    url: <%= ENV["DATABASE_URL"] %>
  primary_replica:
    adapter: postgresql
    encoding: unicode
    url: <%= ENV["DATABASE_REPLICA_URL"] %>

Again, the primary key is a special key indicating that this database is the default. We can use any other key for the replica database configuration. Let’s choose primary_replica for sanity.

Then update the ApplicationRecord to configure a connection to multiple databases:

class ApplicationRecord < ActiveRecord::Base
  self.abstract_class = true

  connects_to database: { writing: :primary, reading: :primary_replica } if Rails.env.production?
end

Note that we add configuration for a production environment only in the above example. If you want to, you can set it up for all environments, after modifying your development setup to support replicas.

Finally, to use the read-only replica, you need to tell Rails when to use the primary database and when to use the replica. Rails provides a basic implementation for automatic role-switching based on the HTTP verb of the request out of the box. To enable it, add the following to your production.rb:

# Use Read-Only Databases on GET requests
config.active_record.database_selector = { delay: 2.seconds }
config.active_record.database_resolver = ActiveRecord::Middleware::DatabaseSelector::Resolver
config.active_record.database_resolver_context = ActiveRecord::Middleware::DatabaseSelector::Resolver::Session

This tells Rails to use the replica for all GET or HEAD requests and the primary one otherwise. Notice the option that sets the delay to two seconds? That tells Rails to keep using the primary database for GET and HEAD requests if it is within two seconds of a write request in the same session.

Gotchas

Does all of this sound too simple? Well, we aren’t done yet. Depending on how your application is structured, you need to keep a few points in mind.

Firstly, ensure you do not write anything in a read-only action like index or show. If there are legitimate reasons for writing during those operations, you can manually switch the connection:

ActiveRecord::Base.connected_to(role: :writing) do
  # Your code here
end

A good example where this can be useful is if you are managing sessions in a database. If you do that, make sure you use the writing role. For example, you can override the save_record method in your session with authlogic:

class UserSession < Authlogic::Session::Base
  # Your session configuration

  def save_record(alternate_record = nil)
    ActiveRecord::Base.connected_to(role: :writing) do
      super
    end
  end
end

Another use case for automatic role-switching is when an app exposes a GraphQL API. All operations on a GraphQL API are POST, but conventionally, all queries are read-only, and mutations are read-write. In this case, to allow Rails to select the correct database, we can use a custom tracer in the schema.

First, create a tracer that switches roles based on the GraphQL document:

module Tracers
  class DatabaseRoleTracer
    EVENT_NAME = "execute_multiplex"

    # Execute on read only database if the operation has only queries.
    def trace(event, data)
      return yield unless Rails.env.production?
      return yield unless event == EVENT_NAME

      multiplex = data[:multiplex]
      ActiveRecord::Base.connected_to(role: role(multiplex)) do
        yield
      end
    end

    private

    def role(multiplex)
      if multiplex.queries.all?(&:query?)
        ActiveRecord::Base.reading_role
      else
        ActiveRecord::Base.writing_role
      end
    end
  end
end

And then use the tracer in your GraphQL Schema:

class MyAppSchema < GraphQL::Schema
  tracer Tracers::DatabaseRoleTracer.new

  # Your code here
end

Let’s get to the final alternative. What can you do if your application still has a huge load on your primary database? The answer: database sharding.

Database Sharding in Your Rails Application

This is the most complex of all the methods for scaling databases discussed in this post. So reach for it only if you need it. It will add considerable complexity to your application and needs to be done right to provide any real benefit.

There are two strategies to shard your database:

Distribute different tables on different nodes (vertical sharding).
Have the same schema across all nodes, but distribute data depending on certain parameters (horizontal sharding).

Vertical sharding is similar to our “multiple databases” strategy in terms of setup and pros and cons, so we will not discuss it again.

Let's discuss horizontal sharding and where it could be helpful.

One example is when you have a SaaS platform where a lot of data is associated with each user, but there is no overlap between the data of two users. In this case, splitting the data across nodes based on the user's id is the most logical way to go. Every signed-in user will have to access only a single database, so we won't have to reach out to multiple databases at the same time.

Setting up Horizontal Sharding

Let’s start with the configuration inside database.yml again:

production:
  primary:
    adapter: postgresql
    encoding: unicode
    url: <%= ENV["DATABASE_URL"] %>
  primary_replica:
    adapter: postgresql
    encoding: unicode
    url: <%= ENV["DATABASE_REPLICA_URL"] %>
  primary_shard_one:
    adapter: postgresql
    encoding: unicode
    url: <%= ENV["DATABASE_SHARD_ONE_URL"] %>
    primary_shard_one_replica:
    adapter: postgresql
    encoding: unicode
    url: <%= ENV["DATABASE_SHARD_ONE_REPLICA_URL"] %>

Then modify the ApplicationRecord to connect to different shards:

class ApplicationRecord < ActiveRecord::Base
  self.abstract_class = true

  connects_to shards: {
    default: { writing: :primary, reading: :primary_replica },
    shard_one: { writing: :primary_shard_one, reading: :primary_shard_one_replica }
  }
end

Now we can use the shard option with ActiveRecord::Base.connected_to to switch shards. Like the automatic database role selector, Rails also provides an automatic shard switcher that can be activated inside production.rb like this:

Rails.application.configure do
  config.active_record.shard_selector = { lock: true }
  config.active_record.shard_resolver = ->(request) { Tenant.find_by!(host: request.host).shard }
end

The shard_resolver lambda is the most interesting part. The above implementation relies on the assumption that our application is accessed from different domains/subdomains and distinguishes between the shards. Modify it to fit your application needs (you might need to access cookies to identify a user before switching the shard).

As with vertical scaling, this strategy is usually a one-way street. Once you shard a database, it is very hard to “un-shard” it (since several databases could have the same ids for different objects). But this lays down the foundation to really scale your app to millions or billions of users when fitting everything on the same server is not an option.

If you want to read more about database sharding, see this write-up by Linode.

Measure Your Rails Database Performance with AppSignal

It can be tricky to keep an eye on the performance of your database without any other tools. Using AppSignal, you can easily track how your databases perform. See our AppSignal for Ruby page for more information.

You can also check out our post Test and Optimize Your Ruby on Rails Database Performance for more information on the metrics you can measure in AppSignal and how a dashboard might look.

Wrap Up

In this post, we discussed three major strategies to scale your database servers horizontally:

Splitting schema between multiple databases
Using read-only replica databases
Splitting data between multiple databases

All strategies have their pros and cons depending on your application use case and scale.

Rails has really upped its database game in its last few releases. This post has shown how easy it is to set up a Rails app to use multiple databases.

As always, if your application allows it, I suggest starting small with optimizations. The easiest optimization to start with is a read-only replica, then only move on when you need more scale.

Happy scaling!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Using Profiling in Elixir to Improve Performance

Pulkit Goyal — Tue, 03 May 2022 10:52:22 +0000

Elixir is all about performance. Say you have an app up and running with Elixir, but some parts aren't working as fast as you would like them to.

That is where profiling comes in.

Profiling tools usually walk you through the frequency and duration of function calls and where they spend their time.
Erlang has impressive profile tooling available at its disposal.

In this post, we will look into three profiling tools in Elixir: cprof, eprof, and fprof.

Do I Need Profiling for My Elixir App?

Firstly, I want to clarify that you may not need profiling at all. As Donald Knuth wrote: 'premature optimization is the root of all evil.' Some operations just cannot be optimized.

For example, say you want to fetch something from your database. You issue a query and get a reply. This incurs a network round trip with some data. If you need all the data, the network round trip time cannot be optimized without moving your database closer to the app.

With that out of the way, let's jump into profiling options.

Profiling with `cprof` in Elixir

cprof counts the number of times each function is invoked.
It doesn't profile the time spent in those functions, so it comes with the least amount of overhead.

Use it when you already have an estimate of your functions' runtimes. You'll see the frequency with which each function is invoked.

Let's see how we can profile a Fibonacci number generator with cprof.

You can follow along with the code. It uses the Rosetta Code algorithm for Fibonacci sequence generation.

Jump into an IEx session and run cprof like this:

iex(15)> :cprof.start()
19244
iex(16)> FibonacciRosettaCode.list(10)
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
iex(17)> :cprof.analyse(FibonacciRosettaCode)
{FibonacciRosettaCode, 79,
 [
   {{FibonacciRosettaCode, :fibonacci, 3}, 54},
   {{FibonacciRosettaCode, :fibonacci, 1}, 11},
   {{FibonacciRosettaCode, :"-fun.fibonacci/1-", 1}, 11},
   {{FibonacciRosettaCode, :module_info, 1}, 1},
   {{FibonacciRosettaCode, :list, 1}, 1},
   {{FibonacciRosettaCode, :__info__, 1}, 1}
 ]}
iex(18)> :cprof.stop()
19266

First, start cprof, run the code that you want to profile, and then call :cprof.analyse/1 to fetch the statistics for the given module. Several other options are available inside the :cprof module, like pausing profiling with :cprof.pause/0.

We can also use Mix's wrapper task profile.cprof directly.

➜ mix profile.cprof -e "FibonacciRosettaCode.list(10)"
                                                                     CNT
Total                                                                113
FibonacciRosettaCode                                                  77  <--
  FibonacciRosettaCode.fibonacci/3                                    54
  FibonacciRosettaCode.fibonacci/1                                    11
  FibonacciRosettaCode."-fun.fibonacci/1-"/1                          11
  FibonacciRosettaCode.list/1                                          1
Enum                                                                  24  <--
  Enum.reduce_range/5                                                 12
  anonymous fn/3 in Enum.map/2                                        11
  Enum.map/2                                                           1
  ...

Here, we can see that the function fibonacci/3 is called the most.

So, if we can somehow decrease the number of calls to that function or optimize the code inside it, we could improve performance.

`eprof` Profiling in Elixir

cprof measures counts while eprof measures the execution time (in addition to counts) spent inside each function.
It has slightly more overhead than cprof. Use eprof when you want to find the most time-consuming functions.

The usage is very similar to cprof. You just need to start the profiler, run the code you want to profile, and then call analyze to fetch the results.

Let's analyze the results from the mix task profile.eprof on our sample Fibonacci generator.

➜ mix profile.eprof -e "FibonacciRosettaCode.list(10)"
#                                               CALLS     % TIME µS/CALL
Total                                             106 100.0   45    0.42
anonymous fn/0 in :elixir_compiler_1.__FILE__/1     1  0.00    0    0.00
:lists.reverse/1                                    1  2.22    1    1.00
:lists.reverse/2                                    1  2.22    1    1.00
FibonacciRosettaCode.fibonacci/1                   11  4.44    2    0.18
Enum.map/2                                          1  4.44    2    2.00
Range.new/2                                         1  4.44    2    2.00
FibonacciRosettaCode."-fun.fibonacci/1-"/1         11  8.89    4    0.36
FibonacciRosettaCode.list/1                         1  8.89    4    4.00
:erlang.apply/2                                     1  8.89    4    4.00
anonymous fn/3 in Enum.map/2                       11 13.33    6    0.55
Enum.reduce_range/5                                12 13.33    6    0.50
FibonacciRosettaCode.fibonacci/3                   54 28.89   13    0.24

Here, we can see that fibonacci/3 is again the most time-consuming part of our program, consuming 28.89% of the total execution time and 0.24µS per call.

In addition, eprof also allows us to profile function calls across different processes.

The usage is very simple. Let's see an example:

:eprof.start_profiling([self()])

# Do some work
1..100 |> Enum.each(fn i ->
  spawn(fn -> FibonacciRosettaCode.list(i + 1) end)
end)

:eprof.stop_profiling()
:eprof.analyze()

You need to call start_profiling/1 with a list of processes to profile.

By default, this also tracks any other processes started from a profiled process.

When you are done, call stop_profiling and run analyze to get the results. They should look something like this, with an entry for each process and the percentage of time it was busy:

****** Process <0.150.0>    -- 37.26 % of profiled time ***
FUNCTION                                                             CALLS        %   TIME  [uS / CALLS]
--------                                                             -----  -------   ----  [----------]
io:request/2                                                             3     0.00      0  [      0.00]
...

****** Process <0.277.0>    -- 0.05 % of profiled time ***
FUNCTION                                             CALLS        %  TIME  [uS / CALLS]
--------                                             -----  -------  ----  [----------]
'Elixir.FibonacciRosettaCode':fibonacci/3                2     0.00     0  [      0.00]
'Elixir.FibonacciRosettaCode':fibonacci/1                3     3.03     1  [      0.33]
'Elixir.FibonacciRosettaCode':'-fun.fibonacci/1-'/1      3     3.03     1  [      0.33]
...

The great thing about this is that you can run it in production systems by accessing the remote console. Just call start_profiling/1, wait some time to process the requests or manually trigger some requests that you want to profile. Then call stop_profiling followed by analyze to get the results.

Using `fprof` in Elixir

The final inbuilt tool that you can use to profile your applications is fprof. It is a comprehensive profiling tool that generates a trace file containing timestamped entries for function calls, process-related events, and garbage collection data.

You can then feed this trace file into other tools to visualize the results thoroughly or use :fprof.analyse like above to fetch function counts and execution times.

Running fprof through IEx is quite advanced compared to running cprof and eprof, but fprof allows tracing multiple processes.

Here is how you can generate a trace file for all processes:

:fprof.start()
:fprof.trace([:start, procs: :all])

# Do some work
1..100 |> Enum.each(fn i ->
  spawn(fn -> FibonacciRosettaCode.list(i + 1) end)
end)

:fprof.trace(:stop)
:fprof.profile()
:fprof.analyse(totals: false, dest: 'prof.analysis')

This generates a comprehensive trace of everything that went on during the run with:

CNT - the number of times a function is called
ACC - the accumulated time spent in the function, including other function calls
OWN - the time the function spent to be executed

Here's the full file (50 MB), if you are interested.

Like eprof, fprof is a great tool for profiling applications in production directly. Note that this will significantly slow down the application, so be prepared for degraded performance during profiling and a huge trace file.

So you have the data now. If you are feeling adventurous, you can start digging through the file and look for patterns.

Or, you can use some tools to help visualize your data.
A popular one is erlgrind. It converts the fprof file to cgrind format that you can open inside KCachegrind.

To convert the file, download erlgrind and then run src/erlgrind profile.fprof.

This will generate a prof.cgrind file that you can open to see graphs like this:

Profile and Collect Metrics from Your Elixir App in Production

eprof and fprof can assist with profiling your application in production, but there are a couple of additional tools worth mentioning — Phoenix Live Dashboard and AppSignal.

Phoenix Live Dashboard

Phoenix's live dashboard can provide a great, quick overview of metrics. While not exactly a profiler, it shows OS data and metrics from telemetry events and processes, among other things.

Here is an example of the dashboard in action:

AppSignal

AppSignal is another great tool for collecting performance data (among other things). Adding AppSignal to an existing application takes a few seconds.

Just install the appsignal dependency and run the appsignal.install mix task with an API key. It has a good set of default metric collection including the throughput and response times for the application. You could even set up minutely probes to track custom metrics.

Here's an example of the AppSignal dashboard collecting data from a sample application:

If you are looking to collect data about specific blocks of code that you suspect are slow, AppSignal's instrumentation feature can help collect this data. Just wrap the suspected code inside Appsignal.instrument/2, like this:

defmodule MyApp.PageController do
  use MyApp, :controller

  def index(conn, _params) do
    custom_function()
    render(conn, "index.html")
  end

  defp custom_function do
    Appsignal.instrument("custom_function", fn ->
      :timer.sleep(1000)
    end)
  end
end

This will show up on the AppSignal event graph tagged as custom_function. You can then explore this event across multiple calls and make an informed decision about the need for optimization.

Check out the full list of features in the AppSignal docs.

Wrap-up: Measure Your Elixir App's Performance with Profiling

In this post, we saw how inbuilt tools like cprof, eprof, and fprof can help gather performance insights for your code, even during production.

We also took a quick look at a couple of other tools to monitor and trace your applications: Phoenix Live Dashboard and AppSignal.

Until next time, happy profiling!

P.S. If you'd like to read Elixir Alchemy posts as soon as they get off the press, subscribe to our Elixir Alchemy newsletter and never miss a single post!

What's New in Rails 7

Pulkit Goyal — Wed, 22 Dec 2021 12:01:21 +0000

Rails 7 is just around the corner. We don't have a confirmed release date, but it is expected to be available before Christmas, so not very long to go. The latest version as of this post's publication is 7.0.0.rc1, the first release candidate. Basecamp, HEY, Github, and Shopify have all been running the Rails 7 alpha in production, so we can expect even the release candidate to be pretty stable.

In this post, we will look at some of the new features and changes that Rails 7 will bring.

Node and Webpack Not Required

Yes, you read that right! JavaScript in Rails 7 will no longer require NodeJS or Webpack. And you can still use npm packages.

Transpiling ES6 with Babel and bundling with Webpack require a lot of setup. While Rails supported it pretty well with the Webpacker gem, this brought a lot of baggage, was hard to understand and make any changes to, especially while maintaining upgradability.

Now, the default for new apps created with rails new is to use import maps through the importmaps-rails gem. Instead of writing a package.json and installing dependencies with npm or yarn, you use ./bin/importmap CLI to pin (or unpin or update) dependencies.

For example, to install date-fns:

$ ./bin/importmap pin date-fns

This will add a line in config/importmap.rb like:

pin "date-fns", to: "https://ga.jspm.io/npm:date-fns@2.27.0/esm/index.js"

In your JavaScript code, you can continue using everything as you used to:

import { formatDistance, subDays } from 'date-fns'

formatDistance(subDays(new Date(), 3), new Date(), { addSuffix: true })
//=> "3 days ago"

One thing to keep in mind with this setup is that there is no transpiling between what you write and what the browser gets. For the most part, this is ok since all browsers that matter now support ES6 out of the box.

But this also means that you won't be able to use TypeScript or JSX as they require transpilation to JS before use.

So, if you want to use React with JSX, you still have to fall back to a different setup (using webpack/rollup/esbuild).

Rails 7 can do this for you. All you need is one command with your chosen strategy:

$ ./bin/rails javascript:install:[esbuild|rollup|webpack]

Turbolinks and UJS Replaced by Turbo and Stimulus

Applications generated with Rails 7 will get Turbo and Stimulus (from Hotwire) by default, instead of Turbolinks and UJS. Hotwire is a new approach that delivers fast updates to the DOM by sending HTML over the wire.

Encryption at Database Layer

Rails 7 allows marking certain database fields as encrypted using the encrypts method on ActiveRecord::Base. This means that after an initial setup, you can write code like this:

class Message < ApplicationRecord
  encrypts :text
end

You can continue using the encrypted attributes like you would any other attribute. Rails 7 will encrypt and decrypt it automatically between the database and your application.

But this comes with a slight quirk: you cannot query the database by that field unless you pass a deterministic: true option to the encrypts method.

The deterministic mode is less secure than the default non-deterministic mode, so only use it for attributes you absolutely need to query.

Asynchronous Querying

There is now a load_async method that you can use when querying data to fetch results in the background. This is especially important when you need to load several un-related queries from a controller action. You can run:

def PostsController
  def index
    @posts = Post.load_async
    @categories = Category.load_async
  end
end

This will fire both queries in the background at the same time. So, if each query takes 200ms, the total time spent fetching the data is ~200ms instead of 400ms, if they are fetched serially.

Zeitwerk Mode for Rails 7

This is a breaking change for older applications that still run the classic loader. All Rails 7 applications must use Zeitwerk mode, but the switch is pretty easy. Check out the full Zeitwerk upgrade guide.

Other Rails 7 Updates

Retry Jobs Unlimited Times

ActiveJob now allows passing :unlimited as the attempts parameter on retry_on. Rails will continue to attempt the job without any maximum number of attempts.

class MyJob < ActiveJob::Base
  retry_on(AlwaysRetryException, attempts: :unlimited)

  def perform
    raise "KABOOM"
  end
end

Named Variants

You can now name variants on ActiveStorage instead of specifying size on every access.

class User < ApplicationRecord
  has_one_attached :avatar do |attachable|
    attachable.variant :thumb, resize: "100x100"
  end
end

#Call avatar.variant(:thumb) to get a thumb variant of an avatar:
<%= image_tag user.avatar.variant(:thumb) %>

Hash to HTML Attributes

There is a new tag.attributes method for use in views that translates a hash into HTML attributes:

<input <%= tag.attributes(type: :text, aria: { label: "Search" }) %>>

will produce

<input type="text" aria-label="Search">

Ruby `debug`

The new default for debugging has changed from byebug to the debug gem.

Instead of calling byebug, you now need to call debugger in the code to enter a debugging session.

Assert a Single Record with `sole`

When querying records, you can now call sole or find_sole_by (instead of first or find_by) when you want to assert that the query should only match a single record.

Product.where(["price = %?", price]).sole
# => ActiveRecord::RecordNotFound      (if no Product with given price)
# => #<Product ...>                    (if one Product with given price)
# => ActiveRecord::SoleRecordExceeded  (if more than one Product with given price)

user.api_keys.find_sole_by(key: key)
# as above

Check Presence/Absence of an Association

We can now use where.associated(:association) to check if an association is present on a record instead of joining and checking for the existence of an id.

# Before:
account.users.joins(:contact).where.not(contact_id: nil)

# After:
account.users.where.associated(:contact)

Stream Generated Files from Controller Actions

You can now use send_stream inside a controller action to start streaming a file that is being generated on the fly.

send_stream(filename: "subscribers.csv") do |stream|
  stream.write "email_address,updated_at\n"

  @subscribers.find_each do |subscriber|
    stream.write "#{subscriber.email_address},#{subscriber.updated_at}\n"
  end
end

This provides an immediate (partial) response to the user so that they know something is happening and has an added benefit if you deploy on Heroku.

Since the file will start streaming immediately, Heroku will not terminate the connection. This means you don't need to resort to background jobs to generate one-off files that take longer than 30 seconds.

Upgrading to Rails 7

As with previous versions of Rails, upgrading is simple. While we don't have an official upgrade guide yet, the steps will remain the same:

Change the Rails version number in the Gemfile (7.0.0.rc1 as of the publication date) and run bundle update.
Run bundle exec rails app:update. Follow the interactive CLI and add/replace/modify the files as required.
Run your tests and verify everything works as expected.

Wrap Up

You can see the full list of bug fixes, features, and changes in the Rails 7 release notes.
These are not comprehensive at the moment, but we can expect them to be updated soon.

If you are still running Rails 6 or lower, please note that with the final release of Rails 7, Rails 6.1 will enter the "security issues only" mode and will no longer receive bug fixes.

This will also mark the EOL for Rails 5.2, as it will no longer receive any fixes.

Have fun coding!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Three Ways to Debug Code in Elixir

Pulkit Goyal — Tue, 07 Dec 2021 13:11:29 +0000

Elixir provides a very powerful suite of tools that devs can use to observe the behavior of their code and debug errors.

There are several different strategies you can use to debug code in Elixir.

While it is hard to produce a comprehensive list of all possible debugging methods, we will cover some of the most common methods in today's post.

1. The IO Module: `puts/2` and `inspect/2`

Use the IO module for a quick and easy way to get some basic visibility into your code when debugging.

You can print out log statements that:

tell you where you are in executing code
inspect structs and other entities
display the function's arguments

puts/2 and inspect/2 are the most interesting to use when debugging. With these, it's easy to sprinkle a few good output messages throughout your code and then visualize what's happening.

puts/2 just prints out a string to the intended device (or :stdio if you don't provide anything).

inspect/2 does something similar but writes out formatted output (e.g., pretty-printing maps, structs, and arrays).
There are a couple of options to select the width or a label for the message:

> IO.inspect(%{foo: :bar}, label: "some map")
# some map: %{foo: :bar}

The great thing about IO.inspect/2 is that it returns the input, so it is easy to tap into long pipes:

[1, 2, 3]
|> IO.inspect(label: "before")
|> Enum.map(&(&1 * 2))
|> IO.inspect(label: "after")
|> Enum.sum

In addition to this, if you need to create strings with embedded maps for the log messages, it is also possible to use Kernel.inspect/2 inside puts strings — like this:

> IO.puts("some map: #{inspect(%{foo: :bar})}")
# some map: %{foo: :bar}

The inspect method has a lot more options to customize your output.

Finally, if you need to access a function's arguments quickly, it is possible to use binding/1.

defmodule Greeter do
  def greet(name \\ "John Doe") do
    IO.inspect(binding())
  end
end

Greeter.greet() # Prints [name: "John Doe"]
Greeter.greet("Jane Doe") # Prints [name: "Jane Doe"]

2. IEx for Advanced Debugging Control

If you need advanced control for debugging, the next tool you'll find useful is the interactive shell IEx. IEx lets you inspect and visualize the current state of your code, manually execute code, and examine the results.

Just pop in require IEx; IEx.pry anywhere in your code and then run it with iex. So, if you are running a:

Standalone elixir file with elixir fib.exs, use iex -r fib.exs instead.
Mix command like mix run fib.exs or mix phx.server, use iex -S mix run fib.exs or iex -S mix phx.server.

Let's take a look at some of the things we can do with IEx.

Using Pry with IEx

Let's see how debugging works with pry by looking at a buggy Fibonacci number generator. The code does not produce the expected result. Let's put a require IEx; IEx.pry on line 9 (just after fib2 = fib) and run it with iex -r fib.exs:

Request to pry #PID<0.104.0> at Fib.number/1 (fib.exs:9)

    7:       fib1 = fib2
    8:       fib2 = fib
    9:       require IEx; IEx.pry
   10:     end)
   11:     fib2

Allow? [Yn] y
Interactive Elixir (1.12.0) - press Ctrl+C to exit (type h() ENTER for help)
pry(1)> binding()
[_i: 2, fib: 1, fib1: 1, fib2: 1, n: 5]

We can see that it stops at the IEx.pry() call. Then, we can inspect the values of the variables (or just use binding to output all context).

For the first iteration, everything looks good, fib2 updates to 1, and fib1 uses the previous value of fib2, i.e., 1.

On the next iteration, we expect fib2 to be 1 + 1 = 2 and fib1 to be 1, and then fib2 to be 2 + 1 = 3 and fib1 to be 2, and so on.

So let's type continue to go to the next pry call and inspect the binding again:

pry(2)> continue
Break reached: Fib.number/1 (fib.exs:9)

    7:       fib1 = fib2
    8:       fib2 = fib
    9:       require IEx; IEx.pry
   10:     end)
   11:     fib2

pry(1)> binding()
[_i: 3, fib: 1, fib1: 1, fib2: 1, n: 5]

Here, we see that we are on the next iteration (_i is 3), but apparently, the other variables do not change at all.
So this is where our bug lies. Everything is immutable in Elixir, so assigning variables inside the anonymous function creates new variables rather than overriding the ones on the outer scope.

We can now use this insight to fix our code.

If you are curious, see the fixed version of the Fibonacci number generator.

Using Breakpoints with IEx

In the previous section, we had to change the code to enter the pry session.
IEx also provides a break! function to set breakpoints without changing code.

This is very important when you want to set breakpoints in parts of code that you don't own, coming from a library or even from Elixir standard modules.

The only drawback is that this only works on compiled code, and you can only break! at the start of the function, not on any arbitrary line.

To use break! with our Fibonacci example:

$ elixirc fib.ex # This generates a beam file in your current dir
$ ls *.beam
Elixir.Fib.beam
$ iex            # This will load all beam files in the current directory
iex> IEx.Helpers.break!(Fib.number/1)
iex> Fib.number(5)
Break reached: Fib.number/1 (fib.ex:2)

    1: defmodule Fib do
    2:   def number(n) do
    3:     fib1 = 0
    4:     fib2 = 1

Bonus: IEx Tips and Tricks

While we are on IEx, let us look at some general tips that can help you be more productive with it.

The first, and possibly the most important, is to enable shell history if you use IEx a lot. You can then press ↑ to get your last used commands or use ^ + R to reverse search the history of used commands.

There are two ways you can enable shell history:

Enable each session by starting it with a flag:

$ iex --erl "-kernel shell_history enabled"

Enable all sessions by setting the ERL_AFLAGS environment on your shell. Depending on your terminal configuration, you will need to add the following (or its equivalent) to a startup script (like ~/.zshrc/~/.bashrc):
```
export ERL_AFLAGS="-kernel shell_history enabled"
```

The second tip, which works on the recent version of Elixir (1.12+), means that you can use multi-line pipes directly in the shell. The pipe automatically gets the last evaluated statement's return value.

So you can just copy and paste long pipes from your code directly in the IEx session:

iex(1)> [1, [2], 3]
[1, [2], 3]
iex(2)> |> List.flatten()
[1, 2, 3]

If you often use modules in IEx, you can create a file called .iex.exs from the directory used to access IEx. Alternatively, you can create a global file inside the home directory (~/.iex/exs), and it will be evaluated every time you open an IEx session.

# Load another ".iex.exs" file
import_file("~/.iex.exs")

# Import some module from lib that may not yet have been defined
import_if_available(MyApp.Mod)

# Import Ecto.Query so that querying is always available in the shell
import Ecto.Query

Finally, there are some cases when you might be using IEx and you make a typo (like an additional bracket or ") and the command cannot be terminated, for example:

iex> ["abc"
...  "
...  ]

In this case, you cannot use ^ + C or ^ + \ as they would terminate the session, rather than just the command. To terminate the command immediately, start a new line with #iex:break:

iex> ["abc"
...  "
...  ]
...  #iex:break
** (TokenMissingError) iex:1: incomplete expression
>

3. Visual Debugging

In addition to the prying functionality provided by Elixir, there is also a more sophisticated Erlang debugger that you can use.

While it works with a single compiled file like IEx.break!, let's try using a file that is a part of a mix project with iex -S mix this time.

iex> :debugger.start()
{:ok, #PID<0.672.0>}
iex> :int.ni(Fib)
{:module, Fib}
iex> :int.break(Fib, 6)
ok
iex> Fib.number(5)

The above will open the Erlang debugger and stop at the configured breakpoint.

This provides a more traditional debugging approach where you can perform a single step or continue to the next breakpoint, evaluate expressions in the current context, etc.

If you are using Visual Studio Code, the ElixirLS plugin supports in-editor breakpoints.
There is also similar support in IntelliJ through the intellij-elixir plugin.

Debugging Elixir Processes

A post on debugging Elixir code wouldn't be complete without also covering how to debug processes.

While we can use the debugging methods we've already covered, a couple of other process-specific options are available.

Using Trace to Debug Processes in Elixir

Use :sys.trace/2 when you quickly want to see all the messages exchanged between a process and its state updates.
We can use it to start/stop logging the process states and messages. Let's continue with the Fibonacci computer, but this time, wrapped inside a GenServer:

iex(3)> {:ok, pid} = GenServer.start_link(Fib, nil)
{:ok, #PID<0.1023.0>}
iex(4)> :sys.trace(pid, true)
:ok
iex(5)> GenServer.call(pid, {:get, 1})
*DBG* <0.1023.0> got call {get,1} from <0.1004.0>
*DBG* <0.1023.0> sent 1 to <0.1004.0>, new state #{0 => 0,1 => 1}
1
iex(6)> GenServer.call(pid, {:get, 2})
*DBG* <0.1023.0> got call {get,2} from <0.1004.0>
*DBG* <0.1023.0> sent nil to <0.1004.0>, new state #{0 => 0,1 => 1}
nil
iex(3)> GenServer.cast(pid, {:compute, 10})
*DBG* <0.1031.0> got cast {compute,10}
:ok
*DBG* <0.1031.0> new state #{0 => 0,1 => 1,2 => 1,3 => 2,4 => 3,5 => 5,6 => 8,
                             7 => 13,8 => 21,9 => 34,10 => 55}
iex(4)> GenServer.call(pid, {:get, 2})
*DBG* <0.1031.0> got call {get,2} from <0.1029.0>
*DBG* <0.1031.0> sent 1 to <0.1029.0>, new state #{0 => 0,1 => 1,2 => 1,
                                                   3 => 2,4 => 3,5 => 5,
                                                   6 => 8,7 => 13,8 => 21,
                                                   9 => 34,10 => 55}
1

Debugging Processes with Observer in Elixir

If you prefer a more visual approach, Erlang provides an :observer that opens a user interface you can use to browse the Supervision Tree or check process states and messages.

To access this, all you need is:

iex> :observer.start()

While a full review of :observer would take up a whole new post, here is a small demo of all that is possible:

Wrap-up

In this post, we've covered three common methods of debugging: using the IO module, IEx, and visual debugging. We've also touched on debugging Elixir processes using trace and observer.

Elixir's powerful debugging tools are what make it such a compelling language choice for developers and businesses.

Until next time, enjoy getting stuck into debugging code and processes in Elixir!

P.S. If you'd like to read Elixir Alchemy posts as soon as they get off the press, subscribe to our Elixir Alchemy newsletter and never miss a single post!

Pulkit is a senior full-stack engineer and consultant. In his free time, he writes about his experiences on his blog.

An Introduction to Pattern Matching in Ruby

Pulkit Goyal — Wed, 04 Aug 2021 13:46:31 +0000

Let's start with a brief discussion about pattern matching in Ruby, what it does, and how it can help improve code readability.

If you are anything like me a few years ago, you might confuse it with pattern matching in Regex. Even a quick Google search of 'pattern matching' with no other context brings you content that's pretty close to that definition.

Formally, pattern matching is the process of checking any data (be it a sequence of characters, a series of tokens, a tuple, or anything else) against other data.

In terms of programming, depending on the capabilities of the language, this could mean any of the following:

Matching against an expected data type
Matching against an expected hash structure (e.g. presence of specific keys)
Matching against an expected array length
Assigning the matches (or a part of them) to some variables

My first foray into pattern matching was through Elixir. Elixir has first class support for pattern matching, so much so that the = operator is, in fact, the match operator, rather than simple assignment.

This means that in Elixir, the following is actually valid code:

iex> x = 1
iex> 1 = x

With that in mind, let's look at the new pattern matching support for Ruby 2.7+ and how we can use it to make our code more readable, starting from today.

Ruby Pattern Matching with `case`/`in`

Ruby supports pattern matching with a special case/in expression. The syntax is:

case <expression>
in <pattern1>
  # ...
in <pattern2>
  # ...
else
  # ...
end

This is not to be confused with the case/when expression. when and in branches cannot be mixed in a single case.

If you do not provide an else expression, any failing match will raise a NoMatchingPatternError.

Pattern Matching Arrays in Ruby

Pattern matching can be used to match arrays to pre-required structures against data types, lengths or values.

For example, all of the following are matches (note that only the first in will be evaluated, as case stops looking after the first match):

case [1, 2, "Three"]
in [Integer, Integer, String]
  "matches"
in [1, 2, "Three"]
  "matches"
in [Integer, *]
  "matches" # because * is a spread operator that matches anything
in [a, *]
  "matches" # and the value of the variable a is now 1
end

This type of pattern matching clause is very useful when you want to produce multiple signals from a method call.

In the Elixir world, this is frequently used when performing operations that could have both an :ok result and an :error result, for example, inserted into a database.

Here is how we can use it for better readability:

def create
  case save(model_params)
  in [:ok, model]
    render :json => model
  in [:error, errors]
    render :json => errors
  end
end

# Somewhere in your code, e.g. inside a global helper or your model base class (with a different name).
def save(attrs)
  model = Model.new(attrs)
  model.save ? [:ok, model] : [:error, model.errors]
end

Pattern Matching Objects in Ruby

You can also match objects in Ruby to enforce a specific structure:

case {a: 1, b: 2}
in {a: Integer}
  "matches" # By default, all object matches are partial
in {a: Integer, **}
  "matches" # and is same as {a: Integer}
in {a: a}
  "matches" # and the value of variable a is now 1
in {a: Integer => a}
  "matches" # and the value of variable a is now 1
in {a: 1, b: b}
  "matches" # and the value of variable b is now 2
in {a: Integer, **nil}
  "does not match" # This will match only if the object has a and no other keys
end

This works great when imposing strong rules for matching against any params.

For example, if you are writing a fancy greeter, it could have the following (strongly opinionated) structure:

def greet(hash = {})
  case hash
  in {greeting: greeting, first_name: first_name, last_name: last_name}
    greet(greeting: greeting, name: "#{first_name} #{last_name}")
  in {greeting: greeting, name: name}
    puts "#{greeting}, #{name}"
  in {name: name}
    greet(greeting: "Hello", name: name)
  in {greeting: greeting}
    greet(greeting: greeting, name: "Anonymous")
  else
    greet(greeting: "Hello", name: "Anonymous")
  end
end

greet # Hello, Anonymous
greet(name: "John") # Hello, John
greet(first_name: "John", last_name: "Doe") # Hello, John Doe
greet(greeting: "Bonjour", first_name: "John", last_name: "Doe") # Bonjour, John Doe
greet(greeting: "Bonjour") # Bonjour, Anonymous

Variable Binding and Pinning in Ruby

As we have seen in some of the above examples, pattern matching is really useful in assigning part of the patterns to arbitrary variables.
This is called variable binding, and there are several ways we can bind to a variable:

With a strong type match, e.g. in [Integer => a] or in {a: Integer => a}
Without the type specification, e.g. in [a, 1, 2] or in {a: a}.
Without the variable name, which defaults to using the key name, e.g. in {a:} will define a variable named a with the value at key a.
Bind rest, e.g. in [Integer, *rest] or in {a: Integer, **rest}.

How, then, can we match when we want to use an existing variable as a sub-pattern? This is when we can use variable pinning with the ^ (pin) operator:

a = 1
case {a: 1, b: 2}
in {a: ^a}
  "matches"
end

You can even use this when a variable is defined in a pattern itself, allowing you to write powerful patterns like this:

case order
in {billing_address: {city:}, shipping_address: {city: ^city}}
  puts "both billing and shipping are to the same city"
else
  raise "both billing and shipping must be to the same city"
end

One important quirk to mention with variable binding is that even if the pattern doesn't fully match, the variable will still have been bound.
This can sometimes be useful.

But, in most cases, this could also be a cause of subtle bugs — so make sure that you don't rely on shadowed variable values that have been used inside a match.
For example, in the following, you would expect the city to be "Amsterdam", but it would instead be "Berlin":

city = "Amsterdam"
order = {billing_address: {city: "Berlin"}, shipping_address: {city: "Zurich"}}
case order
in {billing_address: {city:}, shipping_address: {city: ^city}}
  puts "both billing and shipping are to the same city"
else
  puts "both billing and shipping must be to the same city"
end
puts city # Berlin instead of Amsterdam

Matching Ruby's Custom Classes

You can implement some special methods to make custom classes pattern matching aware in Ruby.

For example, to pattern match a user against his first_name and last_name, we can define deconstruct_keys on the class:

class User
  def deconstruct_keys(keys)
    {first_name: first_name, last_name: last_name}
  end
end

case user
in {first_name: "John"}
  puts "Hey, John"
end

The keys argument to deconstruct_keys contains the keys that have been requested in the pattern.
This is a way for the receiver to provide only the required keys if computing all of them is expensive.

In the same way as deconstruct_keys, we could provide an implementation of deconstruct to allow objects to be pattern matched as an array.
For example, let's say we have a Location class that has latitude and longitude. In addition to using deconstruct_keys to provide latitude and longitude keys, we could expose an array in the form of [latitude, longitude] as well:

class Location
  def deconstruct
    [latitude, longitude]
  end
end

case location
in [Float => latitude, Float => longitude]
  puts "#{latitude}, #{longitude}"
end

Using Guards for Complex Patterns

If we have complex patterns that cannot be represented with regular pattern match operators, we can also use an if (or unless) statement to provide a guard for the match:

case [1, 2]
in [a, b] if b == a * 2
  "matches"
else
  "no match"
end

Pattern Matching with `=>`/`in` Without `case`

If you are on Ruby 3+, you have access to even more pattern matching magic. Starting from Ruby 3, pattern matching can be done in a single line without a case statement:

[1, 2, "Three"] => [Integer => one, two, String => three]
puts one # 1
puts two # 2
puts three # Three

# Same as above
[1, 2, "Three"] in [Integer => one, two, String => three]

Given that the above syntax does not have an else clause, it is most useful when the data structure is known beforehand.

As an example, this pattern could fit well inside a base controller that allows only admin users:

class AdminController < AuthenticatedController
  before_action :verify_admin

  private

  def verify_admin
    Current.user => {role: :admin}
  rescue NoMatchingPatternError
    raise NotAllowedError
  end
end

Pattern Matching in Ruby: Watch This Space

At first, pattern matching can feel a bit strange to grasp.
To some, it might feel like glorified object/array deconstruction.

But if the popularity of Elixir is any indication, pattern matching is a great tool to have in your arsenal.
Having first-hand experience using it on Elixir, I can confirm that it is hard to live without once you get used to it.

If you are on Ruby 2.7, pattern matching (with case/in) is still experimental. With Ruby 3, case/in has moved to stable while the newly introduced single-line pattern matching expressions are experimental.
Warnings can be turned off with Warning[:experimental] = false in code or -W:no-experimental command-line key.

Even though pattern matching in Ruby is still in its early stages, I hope you've found this introduction useful and that you're as excited as I am about future developments to come!

P.S. If you’d like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Our guest author Pulkit is a senior full-stack engineer and consultant. In his free time, he writes about his experiences on his blog.

Forem: Pulkit Goyal

Managing Distributed State with GenServers in Phoenix and Elixir

Overview of Our Phoenix Application

A Single-Node Rate Limiter Implementation Using GenServer for Elixir

Understanding GenServers in a Distributed Elixir Environment

Implementing Distributed GenServers Using a Single Global Process

Using Multiple Processes Across the Cluster

Starting A One Rate Limiter Per Node

Syncing GenServer State With CRDT

Clustering the GenServers

Handling Cluster Changes

Wrapping Up

LiveState for Elixir: An Overview and How to Build Embeddable Web Apps

Embeddable Web Apps

What is LiveState for Elixir?

More Use Cases

Choosing Between LiveView and LiveState

Example: Creating An Embeddable Phoenix Web App

Step 1: Add Dependencies

Step 2: Update Your Endpoint

Step 3: Create the Phoenix.Socket

Step 4: Define the Channel

Build the Front-End Component with LitElement

Adding New To-dos

Server-Side Handling

Bundle Embed Script

Integrating With JS Frameworks

Wrapping Up

How to Use Flume in your Elixir Application

Oban and Exq: Flume Alternatives for your Elixir App

Installation and Setting Up

Pipelines in Flume for Elixir

Rate Limiting

Batching

Runtime Control

Advanced Features in Flume

Running Flume On Production

Best Practices

Wrapping Up

Keep Your Ruby Code Maintainable with Money-Rails

Use Cases for Storing Money

Storing Money in a Ruby Database

Using a Float Column

Using the numeric Type

Using the integer Type

Enter money-rails for Ruby on Rails

Currency in the money Gem for Ruby

Validations with monetize

Localization

Computations

Currency Exchange

Wrap Up

An Introduction to Exceptions in Elixir

Raising Exceptions in Elixir

Handling Elixir Exceptions

Re-raising Exceptions

Rescue And Catch in Elixir

After and Else Blocks in Elixir

Exceptions and Processes

Monitoring Exceptions

Wrapping Up

An Introduction to Mocking Tools for Elixir

Test Without Mocking Tools in Elixir

Test Stubs

Roll Your Own Server

Elixir Mocking Tools

Mock

Mox

Mock the External Client

Test the External Client

Mimic

Use Mocking Carefully for Your Elixir App

Wrap Up

Database Performance Optimization and Scaling in Rails

Disclaimer: Scaling Isn't Always Needed

A Separate Database for Your Rails Application

Using Read-Only Replicas for Rails

Setting up a Read-Only Replica

Gotchas

Database Sharding in Your Rails Application

Step 3: Create the `Phoenix.Socket`

Build the Front-End Component with `LitElement`

Using the `numeric` Type

Using the `integer` Type

Enter `money-rails` for Ruby on Rails

Currency in the `money` Gem for Ruby

Validations with `monetize`

Profiling with `cprof` in Elixir

`eprof` Profiling in Elixir

Using `fprof` in Elixir

Ruby `debug`

Assert a Single Record with `sole`

1. The IO Module: `puts/2` and `inspect/2`

Ruby Pattern Matching with `case`/`in`

Pattern Matching with `=>`/`in` Without `case`