Quick start

Message exchange is a widely used pattern in technology world, mainly in microservices ecosystems.

Herald aims to be a tool which allow companies implement this pattern in a simple way, releasing the developers to think in business logic instead details about broker communication, message exchange, etc.

To getting started with Herald, execute the following steps:

Install it

Add in your mix.exs and run mix deps.get:

def deps do
  [
    {:herald, "~> 0.1.0"}
  ]
end

Install broker plugin

Install one of the following libraries:

Create a Message Schema:

In Message Schema you'll defines what is the expected fields for some messages:

defmodule MyApp.UserMessage do
  use Herald.Message

  payload do
    field :id,   :integer, required: true
    field :age,  :integer, required: true
    field :name, :string,  required: true
  end
end

Create processor function

Processor function will work as a callback function when a message is received. In our case, we created the message in the same module of MyApp.UserMessage, but your can create where your business logic requires:

defmodule MyApp.UserMessage do
  use Herald.Message

  payload do
    field :id,   :integer, required: true
    field :age,  :integer, required: true
    field :name, :string,  required: true
  end

  def my_processor(%MyApp.UserMessage{} = message) do
    if do_some_stuff_with(message) do
      {:ok, message}
    else
      {:error, :my_bad_error}
    end
  end
end

Processor return

The processor function return must match with one of the following expressions:

{:ok, _} - When desired operation is processed with success. Message will be acknowledged in broker, if needed;
{:error, _} - When processor don't reached the desired result. Message will be rejected in broker;
{:error. :delete, _} - The same of {:error, _}, but message will be deleted from broker, if needed.

Create Router

Router will tell for Herald what Message Schema and processor use for process each message received.

In example bellow, any message received in queue user:created will be validated by schema MyApp.UserMessage and processed by function &MyApp.UserMessage.func/1:

defmodule MyApp.Router do
  use Herald.Router

  route "user:created",
    schema: MyApp.UserMessage,
    processor: &MyApp.UserMessage.func/1
end

Configure app

Finaly, need inform Herald what is the module where Router is configured:

config :herald,
  router: MyApp.Router

v0.1.0