Jido.Pod (Jido v2.2.0)

View Source

Pod wrapper macro and runtime helpers.

A pod is just a Jido.Agent with a canonical topology and a singleton pod plugin mounted under the reserved :__pod__ state key.

Summary

Types

ensure_result()
ensure_source()
mutation_report()
node_name()
node_snapshot()
node_status()
reconcile_report()

Functions

ensure_node(server, name, opts \\ [])

Ensures a named node is running and adopted into the pod manager.

fetch_state(agent_or_state)

Fetches pod plugin state from an agent or server state.

fetch_topology(source)

Fetches the canonical topology from a module, agent, or running pod server.

get(manager, key, opts \\ [])

Gets a pod instance through the given InstanceManager and immediately reconciles eager nodes.

lookup_node(server, name)

Looks up a node's live process if it is currently running.

mutate(server, ops, opts \\ [])

Applies live topology mutations to a running pod and waits for runtime work to finish.

mutation_effects(agent, ops, opts \\ [])

Builds state ops and runtime effects for an in-turn pod mutation.

nodes(server)

Returns runtime snapshots for every node in a running pod.

pod_plugin_instance(agent_module)

Returns the reserved pod plugin instance for a pod-wrapped agent module.

put_topology(agent, topology)

Replaces the persisted topology snapshot in a pod agent.

reconcile(server, opts \\ [])

Ensures all eager nodes are running and adopted into the pod manager.

update_topology(agent, fun)

Applies a pure topology transformation to a pod agent.

Types

ensure_result()

@type ensure_result() :: %{
  pid: pid(),
  source: ensure_source(),
  owner: node_name() | nil,
  parent: :pod | node_name()
}

ensure_source()

@type ensure_source() :: :adopted | :running | :started

mutation_report()

@type mutation_report() :: Jido.Pod.Mutation.Report.t()

node_name()

@type node_name() :: Jido.Pod.Topology.node_name()

node_snapshot()

@type node_snapshot() :: %{
  node: Jido.Pod.Topology.Node.t(),
  key: term(),
  pid: pid() | nil,
  running_pid: pid() | nil,
  adopted_pid: pid() | nil,
  owner: node_name() | nil,
  expected_parent: map(),
  actual_parent: map() | nil,
  adopted?: boolean(),
  status: node_status()
}

node_status()

@type node_status() :: :adopted | :running | :misplaced | :stopped

reconcile_report()

@type reconcile_report() :: %{
  requested: [node_name()],
  waves: [[node_name()]],
  nodes: %{required(node_name()) => ensure_result()},
  failures: %{required(node_name()) => term()},
  completed: [node_name()],
  failed: [node_name()],
  pending: [node_name()]
}

Functions

ensure_node(server, name, opts \\ [])

@spec ensure_node(Jido.AgentServer.server(), node_name(), keyword()) ::
  {:ok, pid()} | {:error, term()}

Ensures a named node is running and adopted into the pod manager.

fetch_state(agent_or_state)

@spec fetch_state(Jido.Agent.t() | Jido.AgentServer.State.t()) ::
  {:ok, map()} | {:error, term()}

Fetches pod plugin state from an agent or server state.

fetch_topology(source)

@spec fetch_topology(
  module()
  | Jido.Agent.t()
  | Jido.AgentServer.State.t()
  | Jido.AgentServer.server()
) ::
  {:ok, Jido.Pod.Topology.t()} | {:error, term()}

Fetches the canonical topology from a module, agent, or running pod server.

get(manager, key, opts \\ [])

@spec get(atom(), term(), keyword()) :: {:ok, pid()} | {:error, term()}

Gets a pod instance through the given InstanceManager and immediately reconciles eager nodes.

This is the default happy path for pod lifecycle access. Call Jido.Agent.InstanceManager.get/3 directly if you need lower-level control over reconciliation timing.

lookup_node(server, name)

@spec lookup_node(Jido.AgentServer.server(), node_name()) ::
  {:ok, pid()} | :error | {:error, term()}

Looks up a node's live process if it is currently running.

mutate(server, ops, opts \\ [])

@spec mutate(Jido.AgentServer.server(), [Jido.Pod.Mutation.t() | term()], keyword()) ::
  {:ok, mutation_report()} | {:error, mutation_report() | term()}

Applies live topology mutations to a running pod and waits for runtime work to finish.

server follows the same resolution rules as Jido.AgentServer.state/1 and Jido.AgentServer.call/3. Pass the running pod pid, a locally registered server name, or another resolvable runtime server reference. Raw string ids still require explicit registry lookup before use.

mutation_effects(agent, ops, opts \\ [])

@spec mutation_effects(Jido.Agent.t(), [Jido.Pod.Mutation.t() | term()], keyword()) ::
  {:ok, [struct()]} | {:error, term()}

Builds state ops and runtime effects for an in-turn pod mutation.

nodes(server)

@spec nodes(Jido.AgentServer.server()) ::
  {:ok, %{required(node_name()) => node_snapshot()}} | {:error, term()}

Returns runtime snapshots for every node in a running pod.

pod_plugin_instance(agent_module)

@spec pod_plugin_instance(module()) ::
  {:ok, Jido.Plugin.Instance.t()} | {:error, term()}

Returns the reserved pod plugin instance for a pod-wrapped agent module.

put_topology(agent, topology)

@spec put_topology(Jido.Agent.t(), Jido.Pod.Topology.t()) ::
  {:ok, Jido.Agent.t()} | {:error, term()}

Replaces the persisted topology snapshot in a pod agent.

Structural topology changes advance topology.version; no-op replacements preserve the current version.

reconcile(server, opts \\ [])

@spec reconcile(
  Jido.AgentServer.server(),
  keyword()
) :: {:ok, reconcile_report()} | {:error, reconcile_report()}

Ensures all eager nodes are running and adopted into the pod manager.

update_topology(agent, fun)

@spec update_topology(
  Jido.Agent.t(),
  (Jido.Pod.Topology.t() ->
     Jido.Pod.Topology.t() | {:ok, Jido.Pod.Topology.t()} | {:error, term()})
) :: {:ok, Jido.Agent.t()} | {:error, term()}

Applies a pure topology transformation to a pod agent.

Structural topology changes advance topology.version; no-op updates preserve the current version.