Hourglass.Application (hourglass v0.1.0)

Copy Markdown View Source

OTP Application entry point for the Hourglass Temporal SDK.

The supervision tree is split into local singletons (always started) and the cluster-facing runtime (gated behind config :hourglass, :start_runtime). The split keeps the library inert by default: embedding it as a dependency, running a host's non-Temporal tests, or booting iex -S mix brings up only the cheap ETS/DynSup singletons — no pollers, no bridge handles, no cluster connection — until the host opts in.

ETS table (created imperatively before the supervisor starts)

Hourglass.Worker.WorkflowStateCache uses a :named_table ETS table created by calling WorkflowStateCache.ensure_table/0 at the top of start/2, before Supervisor.start_link/2. The call is idempotent — it is safe to invoke from both Application.start/2 and test setup.

Local singletons (always-on)

local_singletons/0 returns two DynamicSupervisors started unconditionally because they are cheap, hold no cluster resources, and are needed the moment any Worker (default or per-test) spins up:

These DynSups live at Application scope (siblings of the Subsystem, not children) precisely so in-flight Tasks survive a BridgeHolder crash + :rest_for_one cascade inside the Subsystem. See Hourglass.Subsystem for the cascade contract.

Cluster-facing runtime (gated)

Started only when config :hourglass, :start_runtime is true:

  • Hourglass.Subsystem — :rest_for_one group of Runtime, BridgeHolder, WorkerRegistry, Worker.Supervisor, and WorkerLauncher. The launcher registers the default "default"-task-queue Worker (when config :hourglass, :start_default_worker is true); modules are resolved structurally from the Temporal type name — no workflow/activity inventory config is required.
  • Hourglass.NamespaceEnsurer — runs after the Subsystem so Runtime is alive when it calls into the Temporal client. Returns :ignore once it succeeds; crashes the boot supervisor on connect/namespace-register failure so operators see the real error.

The gate

config :hourglass, :start_runtime defaults to false. Hosts that embed Hourglass and want the live worker tree set it true. The :temporal integration test suite either sets it true or brings up the Subsystem via start_supervised/1 per test.