Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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)
Expand Down
2 changes: 1 addition & 1 deletion docs/internal/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
33 changes: 33 additions & 0 deletions src/gateway/aggregate-catalog.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
39 changes: 26 additions & 13 deletions src/gateway/aggregate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -221,6 +221,8 @@ interface CatalogBucket {
/** Models any worker that lists them marks custom. */
readonly customModels: Set<string>;
readonly slimCategories: Set<string>;
/** why: ADR 0084 §3: stays true only while every worker reporting the platform says `virtualDevices: false`. */
phonesOnly: boolean;
readonly defaults: Set<string | undefined>;
/** why: absent ones count as `undefined`, so one worker without a default image tag is a disagreement (ADR 0078 §3). */
readonly imageTagDefaults: Set<string | undefined>;
Expand Down Expand Up @@ -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<string>(),
defaults: new Set<string | undefined>(),
Expand All @@ -263,20 +286,9 @@ function addCatalogEntry(
modelRuntimes: new Map<string, Set<string>>(),
models: new Map<string, string[]>(),
runtimes: new Map<string, string[]>(),
phonesOnly: true,
slimCategories: new Set<string>(),
};
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));
}

/**
Expand Down Expand Up @@ -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 }),
};
Expand Down
115 changes: 115 additions & 0 deletions src/gateway/fleet-routing-phones-only.test.ts
Original file line number Diff line number Diff line change
@@ -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<typeof catalogFixture>[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);
}
});
});
20 changes: 20 additions & 0 deletions src/gateway/routing/serviceability.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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 <platform> …"), 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",
Expand Down
4 changes: 3 additions & 1 deletion website/src/content/docs/docs/gateway/routing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<platform>.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
Expand Down Expand Up @@ -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 `<platform>.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`. |
Expand Down
Loading