Skip to main content

iphone_cli/device/
session.rs

1//! Everything the daemon holds open for one phone: the tunnel, the
2//! accessibility subscription and the touch-input session.
3
4use std::{
5    sync::Arc,
6    time::{Duration, Instant},
7};
8
9use idevice::{
10    ReadWrite, RsdService,
11    core_device::{
12        AppListEntry, AppServiceClient, ImageFormat, PasteboardServiceClient,
13        ScreenCaptureServiceClient,
14    },
15    os_trace_relay::{OsTraceRelayClient, OsTraceRelayReceiver},
16};
17
18use crate::{
19    ax::{
20        dump::Dump,
21        tree::{BuildOptions, Screen},
22    },
23    config::Config,
24    device::{
25        ax::{ANSWER_AT_LEAST, AxSub},
26        conn::{self, Tunnel},
27        input::InputSession,
28    },
29    i18n::t,
30    reply::{Fail, Res},
31    tcp::handle::Reset,
32};
33
34const APP_SERVICE: &str = "com.apple.coredevice.appservice";
35
36/// One touch or button gesture, in normalized HID coordinates.
37#[derive(Debug, Clone)]
38pub enum Gesture {
39    Tap { x: u16, y: u16, hold: Duration },
40    DoubleTap { x: u16, y: u16 },
41    Drag { from: (u16, u16), to: (u16, u16), duration: Duration, motion: crate::device::input::Motion },
42    Button { page: u64, usage: u64, hold: Duration },
43    Pinch(crate::device::pinch::Plan),
44}
45
46/// How fresh a reading must be.
47#[derive(Debug, Clone, Copy, PartialEq)]
48pub enum Fresh {
49    /// Ask the phone for a new dump and wait for it.
50    Force,
51    /// Accept the latest dump if it is at most this old.
52    MaxAge(Duration),
53}
54
55/// A cached reading younger than this is reused when a command follows
56/// another one closely (scripts, batches).
57pub const REUSE: Duration = Duration::from_millis(1500);
58
59/// `REUSE`, or `IPH_REUSE_MS` when set (for experiments).
60pub fn reuse() -> Duration {
61    std::env::var("IPH_REUSE_MS")
62        .ok()
63        .and_then(|v| v.parse().ok())
64        .map(Duration::from_millis)
65        .unwrap_or(REUSE)
66}
67/// How long to wait for one dump before asking again. Dumps requested during
68/// an animation sometimes never come.
69/// How long to wait for the answer to a request before asking again. Every
70/// request restarts the phone's wait, so this must be generous: answers took
71/// up to 5.8 s while a list was still settling.
72const ASK_AGAIN: Duration = Duration::from_millis(6500);
73const READ_TIMEOUT: Duration = Duration::from_secs(14);
74/// The phone's accessibility daemon is not ended more often than this.
75const AX_RESTART_GAP: Duration = Duration::from_secs(120);
76/// Shortest time between the end of one input session and the start of the
77/// next.
78const REOPEN_GAP: Duration = Duration::from_millis(2000);
79const SECOND_PASS_WAIT: Duration = Duration::from_millis(2500);
80
81/// How the phone's accessibility daemon failed a reading, when that calls
82/// for ending it so the phone starts a new one.
83#[derive(Debug, PartialEq, Clone, Copy)]
84pub(crate) enum AxStall {
85    /// Not a word on a connection that is up.
86    Silent,
87    /// Only answers that carry nothing (no application, no element). That is
88    /// how it stayed for 25 minutes on 2026-11-11 (every reading
89    /// `ax_timeout`, three empty answers each) while the phone was unlocked
90    /// and showing Settings; a new daemon answered at once.
91    EmptyOnly,
92}
93
94/// `empty` and `unparsed`: answers of each kind during the failed reading.
95/// Answers that were not understood point at the parser, not the daemon.
96pub(crate) fn ax_stall(empty: u64, unparsed: u64) -> Option<AxStall> {
97    match (empty, unparsed) {
98        (0, 0) => Some(AxStall::Silent),
99        (_, 0) => Some(AxStall::EmptyOnly),
100        _ => None,
101    }
102}
103
104pub struct Session {
105    pub udid: String,
106    pub config: Config,
107    pub tunnel: Option<Tunnel>,
108    pub ax: Option<AxSub>,
109    pub input: Option<InputSession>,
110    pub(crate) input_used: Instant,
111    /// When the last input session ended, to keep the next one apart from it.
112    input_closed_at: Option<Instant>,
113    /// A system panel came up over the app after the last tap (a Face ID
114    /// prompt, for one). Scrolls sent on the same input session right after
115    /// that moved nothing, with no error (seen once, 2026-11-11), so the next
116    /// gesture starts a new session.
117    pub(crate) input_suspect: bool,
118    /// Input sessions given up after an error, each with the tunnel it ran on
119    /// when that was given up too. Their streams are stopped at the next
120    /// quiet moment (`sweep`).
121    abandoned: Vec<(InputSession, Option<Tunnel>)>,
122    apps: Option<Vec<AppListEntry>>,
123    /// Logical screen size from the last complete reading.
124    pub(crate) screen_size: Option<(f64, f64)>,
125    /// Readings that arrived before this moment no longer describe the
126    /// screen (something changed it after they were taken).
127    stale_before: Option<Instant>,
128    /// Counts tunnel (re)connections, for `iph doctor` and logs.
129    pub connects: u64,
130    /// How often, and when last, the phone's accessibility daemon was ended
131    /// because it had stopped answering.
132    pub ax_restarts: u64,
133    ax_restarted_at: Option<Instant>,
134    /// The daemon was ended and the one the phone started in its place did
135    /// not answer either, or it could not be ended. It is not ended again
136    /// until a reading comes back: on 2026-11-12, after about six ends in
137    /// ten minutes, the phone stopped starting it at all until the phone was
138    /// locked and unlocked.
139    ax_restart_unhelpful: bool,
140    /// The last complete reading showed the home screen, Control Center or
141    /// another of the system's panels. The daemon is not ended for a stall
142    /// there: Control Center during a screen recording gets no answer from
143    /// a new daemon either, and the old one answers again once it is closed
144    /// (2026-11-12).
145    system_in_front: bool,
146    /// Do Not Disturb: whether it is on for this session and what to put back.
147    pub dnd: crate::dnd::State,
148    /// `iph syslog`: the log capture, running or ended and not yet stopped.
149    pub capture: Option<crate::syslog::Capture>,
150}
151
152/// A file URL or path as a plain path without a trailing slash.
153pub(crate) fn plain_path(s: &str) -> String {
154    let s = s.strip_prefix("file://").unwrap_or(s);
155    let raw = s.as_bytes();
156    let mut bytes = Vec::with_capacity(raw.len());
157    let mut i = 0;
158    while i < raw.len() {
159        if raw[i] == b'%' && i + 2 < raw.len() {
160            let hex = std::str::from_utf8(&raw[i + 1..i + 3]).unwrap_or("");
161            if let Ok(v) = u8::from_str_radix(hex, 16) {
162                bytes.push(v);
163                i += 3;
164                continue;
165            }
166        }
167        bytes.push(raw[i]);
168        i += 1;
169    }
170    let mut path = String::from_utf8_lossy(&bytes).into_owned();
171    while path.len() > 1 && path.ends_with('/') {
172        path.pop();
173    }
174    // The same app is reported under /private/var and /var.
175    path.strip_prefix("/private").map(String::from).unwrap_or(path)
176}
177
178fn is_transport_error(msg: &str) -> bool {
179    let m = msg.to_lowercase();
180    [
181        "adapter closed",
182        "broken pipe",
183        "channel recv timeout",
184        "connection reset",
185        "not connected",
186        "timed out",
187        "closed",
188        "unreachable",
189        "eof",
190    ]
191    .iter()
192    .any(|needle| m.contains(needle))
193}
194
195/// Bound a device call that has no time limit of its own.
196async fn bounded<T, E: std::fmt::Debug>(
197    what: &str,
198    secs: u64,
199    fut: impl std::future::Future<Output = Result<T, E>>,
200) -> Result<T, String> {
201    match tokio::time::timeout(Duration::from_secs(secs), fut).await {
202        Ok(Ok(v)) => Ok(v),
203        Ok(Err(e)) => Err(format!("{what}: {e:?}")),
204        Err(_) => Err(format!("{what}: no answer within {secs} s")),
205    }
206}
207
208impl Session {
209    pub fn new(udid: String, config: Config) -> Self {
210        let dnd = crate::dnd::State::load(&udid);
211        Self {
212            udid,
213            config,
214            tunnel: None,
215            ax: None,
216            input: None,
217            input_used: Instant::now(),
218            input_closed_at: None,
219            input_suspect: false,
220            abandoned: Vec::new(),
221            apps: None,
222            screen_size: None,
223            stale_before: None,
224            connects: 0,
225            ax_restarts: 0,
226            ax_restarted_at: None,
227            ax_restart_unhelpful: false,
228            system_in_front: false,
229            dnd,
230            capture: None,
231        }
232    }
233
234    /// Mark every reading taken so far as out of date.
235    /// Age of the latest reading, unless it predates `invalidate_readings`.
236    pub(crate) fn reading_age(&self) -> Option<Duration> {
237        let arrived = self.ax.as_ref()?.latest_arrival()?;
238        if self.stale_before.is_some_and(|limit| arrived < limit) {
239            return None;
240        }
241        Some(arrived.elapsed())
242    }
243
244    pub fn invalidate_readings(&mut self) {
245        self.stale_before = Some(Instant::now());
246    }
247
248    /// Port of an RSD service, for connections made outside `&mut self`.
249    pub async fn service_port(&mut self, name: &str) -> Res<(crate::tcp::handle::AdapterHandle, u16)> {
250        let tunnel = self.ensure_tunnel().await?;
251        let port = tunnel
252            .rsd
253            .services
254            .get(name)
255            .map(|s| s.port)
256            .ok_or_else(|| Fail::not_sent("service_unavailable", format!("{name} is not on offer")))?;
257        Ok((tunnel.adapter.clone(), port))
258    }
259
260    /// Abandon the input session without the orderly close (after an error).
261    pub fn drop_input(&mut self) {
262        if let Some(input) = self.input.take() {
263            self.input_closed_at = Some(Instant::now());
264            self.abandoned.push((input, None));
265        }
266    }
267
268    /// Drop every connection. The next request builds them again.
269    pub fn reset(&mut self) {
270        // Its stream runs on the tunnel being dropped.
271        self.end_capture("the connection to the phone was reset");
272        let tunnel = self.tunnel.take();
273        if let Some(input) = self.input.take() {
274            self.input_closed_at = Some(Instant::now());
275            // The tunnel stays until the stream has been told to stop.
276            self.abandoned.push((input, tunnel));
277        }
278        self.ax = None;
279    }
280
281    /// Tell the phone to stop the streams of abandoned input sessions. Left
282    /// alone they keep the phone encoding, and after a row of timeouts
283    /// (2026-11-11, with the Mac overloaded) the phone answered ever slower.
284    pub async fn sweep(&mut self) {
285        for (input, tunnel) in std::mem::take(&mut self.abandoned) {
286            input.abandon().await;
287            drop(tunnel);
288        }
289    }
290
291    pub fn connection(&self) -> Option<&str> {
292        self.tunnel.as_ref().map(|t| t.connection.as_str())
293    }
294
295    /// Only invalidate cached connections; commands decide what to do next.
296    /// No input is replayed when a Wi-Fi heartbeat ends.
297    pub(crate) fn refresh_connection(&mut self) {
298        if self.tunnel.as_ref().is_some_and(Tunnel::is_closed) {
299            crate::events::record("connection", "closed", 0, serde_json::json!({ "udid": self.udid, "reason": "heartbeat ended" }));
300            self.reset();
301        }
302    }
303
304    pub async fn ensure_tunnel(&mut self) -> Res<&mut Tunnel> {
305        self.refresh_connection();
306        if self.tunnel.is_none() {
307            // One tunnel at a time: let go of an abandoned one first.
308            self.sweep().await;
309            let tunnel = conn::open_tunnel(&self.udid).await.map_err(|e| {
310                Fail::not_sent("tunnel_failed", format!("{e:#}")).hint(t(
311                    "폰이 같은 Wi-Fi에 있거나 USB로 연결되어 있고 잠금이 풀려 있는지 확인하세요. `iph doctor`로 점검할 수 있습니다.",
312                    "Check that the phone is on the same Wi-Fi or plugged in, and unlocked. Run `iph doctor`.",
313                ))
314            })?;
315            self.connects += 1;
316            self.tunnel = Some(tunnel);
317        }
318        Ok(self.tunnel.as_mut().unwrap())
319    }
320
321    async fn ensure_ax(&mut self) -> Res<()> {
322        self.refresh_connection();
323        if self.ax.as_ref().is_some_and(|a| a.is_closed()) {
324            // The accessibility connection died; the tunnel may be gone too.
325            self.reset();
326        }
327        if self.ax.is_none() {
328            let mut last = None;
329            for attempt in 0..2 {
330                let tunnel = self.ensure_tunnel().await?;
331                let mut adapter = tunnel.adapter.clone();
332                match bounded("accessibility service", 12, AxSub::open(&mut adapter, &tunnel.rsd)).await {
333                    Ok(ax) => {
334                        self.ax = Some(ax);
335                        return Ok(());
336                    }
337                    Err(e) => {
338                        last = Some(e);
339                        if attempt == 0 {
340                            self.reset();
341                        }
342                    }
343                }
344            }
345            return Err(Fail::not_sent(
346                "ax_unavailable",
347                last.unwrap_or_else(|| "accessibility service unavailable".into()),
348            )
349            .hint(t(
350                "개발자 모드가 켜져 있고 개발자 디스크 이미지가 연결되어 있어야 합니다. `iph doctor`로 확인하세요.",
351                "Developer Mode must be on and the developer disk image mounted. Run `iph doctor`.",
352            )));
353        }
354        Ok(())
355    }
356
357    /// End the phone's accessibility daemon (`axauditd`) so the phone starts
358    /// a new one. Returns the pid that was ended.
359    ///
360    /// The daemon sometimes goes silent: it runs and takes new connections
361    /// but answers no request, and neither a new tunnel nor another route
362    /// changes that (2026-11-11, twice, both after minutes of work over
363    /// Wi-Fi; the cause is not known). The new one answers at once.
364    async fn restart_ax_daemon(&mut self) -> Result<u32, String> {
365        let mut svc = self.app_service().await.map_err(|f| f.message)?;
366        let processes = bounded("list processes", 10, svc.list_processes()).await?;
367        let pid = processes
368            .iter()
369            .find(|p| {
370                p.executable_url
371                    .as_ref()
372                    .is_some_and(|u| plain_path(&u.relative).ends_with("/axauditd"))
373            })
374            .map(|p| p.pid)
375            .ok_or("axauditd is not among the phone's processes")?;
376        // SIGABRT first: the phone then writes a crash report with every
377        // thread's backtrace, which is the only record of where the daemon
378        // was stuck (Settings > Privacy & Security > Analytics & Improvements
379        // > Analytics Data, "axauditd-…"). SIGKILL after it in case the
380        // daemon does not go.
381        const SIGABRT: u32 = 6;
382        const SIGKILL: u32 = 9;
383        bounded("signal", 10, svc.send_signal(pid, SIGABRT)).await?;
384        tokio::time::sleep(Duration::from_millis(1500)).await;
385        let _ = bounded("signal", 5, svc.send_signal(pid, SIGKILL)).await;
386        Ok(pid)
387    }
388
389    /// One reading of the screen as the raw dump plus its sequence number.
390    /// `full` waits for the second pass (identifiers).
391    pub async fn dump(&mut self, fresh: Fresh, full: bool) -> Res<(u64, Arc<Dump>)> {
392        let mut started = Instant::now();
393        let mut restarted = false;
394        let mut reconnects = 0;
395        let mut second_pass_retries = 0;
396        let mut fresh = fresh;
397        // The connection's counts of empty and not understood answers when
398        // this reading began on it: only what came during the reading tells
399        // how the phone is answering now.
400        let mut base: Option<(Instant, u64, u64)> = None;
401        loop {
402            self.ensure_ax().await?;
403            let ax = self.ax.as_mut().unwrap();
404            if base.is_none_or(|(opened, _, _)| opened != ax.opened) {
405                base = Some((ax.opened, ax.empty_count(), ax.unparsed_count()));
406            }
407            let usable = match (self.stale_before, ax.latest_arrival()) {
408                (Some(limit), Some(arrived)) => arrived >= limit,
409                _ => true,
410            };
411            let cached = match fresh {
412                Fresh::MaxAge(max) if usable => ax
413                    .latest()
414                    .filter(|(_, _, age)| *age <= max)
415                    .map(|(seq, dump, _)| (seq, dump)),
416                _ => None,
417            };
418            let got = match cached {
419                Some(c) => Some(c),
420                None => {
421                    // A connection that has not delivered yet already has its
422                    // answer on the way; asking again would only delay it.
423                    let mut asked_at = if ax.latest().is_none() && ax.opened.elapsed() < ASK_AGAIN {
424                        Some(ax.opened)
425                    } else {
426                        ax.request().ok()
427                    };
428                    let mut got = None;
429                    while let Some(at) = asked_at {
430                        // Anything that arrives sooner than an answer can
431                        // belongs to an earlier request and may predate what
432                        // the caller wants to see.
433                        if let Some(x) = ax.wait_arrived(at + ANSWER_AT_LEAST, ASK_AGAIN).await {
434                            crate::device::ax::trace(|| {
435                                let ms = ax
436                                    .latest_arrival()
437                                    .map(|t| t.saturating_duration_since(at).as_millis())
438                                    .unwrap_or(0);
439                                format!("answer accepted {ms} ms after the request")
440                            });
441                            got = Some(x);
442                            break;
443                        }
444                        if ax.is_closed() || started.elapsed() >= READ_TIMEOUT {
445                            break;
446                        }
447                        asked_at = ax.request().ok();
448                    }
449                    got
450                }
451            };
452            let Some((seq, dump)) = got else {
453                if self.ax.as_ref().is_some_and(|a| a.is_closed()) && reconnects < 2 {
454                    reconnects += 1;
455                    self.reset();
456                    continue;
457                }
458                let (empty, unparsed) = match (self.ax.as_ref(), base) {
459                    (Some(a), Some((_, e0, u0))) => {
460                        (a.empty_count().saturating_sub(e0), a.unparsed_count().saturating_sub(u0))
461                    }
462                    _ => (0, 0),
463                };
464                let up = self.ax.as_ref().is_some_and(|a| !a.is_closed());
465                let stall = if up { ax_stall(empty, unparsed) } else { None };
466                // Empty answers are also what a locked phone might send; a
467                // daemon that is fine is not ended for that.
468                let locked = match stall {
469                    Some(AxStall::EmptyOnly) => match conn::route(&self.udid).await {
470                        Ok(r) => conn::passcode_locked(&*r.provider).await,
471                        Err(_) => None,
472                    },
473                    _ => None,
474                };
475                let lately = self.ax_restarted_at.is_some_and(|at| at.elapsed() < AX_RESTART_GAP);
476                let mut why_not = "";
477                if restarted {
478                    // The daemon the phone started in its place did not
479                    // answer either.
480                    self.ax_restart_unhelpful = true;
481                }
482                if stall.is_some() && locked != Some(true) {
483                    if restarted {
484                        why_not = "it was already ended once during this reading";
485                    } else if self.system_in_front {
486                        why_not = "the home screen or a system panel was in front";
487                    } else if self.ax_restart_unhelpful {
488                        why_not = "ending it last time did not help";
489                    } else if lately {
490                        why_not = "it was ended less than 2 minutes ago";
491                    } else if !self.config.daemon.restart_accessibility {
492                        why_not = "[daemon] restart_accessibility = false";
493                    }
494                }
495                if stall.is_some() && locked != Some(true) && why_not.is_empty() {
496                    restarted = true;
497                    let waited = started.elapsed().as_secs();
498                    let how = match stall {
499                        Some(AxStall::EmptyOnly) => format!("sent only empty answers ({empty})"),
500                        _ => "gave no answer".to_string(),
501                    };
502                    match self.restart_ax_daemon().await {
503                        Ok(pid) => {
504                            eprintln!(
505                                "[{}] the phone's accessibility daemon {how} for {waited} s; ended it (pid {pid}) so the phone starts a new one",
506                                crate::clock::now_utc()
507                            );
508                            self.ax_restarted_at = Some(Instant::now());
509                            self.ax_restarts += 1;
510                            self.ax = None;
511                            tokio::time::sleep(Duration::from_millis(500)).await;
512                            started = Instant::now();
513                            continue;
514                        }
515                        Err(e) => {
516                            eprintln!(
517                                "[{}] the phone's accessibility daemon {how} for {waited} s and could not be restarted: {e}",
518                                crate::clock::now_utc()
519                            );
520                            why_not = "ending it failed";
521                            self.ax_restart_unhelpful = true;
522                        }
523                    }
524                }
525                let fail = Fail::not_sent(
526                    "ax_timeout",
527                    format!(
528                        "no accessibility tree within {} ms ({empty} empty, {unparsed} not understood)",
529                        started.elapsed().as_millis(),
530                    ),
531                )
532                .with("phone_locked", locked.map(serde_json::Value::Bool).unwrap_or(serde_json::Value::Null));
533                return Err(if locked == Some(true) {
534                    fail.hint(t("폰이 잠겨 있습니다. 잠금을 풀어 주세요.", "The phone is locked. Unlock it."))
535                } else if stall.is_some() && self.system_in_front {
536                    fail.with("ax_restart_skipped", why_not).hint(t(
537                        "폰의 화면 읽기 서비스가 응답하지 않습니다. 홈 화면이나 제어 센터 같은 시스템 화면이 앞에 있습니다. 화면 기록 중에는 제어 센터가 읽히지 않습니다. `iph button home`으로 닫거나 `iph launch`로 앱을 띄운 뒤 다시 읽으세요. 이 두 명령은 화면을 못 읽어도 나갑니다.",
538                        "The phone's screen-reading service is not answering, and the home screen or a system panel such as Control Center is in front. Control Center cannot be read while the screen is being recorded. Close it with `iph button home` or bring an app up with `iph launch`, then read again; both go out without a reading.",
539                    ))
540                } else if stall.is_some() && self.ax_restart_unhelpful {
541                    fail.with("ax_restart_skipped", why_not).hint(t(
542                        "폰의 화면 읽기 서비스를 다시 띄워도 응답이 없습니다. 폰을 잠갔다가 다시 풀어 주세요.",
543                        "The phone's screen-reading service did not answer after a restart either. Lock the phone and unlock it again.",
544                    ))
545                } else if stall.is_some() {
546                    fail.with("ax_restart_skipped", why_not).hint(t(
547                        "폰의 화면 읽기 서비스(axauditd)가 응답하지 않습니다. 폰이 잠긴 것은 아닙니다. 잠시 뒤 다시 시도하세요. iph가 2분에 한 번까지 그 서비스를 다시 띄웁니다.",
548                        "The phone's screen-reading service (axauditd) is not answering. The phone is not locked. Try again shortly; iph restarts that service at most every 2 minutes.",
549                    ))
550                } else {
551                    fail.hint(t(
552                        "화면 읽기 응답을 이해하지 못했습니다. `iph read --raw`로 확인하세요.",
553                        "The screen-reading answers were not understood. Look with `iph read --raw`.",
554                    ))
555                });
556            };
557            if !full {
558                return Ok((seq, dump));
559            }
560            let ax = self.ax.as_mut().unwrap();
561            if let Some(merged) = ax.full(seq) {
562                return Ok((seq, merged));
563            }
564            match ax.wait_full(seq, SECOND_PASS_WAIT).await {
565                Some(merged) => return Ok((seq, merged)),
566                None => {
567                    // A newer reading replaced this one: take that instead.
568                    if ax.seq() > seq && started.elapsed() < READ_TIMEOUT {
569                        fresh = Fresh::MaxAge(Duration::from_secs(5));
570                        continue;
571                    }
572                    // The second pass sometimes stays away (seen right after
573                    // an input). Ask once more before going on without
574                    // identifiers.
575                    if second_pass_retries < 1 && started.elapsed() < READ_TIMEOUT {
576                        second_pass_retries += 1;
577                        fresh = Fresh::Force;
578                        continue;
579                    }
580                    return Ok((seq, dump));
581                }
582            }
583        }
584    }
585
586    pub async fn screen(&mut self, fresh: Fresh, full: bool, opts: BuildOptions) -> Res<(u64, Screen)> {
587        let mut fresh = fresh;
588        let mut last = None;
589        // A reading taken while an app is coming to the front can lack the
590        // application's frame; look again rather than hand out a screen
591        // without a size.
592        for _ in 0..3 {
593            let (seq, dump) = Box::pin(self.dump(fresh, full)).await?;
594            let screen = Screen::build(&dump, opts);
595            self.ax_restart_unhelpful = false;
596            self.system_in_front = crate::dnd::system_ui(&screen);
597            if screen.width > 0.0 && screen.height > 0.0 {
598                self.screen_size = Some((screen.width, screen.height));
599                return Ok((seq, screen));
600            }
601            last = Some((seq, screen));
602            fresh = Fresh::Force;
603        }
604        let (seq, mut screen) = last.unwrap();
605        if let Some((w, h)) = self.screen_size {
606            screen.width = w;
607            screen.height = h;
608        }
609        Ok((seq, screen))
610    }
611
612    /// Open the input session if needed. Fails with `not_sent`: nothing has
613    /// been written to the phone when this returns an error.
614    pub async fn ensure_input(&mut self) -> Res<&mut InputSession> {
615        // A media stream that stopped delivering packets no longer holds the
616        // phone's HID gate open.
617        self.refresh_connection();
618        let stale = self
619            .input
620            .as_ref()
621            .is_some_and(|i| i.media_idle_ms().is_none_or(|ms| ms > 2500));
622        if (stale || self.input_suspect)
623            && let Some(old) = self.input.take() {
624                old.close().await;
625                self.input_closed_at = Some(Instant::now());
626            }
627        self.input_suspect = false;
628        if self.input.is_none() {
629            self.sweep().await;
630            // Keep a new session a little apart from the one before it.
631            // (Lost first gestures turned out to be touches sent before the
632            // phone had opened the session's devices, which
633            // `InputSession::open` now waits for; the gap stays as a margin.
634            // `IPH_REOPEN_GAP_MS` overrides it.)
635            if let Some(closed) = self.input_closed_at {
636                let gap = std::env::var("IPH_REOPEN_GAP_MS")
637                    .ok()
638                    .and_then(|v| v.parse().ok())
639                    .map(Duration::from_millis)
640                    .unwrap_or(REOPEN_GAP);
641                let since = closed.elapsed();
642                if since < gap {
643                    tokio::time::sleep(gap - since).await;
644                }
645            }
646            let mut last = String::new();
647            for attempt in 0..2 {
648                let video = self.config.daemon.screen_video;
649                let tunnel = self.ensure_tunnel().await?;
650                let mut adapter = tunnel.adapter.clone();
651                match bounded("input session", 20, InputSession::open(&mut adapter, &mut tunnel.rsd, video)).await {
652                    Ok(s) => {
653                        self.input = Some(s);
654                        break;
655                    }
656                    Err(e) => {
657                        last = e;
658                        if attempt == 0 && is_transport_error(&last) {
659                            self.reset();
660                        } else {
661                            break;
662                        }
663                    }
664                }
665            }
666            if self.input.is_none() {
667                return Err(Fail::not_sent("input_unavailable", last).hint(t(
668                    "터치 입력에는 개발자 디스크 이미지의 display service가 필요합니다. `iph doctor`로 확인하세요.",
669                    "Touch input needs the display service from the developer disk image. Run `iph doctor`.",
670                )));
671            }
672        }
673        self.input_used = Instant::now();
674        Ok(self.input.as_mut().unwrap())
675    }
676
677    /// Send one gesture. The phone sometimes closes the input connections on
678    /// its own (it answers the next report with a reset, seen 2026-11-11);
679    /// iph only finds out when it writes. When that write fails before a
680    /// single report went out, nothing reached the phone, so a new session is
681    /// opened and the gesture is sent once more. A gesture that failed
682    /// halfway is never repeated.
683    pub async fn send_gesture(&mut self, gesture: Gesture) -> Res<()> {
684        for attempt in 0..2 {
685            let input = self.ensure_input().await?;
686            let before = input.reports_sent();
687            let sent = match &gesture {
688                Gesture::Tap { x, y, hold } => input.tap(*x, *y, *hold).await,
689                Gesture::DoubleTap { x, y } => input.double_tap(*x, *y).await,
690                Gesture::Drag { from, to, duration, motion } => input.drag(*from, *to, *duration, *motion).await,
691                Gesture::Button { page, usage, hold } => input.button(*page, *usage, *hold).await,
692                Gesture::Pinch(plan) => input.pinch(plan).await,
693            };
694            let Err(e) = sent else {
695                return Ok(());
696            };
697            let untouched = input.reports_sent() == before;
698            self.drop_input();
699            if attempt == 0 && untouched {
700                crate::device::ax::trace(|| format!("gesture not sent ({e:#}); trying once on a new session"));
701                eprintln!("[{}] input connection was closed ({e:#}); sending again on a new session", crate::clock::now_utc());
702                continue;
703            }
704            return Err(Fail::unknown("input_failed", format!("{e:#}")).hint(t(
705                "입력이 나갔을 수 있습니다. 다시 보내지 말고 `iph read`로 화면을 확인하세요.",
706                "The input may have gone out. Do not resend; check the screen with `iph read`.",
707            )));
708        }
709        unreachable!("the loop returns on its second pass")
710    }
711
712    /// Close the input session when it has not been used for a while; the
713    /// media stream keeps the phone encoding video.
714    pub async fn close_idle_input(&mut self) {
715        let idle = Duration::from_secs(self.config.daemon.input_idle_secs);
716        if self.input.is_some() && self.input_used.elapsed() > idle
717            && let Some(s) = self.input.take() {
718                s.close().await;
719                self.input_closed_at = Some(Instant::now());
720            }
721    }
722
723    /// End the input session now.
724    pub async fn close_input(&mut self) {
725        if let Some(s) = self.input.take() {
726            s.close().await;
727            self.input_closed_at = Some(Instant::now());
728        }
729    }
730
731    /// With `input_idle_secs = 0` the input session ends with each command,
732    /// so the phone shows "screen sharing" only while input is being sent.
733    /// For apps that hide their content or complain while the screen is
734    /// shared. Every input then pays for a new session (3 to 4 s).
735    pub async fn close_input_if_unheld(&mut self) {
736        if self.config.daemon.input_idle_secs == 0
737            && let Some(s) = self.input.take() {
738                s.close().await;
739                self.input_closed_at = Some(Instant::now());
740            }
741    }
742
743    pub async fn shutdown(&mut self) {
744        if let Some(s) = self.input.take() {
745            s.close().await;
746        }
747        self.sweep().await;
748        self.reset();
749    }
750
751    async fn rsd_client<T>(&mut self) -> Res<T>
752    where
753        T: RsdService,
754    {
755        let mut last = String::new();
756        for attempt in 0..2 {
757            let tunnel = self.ensure_tunnel().await?;
758            let mut adapter = tunnel.adapter.clone();
759            match bounded("connect", 12, T::connect_rsd(&mut adapter, &mut tunnel.rsd)).await {
760                Ok(c) => return Ok(c),
761                Err(e) => {
762                    last = e;
763                    if attempt == 0 && is_transport_error(&last) {
764                        self.reset();
765                    } else {
766                        break;
767                    }
768                }
769            }
770        }
771        Err(Fail::not_sent(
772            "service_unavailable",
773            format!("{}: {last}", T::rsd_service_name()),
774        ))
775    }
776
777    pub async fn app_service(&mut self) -> Res<AppServiceClient<Box<dyn ReadWrite>>> {
778        self.rsd_client().await
779    }
780
781    /// The phone's log stream, filtered to one process when `pid` is given,
782    /// and its reset. Dropped on any path, here or later, the stream resets
783    /// its connection rather than closing it, which would hold the relay for
784    /// the next capture.
785    pub async fn os_trace(&mut self, pid: Option<u32>) -> Res<(OsTraceRelayReceiver, Reset)> {
786        let name = OsTraceRelayClient::rsd_service_name();
787        let unavailable = |e: String| Fail::not_sent("service_unavailable", format!("{name}: {e}"));
788        // As `rsd_client`: a tunnel that died under the session is rebuilt once.
789        let mut attempt = 0;
790        let mut stream = loop {
791            let (mut adapter, port) = self.service_port(&name).await?;
792            match bounded("connect", 12, adapter.connect(port)).await {
793                Ok(stream) => break stream,
794                Err(e) if attempt == 0 && is_transport_error(&e) => {
795                    attempt += 1;
796                    self.reset();
797                }
798                Err(e) => return Err(unavailable(e)),
799            }
800        };
801        let reset = stream.reset_on_drop();
802        let started = match OsTraceRelayClient::from_stream(Box::new(stream)).await {
803            Ok(client) => bounded("start_trace", 12, client.start_trace(pid)).await,
804            Err(e) => Err(format!("{e:?}")),
805        };
806        started.map(|receiver| (receiver, reset)).map_err(unavailable)
807    }
808
809    pub async fn pasteboard(&mut self) -> Res<PasteboardServiceClient<Box<dyn ReadWrite>>> {
810        self.rsd_client().await
811    }
812
813    pub async fn list_apps(&mut self, refresh: bool) -> Res<Vec<AppListEntry>> {
814        if refresh || self.apps.is_none() {
815            // The plain `listapps` call gets no answer on iOS 27; the phone
816            // advertises a streaming list instead. Use whichever is on offer.
817            let streams = self.ensure_tunnel().await?.rsd.services.get(APP_SERVICE).is_some_and(|svc| {
818                svc.features
819                    .as_ref()
820                    .is_some_and(|f| f.iter().any(|x| x == "com.apple.coredevice.feature.streamapplist"))
821            });
822            let mut svc = self.app_service().await?;
823            let apps: Vec<AppListEntry> = if streams {
824                use futures_util::TryStreamExt;
825                bounded(
826                    "stream app list",
827                    30,
828                    svc.stream_apps(true, true, false, false, true).try_collect(),
829                )
830                .await
831            } else {
832                bounded("list apps", 30, svc.list_apps(true, true, false, false, true)).await
833            }
834            .map_err(|e| Fail::not_sent("apps_failed", e))?;
835            self.apps = Some(apps);
836        }
837        Ok(self.apps.clone().unwrap_or_default())
838    }
839
840    pub async fn screenshot_png(&mut self) -> Res<Vec<u8>> {
841        let mut svc: ScreenCaptureServiceClient<Box<dyn ReadWrite>> = self.rsd_client().await?;
842        bounded("screenshot", 20, svc.take_screenshot(None, ImageFormat::Png))
843            .await
844            .map_err(|e| Fail::not_sent("screenshot_failed", e))
845    }
846}
847
848#[cfg(test)]
849mod tests {
850    use super::{AxStall, ax_stall, plain_path};
851
852    #[test]
853    fn paths_compare_across_spellings() {
854        assert_eq!(
855            plain_path("file:///private/var/containers/Bundle/Application/AB/My%20App.app/"),
856            "/var/containers/Bundle/Application/AB/My App.app"
857        );
858        assert_eq!(plain_path("/Applications/Preferences.app"), "/Applications/Preferences.app");
859        assert_eq!(plain_path("file:///Applications/%EB%A9%94%EB%AA%A8.app/x"), "/Applications/메모.app/x");
860    }
861
862    #[test]
863    fn a_daemon_that_sends_only_empty_answers_is_restarted_too() {
864        // Before: only a silent daemon was ended (`empty == 0 && unparsed == 0`),
865        // and one that sent three empty answers a reading stayed stuck.
866        assert_eq!(ax_stall(0, 0), Some(AxStall::Silent));
867        assert_eq!(ax_stall(3, 0), Some(AxStall::EmptyOnly));
868        // Answers the parser could not read are not the daemon's fault.
869        assert_eq!(ax_stall(0, 1), None);
870        assert_eq!(ax_stall(2, 1), None);
871    }
872}