Outboxer.Message behaviour (Outboxer v0.1.0)

Copy Markdown View Source

The behaviour every outbox message implements.

A message is a plain struct. use Outboxer.Message gives it sensible defaults for every callback, so the smallest message is:

defmodule MyApp.Events.OrderPlaced do
  use Outboxer.Message, outbox: :orders

  defstruct [:order_id, :total]
end

and a message that takes part in ordered delivery adds a group key:

defmodule MyApp.Events.OrderPlaced do
  use Outboxer.Message, outbox: :orders, type: "order.placed"

  defstruct [:order_id, :total]

  @impl true
  def group_key(%__MODULE__{order_id: id}), do: "order:#{id}"
end

Options for use

  • :outbox - the outbox this message is published to. Can be overridden per call with Outboxer.publish(msg, outbox: :other).
  • :type - the type string stored with the message and passed to the relay. Defaults to the module name without the Elixir. prefix.

Callbacks and their defaults

CallbackDefault
outbox/0the :outbox option, or nil (then you must pass outbox: to publish)
type/0the :type option, or the module name
encode/1JSON.encode!/1 of the struct's fields
group_key/1nil (unordered)
headers/1%{}

Encoding

The payload is stored as an opaque binary, so encode/1 may return JSON, Protobuf, Avro or anything else. The default uses Elixir's built-in JSON module on Map.from_struct/1; if your struct holds values JSON cannot encode (other structs without a JSON.Encoder implementation, tuples, pids) implement encode/1 yourself.

Summary

Callbacks

encode(message)

Serialises the message to the binary that will be stored and relayed.

group_key(message)

The ordering group of the message, or nil when it does not need ordering.

headers(message)

String headers stored with the message and passed to the relay.

outbox()

The outbox this message goes to by default.

type()

A stable type name for this kind of message.

Callbacks

encode(message)

@callback encode(message :: struct()) :: binary()

Serialises the message to the binary that will be stored and relayed.

group_key(message)

@callback group_key(message :: struct()) :: String.t() | nil

The ordering group of the message, or nil when it does not need ordering.

Messages with the same group key in the same outbox are delivered in the order they were published. See the "Ordering and groups" guide.

headers(message)

@callback headers(message :: struct()) :: %{optional(String.t()) => String.t()}

String headers stored with the message and passed to the relay.

outbox()

@callback outbox() :: atom() | nil

The outbox this message goes to by default.

type()

@callback type() :: String.t()

A stable type name for this kind of message.