Skip to content

Commit 27170c4

Browse files
andrewfreeclaudethymikee
authored
fix(ios): prepare snapshot helpers within a shared readiness budget (#4181)
* fix(ios): prepare snapshot helpers within a shared readiness budget * fix(ios): await cleanup for every source close caller * test(ios): separate lifecycle fixtures from assertions * fix(ios): retry failed helper startup for later captures * test(ios): pin shared source readiness deadline * fix(ios): deliver late bridge startup failures once per generation * refactor(ios): retain failures at the readiness attempt boundary * test(ios): preserve fixture edge cases and verify readiness child * test(ios): pin single delivery and close waiting for startup Cover a helper crash observed inside the starting capture's wait: the next same-generation capture starts a fresh helper instead of receiving the failure again. Require close to stay pending while adopted startup is paused instead of checking one microtask. Co-Authored-By: Claude Opus 5.5 <[email protected]> * docs(ios): move helper startup notes beside the native bridge Co-Authored-By: Claude Opus 5.5 <[email protected]> * test(ios): give fixture identity cases a capture budget and distinct exit codes The fixture identity cases still create real directories and sockets, so a 100 ms deadline could fail them before identity validation on a loaded runner. The readiness fixture now reports fork and waitpid failures with their own exit codes instead of reusing the behavioral failure code. Co-Authored-By: Claude Opus 5.5 <[email protected]> * chore: adapt to main after rebase Add SnapshotBridgeRequest.m to the readiness fixture build, classify the two new bridge startup refusal codes, and expect main's typed refusal ahead of identity validation. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> --------- Co-authored-by: f <sgf> Co-authored-by: Claude Opus 5.5 <[email protected]> Co-authored-by: Michał Pierzchała <[email protected]>
1 parent 83945b7 commit 27170c4

15 files changed

Lines changed: 1509 additions & 683 deletions

‎apple/snapshot-bridge/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,14 @@ Objective-C shim for those operations, adding another native boundary. Keeping
4141
the guest in Objective-C also allows direct lazy compilation with `clang`
4242
without an Xcode project or Swift module for private headers.
4343

44+
## Startup
45+
46+
The helper initializes its framework runtime before it binds its listener, so a
47+
connectable socket means the runtime is ready. Readiness does not create a
48+
target root or change automation settings, and it does not prove that an app's
49+
accessibility server can answer a capture. The host bounds startup and shares
50+
one readiness allowance between binary preparation and helper startup.
51+
4452
## Foreground ownership
4553

4654
The reader checks AXRuntime's primary foreground application before and after

‎apple/snapshot-bridge/SnapshotBridge.m‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,11 @@ static int serve(NSString *socketPath, int idleTimeoutSeconds, BOOL exitOnDiscon
9393
return 1;
9494
}
9595

96+
NSString *setupError = nil;
97+
if (!sharedRuntime(&setupError)) {
98+
bridgeLog([NSString stringWithFormat:@"runtime initialization failed: %@", setupError]);
99+
return 1;
100+
}
96101
int listener = socket(AF_UNIX, SOCK_STREAM, 0);
97102
if (listener < 0) {
98103
bridgeLog([NSString stringWithFormat:@"socket failed: %s", strerror(errno)]);

‎contracts/fixtures/ios-snapshot-bridge-refusals.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@
2525
"code": "bridge-preparation-pending",
2626
"consequence": "bridge-preparation"
2727
},
28+
{
29+
"code": "bridge-readiness-pending",
30+
"consequence": "bridge-preparation"
31+
},
2832
{
2933
"code": "snapshot-tree-changed",
3034
"consequence": "tree-changed"
@@ -60,6 +64,7 @@
6064
"bridge-process-pid-missing",
6165
"bridge-read-abandoned",
6266
"bridge-request-deadline",
67+
"bridge-startup-deadline",
6368
"child-invalid",
6469
"children-invalid",
6570
"continuation-budget-exhausted",
Lines changed: 316 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,316 @@
1+
import { EventEmitter } from 'node:events';
2+
import { writeFile } from 'node:fs/promises';
3+
import { createLiveTestHostEnvironment } from '@agent-device/test-kit';
4+
import { simulatorAddressFor } from '../core/simctl.ts';
5+
import { createSnapshotSourceHost } from './host.ts';
6+
import { MAXIMUM_REQUEST_LEVELS } from './limits.ts';
7+
import {
8+
encodeSnapshotBridgeFrame,
9+
SNAPSHOT_SOURCE_PROTOCOL_VERSION,
10+
SNAPSHOT_SOURCE_VERSION,
11+
} from './protocol.ts';
12+
import type { SnapshotSourceHost, SnapshotSourceProcess, SnapshotSourceSocket } from './types.ts';
13+
14+
export type AdapterFixture = {
15+
host: SnapshotSourceHost;
16+
builds: number;
17+
runs: number;
18+
responsePid: number;
19+
requestedDepths: number[];
20+
requestedHints: (number | undefined)[];
21+
/** Native levels above which the fake guest reports a rejection-then-recovery. */
22+
rejectLevelsAbove: number | undefined;
23+
/** Whether the fake guest reports a depth- or node-bounded tree. */
24+
truncated: boolean;
25+
/** Whether the fake guest answers with sound counters but an unusable tree. */
26+
malformedTree: boolean;
27+
/** Whether the fake guest's tree ends at another process's content (a remote element leaf). */
28+
remoteContent: boolean;
29+
/** Whether the fake guest's tree holds a window reporting the app box quarter-turned (#2612). */
30+
turnedWindow: boolean;
31+
/** Whether the fake guest's root omits its frame, leaving the capture without a viewport. */
32+
omitViewport: boolean;
33+
/** Whether the fake guest finds a requested system surface host process running. */
34+
runningSurfaceHost: boolean;
35+
/** The surface host check each request carried: its executables and Simulator, or undefined. */
36+
surfaceHostChecks: Array<Readonly<{ executables: unknown; simulatorUdid: unknown }> | undefined>;
37+
/** The windows the fake guest reports under its root when no other tree shape is selected. */
38+
windows: readonly Record<string, unknown>[];
39+
omitRecovery: boolean;
40+
diagnostics: Record<string, unknown>[];
41+
startedTargets: Array<Parameters<SnapshotSourceHost['start']>[0]>;
42+
};
43+
44+
export function targetForTest(simulatorSetPath?: string) {
45+
return {
46+
simulator: simulatorAddressFor({
47+
platform: 'apple',
48+
id: 'simulator-1',
49+
name: 'iPhone 17',
50+
kind: 'simulator',
51+
target: 'mobile',
52+
...(simulatorSetPath ? { simulatorSetPath } : {}),
53+
}),
54+
runtime: 'iOS 26.2',
55+
pid: 321,
56+
};
57+
}
58+
59+
export function createAdapterHost(buildDelayMs = 0): AdapterFixture {
60+
const realHost = createSnapshotSourceHost(createLiveTestHostEnvironment());
61+
const fixture: AdapterFixture = {
62+
host: undefined as never,
63+
builds: 0,
64+
runs: 0,
65+
responsePid: 321,
66+
requestedDepths: [],
67+
requestedHints: [],
68+
rejectLevelsAbove: undefined,
69+
truncated: false,
70+
malformedTree: false,
71+
remoteContent: false,
72+
turnedWindow: false,
73+
omitViewport: false,
74+
runningSurfaceHost: false,
75+
surfaceHostChecks: [],
76+
windows: [],
77+
omitRecovery: false,
78+
diagnostics: [],
79+
startedTargets: [],
80+
};
81+
const host: SnapshotSourceHost = {
82+
...realHost,
83+
cpuArch: async () => 'arm64',
84+
emitDiagnostic: (event) => {
85+
if (event.phase === 'ios_snapshot_source_recovery')
86+
fixture.diagnostics.push(event.data ?? {});
87+
},
88+
run: async (command, args) => {
89+
fixture.runs += 1;
90+
if (command === 'xcrun' && args.includes('clang')) {
91+
fixture.builds += 1;
92+
if (buildDelayMs > 0) await new Promise((resolve) => setTimeout(resolve, buildDelayMs));
93+
await writeFile(args.at(-1)!, 'bridge-binary');
94+
return { stdout: '', stderr: '', exitCode: 0 };
95+
}
96+
return {
97+
stdout:
98+
command === 'xcodebuild'
99+
? 'Xcode 16.4\nBuild version 16F6'
100+
: command === 'sw_vers'
101+
? '15.6'
102+
: '26.2',
103+
stderr: '',
104+
exitCode: 0,
105+
};
106+
},
107+
start: (target) => {
108+
fixture.startedTargets.push(target);
109+
return new AdapterProcess();
110+
},
111+
connect: async () => new AdapterSocket(fixture),
112+
readTargetProcessStartTime: async () => 'target-start',
113+
};
114+
fixture.host = host;
115+
return fixture;
116+
}
117+
118+
class AdapterProcess implements SnapshotSourceProcess {
119+
readonly pid = 801;
120+
readonly wait: Promise<{ stdout: string; stderr: string; exitCode: number }>;
121+
private resolveWait!: (result: { stdout: string; stderr: string; exitCode: number }) => void;
122+
private alive = true;
123+
124+
constructor() {
125+
this.wait = new Promise((resolve) => {
126+
this.resolveWait = resolve;
127+
});
128+
}
129+
130+
isAlive(): boolean {
131+
return this.alive;
132+
}
133+
134+
signal(): void {
135+
this.alive = false;
136+
this.resolveWait({ stdout: '', stderr: '', exitCode: 0 });
137+
}
138+
139+
readLog(): string {
140+
return '';
141+
}
142+
}
143+
144+
class AdapterSocket extends EventEmitter implements SnapshotSourceSocket {
145+
destroyed = false;
146+
private readonly fixture: AdapterFixture;
147+
148+
constructor(fixture: AdapterFixture) {
149+
super();
150+
this.fixture = fixture;
151+
}
152+
153+
/** The guest root's frame, or undefined when the fixture reports a viewportless tree. */
154+
private rootFrame(): Record<string, number> | undefined {
155+
return this.fixture.omitViewport ? undefined : { X: 0, Y: 0, Width: 390, Height: 844 };
156+
}
157+
158+
write(frame: Buffer): boolean {
159+
const bodyLength = frame.readUInt32BE(0);
160+
const request = JSON.parse(frame.subarray(4, bodyLength + 4).toString('utf8')) as {
161+
requestId: string;
162+
pid: number;
163+
generation: string;
164+
maxDepth: number;
165+
nativeLevelsHint?: number;
166+
surfaceHostExecutables?: string[];
167+
simulatorUdid?: string;
168+
};
169+
this.fixture.surfaceHostChecks.push(
170+
request.surfaceHostExecutables
171+
? { executables: request.surfaceHostExecutables, simulatorUdid: request.simulatorUdid }
172+
: undefined,
173+
);
174+
if (this.fixture.runningSurfaceHost && request.surfaceHostExecutables) {
175+
queueMicrotask(() =>
176+
this.emit(
177+
'data',
178+
encodeSnapshotBridgeFrame(
179+
{
180+
protocolVersion: SNAPSHOT_SOURCE_PROTOCOL_VERSION,
181+
sourceVersion: SNAPSHOT_SOURCE_VERSION,
182+
requestId: request.requestId,
183+
ok: false,
184+
pid: this.fixture.responsePid,
185+
generation: request.generation,
186+
error_kind: 'unsupported',
187+
error_code: 'system-surface-host-present',
188+
surfaceHostExecutable: request.surfaceHostExecutables![0],
189+
},
190+
{ maxRequestBytes: 64 * 1024 },
191+
),
192+
),
193+
);
194+
return true;
195+
}
196+
this.fixture.requestedDepths.push(request.maxDepth);
197+
this.fixture.requestedHints.push(request.nativeLevelsHint);
198+
// The guest's own recovery: one request reads at most 65 levels, and a rejected depth halves
199+
// at most twice, like SnapshotBridgeCapture.
200+
const requestedLevels = Math.min(
201+
request.maxDepth + 1,
202+
request.nativeLevelsHint ?? MAXIMUM_REQUEST_LEVELS,
203+
);
204+
const rejectAbove = this.fixture.rejectLevelsAbove;
205+
let acceptedLevels = requestedLevels;
206+
let rejected = 0;
207+
while (rejectAbove !== undefined && acceptedLevels > rejectAbove && rejected < 3) {
208+
rejected += 1;
209+
acceptedLevels = Math.max(1, Math.floor(acceptedLevels / 2));
210+
}
211+
const rejectedEverywhere = rejectAbove !== undefined && acceptedLevels > rejectAbove;
212+
queueMicrotask(() => {
213+
if (this.destroyed) return;
214+
if (rejectedEverywhere) {
215+
this.emit(
216+
'data',
217+
encodeSnapshotBridgeFrame(
218+
{
219+
protocolVersion: SNAPSHOT_SOURCE_PROTOCOL_VERSION,
220+
sourceVersion: SNAPSHOT_SOURCE_VERSION,
221+
requestId: request.requestId,
222+
ok: false,
223+
pid: this.fixture.responsePid,
224+
generation: request.generation,
225+
error_kind: 'application_unavailable',
226+
error_code: 'application-server-unavailable',
227+
},
228+
{ maxRequestBytes: 64 * 1024 },
229+
),
230+
);
231+
return;
232+
}
233+
this.emit(
234+
'data',
235+
encodeSnapshotBridgeFrame(
236+
{
237+
protocolVersion: SNAPSHOT_SOURCE_PROTOCOL_VERSION,
238+
sourceVersion: SNAPSHOT_SOURCE_VERSION,
239+
requestId: request.requestId,
240+
ok: true,
241+
pid: this.fixture.responsePid,
242+
generation: request.generation,
243+
truncated: request.maxDepth === 1 || this.fixture.truncated,
244+
automationEnabled: true,
245+
...(this.fixture.omitRecovery
246+
? {}
247+
: {
248+
recovery: {
249+
requests: 1 + rejected,
250+
rejected,
251+
continuations: 0,
252+
acceptedLevels,
253+
},
254+
}),
255+
tree: this.fixture.malformedTree
256+
? null
257+
: {
258+
XC_kAXXCAttributeElementType: 'Application',
259+
XC_kAXXCAttributeFrame: this.rootFrame(),
260+
XC_kAXXCAttributeChildren:
261+
request.maxDepth === 1
262+
? [{ XC_kAXXCAttributeElementType: 'Button', XC_kAXXCAttributeChildren: [] }]
263+
: this.fixture.remoteContent
264+
? [
265+
{
266+
XC_kAXXCAttributeElementType: 'WebView',
267+
XC_kAXXCAttributeFrame: { X: 0, Y: 0, Width: 390, Height: 844 },
268+
XC_kAXXCAttributeChildren: [
269+
{
270+
XC_kAXXCAttributeElementType: 'AXRemoteElement',
271+
XC_kAXXCAttributeElementBaseType: 'NSObject',
272+
XC_kAXXCAttributeFrame: { X: 0, Y: 0, Width: 390, Height: 844 },
273+
XC_kAXXCAttributeChildren: [],
274+
},
275+
],
276+
},
277+
]
278+
: this.fixture.turnedWindow
279+
? [
280+
{
281+
XC_kAXXCAttributeElementType: 'Application',
282+
XC_kAXXCAttributeElementBaseType: 'UIRemoteKeyboardWindow',
283+
XC_kAXXCAttributeFrame: { X: 0, Y: 0, Width: 844, Height: 390 },
284+
XC_kAXXCAttributeChildren: [
285+
{
286+
XC_kAXXCAttributeAutomationType: 20,
287+
XC_kAXXCAttributeLabel: 'q',
288+
XC_kAXXCAttributeFrame: {
289+
X: 154,
290+
Y: 77,
291+
Width: 45,
292+
Height: 72,
293+
},
294+
XC_kAXXCAttributeChildren: [],
295+
},
296+
],
297+
},
298+
]
299+
: this.fixture.windows,
300+
},
301+
},
302+
{
303+
maxRequestBytes: 64 * 1024,
304+
},
305+
),
306+
);
307+
});
308+
return true;
309+
}
310+
311+
destroy(): void {
312+
if (this.destroyed) return;
313+
this.destroyed = true;
314+
queueMicrotask(() => this.emit('close'));
315+
}
316+
}

0 commit comments

Comments
 (0)