Repository navigation
Description
Part of #1588.
Scope
An operator sets android.virtualDevices or ios.virtualDevices to false and restarts the worker. From then on the worker serves only enrolled physical devices on that platform:
- a lease without
--physical(orphysical: true) is refused at once withUNKNOWN_MODELand a message naming the key and how to ask for a physical device; - the warm pool boots nothing on that platform;
- idle simulators or emulators of that platform are deleted at start;
simlock catalogandcatalog.getsay virtual devices are off;simlock doctornames the key for a warm target it can no longer meet.
Phone leases, the other platform and components work as today.
A user would notice: an emulator still booting on a phones-only worker, a --physical lease refused or stuck, an idle device of the other platform deleted, or a worker that fails to start after the change.
Technical spec
Commit 5e639b4.
Rows
Behaviours: B1, B2, B3, B4, B5, B6, B7, B10
Stored state: S1
Interfaces: I1, I2, I4, I5, I6, I7, I8, I9
Existing code: X1, X2, X3, X4, X5, X6, X7, X8, X9, X10, X14, X15, X16, X17 (the worker pages), X18
Facts
| # | Fact | Source |
|---|---|---|
| F1 | Today config set refuses an unknown key and a non-boolean with exit 2 and these texts |
node dist/cli/main.js config set android.virtualDevices false on main printed Invalid config after setting android.virtualDevices: Unknown config key: "android.virtualDevices"; config set devices.autoEnroll no printed Invalid config value for "devices.autoEnroll": expected a boolean |
| F2 | ManagedDeviceLifecycle.shutdown and destroy take the initiator from the caller, and destroy claims only provisioning, shutdown or quarantined devices, so a ready one is shut down first |
src/core/managed-device-lifecycle.ts:168, :190-201 |
| F3 | A top-level ios or android key in a gateway's config is warned about and ignored, since neither is in the gateway's key list |
src/core/config-role-checks.ts:64-72, :95-96 |
| F4 | Leasing's resolver reads the catalog through core.drivers (the DriverCatalog) |
src/leasing/create-leasing.ts:153, src/leasing/acquisition-ports.ts:62 |
Modules touched
src/core/ (config-types.ts, config-defaults.ts, config-validators.ts, core-ports.ts (CatalogReader), driver-catalog.ts, create-core.ts, startup-converger.ts, doctor.ts, doctor-findings.ts, doctor-types.ts, warm-pool/policy.ts, warm-pool/converger.ts (passes the key into the policy view, :662-667), AGENTS.md, warm-pool/AGENTS.md), src/leasing/ (acquisition-spec-resolver.ts, acquisition-errors.ts, acquisition-ports.ts, AGENTS.md), src/contract/ (status-schemas.ts, protocol.ts), src/cli/commands/catalog.ts, the hand-built config slices that CoreConfig and DoctorConfig gaining ios and android breaks (src/leasing/test-create-leasing.ts:50, test-physical-device-watcher.ts:45, test-lease-end-participants.ts:106, src/core/test-doctor.ts:118, src/core/nuke.test.ts:305, src/core/reaper.test.ts:60, src/leasing/physical-leasing.test.ts:43), docs/internal/EVENTS.md, docs/internal/flows/device-selection.md, docs/internal/flows/startup.md (B5's step, :63-72), and the website pages reference/configuration.mdx, using-devices/physical-devices.mdx, using-devices/errors.mdx, reference/errors.mdx, reference/events.mdx, worker/troubleshooting.mdx (the doctor finding), worker/capacity.mdx (unknown-model at :222, and the off platform's reserve). Searches: listCatalog\(, resolveSpec\(, UnknownModelError, platformCatalogSchema, StartupConverger, unreachableTarget, DoctorConfig, defaultModels in src/core/config-*.
flowchart LR
cfg[core config: virtualDevices] --> dc[core DriverCatalog]
dc --> res[leasing resolver]
dc --> st[core startup converger]
dc --> cat[contract catalog entry]
cat --> cli[cli catalog]
cfg --> doc[core doctor]
Rules in play
- ADR 0084 §1–3: core keys, refused in the one resolve step, empty catalog entry with the field.
- ADR 0065: the key is core's, so no driver definition file changes.
- ADR 0022: a
--physicalrequest skips resolution and stays as it is (X4). src/contract/AGENTS.md(Protocol version): I5 bumpsmaxby one in this PR;minstays, since an older peer strips the field.src/core/AGENTS.md: "Warm pool and startup never install"; "Destroy only what the registry holds" (B5 deletes registry devices only, throughManagedDeviceLifecycle).- Documentation rule 9: the website pages above change in this PR.
Tests
Seam: the worker dispatcher with fake drivers (model: src/daemon/dispatcher-leases.test.ts, src/daemon/dispatcher-components.test.ts), StartupConverger (model: src/core/startup-converger.test.ts), the warm-pool converger (model: src/core/warm-pool/converger-targets-passes.test.ts), doctor (model: src/core/doctor-warm-pool-targets.test.ts), config (model: src/core/config-platform-and-driver-settings.test.ts) and the CLI (model: src/cli/index-catalog-components.test.ts).
- B1:
<platform>.virtualDevicesloads andconfig setwrites it:androidfalse;iosfalse; unset (true);no(refused,expected a boolean);0(refused); a gateway's config holding it (warned and ignored) - B2: a plain lease on a phones-only platform is admitted, then refused with I2: no model; named model; OS range; image tag;
allowDownload; baseline;noWait; iOS slim withexcept; the other platform still granted; the fake driver'sresolveSpec,listCatalogandinstallComponentnever called - B3: a
--physicallease on a phones-only platform: free phone (granted); every match leased (waits); same withnoWait(NO_CAPACITY); no enrolled match (UNKNOWN_MODEL, today's message) - B4: the warm pool on a phones-only platform: configured target (short
unknown-model, no boot); learned kind from before (forgotten);reserveRunning.android: 2(counts as 0: an iOS target on a tight global budget fills, and doctor's room leaves it out); iOS target (filled) - B5: startup on a phones-only platform:
readyidle (shutdown then deleted, initiatorvirtual-devices-off);shutdownidle (deleted); leased (kept, deleted at release,lease-end); claimed (left); enrolled phone; iOS idle device (kept); a saved baseline (still listed);destroythrows (I6,shutdown);shutdownthrows (I6,ready) - B6: the catalog of a phones-only worker:
--platform android; no platform (both entries, iOS full);--json; the driver'slistCatalognever called for Android - B7: components on a phones-only platform: install an Android image; list; remove
- B10: doctor with a warm target on a phones-only platform: Android target, key
false(I8); same target, keytrue, unknown model (today's text); iOS target with Android off (today's findings)
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 (after Android leases that name no image tag get the worker's android.defaultImageTag where it fits #1595 and A worker's catalog names its default image tag, and a gateway ranks and shows it #1596).- The website build passes:
pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjs. docs/internal/EVENTS.mdandreference/events.mdxlistvirtual-devices-offas an initiator ofdevice.shutdownanddevice.deleted.
Out of scope
- The gateway's refusal and merged catalog: Through a gateway, a plain lease that only phones-only workers could serve gets the phones-only refusal #1599.
- Starting Android with only
adbinstalled.
Depends on
- Android leases that name no image tag get the worker's android.defaultImageTag where it fits #1595
- A worker's catalog names its default image tag, and a gateway ranks and shows it #1596
Written by an agent.
Activity
test: a --physical lease on a phones-only platform is granted, waits …
test: <platform>.virtualDevices loads, config set writes it, and a no…
feat(config): android.virtualDevices and ios.virtualDevices are boole…
test: the catalog of a phones-only worker has empty lists and virtual…
feat(catalog): a phones-only platform's entry has empty lists and vir…
test: simlock catalog prints the phones-only line (#1598)
feat(cli): simlock catalog says virtual devices are off for a phones-…
test: component install, list and remove work on a phones-only platfo…
test: startup on a phones-only platform deletes its idle devices and …
feat(core): startup deletes the idle devices of a platform whose virt…
2 remaining items
feat(warm-pool): a platform with virtual devices off holds no reserve (…
test: doctor names <platform>.virtualDevices for a warm target it can…
feat(doctor): a warm target on a phones-only platform is reported wit…
docs: the phones-only platform in the manuals, flows, errors and trou…
docs: cite ADR 0080 for the phones-only platform after the renumber (#…
refactor(warm-pool): one expression keeps a platform's reserve or zer…
fix(test): virtualDevices-off test leases the other platform; correct…
docs: trim manuals to the total budget (#1598)
chore(docs): merge the feature's ADR branch, keeping both startup ste…
docs(leasing): the manual drops a rule the device-selection flow alre…
feat(contract): the protocol range moves one for the catalog's virtua…
docs: the phones-only ADR is cited as 0084 (#1598)
refactor(cli): the catalog's phones-only line is its own function (#1598
feat(leasing): a worker serves only enrolled devices on a platform wh…