Skip to content

Commit c96a2d5

Browse files
authored
docs: slim remote device leases ADR (#4277)
* docs: preserve remote lease contracts in daemon docs * docs: slim remote device lease decision record * docs: restore lease contract ownership and scope * docs: restore lease specification and heartbeat contracts * docs: preserve proxy recovery constraint
1 parent df4c114 commit c96a2d5

11 files changed

Lines changed: 347 additions & 354 deletions

File tree

‎docs/adr/0007-remote-device-leases.md‎

Lines changed: 51 additions & 345 deletions
Large diffs are not rendered by default.

‎packages/command-registry/src/daemon-command-descriptor.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ export type DaemonCommandDescriptor<TRequest = DispatchedCommand> = {
3939
refFrameEffect?: DaemonRefFrameEffect<TRequest>;
4040
leaseAdmissionExempt?: boolean;
4141
/**
42-
* ADR 0007: this command may run under a `macos-app` lease, or on a daemon whose policy requires
42+
* packages/daemon/docs/remote-device-lease-contracts.md: this command may run under a `macos-app` lease, or on a daemon whose policy requires
4343
* one. A command without it is refused there, `leaseAdmissionExempt` or not, so a command
4444
* added later stays out until it opts in.
4545
*/
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Lease device specifications
2+
3+
A proxy lease can name a device spec beside platform, target, and device: `osVersion`, `imageTag`, `deviceMode`, and `physical` on `agent_device.lease.allocate`.
4+
Only a backend in front of the daemon, such as simlock, can pick a device by these keys.
5+
A daemon cannot pick by them.
6+
If a daemon ignored them, a request would run on a device that it did not ask for.
7+
Thus, a daemon refuses every request that names a non-blank `osVersion`, `imageTag` or `deviceMode`, or `physical: true`, before admission and before a lease is recorded.
8+
The refusal is `UNSUPPORTED_OPERATION` with `details.reason: 'device-spec-unsupported'` and `details.keys`.
9+
This applies to a local daemon and to a daemon behind `agent-device proxy`.
10+
A blank `osVersion`, `imageTag` or `deviceMode` and `physical: false` name nothing, so a daemon accepts them.
11+
`deviceMode` (`slim` or `full`) chooses how much of an iOS simulator the backend keeps running; the backend validates the value.
12+
A named value is used as given, without trimming.
13+
A value of another type is refused with `INVALID_ARGS`, `details.reason: 'device-spec-invalid'`, and `details.keys`.
14+
`readLeaseDeviceSpec` is the one decision on these rules, for CLI flags, the SDK, MCP, and the daemon.
15+
A remote config file first applies the value rules of every config key: a string must be non-empty, and a boolean also accepts a boolean string such as `"true"`.
16+
The backend that honours the spec strips the keys before it forwards the allocation, and echoes the granted device on the lease as `lease.device` (`model`, `osVersion`, `imageTag?`, `deviceMode?`, `physical`).
17+
`deviceKey` stays the identity of the lease; `lease.device` is the proof that the spec was understood.
18+
The CLI proxy applies the returned-device checks in [`src/cli/commands/proxy-lease-device.ts`](../../../src/cli/commands/proxy-lease-device.ts).
19+
For a spec request, if a new lease has no `lease.device`, the CLI proxy releases the lease and fails with `UNSUPPORTED_OPERATION` and `details.reason: 'device-spec-unsupported'`.
20+
If the release returns, the error's `details.released` reports its result.
21+
If the release fails, `details.leaseRollback` records the failure.
22+
If the allocation explicitly reports reuse (`created: false`), the CLI proxy returns the same error without a release or `details.released`.
23+
For a `full` request, a reported `slim` grant has the same result as a missing `lease.device`.
24+
For a `slim` request, a `full` grant is accepted.
25+
A lease that reports no mode is accepted, but the mode is not confirmed.
26+
For a later command on a live lease, every spec key the command names must equal the value used to allocate the lease.
27+
If a named key differs, the command fails with `CONNECTION_DEVICE_CONFLICT`.
28+
A key the command omits keeps the lease's value.
Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Client lease heartbeats
2+
3+
## Client-side work that precedes admission
4+
5+
The [protection of admitted work](../../daemon/docs/remote-device-lease-contracts.md#admitted-request-work) covers nothing that happens before a request is admitted.
6+
An artifact install uploads the artifact from the caller before the request that will consume it is admitted.
7+
Thus, an upload slower than the inactivity window of the lease expired the lease that paid for the target device of the bytes (#2946).
8+
The caller therefore sends lease heartbeats over the ordinary transport for as long as that phase runs.
9+
Each heartbeat names the lease scope exactly as the command named it, and carries no payload of its own.
10+
An install names no window, so its heartbeats renew for the window that the lease already carries.
11+
A caller that did name a window continues to renew on that window.
12+
13+
The first heartbeat is sent when the phase starts, not one cadence later.
14+
The reason is that a heartbeat proves that the lease on which the upload spends time is still alive.
15+
Otherwise, a lease shorter than any fixed cadence would lapse before anything renewed it.
16+
A lease that is already gone is caught early, but not before the phase begins.
17+
Hashing, the preflight, and the start of the stream can all run while the first heartbeat is still outstanding.
18+
Thus, the first heartbeat makes sure that the loss is learned during the upload instead of after it.
19+
Each heartbeat answers with the window that it just renewed.
20+
The loop arms the next heartbeat when the current heartbeat starts, not when it settles.
21+
Thus, a heartbeat that never answers is abandoned on schedule and does not stop the schedule.
22+
A phase that settles does not wait for a heartbeat still in flight.
23+
24+
Cadence and budget are deliberately two numbers.
25+
A heartbeat is armed every third of the window, but it is allowed the whole window to answer.
26+
If the budget were equal to the cadence, a heartbeat that needs more than a third of a window for its round trip could never answer.
27+
Examples are a tunneled proxy and an uplink that the upload itself saturates.
28+
Every heartbeat would then time out again on exactly the slow links that the heartbeat exists to protect.
29+
The window, not the cadence, is the interval in which liveness still matters.
30+
Thus, the window is also the longest time that an answer to a heartbeat is worth a wait.
31+
32+
That ceiling is the shorter of the window and the heartbeat's own request policy, currently ninety seconds.
33+
Thus, a ten-minute lease gives a heartbeat ninety seconds instead of the full window.
34+
This limit costs nothing that the heartbeat exists to provide.
35+
The daemon renews the lease when it handles the request, before it answers.
36+
Thus, a round trip abandoned at the cap has still extended the lease if the request ever arrived.
37+
If the request never arrived, the transport has stopped carrying traffic.
38+
A socket held open for the rest of a window measured in minutes does not help that transport.
39+
The cap refuses exactly that idle hold.
40+
The cap binds only on windows longer than the policy.
41+
On those windows, the heartbeat already has the longest answer deadline that any lease gets.
42+
Shorter windows are bounded by their own window, as above.
43+
44+
A heartbeat is a fresh request each time, never the protected request rewritten.
45+
The reason is that a timed-out heartbeat is canceled under its request identity, and heartbeats must not inherit each other's cancellation.
46+
In these cases, a heartbeat ends the phase with that error and cancels the upload:
47+
48+
- The heartbeat returns `UNAUTHORIZED` with `LEASE_NOT_FOUND`, `LEASE_EXPIRED`, or `LEASE_REVOKED`.
49+
- The heartbeat returns `COMMAND_FAILED` with `provider-instance-ended`.
50+
- The heartbeat returns an `AppError` with `LEASE_SCOPE_REQUIRED` or `LEASE_SCOPE_MISMATCH`.
51+
- The heartbeat returns an `AppError` with code `INVALID_ARGS`.
52+
53+
When the provider reports `provider-instance-ended`, the daemon ends the lease and its sessions.
54+
A failed session teardown does not replace that typed reason.
55+
56+
Thus, the upload does not finish bytes against a device that nobody owns or a lease that will stop renewing.
57+
A heartbeat that fails for any other reason is reported, and the phase continues.
58+
The reason is that a later heartbeat covers one lost request.
59+
This includes a request abandoned at its budget instead of answered.
60+
Thus, that promise holds for a stalled round trip, not only for a round trip that fails fast.

‎packages/daemon-client/src/daemon-client-lease-beat.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,10 @@ import { sendRequest } from './daemon-client-transport.ts';
1919
// The lease beat: what keeps a remote lease alive across a client-side phase the daemon never sees.
2020
//
2121
// A lease renews when a request is admitted, and the daemon protects a lease while admitted work runs
22-
// on it (#2509, ADR 0007). An artifact upload is the mirror image: it runs on the caller's side,
22+
// on it (#2509, packages/daemon/docs/remote-device-lease-contracts.md). An artifact upload is the mirror image: it runs on the caller's side,
2323
// before the install that consumes it is admitted, so nothing renews the lease while it runs and a
2424
// large enough artifact expired the lease that was paying for the device it was being uploaded to
25-
// (#2946). This module owns the answer — a beat with a budget that ends before the window does — and
25+
// (#2946, packages/daemon-client/docs/remote-device-leases.md). This module owns the answer — a beat with a budget that ends before the window does — and
2626
// knows nothing about transports beyond the `send` it is handed.
2727

2828
/**
@@ -71,10 +71,10 @@ function isTerminalLeaseBeatError(error: unknown): boolean {
7171
* Runs one client-side phase under a lease it does not own the clock of.
7272
*
7373
* A lease renews when a request is admitted, and the daemon protects a lease while ADMITTED work
74-
* runs on it (#2509, ADR 0007). An artifact upload is the mirror image: it happens on the caller's
74+
* runs on it (#2509, packages/daemon/docs/remote-device-lease-contracts.md). An artifact upload is the mirror image: it happens on the caller's
7575
* side, before the install request that will consume it is admitted, so nothing renews the lease
7676
* while it runs and a large enough artifact expired the lease that was paying for the device it was
77-
* being uploaded to (#2946).
77+
* being uploaded to (#2946, packages/daemon-client/docs/remote-device-leases.md).
7878
*
7979
* `heartbeat` is the caller's transport decision; `undefined` means there is no lease to protect and
8080
* the phase runs untouched. The first beat is fired immediately rather than one interval in, so a

0 commit comments

Comments
 (0)