Repository navigation
Expand file tree
/
Copy pathruntime.ts
More file actions
995 lines (935 loc) · 42 KB
/
Copy pathruntime.ts
File metadata and controls
995 lines (935 loc) · 42 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
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
import Limrun from '@limrun/api';
import type { Interactor, RunnerContext } from '@agent-device/contracts/interactor-types';
import type {
DeviceInventoryProvider,
DeviceLease,
LeaseLifecycleProvider,
LeaseLifecycleContext,
ProviderAppCatalogHandler,
ProviderDeviceInstallOptions,
ProviderDeviceInstallResult,
ProviderDeviceRuntime,
ProviderExpiredLeaseRecovery,
ProviderPortReverseOptions,
} from '@agent-device/contracts/device';
import type { DeviceInfo } from '@agent-device/kernel/device';
import { AppError, errorMessage } from '@agent-device/kernel/errors';
import {
cleanupLimrunAndroidAdbTunnel,
configureLimrunAndroidPortReverse,
createLimrunAndroidInteractor,
createLimrunAndroidSession,
installLimrunAndroidApp,
type LimrunAndroidSession,
} from './android.ts';
import {
attachedLimrunInstanceId,
buildLimrunDevice,
LIMRUN_PROVIDER,
parseLimrunDeviceId,
platformForLimrunLeaseBackend,
type LimrunPlatform,
} from './device.ts';
import { createLimrunIosInteractor, createLimrunIosSession, installLimrunIosApp } from './ios.ts';
import { createLimrunDeviceSession, type LimrunDeviceSession } from './device-session.ts';
import type { LimrunRuntimeDependencies } from './runtime-dependencies.ts';
import type {
PlatformRuntimeHost,
PlatformRuntimeOwner,
PlatformRuntimeProviderModule,
} from '@agent-device/contracts/platform-runtime-operations';
import { providerRuntimeOwner } from '@agent-device/contracts/platform-runtime';
import type { LimrunAppLogDescriptor } from './app-log-descriptor.ts';
import type { LimrunAppLogReader } from './app-log-runtime.ts';
import { LIMRUN_CLIENT_ID, limrunUserAgent, requireLimrunOrgClient } from './client-options.ts';
import { resolveLimrunRuntimeInstance } from './runtime-instance.ts';
import type { LimrunRequestOperationDrain } from './request-cancellation.ts';
import type { LimrunAppAsset } from './app-catalog.ts';
import type { LimrunInstanceAccess } from './instance-access.ts';
import type {
CloudArtifactProvider,
CloudArtifactsResult,
} from '@agent-device/contracts/observability';
import type {
LimrunAppAlias,
LimrunCreateOutcome,
LimrunDisposalOutcome,
LimrunLeaseOwner,
LimrunRuntimeSession,
LimrunTeardownRoute,
} from './lease-ownership.ts';
import type { LimrunCaptureLifecycle } from './capture-lifecycle.ts';
const KEEP_ALIVE_INTERVAL_MS = 30_000;
/**
* How long a teardown waits for the create to say what it rented. The create itself keeps Limrun's own
* timeouts: this bounds only the teardown's wait, so an instance is never held open by a create that
* stopped answering, and the owner is kept for the next route to end what that create rents.
*/
const CREATE_ANSWER_BUDGET_MS = 120_000;
/**
* How long a teardown waits for the local resources it started beside the delete: the instance connection
* and the Android ADB endpoint, whose `adb connect` the SDK runs without a deadline.
*/
const LOCAL_TEARDOWN_BUDGET_MS = 45_000;
/** How long a teardown waits for a capture's HAR record, which is reporting and never a reason to hold a lease. */
const CAPTURE_RECORD_BUDGET_MS = 15_000;
export type LimrunRuntimeOptions = {
/** Organization API key. It creates and deletes instances for platforms without `instances`. */
apiKey?: string;
region?: string;
/** Pings each leased instance every 30 s so Limrun's inactivity timeout does not end idle sessions. */
keepAlive?: boolean;
runtimeInstance?: string;
instances?: LimrunInstanceAccess;
/** Where `--provider-network-logs` writes each lease's HAR file. Without it the capture is unavailable. */
networkHarDir?: string;
};
export type LimrunRuntime = ProviderDeviceRuntime & {
recoverExpiredLease: ProviderExpiredLeaseRecovery;
getDeviceSession(device: DeviceInfo): LimrunDeviceSession | undefined;
};
export type LimrunRuntimeRegistration = Readonly<{
runtime: LimrunRuntime;
platformModule: PlatformRuntimeProviderModule;
}>;
export function createLimrunRuntime(
options: LimrunRuntimeOptions,
dependencies: LimrunRuntimeDependencies,
mode: Readonly<{ includePlatformModule: true }>,
): LimrunRuntimeRegistration;
export function createLimrunRuntime(
options: LimrunRuntimeOptions,
dependencies: LimrunRuntimeDependencies,
): LimrunRuntime;
export function createLimrunRuntime(
options: LimrunRuntimeOptions,
dependencies: LimrunRuntimeDependencies,
mode?: Readonly<{ includePlatformModule: true }>,
): LimrunRuntime | LimrunRuntimeRegistration {
const runtime = new LimrunRuntimeImplementation(options, dependencies);
if (!mode?.includePlatformModule) return runtime;
const owner = providerRuntimeOwner(LIMRUN_PROVIDER, resolveLimrunRuntimeInstance(options));
if (owner.kind !== 'provider-runtime') throw new TypeError('Invalid Limrun runtime owner');
return Object.freeze({
runtime,
platformModule: Object.freeze({
owner,
loadRuntime: async (host: PlatformRuntimeHost) =>
await loadLimrunPlatformRuntime(runtime, owner.instance, host),
}),
});
}
class LimrunRuntimeImplementation implements ProviderDeviceRuntime {
private readonly limrun: Limrun | undefined;
/**
* A lease has an owner from the step it is allocated until the one disposal of it confirms. Allocate,
* join, release, recovery, shutdown and every reader of a live session go through this one map, so an
* in-flight create is never invisible to the route that has to end what it rents.
*/
private readonly leases = new Map<string, LimrunLeaseOwner>();
/**
* What each lease's network capture goes through, including the records a release settled. Absent until a
* lease asks for a capture, which is what keeps the capture's module out of a runtime that captures nothing.
*/
private capturesInstance?: LimrunCaptureLifecycle;
/** Whether this runtime has shut down; it then holds nothing, so it must create nothing. */
private shutDown = false;
private readonly options: LimrunRuntimeOptions;
private readonly dependencies: LimrunRuntimeDependencies;
readonly provider = LIMRUN_PROVIDER;
readonly leaseLifecycle: LeaseLifecycleProvider = {
allocate: async (lease, context) => await this.allocate(lease, context),
release: async (lease) => await this.release(lease),
};
readonly appCatalog: ProviderAppCatalogHandler = async (query, signal) => {
const { assertLimrunUploadedAppAccess, listLimrunAppAssets } = await import('./app-catalog.ts');
assertLimrunUploadedAppAccess(query.publicNetworkOnly);
const limrun = this.orgClient(
'Listing uploaded apps',
'Run open <bundle-or-package-id> first; apps then lists the apps installed on the instance.',
);
return (await listLimrunAppAssets(limrun, query.platform, signal)).map((asset) => asset.name);
};
readonly recoverExpiredLease: ProviderExpiredLeaseRecovery = async (lease) => {
if (lease.leaseProvider !== this.provider || !platformForLimrunLeaseBackend(lease.backend)) {
throw new AppError('UNSUPPORTED_OPERATION', 'Limrun cannot recover this expired lease.', {
leaseId: lease.leaseId,
leaseProvider: lease.leaseProvider,
leaseBackend: lease.backend,
});
}
await this.release(lease);
};
readonly deviceInventoryProvider: DeviceInventoryProvider = async (request) => {
if (request.leaseProvider !== this.provider || !request.leaseId) return null;
const session = this.liveSessionForLease(request.leaseId);
if (!session) return null;
if (request.platform && request.platform !== session.platform) return [];
return [session.device];
};
constructor(options: LimrunRuntimeOptions, dependencies: LimrunRuntimeDependencies) {
if (!options.apiKey && !options.instances?.ios && !options.instances?.android) {
throw new TypeError('Limrun runtime requires an apiKey or instance access');
}
this.options = options;
this.dependencies = dependencies;
this.limrun = options.apiKey
? new Limrun({
apiKey: options.apiKey,
userAgent: limrunUserAgent(dependencies.clientVersion),
})
: undefined;
}
/**
* The capture lifecycle, made the first time a lease asks for a capture. The records a release settled live
* there, so an artifacts read for a lease this runtime no longer holds goes through the same instance that
* settled them, and a runtime that never captures anything never evaluates that module.
*/
private async captures(): Promise<LimrunCaptureLifecycle> {
if (this.capturesInstance === undefined) {
const { LimrunCaptureLifecycle } = await import('./capture-lifecycle.ts');
// Two allocations can be inside this load at once, and the settled records have to be one lifecycle's.
this.capturesInstance ??= new LimrunCaptureLifecycle({
harDir: this.options.networkHarDir,
liveSessionOf: (owner) => this.liveSession(owner),
heldOwners: () => this.leases.values(),
});
}
return this.capturesInstance;
}
ownsDevice(device: DeviceInfo): boolean {
return parseLimrunDeviceId(device.id) !== undefined;
}
hasLiveSession(device: DeviceInfo): boolean {
return this.getSessionForDevice(device) !== undefined;
}
getInteractor(device: DeviceInfo, _runner?: RunnerContext): Interactor | undefined {
const session = this.getSessionForDevice(device);
if (!session) return undefined;
return session.platform === 'ios'
? createLimrunIosInteractor(session)
: createLimrunAndroidInteractor(session);
}
getDeviceSession(device: DeviceInfo): LimrunDeviceSession | undefined {
const session = this.getSessionForDevice(device);
return session ? createLimrunDeviceSession(session) : undefined;
}
async installApp(
device: DeviceInfo,
app: string,
appPath: string,
options?: ProviderDeviceInstallOptions,
signal?: AbortSignal,
operationDrain?: LimrunRequestOperationDrain,
): Promise<ProviderDeviceInstallResult | undefined> {
return await this.installInstallablePath(
device,
appPath,
{
...options,
appIdentifierHint: options?.appIdentifierHint ?? app,
packageNameHint: options?.packageNameHint ?? app,
},
signal,
operationDrain,
);
}
async installInstallablePath(
device: DeviceInfo,
installablePath: string,
options?: ProviderDeviceInstallOptions,
signal?: AbortSignal,
operationDrain?: LimrunRequestOperationDrain,
): Promise<ProviderDeviceInstallResult | undefined> {
const session = this.getSessionForDevice(device);
if (!session) return undefined;
const limrun = this.orgClient('Uploading an app');
return session.platform === 'ios'
? await installLimrunIosApp(limrun, session, installablePath, options, signal, operationDrain)
: await installLimrunAndroidApp(
limrun,
session,
installablePath,
options,
signal,
operationDrain,
);
}
async configurePortReverse(
options: ProviderPortReverseOptions,
): Promise<Record<string, unknown> | undefined> {
const session = this.requireAndroidPortReverseSession(options.leaseId);
if (!session) return undefined;
await configureLimrunAndroidPortReverse(session, options);
return portReverseResult(options);
}
/**
* Ends every instance this runtime holds or is on its way to holding, and says so when it could not.
* Each lease is taken, or joined, in one synchronous step, so a create that answers afterwards is
* disposed by the one disposal of that lease and by no other route, and a release already running is
* awaited rather than raced.
*/
async shutdown(): Promise<void> {
this.shutDown = true;
// Snapshot before anything is awaited: `allocate` refuses once this flag is set and publishes an
// owner only where none exists, and nothing between the flag and this loop awaits. So no create can
// start here, and every create already running has an owner for this loop to take.
const outcomes = await Promise.all(
[...this.leases.values()].map(async (owner) => await this.take(owner, 'shutdown')),
);
// An instance Limrun would not give back is still billed, and this process will not stop it. The
// plugin's close is where an operator learns what a daemon close left running, so the instance and
// the provider's refusal travel on the error rather than being dropped.
const unended = outcomes.filter((outcome) => outcome.cleanup === 'uncertain');
if (unended.length > 0) throw cleanupLeftInstancesRunning(unended);
}
private async allocate(
lease: DeviceLease,
context?: LeaseLifecycleContext,
): Promise<Record<string, unknown> | undefined> {
if (lease.leaseProvider !== this.provider) return undefined;
const platform = platformForLimrunLeaseBackend(lease.backend);
if (!platform) return undefined;
// Joining a lease somebody else allocated, so this call answers for flags of its own, and it settles
// them before it reads any state. Nothing else awaits on this route: the lookup below is the last one.
if (this.leases.has(lease.leaseId)) await this.rejectRefusedProfileFields(context);
// Published without awaiting anything, so a lease is never unowned while its allocation is at its first
// await: a release or a shutdown arriving there finds this owner and takes it, and the create that owner
// stands on checks this call's own profile flags before it bills anything.
let owner = this.leases.get(lease.leaseId);
if (owner === undefined) {
// Nothing between this lookup and the publication below awaits, so two allocations of one lease can
// never both pass it, and this runtime can be shut down only before or after this step.
if (this.shutDown) throw allocationRefusedAfterShutdown(lease);
owner = this.beginAllocation(lease, platform, context);
}
if (owner.state.phase === 'allocating') {
const create = await owner.creation;
if (create.status === 'failed') {
// A create that failed has no release coming for it, so this call is the only route left to end an
// instance it made before failing. What it came to outranks why the create did not finish: an
// instance Limrun is still billing is the caller's problem first.
const outcome = await this.settleFailedCreate(owner);
if (outcome?.cleanup === 'uncertain') throw createLeftInstanceRunning(lease, outcome);
throw create.error;
}
this.goLive(owner, create.session, create.appAlias);
}
// A repeat allocation can ask for the capture, or retry one that could not start. A lease a teardown has
// already taken starts nothing: `captures.start` reads the owner's own live session, and what this lease
// has is that teardown's to end.
if (context?.flags?.providerNetworkLogs === true && owner.capture?.phase !== 'capturing') {
const captures = await this.captures();
await captures.start(owner, context.flags.providerNetworkHosts);
}
// A release or shutdown that took the lease while this call waited owns the instance the create made, and
// answers for it. This caller is refused for that teardown, with what it came to, rather than being handed
// an instance nothing will release for it. The refusal waits for the teardown to answer, so this caller
// never reports before the instance it was promised is gone.
const taken = owner.state;
if (taken.phase === 'releasing') {
const outcome = await taken.disposal;
throw allocationRefusedForTake(lease, taken.by, outcome);
}
const session = this.requireLiveSession(owner);
return { limrunInstanceId: session.instanceId, device: session.device };
}
/** The profile flags this provider reads nothing for, refused for a lease this runtime already holds. */
private async rejectRefusedProfileFields(context?: LeaseLifecycleContext): Promise<void> {
// Loaded here rather than eagerly so this package entry's declared closure stays unchanged. The create
// of a new allocation refuses the same flags as its first step, inside the owner it published.
const { rejectRefusedLimrunProfileFields } = await import('./session-allocation.ts');
rejectRefusedLimrunProfileFields(context);
}
/**
* Publishes the owner one allocation's create is standing on, in the same step that starts the create
* and before it can answer, so a duplicate allocation joins that create instead of making a second
* instance, and a release or shutdown arriving mid-create has somewhere to find the instance that create
* is on its way to making. The owner records that instance the moment Limrun names it, so whichever route
* takes the lease has what it has to end.
*/
private beginAllocation(
lease: DeviceLease,
platform: LimrunPlatform,
context?: LeaseLifecycleContext,
): LimrunLeaseOwner {
let report!: (create: LimrunCreateOutcome) => void;
const creation = new Promise<LimrunCreateOutcome>((settled) => {
report = settled;
});
const owner: LimrunLeaseOwner = {
lease,
platform,
creation,
state: { phase: 'allocating' },
rentedInstanceId: undefined,
keepAlive: undefined,
capture: undefined,
appAlias: undefined,
deletedInstanceId: undefined,
};
this.leases.set(lease.leaseId, owner);
// The create is started after the publication above, so its answer can never arrive without an owner
// beside it. Whichever route takes the lease in the meantime ends what this answer names.
void this.createForLease(owner, context).then(report);
return owner;
}
/**
* Attaches or makes this lease's instance and answers with the whole outcome rather than with a promise
* that resolves or rejects: a refused caller still has to say whether anything was left running, and the
* owner is where an instance this create rented gets recorded. Nothing here ends an instance, and nothing
* retries a create: a create whose answer was lost may have made an instance anyway, and that instance is
* reported and ended, never replaced by a second one.
*/
private async createForLease(
owner: LimrunLeaseOwner,
context?: LeaseLifecycleContext,
): Promise<LimrunCreateOutcome> {
try {
const {
allocateLimrunAndroidSession,
allocateLimrunIosSession,
rejectRefusedLimrunProfileFields,
resolvePreinstalledAppId,
resolveRequestedLimrunAppAsset,
} = await import('./session-allocation.ts');
// The first step of the create, so an allocation that published its owner before it could await
// anything still bills nothing for flags this provider reads no field for.
rejectRefusedLimrunProfileFields(context);
const platform = owner.platform;
// Attach first, and only ask for the organization client if there is nothing to attach: an attached
// instance needs no API key, and is not created with an app asset of ours.
const attached = await this.attachSession(platform, owner.lease);
if (attached) {
return { status: 'ready', session: attached, appAlias: undefined };
}
const limrun = this.orgClient('Creating an instance');
const requestedAsset = await resolveRequestedLimrunAppAsset(limrun, platform, context);
const params = this.sessionAllocationParams(limrun, owner.lease, requestedAsset);
const rent = (instanceId: string): void => {
owner.rentedInstanceId = instanceId;
};
const session =
platform === 'ios'
? await allocateLimrunIosSession(params, rent)
: await allocateLimrunAndroidSession(params, rent);
const appAlias: LimrunAppAlias | undefined = requestedAsset && {
assetName: requestedAsset.name,
installedAppId: await resolvePreinstalledAppId(session, requestedAsset),
};
return { status: 'ready', session, appAlias };
} catch (error) {
return { status: 'failed', error };
}
}
/**
* Puts the instance one create made, and the app alias that came with it, onto its owner. Another
* allocation that joined the same create can get here first, and a route that took the lease while the
* create ran owns the instance instead — either way this owner is already where it belongs, and nothing
* is published for a lease that no longer has an allocation.
*/
private goLive(
owner: LimrunLeaseOwner,
session: LimrunRuntimeSession,
appAlias: LimrunAppAlias | undefined,
): void {
if (owner.state.phase !== 'allocating') return;
owner.appAlias = appAlias;
owner.state = { phase: 'live', session };
if (this.options.keepAlive) this.startKeepAlive(owner, session);
}
/**
* Closes an owner whose create made nothing, and ends the instance one that made an instance before it
* failed. A create that failed has no release coming for it — its caller is being refused — so this is
* the route that ends what it left running, through the same take every other teardown goes through.
* The outcome is reported to that caller, which is the only one left to hear it.
*/
private async settleFailedCreate(
owner: LimrunLeaseOwner,
): Promise<LimrunDisposalOutcome | undefined> {
const state = owner.state;
if (state.phase === 'allocating') return await this.take(owner, 'create');
// Another route took the lease while this call waited, and its disposal owns what the create made.
return state.phase === 'releasing' ? await state.disposal : undefined;
}
/**
* Hands one lease's resources to the one route that may end them, or joins the disposal already ending
* them. The take and the disposal it starts are recorded before this step returns, so no route can reach
* the lease in between and find it free, and the owner leaves the map only once that disposal confirmed.
* A disposal that could not confirm keeps the owner here, so the next release, recovery or shutdown
* retries the delete rather than reporting an instance Limrun may still be billing.
*/
private take(owner: LimrunLeaseOwner, by: LimrunTeardownRoute): Promise<LimrunDisposalOutcome> {
const taken = owner.state;
const settled = taken.phase === 'releasing' ? taken.settled : undefined;
if (taken.phase === 'releasing' && !(settled?.cleanup === 'uncertain')) return taken.disposal;
let reportDisposal!: (outcome: LimrunDisposalOutcome) => void;
const disposal = new Promise<LimrunDisposalOutcome>((settledOutcome) => {
reportDisposal = settledOutcome;
});
owner.state = {
phase: 'releasing',
by,
instanceId:
this.liveSession(owner)?.instanceId ?? owner.rentedInstanceId ?? settled?.instanceId,
disposal,
settled: undefined,
};
const report = (outcome: LimrunDisposalOutcome): void => {
const state = owner.state;
if (state.phase === 'releasing') {
state.settled = outcome;
state.instanceId = outcome.instanceId ?? state.instanceId;
// Whatever the create made is now ended, or was never made, so this owner holds nothing and the
// lease is free again. An unconfirmed delete keeps the owner so its outcome can be retried.
if (outcome.cleanup !== 'uncertain') this.closeOwner(owner);
}
reportDisposal(outcome);
};
// `disposeOwner` reports the failures it can name, so the rejection branch is only for what it could not
// report at all. The disposal still answers, because a caller may be waiting on this lease's instance.
void this.disposeOwner(owner).then(report, (error: unknown) => {
report({
cleanup: 'uncertain',
instanceId: owner.rentedInstanceId,
failure: errorMessage(error),
capture: undefined,
});
});
return disposal;
}
/**
* Ends what one taken owner stands for: the instance its create made or rented, with every resource the
* owner holds beside it. This is the only place an instance is ended, and an owner is taken by exactly one
* route at a time, so one instance is ended exactly once. Every wait here is bounded: work that outlives
* its budget keeps running and cleans up what it makes, and nothing of it stands between this route and the
* delete that stops the instance from being billed.
*/
private async disposeOwner(owner: LimrunLeaseOwner): Promise<LimrunDisposalOutcome> {
const { awaitLimrunWithinBudget, joinOutcomeFailures } = await import('./lifecycle-budget.ts');
// A create that outlives this budget is reported rather than waited on: the owner is kept, so the next
// release, recovery or daemon close ends whatever that create goes on renting.
const create = await awaitLimrunWithinBudget(owner.creation, CREATE_ANSWER_BUDGET_MS);
const session = create.ok && create.value.status === 'ready' ? create.value.session : undefined;
const instanceId = session?.instanceId ?? owner.rentedInstanceId;
if (instanceId === undefined) return await this.disposeUnrented(owner, create.ok);
// The capture's record is optional reporting, and local teardown can outlive its own steps: neither is
// allowed to stand between this route and the delete that stops the instance from being billed, so both
// are started here and joined after it. A lease that never asked for a capture has no lifecycle to end,
// so its disposal never loads one.
const capture = this.capturesInstance?.end(owner);
const local = this.releaseOwnerResources(owner, session);
const instance = await this.endInstance(owner, session, instanceId);
const stuck = await this.awaitLocalTeardown(local);
// The record is optional reporting joined last: a capture that refuses to be written cannot keep a
// release from answering for the instance it ended, and is still listable once it does come to.
const joined =
capture === undefined
? undefined
: await awaitLimrunWithinBudget(capture, CAPTURE_RECORD_BUDGET_MS);
return {
cleanup: instance.cleanup,
instanceId,
failure: joinOutcomeFailures(instance.failure, stuck),
capture: joined?.ok ? joined.value : undefined,
};
}
/**
* Ends what a disposal holds when no instance is named for the lease: its capture, and an outcome that
* keeps the lease held only while a create this route lost sight of may still rent something.
*/
private async disposeUnrented(
owner: LimrunLeaseOwner,
createAnswered: boolean,
): Promise<LimrunDisposalOutcome> {
const { workOutstandingFailure } = await import('./lifecycle-budget.ts');
const capture = await this.capturesInstance?.end(owner);
if (createAnswered) {
return { cleanup: 'none', instanceId: undefined, failure: undefined, capture };
}
return {
cleanup: 'uncertain',
instanceId: undefined,
failure: workOutstandingFailure(
`Instance create for lease '${owner.lease.leaseId}'`,
CREATE_ANSWER_BUDGET_MS,
),
capture,
};
}
/**
* Ends one owner's instance. A delete Limrun already confirmed answers for itself, an attached instance is
* the caller's own to delete, and a created one is deleted here, with that answer deciding whether the
* lease can be given back.
*/
private async endInstance(
owner: LimrunLeaseOwner,
session: LimrunRuntimeSession | undefined,
instanceId: string,
): Promise<Readonly<{ cleanup: LimrunDisposalOutcome['cleanup']; failure: string | undefined }>> {
if (owner.deletedInstanceId === instanceId) return { cleanup: 'confirmed', failure: undefined };
if ((session?.ownership ?? 'created') === 'attached') {
// An attached instance is the caller's own, and this runtime was never given the right to delete it.
return { cleanup: 'attached', failure: undefined };
}
const failure = await this.deleteInstance(owner.platform, instanceId);
if (failure === undefined) owner.deletedInstanceId = instanceId;
return { cleanup: failure === undefined ? 'confirmed' : 'uncertain', failure };
}
/**
* Ends the resources one owner holds besides its instance: the keep-alive beat that would otherwise ping a
* deleted instance forever, the instance connection, and the Android ADB tunnel and its reverse mappings.
* Each is released once, whichever route took the lease.
*/
private async releaseOwnerResources(
owner: LimrunLeaseOwner,
session: LimrunRuntimeSession | undefined,
): Promise<void> {
if (owner.keepAlive) clearInterval(owner.keepAlive);
owner.keepAlive = undefined;
if (session === undefined) return;
session.client.disconnect();
// The tunnel's start is an `adb connect` the SDK runs without a deadline. Its cleanup retires the
// endpoint first, so a tunnel that answers late ends itself and no caller can reach it meanwhile.
if (session.platform === 'android') await cleanupLimrunAndroidAdbTunnel(session);
}
/**
* Reports the local teardown this route had to stop waiting for. A step that refused is reported as one
* that never answered: neither is something this runtime can still fix, and the delete that ran beside it
* has already been answered.
*/
private async awaitLocalTeardown(local: Promise<void>): Promise<string | undefined> {
const { awaitLimrunWithinBudget, workOutstandingFailure } =
await import('./lifecycle-budget.ts');
const stuck = workOutstandingFailure('Local teardown', LOCAL_TEARDOWN_BUDGET_MS);
const ended = await awaitLimrunWithinBudget(
local.then(
(): string | undefined => undefined,
(): string => stuck,
),
LOCAL_TEARDOWN_BUDGET_MS,
);
return ended.ok ? ended.value : stuck;
}
/** One instance delete. `undefined` is Limrun's confirmation that the instance is gone. */
private async deleteInstance(
platform: LimrunPlatform,
instanceId: string,
): Promise<string | undefined> {
try {
const limrun = this.orgClient('Deleting an instance');
if (platform === 'ios') {
await limrun.iosInstances.delete(instanceId);
} else {
await limrun.androidInstances.delete(instanceId);
}
return undefined;
} catch (error) {
return errorMessage(error);
}
}
/** Removes an owner once it holds nothing, and only while it is still the map's owner for that lease. */
private closeOwner(owner: LimrunLeaseOwner): void {
if (this.leases.get(owner.lease.leaseId) === owner) this.leases.delete(owner.lease.leaseId);
}
private startKeepAlive(owner: LimrunLeaseOwner, session: LimrunRuntimeSession): void {
const timer = setInterval(() => {
try {
session.client.keepAlive();
} catch {
// A dead connection surfaces on the next real command.
}
}, KEEP_ALIVE_INTERVAL_MS);
timer.unref();
owner.keepAlive = timer;
}
readonly cloudArtifacts: CloudArtifactProvider = {
listCloudArtifacts: async (query) => await this.listCloudArtifacts(query.leaseId),
};
/**
* What `artifacts` answers for one lease: its capture written now while the lease is held, and the
* record a release settled after the lease is gone. A runtime that never started a capture has no
* lifecycle to ask, so nothing is loaded for it.
*/
private async listCloudArtifacts(
leaseId: string | undefined,
): Promise<CloudArtifactsResult | undefined> {
if (leaseId === undefined) return undefined;
const captures = this.capturesInstance;
if (captures === undefined) return undefined;
const { networkArtifacts } = await import('./network-har.ts');
const capture = await captures.list(leaseId, this.leases.get(leaseId)?.capture);
return capture && networkArtifacts(capture);
}
private async attachSession(
platform: LimrunPlatform,
lease: DeviceLease,
): Promise<LimrunRuntimeSession | undefined> {
const { ios, android } = this.options.instances ?? {};
const target = (apiUrl: string) => {
const instanceId = attachedLimrunInstanceId(apiUrl);
const device = buildLimrunDevice(platform, lease, instanceId);
return { lease, instanceId, ownership: 'attached' as const, device };
};
if (platform === 'android') {
return (
android &&
(await createLimrunAndroidSession(
{ ...target(android.apiUrl), ...android },
this.dependencies,
))
);
}
return (
ios && (await createLimrunIosSession({ ...target(ios.apiUrl), ...ios }, this.dependencies))
);
}
private sessionAllocationParams(limrun: Limrun, lease: DeviceLease, app?: LimrunAppAsset) {
return {
limrun,
lease,
metadata: this.buildInstanceMetadata(lease),
region: this.options.region,
app,
dependencies: this.dependencies,
};
}
private buildInstanceMetadata(lease: DeviceLease) {
return {
displayName: `agent-device-${lease.tenantId}-${lease.runId}`,
labels: {
tenantId: lease.tenantId,
runId: lease.runId,
leaseId: lease.leaseId,
provider: lease.leaseProvider ?? LIMRUN_PROVIDER,
source: LIMRUN_CLIENT_ID,
},
};
}
private async release(lease: DeviceLease): Promise<Record<string, unknown> | undefined> {
// The take happens in this step, before anything is loaded: the release owns the lease from here, and no
// await in between can let the allocation still waiting on its create answer ahead of it.
const owner = this.leases.get(lease.leaseId);
const disposal = owner === undefined ? undefined : this.take(owner, 'release');
const { releaseLimrunLease } = await import('./lease-release.ts');
return await releaseLimrunLease(this.limrun, lease, disposal);
}
private orgClient(operation: string, hint?: string): Limrun {
return requireLimrunOrgClient(this.limrun, operation, hint);
}
/** The live session of one owner: what its create made, and only while the lease is held. */
private liveSession(owner: LimrunLeaseOwner | undefined): LimrunRuntimeSession | undefined {
return owner?.state.phase === 'live' ? owner.state.session : undefined;
}
/** The live session of one owner, for a route that has already refused every other phase. */
private requireLiveSession(owner: LimrunLeaseOwner): LimrunRuntimeSession {
const session = this.liveSession(owner);
if (session === undefined) {
throw new AppError(
'COMMAND_FAILED',
`Limrun lease '${owner.lease.leaseId}' has no live session`,
{ reason: 'limrun_lease_not_live' },
);
}
return session;
}
private liveSessionForLease(leaseId: string): LimrunRuntimeSession | undefined {
return this.liveSession(this.leases.get(leaseId));
}
private getSessionForDevice(device: DeviceInfo): LimrunRuntimeSession | undefined {
const parsed = parseLimrunDeviceId(device.id);
if (!parsed) return undefined;
const session = this.liveSessionForLease(parsed.leaseId);
return session?.platform === parsed.platform ? session : undefined;
}
resolveAppReference(device: DeviceInfo, app: string): string {
const parsed = parseLimrunDeviceId(device.id);
if (!parsed) return app;
const alias = this.leases.get(parsed.leaseId)?.appAlias;
return alias?.assetName === app ? alias.installedAppId : app;
}
currentAppLogReader(device: DeviceInfo): LimrunAppLogReader | undefined {
const session = this.getSessionForDevice(device);
if (!session) return undefined;
const publicSession = createLimrunDeviceSession(session);
return {
platform: session.platform,
leaseId: session.lease.leaseId,
instanceId: session.instanceId,
ownership: session.ownership,
readLogs: async (appBundleId, lineLimit) =>
publicSession.platform === 'ios'
? await publicSession.readLogs(appBundleId, lineLimit)
: await publicSession.readLogs(lineLimit),
[Symbol.asyncDispose]: async () => undefined,
};
}
async reconnectAppLogReader(descriptor: LimrunAppLogDescriptor, signal?: AbortSignal) {
const { reconnectLimrunAppLogReader } = await import('./app-log-reconnect.ts');
return await reconnectLimrunAppLogReader({
limrun: this.limrun,
instances: this.options.instances,
descriptor,
dependencies: this.dependencies,
signal,
});
}
private requireAndroidPortReverseSession(leaseId: string): LimrunAndroidSession | undefined {
const session = this.liveSessionForLease(leaseId);
if (!session || session.platform === 'android') return session;
throw unsupported(
'port reverse',
'Direct Limrun iOS sessions cannot reach local host ports; use a bridge public URL.',
);
}
}
async function loadLimrunPlatformRuntime(
runtime: LimrunRuntimeImplementation,
runtimeInstance: string,
host: PlatformRuntimeHost,
): Promise<PlatformRuntimeOwner> {
const { createLimrunPlatformRuntimeOwner } = await import('./app-log-runtime.ts');
return createLimrunPlatformRuntimeOwner({
host,
runtimeInstance,
ownsDevice: (device) => runtime.ownsDevice(device),
hasLiveSession: (device) => runtime.hasLiveSession(device),
getInteractor: (device, runner) => runtime.getInteractor(device, runner),
getDeviceSession: (device) => runtime.getDeviceSession(device),
resolveAppReference: (device, app) => runtime.resolveAppReference(device, app),
openCurrent: async (device) => runtime.currentAppLogReader(device),
reconnect: async (descriptor, signal) =>
await runtime.reconnectAppLogReader(descriptor, signal),
listApps: async (device, filter, signal) => {
signal.throwIfAborted();
const session = runtime.getDeviceSession(device);
if (!session) {
throw new AppError('DEVICE_NOT_FOUND', 'Limrun app inventory session is unavailable', {
deviceId: device.id,
});
}
return (await session.listApps(filter)).map((app) => ({
id: app.id,
name: app.name ?? app.id,
}));
},
getAppState: async (device, signal) => {
signal.throwIfAborted();
const session = runtime.getDeviceSession(device);
if (session?.platform !== 'android') {
throw new AppError(
'UNSUPPORTED_OPERATION',
'Limrun Android appstate requires an active provider session',
);
}
const state = await session.getForegroundApp(signal);
signal.throwIfAborted();
return { package: state?.appId, activity: state?.activity };
},
deployApp: async (device, input, signal, operationDrain) =>
await runtime.installApp(
device,
input.app,
input.appPath,
{
relaunch: input.replaceExisting,
appIdentifierHint: input.app,
packageNameHint: input.app,
},
signal,
operationDrain,
),
deployMaterializedApp: async (device, input, signal, operationDrain) =>
await runtime.installInstallablePath(
device,
input.artifact.installablePath,
{
appIdentifierHint: input.artifact.bundleId,
packageNameHint: input.artifact.packageName,
},
signal,
operationDrain,
),
configurePortReverse: async (options) => await runtime.configurePortReverse(options),
});
}
function portReverseResult(options: ProviderPortReverseOptions): Record<string, unknown> {
return {
leaseId: options.leaseId,
devicePort: options.devicePort,
hostPort: options.hostPort,
name: options.name,
};
}
function unsupported(command: string, message: string): never {
throw new AppError('UNSUPPORTED_OPERATION', message, { command });
}
/** A lease cannot be allocated into a runtime that has been told to end every instance it holds. */
function allocationRefusedAfterShutdown(lease: DeviceLease): never {
throw new AppError(
'SESSION_NOT_FOUND',
`Cannot allocate Limrun lease '${lease.leaseId}': this runtime is shut down`,
{
reason: 'limrun_runtime_shut_down',
hint: 'Start the daemon again to allocate a Limrun lease.',
},
);
}
/**
* The refusal an allocation gets when a teardown took its lease while the create ran. The caller passes the
* disposal's outcome rather than reading the owner, so this answers with what that teardown came to —
* including a delete Limrun did not confirm, which the refused caller is the last route left to hear about.
*/
function allocationRefusedForTake(
lease: DeviceLease,
by: LimrunTeardownRoute,
outcome: LimrunDisposalOutcome,
): never {
const { instanceId } = outcome;
throw new AppError(
'DEVICE_IN_USE',
`Limrun lease '${lease.leaseId}' was released while its instance was being prepared`,
{
reason: 'limrun_lease_released_mid_allocation',
...(instanceId === undefined
? {}
: {
limrunInstanceId: instanceId,
hint: `Instance '${instanceId}' was ended by the ${by} of this lease. Open a new lease.`,
}),
...(outcome.cleanup === 'uncertain'
? { retriable: true, ...(outcome.failure === undefined ? {} : { cause: outcome.failure }) }
: {}),
},
);
}
/** What an allocation reports when the create it waited on failed and left an instance running. */
function createLeftInstanceRunning(lease: DeviceLease, outcome: LimrunDisposalOutcome): never {
throw new AppError(
'COMMAND_FAILED',
`Limrun lease '${lease.leaseId}' could not be allocated, and its instance could not be deleted`,
{
reason: 'limrun_instance_delete_unconfirmed',
retriable: true,
...(outcome.instanceId === undefined ? {} : { limrunInstanceId: outcome.instanceId }),
...(outcome.failure === undefined ? {} : { cause: outcome.failure }),
hint: `Ask Limrun to delete instance '${outcome.instanceId ?? lease.leaseId}' — this runtime could not confirm the delete.`,
},
);
}
/** What a daemon close reports for every instance it could not stop before the process moved on. */
function cleanupLeftInstancesRunning(outcomes: readonly LimrunDisposalOutcome[]): never {
const leftRunning = outcomes
.map((outcome) => outcome.instanceId)
.filter((id) => id !== undefined);
throw new AppError(
'COMMAND_FAILED',
`Limrun cleanup could not delete ${String(leftRunning.length)} instance${leftRunning.length === 1 ? '' : 's'}`,
{
reason: 'limrun_instance_delete_unconfirmed',
...(leftRunning.length === 0 ? {} : { limrunInstanceIds: leftRunning }),
...(outcomes[0]?.failure === undefined ? {} : { cause: outcomes[0].failure }),
hint: `Ask Limrun to delete: ${leftRunning.join(', ')}.`,
},
);
}