Skip to content

Commit 7a0cc02

Browse files
docs(remote): say only the host ends a macos-app lease
1 parent 1163b7a commit 7a0cc02

3 files changed

Lines changed: 12 additions & 14 deletions

File tree

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

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -173,16 +173,18 @@ A `macos-app` lease's device key is a bundle id, optionally pinned to one proces
173173
only a host administrator allocates one, over the loopback `/admin/leases` route that uses the daemon
174174
token like host holds; tenant `lease_allocate` refuses the backend. The host picks the lease id, a
175175
repeated PUT renews it, and a PUT naming another scope for an existing id is refused rather than
176-
rewritten. Heartbeat, expiry, release, and the loss on daemon restart are those of any lease, except
177-
that a tenant heartbeat or request cannot renew it for longer than the window of the host's last PUT.
176+
rewritten. Heartbeat, expiry, and the loss on daemon restart are those of any lease, except that a
177+
tenant heartbeat or request cannot renew it for longer than the window of the host's last PUT, and
178+
only the host ends it: `DELETE /admin/leases`, expiry, or `close` when `retainOnClose` is false. A
179+
tenant `lease_release` is refused with `MACOS_APP_LEASE_HOST_OWNED`.
178180

179181
Request admission confines every request admitted under the lease, so `batch` steps and `replay`
180182
actions are confined when they re-enter it: an allow list of commands, the ones whose command
181183
registry descriptor declares `appLease: 'allowed'` (later commands are refused, and of the commands
182184
lease admission otherwise exempts only `lease_heartbeat` and `lease_release` declare it),
183185
`open` and `close` of the leased bundle only, the `app` surface only, window-only screenshots, no
184186
input that names a host path or launches beside the app, and an existing session that is the leased
185-
app for every request but `open`, the `batch` envelope, and the lease's heartbeat and release, so a
187+
app for every request but `open`, the `batch` envelope, and the lease's heartbeat, so a
186188
request naming no session cannot fall back to the host Mac. `open` requires the native app backend (ADR 0031), because XCTest
187189
posts screen events that can land outside the app's window. A pid-pinned lease is checked against the
188190
running process before each admitted request. A session opened under the lease holds its app, not

‎src/daemon/macos-app-lease.ts‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -38,14 +38,9 @@ export function parseMacOsAppLeaseKey(deviceKey: string | undefined): MacOsAppLe
3838

3939
/**
4040
* The requests that run without the leased app's session: `open` creates it, each `batch` step is
41-
* admitted again when it runs, and a heartbeat acts on the lease alone, and a release is refused (the host ends the lease).
41+
* admitted again when it runs.
4242
*/
43-
const SESSIONLESS_COMMANDS: ReadonlySet<string> = new Set([
44-
'open',
45-
'batch',
46-
'lease_heartbeat',
47-
'lease_release',
48-
]);
43+
const SESSIONLESS_COMMANDS: ReadonlySet<string> = new Set(['open', 'batch']);
4944

5045
type MacOsAppLeaseRule =
5146
| 'command'

‎website/docs/docs/remote-proxy.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -141,9 +141,10 @@ The lease id is 16 to 128 hex characters the host chooses. Repeating the PUT ren
141141
that names another scope for an existing id is refused. The lease stays allocated across the
142142
client's `close` unless the body sets `retainOnClose: false`, and DELETE revokes it at once. It
143143
expires after `ttlMs` without a renewal or a client request, like any lease. A client heartbeat can
144-
shorten that window but never extend it past the `ttlMs` of the last PUT. A client cannot release
145-
it: `disconnect` drops only its local connection state, and a tenant `lease_release` is refused
146-
with `MACOS_APP_LEASE_HOST_OWNED`.
144+
shorten that window but never extend it past the `ttlMs` of the last PUT. Only the host ends
145+
the lease: `DELETE /admin/leases`, expiry, or `close` when `retainOnClose` is false. A client cannot
146+
release it: `disconnect` drops only its local connection state, and a tenant `lease_release` is
147+
refused with `MACOS_APP_LEASE_HOST_OWNED`.
147148

148149
The client connects with a remote config that names the lease, and runs `open <bundleId>`:
149150

@@ -164,7 +165,7 @@ The client connects with a remote config that names the lease, and runs `open <b
164165

165166
Requests under a `macos-app` lease are limited to `open`, `close`, `snapshot`, `wait`,
166167
`find`, `get`, `is`, `click`, `fill`, `press`, `type`, `focus`, `scroll`, `screenshot`, and `batch`,
167-
plus the lease's own heartbeat and release; `doctor`, `devices`, `session list` and the other
168+
plus the lease's own heartbeat; `doctor`, `devices`, `session list` and the other
168169
inventory commands are refused too.
169170
`open` and `close` accept only the leased bundle id, only the `app` surface is allowed, screenshots
170171
capture only the app window, inputs that name a host path or a launch (`--save-script`,

0 commit comments

Comments
 (0)