Jido.Pod.Topology (Jido v2.2.0)

Canonical pod topology data structure.

Topologies are pure data. They define the named durable nodes that a pod manages and can be validated, stored, and mutated independently of runtime process state.

Summary

Types

node_name()

t()

Functions

delete_link(topology, link)

Removes a link from the topology.

delete_node(topology, name)

Removes a node from the topology.

dependencies_of(topology, name)

Returns the direct :depends_on prerequisites for the given node.

dependency_order(topology, node_names)

Orders the given node names according to :depends_on links.

fetch_node(topology, name)

Fetches a node by name.

from_nodes(name, nodes, opts \\ [])

Builds a topology from the common shorthand node map form.

from_nodes!(name, nodes, opts \\ [])

Builds a topology from shorthand, raising on error.

new(topology)

Builds a validated topology.

new!(attrs)

Builds a validated topology, raising on error.

owned_children(topology, owner)

Returns the owned children for the given node.

owner_of(topology, name)

Returns the logical owner of a node when the topology contains an :owns link.

put_link(topology, link)

Appends a link to the topology if it is not already present.

put_node(topology, name, node)

Inserts or replaces a node definition in the topology.

reconcile_waves(topology, node_names)

Builds runtime reconcile waves for the requested nodes.

roots(topology)

Returns the root nodes that have no logical :owns parent.

with_name(topology, name)

Returns a copy of the topology with a new validated name.

Types

node_name()

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

t()

@type t() :: %Jido.Pod.Topology{
  defaults: map(),
  links: [
    %Jido.Pod.Topology.Link{
      from: atom() | binary(),
      meta: map(),
      to: atom() | binary(),
      type: atom()
    }
  ],
  name: binary(),
  nodes: map(),
  version: integer()
}

Functions

delete_link(topology, link)

@spec delete_link(t(), Jido.Pod.Topology.Link.t() | tuple() | keyword() | map()) ::
  t()

Removes a link from the topology.

delete_node(topology, name)

@spec delete_node(t(), node_name()) :: t()

Removes a node from the topology.

dependencies_of(topology, name)

@spec dependencies_of(t(), node_name()) :: [node_name()]

Returns the direct :depends_on prerequisites for the given node.

dependency_order(topology, node_names)

@spec dependency_order(t(), [node_name()]) :: {:ok, [node_name()]} | {:error, term()}

Orders the given node names according to :depends_on links.

Only dependencies between the provided node names participate in ordering. Other links are ignored.

fetch_node(topology, name)

@spec fetch_node(t(), node_name()) :: {:ok, Jido.Pod.Topology.Node.t()} | :error

Fetches a node by name.

from_nodes(name, nodes, opts \\ [])

@spec from_nodes(String.t(), map(), keyword()) :: {:ok, t()} | {:error, term()}

Builds a topology from the common shorthand node map form.

from_nodes!(name, nodes, opts \\ [])

@spec from_nodes!(String.t(), map(), keyword()) :: t()

Builds a topology from shorthand, raising on error.

new(topology)

@spec new(keyword() | map() | t()) :: {:ok, t()} | {:error, term()}

Builds a validated topology.

new!(attrs)

@spec new!(keyword() | map() | t()) :: t()

Builds a validated topology, raising on error.

owned_children(topology, owner)

@spec owned_children(t(), node_name()) :: [node_name()]

Returns the owned children for the given node.

owner_of(topology, name)

@spec owner_of(t(), node_name()) :: {:ok, node_name()} | :root | :error

Returns the logical owner of a node when the topology contains an :owns link.

put_link(topology, link)

@spec put_link(t(), Jido.Pod.Topology.Link.t() | tuple() | keyword() | map()) ::
  {:ok, t()} | {:error, term()}

Appends a link to the topology if it is not already present.

put_node(topology, name, node)

@spec put_node(t(), node_name(), Jido.Pod.Topology.Node.t() | keyword() | map()) ::
  {:ok, t()} | {:error, term()}

Inserts or replaces a node definition in the topology.

reconcile_waves(topology, node_names)

@spec reconcile_waves(t(), [node_name()]) :: {:ok, [[node_name()]]} | {:error, term()}

Builds runtime reconcile waves for the requested nodes.

Each wave contains nodes whose ownership and dependency prerequisites are satisfied by earlier waves. The requested nodes are automatically expanded to include transitive owners and dependencies.

roots(topology)

@spec roots(t()) :: [node_name()]

Returns the root nodes that have no logical :owns parent.

with_name(topology, name)

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

Returns a copy of the topology with a new validated name.