DEV Community: Artur Plysiuk

You're probably underusing middleware for HTTP response handling

Artur Plysiuk — Sun, 17 May 2026 21:08:32 +0000

When you wrap an external API in Elixir, most of what a function like Acme.fetch_user/1 does is response handling: validate the status, parse the body, translate failures. That code almost always lives after the Tesla.get call, in a case or a handle_response/1 at the end of a |> pipeline.

That's the wrong place. A middleware can return {:error, ...} from Tesla.run, which makes Tesla's telemetry event record the request as failed. A function called after Tesla.get can't do that. It only sees the result. Failures it detects don't reach telemetry, so your observability stack undercounts them.

Code samples use Tesla. Same shapes apply to Req. Pick whichever you're using and translate as you go.

Real APIs don't read their own docs

Real APIs are dirtier than tutorial examples. A few I've run into:

I've seen well-known, large providers respond with bodies that fail to parse. Yup, broken JSON
A field documented as a boolean returns the JSON string "true" for true and, the JSON string "No" for false.
A field documented as a string returns "N/A", or just "", to mean NULL.

Your API client translates external bytes into something your application can rely on, and that parsing can fail. Malformed JSON already makes Tesla return {:error, ...}. A malformed value inside a well-formed JSON is the same failure, one layer up.

The pattern that fails

Here is a fetch_user/1 written in a pattern I see a lot. handle_response/1 is a shared helper: every endpoint in the module funnels through it. fetch_user, create_user, delete_invoice all end with |> handle_response(): one place for the wrap, one place for error translation. Here is just one endpoint to keep the example small.

def fetch_user(id) do
  case client() |> Tesla.get("/users/#{id}") |> handle_response() do
    {:ok, body} -> {:ok, decode_user(body)}
    {:error, :not_found} -> {:error, :not_found}
    _ -> {:error, :service_unavailable}
  end
end

defp handle_response({:ok, %Tesla.Env{status: status, body: body}})
     when status in 200..299 do
  {:ok, body}
end

defp handle_response({:ok, %Tesla.Env{status: 404}}) do
  {:error, :not_found}
end

defp handle_response({:ok, %Tesla.Env{status: status, body: body}}) do
  Logger.error("Acme API returned unexpected status #{status}: #{inspect(body)}")
  {:error, {:unexpected_status, status, body}}
end

defp handle_response(result), do: result

defp decode_user(body) do
  {:ok, created_at, _} = DateTime.from_iso8601(body["created_at"])

  %{
    id: body["id"],
    first_name: body["first_name"],
    last_name: body["last_name"],
    email: body["email"],
    created_at: created_at
  }
end

When the API returns a 500, handle_response/1 produces {:error, {:unexpected_status, 500, body}}, the case falls through to _ -> {:error, :service_unavailable}, and the caller gets a clean tagged tuple. The function itself is doing nothing wrong.

Tesla considers the request successful. The middleware chain returned {:ok, env}. The standard [:tesla, :request, :stop] telemetry event records it as :ok. Tesla.Middleware.Retry, whose default should_retry matches {:error, _}, sees {:ok, env} and doesn't fire. The 500 only becomes an "error" inside handle_response/1's return value and the surrounding case. That's application code, after the request is done.

The Logger.error inside handle_response/1 is a patch for this. Telemetry doesn't catch the 5xx, so someone adds a log line by hand. The error reaches the logs but skips the telemetry pipeline, and every API client module grows its own version.

Body parsing has the same hole. decode_user/1 returns the user map directly and can't signal a parse error. If the API renames email to email_address, body["email"] is nil and the caller gets a user with nil in the email field. If body["created_at"] is missing or malformed, DateTime.from_iso8601/1 returns {:error, _} and the {:ok, created_at, _} = ... match raises a MatchError. Phoenix or Oban catches the exception, but Tesla still considers the request successful and the telemetry event still says :ok.

Middleware can fail the request

When a middleware returns {:error, ...} from Tesla.run, the request short-circuits. The Telemetry middleware emits [:tesla, :request, :stop] with error: reason in the metadata, and Tesla.get returns {:error, ...} (or Tesla.get! raises a Tesla.Error). A handle_response/1 chained after the call only sees the result, so any failure it spots stays out of telemetry.

A 404 from fetch_user/1 means the user doesn't exist, return {:error, :not_found}. A 404 from POST /users means the route isn't there, which is a bug to crash on. Same status, different meaning. The middleware can't decide globally what counts as "ok"; the caller has to declare it.

Doing it in middleware

The middleware takes a per-call map of expected statuses and how to parse their bodies. Here's fetch_user/1 using it:

def fetch_user(id) do
  case Tesla.get(client(), "/users/#{id}",
         opts: [
           parse_body: %{
             200 => &decode_user/1,
             404 => fn _ -> {:ok, nil} end
           }
         ]) do
    {:ok, %Tesla.Env{status: 200, body: user}} -> {:ok, user}
    {:ok, %Tesla.Env{status: 404}} -> {:error, :not_found}
    {:error, _} -> {:error, :service_unavailable}
  end
