gmtprime/yggdrasil

Yggdrasil is an immense mythical tree that connects the nine worlds in Norse cosmology.

Yggdrasil is an agnostic publisher/subscriber:

• Multi-node pubsub.
• Simple API (subscribe/1, unsubscribe/1, publish/2).
• GenServer wrapper for handling subscriber events easily.
• Several fault tolerant adapters:
  • RabbitMQ
  • PostgreSQL
  • Redis
  • GraphQL

Small Example

The following example uses the Elixir distribution to send the messages:

iex(1)> Yggdrasil.subscribe(name: "my_channel")
iex(2)> flush()
{:Y_CONNECTED, %Yggdrasil.Channel{...}}

and to publish a for the subscribers:

iex(3)> Yggdrasil.publish([name: "my_channel"], "message")
iex(4)> flush()
{:Y_EVENT, %Yggdrasil.Channel{...}, "message"}

When the subscriber wants to stop receiving messages, then it can unsubscribe from the channel:

iex(6)> Yggdrasil.unsubscribe(name: "my_channel")
iex(7)> flush()
{:Y_DISCONNECTED, %Yggdrasil.Channel{...}}

For convinience, Yggdrasil is also a GenServer wrapper for subscribing to one or several channels e.g the following Subscriber prints every message it receives from the channel [name: "my_channel"]:

defmodule Subscriber do
  use Yggdrasil

  def start_link do
    channel = [name: "my_channel"]
    Yggdrasil.start_link(__MODULE__, [channel])
  end

  @impl true
  def handle_event(_channel, message, _state) do
    IO.inspect message
    {:ok, nil}
  end
end

Channels

Channels, though internally use the struct Yggdrasil.Channel.t(), they can be any map or keyword list with the following keys:

This means that the channel [name: "my_channel"] actually translates to:

%Yggdrasil.Channel{
  adapter: :elixir,
  name: "my_channel",
  transformer: :default,
  backend: :default,
  namespace: nil
}

Adapters

An adapter is the implementation of the behaviour Yggdrasil.Adapter. This behaviour depends on two other behaviours:

• Yggdrasil.Subscriber.Adapter for implementing subscribers for a specific adapter.
• Yggdrasil.Publisher.Adapter for implementing publishers for a specific adapter.

The following are the available adapters and their respective projects:

For more information on how to use them, check the corresponding repository documentation.

Transformers

A transformer is the implementation of the behaviour Yggdrasil.Transformer. In essence implements two functions:

• decode/2 for decoding messages coming from the adapter.
• encode/2 for encoding messages going to the adapter

Yggdrasil has two implemented transformers:

Backends

A backend is the implementation of the behaviour Yggdrasil.Backend. The module is in charge of distributing the messages with a certain format inside Yggdrasil. Currently, there is only one backend, :default, and it is used by default. It uses Phoenix.PubSub to distribute the messages.

The messages received by the subscribers when using :default backend are:

• {:Y_CONNECTED, Yggdrasil.Channel.t()} when the connection with the adapter is established.
• {:Y_EVENT, Yggdrasil.Channel.t(), message()} when a message is received from the adapter.
• {:Y_DISCONNECTED, Yggdrasil.Channel.t()} when the connection with the adapter is finished due to disconnection or unsubscription.

This backend is the only backend supported by Yggdrasil behaviour.

Multi node

Though :elixir adapter has built-in support for multi node pubsub, that's not the case with the other adapters. To overcome this limitation, :bridge adapter is capable of connecting to a remote adapter if and only if this adapter is not present in the current node e.g. let's say we have the following scenario:

• Node A has :yggdrasil.
• Node B has :yggdrasil_rabbitmq.
• The nodes A and B are connected.

Then is possible for the node A to connect to RabbitMQ through node B by using the :bridge adapter:

For subscription:

iex(1)> channel = [
...(1)>   name: [name: {"amq.topic", "foo"}, adapter: :rabbitmq],
...(1)>   adapter: :bridge
...(1)> ]
iex(2)> Yggdrasil.subscribe(channel)
iex(3)> flush()
{:Y_CONNECTED, %Yggdrasil.Channel{(...)}}

and for publishing:

iex(1)> channel = [
...(1)>   name: [name: {"amq.topic", "foo"}, adapter: :rabbitmq],
...(1)>   adapter: :bridge
...(1)> ]
iex(2)> Yggdrasil.publish(channel, "bar")
:ok

Configuration

Yggdrasil works out of the box with no special configuration at all. However, it is possible to tune the publisher pool:

For more information about configuration using OS environment variables check the module Yggdrasil.Config.

Installation

Yggdrasil is available as a Hex package. To install, add it to your dependencies in your mix.exs file:

• For Elixir < 1.8 and Erlang < 21

  def deps do
    [{:yggdrasil, "~> 4.1"}]
  end

• For Elixir ≥ 1.8 and Elixir < 1.12 and Erlang ≥ 21 and Erlang < 23

  def deps do
    [{:yggdrasil, "~> 5.0"}]
  end

• For Elixir Elixir ≥ 1.12 and Erlang ≥ 23

  def deps do
    [{:yggdrasil, "~> 6.0"}]
  end

Author

Alexander de Sousa.

License

Yggdrasil is released under the MIT License. See the LICENSE file for further details.