Decree.Store.TagIndex (decree v0.1.0)

Copy Markdown View Source

The grammar of the facts that say whether a tag index can be trusted.

A condition finds an event by its tags, so a decision rests on the tag rows being complete. Whether they are is a fact on the ledger, in events the application appends. Decree ships no such event and no command: it ships the grammar, the store's guard on it, and the check a decision runs over it.

The grammar

A fact is an event carrying fact_tag/0, "tag_index:fact", and at least one state tag:

tag_index_state:<family>:<key or ->:<enabled|disabled>

state_tag/3 builds one. <family> is a tag kind and <key> a fingerprint, or - for a family with no key. The store refuses an append, with {:error, :invalid_tag_index_fact} and before any statement, when an event carries a tag_index tag that is not exactly tag_index:fact, a tag_index_state tag that does not parse, or one of the two without the other. A disable with no fact tag would be invisible to the read that finds the facts, so an earlier enable would stand.

tag_index and tag_index_state are reserved_kinds/0. Neither can be declared deletable, and delete_stream_tags refuses them, because a fact whose state tag is gone could have been a disable.

The families

A tag of a kind in named_families/0 is in the family of that kind, and so is a tag of a kind a decision lists in its index_families/0. Any other kind is in the entity family. Decree's own named families are command, command_kind and correlation; the application adds its own kinds through the application environment:

config :decree, :tag_index_named_families, ["tenant_slug", "plan_slug"]

Every node must run the same list for the store's life. The list decides which facts a decision requires, so changing it changes what an existing fact covers, and a kind left out falls into the entity family without a word.

A kind listed :digest holds <fingerprint>:<digest>, and its family's key is that fingerprint: digest_key/1 reads it. Every other family has no key.

The fold

A decision reads the facts in its own read and folds them in position order: the last state per family and key wins, and a family and key with no fact is disabled. A fact the fold cannot attribute, one whose state tags are gone, refuses as a disable would. See "Index facts" in Decree.Decision.

The fingerprint

fingerprint/1 is DOC-1's form: the first 8 bytes of HMAC-SHA-256 keyed by the key material over "tag-digest-fingerprint", in lowercase hex, 16 characters. It is derived from the key material and shows nothing about the key, and it holds no :, so it reads back from a <fingerprint>:<digest> value. It names a digest key without holding it, so one key's tags and its retirement meet under one name. The key and the digests stay the application's.

The lifecycle

  • A fresh store. The application's release step appends the enabling batch only when $all is empty, so the facts sit from position 1 and every later event is covered by them.
  • A store with history. The same step does nothing, and every decision refuses {:error, :tag_index_not_enabled} until a family is repaired and enabled.
  • Repair. A disable for repair, the repair writing the tag rows, then an enable under a new index id. That is the supported way to retag. There is no shadow index to build beside the live one.
  • Retirement. A disable for a family and fingerprint whose key is retired. A key restored later has the same material, so the same fingerprint, and meets that disable.
  • Never deleted. A hard delete of a stream holding a fact, its own or through a link row written before links were removed, answers {:error, :hard_delete_of_index_fact}. A hard delete takes the stream's events from every stream, so a disable gone that way would leave an earlier enable standing. A fact stays for the store's life.

Summary

Functions

The fingerprint a digest tag's value names, {:ok, fingerprint} for <fingerprint>:<digest>, or :error. The value is what follows the tag's kind and its :.

The tag every fact carries.

The fingerprint of a digest key: 16 lowercase hex characters. Raises an ArgumentError for anything but a non-empty binary.

The families that are their own kind's, whatever a decision lists: decree's own command, command_kind and correlation, then the application's :tag_index_named_families, in order. Raises an ArgumentError when that is not a list of tag kinds that are not reserved.

The tag kinds no application tag may hold, and no family is.

A fact's state tag. key is nil for a family with no key. Raises an ArgumentError for a family that is not a tag kind or is reserved, a key that is empty, holds a : or is -, and a state other than :enabled and :disabled.

Types

family()

@type family() :: String.t()

key()

@type key() :: String.t() | nil

state()

@type state() :: :enabled | :disabled

Functions

digest_key(value)

@spec digest_key(term()) :: {:ok, String.t()} | :error

The fingerprint a digest tag's value names, {:ok, fingerprint} for <fingerprint>:<digest>, or :error. The value is what follows the tag's kind and its :.

fact_tag()

@spec fact_tag() :: String.t()

The tag every fact carries.

fingerprint(key_material)

@spec fingerprint(binary()) :: String.t()

The fingerprint of a digest key: 16 lowercase hex characters. Raises an ArgumentError for anything but a non-empty binary.

named_families()

@spec named_families() :: [family()]

The families that are their own kind's, whatever a decision lists: decree's own command, command_kind and correlation, then the application's :tag_index_named_families, in order. Raises an ArgumentError when that is not a list of tag kinds that are not reserved.

reserved_kinds()

@spec reserved_kinds() :: [String.t()]

The tag kinds no application tag may hold, and no family is.

state_tag(family, key, state)

@spec state_tag(family(), key(), state()) :: String.t()

A fact's state tag. key is nil for a family with no key. Raises an ArgumentError for a family that is not a tag kind or is reserved, a key that is empty, holds a : or is -, and a state other than :enabled and :disabled.