Brook (brook_stream v1.0.0)
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
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
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
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
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
author()
@type author() :: String.Chars.t()
The source application generating an event message
event()
@type event() :: term()
The data component of an event message
event_type()
@type event_type() :: String.t()
The catagory of event to contextualize the data of an event message
instance()
@type instance() :: atom()
The name of this instance of Brook
reason()
@type reason() :: term()
The potential negative return value of a view state query.
view_collection()
@type view_collection() :: String.Chars.t()
The grouping of events by catagory for persisted view storage
view_key()
@type view_key() :: String.Chars.t()
The index by which events are stored in a view state collection
view_value()
@type 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.
deserialize(string)
get(instance, collection, key)
@spec 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)
@spec 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)
@spec 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)
@spec 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)
@spec 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)
@spec 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)
@spec 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, type)
@spec 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.
get_events!(instance, collection, key)
@spec 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.
get_events!(instance, collection, key, type)
@spec 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.
serialize(data)
start_link(opts)
Starts a Brook process linked to the current process.