Synapse.SignalRouter (Synapse v0.1.1)

Runtime wrapper around Jido.Signal.Bus that enforces signal contracts, centralizes publish/subscribe ergonomics, and enables targeted delivery to specialists without leaking process identifiers.

Summary

Types

subscription_id()

Unique subscription identifier returned by subscribe/3.

Functions

ack(router \\ __MODULE__, signal)

Acknowledges a signal delivery (placeholder hook for future durability).

cast_to_specialist(router \\ __MODULE__, specialist_id, signal, opts \\ [])

Dispatches a review request to a specialist identified by registry id.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

fetch(name \\ __MODULE__)

Fetches router metadata (bus, registry, name) from persistent storage.

publish(router \\ __MODULE__, topic, payload, opts \\ [])

Publishes a signal for the given topic after validating the payload.

replay(router \\ __MODULE__, topic, opts \\ [])

Replays historical signals for the given topic.

retry(router \\ __MODULE__, topic, payload, opts \\ [])

Retries a publish with the provided payload and options.

start_link(opts \\ [])

Starts the router process and its dedicated signal bus.

subscribe(router \\ __MODULE__, topic, opts \\ [])

Subscribes the caller (or provided :target) to a validated topic stream.

unsubscribe(router \\ __MODULE__, subscription_id)

Cancels a subscription created via subscribe/3.

Types

subscription_id()

@type subscription_id() :: reference()

Unique subscription identifier returned by subscribe/3.

Functions

ack(router \\ MODULE, signal)

@spec ack(atom(), Jido.Signal.t()) :: :ok

Acknowledges a signal delivery (placeholder hook for future durability).

cast_to_specialist(router \\ MODULE, specialist_id, signal, opts \\ [])

@spec cast_to_specialist(
  atom(),
  Synapse.AgentRegistry.agent_id(),
  Jido.Signal.t(),
  keyword()
) ::
  :ok | {:error, term()}

Dispatches a review request to a specialist identified by registry id.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

fetch(name \\ MODULE)

@spec fetch(atom()) :: %{bus: atom(), registry: atom() | nil, name: atom()}

Fetches router metadata (bus, registry, name) from persistent storage.

publish(router \\ MODULE, topic, payload, opts \\ [])

@spec publish(atom(), Synapse.Signal.topic(), map(), keyword()) ::
  {:ok, Jido.Signal.t()} | {:error, term()}

Publishes a signal for the given topic after validating the payload.

Accepted options:

:source - logical source URI (defaults to "/synapse/router")
:subject - optional subject string
:meta - metadata map merged into the signal struct

replay(router \\ MODULE, topic, opts \\ [])

@spec replay(atom(), Synapse.Signal.topic(), keyword()) ::
  {:ok, [Jido.Signal.t()]} | {:error, term()}

Replays historical signals for the given topic.

retry(router \\ MODULE, topic, payload, opts \\ [])

@spec retry(atom(), Synapse.Signal.topic(), map(), keyword()) ::
  {:ok, Jido.Signal.t()} | {:error, term()}

Retries a publish with the provided payload and options.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the router process and its dedicated signal bus.

Options:

:name - router identifier (defaults to Synapse.SignalRouter)
:bus_name - name of the underlying Jido.Signal.Bus
:registry - Synapse.AgentRegistry name for targeted delivery helpers
:bus_opts - additional options passed to Jido.Signal.Bus.start_link/1

unsubscribe(router \\ MODULE, subscription_id)

@spec unsubscribe(atom(), subscription_id()) :: :ok

Cancels a subscription created via subscribe/3.