agent_first_http/shared/
afdata.rs

1//! AFDATA protocol adapter.
2//!
3//! Every `afhttp` command emits one AFDATA protocol-v1 event per invocation:
4//! a single-line `{"kind":"result","result":...}` or `{"kind":"error",
5//! "error":...}` JSON value followed by a newline.
6
7use serde::Serialize;
8use serde::de::DeserializeOwned;
9use std::io::Write;
10
11use crate::shared::error::Error;
12
13/// Emit a typed result event to `writer` and write it as one line of JSON followed
14/// by a newline. The command-specific `code` remains inside `result`.
15///
16/// Redacts AFDATA `_secret` fields by default and never panics on well-formed
17/// input — but we still funnel through this single seam so `print_stdout` /
18/// `print_stderr` stay clippy-denied at crate level.
19pub fn emit<W: Write, T: Serialize>(writer: &mut W, code: &str, payload: &T) -> Result<(), Error> {
20    emit_inner(writer, code, payload, RedactionMode::Default)
21}
22
23/// Emit a payload without AFDATA redaction. Use only for commands that require
24/// an explicit reveal flag and whose payload contains no unrelated secrets.
25pub fn emit_unredacted<W: Write, T: Serialize>(
26    writer: &mut W,
27    code: &str,
28    payload: &T,
29) -> Result<(), Error> {
30    emit_inner(writer, code, payload, RedactionMode::None)
31}
32
33#[derive(Clone, Copy)]
34enum RedactionMode {
35    Default,
36    None,
37}
38
39fn emit_inner<W: Write, T: Serialize>(
40    writer: &mut W,
41    code: &str,
42    payload: &T,
43    redaction: RedactionMode,
44) -> Result<(), Error> {
45    let mut value = serde_json::to_value(payload).map_err(|e| {
46        Error::new(
47            crate::shared::error::ErrorCode::InternalError,
48            format!("AFDATA: failed to serialize payload: {e}"),
49        )
50    })?;
51    value = wrap_payload(code, value)?;
52
53    let options = match redaction {
54        RedactionMode::Default => agent_first_data::OutputOptions::default(),
55        RedactionMode::None => agent_first_data::OutputOptions {
56            redaction: agent_first_data::Redactor::new()
57                .policy(agent_first_data::RedactionPolicy::Off),
58            style: agent_first_data::PlainStyle::Raw,
59        },
60    };
61    let mut emitter = agent_first_data::CliEmitter::with_options(
62        writer,
63        agent_first_data::OutputFormat::Json,
64        options,
65    )
66    .with_strict_protocol();
67    emitter.emit_result(value).map_err(|err| {
68        Error::new(
69            crate::shared::error::ErrorCode::InternalError,
70            err.to_string(),
71        )
72    })?;
73    Ok(())
74}
75
76fn wrap_payload(code: &str, value: serde_json::Value) -> Result<serde_json::Value, Error> {
77    let serde_json::Value::Object(mut map) = value else {
78        return Err(Error::new(
79            crate::shared::error::ErrorCode::InternalError,
80            "AFDATA result payload must serialize to a JSON object",
81        ));
82    };
83
84    map.insert("code".into(), serde_json::Value::String(code.to_string()));
85    Ok(serde_json::Value::Object(map))
86}
87
88/// Convenience: emit an SDK-built AFDATA error event.
89pub fn emit_error<W: Write>(writer: &mut W, err: &Error) -> Result<(), Error> {
90    let mut emitter =
91        agent_first_data::CliEmitter::new(writer, agent_first_data::OutputFormat::Json)
92            .with_strict_protocol();
93    let event = agent_first_data::json_error(err.error_code.as_str(), &err.detail)
94        .retryable_if(err.retryable)
95        .build()
96        .map_err(|err| {
97            Error::new(
98                crate::shared::error::ErrorCode::InternalError,
99                err.to_string(),
100            )
101        })?;
102    emitter.emit(event).map_err(|emit_err| {
103        Error::new(
104            crate::shared::error::ErrorCode::InternalError,
105            emit_err.to_string(),
106        )
107    })
108}
109
110/// Emit an error event with caller-owned extension fields and trace.
111pub fn emit_error_with<W: Write>(
112    writer: &mut W,
113    code: &str,
114    message: &str,
115    fields: serde_json::Value,
116    trace: serde_json::Value,
117) -> Result<(), Error> {
118    let mut emitter =
119        agent_first_data::CliEmitter::new(writer, agent_first_data::OutputFormat::Json)
120            .with_strict_protocol();
121    let retryable = fields
122        .get("retryable")
123        .and_then(serde_json::Value::as_bool)
124        .unwrap_or(false);
125    let fields = match fields {
126        serde_json::Value::Object(mut fields) => {
127            fields.remove("retryable");
128            serde_json::Value::Object(fields)
129        }
130        other => other,
131    };
132    let event = agent_first_data::json_error(code, message)
133        .retryable_if(retryable)
134        .fields(fields)
135        .trace(trace)
136        .build()
137        .map_err(|err| {
138            Error::new(
139                crate::shared::error::ErrorCode::InternalError,
140                err.to_string(),
141            )
142        })?;
143    emitter.emit(event).map_err(|err| {
144        Error::new(
145            crate::shared::error::ErrorCode::InternalError,
146            err.to_string(),
147        )
148    })
149}
150
151/// Build a strict AFDATA error event for HTTP response bodies.
152pub fn error_value(code: &str, message: &str, retryable: bool) -> serde_json::Value {
153    agent_first_data::json_error(code, message)
154        .retryable_if(retryable)
155        .build()
156        .map(Into::into)
157        .unwrap_or_else(|_| serde_json::json!({}))
158}
159
160/// Build a strict AFDATA result event for HTTP response bodies.
161pub fn result_value(code: &str, mut payload: serde_json::Value) -> serde_json::Value {
162    let payload = match &mut payload {
163        serde_json::Value::Object(fields) => {
164            fields
165                .entry("code".to_string())
166                .or_insert_with(|| serde_json::Value::String(code.to_string()));
167            payload
168        }
169        _ => serde_json::json!({"code": code, "value": payload}),
170    };
171    agent_first_data::json_result(payload).build().into()
172}
173
174pub fn decode_result<T: DeserializeOwned>(bytes: &[u8]) -> Result<T, Error> {
175    let text = std::str::from_utf8(bytes).map_err(|error| {
176        Error::new(
177            crate::shared::error::ErrorCode::InternalError,
178            format!("decode AFDATA event: {error}"),
179        )
180    })?;
181    match agent_first_data::decode_protocol_event(text) {
182        Ok(agent_first_data::DecodedEvent::Result(result)) => serde_json::from_value(result.result)
183            .map_err(|error| {
184                Error::new(
185                    crate::shared::error::ErrorCode::InternalError,
186                    format!("decode AFDATA result payload: {error}"),
187                )
188            }),
189        Ok(_) => Err(Error::new(
190            crate::shared::error::ErrorCode::InternalError,
191            "expected AFDATA result event",
192        )),
193        Err(error) => Err(Error::new(
194            crate::shared::error::ErrorCode::InternalError,
195            format!("invalid AFDATA event: {error}"),
196        )),
197    }
198}
199
200pub fn decode_error(bytes: &[u8]) -> Result<Error, Error> {
201    let text = std::str::from_utf8(bytes).map_err(|error| {
202        Error::new(
203            crate::shared::error::ErrorCode::InternalError,
204            format!("decode AFDATA error event: {error}"),
205        )
206    })?;
207    match agent_first_data::decode_protocol_event(text) {
208        Ok(agent_first_data::DecodedEvent::Error(error)) => {
209            let code = serde_json::from_value(serde_json::Value::String(error.code))
210                .unwrap_or(crate::shared::error::ErrorCode::InternalError);
211            Ok(Error::new(code, error.message).with_retryable(error.retryable))
212        }
213        Ok(_) => Err(Error::new(
214            crate::shared::error::ErrorCode::InternalError,
215            "expected AFDATA error event",
216        )),
217        Err(error) => Err(Error::new(
218            crate::shared::error::ErrorCode::InternalError,
219            format!("invalid AFDATA error event: {error}"),
220        )),
221    }
222}
223
224#[cfg(test)]
225mod tests {
226    use super::*;
227
228    #[derive(Serialize)]
229    struct HealthPayload {
230        status: &'static str,
231        uptime_s: u64,
232    }
233
234    #[test]
235    fn json_result_event_is_single_line_with_code_field() {
236        let mut buf = Vec::new();
237        let payload = HealthPayload {
238            status: "ok",
239            uptime_s: 42,
240        };
241        emit(&mut buf, "health", &payload).unwrap();
242        let s = String::from_utf8(buf).unwrap_or_default();
243        assert!(s.ends_with('\n'));
244        let trimmed = s.trim_end();
245        let parsed: serde_json::Value = serde_json::from_str(trimmed).unwrap();
246        assert_eq!(parsed["kind"], "result");
247        assert_eq!(parsed["result"]["code"], "health");
248        assert_eq!(parsed["result"]["status"], "ok");
249        assert_eq!(parsed["result"]["uptime_s"], 42);
250        assert_eq!(trimmed.lines().count(), 1);
251    }
252
253    #[test]
254    fn error_event_uses_error_code_tag() {
255        let mut buf = Vec::new();
256        let err = Error::new(
257            crate::shared::error::ErrorCode::NavigationTimeout,
258            "no load",
259        );
260        emit_error(&mut buf, &err).unwrap();
261        let parsed: serde_json::Value =
262            serde_json::from_slice(&buf).unwrap_or(serde_json::Value::Null);
263        assert_eq!(parsed["kind"], "error");
264        assert_eq!(parsed["error"]["code"], "navigation_timeout");
265        assert_eq!(parsed["error"]["message"], "no load");
266        assert_eq!(parsed["error"]["retryable"], true);
267    }
268
269    #[test]
270    fn error_extension_fields_are_flattened_into_error_payload() {
271        let mut buf = Vec::new();
272        emit_error_with(
273            &mut buf,
274            "navigation_timeout",
275            "no load",
276            serde_json::json!({
277                "retryable": true,
278                "stage": "capture_text",
279                "details": "scalar detail remains an explicitly named field"
280            }),
281            serde_json::json!({"duration_ms": 10}),
282        )
283        .unwrap();
284        let parsed: serde_json::Value = serde_json::from_slice(&buf).unwrap();
285        assert_eq!(parsed["error"]["stage"], "capture_text");
286        assert_eq!(parsed["error"]["retryable"], true);
287        assert_eq!(
288            parsed["error"]["details"],
289            "scalar detail remains an explicitly named field"
290        );
291        assert!(parsed["error"].get("fields").is_none());
292    }
293
294    #[derive(Serialize)]
295    struct SecretPayload {
296        token_secret: &'static str,
297    }
298
299    #[test]
300    fn afdata_event_redacts_secret_fields() {
301        let mut buf = Vec::new();
302        emit(
303            &mut buf,
304            "container_status",
305            &SecretPayload {
306                token_secret: "supersecret",
307            },
308        )
309        .unwrap();
310        let parsed: serde_json::Value = serde_json::from_slice(&buf).unwrap();
311        assert_eq!(parsed["result"]["token_secret"], "***");
312    }
313
314    #[test]
315    fn envelope_uses_sdk_result_payload_without_nested_envelope() {
316        let mut buf = Vec::new();
317        let payload = serde_json::json!({"code": -32000, "message": "cdp error"});
318        emit(&mut buf, "cdp", &payload).unwrap();
319        let parsed: serde_json::Value = serde_json::from_slice(&buf).unwrap();
320        assert_eq!(parsed["kind"], "result");
321        assert_eq!(parsed["result"]["code"], "cdp");
322        assert_eq!(parsed["result"]["code"], "cdp");
323        assert_eq!(parsed["result"]["message"], "cdp error");
324        assert!(parsed["result"].get("result").is_none());
325    }
326}
agent_first_http/shared/afdata.rs

agent_first_http/shared/
afdata.rs
