Repository navigation
Description
Part of #1645.
Scope
An operator sets ios.modes on a worker, and from then on the worker refuses at once, with MODE_UNAVAILABLE, every iOS lease whose mode it does not serve. Its warm pool boots no device of that mode, doctor reports a warm target that cannot be met, and simlock catalog shows the served modes. A gateway does not route by them yet.
If this goes wrong, a user on a slim-only worker still gets a full simulator, or a lease of a served mode is refused.
Technical spec
Commit 1cd9315.
Rows
Behaviours: B1, B2, B3, B4, B5
Stored state: S1
Interfaces: I1, I2, I3, I4, I5, I8
Existing code: X1, X2, X3, X4, X5, X6, X7, X8, X9, X10, X15 (the worker pages), X16, X18
Facts
| # | Fact | Source |
|---|---|---|
| F1 | Today config set ios.modes is refused as an unknown key, exit 2 |
node dist/cli/main.js config set ios.modes '["slim"]' on main, with a scratch HOME, printed {"error":{"code":"USAGE","message":"Invalid config after setting ios.modes: Unknown config key: \"ios.modes\""}} and exited 2 |
| F2 | config set checks a value by loading the whole config, so a cross-key check in loadConfig refuses it too |
src/cli/commands/config.ts:56-60, src/core/config.ts:202-215 |
| F3 | A list config value is passed as JSON on the command line | website/src/content/docs/docs/gateway/routing.mdx:51 (config set gateway.admission.command '["bun",…]') |
| F4 | stringArray is the existing list validator |
src/core/validation.ts:160 |
| F5 | The defaults are merged before the checks run, so "ios.defaultMode unset" is read from the file and the overrides, not from the merged config |
src/core/config.ts:180-193 |
Modules touched
src/core/ (config-types.ts, config-defaults.ts, config-validators.ts, config.ts, create-core.ts, domain.ts (TargetRefusal), src/core/doctor.ts:543 (passes the served modes to unreachableTarget), doctor-findings.ts, doctor-types.ts, warm-pool/policy.ts, warm-pool/catalog-check.ts, warm-pool/converger.ts, AGENTS.md, warm-pool/AGENTS.md), src/leasing/ (acquisition-spec-resolver.ts, acquisition-errors.ts, create-leasing.ts:57, :160, acquisition-ports.ts:66, the test helpers src/leasing/testing.ts:57 and test-create-leasing.ts:130, AGENTS.md), src/daemon/ (error-code.ts, lease-request-refusal.ts, worker-composition.ts, dispatcher-status.ts, the test helper src/daemon/test-dispatcher.ts:194), src/contract/ (errors.ts, config-schemas.ts, status-schemas.ts, report-schemas.ts, protocol.ts), src/http/lease-declarations.ts, src/cli/commands/catalog.ts, the hand-built CoreConfig and DoctorConfig slices that a new ios field breaks (found by the typecheck), docs/internal/flows/device-selection.md, and the website pages reference/configuration.mdx, reference/errors.mdx, using-devices/errors.mdx, using-devices/choosing-a-device.mdx, worker/capacity.mdx, worker/configuration.mdx, worker/troubleshooting.mdx (the doctor finding). Searches: defaultMode, defaultModes, checkedSpec, baselineSpec, refusalOf, TargetRefusal, warmPoolShortSchema, unreachableTarget, DoctorConfig, CatalogCheck, #withDefaults, ERROR_TABLE.
flowchart LR
cfg[core config: ios.modes] --> res[leasing resolver]
cfg --> wp[core warm-pool catalog check]
cfg --> doc[core doctor]
res --> err[daemon error code and details]
cfg --> cat[daemon catalog.get]
cat --> cli[cli catalog]
Rules in play
- ADR 0082 §1–3: the key, the check on the asked and resolved modes, the new code.
- ADR 0007 §2: the default is still resolved once, in the resolver; §5 stays true (a full request never gets a slim device).
- ADR 0065: the key is core's, beside
defaultMode, so no driver definition file changes. src/contract/AGENTS.md(Protocol version, Adding an operation step 7): I2 and I3 bumpmaxby one in this PR, together;minstays, since an older peer strips the field and relays the code.src/core/AGENTS.md: "A part takes the config sections it reads" (CoreConfigandDoctorConfiggain onlyios).- Documentation rule 9: the website pages above change in this PR.
Tests
Seam: the worker dispatcher with fake drivers (model: src/daemon/dispatcher-leases-device-mode.test.ts), core with leasing and the warm pool over fake drivers, through the real resolver, for B3 and B4 (model: src/leasing/create-leasing-warm-targets.test.ts; B4 then reads doctor's findings over those figures, as src/core/doctor-warm-pool-targets.test.ts does), config (model: src/core/config-platform-and-driver-settings.test.ts) and the CLI (model: src/cli/index-catalog-components.test.ts).
- B1:
ios.modesloads andconfig setwrites it: every row of the config Examples table; unset (both, defaultfull);["full"]with the default unset; a gateway's config holding it (warned and ignored) - B2: an iOS lease whose resolved mode is not served is refused with I2 and its details: no mode,
slim,full, slim below 18.5, no mode below 18.5, full baseline, slim baseline,noWait,--physical, Android,--mode full --allow-downloadof a missing version (installComponentnever called), slim--allow-downloadbelow 18.5 (installed, then refused);["full"]with--mode slim; unset with--mode full(granted) - B3: the warm pool without full: full target (short
mode-unavailable, nothing booted); mode-less target on iOS 17.5 (short); slim target on 26.1 (filled); learned full kind (forgotten); learned kind of a full baseline (forgotten);["full"]with a learned slim kind (forgotten); a full idle device from before (not intargeted()) - B4: doctor with a target the worker cannot meet: full target with
["slim"]; slim target with["full"]; both with the key unset (no finding) - B5: the catalog of a one-mode worker:
["slim"];["full"]; unset (no field,Modes served: slim, full);--json; Android entry (no field, no line)
Done when
pnpm test:changedpasses, with every Tests line above as a test.pnpm checkpasses, the protocol-bump check included:maxis one above the valuemainholds when this lands.- The website build passes:
pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjs. reference/errors.mdxlistsMODE_UNAVAILABLEunder exit 12 and in the code table, andreference/configuration.mdxhas theios.modesrow.
Out of scope
- Gateway routing by mode, the gateway's refusal and its merged catalog: T2.
- Deleting idle full simulators at start (a non-goal of Restrict iOS lease modes on a worker #1645).
Depends on
- A worker serves only enrolled devices on a platform whose virtualDevices is false #1598
- A held remote simlock lease and simlock mcp reconnect and keep their lease through a network drop #1642
Written by an agent.
Activity