end

defp decode_user(body) do
  with :ok <- check_required(body, ["id", "first_name", "last_name", "email", "created_at"]),
       {:ok, created_at, _} <- DateTime.from_iso8601(body["created_at"]) do
    {:ok,
     %{
       id: body["id"],
       first_name: body["first_name"],
       last_name: body["last_name"],
       email: body["email"],
       created_at: created_at
     }}
  end
end

defp check_required(body, fields) do
  case Enum.filter(fields, &is_nil(Map.get(body, &1))) do
    [] -> :ok
    missing -> {:error, {:missing_fields, missing}}
  end
end

The middleware behind parse_body:

defmodule ParseBody do
  @behaviour Tesla.Middleware

  @impl true
  def call(env, next, _opts) do
    with {:ok, env} <- Tesla.run(env, next) do
      parsers = Keyword.fetch!(env.opts, :parse_body)

      case Map.fetch(parsers, env.status) do
        :error ->
          {:error,
           {:unexpected_status,
            status: env.status, expected: Map.keys(parsers), body: env.body}}

        {:ok, parser} ->
          case parser.(env.body) do
            {:ok, parsed} ->
              {:ok, %{env | body: parsed}}

            {:error, reason} ->
              {:error,
               {:parse_error, status: env.status, reason: reason, body: env.body}}
          end
      end
    end
  end
end

Parser failures short-circuit with and become failed Tesla requests, not a separate validation step the caller has to remember. They fire the same [:tesla, :request, :stop] event as any other failure, with the error in metadata.

The handle_response/1 helper is gone. The when status in 200..299 guard is gone. The Logger.error is gone too. Telemetry handles the logging now.

{:error, _} in fetch_user/1 swallows the structured errors, so the function doesn't need to unpack them.

