Squidie.Runtime.Journal.Options (squidie v0.3.0)

Validates public options that reach journal-backed runtime threads.

Journal-backed start, inspection, and explanation all cross the same storage boundary: caller-provided storage config is normalized into a Squidie journal storage struct, and caller-provided run or queue identifiers become part of journal thread ids. This module keeps that validation in one place so those public APIs fail with structured, redacted errors before invalid values can reach an adapter or file-backed thread path.

The validation is intentionally about runtime safety, not compatibility. It accepts the current Jido storage adapter shape through a Squidie-owned boundary, validates the built-in adapters whose required options can otherwise raise, and keeps thread id components to a conservative portable character set.

Summary

Functions

now_from_opts(opts)

Fetches a runtime clock from options, defaulting to DateTime.utc_now/0.

queue(queue \\ "default")

Normalizes and validates a dispatch queue name for use in journal thread ids.

queue_from_opts(opts)

Fetches and validates :queue from a runtime option list.

storage(storage)

Validates a journal storage config before a public API calls the adapter.

storage_from_opts(opts)

Fetches and validates :journal_storage from a runtime option list.

storage_safe_value?(value)

Returns true when a value can be safely persisted in journal metadata.

thread_part(value, field)

Validates a caller-provided journal thread-id component.

uuid(value)

Validates and canonicalizes a public run id that must be a UUID.

uuid_run_id(value)

Validates a run id as a UUID for internal journal lookups.

Functions

now_from_opts(opts)

@spec now_from_opts(keyword()) ::
  {:ok, DateTime.t()} | {:error, {:invalid_option, {:now, :invalid}}}

Fetches a runtime clock from options, defaulting to DateTime.utc_now/0.

queue(queue \\ "default")

@spec queue(term()) ::
  {:ok, String.t()} | {:error, {:invalid_option, {:queue, :invalid}}}

Normalizes and validates a dispatch queue name for use in journal thread ids.

Atoms are converted to strings. Queue names must be non-empty and use the conservative portable thread-id character set enforced by this module.

queue_from_opts(opts)

@spec queue_from_opts(keyword()) ::
  {:ok, String.t()} | {:error, {:invalid_option, {:queue, :invalid}}}

Fetches and validates :queue from a runtime option list.

storage(storage)

@spec storage(term()) ::
  {:ok, Squidie.Runtime.Journal.Storage.t()}
  | {:error, {:invalid_option, term()}}

Validates a journal storage config before a public API calls the adapter.

Invalid configs return structured, redacted option errors. Built-in adapters that raise for missing required options are checked here first. Treat journal_storage as trusted host configuration, not request-derived input.

storage_from_opts(opts)

@spec storage_from_opts(keyword()) ::
  {:ok, Squidie.Runtime.Journal.Storage.t()}
  | {:error, {:invalid_option, term()}}

Fetches and validates :journal_storage from a runtime option list.

storage_safe_value?(value)

@spec storage_safe_value?(term()) :: boolean()

Returns true when a value can be safely persisted in journal metadata.

thread_part(value, field)

@spec thread_part(term(), atom()) ::
  {:ok, String.t()} | {:error, {:invalid_option, term()}}

Validates a caller-provided journal thread-id component.

Use this for public identifiers, such as run ids in projection reads, that are

not required to be UUIDs but still become part of a Jido thread id.

uuid(value)

@spec uuid(term()) ::
  {:ok, String.t()} | {:error, {:invalid_option, {:run_id, :invalid}}}

Validates and canonicalizes a public run id that must be a UUID.

Journal starts use UUID run ids so caller-provided ids are safe as stable workflow thread identifiers and duplicate-start fences.

uuid_run_id(value)

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

Validates a run id as a UUID for internal journal lookups.