Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/internal/EVENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ Simlock registry (ADR 0002, `docs/internal/adr/0002-opt-in-slim-ios-simulators.m
only") is satisfied by waiting for that commit to become observable, not by waiting on a registry
write: the driver writes the launchd overrides file while the simulator is shut down, boots it once, and only fires
`onSlimmed` once the readback shows the overrides in force. The registry's own `device.ready` for that same boot is a separate,
later event, emitted through the normal readiness path once the driver call returns. A boot with a lease's except list (ADR 0066) reports `categories` as the smaller list (the worker's slim set minus the excepted categories), `signature` as that list's signature and `labelCount` as the labels written `true`, so a kept label that a slimmed category also lists is not counted; a boot whose smaller list is empty is granted `full` and emits none. A slim
later event, emitted through the normal readiness path once the driver call returns. A boot with a lease's except list (ADR 0066) reports `categories` as the smaller list (the worker's slim set minus the excepted categories), `signature` as that list's signature and `labelCount` as the labels written `true`, so a kept label that a slimmed category also lists is not counted and a worker's `ios.slim.exclude` name is (ADR 0083); a boot that writes no label `true` is granted `full` and emits none. A slim
request on a runtime older than iOS 18.5 is resolved to a full spec before planning (ADR 0007
§4), so it never reaches a slim boot. A *skipped* slim on a slim-spec device -- its runtime id
didn't parse, the overrides file could not be written, or the readback disagreed or failed -- is deliberately not an event: it isn't a fact worth putting in front of every event-bus
Expand Down
11 changes: 11 additions & 0 deletions e2e/helpers/ios-device-set.ts
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,17 @@ export async function sweepStaleDeviceSets(): Promise<void> {
}
}

// why: a simulator's daemons run from the runtime's own root, not from the device set, so a service
// is found by its binary's name under a `RuntimeRoot`.
export async function runtimeRootProcesses(binary: string): Promise<string[]> {
const { stdout } = await execFileAsync("ps", ["-axo", "command="], {
maxBuffer: 16 * 1024 * 1024,
});
return stdout
.split("\n")
.filter((line) => line.includes("RuntimeRoot") && line.includes(`/usr/libexec/${binary}`));
}

/**
* Host processes whose command line names a path inside `deviceSet`. A booted simulator runs a
* `launchd_sim` (and its children) out of its device directory, so a non-empty result means a
Expand Down
37 changes: 37 additions & 0 deletions e2e/slow-ios-slim.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import type { TestEnv } from "./helpers/env.js";
import {
iosDeviceSet,
processesInDeviceSet,
runtimeRootProcesses,
setDevices,
simctlInSet,
sweepStaleDeviceSets,
Expand Down Expand Up @@ -442,6 +443,42 @@ describe.skipIf(process.platform !== "darwin")(
},
);

it(
"a worker's exclude turns off a service no category holds, and its include keeps a category's service running",
{ timeout: 1_800_000 },
async () => {
const diagnosticd = "com.apple.diagnosticd";
const apsd = "com.apple.apsd";
const excluding = await withRealDaemon({
ios: { defaultMode: "slim", slim: { categories: [], exclude: [diagnosticd] } },
});
const { model, os } = await catalogModelWithOs(excluding, (versions) =>
versions.find((version) => Number(version.split(".")[0]) >= 26),
);
const excluded = await leaseDetached(excluding, model, os, "slim-exclude");
await expectSlim(excluding, excluded.mode, "a worker with only an exclude must grant slim");
expect((await printDisabled(excluded)).has(diagnosticd)).toBe(true);
expect(
await runtimeRootProcesses("diagnosticd"),
"no diagnosticd runs while the excluding worker's device is booted",
).toEqual([]);
await excluding.cli(["nuke", "--delete-devices", "--yes"], { timeout: 180_000 });

const including = await withRealDaemon({
ios: { defaultMode: "slim", slim: { include: [apsd] } },
});
const included = await leaseDetached(including, model, os, "slim-include");
await expectSlim(including, included.mode, "a worker with only an include must grant slim");
const disabled = await printDisabled(included);
expect(disabled.has(apsd), "apsd is kept running by include").toBe(false);
expect(
[...ALL_LABELS].filter((label) => label !== apsd && !disabled.has(label)),
"every other category label is disabled",
).toEqual([]);
await including.cli(["nuke", "--delete-devices", "--yes"], { timeout: 180_000 });
},
);

it(
"no simulator from this file's device sets is still running after its flows",
{ timeout: 60_000 },
Expand Down
17 changes: 16 additions & 1 deletion src/core/config-role-checks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,13 @@ import {
isCapacityStrategyName,
type CapacityStrategyName,
} from "./capacity/index.js";
import type { Config, DownloadPolicy, Layer, ModuleConfigEntry } from "./config-types.js";
import type {
Config,
DownloadPolicy,
DriverConfigEntry,
Layer,
ModuleConfigEntry,
} from "./config-types.js";
import { MIN_EVENT_LOG_MAX_BYTES } from "./config-defaults.js";
import { asObject, mergeConfig, omit, pick } from "./config-helpers.js";
import { invalidValue, requireObject, type Warn } from "./validation.js";
Expand Down Expand Up @@ -136,6 +142,15 @@ export function runModuleChecks(config: Config, modules: readonly ModuleConfigEn
}
}

export function runDriverChecks(
config: Config,
driverSections: readonly DriverConfigEntry[],
): void {
for (const entry of driverSections) {
entry.check?.(config[entry.platform] as never, config);
}
}

function warnWorkerOnlySubKeys(
layer: Record<string, unknown>,
section: string,
Expand Down
2 changes: 2 additions & 0 deletions src/core/config-types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -272,6 +272,8 @@ export interface DriverConfigEntry<Section = unknown> {
simlockHome: string,
settings: Readonly<Record<string, string | number | boolean>>,
) => Readonly<Record<string, string | number | boolean>>;
// why: ADR 0083 I4: runs on the merged config, after both layers, where a rule that spans keys of one section can be judged; it throws a `ConfigError`.
readonly check?: (section: never, config: Config) => void;
}

export interface ModuleConfigEntry {
Expand Down
2 changes: 2 additions & 0 deletions src/core/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import {
normalizeLayer,
requireGatewayHttp,
resolveStrategyName,
runDriverChecks,
runModuleChecks,
validateDeletedRetention,
validateEventLogBounds,
Expand Down Expand Up @@ -204,6 +205,7 @@ export function configFromLayers(
validateMetricsRetention(merged);
// why: a gateway reads a module's gateway keys, so a bad value stops it too.
runModuleChecks(merged, modules);
runDriverChecks(merged, driverSections);
if (role === "gateway") {
warnWorkerOnlyKeys([fromFile, fromOverrides], warn, modules);
requireGatewayHttp(merged);
Expand Down
2 changes: 2 additions & 0 deletions src/drivers/ios/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ Resolve and boot:
- `RuntimeMissingError` is only for what a download can fix: an OS outside the device type's range, an installed runtime not paired with the type, and anything below iOS 16 are refused instead.
- A boot is `simctl boot`, `bootstatus -b`, then `listapps` until it succeeds, on one deadline: bootstatus can finish before the installer accepts requests.
- Slim (ADR 0060), on `prepare` of a slim spec only: the managed labels are merged into the simulator's `disabled.plist` before the boot (other entries kept; a failed write is logged and the boot goes on), and `launchctl print-disabled system` is read back after it. A label not as written returns `full`; a readback that fails returns `slim`; both call `onSlimSkipped`, logged only. Every label as written and the write ok: `slim`, and `onSlimmed` becomes `device.slimmed`.
- Named services (ADR 0083, `ios.slim.include` and `ios.slim.exclude`): every name in either list, in the record and in a category is a managed label, written in this order, last wins: `false`; `true` for a configured category's label (never-disable labels excepted) and for an `exclude` name; `false` for an `include` name and for a lease's `--except` category. `exclude` beats the never-disable list. A device is `slim` only when some label is written `true`, so `categories: []` with an `exclude` is slim and an `include` covering the slim set is `full`. An `include` or `exclude` label not read back as written grants `full`, never a throw. The record `simlock-managed.json` beside `disabled.plist` lists the names last written: a recorded name in neither list is written `false`, then the record is rewritten (an empty list with no file is not written). It is copied with the plist and removed with its folder; one that cannot be read as a list of strings is empty and logged. A failed record write is a failed overrides write.
- Slim `except` (ADR 0066, `slim-except.ts`): an excepted category's labels are written `false`; an unknown name is `BAD_REQUEST`; a kept label not read back throws `KeptCategoriesError`.
- A recovery boot writes no slim overrides and reads nothing back. DeviceHub clipboard isolation is configured before preparation and recovery boots; ready default-set simulators reboot under the lease claim before a grant. Active leases at upgrade keep clipboard sync until a later boot or lease end.
- The overrides folder lives outside the device set (`launchdOverridesRoot`), so `destroy` removes it itself after `simctl delete`.
Expand Down Expand Up @@ -52,6 +53,7 @@ Tunnels (`device-tcp.ts`):
- **A restart between `simctl clone` and the durable mark under `default` (#968)** leaves one unlisted `simlock-<id>` simulator in Xcode's set. Delete it with `simctl delete`.
- **Runtime downloads outlive deletion (#79).** Reclaim them in Xcode → Settings → Platforms.
- **Slim costs (#87, #172).** Below iOS 18.5 a slim request gets `full`. Slim devices lose push, Spotlight, StoreKit, universal links, Siri, iCloud sync; use `--mode full` for them.
- **A misspelt `include` or `exclude` name is silent**, and a baseline saved before ADR 0083 has no record: a name later dropped from `exclude` stays off in its copies until it is put in `include`.
- **The overrides file is undocumented.** If Apple ignores it, the readback grants `full`.
- **A recovered slim device runs full but is recorded `slim` (#174)** until its next `makeReady`.
- **A cold slim lease takes a full cold boot.** MCP clients need a longer timeout.
Expand Down
45 changes: 44 additions & 1 deletion src/drivers/ios/definition.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import { iosDriverConfig } from "./definition.js";

const configPath = "/home/agent/.simlock/config.json";

async function load(file: unknown) {
async function load(file: unknown, overrides?: unknown) {
const filesystem = new MemoryFilesystem();
const warn = vi.fn();
await filesystem.mkdirp("/home/agent/.simlock");
Expand All @@ -17,6 +17,7 @@ async function load(file: unknown) {
filesystem,
systemStats: new FakeSystemStats({ cpuCount: 8, totalRamBytes: 32 * 1024 ** 3 }),
warn,
...(overrides === undefined ? {} : { overrides: overrides as never }),
});
return { section: driverConfig(config, iosDriverConfig), warn };
}
Expand Down Expand Up @@ -77,3 +78,45 @@ describe("the iOS driver's keys of the ios config section", () => {
expect(section.simulator).toEqual({ audio: true, createTimeoutMs: 30_000, headless: true });
});
});

describe("the iOS driver's ios.slim.include and ios.slim.exclude", () => {
const bothLists = (names: string) =>
`Invalid config value for "ios.slim": expected no service in both include and exclude (${names})`;

it("load as lists of service names, and fail the load for a name in both lists or a value that is no list of names", async () => {
const both = await load({
ios: { slim: { include: ["com.apple.apsd"], exclude: ["com.apple.diagnosticd"] } },
});
expect(both.section.slim).toEqual({
bootTimeoutMs: 600_000,
exclude: ["com.apple.diagnosticd"],
include: ["com.apple.apsd"],
});
expect(both.warn).not.toHaveBeenCalled();
expect((await load({ ios: { slim: { include: [] } } })).section.slim.include).toEqual([]);
expect((await load({ ios: { slim: { exclude: ["a", "a"] } } })).section.slim.exclude).toEqual([
"a",
"a",
]);

const refused = [
[{ ios: { slim: { include: ["x", "y"], exclude: ["y", "x", "z"] } } }, bothLists("x, y")],
[
{ ios: { slim: { include: ["x"] } } },
bothLists("x"),
{ ios: { slim: { exclude: ["x"] } } },
],
[
{ ios: { slim: { exclude: "com.apple.diagnosticd" } } },
'Invalid config value for "ios.slim.exclude": expected an array of strings',
],
[
{ ios: { slim: { exclude: [""] } } },
'Invalid config value for "ios.slim.exclude": expected an array of strings',
],
] as const;
for (const [file, message, overrides] of refused) {
await expect(load(file, overrides), message).rejects.toThrow(message);
}
});
});
20 changes: 19 additions & 1 deletion src/drivers/ios/definition.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { join } from "node:path";

import {
booleanValue,
invalidValue,
type DriverConfigEntry,
objectValidator,
positiveNumber,
Expand All @@ -12,6 +13,10 @@ export interface IosDriverConfig {
readonly slim: {
/** why: undefined disables every category the driver knows. */
readonly categories?: readonly string[];
/** why: services a slim device keeps running whatever the categories turn off (ADR 0083 §2). */
readonly include?: readonly string[];
/** why: services a slim device turns off beside the categories (ADR 0083 §2). */
readonly exclude?: readonly string[];
/** why: a slim device gets its own boot deadline, because CI runners are slow. */
readonly bootTimeoutMs: number;
};
Expand Down Expand Up @@ -45,8 +50,21 @@ export const iosDriverConfig: DriverConfigEntry<IosDriverConfig> = {
full: { bootTimeoutMs: 300_000 },
simulator: { audio: true, createTimeoutMs: 30_000, headless: true },
},
// why: ADR 0083 §1: the two lists are checked on the merged config, because the file and the overrides are validated one layer at a time.
check: (section: IosDriverConfig) => {
const { exclude = [], include = [] } = section.slim;
const both = [...new Set(include.filter((name) => exclude.includes(name)))].sort();
if (both.length > 0) {
throw invalidValue("ios.slim", `no service in both include and exclude (${both.join(", ")})`);
}
},
validators: {
slim: objectValidator({ categories: stringArray, bootTimeoutMs: positiveNumber }),
slim: objectValidator({
categories: stringArray,
bootTimeoutMs: positiveNumber,
include: stringArray,
exclude: stringArray,
}),
full: objectValidator({ bootTimeoutMs: positiveNumber }),
simulator: objectValidator({
audio: booleanValue,
Expand Down
6 changes: 5 additions & 1 deletion src/drivers/ios/index-save-source-lifecycle.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import {
plantManagedDevice,
overridesFolder,
overridesPath,
recordPath,
overridesPlist,
FaultyFilesystem,
instanceId,
Expand Down Expand Up @@ -183,7 +184,7 @@ describe("IosSimctlDriver", () => {

it.each([
{
name: "copies the seed's disabled.plist to the new simulator",
name: "copies the seed's disabled.plist and its record of named services to the new simulator",
seedHas: true,
failing: undefined,
},
Expand All @@ -199,6 +200,7 @@ describe("IosSimctlDriver", () => {
if (seedHas) {
await filesystem.mkdirp(overridesFolder(seedUdid));
await filesystem.writeFileAtomic(overridesPath(seedUdid), overridesPlist({ "a.b": true }));
await filesystem.writeFileAtomic(recordPath(seedUdid), '["a.b"]');
}
await plantLaunchServices(filesystem, `${deviceRoot}/${driverData.udid}`);
filesystem.failing = failing;
Expand Down Expand Up @@ -233,7 +235,9 @@ describe("IosSimctlDriver", () => {
).toEqual(["com.apple.LaunchServices.unregisteredtypes-501.db"]);
const copied = failing === undefined && seedHas;
expect(await filesystem.exists(overridesPath(driverData.udid))).toBe(copied);
expect(await filesystem.exists(recordPath(driverData.udid))).toBe(copied);
if (copied) {
expect(await filesystem.readFile(recordPath(driverData.udid))).toBe('["a.b"]');
expect(await filesystem.readFile(overridesPath(driverData.udid))).toBe(
overridesPlist({ "a.b": true }),
);
Expand Down
Loading
Loading