Skip to main content

aios_action/
android_adapter.rs

1//! 一等公民 `AndroidAdapter`:把已封存的 `AuthorizedAction` 经请求/响应协议
2//! 转发到设备侧 localhost bridge,并把设备的真实执行结果如实映射为
3//! `ActionOutcome` / `AdapterError`。
4//!
5//! 与旧实现(`DefaultActionExecutor` 内部 env 分支 + fire-and-forget)相比的关键差异:
6//!
7//! 1. **诚实的 outcome**:请求/响应。转发后**读取**设备回执;超时、连接被拒、设备
8//!    拒绝或回执非法都返回 `Err(AdapterError::AndroidBridgeError)` → 生命周期记为
9//!    `Failed`,而不再把"一次成功的 TCP 写"谎报为 `Succeeded`。
10//! 2. **注入式配置**:[`AndroidBridgeConfig`] 在**构造时**注入,`execute()` 内不再
11//!    读取进程环境变量 —— 移除执行期的 ambient authority。
12//! 3. **HMAC 绑定**:认证标签覆盖 freshness window 与 `AuthorizedAction` 字节,
13//!    而非静态 bearer token,使捕获到的标签无法重放到另一个 action 或过期窗口。
14//!
15//! 非转发类动作(或缺少有效目标的 `PrefetchFile`)回退到内部
16//! [`DefaultActionExecutor`] 的确定性本地 stub —— 复用同一套 stub 语义,不重复实现。
17//!
18//! 注意:`AndroidAdapter` **不**进入 golden/replay 的 hash 路径(那条路径用
19//! `OfflineAdapter`)。设备侧 latency/成败本就非确定,本 adapter 只产生供检视的
20//! 审计轨迹,不参与可复现性断言。
21
22use std::env;
23use std::io::{ErrorKind, Read, Write};
24use std::net::{Shutdown, TcpStream};
25use std::time::{Duration, SystemTime, UNIX_EPOCH};
26
27use aios_core::governance::{ActionAdapter, AuthorizedAction};
28use aios_spec::bridge::{
29    BridgeAuth, BridgeExecuteRequest, BridgeExecuteResponse, BridgeStatus,
30    BRIDGE_MESSAGE_TYPE_EXECUTE,
31};
32use aios_spec::governance::{ActionOutcome, AdapterError};
33use aios_spec::intent::{ActionType, SuggestedAction};
34use hmac::{Hmac, Mac};
35use sha2::Sha256;
36
37use crate::DefaultActionExecutor;
38
39type HmacSha256 = Hmac<Sha256>;
40
41const DEFAULT_ANDROID_ACTION_BRIDGE_PORT: u16 = 46321;
42const ANDROID_ACTION_PAYLOAD_TTL_MS: i64 = 60_000;
43const READ_TIMEOUT_MS: u64 = 5000;
44const MAX_RESPONSE_BYTES: usize = 4096;
45
46/// 转发到 Android bridge 所需的配置。构造时注入,不在 `execute()` 内读 env。
47#[derive(Debug, Clone)]
48pub struct AndroidBridgeConfig {
49    pub host: String,
50    pub port: u16,
51    /// HMAC-SHA256 共享密钥(key),转发时必需。
52    pub auth_key: Option<String>,
53}
54
55impl AndroidBridgeConfig {
56    /// 从环境变量构造配置。**仅供启动期**调用一次(如 daemon 装配 adapter 时),
57    /// 不应在每次动作执行时调用。返回 `None` 表示未启用 Android bridge。
58    pub fn from_env() -> Option<Self> {
59        if !env_flag("DIPECS_ANDROID_ACTION_BRIDGE_ENABLED") {
60            return None;
61        }
62
63        let host = env::var("DIPECS_ANDROID_ACTION_BRIDGE_HOST")
64            .ok()
65            .filter(|value| !value.trim().is_empty())
66            .unwrap_or_else(|| "127.0.0.1".to_string());
67        let port = env::var("DIPECS_ANDROID_ACTION_BRIDGE_PORT")
68            .ok()
69            .and_then(|value| value.parse::<u16>().ok())
70            .unwrap_or(DEFAULT_ANDROID_ACTION_BRIDGE_PORT);
71        let auth_key = env::var("DIPECS_ANDROID_ACTION_BRIDGE_TOKEN")
72            .ok()
73            .filter(|value| !value.trim().is_empty());
74        Some(Self {
75            host,
76            port,
77            auth_key,
78        })
79    }
80}
81
82/// 转发到设备侧 bridge 的一等 adapter。
83pub struct AndroidAdapter {
84    config: AndroidBridgeConfig,
85    /// 非转发类动作的本地回退执行器(确定性 stub)。
86    fallback: DefaultActionExecutor,
87}
88
89impl AndroidAdapter {
90    pub fn new(config: AndroidBridgeConfig) -> Self {
91        Self {
92            config,
93            fallback: DefaultActionExecutor::new(),
94        }
95    }
96
97    /// 把动作转发到设备并把回执映射为 outcome。任何失败均为 `Err` → `Failed`。
98    fn forward(
99        &self,
100        authorized: &AuthorizedAction,
101        target: &str,
102    ) -> Result<ActionOutcome, AdapterError> {
103        let auth_key = self.config.auth_key.as_deref().ok_or_else(|| {
104            AdapterError::AndroidBridgeError(
105                "DIPECS_ANDROID_ACTION_BRIDGE_TOKEN is required when forwarding to Android bridge"
106                    .into(),
107            )
108        })?;
109
110        // canonical 序列化 AuthorizedAction;HMAC 绑定这些字节和 freshness window。
111        let action_json = serde_json::to_string(authorized).map_err(|error| {
112            AdapterError::AndroidBridgeError(format!("serialize AuthorizedAction: {error}"))
113        })?;
114        let issued_at_ms = SystemTime::now()
115            .duration_since(UNIX_EPOCH)
116            .map_err(|error| {
117                AdapterError::AndroidBridgeError(format!(
118                    "calculate Android bridge payload issue time: {error}"
119                ))
120            })?
121            .as_millis() as i64;
122        let expires_at_ms = issued_at_ms + ANDROID_ACTION_PAYLOAD_TTL_MS;
123        let canonical = canonical_execute_envelope_input(issued_at_ms, expires_at_ms, &action_json);
124        let hmac_sha256 = compute_hmac(auth_key, canonical.as_bytes())
125            .map_err(AdapterError::AndroidBridgeError)?;
126
127        let request = BridgeExecuteRequest {
128            message_type: BRIDGE_MESSAGE_TYPE_EXECUTE.to_string(),
129            issued_at_ms,
130            expires_at_ms,
131            auth: BridgeAuth { hmac_sha256 },
132            action: action_json,
133        };
134        let payload = serde_json::to_string(&request).map_err(|error| {
135            AdapterError::AndroidBridgeError(format!("serialize bridge request: {error}"))
136        })?;
137
138        let raw = send_request(&self.config.host, self.config.port, payload.as_bytes())
139            .map_err(AdapterError::AndroidBridgeError)?;
140        let response: BridgeExecuteResponse = serde_json::from_slice(&raw).map_err(|error| {
141            AdapterError::AndroidBridgeError(format!("parse bridge response: {error}"))
142        })?;
143
144        match response.status {
145            BridgeStatus::Ok => {
146                tracing::info!(
147                    host = %self.config.host,
148                    port = self.config.port,
149                    target = %target,
150                    "AndroidAdapter: device confirmed execution"
151                );
152                Ok(ActionOutcome {
153                    action_type: format!("{:?}", authorized.action().action_type),
154                    target: authorized.action().target.clone(),
155                    summary: response
156                        .summary
157                        .unwrap_or_else(|| "android_executed".to_string()),
158                    latency_us: response.latency_us.unwrap_or(0),
159                })
160            },
161            BridgeStatus::Rejected => Err(AdapterError::AndroidBridgeError(format!(
162                "android bridge rejected action: {}",
163                response
164                    .error
165                    .unwrap_or_else(|| "no reason given".to_string())
166            ))),
167            BridgeStatus::Error => Err(AdapterError::AndroidBridgeError(format!(
168                "android bridge execution error: {}",
169                response
170                    .error
171                    .unwrap_or_else(|| "no detail given".to_string())
172            ))),
173        }
174    }
175}
176
177impl ActionAdapter for AndroidAdapter {
178    fn name(&self) -> &'static str {
179        "android"
180    }
181
182    fn execute(&self, authorized: &AuthorizedAction) -> Result<ActionOutcome, AdapterError> {
183        match classify(authorized.action()) {
184            Route::Forward(target) => self.forward(authorized, target),
185            Route::Local => self.fallback.execute(authorized),
186        }
187    }
188}
189
190/// 路由判定:
191///   - `PrefetchFile`:仅带 `url:`/`uri:` 目标时转发到设备。
192///   - `PreWarmProcess` / `KeepAlive` / `ReleaseMemory`:无条件转发到设备;
193///     设备侧 bridge 解析 `AuthorizedAction` 中内嵌的 `action_type` + `target`
194///     并执行结构化动作。
195///   - `NoOp` 及其它未知类型留在本地 stub。
196enum Route<'a> {
197    Forward(&'a str),
198    Local,
199}
200
201fn classify(action: &SuggestedAction) -> Route<'_> {
202    match action.action_type {
203        ActionType::PrefetchFile => match action.target.as_deref() {
204            Some(target) if target.starts_with("url:") || target.starts_with("uri:") => {
205                Route::Forward(target)
206            },
207            _ => Route::Local,
208        },
209        ActionType::PreWarmProcess | ActionType::KeepAlive | ActionType::ReleaseMemory => {
210            Route::Forward(action.target.as_deref().unwrap_or(""))
211        },
212        _ => Route::Local,
213    }
214}
215
216/// Canonical HMAC input shared with the Android bridge.
217fn canonical_execute_envelope_input(
218    issued_at_ms: i64,
219    expires_at_ms: i64,
220    action_json: &str,
221) -> String {
222    format!(
223        "dipecs.android.bridge.execute.v1\nissued_at_ms:{issued_at_ms}\nexpires_at_ms:{expires_at_ms}\naction:{}:{action_json}",
224        action_json.len(),
225    )
226}
227
228/// 对 canonical 消息字节计算 HMAC-SHA256,返回小写 hex。
229fn compute_hmac(key: &str, message: &[u8]) -> Result<String, String> {
230    let mut mac = HmacSha256::new_from_slice(key.as_bytes())
231        .map_err(|error| format!("init HMAC key: {error}"))?;
232    mac.update(message);
233    Ok(hex::encode(mac.finalize().into_bytes()))
234}
235
236/// 建连、写请求、半关写端发 EOF、读到 EOF/完整 JSON/超时为止。
237///
238/// 这是"诚实"的核心:超时且无数据、连接被拒、对端空回都映射为 `Err`,绝不静默成功。
239fn send_request(host: &str, port: u16, payload: &[u8]) -> Result<Vec<u8>, String> {
240    let mut stream = TcpStream::connect((host, port))
241        .map_err(|error| format!("connect Android bridge {host}:{port}: {error}"))?;
242    stream
243        .set_read_timeout(Some(Duration::from_millis(READ_TIMEOUT_MS)))
244        .map_err(|error| format!("set read timeout: {error}"))?;
245    stream
246        .write_all(payload)
247        .map_err(|error| format!("write request to {host}:{port}: {error}"))?;
248    stream
249        .flush()
250        .map_err(|error| format!("flush request to {host}:{port}: {error}"))?;
251    // 半关写端:让按 EOF 读取的服务端知道请求已完整,立即回执。
252    stream
253        .shutdown(Shutdown::Write)
254        .map_err(|error| format!("shutdown write to {host}:{port}: {error}"))?;
255
256    let mut buf = Vec::with_capacity(MAX_RESPONSE_BYTES);
257    let mut chunk = [0u8; 1024];
258    loop {
259        match stream.read(&mut chunk) {
260            Ok(0) => break,
261            Ok(n) => {
262                if buf.len() + n > MAX_RESPONSE_BYTES {
263                    return Err(format!(
264                        "bridge response exceeded {MAX_RESPONSE_BYTES} bytes"
265                    ));
266                }
267                buf.extend_from_slice(&chunk[..n]);
268                // 已能解析出完整 JSON 即可停(服务端可能保持半开)。
269                if serde_json::from_slice::<serde_json::Value>(&buf).is_ok() {
270                    break;
271                }
272            },
273            Err(error)
274                if error.kind() == ErrorKind::WouldBlock || error.kind() == ErrorKind::TimedOut =>
275            {
276                if buf.is_empty() {
277                    return Err(format!("read bridge response from {host}:{port}: {error}"));
278                }
279                break;
280            },
281            Err(error) => {
282                return Err(format!("read bridge response from {host}:{port}: {error}"));
283            },
284        }
285    }
286
287    if buf.is_empty() {
288        return Err(format!("bridge {host}:{port} closed without response"));
289    }
290    Ok(buf)
291}
292
293fn env_flag(name: &str) -> bool {
294    matches!(
295        env::var(name).ok().as_deref(),
296        Some("1" | "true" | "TRUE" | "yes" | "YES" | "on" | "ON")
297    )
298}
299
300#[cfg(test)]
301mod tests {
302    use std::io::{Read, Write};
303    use std::net::{Shutdown, TcpListener};
304    use std::thread;
305
306    use aios_spec::intent::ActionUrgency;
307
308    use super::*;
309
310    #[test]
311    fn env_flag_accepts_true_values() {
312        assert!(env_flag_eval("true"));
313        assert!(env_flag_eval("1"));
314        assert!(env_flag_eval("ON"));
315        assert!(!env_flag_eval("false"));
316        assert!(!env_flag_eval(""));
317    }
318
319    fn env_flag_eval(value: &str) -> bool {
320        std::env::set_var("DIPECS_TEST_FLAG", value);
321        let enabled = env_flag("DIPECS_TEST_FLAG");
322        std::env::remove_var("DIPECS_TEST_FLAG");
323        enabled
324    }
325
326    #[test]
327    fn hmac_is_deterministic_and_key_sensitive() {
328        let a = compute_hmac("k1", b"payload").unwrap();
329        let b = compute_hmac("k1", b"payload").unwrap();
330        let c = compute_hmac("k2", b"payload").unwrap();
331        let d = compute_hmac("k1", b"payload2").unwrap();
332        assert_eq!(a, b, "same key+message must yield same tag");
333        assert_ne!(a, c, "different key must change tag");
334        assert_ne!(a, d, "different message must change tag");
335        assert_eq!(a.len(), 64, "SHA-256 HMAC hex is 64 chars");
336    }
337
338    fn prefetch(target: Option<&str>) -> SuggestedAction {
339        SuggestedAction {
340            action_type: ActionType::PrefetchFile,
341            target: target.map(|s| s.to_string()),
342            urgency: ActionUrgency::Immediate,
343        }
344    }
345
346    #[test]
347    fn classify_routes_url_prefetch_to_forward() {
348        assert!(matches!(
349            classify(&prefetch(Some("url:https://x.test/a"))),
350            Route::Forward(_)
351        ));
352        assert!(matches!(
353            classify(&prefetch(Some("uri:content://x"))),
354            Route::Forward(_)
355        ));
356    }
357
358    #[test]
359    fn classify_routes_non_forwardable_to_local() {
360        // PrefetchFile without an Android target stays local.
361        assert!(matches!(
362            classify(&prefetch(Some("file:/tmp/x"))),
363            Route::Local
364        ));
365        assert!(matches!(classify(&prefetch(None)), Route::Local));
366        // NoOp (and any truly unknown type) stays local.
367        let noop = SuggestedAction {
368            action_type: ActionType::NoOp,
369            target: None,
370            urgency: ActionUrgency::Immediate,
371        };
372        assert!(matches!(classify(&noop), Route::Local));
373    }
374
375    #[test]
376    fn classify_routes_forwarded_actions() {
377        // PreWarmProcess, KeepAlive, ReleaseMemory always forward.
378        for (action_type, target) in [
379            (ActionType::PreWarmProcess, Some("pkg:com.example")),
380            (ActionType::PreWarmProcess, None),
381            (ActionType::KeepAlive, Some("work:collector_heartbeat")),
382            (ActionType::KeepAlive, None),
383            (ActionType::ReleaseMemory, Some("cache:prefetch")),
384            (ActionType::ReleaseMemory, None),
385        ] {
386            let action = SuggestedAction {
387                action_type: action_type.clone(),
388                target: target.map(|s| s.to_string()),
389                urgency: ActionUrgency::Immediate,
390            };
391            assert!(
392                matches!(classify(&action), Route::Forward(_)),
393                "{:?} with target {:?} must forward",
394                action.action_type,
395                action.target,
396            );
397        }
398    }
399
400    /// 启动一个一次性 TCP 服务端:读到 EOF 后回送 `response`。
401    fn spawn_responder(response: &'static [u8]) -> u16 {
402        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
403        let port = listener.local_addr().unwrap().port();
404        thread::spawn(move || {
405            let (mut stream, _) = listener.accept().unwrap();
406            let mut buf = Vec::new();
407            let mut chunk = [0u8; 1024];
408            loop {
409                match stream.read(&mut chunk) {
410                    Ok(0) => break,
411                    Ok(n) => buf.extend_from_slice(&chunk[..n]),
412                    Err(_) => break,
413                }
414            }
415            stream.write_all(response).unwrap();
416            stream.flush().unwrap();
417            stream.shutdown(Shutdown::Write).ok();
418        });
419        port
420    }
421
422    #[test]
423    fn send_request_returns_response_bytes() {
424        let port = spawn_responder(br#"{"status":"ok","summary":"done","latency_us":7}"#);
425        let raw = send_request("127.0.0.1", port, b"req").unwrap();
426        let parsed: BridgeExecuteResponse = serde_json::from_slice(&raw).unwrap();
427        assert_eq!(parsed.status, BridgeStatus::Ok);
428        assert_eq!(parsed.summary.as_deref(), Some("done"));
429        assert_eq!(parsed.latency_us, Some(7));
430    }
431
432    #[test]
433    fn send_request_fails_closed_on_refused_connection() {
434        // Nothing is listening on this port → connect fails → Err (never silent success).
435        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
436        let port = listener.local_addr().unwrap().port();
437        drop(listener); // free the port so connect is refused
438        let err = send_request("127.0.0.1", port, b"req").unwrap_err();
439        assert!(err.contains("connect Android bridge"), "got: {err}");
440    }
441
442    #[test]
443    fn send_request_fails_when_peer_closes_without_response() {
444        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
445        let port = listener.local_addr().unwrap().port();
446        thread::spawn(move || {
447            let (mut stream, _) = listener.accept().unwrap();
448            // Drain the request (avoid an RST from unread data), then close
449            // without replying: the client sees a clean EOF with empty buffer.
450            let mut chunk = [0u8; 1024];
451            loop {
452                match stream.read(&mut chunk) {
453                    Ok(0) => break,
454                    Ok(_) => {},
455                    Err(_) => break,
456                }
457            }
458            drop(stream);
459        });
460        let err = send_request("127.0.0.1", port, b"req").unwrap_err();
461        assert!(err.contains("closed without response"), "got: {err}");
462    }
463}