solti_api/
handler.rs

1//! # Handler trait.
2//!
3//! [`ApiHandler`] defines the transport-agnostic API surface.
4//! Implement this trait to plug custom logic (auth, rate limiting, metrics) between the wire layer and the supervisor.
5
6use async_trait::async_trait;
7use solti_model::{Task, TaskId, TaskPage, TaskQuery, TaskRun, TaskSpec};
8
9use crate::error::ApiError;
10
11/// Task execution API handler.
12///
13/// ## Also
14///
15/// - [`SupervisorApiAdapter`](crate::SupervisorApiAdapter) ready-to-use implementation.
16/// - [`ApiError`](crate::ApiError) error type returned by all methods.
17///
18/// This trait abstracts the backend implementation, allowing users to:
19/// - Use the provided [`SupervisorApiAdapter`](crate::SupervisorApiAdapter)
20/// - Implement custom handlers with additional logic (auth, rate limiting, etc.)
21///
22/// ## API surface
23///
24/// | Method             | HTTP                              | gRPC                |
25/// |--------------------|-----------------------------------|---------------------|
26/// | `submit_task`      | `POST   /api/v1/tasks`            | `SubmitTask`        |
27/// | `get_task_status`  | `GET    /api/v1/tasks/{id}`       | `GetTaskStatus`     |
28/// | `query_tasks`      | `GET    /api/v1/tasks`            | `ListTasks`         |
29/// | `list_task_runs`   | `GET    /api/v1/tasks/{id}/runs`  | `ListTaskRuns`      |
30/// | `delete_task`      | `DELETE /api/v1/tasks/{id}`       | `DeleteTask`        |
31#[async_trait]
32pub trait ApiHandler: Send + Sync + 'static {
33    /// Submit a new task for execution.
34    async fn submit_task(&self, spec: TaskSpec) -> Result<TaskId, ApiError>;
35
36    /// Get current status of a task by ID.
37    async fn get_task_status(&self, id: &TaskId) -> Result<Option<Task>, ApiError>;
38
39    /// Query tasks with combined filters and pagination.
40    ///
41    /// Supports filtering by slot and/or status simultaneously, with offset/limit pagination. Returns a page with total count.
42    async fn query_tasks(&self, query: TaskQuery) -> Result<TaskPage<Task>, ApiError>;
43
44    /// List execution history for a specific task (oldest first).
45    async fn list_task_runs(&self, id: &TaskId) -> Result<Vec<TaskRun>, ApiError>;
46
47    /// Stop a task and purge its run history.
48    ///
49    /// Idempotent:
50    /// returns `Ok(())` whether the task is currently registered on the agent.
51    /// Errors only on supervisor cancellation failures (timeout, internal error).
52    async fn delete_task(&self, id: &TaskId) -> Result<(), ApiError>;
53}
solti_api/handler.rs

solti_api/
handler.rs
