Virgil

Virgil is an Elixir library designed to abstract and simplify the utilization of internal circuit breakers within applications. Its primary function is to act as a guardian, ensuring uninterrupted operation even in the face of recurrent errors.

Installation

If available in Hex, the package can be installed by adding virgil to your list of dependencies in mix.exs:

def deps do
  [
    {:virgil, "~> 1.0.4"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/virgil.

Available virgil managers

• Virgil.Manager.ETSManager
• Virgil.Manager.GenserverManager

Custom circuit example

Defining circuit module

You can define a module that represents an application circuit following the example:

defmodule MyCustomCircuit do
  @moduledoc false

  # error_threshold: max number of attempts until the circuit be openned
  # reset_timeout: timeout in seconds until the manager close circuit back
  use Virgil.Circuit,
    error_threshold: 5,
    reset_timeout: 10

  def run(%{document_number: document}) do
    response = Tesla.get("https://my-bureau-api.com/", query: [document: document])

    case response.status do
      200 -> {:ok, response}
      401 -> {:error, :unauthorized}
      500 -> {:error, :api_error}
    end
  end
end

Executing circuit

You can execute the circuit pipeline using the MyCustomCircuit.execute/1 function. This function receives one argument and pass it to the defined MyCustomCircuit:run/1 function.

%{document_number: "11122233300", name: "John Doe"}
|> MyCustomCircuit.execute()

Circuit Flow

flowchart TD
    A[Circuit] -->|execute| C{successful response?}
    C -->|Yes| D[Successful telemetry event]
    C -->|No| E[Failure telemetry event]
    E --> F{Number of failures reached threshold?}
    F -->|Yes| G[Open circuit]
    F -->|No| H[Increase Number of failures]
    G --> I[Schedule process to close circuit back]