Add src/hk_event.erl

src/hk_event.erl

@@ -0,0 +1,73 @@
+%%%-------------------------------------------------------------------
+%%% @doc HK-VIS :: Event schema.
+%%%
+%%% Implements the `Event' entity from the data model and the
+%%% append-oriented event model described in the architecture:
+%%% every observable action in the system (agent, browser, search,
+%%% messaging, system) is represented as one immutable `#hk_event{}'
+%%% record with a stable id, a timestamp, a dotted category
+%%% (`agent.created', `browser.navigation.completed', ...), a
+%%% subject (the entity the event is about), and an opaque-to-this-
+%%% module `data' payload map.
+%%%
+%%% This module never inspects `data' -- it only assigns identity
+%%% and timestamp and hands the event to `hk_event_bus'. This keeps
+%%% the event envelope schema decoupled from what any given
+%%% subsystem chooses to report.
+%%% @end
+%%%-------------------------------------------------------------------
+-module(hk_event).
+
+-export([new/3, new/4, to_map/1]).
+
+-export_type([t/0, category/0]).
+
+%% Dotted event category, e.g. <<"agent.action.completed">>.
+-type category() :: binary().
+
+-record(hk_event, {
+    event_id      :: binary(),
+    category      :: category(),
+    %% {Type, Id} identifies the entity the event is about, e.g.
+    %% {agent, <<"agent_...">>} or {browser_session, <<"sess_...">>}.
+    subject       :: {atom(), binary()} | undefined,
+    %% correlation id: links an event back to the operation that
+    %% caused it, when one exists (see hk_schema:operation()).
+    operation_id  :: binary() | undefined,
+    data          :: map(),
+    emitted_at_ms :: integer()
+}).
+
+-opaque t() :: #hk_event{}.
+
+-spec new(category(), {atom(), binary()} | undefined, map()) -> t().
+new(Category, Subject, Data) ->
+    new(Category, Subject, Data, undefined).
+
+-spec new(category(), {atom(), binary()} | undefined, map(), binary() | undefined) -> t().
+new(Category, Subject, Data, OperationId) when is_binary(Category), is_map(Data) ->
+    #hk_event{
+        event_id = hk_id:new(<<"evt">>),
+        category = Category,
+        subject = Subject,
+        operation_id = OperationId,
+        data = Data,
+        emitted_at_ms = hk_id:timestamp_ms()
+    }.
+
+%% @doc Render for JSON transport / the audit log. This is the only
+%% place the wire representation of an event is defined.
+-spec to_map(t()) -> map().
+to_map(#hk_event{event_id = Id, category = Cat, subject = Subj,
+                  operation_id = OpId, data = Data, emitted_at_ms = Ts}) ->
+    #{
+        event_id => Id,
+        category => Cat,
+        subject => case Subj of
+                       {Type, SubjId} -> #{type => Type, id => SubjId};
+                       undefined -> null
+                   end,
+        operation_id => case OpId of undefined -> null; _ -> OpId end,
+        data => Data,
+        emitted_at_ms => Ts
+    }.