Struct RequestHandler 

pub struct RequestHandler { /* private fields */ }

The core protocol logic handler.

Orchestrates task lifecycle, event streaming, push notifications, and interceptor chains for all A2A methods.

RequestHandler is not generic — it stores the executor as Arc<dyn AgentExecutor>, enabling dynamic dispatch and simplifying the downstream API (dispatchers, builder, etc.).

Store ownership

Stores are held as Arc<dyn TaskStore> / Arc<dyn PushConfigStore> rather than Box<dyn ...> so that they can be cheaply cloned into background tasks (e.g. the streaming push-delivery processor).

Implementations

impl RequestHandler

pub fn activated_extensions( &self, headers: &HashMap<String, String>, ) -> Vec<String>

Returns the activated extension set for a request: the intersection of the client’s A2A-Extensions declaration and the card’s declared extensions, in request order. HTTP dispatchers echo this back in the response A2A-Extensions header (official-SDK convention) so clients know which requested extensions the agent honored.

impl RequestHandler

pub async fn active_queue_count(&self) -> usize

Number of event queues currently alive.

One queue exists per in-flight task and is destroyed when the task finishes, so under steady traffic this tracks concurrency rather than throughput. A value that climbs with cumulative request count — instead of settling — means queues are not being reclaimed.

Exposed for monitoring and for the sustained-load tests. The Metrics::on_queue_depth_change callback reports the same quantity as it changes; this is the pull-based counterpart, for a gauge scrape or a health page.

pub async fn task_count(&self) -> Result<u64, A2aError>

Number of tasks currently held by the task store.

Delegates to count on the configured store.

Errors

Returns whatever the store returned.

pub async fn cancellation_token_count(&self) -> usize

Number of registered cancellation tokens.

One is registered per in-flight task and removed when it finishes, so like active_queue_count this should settle under steady traffic rather than climb. It has its own bound (max_cancellation_tokens), so a leak here eventually rejects new work rather than only consuming memory — which makes it worth watching directly.

pub async fn task_store_health(&self) -> Result<(), A2aError>

Probes the task store, for readiness checks.

Answers the one question a readiness probe needs: can this replica reach the dependency it cannot serve a request without? A liveness probe deliberately cannot answer that — making liveness depend on a downstream turns that downstream’s outage into a restart loop across every replica, which is how a degraded service becomes an unavailable one.

Implemented as count, which every bundled store answers with a cheap query. It performs no write, so a store at its capacity limit still reports healthy — capacity is not the same question as reachability, and conflating them would drain traffic from a cluster that was merely full.

Errors

Returns whatever the store returned. Callers exposing this over HTTP should surface metric_label rather than the message, which may name a host or a connection string.

impl RequestHandler

pub async fn on_cancel_task( &self, params: CancelTaskParams, headers: Option<&HashMap<String, String>>, ) -> Result<Task, ServerError>

Handles CancelTask.

Errors

Returns ServerError::TaskNotFound or ServerError::TaskNotCancelable.

impl RequestHandler

pub async fn on_get_extended_agent_card( &self, headers: Option<&HashMap<String, String>>, ) -> Result<AgentCard, ServerError>

Handles GetExtendedAgentCard.

Errors

Returns ServerError::Internal if no agent card is configured.

impl RequestHandler

pub async fn on_get_task( &self, params: TaskQueryParams, headers: Option<&HashMap<String, String>>, ) -> Result<Task, ServerError>

Handles GetTask. Returns ServerError::TaskNotFound if missing.

Errors

Returns ServerError::TaskNotFound if the task does not exist.

impl RequestHandler

pub async fn on_list_tasks( &self, params: ListTasksParams, headers: Option<&HashMap<String, String>>, ) -> Result<TaskListResponse, ServerError>

Handles ListTasks.

Errors

Returns a ServerError if the store query fails.

impl RequestHandler

pub async fn on_resubscribe( &self, params: TaskIdParams, headers: Option<&HashMap<String, String>>, ) -> Result<InMemoryQueueReader, ServerError>

Handles SubscribeToTask.

Errors

Returns ServerError::TaskNotFound if the task does not exist.

impl RequestHandler

pub async fn on_send_message( &self, params: MessageSendParams, streaming: bool, headers: Option<&HashMap<String, String>>, ) -> Result<SendMessageResult, ServerError>

Handles SendMessage / SendStreamingMessage.

The optional headers map carries HTTP request headers for interceptor access-control decisions (e.g. Authorization).

Errors

Returns ServerError if task creation or execution fails.

impl RequestHandler

pub async fn on_set_push_config( &self, config: TaskPushNotificationConfig, headers: Option<&HashMap<String, String>>, ) -> Result<TaskPushNotificationConfig, ServerError>

Handles CreateTaskPushNotificationConfig.

Errors

Returns ServerError::PushNotSupported if no push sender is configured.

pub async fn on_get_push_config( &self, params: GetPushConfigParams, headers: Option<&HashMap<String, String>>, ) -> Result<TaskPushNotificationConfig, ServerError>

Handles GetTaskPushNotificationConfig.

Errors

Returns ServerError::PushNotSupported if the agent card does not advertise push notifications, or ServerError::TaskNotFound if the requested configuration does not exist (spec §3.1.8).

pub async fn on_list_push_configs( &self, task_id: &str, tenant: Option<&str>, headers: Option<&HashMap<String, String>>, ) -> Result<Vec<TaskPushNotificationConfig>, ServerError>

Handles ListTaskPushNotificationConfigs.

Errors

Returns a ServerError if the store query fails.

pub async fn on_delete_push_config( &self, params: DeletePushConfigParams, headers: Option<&HashMap<String, String>>, ) -> Result<(), ServerError>

Handles DeleteTaskPushNotificationConfig.

Errors

Returns a ServerError if the delete operation fails.

impl RequestHandler

pub async fn shutdown(&self) -> ShutdownReport

Initiates graceful shutdown of the handler.

This method:

1. Cancels all in-flight tasks by signalling their cancellation tokens.
2. Destroys all event queues, causing readers to see EOF.

After calling shutdown(), new requests will still be accepted but in-flight tasks will observe cancellation. The caller should stop accepting new connections after calling this method.

Returns a ShutdownReport describing whether the executor’s cleanup hook finished. This method does not wait for queues to drain, so queues_force_destroyed is always 0 — use shutdown_with_timeout when in-flight work should be given a chance to finish.

pub async fn shutdown_with_timeout(&self, timeout: Duration) -> ShutdownReport

Initiates graceful shutdown with a timeout.

Cancels all in-flight tasks and waits up to timeout for event queues to drain before force-destroying them. This gives executors a chance to finish writing final events before the queues are torn down.

Returns a ShutdownReport: a non-zero queues_force_destroyed means the deadline passed with work still in flight, and executor_cleanup_completed == false means the executor’s cleanup hook was abandoned. Both are invisible from the outside otherwise, which is how a rollout can truncate every in-flight stream without anyone noticing.

impl RequestHandler

pub fn tenant_resolver(&self) -> Option<&(dyn TenantResolver + 'static)>

Returns the tenant resolver, if configured.

Use this in dispatchers or middleware to resolve the tenant identity from a CallContext before processing a request.

pub const fn tenant_config(&self) -> Option<&PerTenantConfig>

Returns the per-tenant configuration, if configured.

Use this alongside tenant_resolver to look up resource limits for the resolved tenant.

Trait Implementations

impl Debug for RequestHandler

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

Formats the value using the given formatter.