import {
DeviceBootError,
type DeviceHostId,
DeviceOperationError,
type DevicePlatform,
} from "@t3tools/contracts";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Schema from "effect/Schema";
import { HttpClient, HttpClientError, HttpClientRequest, HttpClientResponse } from "effect/http";
import type { DeviceHostReady, DeviceOperations, HostDevice } from "./DeviceHost.ts";
const BOOT_TIMEOUT = Duration.minutes(3);
const SCREENSHOT_TIMEOUT = Duration.seconds(20);
// Let the hub's 30 s simctl timeout report its cause first.
const LIST_TIMEOUT_SECONDS = 40;
// expo-device-hub 0.19.1 reports a failed simulator listing only as text; its error ids are hashes.
const SIMULATOR_LIST_FAILED =
/^\[apple-utils\] (?:Failed to (?:run `xcrun simctl list devices|parse JSON output:|list devices:)|`xcrun simctl list devices --json` did not respond within )/;
const HubDevice = Schema.Struct({
id: Schema.String,
name: Schema.String,
version: Schema.String,
platform: Schema.Literals(["ios", "android"]),
booted: Schema.Boolean,
physical: Schema.Boolean,
});
const HubDeviceList = Schema.Struct({
simulators: Schema.Array(HubDevice),
emulators: Schema.Array(HubDevice),
errors: Schema.optional(
Schema.Array(Schema.Struct({ message: Schema.String, error: Schema.optional(Schema.String) })),
),
});
const HubActionResult = Schema.Struct({
ok: Schema.Boolean,
id: Schema.optional(Schema.String),
serial: Schema.optional(Schema.String),
error: Schema.optional(Schema.String),
errors: Schema.optional(
Schema.Array(Schema.Struct({ message: Schema.String, error: Schema.optional(Schema.String) })),
),
});
// Hub diagnostics can carry a whole stderr dump.
const boundDiagnostics = (text: string) =>
text.length > 2_000 ? `${text.slice(0, 1_999)}…` : text;
// The hub's `error` is a util.inspect of Node's exec error; the stack and the
// inspected fields follow the first frame, so keep the lines before it.
const errorHead = (error: string) => {
const lines = error.split(/\r?\n/);
const firstFrame = lines.findIndex((line) => /^\s+at /.test(line));
return (firstFrame === -1 ? lines : lines.slice(0, firstFrame))
.map((line) => line.trim())
.filter(Boolean)
.join(" ");
};
const vendorPrefix = (platform: DevicePlatform) =>
platform === "ios" ? "/vendor/serve-sim" : "/vendor/serve-emu";
/** Device operations for a host that runs expo-device-hub at `origin`. */
export const makeDeviceHubOperations = (options: {
readonly hostId: DeviceHostId;
readonly origin: string;
readonly http: HttpClient.HttpClient;
readonly run: DeviceHostReady["run"];
/** Android gates listing AVDs, which the hub does not report until they boot. */
readonly platformAvailable: (platform: DevicePlatform) => Effect.Effect<boolean>;
}): DeviceOperations => {
const { hostId, origin, run } = options;
const httpClient = options.http.pipe(HttpClient.withScope);
const fetchJson = Effect.fn("DeviceHubOperations.fetchJson")(function* <A, I>(
request: HttpClientRequest.HttpClientRequest,
schema: Schema.Codec<A, I>,
) {
return yield* httpClient
.execute(request)
.pipe(
Effect.flatMap(HttpClientResponse.filterStatusOk),
Effect.flatMap(HttpClientResponse.schemaBodyJson(schema)),
Effect.scoped,
);
});
const hubJson = <A, I>(
request: HttpClientRequest.HttpClientRequest,
schema: Schema.Codec<A, I>,
operation: string,
timeout: Duration.Input = Duration.seconds(15),
) =>
fetchJson(request, schema).pipe(
Effect.timeout(timeout),
Effect.mapError(
(cause) => new DeviceOperationError({ operation, reason: "request_failed", cause }),
),
);
const postJson = (path: string, body: Record<string, string>, operation: string) =>
HttpClientRequest.post(`${origin}${path}`).pipe(
HttpClientRequest.bodyJson(body),
Effect.mapError(
(cause) => new DeviceOperationError({ operation, reason: "invalid_payload", cause }),
),
);
// Booting alone does not attach a serve-sim helper; the grid start does both
// and is idempotent for a booted simulator.
const attachIosStream = (udid: string, operation: string) =>
postJson(`${vendorPrefix("ios")}/grid/api/start`, { udid }, operation).pipe(
Effect.flatMap((request) => hubJson(request, HubActionResult, "attach stream", BOOT_TIMEOUT)),
);
const list: DeviceOperations["list"] = Effect.gen(function* () {
const listed = yield* fetchJson(
HttpClientRequest.get(`${origin}/api/devices`),
HubDeviceList,
).pipe(
Effect.mapError(
(cause) => new DeviceOperationError({ operation: "list", reason: "request_failed", cause }),
),
Effect.timeoutOption(Duration.seconds(LIST_TIMEOUT_SECONDS)),
);
if (Option.isNone(listed)) {
return {
devices: [],
detail: `The device hub did not answer within ${LIST_TIMEOUT_SECONDS} seconds.`,
incompletePlatforms: yield* Effect.filter(["ios", "android"] as const, (platform) =>
options.platformAvailable(platform),
),
};
}
const hubList = listed.value;
const devices: Array<HostDevice> = [...hubList.simulators, ...hubList.emulators];
const androidAvailable = yield* options.platformAvailable("android");
const warnings = hubList.errors?.filter(
(error) =>
// The host summary already explains a missing Android SDK; the hub's failed probes are noise.
!(!androidAvailable && error.message.startsWith("[android-utils] ")) &&
// CoreSimulator can retain deleted devices; their optional usage timestamps are absent.
!(
error.message.startsWith("[apple-utils] Failed to read CoreSimulator plist at ") &&
/\/CoreSimulator\/Devices\/[^/]+\/device\.plist:$/.test(error.message) &&
/(?:^Error:\s*ENOENT:|\bcode:\s*['"]ENOENT['"])/.test(error.error ?? "")
),
);
const details =
warnings?.map((error) => {
const head = errorHead(error.error ?? "");
return boundDiagnostics(head ? `${error.message} ${head}` : error.message);
}) ?? [];
let androidDiscoveryIncomplete = false;
if (androidAvailable) {
const avds = yield* run("emulator", ["-list-avds"]);
// Discovered devices stay listed; the AVDs that could not be listed are a warning.
if (avds.code !== 0) {
androidDiscoveryIncomplete = true;
details.push(
`Could not list Android virtual devices (emulator -list-avds, exit code ${avds.code}). Discovered devices remain available.`,
);
}
for (const name of (avds.code === 0 ? avds.stdout : "")
.split(/\r?\n/)
.map((line) => line.trim())
.filter(Boolean)) {
if (!devices.some((device) => device.platform === "android" && device.name === name)) {
devices.push({
id: name,
name,
platform: "android",
version: "Android",
booted: false,
physical: false,
});
}
}
}
const simulatorsUnlisted =
hubList.simulators.length === 0 &&
(hubList.errors ?? []).some((error) => SIMULATOR_LIST_FAILED.test(error.message));
return {
devices,
detail: details.join("\n") || undefined,
androidDiscoveryIncomplete,
...(simulatorsUnlisted ? { incompletePlatforms: ["ios"] as const } : {}),
};
}).pipe(Effect.withSpan("DeviceHubOperations.list"));
const boot: DeviceOperations["boot"] = Effect.fn("DeviceHubOperations.boot")(function* (device) {
const result = yield* postJson(
"/api/devices/boot",
{ platform: device.platform, id: device.id, name: device.name },
"boot",
).pipe(Effect.flatMap((request) => hubJson(request, HubActionResult, "boot", BOOT_TIMEOUT)));
if (!result.ok) {
// Keep the hub's launch command and nested failure available to agents for recovery.
const diagnostics = [
result.error,
...(result.errors ?? []).flatMap((error) => [error.message, error.error]),
]
.filter((text) => text?.trim())
.join("\n\n");
return yield* new DeviceBootError({
hostId,
deviceId: device.id,
reason: /insufficient.*(?:disk|space)|not enough.*(?:disk|space)|no space left/i.test(
diagnostics,
)
? "disk_space"
: /timed? out|timeout/i.test(diagnostics)
? "timeout"
: "launch_failed",
...(diagnostics ? { diagnostics: boundDiagnostics(diagnostics) } : {}),
cause: result,
});
}
if (device.platform === "ios") yield* attachIosStream(device.id, "boot");
return result.serial ?? result.id ?? device.id;
});
const attach: DeviceOperations["attach"] = (device) =>
device.platform === "ios"
? attachIosStream(device.id, "open").pipe(Effect.asVoid)
: Effect.void;
const shutdown: DeviceOperations["shutdown"] = Effect.fn("DeviceHubOperations.shutdown")(
function* (device) {
const postShutdown = (path: string, body: Record<string, string>) =>
postJson(path, body, "shutdown").pipe(
Effect.flatMap((request) => hubJson(request, HubActionResult, "shutdown")),
Effect.flatMap((result) =>
result.ok
? Effect.void
: Effect.fail(
new DeviceOperationError({
operation: "shutdown",
reason: "hub_rejected",
cause: result,
}),
),
),
);
// serve-sim's shutdown closes its in-process capture session before it
// runs `simctl shutdown`; the hub's generic shutdown can leave that
// session cached across a reboot. serve-sim runs simctl bare, though, so
// a simulator that is already off fails there.
yield* device.platform === "ios"
? postShutdown(`${vendorPrefix("ios")}/grid/api/shutdown`, { udid: device.id }).pipe(
Effect.catch((cause) =>
list.pipe(
Effect.flatMap(({ devices }) =>
devices.find((candidate) => candidate.id === device.id)?.booted === false
? Effect.logInfo("iOS simulator was already shut down", { deviceId: device.id })
: Effect.fail(cause),
),
),
),
)
: postShutdown("/api/devices/shutdown", { platform: device.platform, id: device.id });
},
);
const screenshot: DeviceOperations["screenshot"] = (device) =>
httpClient
.execute(
HttpClientRequest.post(
`${origin}${vendorPrefix(device.platform)}/api/screenshot?device=${encodeURIComponent(device.id)}`,
),
)
.pipe(
Effect.flatMap(HttpClientResponse.filterStatusOk),
Effect.flatMap((response) => response.arrayBuffer),
Effect.map((buffer) => new Uint8Array(buffer)),
Effect.scoped,
Effect.timeout(SCREENSHOT_TIMEOUT),
Effect.mapError(
(cause) =>
new DeviceOperationError({
operation: "screenshot",
reason:
HttpClientError.isHttpClientError(cause) && cause.reason._tag === "StatusCodeError"
? "hub_rejected"
: "request_failed",
cause,
}),
),
Effect.withSpan("DeviceHubOperations.screenshot"),
);
return { list, boot, attach, shutdown, screenshot };
};