diff --git a/docs/internal/adr/0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md b/docs/internal/adr/0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md index ec3232299..b0f0f9032 100644 --- a/docs/internal/adr/0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md +++ b/docs/internal/adr/0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md @@ -1,6 +1,6 @@ # 0084. A worker may serve a platform's enrolled phones only -- **Status:** Accepted — not yet implemented +- **Status:** Accepted - **Date:** 2026-11-16 - **Issue:** [#1588](https://github.com/callstackincubator/simlock/issues/1588) (request [#1181](https://github.com/callstackincubator/simlock/issues/1181)) - **Narrows:** [ADR 0022](0022-a-physical-device-is-a-second-device-type-the-core-knows.md) diff --git a/docs/internal/adr/README.md b/docs/internal/adr/README.md index 62b056c8a..4743b1dcd 100644 --- a/docs/internal/adr/README.md +++ b/docs/internal/adr/README.md @@ -115,4 +115,4 @@ the status is stale. | [0078](0078-an-android-worker-tries-its-default-image-tag-first-and-falls-back-to-none.md) | An Android worker tries its default image tag first, and a lease falls back to none | Accepted | | [0079](0079-one-capture-per-device-is-shared-by-every-viewer-and-every-capture-sends-a-key-frame-every-5-s.md) | One capture per device is shared by every viewer, and every capture sends a key frame at least every 5 s | Accepted; narrows 0045 §5 | | [0080](0080-an-android-worker-may-enrol-phones-reached-over-the-network.md) | An Android worker may enrol phones reached over the network | Accepted; narrows 0022 §6 and §7, and 0073 §2 and §5 | -| [0084](0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md) | A worker may serve a platform's enrolled phones only | Accepted — not yet implemented; narrows 0022 and 0009 §4 | +| [0084](0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md) | A worker may serve a platform's enrolled phones only | Accepted; narrows 0022 and 0009 §4 | diff --git a/src/gateway/aggregate-catalog.test.ts b/src/gateway/aggregate-catalog.test.ts index 97771f7a8..94270c527 100644 --- a/src/gateway/aggregate-catalog.test.ts +++ b/src/gateway/aggregate-catalog.test.ts @@ -60,6 +60,39 @@ describe("aggregateCatalog", () => { }); }); + it("says virtualDevices false for a platform only when every worker reporting it says so, and lists the emulator worker's models otherwise", () => { + const phonesOnly = { + ...iosOnA, + classDefaults: {}, + modelClasses: {}, + modelRuntimes: {}, + models: [], + runtimes: [], + virtualDevices: false as const, + }; + + const allOff = aggregateCatalog([ + view({ catalog: [phonesOnly], id: "wrk_a" }), + view({ catalog: [phonesOnly], id: "wrk_b" }), + ]); + const mixed = aggregateCatalog([ + view({ catalog: [phonesOnly], id: "wrk_a" }), + view({ catalog: [iosOnA], id: "wrk_b" }), + ]); + const mixedEmulatorFirst = aggregateCatalog([ + view({ catalog: [iosOnA], id: "wrk_a" }), + view({ catalog: [phonesOnly], id: "wrk_b" }), + ]); + + expect(allOff.platforms[0]).toMatchObject({ models: [], virtualDevices: false }); + expect(mixed.platforms[0]).toMatchObject({ models: ["iPhone 17"], runtimes: ["26.0"] }); + expect(mixed.platforms[0]).not.toHaveProperty("virtualDevices"); + expect(mixedEmulatorFirst.platforms[0]).toMatchObject({ models: ["iPhone 17"] }); + expect(mixedEmulatorFirst.platforms[0]).not.toHaveProperty("virtualDevices"); + expect(() => OPERATIONS["catalog.get"].output.parse(allOff)).not.toThrow(); + expect(() => OPERATIONS["catalog.get"].output.parse(mixed)).not.toThrow(); + }); + it("carries the union of the workers' slim categories, and no default mode", () => { const slimming = (slimCategories: string[], defaultMode: "slim" | "full") => ({ ...iosOnA, diff --git a/src/gateway/aggregate.ts b/src/gateway/aggregate.ts index a85199d10..5cdf74d9c 100644 --- a/src/gateway/aggregate.ts +++ b/src/gateway/aggregate.ts @@ -221,6 +221,8 @@ interface CatalogBucket { /** Models any worker that lists them marks custom. */ readonly customModels: Set; readonly slimCategories: Set; + /** why: ADR 0084 §3: stays true only while every worker reporting the platform says `virtualDevices: false`. */ + phonesOnly: boolean; readonly defaults: Set; /** why: absent ones count as `undefined`, so one worker without a default image tag is a disagreement (ADR 0078 §3). */ readonly imageTagDefaults: Set; @@ -252,7 +254,28 @@ function addCatalogEntry( entry: PlatformCatalog, workerId: string, ): void { - const bucket = byPlatform.get(entry.platform) ?? { + const bucket = byPlatform.get(entry.platform) ?? emptyBucket(); + byPlatform.set(entry.platform, bucket); + addNames(bucket, entry, workerId); + addModelClasses(bucket.modelClasses, entry); + addCustomModels(bucket.customModels, entry); + bucket.phonesOnly &&= entry.virtualDevices === false; + for (const category of entry.slimCategories ?? []) bucket.slimCategories.add(category); + if (entry.images !== undefined) bucket.images = addImages(bucket.images, entry, entry.images); + bucket.defaults.add(entry.defaultRuntime); + bucket.imageTagDefaults.add(entry.defaultImageTag); + bucket.classDefaults.push(listedClassDefaults(entry)); +} + +function addNames(bucket: CatalogBucket, entry: PlatformCatalog, workerId: string): void { + for (const model of entry.models) annotate(bucket.models, model, workerId); + for (const runtime of entry.runtimes) annotate(bucket.runtimes, runtime, workerId); + for (const model of entry.models) addPairings(bucket.modelRuntimes, entry, model); + for (const model of entry.models) addAliases(bucket.modelAliases, entry, model); +} + +function emptyBucket(): CatalogBucket { + return { classDefaults: [], customModels: new Set(), defaults: new Set(), @@ -263,20 +286,9 @@ function addCatalogEntry( modelRuntimes: new Map>(), models: new Map(), runtimes: new Map(), + phonesOnly: true, slimCategories: new Set(), }; - byPlatform.set(entry.platform, bucket); - for (const model of entry.models) annotate(bucket.models, model, workerId); - for (const runtime of entry.runtimes) annotate(bucket.runtimes, runtime, workerId); - for (const model of entry.models) addPairings(bucket.modelRuntimes, entry, model); - for (const model of entry.models) addAliases(bucket.modelAliases, entry, model); - addModelClasses(bucket.modelClasses, entry); - addCustomModels(bucket.customModels, entry); - for (const category of entry.slimCategories ?? []) bucket.slimCategories.add(category); - if (entry.images !== undefined) bucket.images = addImages(bucket.images, entry, entry.images); - bucket.defaults.add(entry.defaultRuntime); - bucket.imageTagDefaults.add(entry.defaultImageTag); - bucket.classDefaults.push(listedClassDefaults(entry)); } /** @@ -416,6 +428,7 @@ function renderPlatform(platform: Platform, bucket: CatalogBucket): PlatformCata .sort() .slice(0, CATALOG_LIST_LIMITS.slimCategories), }), + ...(bucket.phonesOnly ? { virtualDevices: false as const } : {}), ...(agreedDefault === undefined ? {} : { defaultRuntime: agreedDefault }), ...(agreedImageTag === undefined ? {} : { defaultImageTag: agreedImageTag }), }; diff --git a/src/gateway/fleet-routing-phones-only.test.ts b/src/gateway/fleet-routing-phones-only.test.ts new file mode 100644 index 000000000..1d2165ac5 --- /dev/null +++ b/src/gateway/fleet-routing-phones-only.test.ts @@ -0,0 +1,115 @@ +import { describe, expect, it } from "vitest"; + +import { buildFleet, requestOptions } from "./test-fleet.js"; +import { + catalogFixture, + grantFixture, + physicalDeviceFixture, + ScriptedWorkerClient, + statusFixture, +} from "./test-support.js"; +import type { WorkerRegistry } from "./worker-registry.js"; + +type Entry = Parameters[0][number]; + +const PHONES_ONLY = (platform: "android" | "ios"): Entry => ({ + models: [], + platform, + runtimes: [], + virtualDevices: false, +}); +const EMULATORS = (platform: "android" | "ios"): Entry => ({ + models: [platform === "ios" ? "iPhone 17" : "Pixel 9"], + platform, + runtimes: [platform === "ios" ? "26.0" : "36"], +}); + +function connect(workers: WorkerRegistry, id: string, entry: Entry, physical = false): void { + workers.connected(id, undefined, "0.3.0"); + workers.refresh(id, { + capacity: statusFixture().capacity, + catalog: catalogFixture([entry]).platforms, + devices: physical ? [physicalDeviceFixture("dev_p", "ready", { model: "iPhone 15 Pro" })] : [], + downloads: { policy: "on-request" }, + health: "running", + leases: [], + queueDepth: 0, + }); +} + +// why: the gateway's answer to a plain lease must match the worker's (ADR 0084 §3), so the cases run through the coordinator, which routes with `assess` and `select`. +describe("FleetLeaseCoordinator with phones-only workers (ADR 0084 §3)", () => { + const PLAIN = { model: "iPhone 17", platform: "ios" as const }; + const PHYSICAL = { physical: true as const, platform: "ios" as const }; + + it.each([ + { + name: "one phones-only worker: the phones-only refusal", + refused: + "Every worker with ios serves only enrolled physical ios devices " + + "(ios.virtualDevices is false); ask for a physical device (--physical, or physical: true)", + request: PLAIN, + workers: [["wrk_a", PHONES_ONLY("ios")]] as const, + }, + { + name: "a worker without the platform beside a phones-only one: still the phones-only refusal", + refused: + "Every worker with android serves only enrolled physical android devices " + + "(android.virtualDevices is false); ask for a physical device (--physical, or physical: true)", + request: { model: "Pixel 9", platform: "android" as const }, + workers: [ + ["wrk_a", EMULATORS("ios")], + ["wrk_b", PHONES_ONLY("android")], + ] as const, + }, + { + name: "a phones-only worker and an emulator worker: the emulator worker", + request: { model: "Pixel 9", platform: "android" as const }, + served: "wrk_b", + workers: [ + ["wrk_a", PHONES_ONLY("android")], + ["wrk_b", EMULATORS("android")], + ] as const, + }, + { + name: "a phones-only worker and a worker without the field: the second", + request: PLAIN, + served: "wrk_b", + workers: [ + ["wrk_a", PHONES_ONLY("ios")], + ["wrk_b", EMULATORS("ios")], + ] as const, + }, + { + name: "one worker without the field and no models: the generic UNKNOWN_MODEL", + refused: "Unknown ios model: iPhone 17", + request: PLAIN, + workers: [["wrk_a", { models: [], platform: "ios", runtimes: [] } satisfies Entry]] as const, + }, + { + name: "--physical to the phones-only worker: granted", + request: PHYSICAL, + served: "wrk_a", + workers: [["wrk_a", PHONES_ONLY("ios")]] as const, + }, + ])("through a gateway, $name", async ({ request, workers, ...expected }) => { + const fleet = buildFleet(); + for (const [id, entry] of workers) { + const client = new ScriptedWorkerClient(); + client.requestLeaseQueue.push({ grant: grantFixture(), kind: "grant" }); + fleet.directory.add(id, client); + connect(fleet.workers, id, entry, "physical" in request); + } + + const outcome = fleet.coordinator.request(request, requestOptions({ noWait: true })); + + if ("refused" in expected) { + await expect(outcome).rejects.toMatchObject({ + code: "UNKNOWN_MODEL", + message: expected.refused, + }); + } else { + expect((await outcome).lease.worker?.id).toBe(expected.served); + } + }); +}); diff --git a/src/gateway/routing/serviceability.ts b/src/gateway/routing/serviceability.ts index 8db613c80..446f887df 100644 --- a/src/gateway/routing/serviceability.ts +++ b/src/gateway/routing/serviceability.ts @@ -221,6 +221,7 @@ function assessLeading( reason: "unresolvable-spec", }; } + if (phonesOnlyEverywhere(known, request)) return phonesOnly(request); if (!known.some((worker) => listsModel(worker, request))) return unknownModel(request); if (!known.some((worker) => matchRequest(worker, request) !== undefined)) { const osVersion = request.osVersion ?? "default"; @@ -276,6 +277,25 @@ function unknownModel(request: RoutableRequest): Rejection { }; } +// why: ADR 0084 §3: a plain request is refused with the phones-only message only when every known worker that has the platform says `virtualDevices: false`. +function phonesOnlyEverywhere(known: readonly WorkerView[], request: RoutableRequest): boolean { + return known + .filter((worker) => hasPlatform(worker, request)) + .every((worker) => catalogOf(worker, request)?.virtualDevices === false); +} + +// why: ADR 0084 §3 and the issue's I3 word the gateway's refusal for the fleet ("Every worker with …"), unlike the single worker's "This worker serves only…" in `VirtualDevicesOffError`. +function phonesOnly(request: RoutableRequest): Rejection { + const { platform } = request; + return { + ...unknownModel(request), + message: + `Every worker with ${platform} serves only enrolled physical ${platform} devices ` + + `(${platform}.virtualDevices is false); ask for a physical device ` + + "(--physical, or physical: true)", + }; +} + function noWorker(): Rejection { return { code: "NO_CAPACITY", diff --git a/website/src/content/docs/docs/gateway/routing.mdx b/website/src/content/docs/docs/gateway/routing.mdx index 2de123cd7..58b2aad53 100644 --- a/website/src/content/docs/docs/gateway/routing.mdx +++ b/website/src/content/docs/docs/gateway/routing.mdx @@ -27,6 +27,8 @@ Among those workers, the gateway prefers: A request for a physical device goes only to a worker with a matching enrolled device that is free now. If none is free, the request waits. +A worker can serve only a platform's enrolled physical devices (its `.virtualDevices` is `false`). A request without `--physical` skips such a worker, and goes to one that still makes simulators or emulators. When every worker with the platform is like that, the request is refused with `UNKNOWN_MODEL`, and a message that tells the agent to ask for a physical device. `simlock --gateway catalog` shows virtual devices off for a platform only when every worker reporting it says so. + A worker can still turn a request down, for example because an agent on that machine took the last free slot a moment earlier. The gateway then tries another worker, or puts the request back in the fleet queue. ## When every worker is busy: the fleet queue @@ -88,7 +90,7 @@ The gateway doesn't queue a request that no worker could serve. It fails at once | --- | --- | --- | --- | --- | | `NO_CAPACITY` | 11 | 503 | Workers could serve it, but none is connected and taking requests: they are all disconnected, drained or incompatible. | Bring a worker back, or undrain one. | | `NO_DRIVER` | 12 | 422 | No worker supports the platform, for example no worker has Android tools. | Add a worker that has the platform. | -| `UNKNOWN_MODEL` | 12 | 422 | No worker offers that model or device class, or, for a physical device, no worker has one enrolled. | Check the name with `simlock --gateway catalog`. | +| `UNKNOWN_MODEL` | 12 | 422 | No worker offers that model or device class, or, for a physical device, no worker has one enrolled. Also when every worker with the platform serves only enrolled physical devices and the request didn't ask for one. | Check the name with `simlock --gateway catalog`. When the message names `.virtualDevices`, ask for a physical device with `--physical`. | | `RUNTIME_MISSING` | 12 | 422 | Workers offer the model, but none has a matching OS version installed. The gateway never downloads one. | Install it on the workers. See [Install runtimes and images on workers](/simlock/docs/gateway/managing-workers#install-runtimes-and-images-on-workers). | | `CAPABILITY_MISSING` | 12 | 422 | No worker that could serve the request has the optional capability it needs turned on. | Turn the capability on for a worker. | | `BAD_REQUEST` | 2 | 400 | The request names `except` categories, and no worker slims all of them, or none would give a slim device (every worker's default mode is `full` and the request names no mode, or the baseline is `full`). | Name categories the workers slim (`ios.slim.categories`), pass `--mode slim`, or set `ios.defaultMode` to `slim`. |