act_types/
http.rs

1//! ACT-HTTP protocol types for request/response serialization.
2//!
3//! All types derive both `Serialize` and `Deserialize` so they can be used
4//! by servers (act-host), clients (act-bridge), and SDKs alike.
5
6use serde::{Deserialize, Serialize};
7
8/// ACT-HTTP protocol version.
9pub const PROTOCOL_VERSION: &str = "0.2";
10
11/// HTTP header name for the protocol version.
12pub const HEADER_PROTOCOL_VERSION: &str = "ACT-Protocol-Version";
13
14/// Server metadata returned by `GET /info`.
15#[derive(Debug, Clone, Serialize, Deserialize)]
16pub struct ServerInfo {
17    pub name: String,
18    pub version: String,
19    pub description: String,
20    pub default_language: String,
21    #[serde(skip_serializing_if = "Option::is_none")]
22    pub capabilities: Option<Vec<Capability>>,
23    #[serde(skip_serializing_if = "Option::is_none")]
24    pub metadata: Option<serde_json::Value>,
25}
26
27/// A server capability declaration.
28#[derive(Debug, Clone, Serialize, Deserialize)]
29pub struct Capability {
30    pub id: String,
31    pub required: bool,
32    #[serde(skip_serializing_if = "Option::is_none")]
33    pub description: Option<String>,
34}
35
36/// Tool definition returned in `ListToolsResponse`.
37#[derive(Debug, Clone, Serialize, Deserialize)]
38pub struct ToolDefinition {
39    pub name: String,
40    pub description: String,
41    pub parameters_schema: serde_json::Value,
42    #[serde(skip_serializing_if = "Option::is_none")]
43    pub metadata: Option<serde_json::Value>,
44}
45
46/// Response from `POST /tools`.
47#[derive(Debug, Clone, Serialize, Deserialize)]
48pub struct ListToolsResponse {
49    pub tools: Vec<ToolDefinition>,
50    #[serde(skip_serializing_if = "Option::is_none")]
51    pub metadata: Option<serde_json::Value>,
52}
53
54/// Request body for `POST /metadata-schema`.
55#[derive(Debug, Clone, Serialize, Deserialize, Default)]
56pub struct MetadataSchemaRequest {
57    #[serde(default, skip_serializing_if = "Option::is_none")]
58    pub metadata: Option<serde_json::Value>,
59}
60
61/// Request body for `POST /tools` and `QUERY /tools`.
62#[derive(Debug, Clone, Serialize, Deserialize, Default)]
63pub struct MetadataRequest {
64    #[serde(default, skip_serializing_if = "Option::is_none")]
65    pub metadata: Option<serde_json::Value>,
66}
67
68/// Request body for `POST /tools/{name}`.
69#[derive(Debug, Clone, Serialize, Deserialize)]
70pub struct ToolCallRequest {
71    pub arguments: serde_json::Value,
72    #[serde(default, skip_serializing_if = "Option::is_none")]
73    pub metadata: Option<serde_json::Value>,
74}
75
76/// A content part in a tool response.
77#[derive(Debug, Clone, Serialize, Deserialize)]
78pub struct ContentPart {
79    pub data: serde_json::Value,
80    #[serde(default, skip_serializing_if = "Option::is_none")]
81    pub mime_type: Option<String>,
82    #[serde(default, skip_serializing_if = "Option::is_none")]
83    pub metadata: Option<serde_json::Value>,
84}
85
86/// Response from `POST /tools/{name}`.
87#[derive(Debug, Clone, Serialize, Deserialize)]
88pub struct ToolCallResponse {
89    pub content: Vec<ContentPart>,
90    #[serde(default, skip_serializing_if = "Option::is_none")]
91    pub metadata: Option<serde_json::Value>,
92}
93
94/// Error object in error responses.
95#[derive(Debug, Clone, Serialize, Deserialize)]
96pub struct ToolError {
97    pub kind: String,
98    pub message: String,
99    #[serde(default, skip_serializing_if = "Option::is_none")]
100    pub metadata: Option<serde_json::Value>,
101}
102
103/// Wrapper for error responses (`{"error": ...}`).
104#[derive(Debug, Clone, Serialize, Deserialize)]
105pub struct ErrorResponse {
106    pub error: ToolError,
107}
108
109/// Resource info returned by `POST /resources`.
110#[derive(Debug, Clone, Serialize, Deserialize)]
111pub struct ResourceInfo {
112    pub uri: String,
113    #[serde(default, skip_serializing_if = "Option::is_none")]
114    pub mime_type: Option<String>,
115    pub description: String,
116    #[serde(default, skip_serializing_if = "Option::is_none")]
117    pub metadata: Option<serde_json::Value>,
118}
119
120/// Response from `POST /resources`.
121#[derive(Debug, Clone, Serialize, Deserialize)]
122pub struct ListResourcesResponse {
123    pub resources: Vec<ResourceInfo>,
124    #[serde(default, skip_serializing_if = "Option::is_none")]
125    pub metadata: Option<serde_json::Value>,
126}
127
128/// Map an ACT error kind to an HTTP status code per ACT-HTTP spec.
129pub fn error_kind_to_status(kind: &str) -> u16 {
130    use crate::constants::*;
131    match kind {
132        ERR_NOT_FOUND => 404,
133        ERR_INVALID_ARGS => 422,
134        ERR_TIMEOUT => 504,
135        ERR_CAPABILITY_DENIED => 403,
136        _ => 500,
137    }
138}
act_types/http.rs

act_types/
http.rs
