Struct HotReloadAgentCardHandler 

pub struct HotReloadAgentCardHandler { /* private fields */ }

An agent card handler that supports hot-reloading.

The current AgentCard is stored behind an Arc<RwLock<_>> so that it can be atomically swapped while the server continues to serve requests.

This type implements AgentCardProducer, so it can be plugged directly into a DynamicAgentCardHandler for full HTTP caching support.

Implementations

impl HotReloadAgentCardHandler

pub fn new(card: AgentCard) -> Self

Creates a new handler with the given initial AgentCard.

pub fn current(&self) -> AgentCard

Returns a snapshot of the current AgentCard.

This acquires a short-lived read lock and clones the card.

A poisoned lock is recovered from rather than propagated — see update.

pub fn update(&self, card: AgentCard)

Replaces the current agent card with card.

All subsequent requests will see the new card immediately.

A poisoned lock is recovered from, not propagated

Both accessors used to expect on the lock, so one panic anywhere under the write lock turned every subsequent agent-card request into a panic — on the request path, in a handler whose whole purpose is to answer GetAgentCard. In a release build that is worse still: this workspace sets panic = "abort", so the second panic is a process abort rather than one failed request.

Recovery is correct here, not merely convenient. The only write is this whole-value assignment of an already-constructed AgentCard, so there is no state in which the guarded value is half-updated for a later reader to observe. The same reasoning the rest of this workspace applies to its std mutexes.

pub fn reload_from_file(&self, path: &Path) -> ServerResult<()>

Reloads the agent card from a JSON file at path.

The file is read synchronously (agent card files are expected to be small). On success the internal card is replaced atomically.

Errors

Returns ServerError::Internal if the file cannot be read or parsed.

pub fn reload_from_json(&self, json: &str) -> ServerResult<()>

Reloads the agent card from a JSON string.

On success the internal card is replaced atomically.

Errors

Returns ServerError::Serialization if json is not valid agent card JSON.

pub fn spawn_poll_watcher( &self, path: &Path, interval: Duration, ) -> JoinHandle<()>

Spawns a background task that periodically checks whether the file at path has been modified and reloads the agent card when it has.

The watcher compares the file’s modification time on each tick and only re-reads the file when the timestamp changes. This is cross-platform and requires no OS-specific file notification APIs.

Returns a tokio::task::JoinHandle that can be used to abort the watcher (via JoinHandle::abort).

pub fn spawn_signal_watcher(&self, path: &Path) -> JoinHandle<()>

Spawns a background task that reloads the agent card from path whenever the process receives SIGHUP.

This is the traditional Unix mechanism for configuration reload and integrates well with process managers (systemd, supervisord, etc.).

Returns a tokio::task::JoinHandle that can be used to abort the watcher (via JoinHandle::abort).

If the handler cannot be registered for an ordinary I/O reason, the watcher logs a warning and exits; reload-on-SIGHUP is then unavailable, and reload_from_file and spawn_poll_watcher still work.

Panics

Panics here, at this call, if the current Tokio runtime has no signal driver — there is no signal driver running, must be called from the context of Tokio runtime. That is what a runtime built by hand without enable_all() (or at least enable_io()) gives you; the #[tokio::main] default has it.

Registration used to happen inside the spawned task, which made the same panic much worse. It fired after this function had already returned a handle, so a caller had no way to see it coming and nothing to catch — and this workspace builds release with panic = "abort", so what a developer would meet as a failing startup in the first case is a process abort at an arbitrary later moment in the second. Registering synchronously does not remove the panic; it moves it to the caller’s own startup path, where it is deterministic and where this paragraph is about the function it is attached to.

Trait Implementations

impl AgentCardProducer for HotReloadAgentCardHandler

fn produce<'a>( &'a self, ) -> Pin<Box<dyn Future<Output = A2aResult<AgentCard>> + Send + 'a>>

Produces an AgentCard for the current request.

impl Clone for HotReloadAgentCardHandler

fn clone(&self) -> HotReloadAgentCardHandler

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HotReloadAgentCardHandler

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.