Order matters when wiring it in. ParseBody goes after Tesla.Middleware.Telemetry (so Telemetry records its {:error, _} as the request's result) and before Tesla.Middleware.JSON (so the body is already decoded when ParseBody sees it):

defp client do
  Tesla.client([
    {Tesla.Middleware.BaseUrl, "https://api.acme.com"},
    {Tesla.Middleware.Telemetry, metadata: %{service: :acme}},
    ParseBody,
    Tesla.Middleware.JSON
  ])
end

A note on `Tesla.get!`

If retrying or falling back on a transient outage isn't part of how the caller actually behaves, :service_unavailable is ceremony. Application code doesn't pattern-match {:error, :service_unavailable} on every Repo.get/2. We assume the database works; if it doesn't, the request crashes and the supervisor or web framework deals with it.

You can apply the same discipline to an external API. Use Tesla.get! instead of Tesla.get, drop :service_unavailable from the contract, and let any failed request become a Tesla.Error exception. Phoenix turns it into a 500. Oban retries the job. The two clauses left in fetch_user/1 collapse to:

case Tesla.get!(...) do
  %Tesla.Env{status: 200, body: user} -> {:ok, user}
  %Tesla.Env{status: 404} -> {:error, :not_found}
end

Whether to do this depends on the API's stability and the caller's context.

When it wants to be data

Most parsers are boilerplate: required fields, ISO timestamps, nullability checks. A schema handles that better than a function. tesla_middleware_mold and Mold give you that. fetch_user/1 with a schema:

def fetch_user(id) do
  case Tesla.get(client(), "/users/#{id}", opts: [mold: %{200 => user_schema(), 404 => nil}]) do
    {:ok, %Tesla.Env{status: 200, body: user}} -> {:ok, user}
    {:ok, %Tesla.Env{status: 404}} -> {:error, :not_found}
    {:error, _} -> {:error, :service_unavailable}
  end
end

defp user_schema do
  %{
    id: :string,
    first_name: :string,
    last_name: :string,
    email: :string,
    created_at: :datetime
  }
end

200 => schema runs Mold.parse/2. 404 => nil accepts the response without parsing. Anything else fails the request.

The function shape Mold accepts as a parser is the same one the middleware accepts (body -> {:ok, term} | {:error, reason}), so you can mix schemas with hand-written parsers in the same map, depending on which is cleaner for which response.

Nothing in this article requires tesla_middleware_mold. The hand-rolled ParseBody above is around 20 lines once you collapse the formatting; dropping it into your own codebase gives you the same telemetry behavior. Reach for the library when you also want to stop hand-writing parsers.

Writing dynamic Ecto queries with Composite

Artur Plysiuk — Mon, 19 Feb 2024 18:46:02 +0000

There is already an existing article in Ecto docs about dynamic queries https://hexdocs.pm/ecto/dynamic-queries.html so you might think why another article is needed.

Indeed, the article from docs contains a solid foundation. However, I suggest organizing the final code differently. Let's examine the code:

def filter(params) do
  Post
  |> join(:inner, [p], assoc(p, :authors), as: :authors)
  |> order_by(^filter_order_by(params["order_by"]))
  |> where(^filter_where(params))
end

def filter_order_by("published_at_desc"),
  do: [desc: dynamic([p], p.published_at)]

def filter_order_by("published_at"),
  do: dynamic([p], p.published_at)

def filter_order_by("author_name_desc"),
  do: [desc: dynamic([authors: a], a.name)]

def filter_order_by("author_name"),
  do: dynamic([authors: a], a.name)

def filter_order_by(_),
  do: []

def filter_where(params) do
  Enum.reduce(params, dynamic(true), fn
    {"author", value}, dynamic ->
      dynamic([authors: a], ^dynamic and a.name == ^value)

    {"category", value}, dynamic ->
      dynamic([p], ^dynamic and p.category == ^value)

    {"published_at", value}, dynamic ->
      dynamic([p], ^dynamic and p.published_at > ^value)

    {_, _}, dynamic ->
      # Not a where parameter
      dynamic
  end)
end

One of the goals of the article was to demonstrate the use of the Ecto.Query.dynamic/2 macro. However, dynamic queries are not only about the usage of the Ecto.Query.dynamic/2 macro. Ecto queries are composable by design. Therefore, writing dynamic Ecto queries is all about the optional application of functions. The ultimate aim is to compose a query by given input parameters and Ecto.Query.dynamic/2 may not be needed at all.

I've observed various approaches to writing dynamic Ecto queries.
While I won't list them here, the Composite library is a result of refactoring those places.

Let's look at the alternative implementation with Composite:

def filter(params) do
  Post
  |> join(:inner, [p], assoc(p, :authors), as: :authors)
  |> Composite.new(params)
  |> Composite.param("order_by", &order_by(&1, ^order_instructions(&2)))
  |> Composite.param("author", &where(&1, [authors: a], a.name == ^name))
  |> Composite.param("category", &where(&1, category: ^&2))
  |> Composite.param("published_at", &where(&1, [p], p.published_at > ^&2))
end

defp order_instructions(value) do
  case value do
    "published_at_desc" -> [desc: :published_at]
    "published_at" -> [:published_at]
    "author_name_desc" -> [desc: dynamic([authors: a], a.name)]
    "author_name" -> dynamic([authors: a], a.name)
  end
end

Apart from having fewer lines of code, this implementation places all used parameters at the top level, eliminating the need to delve deep into the implementation of nested functions. Essentially, it resembles a router.
Composite.new/2 wraps the Ecto query into a Composite struct.

Composite.param/3 function calls define how to modify a query if a given parameter is present. The presence of the parameter is controlled by the :ignore? option, which ignores the following values by default: nil, "", [], %{}.

The third argument of the Composite.param/3 function is a modifier function for the query. An important property of this function is that the first argument is an Ecto query, and the second argument is a value of the specified parameter. This is important, because this is one of the default patterns when writing Ecto queries, as it allows sequential composition using a pipe operator. Thus, with the named function the last instruction can be written as:

# ...
|> Composite.param("published_at", &posts_published_after/2)
# ...
def posts_published_after(query, value) do
  where(query, [p], p.published_at > ^value)
end

You may have noticed, that the :authors association is always joined at the beginning of the query. It would be more efficient to optimize this part and join the association only when needed based on the input parameters. Composite can handle this by using dependencies. Each dependency is declared with the loader function which will be invoked before invoking the parameter handler.

def filter(params) do
  Post
  |> Composite.new(params)
  |> Composite.param(
    "order_by",
    fn query, value -> order_by(query, ^order_instructions(value)) end,
    requires: fn
      "author_name" -> :authors
      "author_name_desc" -> :authors
      _ -> nil
    end
  )
  |> Composite.param("author", &where(&1, [authors: a], a.name == ^&2), requires: :authors)
  |> Composite.param("category", &where(&1, category: ^&2))
  |> Composite.param("published_at", &where(&1, [p], p.published_at > ^&2))
  |> Composite.dependency(:authors, &join(&1, :inner, [p], assoc(p, :authors), as: :authors))
end

defp order_instructions(value) do
  case value do
    "published_at_desc" -> [desc: :published_at]
    "published_at" -> [:published_at]
    "author_name_desc" -> [desc: dynamic([authors: a], a.name)]
    "author_name" -> dynamic([authors: a], a.name)
  end
end

To convert the struct back to Ecto query, we can call Composite.apply/1 function at the end of the chain. This is done automatically by Ecto when you invoke functions from Ecto.Repo or Ecto.Query modules, because Composite implements the Ecto.Queryable protocol.

%{"category" => "Open Source"}
|> filter()
|> Composite.apply()
#Ecto.Query<from p0 in Post, where: p0.category == ^"Open Source">

%{
  "category" => "Open Source",
  "author" => "John Doe",
  "order_by" => "author_name"
}
|> filter()
|> Composite.apply()
# #Ecto.Query<from p0 in Post, join: a1 in assoc(p0, :authors), as: :authors,
#  where: a1.name == ^"John Doe", where: p0.category == ^"Open Source",
#  order_by: [asc: a1.name]>

This article doesn't describe all the features of Composite because the initial example is not very complex, reach out to docs for details. Source code is available on GitHub

That's it. Hope this helps :)