Kathikon.Storage behaviour (Kathikon v0.2.1)

Copy Markdown View Source

Storage behaviour and facade for job persistence.

Application code should prefer Kathikon.insert/3 and management APIs. Configure the backend via config :kathikon, storage_backend: module.

Default: Kathikon.Storage.Mnesia.

Examples

:ok = Kathikon.Storage.setup()

# Tests and Livebook embedding
Kathikon.Storage.reset!()

See docs/storage.md.

Summary

Types

job()

Callbacks

all()
cancel_job(t, term, map)
claim(atom, t)
claim_and_start_available_jobs(atom, pos_integer, map)
claim_available_jobs(atom, pos_integer, map)
claim_job(t, map)
clear_jobs!()
complete_job(t, term, map)
defer_job(t, t, map)
delete(t)
discard_job(t, term, map)
fail_job(t, term, map)
fetch(t)
get_job(t)
insert(t)
insert_history_event(t, map)
insert_job(job)
list_dead_jobs(keyword)
list_history(t)
list_jobs(keyword)
list_jobs_page(keyword)
move_to_dead_letter(t, term, map)
promote_scheduled(t)
prunable_jobs(t)
reset!()
retry_job(t, keyword)
setup()
start_job(t, map, t)
update(t)
update_job(t, map)

Functions

setup()

Ensures the storage backend schema and tables exist.

Types

job()

@type job() :: Kathikon.Job.t() | map()

Callbacks

all()

(optional) 
@callback all() :: [Kathikon.Job.t()]

cancel_job(t, term, map)

@callback cancel_job(String.t(), term(), map()) ::
  {:ok, map()} | {:ok, Kathikon.Job.t()} | {:error, term()}

claim(atom, t)

(optional) 
@callback claim(atom(), DateTime.t()) ::
  {:ok, Kathikon.Job.t()} | :not_found | {:error, term()}

claim_and_start_available_jobs(atom, pos_integer, map)

(optional) 
@callback claim_and_start_available_jobs(atom(), pos_integer(), map()) ::
  {:ok, [map()]} | {:ok, [Kathikon.Job.t()]} | {:error, term()}

claim_available_jobs(atom, pos_integer, map)

@callback claim_available_jobs(atom(), pos_integer(), map()) ::
  {:ok, [map()]} | {:ok, [Kathikon.Job.t()]} | {:error, term()}

claim_job(t, map)

@callback claim_job(String.t(), map()) ::
  {:ok, map()}
  | {:ok, Kathikon.Job.t()}
  | {:error, :not_found | :already_claimed | :not_claimable | term()}

clear_jobs!()

@callback clear_jobs!() :: :ok

complete_job(t, term, map)

@callback complete_job(String.t(), term(), map()) ::
  {:ok, map()} | {:ok, Kathikon.Job.t()} | {:error, term()}

defer_job(t, t, map)

(optional) 
@callback defer_job(String.t(), DateTime.t(), map()) ::
  {:ok, map()} | {:ok, Kathikon.Job.t()} | {:error, term()}

delete(t)

(optional) 
@callback delete(String.t()) :: :ok

discard_job(t, term, map)

@callback discard_job(String.t(), term(), map()) ::
  {:ok, map()} | {:ok, Kathikon.Job.t()} | {:error, term()}

fail_job(t, term, map)

@callback fail_job(String.t(), term(), map()) ::
  {:ok, map()} | {:ok, Kathikon.Job.t()} | {:error, term()}

fetch(t)

(optional) 
@callback fetch(String.t()) :: {:ok, Kathikon.Job.t()} | {:error, term()}

get_job(t)

@callback get_job(String.t()) ::
  {:ok, map()} | {:ok, Kathikon.Job.t()} | {:error, :not_found | term()}

insert(t)

(optional) 
@callback insert(Kathikon.Job.t()) :: {:ok, Kathikon.Job.t()} | {:error, term()}

insert_history_event(t, map)

@callback insert_history_event(String.t(), map()) :: :ok | {:error, term()}

insert_job(job)

@callback insert_job(job()) ::
  {:ok, String.t()} | {:ok, Kathikon.Job.t()} | {:error, term()}

list_dead_jobs(keyword)

@callback list_dead_jobs(keyword()) ::
  {:ok, [map()]} | {:ok, [Kathikon.Job.t()]} | {:error, term()}

list_history(t)

@callback list_history(String.t()) :: {:ok, [map()]} | {:error, term()}

list_jobs(keyword)

@callback list_jobs(keyword()) ::
  {:ok, [map()]} | {:ok, [Kathikon.Job.t()]} | {:error, term()}

list_jobs_page(keyword)

(optional) 
@callback list_jobs_page(keyword()) ::
  {:ok, %{jobs: [map()] | [Kathikon.Job.t()], total: non_neg_integer()}}
  | {:error, term()}

move_to_dead_letter(t, term, map)

@callback move_to_dead_letter(String.t(), term(), map()) ::
  {:ok, map()} | {:ok, Kathikon.Job.t()} | {:error, term()}

promote_scheduled(t)

(optional) 
@callback promote_scheduled(DateTime.t()) :: non_neg_integer()

prunable_jobs(t)

(optional) 
@callback prunable_jobs(DateTime.t()) :: [Kathikon.Job.t()]

reset!()

@callback reset!() :: :ok

retry_job(t, keyword)

@callback retry_job(
  String.t(),
  keyword()
) :: {:ok, map()} | {:ok, Kathikon.Job.t()} | {:error, term()}

setup()

@callback setup() :: :ok

start_job(t, map, t)

(optional) 
@callback start_job(Kathikon.Job.t(), map(), DateTime.t()) ::
  {:ok, Kathikon.Job.t()} | {:error, term()}

update(t)

(optional) 
@callback update(Kathikon.Job.t()) :: {:ok, Kathikon.Job.t()} | {:error, term()}

update_job(t, map)

@callback update_job(String.t(), map()) ::
  {:ok, map()} | {:ok, Kathikon.Job.t()} | {:error, :not_found | term()}

Functions

setup()

@spec setup() :: :ok

Ensures the storage backend schema and tables exist.

Called automatically on application start. Call explicitly when embedding Kathikon in scripts, Livebook, or tests without the full application.

Examples

:ok = Kathikon.Storage.setup()