brook v0.4.1 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 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
author()
author() :: String.Chars.t()
author() :: String.Chars.t()
The source application generating an event message
event()
event() :: term()
event() :: term()
The data component of an event message
event_type()
event_type() :: String.t()
event_type() :: String.t()
The catagory of event to contextualize the data of an event message
instance()
instance() :: atom()
instance() :: atom()
The name of this instance of Brook
reason()
reason() :: term()
reason() :: term()
The potential negative return value of a view state query.
view_collection()
view_collection() :: String.Chars.t()
view_collection() :: String.Chars.t()
The grouping of events by catagory for persisted view storage
view_key()
view_key() :: String.Chars.t()
view_key() :: String.Chars.t()
The index by which events are stored in a view state collection
view_value()
view_value() :: term()
view_value() :: term()
The event data stored within a view state collection, indexed by key
Link to this section Functions
child_spec(args)
Provides a Brook Supervisor child spec for defining a custom Brook supervisor.
get(instance, collection, key)
get(instance(), view_collection(), view_key()) ::
{:ok, view_value()} | {:error, reason()}
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.
get!(instance, collection, key)
get!(instance(), view_collection(), view_key()) :: view_value()
get!(instance(), view_collection(), view_key()) :: view_value()
Returns the value stored under the given key and collection from the Brook view state or else raises an exception.
get_all(instance, collection)
get_all(instance(), view_collection()) ::
{:ok, %{required(view_key()) => view_value()}} | {:error, reason()}
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.
get_all!(instance, collection)
get_all!(instance(), view_collection()) :: %{
required(view_key()) => view_value()
}
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.
get_all_values(instance, collection)
get_all_values(instance(), view_collection()) ::
{:ok, [view_value()]} | {:error, reason()}
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.
get_all_values!(instance, collection)
get_all_values!(instance(), view_collection()) :: [view_value()]
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.
get_events(instance, collection, key)
get_events(instance(), view_collection(), view_key()) ::
{:ok, [Brook.Event.t()]} | {:error, reason()}
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.
get_events!(instance, collection, key)
get_events!(instance(), view_collection(), view_key()) :: [Brook.Event.t()]
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.
start_link(opts)
Starts a Brook process linked to the current process.