diff --git a/docs/internal/EVENTS.md b/docs/internal/EVENTS.md index f783d44b6..af73a7c4b 100644 --- a/docs/internal/EVENTS.md +++ b/docs/internal/EVENTS.md @@ -84,8 +84,8 @@ worker is ever contacted. `lease-id-taken` (ADR 0020; widens a published vocabul | `device.quarantine-recovered` | device id, attempts, reclaim strategy (erase/snapshot/wipe/uninstall), `missingApps` for a physical device (additive), the device's `platform` (`ios` or `android`) | a quarantined device's retried purge succeeded; it returned to `ready`/`shutdown` and rejoined the warm pool. Never emitted for a spent `fresh` device (`mayBeGranted` false): its retry is a delete, and a successful one emits `device.deleted` with initiator `lease-end` (`lease-engine` for a device that never served a lease) | QuarantineCoordinator | implemented | | `device.quarantine-abandoned` | device id, attempts, the device's `platform` (`ios` or `android`) | a quarantined device exhausted its configured retry budget (`warmPool.quarantine.maxRetries`) — purge retries, or delete retries for a spent `fresh` device — and was destroyed, or, for a physical device, unenrolled: Simlock never destroys one (safety rule 2, ADR 0022 §4) | QuarantineCoordinator | implemented | | `device.quarantine-stranded` | device id, attempts, stable error summary, the device's `platform` (`ios` or `android`) | a quarantined device exhausted its retry budget (purge or delete retries) and the destroy that should have retired it also failed; it stays `quarantined` with no further retry until an operator intervenes | QuarantineCoordinator | implemented | -| `device.shutdown` | device id, initiator (rule/command; `daemon-stop` when a stopping daemon shut down an idle device, #1056; `warm-pool` when the warm pool shut an idle device down, over the running limit, with `warmPool.enabled: false`, to keep `warmPool.reserveRunning` running slots free, or because a ready device that never served a lease and that no `warmPool.targets` entry and no kind the pool learned from a lease keeps has been idle past `idle.shutdownAfterMs`, or to displace it: an idle device shut down so a newer learned kind, or a configured target, can boot into its slot; `lease-engine` when a ready warm device failed the reboot a lease with `except` asked of it, ADR 0066 §2) | device stopped, still on disk | Registry; ReclaimCoordinator for interrupted reclaim recovery | implemented | -| `device.deleted` | device id, initiator (`lease-end` when a `fresh` device's lease ended and its delete completed — from ReclaimCoordinator, at startup convergence, or retried from quarantine; #75. `doctor` when `doctor --fix` marked a missing device, or startup's lease reconciler found a leased device absent from a platform it could read and ended the lease in the same write, ADR 0019 §2. `operator` when `device remove` unenrolled a physical device, ADR 0022 §2. `quarantine` when a physical device's quarantine retries ran out and it was unenrolled, ADR 0022 §4; `lease-engine` when a device that failed to boot for a lease was destroyed in cleanup, or when quarantine's delete retry removed a device that never served a lease; `cleanup-reaper` when the cleanup reaper destroyed a device; `nuke` when `nuke` destroyed it; `baseline-save` when `baseline save` kept a copy of the device and deleted it; `baseline-remove` when `baseline remove` deleted an idle device made from the baseline; `baseline-replaced` when a newer baseline version replaced the one an idle device was made from and the device was deleted), physical (the record's own flag: `true` for an enrolled physical device, `false` for a simulator or emulator; additive, events rule 6) | device removed from the registry, and from disk for a virtual device; a physical device is only forgotten and nothing is sent to it | Registry | implemented | +| `device.shutdown` | device id, initiator (rule/command; `daemon-stop` when a stopping daemon shut down an idle device, #1056; `warm-pool` when the warm pool shut an idle device down, over the running limit, with `warmPool.enabled: false`, to keep `warmPool.reserveRunning` running slots free, or because a ready device that never served a lease and that no `warmPool.targets` entry and no kind the pool learned from a lease keeps has been idle past `idle.shutdownAfterMs`, or to displace it: an idle device shut down so a newer learned kind, or a configured target, can boot into its slot; `lease-engine` when a ready warm device failed the reboot a lease with `except` asked of it, ADR 0066 §2; `virtual-devices-off` when startup shut down an idle device of a platform whose `.virtualDevices` is false, ADR 0084 §2) | device stopped, still on disk | Registry; ReclaimCoordinator for interrupted reclaim recovery | implemented | +| `device.deleted` | device id, initiator (`lease-end` when a `fresh` device's lease ended and its delete completed — from ReclaimCoordinator, at startup convergence, or retried from quarantine; #75. `doctor` when `doctor --fix` marked a missing device, or startup's lease reconciler found a leased device absent from a platform it could read and ended the lease in the same write, ADR 0019 §2. `operator` when `device remove` unenrolled a physical device, ADR 0022 §2. `quarantine` when a physical device's quarantine retries ran out and it was unenrolled, ADR 0022 §4; `lease-engine` when a device that failed to boot for a lease was destroyed in cleanup, or when quarantine's delete retry removed a device that never served a lease; `cleanup-reaper` when the cleanup reaper destroyed a device; `nuke` when `nuke` destroyed it; `baseline-save` when `baseline save` kept a copy of the device and deleted it; `baseline-remove` when `baseline remove` deleted an idle device made from the baseline; `baseline-replaced` when a newer baseline version replaced the one an idle device was made from and the device was deleted; `virtual-devices-off` when startup deleted an idle device of a platform whose `.virtualDevices` is false, ADR 0084 §2), physical (the record's own flag: `true` for an enrolled physical device, `false` for a simulator or emulator; additive, events rule 6) | device removed from the registry, and from disk for a virtual device; a physical device is only forgotten and nothing is sent to it | Registry | implemented | | `device.enrolled` | device id, platform, driver device id (the canonical ID), model, OS version, class (phone/tablet), app count, reenrolled, initiator (`operator` or `auto`) | an admin's `device add`, or the worker's auto-enroller under `devices.autoEnroll` (ADR 0073), wrote a physical device `ready` (ADR 0022 §2). `reenrolled` is `true` when the device already had a `ready`, `quarantined` or `absent` record, which kept its registry ID and took a fresh read of model, OS version, class and apps | Registry | implemented | | `device.absence-detected` | device id, previous state (ready/leased/reclaiming), absent reason (locked/untrusted/not-present) | an enrolled physical device became `absent` (ADR 0022 §2, §7, §8): the `PhysicalDeviceWatcher` read it not present `health.stableObservations` times in a row (a leased device's lease ends first, `lease.released` device-lost, in the same write), or `ReclaimCoordinator` found it not present after a failed reclaim (`reclaiming → absent`, no `device.purge-failed`, no `device.quarantined`). Emitted after the commit | Registry (the watcher's writes, the reclaim's failure path) | implemented | | `device.returned` | device id, OS version | the watcher read an `absent` physical device present, and the return reclaim it started committed `absent → reclaiming` with the OS version the read reports (ADR 0022 §7). Emitted after that commit; the reclaim then emits `device.reclaimed` | Registry (written by `ReclaimCoordinator`'s return reclaim) | implemented | diff --git a/docs/internal/flows/device-selection.md b/docs/internal/flows/device-selection.md index ab3d46270..2739b0db6 100644 --- a/docs/internal/flows/device-selection.md +++ b/docs/internal/flows/device-selection.md @@ -31,7 +31,7 @@ Never read: the sdkmanager catalog. A preference list is merged in `daemon/worke ## Virtual: request → spec -In `AcquisitionSpecResolver` (`leasing/acquisition-spec-resolver.ts`), a part of `LeaseAcquisitionCoordinator`, no lock held: +In `AcquisitionSpecResolver` (`leasing/acquisition-spec-resolver.ts`), a part of `LeaseAcquisitionCoordinator`, no lock held. A `virtualDevices: false` platform is refused first (`VirtualDevicesOffError`), before any catalog read or download: 1. `physical: true` → skip to the physical branch. A virtual Android request with no `imageTag` on a worker with `android.defaultImageTag` is tried first as if it named that tag, with downloads off and `defaultTag` set so only host-CPU images count; a `RuntimeMissingError` runs steps 2 to 9 again on the request as it came (ADR 0078). diff --git a/docs/internal/flows/startup.md b/docs/internal/flows/startup.md index e71155fbf..fc104ee74 100644 --- a/docs/internal/flows/startup.md +++ b/docs/internal/flows/startup.md @@ -68,8 +68,10 @@ Before step 16, a driver with `deviceTcp` sweeps the reverse rules into 47000-47 `device.shutdown` (initiator `startup-interrupted-reclaim`). 3. Spent deletes: `shutdown` devices that may not be granted again are deleted inline. A failed delete is logged; the device stays `shutdown`. - 4. Baselines `checkStale` (a failure is logged), so a baseline the driver calls stale is known before the first lease. - 5. Warm pool and capacity observer start. The pool closes the lease rows of its learned-kind + 4. Idle devices of a `virtualDevices: false` platform: a `ready` one is shut down, then each + is deleted (initiator `virtual-devices-off`). Claimed and leased ones are skipped. + 5. Baselines `checkStale` (a failure is logged), so a baseline the driver calls stale is known before the first lease. + 6. Warm pool and capacity observer start. The pool closes the lease rows of its learned-kind record whose lease the registry no longer holds, and its first pass boots the recorded kinds. 22. `queue.changed` with the first depth. Converge done → health `running`. diff --git a/src/cli/commands/catalog.ts b/src/cli/commands/catalog.ts index fcb89c4fb..024b49519 100644 --- a/src/cli/commands/catalog.ts +++ b/src/cli/commands/catalog.ts @@ -34,6 +34,13 @@ async function run( } } +function phonesOnlyLine(entry: CatalogGetOutput["platforms"][number]): string[] { + if (entry.virtualDevices !== false) return []; + return [ + ` Virtual devices: off (${entry.platform}.virtualDevices is false); only enrolled physical devices are leased`, + ]; +} + function formatCatalog(response: CatalogGetOutput): string { if (response.platforms.length === 0) return "No platforms available."; return response.platforms @@ -69,6 +76,7 @@ function formatCatalog(response: CatalogGetOutput): string { ); return [ `Platform: ${entry.platform}`, + ...phonesOnlyLine(entry), ` Runtimes: ${entry.runtimes.length > 0 ? esc(entry.runtimes.join(", ")) : "(none)"} (default: ${esc(defaultRuntime)})`, ...(entry.defaultImageTag === undefined ? [] diff --git a/src/cli/index-catalog-components.test.ts b/src/cli/index-catalog-components.test.ts index a33c9b374..bb7f9f6f9 100644 --- a/src/cli/index-catalog-components.test.ts +++ b/src/cli/index-catalog-components.test.ts @@ -60,6 +60,39 @@ describe("CLI: catalog", () => { ); }); + it("prints the phones-only line right after the platform line, and --json carries virtualDevices false", async () => { + const entry = { + classDefaults: {}, + modelAliases: {}, + modelClasses: {}, + modelRuntimes: {}, + models: [], + platform: "android" as const, + runtimes: [], + virtualDevices: false as const, + }; + const run = async (arguments_: string[]) => { + const output = outputCapture(); + const environment = output.environmentWith({ + connectAdmin: async () => + fakeClient({ getCatalog: () => Promise.resolve({ platforms: [entry] }) }), + }); + await expect(runCli(arguments_, environment)).resolves.toBe(0); + return output.stdout; + }; + + expect(await run(["catalog", "--platform", "android"])).toBe( + [ + "Platform: android", + " Virtual devices: off (android.virtualDevices is false); only enrolled physical devices are leased", + " Runtimes: (none) (default: (none))", + " Models: (none)", + "", + ].join("\n"), + ); + expect(JSON.parse(await run(["catalog", "--json"]))).toEqual({ platforms: [entry] }); + }); + it("prints each model with the runtimes it pairs with", async () => { const output = outputCapture(); const environment = output.environmentWith({ diff --git a/src/contract/protocol.ts b/src/contract/protocol.ts index c55b0857a..1ed2813a9 100644 --- a/src/contract/protocol.ts +++ b/src/contract/protocol.ts @@ -10,7 +10,7 @@ export interface ProtocolRange { const protocolRangeSchema = z.object({ min: z.number().int(), max: z.number().int() }); /** Widen only once a second version is kept alive side by side with the first; a bump that leaves no shim behind moves both ends. */ -export const PROTOCOL_VERSION_RANGE: ProtocolRange = { min: 89, max: 92 }; +export const PROTOCOL_VERSION_RANGE: ProtocolRange = { min: 89, max: 93 }; const LEGACY_DAEMON_PROTOCOL_VERSION = 2; diff --git a/src/contract/status-schemas.ts b/src/contract/status-schemas.ts index 7c0a72fd1..2741e2668 100644 --- a/src/contract/status-schemas.ts +++ b/src/contract/status-schemas.ts @@ -306,6 +306,8 @@ export const platformCatalogSchema = z.object({ .optional(), defaultMode: deviceModeSchema.optional(), defaultImageTag: imageTagSchema.optional(), + /** why: ADR 0084 §3: `false` says this worker serves only enrolled physical devices of the platform; absent means it makes virtual devices. */ + virtualDevices: z.literal(false).optional(), }); /** diff --git a/src/core/config-defaults.ts b/src/core/config-defaults.ts index b2fa3bf9b..b82526980 100644 --- a/src/core/config-defaults.ts +++ b/src/core/config-defaults.ts @@ -149,8 +149,17 @@ export function defaultConfig( recoveryBackoffMs: 5_000, maxConcurrentRecoveries: 1, }, - ios: { ...driverDefaults(driverSections, "ios"), defaultMode: "full", defaultModels: {} }, - android: { ...driverDefaults(driverSections, "android"), defaultModels: {} }, + ios: { + ...driverDefaults(driverSections, "ios"), + defaultMode: "full", + defaultModels: {}, + virtualDevices: true, + }, + android: { + ...driverDefaults(driverSections, "android"), + defaultModels: {}, + virtualDevices: true, + }, gateway: { disconnectedRetentionMs: DEFAULT_DISCONNECTED_RETENTION_MS, execTimeoutMs: DEFAULT_GATEWAY_EXEC_TIMEOUT_MS, diff --git a/src/core/config-platform-and-driver-settings.test.ts b/src/core/config-platform-and-driver-settings.test.ts index 2961cb21b..10acf7903 100644 --- a/src/core/config-platform-and-driver-settings.test.ts +++ b/src/core/config-platform-and-driver-settings.test.ts @@ -54,8 +54,12 @@ describe("loadConfig", () => { 'Invalid config value for "android.turbo"', ); expect(unknown.warn).toHaveBeenCalledWith('Unknown config key: "android.turbo"'); - expect(unknown.config.android).toEqual({ defaultModels: {} }); - expect(set.config.ios).toEqual({ defaultMode: "full", defaultModels: {} }); + expect(unknown.config.android).toEqual({ defaultModels: {}, virtualDevices: true }); + expect(set.config.ios).toEqual({ + defaultMode: "full", + defaultModels: {}, + virtualDevices: true, + }); }); it("loads android.defaultImageTag when it is a valid image tag, leaves it unset when absent, and refuses any other value naming the key and what it expects", async () => { @@ -77,6 +81,39 @@ describe("loadConfig", () => { } }); + it("loads .virtualDevices as true when unset, false when set, refuses a non-boolean naming the key, and ignores it with a warning on a gateway", async () => { + const load = async (file: unknown, role: "gateway" | "worker" = "worker") => { + const filesystem = new MemoryFilesystem(); + const warn = vi.fn(); + await filesystem.mkdirp("/home/agent/.simlock"); + await filesystem.writeFileAtomic(configPath, JSON.stringify(file)); + const config = await loadConfig({ + configPath, + filesystem, + role, + systemStats: createStats(), + warn, + }); + return { config, warn }; + }; + + const unset = (await load({})).config; + expect([unset.android.virtualDevices, unset.ios.virtualDevices]).toEqual([true, true]); + const android = (await load({ android: { virtualDevices: false } })).config; + expect([android.android.virtualDevices, android.ios.virtualDevices]).toEqual([false, true]); + const ios = (await load({ ios: { virtualDevices: false } })).config; + expect([ios.android.virtualDevices, ios.ios.virtualDevices]).toEqual([true, false]); + for (const value of ["no", 0]) { + await expect(load({ android: { virtualDevices: value } }), String(value)).rejects.toThrow( + 'Invalid config value for "android.virtualDevices": expected a boolean', + ); + } + const gateway = await load({ ios: { virtualDevices: false } }, "gateway"); + expect(gateway.warn).toHaveBeenCalledWith( + 'Ignoring "ios": it configures a worker, and this daemon runs in gateway mode.', + ); + }); + it.each(["fast", "worker", true])( "rejects an ios.defaultMode of %j, naming the key", async (value) => { diff --git a/src/core/config-types.ts b/src/core/config-types.ts index f650fd4a1..1da96b0d9 100644 --- a/src/core/config-types.ts +++ b/src/core/config-types.ts @@ -166,11 +166,15 @@ export interface Config { readonly ios: { readonly defaultMode: DeviceMode; readonly defaultModels: DefaultModels; + /** why: false makes this worker serve only enrolled physical iOS devices (ADR 0084 §1). */ + readonly virtualDevices: boolean; } & DriverConfigSection; readonly android: { /** why: the image tag an Android lease that names none gets where an image of it fits (ADR 0078 §1). */ readonly defaultImageTag?: string; readonly defaultModels: DefaultModels; + /** why: false makes this worker serve only enrolled physical Android devices (ADR 0084 §1). */ + readonly virtualDevices: boolean; } & DriverConfigSection; /** * why: ADR 0005 §3/§6. Both sides of the fleet live under one key, and which half is read depends diff --git a/src/core/config-validators.ts b/src/core/config-validators.ts index 48d30ff08..f4eda535b 100644 --- a/src/core/config-validators.ts +++ b/src/core/config-validators.ts @@ -256,11 +256,13 @@ export function configValidators( ...driverValidators(driverSections, "ios"), defaultMode: stringUnion(["slim", "full"]), defaultModels: defaultModelsValidator, + virtualDevices: booleanValue, }), android: objectValidator({ ...driverValidators(driverSections, "android"), defaultImageTag: imageTagValidator, defaultModels: defaultModelsValidator, + virtualDevices: booleanValue, }), stalledTransition: objectValidator({ thresholdMultiplier: numberAtLeast(1), diff --git a/src/core/create-core.ts b/src/core/create-core.ts index d6a224895..9bc174ebc 100644 --- a/src/core/create-core.ts +++ b/src/core/create-core.ts @@ -218,6 +218,10 @@ export function createCore(options: CoreOptions): Core { const drivers = new DriverCatalog(options.drivers, { logger: options.logger, preferences: options.modelPreferences, + virtualDevices: { + android: options.config.android.virtualDevices, + ios: options.config.ios.virtualDevices, + }, }); const deviceLifecycle = new ManagedDeviceLifecycle( drivers, @@ -391,6 +395,29 @@ export function createCore(options: CoreOptions): Core { const startup = new StartupConverger({ claims, decisions, + idleDeletion: { + // why: a failed shutdown or delete must not stop the daemon from starting: the device stays in the state it reached and the next start tries again (ADR 0084 §2). + deleteIdle: async (device) => { + try { + const stopped = + device.state === "ready" + ? await deviceLifecycle.shutdown(device, "virtual-devices-off", "cleanup") + : device; + if (stopped !== undefined) { + await deviceLifecycle.destroy(stopped, "virtual-devices-off", "cleanup"); + } + } catch (error: unknown) { + options.logger?.warn("Could not delete an idle device at start", { + deviceId: device.id, + error: stableError(error), + platform: device.spec.platform, + }); + } + }, + platforms: (["ios", "android"] as const).filter( + (platform) => !drivers.virtualDevices(platform), + ), + }, interruptedReclaimRecovery: { recoverInterruptedReclaim: async (device) => { await reclaim.recoverInterrupted(device.id); diff --git a/src/core/doctor-findings.ts b/src/core/doctor-findings.ts index 4fa6a8903..0ab5ca67e 100644 --- a/src/core/doctor-findings.ts +++ b/src/core/doctor-findings.ts @@ -157,10 +157,23 @@ function isRange(osVersion: string): boolean { export function unreachableTarget( target: WarmTargetFigures, catalog: DriverCatalogEntry | undefined, + virtualDevices: boolean, ): DoctorFinding[] { const { model, osVersion, platform, short } = target; const named = [model, osVersion, target.mode].filter((part) => part !== undefined).join(" / "); const name = PLATFORM_NAMES[platform]; + if (!virtualDevices) { + return [ + { + kind: "warm-pool-target-unreachable", + message: `${named} cannot be met: ${platform}.virtualDevices is false`, + platform, + reason: "unknown-model", + remedy: `remove the target from warmPool.targets, or set ${platform}.virtualDevices true`, + target: named, + }, + ]; + } if (short === "runtime-missing") { if (osVersion !== undefined && isRange(osVersion)) { return [ diff --git a/src/core/doctor-types.ts b/src/core/doctor-types.ts index f8bc5bf78..673f6eca5 100644 --- a/src/core/doctor-types.ts +++ b/src/core/doctor-types.ts @@ -139,7 +139,8 @@ export interface DoctorQuarantine { enterFromStalledTransition(deviceId: string, findingState: DeviceState): Promise; } -export type DoctorConfig = Pick; +export type DoctorConfig = Pick & + Readonly>>; export interface DoctorOptions { readonly clock: Clock; diff --git a/src/core/doctor-warm-pool-targets.test.ts b/src/core/doctor-warm-pool-targets.test.ts index 75196fc88..30c0b8239 100644 --- a/src/core/doctor-warm-pool-targets.test.ts +++ b/src/core/doctor-warm-pool-targets.test.ts @@ -50,6 +50,7 @@ describe("Doctor: warm pool targets", () => { readonly limit?: { ios?: number; android?: number; global?: number }; readonly figures?: ReturnType; readonly driver?: Omit[0], "clock">; + readonly virtualDevices?: Partial>; }): Promise { const clock = new FakeClock(10_000); const eventBus = new EventBus(clock); @@ -60,6 +61,8 @@ describe("Doctor: warm pool targets", () => { clock, config: { ...base, + android: { virtualDevices: options.virtualDevices?.android ?? true }, + ios: { virtualDevices: options.virtualDevices?.ios ?? true }, warmPool: { ...base.warmPool, enabled: options.enabled ?? true, @@ -148,6 +151,61 @@ describe("Doctor: warm pool targets", () => { ]); }); + it("names .virtualDevices for a configured target on a phones-only platform, and keeps today's findings with the key true or on the other platform", async () => { + const androidTarget = { model: "Pixel 9", osVersion: "36", platform: "android" } as const; + const target = "Pixel 9 / 36 / full"; + + const off = await findings({ + figures: figuresOf([{ ...androidTarget, short: "unknown-model" }]), + virtualDevices: { android: false }, + }); + const on = await findings({ + figures: figuresOf([{ ...androidTarget, short: "unknown-model" }]), + }); + const otherOff = await findings({ + figures: figuresOf([{ model: "iPhone 99", osVersion: "26.0", short: "unknown-model" }]), + virtualDevices: { android: false }, + }); + + expect(off).toStrictEqual([ + { + kind: "warm-pool-target-unreachable", + message: `${target} cannot be met: android.virtualDevices is false`, + platform: "android", + reason: "unknown-model", + remedy: "remove the target from warmPool.targets, or set android.virtualDevices true", + target, + }, + ]); + expect(on).toStrictEqual([ + expect.objectContaining({ + message: "Pixel 9 is not a known Android model", + reason: "unknown-model", + }), + ]); + expect(otherOff).toStrictEqual([ + expect.objectContaining({ + message: "iPhone 99 is not a known iOS model", + platform: "ios", + }), + ]); + }); + + it("leaves a phones-only platform's reserveRunning out of the room the targets are checked against", async () => { + const ask = (virtualDevices: boolean) => + findings({ + limit: { global: 2 }, + reserve: { android: 2, ios: 0 }, + targets: [{ count: 2, model: "iPhone 17", platform: "ios" }], + virtualDevices: { android: virtualDevices }, + }); + + expect(await ask(true)).toStrictEqual([ + expect.objectContaining({ reason: "over-limit", target: "all targets" }), + ]); + expect(await ask(false)).toStrictEqual([]); + }); + it("reports a target short with unknown-model as unreachable", async () => { const found = await findings({ figures: figuresOf([{ model: "iPhone 99", osVersion: "26.0", short: "unknown-model" }]), diff --git a/src/core/doctor.ts b/src/core/doctor.ts index c7102ce07..7ac3bedc9 100644 --- a/src/core/doctor.ts +++ b/src/core/doctor.ts @@ -30,7 +30,11 @@ import { stalledTransitionFinding, unreachableTarget, } from "./doctor-findings.js"; -import { reservedRunning, type WarmTargetFigures } from "./warm-pool/index.js"; +import { + reservedRunning, + reserveOnVirtualPlatforms, + type WarmTargetFigures, +} from "./warm-pool/index.js"; import type { StartupRead } from "./startup-read.js"; export type { @@ -540,9 +544,22 @@ export class Doctor { const figures = warmPool.figures().targets.filter((target) => target.origin === "configured"); const catalogs = await this.#catalogsOfMissingRuntimes(figures); const findings = figures.flatMap((target) => - unreachableTarget(target, catalogs.get(target.platform)), + unreachableTarget( + target, + catalogs.get(target.platform), + this.options.config[target.platform].virtualDevices, + ), + ); + const { android, ios } = this.options.config; + const reserves = reservedRunning( + { + reserveRunning: reserveOnVirtualPlatforms( + this.options.config.warmPool.reserveRunning, + (platform) => (platform === "ios" ? ios : android).virtualDevices, + ), + }, + limits, ); - const reserves = reservedRunning(this.options.config.warmPool, limits); let wanted = 0; for (const platform of ["ios", "android"] as const) { const sum = targets diff --git a/src/core/driver-catalog.ts b/src/core/driver-catalog.ts index 08e0747c4..e543562a0 100644 --- a/src/core/driver-catalog.ts +++ b/src/core/driver-catalog.ts @@ -41,6 +41,8 @@ export type ModelPreferences = Readonly< export interface PlatformCatalog extends DriverCatalogEntry { readonly platform: Platform; readonly classDefaults: Readonly>>; + /** why: `false` for a platform whose `.virtualDevices` is off (ADR 0084 §3); absent otherwise. */ + readonly virtualDevices?: false; } export interface ScreenAvailability { @@ -48,23 +50,47 @@ export interface ScreenAvailability { readonly reason?: string; } +/** why: the catalog entry of a platform whose virtual devices are off: the platform stays so a gateway still routes phone requests to this worker (ADR 0084 §3). */ +function phonesOnlyEntry(platform: Platform): PlatformCatalog { + return { + classDefaults: {}, + defaultRuntime: undefined, + modelAliases: {}, + modelClasses: {}, + modelRuntimes: {}, + models: [], + platform, + runtimes: [], + virtualDevices: false, + }; +} + export class DriverCatalog { readonly #drivers: ReadonlyMap; readonly #logger: Logger; readonly #preferences: ModelPreferences; + readonly #virtualDevices: Readonly>>; constructor( drivers: readonly Driver[], options: { readonly logger?: Logger | undefined; readonly preferences?: ModelPreferences | undefined; + /** why: a platform set to `false` serves enrolled physical devices only (ADR 0084 §1). */ + readonly virtualDevices?: Readonly>> | undefined; } = {}, ) { + this.#virtualDevices = options.virtualDevices ?? {}; this.#drivers = new Map(drivers.map((driver) => [driver.platform, driver])); this.#preferences = options.preferences ?? {}; this.#logger = options.logger?.child("driver-catalog") ?? new NoopLogger(); } + /** why: false only for a platform whose `.virtualDevices` key is false (ADR 0084 §1). */ + virtualDevices(platform: Platform): boolean { + return this.#virtualDevices[platform] !== false; + } + get(platform: Platform): Driver { const driver = this.#drivers.get(platform); if (driver === undefined) throw new NoDriverError(platform); @@ -195,6 +221,7 @@ export class DriverCatalog { async listCatalog(platform?: Platform): Promise { const listed = await Promise.all( this.select(platform).map(async (driver): Promise => { + if (!this.virtualDevices(driver.platform)) return phonesOnlyEntry(driver.platform); try { const entry = await driver.listCatalog(); return { diff --git a/src/core/nuke.test.ts b/src/core/nuke.test.ts index 48d5646d5..588d4d902 100644 --- a/src/core/nuke.test.ts +++ b/src/core/nuke.test.ts @@ -293,7 +293,9 @@ function sequence() { function config(): TestEngineConfig { return { + android: { virtualDevices: true }, devices: { autoEnroll: false, deletedRetentionMs: 3_600_000 }, + ios: { virtualDevices: true }, health: { enabled: true, maxConcurrentRecoveries: 1, diff --git a/src/core/reaper.test.ts b/src/core/reaper.test.ts index f0b123c8b..cb9723f8d 100644 --- a/src/core/reaper.test.ts +++ b/src/core/reaper.test.ts @@ -47,7 +47,9 @@ class MutableFreeDiskFilesystem extends MemoryFilesystem { function config(): ReaperTestConfig { return { + android: { virtualDevices: true }, devices: { autoEnroll: false, deletedRetentionMs: 3_600_000 }, + ios: { virtualDevices: true }, diskPressure: { freeBytesThreshold: 10 * gibibyte }, health: { enabled: true, diff --git a/src/core/startup-converger.test.ts b/src/core/startup-converger.test.ts index 7b2d2b5cb..2694e5a2c 100644 --- a/src/core/startup-converger.test.ts +++ b/src/core/startup-converger.test.ts @@ -56,6 +56,7 @@ function createHarness( const converger = new StartupConverger({ claims: { isClaimed: (deviceId) => claimed.has(deviceId) }, decisions: new SerializedDecision(), + idleDeletion: { deleteIdle: async () => undefined, platforms: [] }, interruptedReclaimRecovery: recovery, quarantineRestore, registry: { diff --git a/src/core/startup-converger.ts b/src/core/startup-converger.ts index a85567fc3..648483b8d 100644 --- a/src/core/startup-converger.ts +++ b/src/core/startup-converger.ts @@ -1,4 +1,10 @@ -import { type DeviceRecord, type LeaseRecord, mayBeGranted, type VirtualDevice } from "./domain.js"; +import { + type DeviceRecord, + type LeaseRecord, + mayBeGranted, + type Platform, + type VirtualDevice, +} from "./domain.js"; import type { SerializedDecision } from "./serialized-decision.js"; import type { StartupRead } from "./startup-read.js"; @@ -17,6 +23,12 @@ export interface SpentDeviceDeletion { deleteSpent(device: VirtualDevice): Promise; } +/** why: deletes an idle virtual device of a platform whose `.virtualDevices` is false (ADR 0084 §2). */ +export interface IdleDeviceDeletion { + readonly platforms: readonly Platform[]; + deleteIdle(device: VirtualDevice): Promise; +} + export interface QuarantineRestorer { restore(include: (device: DeviceRecord) => boolean): void; } @@ -28,6 +40,7 @@ export interface DeviceClaimReader { export interface StartupConvergerOptions { readonly claims: DeviceClaimReader; readonly decisions: SerializedDecision; + readonly idleDeletion: IdleDeviceDeletion; readonly interruptedReclaimRecovery: InterruptedReclaimRecovery; readonly quarantineRestore: QuarantineRestorer; readonly registry: StartupRegistry; @@ -50,6 +63,20 @@ export class StartupConverger { // After interrupted reclaims: a spent fresh device found `reclaiming` has just been shut // down there, and is deleted here along with any the previous process left `shutdown`. await this.#deleteSpentDevices(read); + await this.#deleteIdleDevicesOfOffPlatforms(read); + } + + async #deleteIdleDevicesOfOffPlatforms(read: StartupRead): Promise { + const { platforms } = this.options.idleDeletion; + if (platforms.length === 0) return; + const idle = await this.options.decisions.run(() => + (["ready", "shutdown"] as const) + .flatMap((state) => this.#actionableDevices(state, read)) + .filter((device) => platforms.includes(device.spec.platform)), + ); + for (const device of idle) { + await this.options.idleDeletion.deleteIdle(device); + } } async #recoverInterruptedReclaims(read: StartupRead): Promise { diff --git a/src/core/test-doctor.ts b/src/core/test-doctor.ts index 47ffd003a..36bc6e47e 100644 --- a/src/core/test-doctor.ts +++ b/src/core/test-doctor.ts @@ -72,7 +72,9 @@ export function config( stalledTransitionOverrides: Partial = {}, ): TestEngineConfig { return { + android: { virtualDevices: true }, devices: { autoEnroll: false, deletedRetentionMs: 3_600_000 }, + ios: { virtualDevices: true }, health: { enabled: true, maxConcurrentRecoveries: 1, diff --git a/src/core/warm-pool/converger.ts b/src/core/warm-pool/converger.ts index 015af42fe..5bed31b91 100644 --- a/src/core/warm-pool/converger.ts +++ b/src/core/warm-pool/converger.ts @@ -32,6 +32,7 @@ import { evaluate, type ResolvedTarget, readyCount, + reserveOnVirtualPlatforms, targetedDevices, type TargetKind, type TargetReport, @@ -79,7 +80,7 @@ export interface WarmPoolOptions { readonly hasDriver: (platform: Platform) => boolean; readonly idle: { readonly shutdownAfterMs: number }; /** why: the pool reads the catalog of a platform with a learned kind, to forget a kind whose model or runtime is gone. */ - readonly catalog: Pick; + readonly catalog: Pick; readonly lifecycle: Pick; readonly logger?: Logger; /** why: ADR 0068 §3: the pool starts nothing at `warming-paused` and sheds one idle device per reading. */ @@ -662,7 +663,9 @@ export class WarmPool { config: { enabled: this.options.config.enabled, maxConcurrentBoots: this.options.config.maxConcurrentBoots, - reserveRunning: this.options.config.reserveRunning, + reserveRunning: reserveOnVirtualPlatforms(this.options.config.reserveRunning, (platform) => + this.options.catalog.virtualDevices(platform), + ), shutdownAfterMs: this.options.idle.shutdownAfterMs, }, devices, diff --git a/src/core/warm-pool/index.ts b/src/core/warm-pool/index.ts index f45fdf4ab..1f523be3e 100644 --- a/src/core/warm-pool/index.ts +++ b/src/core/warm-pool/index.ts @@ -4,4 +4,4 @@ export { defaultWarmPoolConfig, warmPoolConfigValidator } from "./config.js"; export type { WarmPoolConfig } from "./config.js"; export type { WarmPoolFigures, WarmTargetFigures } from "./figures.js"; export type { LearnedKindMatch } from "./learned.js"; -export { reservedRunning } from "./policy.js"; +export { reservedRunning, reserveOnVirtualPlatforms } from "./policy.js"; diff --git a/src/core/warm-pool/policy.ts b/src/core/warm-pool/policy.ts index 098752409..5a7bd8ab2 100644 --- a/src/core/warm-pool/policy.ts +++ b/src/core/warm-pool/policy.ts @@ -224,6 +224,16 @@ function reservedOf(view: WarmPolicyView): Slots { return { android: reserve.android, global: reserve.ios + reserve.android, ios: reserve.ios }; } +/** why: a platform with virtual devices off holds no running slot for idle devices, so its reserve counts as 0 (ADR 0084 §2). */ +export function reserveOnVirtualPlatforms( + reserve: { readonly ios: number; readonly android: number }, + virtualDevices: (platform: "ios" | "android") => boolean, +): { readonly ios: number; readonly android: number } { + const kept = (platform: "ios" | "android"): number => + virtualDevices(platform) ? reserve[platform] : 0; + return { android: kept("android"), ios: kept("ios") }; +} + /** * The running slots the operator's reserve holds back on each platform: `reserveRunning`, never * more than that platform's own running limit. The one place the cap is decided; `doctor` reads it diff --git a/src/core/warm-pool/test-fixtures.ts b/src/core/warm-pool/test-fixtures.ts index 430de497b..b8d214958 100644 --- a/src/core/warm-pool/test-fixtures.ts +++ b/src/core/warm-pool/test-fixtures.ts @@ -293,7 +293,7 @@ export function harness( }; }, }, - catalog: { listCatalog: options.catalog ?? (async () => []) }, + catalog: { listCatalog: options.catalog ?? (async () => []), virtualDevices: () => true }, claims: { claim: (id) => claims.claim(id), isClaimed: (id) => claims.isClaimed(id), diff --git a/src/daemon/dispatcher-virtual-devices-off.test.ts b/src/daemon/dispatcher-virtual-devices-off.test.ts new file mode 100644 index 000000000..a70c65cf2 --- /dev/null +++ b/src/daemon/dispatcher-virtual-devices-off.test.ts @@ -0,0 +1,184 @@ +import { describe, expect, it } from "vitest"; +import { FakeDriver } from "../core/testing.js"; +import { FakeClock } from "../ports/index.js"; +import { classifyError } from "./error-code.js"; +import { buildDispatcher, flushPromises, session } from "./test-dispatcher.js"; + +type Off = "android" | "ios"; + +const OTHER: Record = { android: "ios", ios: "android" }; + +function refusal(platform: Off): string { + return ( + `This worker serves only enrolled physical ${platform} devices ` + + `(${platform}.virtualDevices is false); ask for a physical device (--physical, or physical: true)` + ); +} + +// why: the request shapes of ADR 0084's Examples, each a plain lease on the phones-only platform. +function plainRequests(platform: Off): readonly Record[] { + return [ + { platform }, + { model: "Pixel 9", platform }, + { osVersion: ">=34", platform }, + { allowDownload: true, osVersion: "36", platform }, + { baseline: "checkout", platform }, + { noWait: true, platform }, + ...(platform === "android" ? [{ imageTag: "google_apis_playstore", platform }] : []), + ...(platform === "ios" ? [{ except: ["audio"], mode: "slim", platform }] : []), + ]; +} + +describe("a worker whose .virtualDevices is false", () => { + it.each(["android", "ios"] as const)( + "refuses a plain %s lease at once with UNKNOWN_MODEL naming the key, never touching the driver, and serves the other platform", + async (off) => { + const clock = new FakeClock(1_000); + const offDriver = new FakeDriver({ availableOsVersions: ["36"], clock, platform: off }); + const otherDriver = new FakeDriver({ + availableOsVersions: ["26.5"], + clock, + knownModels: ["Other"], + platform: OTHER[off], + }); + const { dispatcher, eventBus } = await buildDispatcher({ + clock, + driverOptions: { platform: "ios" }, + extraDrivers: [offDriver, otherDriver], + virtualDevices: { [off]: false }, + }); + const requests = plainRequests(off); + + for (const [index, request] of requests.entries()) { + const error = await dispatcher + .dispatch("lease.request", { ...request, requesterId: `agent-${index}` }, session()) + .then( + () => undefined, + (rejection: unknown) => rejection, + ); + expect(classifyError(error), JSON.stringify(request)).toBe("UNKNOWN_MODEL"); + expect(error).toMatchObject({ message: refusal(off), platform: off }); + } + + expect(eventBus.replay().filter((event) => event.event === "lease.requested")).toHaveLength( + requests.length, + ); + const operations = offDriver.calls.map((call) => call.operation); + expect(operations).not.toContain("resolveSpec"); + expect(operations).not.toContain("listCatalog"); + expect(operations).not.toContain("installComponent"); + + const served = await dispatcher.dispatch( + "lease.request", + { model: "Other", platform: OTHER[off], requesterId: "agent-other" }, + session(), + ); + expect(served.device.spec.platform).toBe(OTHER[off]); + }, + ); + + it("serves a --physical lease as on any worker: granted, waiting, NO_CAPACITY with noWait, UNKNOWN_MODEL with no enrolled match", async () => { + const { dispatcher, driver, engine } = await buildDispatcher({ + physicalDevices: [ + { + createdAt: 1, + driverDeviceId: "00008110-001A2B3C4D5E", + enrolledApps: [], + id: "dev_phys", + spec: { class: "phone", model: "iPhone 15", osVersion: "18.4" }, + state: "ready", + }, + ], + virtualDevices: { ios: false }, + }); + await engine.convergeRunningCapacity(); + driver.setPhysicalPresence("00008110-001A2B3C4D5E", true); + const phone = { model: "iPhone 15", physical: true, platform: "ios" } as const; + const ask = (input: Record, requesterId: string) => + dispatcher.dispatch("lease.request", { ...input, requesterId }, session()); + + const granted = await ask(phone, "first"); + expect(granted.device).toMatchObject({ id: "dev_phys", physical: true }); + + const noWait = await ask({ ...phone, noWait: true }, "second").then( + () => undefined, + (rejection: unknown) => rejection, + ); + expect(classifyError(noWait)).toBe("NO_CAPACITY"); + + let waiterSettled = false; + const waiter = ask(phone, "third").finally(() => { + waiterSettled = true; + }); + await flushPromises(); + expect(waiterSettled).toBe(false); + await dispatcher.dispatch("lease.release", { leaseId: granted.lease.id }, session()); + await expect(waiter).resolves.toMatchObject({ device: { id: "dev_phys", physical: true } }); + + const unmatched = await ask({ ...phone, model: "iPhone 99" }, "fourth").then( + () => undefined, + (rejection: unknown) => rejection, + ); + expect(classifyError(unmatched)).toBe("UNKNOWN_MODEL"); + expect((unmatched as Error).message).toContain("no enrolled physical device can match"); + }); + + it("catalog.get answers a phones-only platform with empty lists and virtualDevices false, without asking its driver, and the other platform in full", async () => { + const clock = new FakeClock(1_000); + const android = new FakeDriver({ + availableOsVersions: ["36"], + clock, + knownModels: ["Pixel 8"], + platform: "android", + }); + const { dispatcher } = await buildDispatcher({ + clock, + extraDrivers: [android], + virtualDevices: { android: false }, + }); + const phonesOnly = { + classDefaults: {}, + modelAliases: {}, + modelClasses: {}, + modelRuntimes: {}, + models: [], + platform: "android", + runtimes: [], + virtualDevices: false, + }; + + const only = await dispatcher.dispatch("catalog.get", { platform: "android" }, session()); + const both = await dispatcher.dispatch("catalog.get", {}, session()); + + expect(only.platforms).toEqual([phonesOnly]); + expect(both.platforms).toHaveLength(2); + expect(both.platforms.find((entry) => entry.platform === "android")).toEqual(phonesOnly); + expect(both.platforms.find((entry) => entry.platform === "ios")).toMatchObject({ + runtimes: ["26.5"], + }); + expect(both.platforms.find((entry) => entry.platform === "ios")).not.toHaveProperty( + "virtualDevices", + ); + expect(android.calls.map((call) => call.operation)).not.toContain("listCatalog"); + }); + + it("installs, lists and removes components on a phones-only platform as on any worker", async () => { + const { dispatcher } = await buildDispatcher({ virtualDevices: { ios: false } }); + const admin = session({ principal: "tok_operator", role: "admin" }); + const component = { platform: "ios", version: "27.0" } as const; + + await expect(dispatcher.dispatch("component.install", component, admin)).resolves.toEqual({ + component: "27.0", + outcome: "installed", + platform: "ios", + version: "27.0", + }); + const listed = await dispatcher.dispatch("component.list", { platform: "ios" }, admin); + expect(listed.components.map((entry) => entry.version)).toContain("27.0"); + await expect(dispatcher.dispatch("component.remove", component, admin)).resolves.toMatchObject({ + outcome: "removed", + }); + const after = await dispatcher.dispatch("component.list", { platform: "ios" }, admin); + expect(after.components.map((entry) => entry.version)).not.toContain("27.0"); + }); +}); diff --git a/src/daemon/driver-discovery.test.ts b/src/daemon/driver-discovery.test.ts index ec39bb3a2..7183cdb00 100644 --- a/src/daemon/driver-discovery.test.ts +++ b/src/daemon/driver-discovery.test.ts @@ -644,10 +644,11 @@ describe("deviceModeWiring", () => { (defaultMode) => { expect( deviceModeWiring({ - android: { defaultModels: {} }, + android: { defaultModels: {}, virtualDevices: true }, ios: { defaultMode, defaultModels: {}, + virtualDevices: true, }, }), ).toMatchObject({ @@ -658,16 +659,21 @@ describe("deviceModeWiring", () => { ); it("passes android.defaultImageTag to leasing as the Android default tag, and nothing when it is unset", () => { - const ios = { defaultMode: "full", defaultModels: {} } as const; + const ios = { defaultMode: "full", defaultModels: {}, virtualDevices: true } as const; expect( deviceModeWiring({ - android: { defaultImageTag: "google_apis_playstore", defaultModels: {} }, + android: { + defaultImageTag: "google_apis_playstore", + defaultModels: {}, + virtualDevices: true, + }, ios, }).defaultImageTags, ).toEqual({ android: "google_apis_playstore" }); expect( - deviceModeWiring({ android: { defaultModels: {} }, ios }).defaultImageTags, + deviceModeWiring({ android: { defaultModels: {}, virtualDevices: true }, ios }) + .defaultImageTags, ).toStrictEqual({}); }); }); diff --git a/src/daemon/test-dispatcher.ts b/src/daemon/test-dispatcher.ts index add8d1a90..82e69d6da 100644 --- a/src/daemon/test-dispatcher.ts +++ b/src/daemon/test-dispatcher.ts @@ -105,6 +105,17 @@ function withGatewayLabel(config: Config, label: string | undefined): Config { return label === undefined ? config : { ...config, gateway: { ...config.gateway, label } }; } +function withVirtualDevices( + config: Config, + virtualDevices: Readonly>> | undefined, +): Config { + return { + ...config, + android: { ...config.android, virtualDevices: virtualDevices?.android ?? true }, + ios: { ...config.ios, virtualDevices: virtualDevices?.ios ?? true }, + }; +} + function withHttp(config: Config, http: Config["http"] | undefined): Config { return http === undefined ? config : { ...config, http }; } @@ -178,6 +189,8 @@ export async function buildDispatcher( readonly iosDefaultMode?: "slim" | "full"; /** why: the `android.defaultImageTag` `config.get` reports. */ readonly androidDefaultImageTag?: string; + /** why: a platform a test turns `.virtualDevices` off for (ADR 0084). */ + readonly virtualDevices?: Readonly>>; /** why: the two boot deadlines `config.get` reports. */ readonly bootTimeouts?: { readonly iosFull: number; readonly android: number }; readonly components?: Pick< @@ -238,22 +251,27 @@ export async function buildDispatcher( ), overrides.http, ); - const config: Config = { - ...baseConfig, - ...(overrides.androidDefaultImageTag === undefined - ? {} - : { android: { ...baseConfig.android, defaultImageTag: overrides.androidDefaultImageTag } }), - warmPool: { ...baseConfig.warmPool, ...overrides.warmPool }, - ...(overrides.iosDefaultMode === undefined - ? {} - : { ios: { ...baseConfig.ios, defaultMode: overrides.iosDefaultMode } }), - ...(overrides.bootTimeouts === undefined - ? {} - : { - android: { ...baseConfig.android, bootTimeoutMs: overrides.bootTimeouts.android }, - ios: { ...baseConfig.ios, full: { bootTimeoutMs: overrides.bootTimeouts.iosFull } }, - }), - }; + const config: Config = withVirtualDevices( + { + ...baseConfig, + ...(overrides.androidDefaultImageTag === undefined + ? {} + : { + android: { ...baseConfig.android, defaultImageTag: overrides.androidDefaultImageTag }, + }), + warmPool: { ...baseConfig.warmPool, ...overrides.warmPool }, + ...(overrides.iosDefaultMode === undefined + ? {} + : { ios: { ...baseConfig.ios, defaultMode: overrides.iosDefaultMode } }), + ...(overrides.bootTimeouts === undefined + ? {} + : { + android: { ...baseConfig.android, bootTimeoutMs: overrides.bootTimeouts.android }, + ios: { ...baseConfig.ios, full: { bootTimeoutMs: overrides.bootTimeouts.iosFull } }, + }), + }, + overrides.virtualDevices, + ); const wiring = testComponentWiring({ clock: clock, components: overrides.components, diff --git a/src/leasing/acquisition-errors.ts b/src/leasing/acquisition-errors.ts index 9b8621710..294dda87c 100644 --- a/src/leasing/acquisition-errors.ts +++ b/src/leasing/acquisition-errors.ts @@ -1,4 +1,9 @@ -import { noPhysicalMatch, type PhysicalRequest, UnknownModelError } from "../core/index.js"; +import { + type DeviceRequest, + noPhysicalMatch, + type PhysicalRequest, + UnknownModelError, +} from "../core/index.js"; import { type WaitingReason } from "./acquisition-planner.js"; export class NoCapacityError extends Error { @@ -37,6 +42,18 @@ export class PhysicalUnknownModelError extends UnknownModelError { } } +/** why: a plain lease on a platform whose `.virtualDevices` is false; the message names the key and both ways to ask for a physical device (ADR 0084 §2). */ +export class VirtualDevicesOffError extends UnknownModelError { + constructor(request: Pick) { + super(request.platform, request.model, request.model === undefined ? request.class : undefined); + this.name = "VirtualDevicesOffError"; + this.message = + `This worker serves only enrolled physical ${request.platform} devices ` + + `(${request.platform}.virtualDevices is false); ask for a physical device ` + + "(--physical, or physical: true)"; + } +} + export function asError(error: unknown): Error { return error instanceof Error ? error : new Error(String(error)); } diff --git a/src/leasing/acquisition-ports.ts b/src/leasing/acquisition-ports.ts index f995db61b..ee29a8ebd 100644 --- a/src/leasing/acquisition-ports.ts +++ b/src/leasing/acquisition-ports.ts @@ -59,7 +59,7 @@ export type AcquisitionQueue = Pick< export interface LeaseAcquisitionCoordinatorOptions { readonly baselines: Pick; - readonly catalog: Pick; + readonly catalog: Pick & Pick; readonly claims: AcquisitionClaims; readonly components: Pick; readonly decisions: AcquisitionDecision; diff --git a/src/leasing/acquisition-spec-resolver.ts b/src/leasing/acquisition-spec-resolver.ts index 7ca1f34f0..bb01cda48 100644 --- a/src/leasing/acquisition-spec-resolver.ts +++ b/src/leasing/acquisition-spec-resolver.ts @@ -23,7 +23,7 @@ import { UnknownModelError, type VirtualSpec, } from "../core/index.js"; -import { asError } from "./acquisition-errors.js"; +import { asError, VirtualDevicesOffError } from "./acquisition-errors.js"; import { type LeaseAcquisitionCoordinatorOptions } from "./acquisition-ports.js"; import { downloadingProgress, @@ -66,6 +66,10 @@ export class AcquisitionSpecResolver { readonly requirement: DeviceRequirement; readonly classOf: ((model: string) => DeviceClass | undefined) | undefined; }> { + // why: before the baseline branch, any catalog read, download or wait: a phones-only platform makes no virtual device (ADR 0084 §2). + if (!this.options.catalog.virtualDevices(request.platform)) { + throw new VirtualDevicesOffError(request); + } if (request.baseline !== undefined) { return this.#resolveBaseline(driver, request.baseline, request); } diff --git a/src/leasing/create-leasing-virtual-devices-off-startup.test.ts b/src/leasing/create-leasing-virtual-devices-off-startup.test.ts new file mode 100644 index 000000000..e24f8f8e9 --- /dev/null +++ b/src/leasing/create-leasing-virtual-devices-off-startup.test.ts @@ -0,0 +1,173 @@ +import { describe, expect, it } from "vitest"; +import { toDriverDevice } from "../core/index.js"; +import { FakeDriver, openTestState } from "../core/testing.js"; +import { FakeClock, JsonLinesLogger, MemoryLogSink } from "../ports/index.js"; +import { androidRequest, createHarness, flush, request, seedReady } from "./test-create-leasing.js"; + +// why: a model no lease below asks for, so the leases make their own devices and leave these idle. +const ANDROID = { + model: "Pixel 7", + osVersion: "36", + physical: false, + platform: "android", +} as const; +const IOS = { ...request, physical: false } as const; +const LIMITS = { + android: { maxDevices: 8, maxRunning: 8 }, + ios: { maxDevices: 8, maxRunning: 8 }, + maxRunning: 16, +}; + +type Failure = "destroy" | "shutdown" | undefined; + +/** why: the worker ran with virtual devices on, left devices behind in every state, and starts again with Android phones-only. */ +async function restartedPhonesOnly(failure: Failure = undefined) { + const clock = new FakeClock(1_000); + const ios = new FakeDriver({ availableOsVersions: ["26.5"], clock, platform: "ios" }); + const android = new FakeDriver({ availableOsVersions: ["36"], clock, platform: "android" }); + const state = await openTestState(); + const before = await createHarness({ + drivers: [ios, android], + lease: { defaultTtlMs: 900_000 }, + limits: LIMITS, + state, + }); + const phone = await before.registry.enrollPhysical({ + apps: [], + class: "phone", + driverDeviceId: "serial-1", + model: "Pixel 8", + osVersion: "35", + platform: "android", + }); + const saver = await before.engine.request(androidRequest, { + ownerId: "saver", + requesterId: "saver", + }); + await before.engine.core.baselines.save({ + leaseId: saver.lease.id, + name: "checkout", + requesterId: "saver", + }); + const leased = await before.engine.request(androidRequest, { + ownerId: "holder", + requesterId: "holder", + }); + before.engine.dispose(); + + const sink = new MemoryLogSink(); + const after = await createHarness({ + drivers: [ios, android], + firstId: 5_000, + lease: { defaultTtlMs: 900_000 }, + limits: LIMITS, + logger: new JsonLinesLogger({ clock, sink }), + state, + virtualDevices: { android: false }, + }); + + const ready = await seedReady(after, ANDROID, "full", android); + const claimed = await seedReady(after, ANDROID, "full", android); + const shutdown = await seedReady(after, ANDROID, "full", android); + await android.shutdown(toDriverDevice(shutdown)); + await after.registry.transitionDevice(shutdown.id, "shutdown", { + event: "device.shutdown", + payload: { deviceId: shutdown.id, initiator: "test" }, + }); + const iosIdle = await seedReady(after, IOS, "full", ios); + after.engine.core.claims.tryClaim(claimed.id, "boot"); + const next = (operation: "destroy" | "shutdown") => + android.calls.filter((call) => call.operation === operation).length + 1; + if (failure !== undefined) { + android.failOn(failure, next(failure), new Error(`${failure} refused`)); + } + const mark = after.bus.replay().length; + await after.engine.convergeRunningCapacity(); + await flush(); + const events = after.bus + .replay() + .slice(mark) + .filter((event) => event.event === "device.shutdown" || event.event === "device.deleted") + .map((event) => ({ ...(event.payload as object), event: event.event })); + const stateOf = (id: string) => + after.registry.snapshot.devices.find((device) => device.id === id)?.state; + return { + after, + claimed, + events, + iosIdle, + leased, + logs: sink.records, + phone, + ready, + shutdown, + stateOf, + }; +} + +describe("startup on a worker whose android.virtualDevices is false", () => { + it("deletes the platform's idle devices, keeps leased, claimed, phone and iOS devices and the baseline, and goes on when a delete fails", async () => { + const world = await restartedPhonesOnly(); + + expect(world.events).toEqual([ + { deviceId: world.ready.id, event: "device.shutdown", initiator: "virtual-devices-off" }, + { + deviceId: world.ready.id, + event: "device.deleted", + initiator: "virtual-devices-off", + physical: false, + }, + { + deviceId: world.shutdown.id, + event: "device.deleted", + initiator: "virtual-devices-off", + physical: false, + }, + ]); + expect(world.stateOf(world.ready.id)).toBe("deleted"); + expect(world.stateOf(world.shutdown.id)).toBe("deleted"); + expect(world.stateOf(world.claimed.id)).toBe("ready"); + expect(world.stateOf(world.phone.id)).toBe("ready"); + expect(world.stateOf(world.iosIdle.id)).toBe("ready"); + expect(world.stateOf(world.leased.device.id)).toBe("leased"); + expect((await world.after.engine.core.baselines.list()).map((entry) => entry.name)).toEqual([ + "checkout", + ]); + + await world.after.engine.release(world.leased.lease.id, "explicit"); + await flush(); + expect(world.stateOf(world.leased.device.id)).toBe("deleted"); + expect( + world.after.bus + .replay() + .filter( + (event) => + event.event === "device.deleted" && + (event.payload as { deviceId: string }).deviceId === world.leased.device.id, + ) + .map((event) => (event.payload as { initiator: string }).initiator), + ).toEqual(["lease-end"]); + + const destroyFails = await restartedPhonesOnly("destroy"); + expect(destroyFails.stateOf(destroyFails.ready.id)).toBe("shutdown"); + expect(destroyFails.stateOf(destroyFails.shutdown.id)).toBe("deleted"); + expect(destroyFails.logs).toContainEqual( + expect.objectContaining({ + fields: expect.objectContaining({ deviceId: destroyFails.ready.id, platform: "android" }), + level: "warn", + message: "Could not delete an idle device at start", + }), + ); + + const shutdownFails = await restartedPhonesOnly("shutdown"); + expect(shutdownFails.stateOf(shutdownFails.ready.id)).toBe("ready"); + expect(shutdownFails.stateOf(shutdownFails.shutdown.id)).toBe("deleted"); + expect(shutdownFails.logs).toContainEqual( + expect.objectContaining({ + fields: expect.objectContaining({ deviceId: shutdownFails.ready.id, platform: "android" }), + level: "warn", + message: "Could not delete an idle device at start", + }), + ); + }); +}); diff --git a/src/leasing/create-leasing-warm-pool-virtual-devices-off.test.ts b/src/leasing/create-leasing-warm-pool-virtual-devices-off.test.ts new file mode 100644 index 000000000..f4eb8b4eb --- /dev/null +++ b/src/leasing/create-leasing-warm-pool-virtual-devices-off.test.ts @@ -0,0 +1,83 @@ +import { describe, expect, it, vi } from "vitest"; +import { FakeDriver, openTestState } from "../core/testing.js"; +import { FakeClock } from "../ports/index.js"; +import { androidRequest, createHarness, flush, request } from "./test-create-leasing.js"; + +const LIMITS = { + android: { maxDevices: 2, maxRunning: 2 }, + ios: { maxDevices: 2, maxRunning: 2 }, + maxRunning: 2, +}; + +describe("the warm pool on a worker whose android.virtualDevices is false", () => { + it("boots nothing on the platform, reports its configured target short unknown-model, forgets its learned kind, counts its reserve as 0, and fills an iOS target", async () => { + const clock = new FakeClock(1_000); + const ios = new FakeDriver({ availableOsVersions: ["26.5"], clock, platform: "ios" }); + const android = new FakeDriver({ + availableOsVersions: ["36"], + clock, + knownModels: [androidRequest.model], + platform: "android", + }); + const state = await openTestState(); + const before = await createHarness({ + drivers: [ios, android], + limits: LIMITS, + startPool: true, + state, + }); + before.bus.emit("daemon.started", { configSnapshot: {}, version: "test" }, "test"); + const learning = await before.engine.request(androidRequest, { + ownerId: "learner", + requesterId: "learner", + }); + await before.engine.release(learning.lease.id, "explicit"); + await flush(); + await before.engine.core.passWarmPool(); + expect( + before.engine.figures().targets.map((target) => [target.origin, target.platform]), + ).toContainEqual(["learned", "android"]); + before.engine.dispose(); + const androidBoots = () => + android.calls.filter((call) => ["makeReady", "provision"].includes(call.operation)).length; + const bootsBefore = androidBoots(); + + const after = await createHarness({ + drivers: [ios, android], + firstId: 5_000, + limits: LIMITS, + startPool: true, + state, + virtualDevices: { android: false }, + warmPool: { + reserveRunning: { android: 2, ios: 0 }, + targets: [ + { count: 1, model: androidRequest.model, osVersion: "36", platform: "android" }, + { count: 1, model: request.model, osVersion: "26.5", platform: "ios" }, + ], + }, + }); + await after.engine.core.passWarmPool(); + await vi.waitFor(() => + expect( + after.engine.figures().targets.find((target) => target.platform === "ios"), + ).toMatchObject({ ready: 1 }), + ); + await after.engine.settle(); + + const figures = after.engine.figures().targets; + expect(figures.find((target) => target.platform === "android")).toMatchObject({ + booting: 0, + origin: "configured", + ready: 0, + short: "unknown-model", + }); + expect(figures.filter((target) => target.platform === "android")).toHaveLength(1); + expect(figures.find((target) => target.platform === "ios")).toMatchObject({ + origin: "configured", + ready: 1, + }); + expect(figures.find((target) => target.platform === "ios")).not.toHaveProperty("short"); + expect(androidBoots()).toBe(bootsBefore); + }); +}); diff --git a/src/leasing/physical-leasing.test.ts b/src/leasing/physical-leasing.test.ts index 0d403c64a..48cf049b3 100644 --- a/src/leasing/physical-leasing.test.ts +++ b/src/leasing/physical-leasing.test.ts @@ -31,7 +31,9 @@ const virtualRequest = { function config(leaseOverrides: object = {}): TestEngineConfig { return { + android: { virtualDevices: true }, devices: { autoEnroll: false, deletedRetentionMs: 3_600_000 }, + ios: { virtualDevices: true }, health: { enabled: true, maxConcurrentRecoveries: 1, diff --git a/src/leasing/test-create-leasing.ts b/src/leasing/test-create-leasing.ts index 3bd51de74..c184be2e2 100644 --- a/src/leasing/test-create-leasing.ts +++ b/src/leasing/test-create-leasing.ts @@ -38,7 +38,9 @@ export function config( warmPool: Partial = {}, ): TestEngineConfig { return { + android: { virtualDevices: true }, devices: { autoEnroll: false, deletedRetentionMs: 3_600_000 }, + ios: { virtualDevices: true }, health: { enabled: true, maxConcurrentRecoveries: 1, @@ -121,6 +123,8 @@ export async function createHarness( readonly driver?: FakeDriver; readonly drivers?: readonly FakeDriver[]; readonly state?: StateDatabase; + /** why: the first id this process mints, so a second process on the same `state` does not mint the first one's ids. */ + readonly firstId?: number; readonly identity?: Config["lease"]["identity"]; readonly lease?: Partial; /** why: a participant holds a released device in `reclaiming` until it returns. */ @@ -137,6 +141,8 @@ export async function createHarness( readonly warmPool?: Partial; /** why: how long a ready device may idle before the pool shuts it down. */ readonly idleShutdownAfterMs?: number; + /** why: a platform a test turns `.virtualDevices` off for (ADR 0084). */ + readonly virtualDevices?: Readonly>>; /** why: starts the warm pool as the daemon's startup does, so it learns from the leases and reacts to events. */ readonly startPool?: boolean; } = {}, @@ -146,7 +152,7 @@ export async function createHarness( const bus = new EventBus(clock); const driver = options.driver ?? new FakeDriver({ availableOsVersions: ["26.5"], clock, platform: "ios" }); - let nextId = options.state === undefined ? 1 : 1_000; + let nextId = options.firstId ?? (options.state === undefined ? 1 : 1_000); const registry = await loadTestRegistry({ clock, eventBus: bus, @@ -165,7 +171,9 @@ export async function createHarness( ); const engineConfig: TestEngineConfig = { ...baseConfig, + android: { virtualDevices: options.virtualDevices?.android ?? true }, capacity: capacityConfig(baseConfig, options), + ios: { virtualDevices: options.virtualDevices?.ios ?? true }, }; const totalRamBytes = options.totalRamBytes ?? 32 * gibibyte; const drivers = options.drivers ?? [driver]; diff --git a/src/leasing/test-lease-acquisition.ts b/src/leasing/test-lease-acquisition.ts index 1aa067960..46b34322d 100644 --- a/src/leasing/test-lease-acquisition.ts +++ b/src/leasing/test-lease-acquisition.ts @@ -201,7 +201,13 @@ export async function createHarness( }); coordinator = new LeaseAcquisitionCoordinator({ baselines: options.baselines ?? { current: () => undefined }, - catalog: options.catalogReader ?? catalog, + catalog: + options.catalogReader === undefined + ? catalog + : { + listCatalog: (platform) => options.catalogReader!.listCatalog(platform), + virtualDevices: (platform) => catalog.virtualDevices(platform), + }, claims, components, decisions, diff --git a/src/leasing/test-lease-end-participants.ts b/src/leasing/test-lease-end-participants.ts index 98b68d72e..b90165633 100644 --- a/src/leasing/test-lease-end-participants.ts +++ b/src/leasing/test-lease-end-participants.ts @@ -94,7 +94,9 @@ interface EngineOptions { function config(options: EngineOptions): TestEngineConfig { const ios = options.ios ?? { maxDevices: 1, maxRunning: 1 }; return { + android: { virtualDevices: true }, devices: { autoEnroll: false, deletedRetentionMs: 3_600_000 }, + ios: { virtualDevices: true }, health: { enabled: true, maxConcurrentRecoveries: 1, diff --git a/src/leasing/test-physical-device-watcher.ts b/src/leasing/test-physical-device-watcher.ts index 5f0370a68..aa6f4ef6d 100644 --- a/src/leasing/test-physical-device-watcher.ts +++ b/src/leasing/test-physical-device-watcher.ts @@ -32,7 +32,9 @@ interface HarnessOptions { function config(options: HarnessOptions): TestEngineConfig { const quarantineBackoffMs = options.quarantineBackoffMs ?? 30_000; return { + android: { virtualDevices: true }, devices: { autoEnroll: false, deletedRetentionMs: 3_600_000 }, + ios: { virtualDevices: true }, health: { enabled: true, maxConcurrentRecoveries: 1, diff --git a/website/src/content/docs/docs/reference/configuration.mdx b/website/src/content/docs/docs/reference/configuration.mdx index 7e10a9049..6cd0a0606 100644 --- a/website/src/content/docs/docs/reference/configuration.mdx +++ b/website/src/content/docs/docs/reference/configuration.mdx @@ -209,6 +209,8 @@ The warm pool never downloads. A gateway never asks a worker to download for a l | `ios.defaultModels.` | model name, or non-empty list | not set | iOS models to try first for a class (`phone`, `tablet`, `watch`, `tv`, `vision`, `auto`, `desktop`), most preferred first, before Simlock's own list. A key that is not a class stops the daemon from starting. | Worker | | `android.defaultModels.` | model name, or non-empty list | not set | The same for Android models. | Worker | | `android.defaultImageTag` | image tag: 1 to 64 letters, digits, `_`, `.` or `-` | not set | Image tag for an Android request that names none, such as `google_apis_playstore`. The worker tries an image of that tag built for its own CPU first, never downloading, and falls back to what the request gets without the setting when none fits. See [Choose the system image](/simlock/docs/using-devices/choosing-a-device#choose-the-system-image-android). | Worker | +| `ios.virtualDevices` | `true` or `false` | `true` | `false` makes the worker serve only enrolled physical iOS devices. A lease without `--physical` is refused at once with `UNKNOWN_MODEL`, the warm pool boots no simulator, and idle simulators are deleted at start. See [Serve enrolled devices only](/simlock/docs/using-devices/physical-devices#serve-enrolled-devices-only). | Worker | +| `android.virtualDevices` | `true` or `false` | `true` | The same for Android emulators. | Worker | | `android.bootTimeoutMs` | positive number | `300000` (5 min) | Boot deadline for an Android emulator, counted from its start. A new seed boots twice, each within this time. Waiting for an emulator to exit stays at 3 minutes. | Worker | | `android.networkDevices` | boolean | `false` | `true` lets `simlock device add --platform android` enrol a phone the worker's adb server reaches over the network (`host:port` or a wireless-debugging name), and makes the worker run `adb connect` for an enrolled `host:port` phone adb no longer lists. With `devices.autoEnroll` on too, every network phone connected on the worker is enrolled. See [Android phones reached over the network](/simlock/docs/worker/enrolling-physical-devices#android-phones-reached-over-the-network). | Worker | | `android.emulator.headless` | boolean | `false` | Start emulators without a window. Needed on a machine with no display. | Worker | diff --git a/website/src/content/docs/docs/reference/errors.mdx b/website/src/content/docs/docs/reference/errors.mdx index 35ff591ce..5901c85e8 100644 --- a/website/src/content/docs/docs/reference/errors.mdx +++ b/website/src/content/docs/docs/reference/errors.mdx @@ -48,7 +48,7 @@ In a script, check `code`, not the message: the wording of a message can change, | `ADMISSION_FAILED` | 16 | 503 | The gateway's admission command could not decide: it exited non-zero, ran past `gateway.admission.timeoutMs`, printed more than 64 KiB or something that is not an answer, was killed, or could not start. The gateway refuses rather than let the request through. The message and the details (`cause`) say which. | Tell the operator: the gateway log names the cause and the command's stderr. The same request can pass once the command is fixed. | | `IDEMPOTENCY_CONFLICT` | 2 | 409 | A lease request reused an idempotency key its requester already sent for a different device, `except` list or lease ID. | Send a new key for a new request. | | `PROVISION_FAILED` | 1 | 500 | Creating or booting a device for the request failed. A device that fails to boot, by timing out or by crashing, fails the request at once, unless the request has `--except`. Any other failure is tried again once, and a request with `--except` counts a failed boot of a device it was given, warm or new, the same way. The message carries the platform tool's error. | Read the message and `simlock daemon logs`, then run `simlock doctor`. | -| `UNKNOWN_MODEL` | 12 | 422 | The model is not one this platform offers here, or no model of the requested class exists. | Run `simlock catalog` for the models and their exact names. | +| `UNKNOWN_MODEL` | 12 | 422 | The model is not one this platform offers here, no model of the requested class exists, or the worker serves only enrolled devices of the platform (`.virtualDevices` is `false`) and the request did not ask for a physical one. | Run `simlock catalog` for the models and their exact names. When the message names `.virtualDevices`, ask for a physical device: `--physical`, or `physical: true` over MCP and HTTP. | | `RUNTIME_MISSING` | 12 | 422 | The OS version, or an image of the `--image-tag`, is not installed. A range or an image tag never downloads. | Add `--allow-download`, install it with `simlock component install`, or pick an installed version from `simlock catalog`. | | `NO_DRIVER` | 12 | 422 | This machine cannot run the platform: iOS on Linux, or a platform whose tools are missing. | Run `simlock doctor` to see what is missing, install it, then restart the daemon. | | `CAPABILITY_MISSING` | 12 | 422 | No worker that could serve the request has every optional module it asks for, such as screen streaming. Only the programmatic client asks for modules. | Ask for fewer, or turn the module on for a worker under `capabilities` in its configuration. | diff --git a/website/src/content/docs/docs/reference/events.mdx b/website/src/content/docs/docs/reference/events.mdx index 5dcbe32e3..06aa06832 100644 --- a/website/src/content/docs/docs/reference/events.mdx +++ b/website/src/content/docs/docs/reference/events.mdx @@ -143,8 +143,8 @@ release and records nothing. | `device.crash-detected` | A leased device stopped running outside Simlock. | `deviceId`, `leaseId`, `platform`, `observed` | Relayed | | `device.recovered` | A crashed leased device was rebooted and the lease goes on. | `deviceId`, `leaseId`, `attempts`, `duration`, `platform` | Relayed | | `device.recovery-failed` | A crashed leased device could not be brought back; its lease ends as `device-lost`. | `deviceId`, `leaseId`, `attempts`, `reason`, `error`, `platform` | Relayed | -| `device.shutdown` | A device was shut down and kept on disk. | `deviceId`, `initiator` (who did it, such as `cleanup-reaper`, `warm-pool`, `daemon-stop` or `nuke`) | Relayed | -| `device.deleted` | A device was removed: deleted from disk, or forgotten if physical. | `deviceId`, `initiator` (such as `lease-end`, `cleanup-reaper`, `lease-engine`, `doctor`, `nuke`, `operator`, `quarantine`, `baseline-save`, `baseline-remove`, `baseline-replaced`), `physical` | Relayed | +| `device.shutdown` | A device was shut down and kept on disk. | `deviceId`, `initiator` (who did it, such as `cleanup-reaper`, `warm-pool`, `daemon-stop`, `nuke` or `virtual-devices-off`) | Relayed | +| `device.deleted` | A device was removed: deleted from disk, or forgotten if physical. | `deviceId`, `initiator` (such as `lease-end`, `cleanup-reaper`, `lease-engine`, `doctor`, `nuke`, `operator`, `quarantine`, `baseline-save`, `baseline-remove`, `baseline-replaced`, `virtual-devices-off`), `physical` | Relayed | | `device.enrolled` | A physical device was enrolled: by `simlock device add`, or by a worker with `devices.autoEnroll`. | `deviceId`, `platform`, `driverDeviceId`, `model`, `osVersion`, `class` (`phone` or `tablet`), `appCount`, `reenrolled`, `initiator` (`operator` or `auto`) | Relayed | | `device.absence-detected` | An enrolled physical device went away. | `deviceId`, `previousState` (`ready`, `leased`, `reclaiming`), `absentReason` (`locked`, `untrusted`, `not-present`) | Relayed | | `device.returned` | An absent physical device is back; it is cleaned before its next lease. | `deviceId`, `osVersion` | Relayed | diff --git a/website/src/content/docs/docs/using-devices/errors.mdx b/website/src/content/docs/docs/using-devices/errors.mdx index d4f2f2242..5cb3e6280 100644 --- a/website/src/content/docs/docs/using-devices/errors.mdx +++ b/website/src/content/docs/docs/using-devices/errors.mdx @@ -41,7 +41,7 @@ In a script, check the exit code or `code`, never the message: the message is fo | Code | Exit | What it means | What to do | | --- | --- | --- | --- | -| `UNKNOWN_MODEL` | 12 | This machine doesn't know the model, has no model listed for the class, or (with `--physical`) has no enrolled device that could ever match. | Check the spelling against `simlock catalog`. For a class, an admin can name a model in `ios.defaultModels` or `android.defaultModels`. For a physical device, remember `--os` is exact. | +| `UNKNOWN_MODEL` | 12 | This machine doesn't know the model, has no model listed for the class, has `ios.virtualDevices` or `android.virtualDevices` set to `false` and the request has no `--physical`, or (with `--physical`) has no enrolled device that could ever match. | Check the spelling against `simlock catalog`. On a phones-only worker the message names the key: ask again with `--physical`. For a class, an admin can name a model in `ios.defaultModels` or `android.defaultModels`. For a physical device, remember `--os` is exact. | | `RUNTIME_MISSING` | 12 | The OS version, or the Android image, isn't installed. An OS range or `--image-tag` never downloads. | Pass `--allow-download` for an exact version, or ask an admin to install it. See [Choosing a device](/simlock/docs/using-devices/choosing-a-device#when-the-runtime-is-not-installed). | | `UNKNOWN_BASELINE` | 12 | `--baseline` names a baseline this machine doesn't have. | Check the name with `simlock baseline list`. | | `BASELINE_MISMATCH` | 2 | `--baseline` came with a platform, model, OS, mode or image tag that differs from the baseline. The message names the first one that differs. | Drop that option: the baseline already decides it. | diff --git a/website/src/content/docs/docs/using-devices/physical-devices.mdx b/website/src/content/docs/docs/using-devices/physical-devices.mdx index 4bb01ac24..91d5f4a71 100644 --- a/website/src/content/docs/docs/using-devices/physical-devices.mdx +++ b/website/src/content/docs/docs/using-devices/physical-devices.mdx @@ -58,6 +58,26 @@ The grant is the same JSON line as for a simulator, with `device.physical` set t Physical requests have their own queue. A simulator request never waits behind a physical one, and a request for one phone model never waits behind a request for another. +## Serve enrolled devices only + +To keep a worker for real phones, set `android.virtualDevices` or `ios.virtualDevices` to `false` and restart the worker: + +```bash +simlock config set android.virtualDevices false +simlock daemon stop && simlock daemon start +``` + +From then on the worker never creates, boots or keeps an emulator (or simulator) of that platform: + +- A lease without `--physical` fails at once with `UNKNOWN_MODEL` (exit 12), whatever else it asks for. It never waits and never downloads. +- The warm pool boots nothing on that platform, and idle devices of it are deleted when the worker starts. A leased one runs to its release. Saved baselines stay. +- `simlock catalog` says virtual devices are off for the platform. +- A lease with `--physical`, the other platform and components work as before. + +```json +{"error":{"code":"UNKNOWN_MODEL","message":"This worker serves only enrolled physical android devices (android.virtualDevices is false); ask for a physical device (--physical, or physical: true)"}} +``` + ## Use the device `simlock simctl` and `simlock adb` only reach simulators and emulators. For a physical device, use the platform's own tools with the values from the grant's `environment`. diff --git a/website/src/content/docs/docs/worker/capacity.mdx b/website/src/content/docs/docs/worker/capacity.mdx index fec75583f..3bd96c955 100644 --- a/website/src/content/docs/docs/worker/capacity.mdx +++ b/website/src/content/docs/docs/worker/capacity.mdx @@ -219,13 +219,13 @@ warm pool: enabled, reserve ios 1 android 0 | --- | --- | | `disabled` | The warm pool is off (`warmPool.enabled` is `false`). | | `runtime-missing` | Install the runtime or system image. See [Runtimes and images](/simlock/docs/worker/runtimes-and-images). | -| `unknown-model` | The model does not exist on this machine. Check `simlock catalog`. | +| `unknown-model` | The model does not exist on this machine, or the platform's `.virtualDevices` is `false`. Check `simlock catalog`. | | `unresolvable` | No device can be created for it. Check its OS version and mode. | | `no-driver` | The platform's tools are missing. Run `simlock doctor`. | | `boot-failed` | The last boot failed, or did not finish within `ios.full.bootTimeoutMs`, `ios.slim.bootTimeoutMs` or `android.bootTimeoutMs`. Simlock tries again later. Check `simlock daemon logs`. | | `running-limit` | No running slot is free. Raise the running limits or lower `count`. | | `device-limit` | The platform is at its device limit. | -| `reserve` | The slot is held back by `warmPool.reserveRunning`. | +| `reserve` | The slot is held back by `warmPool.reserveRunning`. A platform with `.virtualDevices` set to `false` holds none. | | `ram-budget` | The device would not fit in the RAM budget. | | `memory-pressure` | The host is short of memory and warming is paused (`memoryPressure.*`). | diff --git a/website/src/content/docs/docs/worker/troubleshooting.mdx b/website/src/content/docs/docs/worker/troubleshooting.mdx index 4c07c3afd..998db66a6 100644 --- a/website/src/content/docs/docs/worker/troubleshooting.mdx +++ b/website/src/content/docs/docs/worker/troubleshooting.mdx @@ -58,7 +58,7 @@ Service broken: com.callstack.simlock.worker (launchd) names missing /Users/dana | `foreign-provenance-change` | A device no longer carries the marks that show Simlock made it, for example after it was erased by hand. | Nothing. Check the device; delete it if it is not yours. | | `orphan-device` | A device sits in Simlock's device folder with no record. | Nothing. See [Orphaned devices](#orphaned-devices). | | `orphan-process` | A simulator or emulator is running that Simlock has no record of. | Nothing. | -| `warm-pool-target-unreachable` | A warm pool target can never be filled: its runtime is not installed, its model is unknown, or it asks for more than capacity allows. | Nothing. Install the runtime or change the target. | +| `warm-pool-target-unreachable` | A warm pool target can never be filled: its runtime is not installed, its model is unknown, its platform's `.virtualDevices` is `false`, or it asks for more than capacity allows. | Nothing. Install the runtime, change the target, or remove it or set the key to `true`. | | `driver-unavailable` | A platform's driver was refused at start, so the platform is off. The finding carries the `reason` (such as `invalid-device-set` or `device-set-changed`) and a `detail` that says what to run; `simlock doctor` also prints it as `Unavailable [] : ` on stderr. | Nothing. Fix it, then restart the daemon. | | `driver-advisory` | A platform tool reported something worth knowing that is not a fault. The code is in the message; see [`default-image-tag-not-installed`](#default-image-tag-not-installed). | Nothing. | | `module-unavailable` | An optional feature that is turned on cannot run on this machine. The remedy says why. | Nothing. |