hecate_om_service behaviour (hecate_om v0.19.0)
View SourceSummary
Callbacks
Capabilities this service exposes, to be advertised on the mesh. Other services find this one by these names. A capability whose map includes handler => {HandlerModule, Args}' (HandlerModule implementing themacula_response' behaviour) is advertised via macula_response:advertise_direct/7' -- discoverable AND directly callable. A capability with nohandler' key is written as a bare discovery record only (today's behavior, kept for services that advertise a capability another mechanism serves).
OPTIONAL. The on-disk root for this service's reckon-db store. The store data lands at data_dir/store_id.
Snapshot of current health. Called every /health hit.
UCAN this service wants minted by hecate-realm at boot. Until UCAN-delegation lands in realm, this is informational only.
Static metadata about the service. Reported on /health.
OPTIONAL. The barrel_docdb database name this service's read model lives in (lowercase alphanumerics/underscore/hyphen, 1-63 chars — see barrel_docdb:validate_db_name/1). When exported alongside data_dir/0, hecate_om:boot/1 opens the database at data_dir/read_model_id before calling ServiceMod:start/1. PRJ code writes to it with barrel_docdb directly, using this same name as the database handle — there is no separate accessor to call first. Independent of store_id/0: a service may have a read model, an event store, both, or neither.
Start the service's supervision tree. Called once on boot.
Stop the service. Called on shutdown.
OPTIONAL. The reckon-db store_id this service owns. When exported alongside data_dir/0, hecate_om:boot/1 auto-starts the store and the per-store evoq subscription before the service module's own start/1 fires.
OPTIONAL. The reckon-db secondary index declarations this service's store maintains, e.g. [tags, event_type, {payload, <<"plate">>}, {payload_hash, [<<"lot_id">>, <<"plate">>]}]. When exported alongside store_id/0 + data_dir/0, hecate_om:boot/1 installs these on the auto-started store so CCC payload indexes are declared. Omit for a store with no secondary indexes.
OPTIONAL. The reckon-db integrity config for the store: disabled' (default), or#{enabled => true, key_source => {env_var, Name} | {sealed_file, Path}}' to enable per-store HMAC event tamper-resistance. When exported, hecate_om:boot/1 threads it into the store config. The store refuses to start if integrity is enabled but the key cannot be loaded, so provision the key before enabling.
OPTIONAL. The reckon-db store mode: single (default) or cluster. cluster makes reckon-db discover peers and form a Ra cluster across every node that starts the same store_id (RF = number of such nodes). When exported alongside store_id/0 + data_dir/0, hecate_om:boot/1 auto-starts the store in this mode. Omit for a standalone single-node store.
OPTIONAL. Topics this service subscribes to at boot: a list of {Topic, HandlerModule, Args} triples, HandlerModule implementing the `macula_subscriber' behaviour. hecate_om:boot/1 wires each into a supervised macula_subscriber under hecate_om_pubsub_sup before the service module's own start/1 runs. Call hecate_om_pubsub:ensure_subscriptions/1 again whenever the desired set changes at runtime (e.g. a new topic per newly-registered entity) -- it diffs against what's currently running and starts/stops only the delta.
Types
-type capability() :: #{name := binary(), version := pos_integer(), handler => {module(), term()}, auth => open | {ucan_required, <<_:256>>}, kind => response | streamer, stream_opts => #{mode => server_stream | client_stream}}.
-type identity_spec() :: #{scope := binary(), actions := [binary()], resources := [binary()], ttl_days := pos_integer()}.
Callbacks
-callback capabilities() -> [capability()].
Capabilities this service exposes, to be advertised on the mesh. Other services find this one by these names. A capability whose map includes handler => {HandlerModule, Args}' (HandlerModule implementing themacula_response' behaviour) is advertised via macula_response:advertise_direct/7' -- discoverable AND directly callable. A capability with nohandler' key is written as a bare discovery record only (today's behavior, kept for services that advertise a capability another mechanism serves).
-callback data_dir() -> string().
OPTIONAL. The on-disk root for this service's reckon-db store. The store data lands at data_dir/store_id.
-callback health() -> health().
Snapshot of current health. Called every /health hit.
-callback identity_spec() -> identity_spec().
UCAN this service wants minted by hecate-realm at boot. Until UCAN-delegation lands in realm, this is informational only.
-callback info() -> info().
Static metadata about the service. Reported on /health.
-callback read_model_id() -> binary().
OPTIONAL. The barrel_docdb database name this service's read model lives in (lowercase alphanumerics/underscore/hyphen, 1-63 chars — see barrel_docdb:validate_db_name/1). When exported alongside data_dir/0, hecate_om:boot/1 opens the database at data_dir/read_model_id before calling ServiceMod:start/1. PRJ code writes to it with barrel_docdb directly, using this same name as the database handle — there is no separate accessor to call first. Independent of store_id/0: a service may have a read model, an event store, both, or neither.
Start the service's supervision tree. Called once on boot.
-callback stop(term()) -> ok.
Stop the service. Called on shutdown.
-callback store_id() -> atom().
OPTIONAL. The reckon-db store_id this service owns. When exported alongside data_dir/0, hecate_om:boot/1 auto-starts the store and the per-store evoq subscription before the service module's own start/1 fires.
-callback store_indexes() -> [term()].
OPTIONAL. The reckon-db secondary index declarations this service's store maintains, e.g. [tags, event_type, {payload, <<"plate">>}, {payload_hash, [<<"lot_id">>, <<"plate">>]}]. When exported alongside store_id/0 + data_dir/0, hecate_om:boot/1 installs these on the auto-started store so CCC payload indexes are declared. Omit for a store with no secondary indexes.
-callback store_integrity() -> disabled | map().
OPTIONAL. The reckon-db integrity config for the store: disabled' (default), or#{enabled => true, key_source => {env_var, Name} | {sealed_file, Path}}' to enable per-store HMAC event tamper-resistance. When exported, hecate_om:boot/1 threads it into the store config. The store refuses to start if integrity is enabled but the key cannot be loaded, so provision the key before enabling.
-callback store_mode() -> single | cluster.
OPTIONAL. The reckon-db store mode: single (default) or cluster. cluster makes reckon-db discover peers and form a Ra cluster across every node that starts the same store_id (RF = number of such nodes). When exported alongside store_id/0 + data_dir/0, hecate_om:boot/1 auto-starts the store in this mode. Omit for a standalone single-node store.
OPTIONAL. Topics this service subscribes to at boot: a list of {Topic, HandlerModule, Args} triples, HandlerModule implementing the `macula_subscriber' behaviour. hecate_om:boot/1 wires each into a supervised macula_subscriber under hecate_om_pubsub_sup before the service module's own start/1 runs. Call hecate_om_pubsub:ensure_subscriptions/1 again whenever the desired set changes at runtime (e.g. a new topic per newly-registered entity) -- it diffs against what's currently running and starts/stops only the delta.