brook v0.4.8 Brook

Brook provides an event stream client interface for distributed applications to communicate indirectly and asynchronously. Brook sends and receives messages with the event stream (typically a message queue service) via a driver module and persists an application-specific view of the event stream via a storage module (defaulting to ETS).

Sample Configuration

Brook is configured within the application environment by defining a keyword list with three primary keys: driver, handler, and storage.

config :my_app, :brook,

driver: [
  module: Brook.Driver.Json,
  init_arg: []
],
handler: [MyApp.Event.Handler],
storage: [
  modules: Brook.Storage.Ets,
  init_arg: []
]

Driver

The Brook driver implements a behaviour that sends messages to the event stream. Events are Brook structs that contain an event type, an author (or source), a creation timestamp, the event data, and an ack reference and ack data (following the lead of the broadway library.)

The default driver sends the event message to the Brook server via Genserver.cast

Additional drivers provided at this time are a json-encoding version of the default driver and a Kafka driver using the elsa library.

Handler

The Brook handler implements a behaviour that provides a handle_event/1 function. Handlers receive a Brook event and take appropriate action according to the implementing application's business logic.

Applications implement as many function heads for the event handler as necessary and return one of four tuples depending on how the storage module should treat the event with respect to persistence. Events can:

  • create a record in the view state via the {:create, collection, key, value} return
  • update an existing record via the {:merge, collection, key, value} return
  • delete a record via the {:delete, collection, key} return
  • discard the record and do not effect the persistent view via the :discard return

Storage

The Brook storage module implements yet another behaviour that persists event data to an application view state specific to the application importing the Brook library, allowing the application to only store information received from the event stream that is relevant to its own domain and retrieve it when necessary.

Storage modules implement basic CRUD operations that correlate to the return values of the event handler module.

The default module uses ETS for fast, local, in-memory storage and retrieval (great for testing purposes!) with an additional Redis-based module as well.

Link to this section Summary

Types

The source application generating an event message

The data component of an event message

The catagory of event to contextualize the data of an event message

The name of this instance of Brook

The potential negative return value of a view state query.

The grouping of events by catagory for persisted view storage

The index by which events are stored in a view state collection

The event data stored within a view state collection, indexed by key

Functions

Provides a Brook Supervisor child spec for defining a custom Brook supervisor.

Return an item from the Brook view state for the implementing application wrapped in an :ok tuple or else an :error tuple with a reason.

Returns the value stored under the given key and collection from the Brook view state or else raises an exception.

Return all values saved to the Brook view state for a given collection, wrapped in an :ok tuple or else an :error tuple with reason. Values are returned as a map where the keys are the keys used to index the saved values and the values are anything saved under a given key based on processing events.

Return all values saved to the Brook view state for a given collection or else raises an exception. Values are returned as a map where the keys are the keys used to index the saved values and the values are anything saved under a given key.

Returns a list of all values saved to a given collection of the Brook view state, indepentent of the key used to index them. Results is wrapped in an :ok tuple or else an :error tuple with reason is returned.

Returns a list of all values saved to a given collection of the Brook view state, independent of the key used to index them, or else raises an exception.

Returns a list of Brook events that produced the value stored under the given key within a collection from the Brook view state, wrapped in an :ok tuple or else an :error tuple with reason.

Returns a list of Brook events matching the provided type that produced the value stored under the given key within a collection from the Brook view state, wrapped in an :ok tuple or else an :error tuple with reason.

Returns a list of Brook events that produced the value stored under the given key within a collection from the Brook view state or else raises an exception.

Returns a list of Brook events matching the provided type that produced the value stored under the given key within a collection from the Brook view state or else raises an exception.

Starts a Brook process linked to the current process.

Link to this section Types

Link to this type

author()
author() :: String.Chars.t()

The source application generating an event message

Link to this type

event()
event() :: term()

The data component of an event message

Link to this type

event_type()
event_type() :: String.t()

The catagory of event to contextualize the data of an event message

Link to this type

instance()
instance() :: atom()

The name of this instance of Brook

Link to this type

reason()
reason() :: term()

The potential negative return value of a view state query.

Link to this type

view_collection()
view_collection() :: String.Chars.t()

The grouping of events by catagory for persisted view storage

Link to this type

view_key()
view_key() :: String.Chars.t()

The index by which events are stored in a view state collection

Link to this type

view_value()
view_value() :: term()

The event data stored within a view state collection, indexed by key

Link to this section Functions

Link to this function

child_spec(args)

Provides a Brook Supervisor child spec for defining a custom Brook supervisor.

Link to this function

get(instance, collection, key)
get(instance(), view_collection(), view_key()) ::
  {:ok, view_value()} | {:error, reason()}

Return an item from the Brook view state for the implementing application wrapped in an :ok tuple or else an :error tuple with a reason.

Link to this function

get!(instance, collection, key)

Returns the value stored under the given key and collection from the Brook view state or else raises an exception.

Link to this function

get_all(instance, collection)
get_all(instance(), view_collection()) ::
  {:ok, %{required(view_key()) => view_value()}} | {:error, reason()}

Return all values saved to the Brook view state for a given collection, wrapped in an :ok tuple or else an :error tuple with reason. Values are returned as a map where the keys are the keys used to index the saved values and the values are anything saved under a given key based on processing events.

Link to this function

get_all!(instance, collection)
get_all!(instance(), view_collection()) :: %{
  required(view_key()) => view_value()
}

Return all values saved to the Brook view state for a given collection or else raises an exception. Values are returned as a map where the keys are the keys used to index the saved values and the values are anything saved under a given key.

Link to this function

get_all_values(instance, collection)
get_all_values(instance(), view_collection()) ::
  {:ok, [view_value()]} | {:error, reason()}

Returns a list of all values saved to a given collection of the Brook view state, indepentent of the key used to index them. Results is wrapped in an :ok tuple or else an :error tuple with reason is returned.

Link to this function

get_all_values!(instance, collection)
get_all_values!(instance(), view_collection()) :: [view_value()]

Returns a list of all values saved to a given collection of the Brook view state, independent of the key used to index them, or else raises an exception.

Link to this function

get_events(instance, collection, key)
get_events(instance(), view_collection(), view_key()) ::
  {:ok, [Brook.Event.t()]} | {:error, reason()}

Returns a list of Brook events that produced the value stored under the given key within a collection from the Brook view state, wrapped in an :ok tuple or else an :error tuple with reason.

Link to this function

get_events(instance, collection, key, type)
get_events(instance(), view_collection(), view_key(), event_type()) ::
  {:ok, [Brook.Event.t()]} | {:error, reason()}

Returns a list of Brook events matching the provided type that produced the value stored under the given key within a collection from the Brook view state, wrapped in an :ok tuple or else an :error tuple with reason.

Link to this function

get_events!(instance, collection, key)
get_events!(instance(), view_collection(), view_key()) :: [Brook.Event.t()]

Returns a list of Brook events that produced the value stored under the given key within a collection from the Brook view state or else raises an exception.

Link to this function

get_events!(instance, collection, key, type)
get_events!(instance(), view_collection(), view_key(), event_type()) :: [
  Brook.Event.t()
]

Returns a list of Brook events matching the provided type that produced the value stored under the given key within a collection from the Brook view state or else raises an exception.

Link to this function

start_link(opts)

Starts a Brook process linked to the current process.