feat(task): add task support (SEP-1686) (#536)

Signed-off-by: jokemanfire <hu.dingyang@zte.com.cn>
This commit is contained in:
jokemanfire 2025-12-22 22:01:00 +08:00 • committed by GitHub
commit 621c9f619e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 1922 additions and 57 deletions

View file

@ -6,7 +6,10 @@
This library primarily provides the following macros:
- `#[tool]`: Used to mark functions as RMCP tools, automatically generating necessary metadata and invocation mechanisms
- `#[tool]`: Mark an async/sync function as an RMCP tool and generate metadata + schema glue
- `#[tool_router]`: Collect all `#[tool]` functions in an impl block into a router value
- `#[tool_handler]`: Implement the `call_tool` and `list_tools` entry points by delegating to a router expression
- `#[task_handler]`: Wire up the task lifecycle (list/enqueue/get/cancel) on top of an `OperationProcessor`
## Usage
@ -16,7 +19,7 @@ This macro is used to mark a function as a tool handler.
This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
#### Usage
#### Tool attributes
| field | type | usage |
| :- | :- | :- |
@ -25,7 +28,7 @@ This will generate a function that return the attribute of this tool, with type
| `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
| `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
#### Example
#### Tool example
```rust
#[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
@ -42,14 +45,14 @@ It creates a function that returns a `ToolRouter` instance.
In most case, you need to add a field for handler to store the router information and initialize it when creating handler, or store it with a static variable.
#### Usage
#### Router attributes
| field | type | usage |
| :- | :- | :- |
| `router` | `Ident` | The name of the router function to be generated. Defaults to `tool_router`. |
| `vis` | `Visibility` | The visibility of the generated router function. Defaults to empty. |
#### Example
#### Router example
```rust
#[tool_router]
@ -104,13 +107,14 @@ impl MyToolHandler {
This macro will generate the handler for `tool_call` and `list_tools` methods in the implementation block, by using an existing `ToolRouter` instance.
#### Usage
#### Handler attributes
| field | type | usage |
| :- | :- | :- |
| `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
#### Example
#### Handler example
```rust
#[tool_handler]
impl ServerHandler for MyToolHandler {
@ -119,6 +123,7 @@ impl ServerHandler for MyToolHandler {
```
or using a custom router expression:
```rust
#[tool_handler(router = self.get_router().await)]
impl ServerHandler for MyToolHandler {
@ -126,8 +131,10 @@ impl ServerHandler for MyToolHandler {
}
```
#### Explained
#### Handler expansion
This macro will be expended to something like this:
```rust
impl ServerHandler for MyToolHandler {
async fn call_tool(
@ -150,6 +157,46 @@ impl ServerHandler for MyToolHandler {
}
```
### task_handler
This macro wires the task lifecycle endpoints (`list_tasks`, `enqueue_task`, `get_task`, `cancel_task`) to an implementation of `OperationProcessor`. It keeps the handler lean by delegating scheduling, status tracking, and cancellation semantics to the processor.
#### Task handler attributes
| field | type | usage |
| :- | :- | :- |
| `processor` | `Expr` | Expression that yields an `Arc<dyn OperationProcessor>` (or compatible trait object). Defaults to `self.processor.clone()`. |
#### Task handler example
```rust
#[derive(Clone)]
pub struct TaskHandler {
processor: Arc<dyn OperationProcessor<RoleServer> + Send + Sync>,
}
#[task_handler(processor = self.processor.clone())]
impl ServerHandler for TaskHandler {}
```
#### Task handler expansion
At expansion time the macro implements the task-specific handler methods by forwarding to the processor expression, roughly equivalent to:
```rust
impl ServerHandler for TaskHandler {
async fn list_tasks(&self, request: TaskListRequest, ctx: RequestContext<RoleServer>) -> Result<TaskListResult, rmcp::ErrorData> {
self.processor.list_tasks(request, ctx).await
}
async fn enqueue_task(&self, request: TaskEnqueueRequest, ctx: RequestContext<RoleServer>) -> Result<TaskEnqueueResult, rmcp::ErrorData> {
self.processor.enqueue_task(request, ctx).await
}
// get_task and cancel_task are generated in the same manner.
}
```
## Advanced Features
@ -159,4 +206,4 @@ impl ServerHandler for MyToolHandler {
## License
Please refer to the LICENSE file in the project root directory.
Please refer to the LICENSE file in the project root directory.

View file

@ -5,6 +5,7 @@ mod common;
mod prompt;
mod prompt_handler;
mod prompt_router;
mod task_handler;
mod tool;
mod tool_handler;
mod tool_router;
@ -263,3 +264,17 @@ pub fn prompt_handler(attr: TokenStream, input: TokenStream) -> TokenStream {
.unwrap_or_else(|err| err.to_compile_error())
.into()
}
/// # task_handler
///
/// Generates basic task-handling methods (`enqueue_task` and `list_tasks`) for a server handler
/// using a shared \[`OperationProcessor`\]. The default processor expression assumes a
/// `self.processor` field holding an `Arc<Mutex<OperationProcessor>>`, but it can be customized
/// via `#[task_handler(processor = ...)]`. Because the macro captures `self` inside spawned
/// futures, the handler type must implement [`Clone`].
#[proc_macro_attribute]
pub fn task_handler(attr: TokenStream, input: TokenStream) -> TokenStream {
task_handler::task_handler(attr.into(), input.into())
.unwrap_or_else(|err| err.to_compile_error())
.into()
}

View file

@ -0,0 +1,278 @@
use darling::{FromMeta, ast::NestedMeta};
use proc_macro2::TokenStream;
use quote::{ToTokens, quote};
use syn::{Expr, ImplItem, ItemImpl};
#[derive(FromMeta)]
#[darling(default)]
struct TaskHandlerAttribute {
processor: Expr,
}
impl Default for TaskHandlerAttribute {
fn default() -> Self {
Self {
processor: syn::parse2(quote! { self.processor }).expect("default processor expr"),
}
}
}
pub fn task_handler(attr: TokenStream, input: TokenStream) -> syn::Result<TokenStream> {
let attr_args = NestedMeta::parse_meta_list(attr)?;
let TaskHandlerAttribute { processor } = TaskHandlerAttribute::from_list(&attr_args)?;
let mut item_impl = syn::parse2::<ItemImpl>(input.clone())?;
let has_method = |name: &str, item_impl: &ItemImpl| -> bool {
item_impl.items.iter().any(|item| match item {
ImplItem::Fn(func) => func.sig.ident == name,
_ => false,
})
};
if !has_method("list_tasks", &item_impl) {
let list_fn = quote! {
async fn list_tasks(
&self,
_request: Option<rmcp::model::PaginatedRequestParam>,
_: rmcp::service::RequestContext<rmcp::RoleServer>,
) -> Result<rmcp::model::ListTasksResult, McpError> {
let running_ids = (#processor).lock().await.list_running();
let total = running_ids.len() as u64;
let tasks = running_ids
.into_iter()
.map(|task_id| {
let timestamp = rmcp::task_manager::current_timestamp();
rmcp::model::Task {
task_id,
status: rmcp::model::TaskStatus::Working,
status_message: None,
created_at: timestamp.clone(),
last_updated_at: Some(timestamp),
ttl: None,
poll_interval: None,
}
})
.collect::<Vec<_>>();
Ok(rmcp::model::ListTasksResult {
tasks,
next_cursor: None,
total: Some(total),
})
}
};
item_impl.items.push(syn::parse2::<ImplItem>(list_fn)?);
}
if !has_method("enqueue_task", &item_impl) {
let enqueue_fn = quote! {
async fn enqueue_task(
&self,
request: rmcp::model::CallToolRequestParam,
context: rmcp::service::RequestContext<rmcp::RoleServer>,
) -> Result<rmcp::model::CreateTaskResult, McpError> {
use rmcp::task_manager::{
current_timestamp, OperationDescriptor, OperationMessage, OperationResultTransport,
ToolCallTaskResult,
};
let task_id = context.id.to_string();
let operation_name = request.name.to_string();
let future_request = request.clone();
let future_context = context.clone();
let server = self.clone();
let descriptor = OperationDescriptor::new(task_id.clone(), operation_name)
.with_context(context)
.with_client_request(rmcp::model::ClientRequest::CallToolRequest(
rmcp::model::Request::new(request),
));
let task_result_id = task_id.clone();
let future = Box::pin(async move {
let result = server.call_tool(future_request, future_context).await;
Ok(
Box::new(ToolCallTaskResult::new(task_result_id, result))
as Box<dyn OperationResultTransport>,
)
});
(#processor)
.lock()
.await
.submit_operation(OperationMessage::new(descriptor, future))
.map_err(|err| rmcp::ErrorData::internal_error(
format!("failed to enqueue task: {err}"),
None,
))?;
let timestamp = current_timestamp();
let task = rmcp::model::Task {
task_id,
status: rmcp::model::TaskStatus::Working,
status_message: Some("Task accepted".to_string()),
created_at: timestamp.clone(),
last_updated_at: Some(timestamp),
ttl: None,
poll_interval: None,
};
Ok(rmcp::model::CreateTaskResult { task })
}
};
item_impl.items.push(syn::parse2::<ImplItem>(enqueue_fn)?);
}
if !has_method("get_task_info", &item_impl) {
let get_info_fn = quote! {
async fn get_task_info(
&self,
request: rmcp::model::GetTaskInfoParam,
_context: rmcp::service::RequestContext<rmcp::RoleServer>,
) -> Result<rmcp::model::GetTaskInfoResult, McpError> {
use rmcp::task_manager::current_timestamp;
let task_id = request.task_id.clone();
let mut processor = (#processor).lock().await;
processor.collect_completed_results();
// Check completed results first
let completed = processor.peek_completed().iter().rev().find(|r| r.descriptor.operation_id == task_id);
if let Some(completed_result) = completed {
// Determine Finished vs Failed
let status = match &completed_result.result {
Ok(boxed) => {
if let Some(tool) = boxed.as_any().downcast_ref::<rmcp::task_manager::ToolCallTaskResult>() {
match &tool.result {
Ok(_) => rmcp::model::TaskStatus::Completed,
Err(_) => rmcp::model::TaskStatus::Failed,
}
} else {
rmcp::model::TaskStatus::Completed
}
}
Err(_) => rmcp::model::TaskStatus::Failed,
};
let timestamp = current_timestamp();
let task = rmcp::model::Task {
task_id,
status,
status_message: None,
created_at: timestamp.clone(),
last_updated_at: Some(timestamp),
ttl: completed_result.descriptor.ttl,
poll_interval: None,
};
return Ok(rmcp::model::GetTaskInfoResult { task: Some(task) });
}
// If not completed, check running
let running = processor.list_running();
if running.into_iter().any(|id| id == task_id) {
let timestamp = current_timestamp();
let task = rmcp::model::Task {
task_id,
status: rmcp::model::TaskStatus::Working,
status_message: None,
created_at: timestamp.clone(),
last_updated_at: Some(timestamp),
ttl: None,
poll_interval: None,
};
return Ok(rmcp::model::GetTaskInfoResult { task: Some(task) });
}
Ok(rmcp::model::GetTaskInfoResult { task: None })
}
};
item_impl.items.push(syn::parse2::<ImplItem>(get_info_fn)?);
}
if !has_method("get_task_result", &item_impl) {
let get_result_fn = quote! {
async fn get_task_result(
&self,
request: rmcp::model::GetTaskResultParam,
_context: rmcp::service::RequestContext<rmcp::RoleServer>,
) -> Result<rmcp::model::TaskResult, McpError> {
use std::time::Duration;
let task_id = request.task_id.clone();
loop {
// Scope the lock so we can await outside if needed
{
let mut processor = (#processor).lock().await;
processor.collect_completed_results();
if let Some(task_result) = processor.take_completed_result(&task_id) {
match task_result.result {
Ok(boxed) => {
if let Some(tool) = boxed.as_any().downcast_ref::<rmcp::task_manager::ToolCallTaskResult>() {
match &tool.result {
Ok(call_tool) => {
let value = ::serde_json::to_value(call_tool).unwrap_or(::serde_json::Value::Null);
return Ok(rmcp::model::TaskResult {
content_type: "application/json".to_string(),
value,
summary: None,
});
}
Err(err) => return Err(McpError::internal_error(
format!("task failed: {}", err),
None,
)),
}
} else {
return Err(McpError::internal_error("unsupported task result transport", None));
}
}
Err(err) => return Err(McpError::internal_error(
format!("task execution error: {}", err),
None,
)),
}
}
// Not completed yet: if not running, return not found
let running = processor.list_running();
if !running.iter().any(|id| id == &task_id) {
return Err(McpError::resource_not_found(format!("task not found: {}", task_id), None));
}
}
tokio::time::sleep(Duration::from_millis(100)).await;
}
}
};
item_impl
.items
.push(syn::parse2::<ImplItem>(get_result_fn)?);
}
if !has_method("cancel_task", &item_impl) {
let cancel_fn = quote! {
async fn cancel_task(
&self,
request: rmcp::model::CancelTaskParam,
_context: rmcp::service::RequestContext<rmcp::RoleServer>,
) -> Result<(), McpError> {
let task_id = request.task_id;
let mut processor = (#processor).lock().await;
processor.collect_completed_results();
if processor.cancel_task(&task_id) {
return Ok(());
}
// If already completed, signal it's not cancellable
let exists_completed = processor.peek_completed().iter().any(|r| r.descriptor.operation_id == task_id);
if exists_completed {
return Err(McpError::invalid_request(format!("task already completed: {}", task_id), None));
}
Err(McpError::resource_not_found(format!("task not found: {}", task_id), None))
}
};
item_impl.items.push(syn::parse2::<ImplItem>(cancel_fn)?);
}
Ok(item_impl.into_token_stream())
}