Repository navigation
Expand file tree
/
Copy pathlease-scope.ts
More file actions
353 lines (322 loc) · 11 KB
/
Copy pathlease-scope.ts
File metadata and controls
353 lines (322 loc) · 11 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
import type { LeaseBackend } from '@agent-device/kernel/contracts';
import { stripUndefined } from '@agent-device/kernel/record';
import type { CloudProviderProfileFields } from './remote-config-fields.ts';
import type { CommandFlags } from './command-flags.ts';
const PROXY_LEASE_PROVIDER = 'proxy';
const REQUIRED_PROXY_LEASE_FIELDS = [
'leaseId',
'tenantId',
'runId',
'clientId',
'deviceKey',
] as const satisfies readonly (keyof LeaseScope)[];
export type LeaseScope = {
tenantId?: string;
runId?: string;
leaseId?: string;
leaseTtlMs?: number;
leaseBackend?: LeaseBackend;
leaseProvider?: string;
deviceKey?: string;
clientId?: string;
};
export type LeaseDiagnosticsContext = Omit<LeaseScope, 'leaseTtlMs'>;
export type LeaseRpcCommand = 'lease_allocate' | 'lease_heartbeat' | 'lease_release';
export type LeaseAllocateRequestScope = {
tenantId: string;
runId: string;
leaseBackend?: LeaseBackend;
leaseProvider?: string;
deviceKey?: string;
clientId?: string;
ttlMs?: number;
};
export type LeaseScopedRequestScope = {
leaseId: string;
tenantId?: string;
runId?: string;
leaseBackend?: LeaseBackend;
leaseProvider?: string;
deviceKey?: string;
clientId?: string;
ttlMs?: number;
};
type LeaseRequestLike = {
flags?: Record<string, unknown>;
meta?: {
tenantId?: string;
runId?: string;
leaseId?: string;
leaseTtlMs?: number;
leaseBackend?: LeaseBackend;
leaseProvider?: string;
deviceKey?: string;
clientId?: string;
};
};
type LeaseOptionsLike = {
tenant?: string;
runId?: string;
leaseId?: string;
leaseTtlMs?: number;
ttlMs?: number;
leaseBackend?: LeaseBackend;
leaseProvider?: string;
provider?: string;
deviceKey?: string;
clientId?: string;
};
export function leaseScopeFromRequest(req: LeaseRequestLike): LeaseScope {
return stripUndefined({
tenantId: req.meta?.tenantId ?? readFlagString(req.flags, 'tenant'),
runId: req.meta?.runId ?? readFlagString(req.flags, 'runId'),
leaseId: req.meta?.leaseId ?? readFlagString(req.flags, 'leaseId'),
leaseTtlMs: req.meta?.leaseTtlMs,
leaseBackend: req.meta?.leaseBackend,
leaseProvider:
req.meta?.leaseProvider ??
readFlagString(req.flags, 'leaseProvider') ??
readFlagString(req.flags, 'provider'),
deviceKey: req.meta?.deviceKey ?? readFlagString(req.flags, 'deviceKey'),
clientId: req.meta?.clientId ?? readFlagString(req.flags, 'clientId'),
});
}
export function leaseScopeFromOptions(options: LeaseOptionsLike): LeaseScope {
return stripUndefined({
tenantId: options.tenant,
runId: options.runId,
leaseId: options.leaseId,
leaseTtlMs: options.leaseTtlMs ?? options.ttlMs,
leaseBackend: options.leaseBackend,
leaseProvider: options.leaseProvider ?? options.provider,
deviceKey: options.deviceKey,
clientId: options.clientId,
});
}
export function leaseScopeToRequestMeta(scope: LeaseScope): LeaseRequestLike['meta'] {
return stripUndefined({
tenantId: scope.tenantId,
runId: scope.runId,
leaseId: scope.leaseId,
leaseTtlMs: scope.leaseTtlMs,
leaseBackend: scope.leaseBackend,
leaseProvider: scope.leaseProvider,
deviceKey: scope.deviceKey,
clientId: scope.clientId,
});
}
export function leaseScopeToCommandFlags(scope: LeaseScope): Record<string, unknown> {
return stripUndefined({
tenant: scope.tenantId,
runId: scope.runId,
leaseId: scope.leaseId,
leaseBackend: scope.leaseBackend,
leaseProvider: scope.leaseProvider,
deviceKey: scope.deviceKey,
clientId: scope.clientId,
});
}
export function leaseScopeToAllocateRequest(scope: LeaseScope): LeaseAllocateRequestScope {
return stripUndefined({
tenantId: scope.tenantId ?? '',
runId: scope.runId ?? '',
leaseBackend: scope.leaseBackend,
leaseProvider: scope.leaseProvider,
deviceKey: scope.deviceKey,
clientId: scope.clientId,
ttlMs: scope.leaseTtlMs,
}) as LeaseAllocateRequestScope;
}
export function leaseScopeToHeartbeatRequest(scope: LeaseScope): LeaseScopedRequestScope {
return leaseScopeToScopedRequest(scope);
}
export function leaseScopeToReleaseRequest(
scope: LeaseScope,
): Omit<LeaseScopedRequestScope, 'ttlMs'> {
const { ttlMs: _ttlMs, ...request } = leaseScopeToScopedRequest(scope);
return request;
}
export function leaseScopeToLeaseRpcParams(
scope: LeaseScope,
command: LeaseRpcCommand,
options: {
includeTokenParam: boolean;
token?: string;
session?: string;
},
): Record<string, unknown> {
const common = stripUndefined({
...(options.includeTokenParam ? { token: options.token } : {}),
session: options.session,
tenantId: scope.tenantId,
runId: scope.runId,
leaseProvider: scope.leaseProvider,
clientId: scope.clientId,
deviceKey: scope.deviceKey,
});
switch (command) {
case 'lease_allocate':
return {
...common,
...stripUndefined({
ttlMs: scope.leaseTtlMs,
backend: scope.leaseBackend,
}),
};
case 'lease_heartbeat':
return {
...common,
...stripUndefined({
leaseId: scope.leaseId,
ttlMs: scope.leaseTtlMs,
}),
};
case 'lease_release':
return {
...common,
...stripUndefined({
leaseId: scope.leaseId,
}),
};
}
}
/**
* Request flags that must travel with `lease_allocate` so the daemon's lease-lifecycle provider can
* prepare the session — device selection, the app/os, the session-naming fields, and the configured
* device-feature and AWS knobs. The line transport forwards the whole request and these arrive for
* free; the compact lease envelope is the only projection that has to name them, so the client's
* producer and the daemon's consumer read the SAME list and cannot drop a sibling the provider needs.
*/
const LEASE_ALLOCATE_PROVIDER_FLAG_KEYS = [
// Device selection the lease-lifecycle provider needs to create the session.
'platform',
'device',
// The Cloud provider profile fields; pinned exhaustive against that vocabulary below.
'providerApp',
'providerOsVersion',
'providerDeviceType',
'providerProject',
'providerBuild',
'providerSessionName',
'providerDeviceOrientation',
'providerGeoLocation',
'providerTimezone',
'providerAppiumVersion',
'providerLanguage',
'providerLocale',
'providerNetworkProfile',
'providerCustomNetwork',
'providerNoResignApp',
'awsProjectArn',
'awsDeviceArn',
'awsAppArn',
'awsRegion',
'awsInteractionMode',
] as const satisfies readonly (keyof CommandFlags)[];
type LeaseAllocateProviderFlagKey = (typeof LEASE_ALLOCATE_PROVIDER_FLAG_KEYS)[number];
// A Cloud provider profile field added without joining the projection would be dropped from the
// envelope and fail `prepareSession` on the remote daemon — this makes that omission fail to build.
type LeaseAllocateProfileKeysAreExhaustive =
Exclude<keyof CloudProviderProfileFields, LeaseAllocateProviderFlagKey> extends never
? true
: Exclude<keyof CloudProviderProfileFields, LeaseAllocateProviderFlagKey>;
const leaseAllocateProfileKeysExhaustive: LeaseAllocateProfileKeysAreExhaustive = true;
void leaseAllocateProfileKeysExhaustive;
type LeaseAllocateProviderFlags = Partial<Pick<CommandFlags, LeaseAllocateProviderFlagKey>>;
/** Reads the provider-allocation flags out of a request flags bag or a lease-envelope param bag. */
export function readLeaseAllocateProviderFlags(
source: Record<string, unknown> | undefined,
): LeaseAllocateProviderFlags {
const flags: Record<string, string | boolean> = {};
for (const key of LEASE_ALLOCATE_PROVIDER_FLAG_KEYS) {
const value = source?.[key];
if (typeof value === 'string' || typeof value === 'boolean') flags[key] = value;
}
return flags as LeaseAllocateProviderFlags;
}
export function leaseScopeToConnectionMetadata(
scope: LeaseScope,
): Pick<LeaseScope, 'leaseProvider' | 'deviceKey' | 'clientId'> | undefined {
const connection = stripUndefined({
leaseProvider: scope.leaseProvider,
deviceKey: scope.deviceKey,
clientId: scope.clientId,
});
return Object.keys(connection).length > 0 ? connection : undefined;
}
/**
* @internal Lease diagnostics seam exposed for unit tests.
*/
export function buildLeaseDiagnosticsContext(
leaseScope: LeaseScope | undefined,
): LeaseDiagnosticsContext | undefined {
if (!leaseScope) return undefined;
const context = stripUndefined({
tenantId: leaseScope.tenantId,
runId: leaseScope.runId,
leaseId: leaseScope.leaseId,
leaseBackend: leaseScope.leaseBackend,
leaseProvider: leaseScope.leaseProvider,
deviceKey: leaseScope.deviceKey,
clientId: leaseScope.clientId,
});
return Object.keys(context).length > 0 ? context : undefined;
}
export function isProxyLeaseScope(scope: LeaseScope): boolean {
return scope.leaseProvider === PROXY_LEASE_PROVIDER;
}
export function findMissingProxyLeaseFields(scope: LeaseScope): string[] {
if (!isProxyLeaseScope(scope)) return [];
return REQUIRED_PROXY_LEASE_FIELDS.filter((field) => !scope[field]);
}
/**
* The shortest inactivity window a lease can hold by default.
*
* The registry clamps every ttl to this floor, so it is also the worst case a client plans against
* before it has seen a lease answer: work that has to finish inside a lease window it does not know
* yet must assume this one, or it can be planning for a window the daemon would never grant.
*/
export const MIN_LEASE_WINDOW_MS = 5_000;
/**
* Why a lease stopped being ours: it is gone, spent, or taken back.
*
* This is the whole taxonomy of "the lease is no longer usable" as the daemon reports it, and both
* readers ask the same question — a client deciding whether a connection still owns a device, and a
* lease beat deciding whether an upload is still worth finishing. A reason naming a mismatch between
* a request and a lease is not in here: that says something about the request, not the lease.
*/
const INACTIVE_LEASE_REASONS: ReadonlySet<unknown> = new Set([
'LEASE_NOT_FOUND',
'LEASE_EXPIRED',
'LEASE_REVOKED',
]);
/** Whether `error` says the lease is gone rather than merely unavailable to this request. */
export function isInactiveLeaseError(error: unknown): boolean {
return (
typeof error === 'object' &&
error !== null &&
(error as Readonly<{ code?: unknown }>).code === 'UNAUTHORIZED' &&
INACTIVE_LEASE_REASONS.has(
(error as Readonly<{ details?: Readonly<{ reason?: unknown }> }>).details?.reason,
)
);
}
function leaseScopeToScopedRequest(scope: LeaseScope): LeaseScopedRequestScope {
return stripUndefined({
leaseId: scope.leaseId ?? '',
tenantId: scope.tenantId,
runId: scope.runId,
leaseBackend: scope.leaseBackend,
leaseProvider: scope.leaseProvider,
deviceKey: scope.deviceKey,
clientId: scope.clientId,
ttlMs: scope.leaseTtlMs,
}) as LeaseScopedRequestScope;
}
function readFlagString(
flags: Record<string, unknown> | undefined,
key: string,
): string | undefined {
const value = flags?.[key];
return typeof value === 'string' ? value : undefined;
}