From 2e328da87c3fa50c8b15521d0be644b8fe252551 Mon Sep 17 00:00:00 2001 From: KayaanT Date: Thu, 12 Nov 2026 00:09:14 -0500 Subject: [PATCH 1/2] feat(revyl): install local builds and start sessions without an app `connect revyl` no longer requires --provider-app. Without it, Revyl starts the device with no app, and `install` puts a local build on it: the build is uploaded to the session's storage and the worker installs it through install_async, polled with install_status until it ends. A simulator .app directory is packed as a gzip tar; a .zip, .tar.gz or .tgz (iOS) and an .apk (Android) are uploaded as they are. install-from-source uses the host's materializer and the same upload. The upload and install share one 420 s budget, inside the install command's 480 s envelope, so a slow install ends with the plugin's own error rather than a client timeout that resets the daemon holding the rented device. --- packages/provider-revyl/README.md | 3 +- packages/provider-revyl/package.json | 3 +- .../provider-revyl/src/connection.test.ts | 23 +- packages/provider-revyl/src/connection.ts | 57 ++-- .../provider-revyl/src/deployment.test.ts | 175 ++++++++++++ packages/provider-revyl/src/deployment.ts | 257 ++++++++++++++++++ .../provider-revyl/src/facts-runtime.test.ts | 6 +- packages/provider-revyl/src/facts-runtime.ts | 12 +- .../src/platform-runtime.test.ts | 90 +++++- .../provider-revyl/src/platform-runtime.ts | 34 ++- packages/provider-revyl/src/revyl-client.ts | 77 ++++++ packages/provider-revyl/src/revyl-types.ts | 15 + packages/provider-revyl/src/runtime.ts | 15 + packages/provider-revyl/tsconfig.json | 3 + pnpm-lock.yaml | 3 + website/docs/docs/capabilities.md | 4 +- website/docs/docs/revyl.md | 27 +- 17 files changed, 743 insertions(+), 61 deletions(-) create mode 100644 packages/provider-revyl/src/deployment.test.ts create mode 100644 packages/provider-revyl/src/deployment.ts diff --git a/packages/provider-revyl/README.md b/packages/provider-revyl/README.md index e59b94951e..d55032a520 100644 --- a/packages/provider-revyl/README.md +++ b/packages/provider-revyl/README.md @@ -9,7 +9,8 @@ npm install -g agent-device agent-device plugins add @agent-device/revyl export REVYL_API_KEY=your-api-key export AGENT_DEVICE_SESSION=checkout-ios -agent-device connect revyl --platform ios --provider-app https://apps.example.com/MyApp-simulator.zip +agent-device connect revyl --platform ios +agent-device install com.example.app ./build/MyApp.app agent-device open com.example.app agent-device snapshot -i agent-device close diff --git a/packages/provider-revyl/package.json b/packages/provider-revyl/package.json index 8fbb597a4f..681f2c8bf7 100644 --- a/packages/provider-revyl/package.json +++ b/packages/provider-revyl/package.json @@ -24,9 +24,10 @@ "devDependencies": { "@agent-device/capture-kit": "workspace:*", "@agent-device/contracts": "workspace:*", + "@agent-device/host-kit": "workspace:*", "@agent-device/kernel": "workspace:*", - "@agent-device/provision-kit": "workspace:*", "@agent-device/provider-webdriver": "workspace:*", + "@agent-device/provision-kit": "workspace:*", "@agent-device/test-kit": "workspace:*", "agent-device": "workspace:*" }, diff --git a/packages/provider-revyl/src/connection.test.ts b/packages/provider-revyl/src/connection.test.ts index 1968170e12..f197e26c14 100644 --- a/packages/provider-revyl/src/connection.test.ts +++ b/packages/provider-revyl/src/connection.test.ts @@ -77,6 +77,18 @@ test('verify reports a profile that names no device or OS version', async () => }); }); +test('verify reports a profile without an app as one the device starts without', async () => { + const fixture = await backend(); + const result = await verifyRevylProfile( + { apiKey: 'test-key', apiUrl: fixture.backendUrl }, + '0.0.0-test', + 'ios', + {}, + ); + assert.equal(result.app.status, 'deferred'); + assert.equal(result.app.reference, undefined); +}); + test('verify reports a rejected key as an unauthorized error before checking the app', async () => { const fixture = await backend({ respond: { 'GET /api/v1/entity/users/get_user_uuid': { status: 401, body: { error: 'nope' } } }, @@ -201,10 +213,19 @@ test('resolve keeps the device, OS version and app URL and refuses a non-mobile ); }); +test('resolve keeps a profile without an app, so the device starts with none', () => { + const connection = createRevylConnection(HOST); + const resolved = connection.resolve({ + flags: { platform: 'android' } as CliFlags, + cwd: '/tmp', + } as never); + assert.equal('providerApp' in resolved.profile, false); + assert.equal('extraFlags' in resolved, false); +}); + test('resolve refuses an app that is not an https URL', () => { const connection = createRevylConnection(HOST); for (const providerApp of [ - undefined, './build/app.ipa', 'https://user@apps.test/app.zip', 'http://apps.test/app.zip', diff --git a/packages/provider-revyl/src/connection.ts b/packages/provider-revyl/src/connection.ts index 56607d0c8f..7f9bb1bf08 100644 --- a/packages/provider-revyl/src/connection.ts +++ b/packages/provider-revyl/src/connection.ts @@ -26,7 +26,7 @@ export function createRevylConnection(host: ProviderPluginHost) { rejectRefusedProviderProfileFields(flags, REVYL_PROFILE_FIELDS); requireRevylCredentials(host.env, `connect ${REVYL_PROVIDER}`); const platform = requireConnectPlatform(flags); - const app = requireAppUrl(flags.providerApp, host); + const app = optionalAppUrl(flags.providerApp, host); // Stored through the same canonicalizer allocation reads with, so the profile and the // `start_device` body cannot differ by surrounding whitespace. const deviceModel = revylTextFlag(flags.device); @@ -36,10 +36,10 @@ export function createRevylConnection(host: ProviderPluginHost) { leaseProvider: REVYL_PROVIDER, platform, ...(deviceModel === undefined ? {} : { device: deviceModel }), - providerApp: app, + ...(app === undefined ? {} : { providerApp: app }), ...(osVersion === undefined ? {} : { providerOsVersion: osVersion }), }, - extraFlags: { providerApp: app }, + ...(app === undefined ? {} : { extraFlags: { providerApp: app } }), }; }, verify: async ({ flags }: { flags: CliFlags }) => { @@ -48,12 +48,13 @@ export function createRevylConnection(host: ProviderPluginHost) { rejectRefusedProviderProfileFields(flags, REVYL_PROFILE_FIELDS); const deviceModel = revylTextFlag(flags.device); const osVersion = revylTextFlag(flags.providerOsVersion); + const appUrl = revylTextFlag(flags.providerApp); return await verifyRevylProfile( requireRevylCredentials(host.env, `connect ${REVYL_PROVIDER}`), host.clientVersion, requireResolvedProfilePlatform(flags.platform, REVYL_SERVICE), { - appUrl: requireAppReference(flags.providerApp), + ...(appUrl === undefined ? {} : { appUrl }), ...(deviceModel === undefined ? {} : { deviceModel }), ...(osVersion === undefined ? {} : { osVersion }), }, @@ -64,15 +65,16 @@ export function createRevylConnection(host: ProviderPluginHost) { /** * Proves the credentials against the backend and reports the selected profile, both before a device is - * rented. Revyl starts a device from the platform, an optional model and OS version, and an app URL, so - * every one of those is what the verification reports back; nothing about them can be checked against - * a catalog, because Revyl picks the device from its own pool at start time. + * rented. Revyl starts a device from the platform, an optional model and OS version, and an optional app + * URL, so every one of those is what the verification reports back; nothing about them can be checked + * against a catalog, because Revyl picks the device from its own pool at start time. Without an app URL + * the device starts with no app, and `install` puts a local build on it. */ export async function verifyRevylProfile( credentials: RevylCredentials, clientVersion: string, platform: RevylPlatform, - profile: Readonly<{ appUrl: string; deviceModel?: string; osVersion?: string }>, + profile: Readonly<{ appUrl?: string; deviceModel?: string; osVersion?: string }>, ): Promise { const client = createRevylClient({ apiKey: credentials.apiKey, @@ -80,7 +82,7 @@ export async function verifyRevylProfile( clientVersion, }); await client.verifyCredentials(); - if (!isRevylAppUrl(profile.appUrl)) { + if (profile.appUrl !== undefined && !isRevylAppUrl(profile.appUrl)) { throw new AppError( 'INVALID_ARGS', `${REVYL_SERVICE} installs the app from a URL, so --provider-app must be an https URL.`, @@ -101,11 +103,17 @@ export async function verifyRevylProfile( ...(profile.osVersion === undefined ? {} : { osVersion: profile.osVersion }), message: `${REVYL_SERVICE} assigns a device of this platform when the session starts; a model or OS version it has no device for is reported then.`, }, - app: { - status: 'configured', - reference: profile.appUrl, - message: `App URL configured; ${REVYL_SERVICE} fetches and installs it when the session starts.`, - }, + app: + profile.appUrl === undefined + ? { + status: 'deferred', + message: `No app URL; the device starts without an app. Run install to add a local build.`, + } + : { + status: 'configured', + reference: profile.appUrl, + message: `App URL configured; ${REVYL_SERVICE} fetches and installs it when the session starts.`, + }, }; } @@ -133,14 +141,10 @@ function requireConnectPlatform(flags: CliFlags): RevylPlatform { }); } -function requireAppUrl(app: string | undefined, host: ProviderPluginHost): string { +/** An app URL is optional; one that is given must be a URL Revyl can download. */ +function optionalAppUrl(app: string | undefined, host: ProviderPluginHost): string | undefined { const value = app?.trim(); - if (!value) { - throw host.createError( - 'INVALID_ARGS', - `connect ${REVYL_PROVIDER} requires --provider-app with the build to install.`, - ); - } + if (!value) return undefined; if (!isRevylAppUrl(value)) { throw host.createError( 'INVALID_ARGS', @@ -149,14 +153,3 @@ function requireAppUrl(app: string | undefined, host: ProviderPluginHost): strin } return value; } - -/** Reads the app reference back out of the resolved profile verify is handed. */ -function requireAppReference(app: string | undefined): string { - const value = app?.trim(); - if (!value) { - throw new AppError('COMMAND_FAILED', `${REVYL_SERVICE} profile missed its app URL.`, { - hint: 'Reconnect with --provider-app .', - }); - } - return value; -} diff --git a/packages/provider-revyl/src/deployment.test.ts b/packages/provider-revyl/src/deployment.test.ts new file mode 100644 index 0000000000..784f2a42c8 --- /dev/null +++ b/packages/provider-revyl/src/deployment.test.ts @@ -0,0 +1,175 @@ +import assert from 'node:assert/strict'; +import fs from 'node:fs/promises'; +import path from 'node:path'; +import { afterEach, test } from 'vitest'; +import { mkdtempForTest } from '@agent-device/test-kit'; +import { AppError } from '@agent-device/kernel/errors'; +import { + revylLease, + startRevylFixtureBackend, + type RevylFixtureBackend, +} from './revyl-backend.fixtures.ts'; +import { deployRevylApp } from './deployment.ts'; +import { revylSessionIdForLease } from './session-identity.ts'; + +const openBackends: RevylFixtureBackend[] = []; + +afterEach(async () => { + await Promise.all(openBackends.splice(0).map((fixture) => fixture.close())); +}); + +const UPLOAD_PATH = '/api/storage/put'; +/** The host environment the packer runs `tar` with. */ +const ENV = { PATH: '/usr/bin:/bin' }; +const DOWNLOAD_URL = 'https://storage.test/session-build'; + +/** A backend whose session accepts one upload and reports the install with `result`. */ +async function installingBackend(result: Record, status = 'completed') { + const sessionId = revylSessionIdForLease('lease-1'); + let backendUrl = ''; + const fixture = await startRevylFixtureBackend({ + respond: { + [`POST /api/v1/execution/device-sessions/${sessionId}/artifacts/upload-url`]: () => ({ + body: { upload_url: `${backendUrl}${UPLOAD_PATH}`, download_url: DOWNLOAD_URL }, + }), + [`PUT ${UPLOAD_PATH}`]: { body: {} }, + 'POST /api/v1/execution/device-proxy/run-1/install_async': { + body: { install_id: 'install-1', status: 'accepted' }, + }, + 'GET /api/v1/execution/device-proxy/run-1/install_status/install-1': { + body: { install_id: 'install-1', status, result }, + }, + }, + }); + backendUrl = fixture.backendUrl; + openBackends.push(fixture); + const runtime = fixture.createRuntime(); + return { fixture, runtime }; +} + +async function liveSession( + runtime: Awaited>['runtime'], + platform: 'ios' | 'android', +) { + await runtime.leaseLifecycle?.allocate?.(revylLease(platform)); + const device = ( + await runtime.deviceInventoryProvider?.({ + leaseProvider: 'revyl', + leaseId: 'lease-1', + platform, + }) + )?.[0]; + if (!device) throw new Error('Expected the live session to be listed.'); + const session = runtime.getDeploymentSession(device); + if (!session) throw new Error('Expected a live deployment session.'); + return { device, session }; +} + +test('an Android install uploads the apk to the session and installs it from there', async () => { + const { fixture, runtime } = await installingBackend({ + success: true, + package_name: 'com.example.app', + }); + const { session } = await liveSession(runtime, 'android'); + const dir = await mkdtempForTest('revyl-deploy-'); + const apk = path.join(dir, 'app-debug.apk'); + await fs.writeFile(apk, 'apk-bytes'); + + const result = await deployRevylApp(session, apk, ENV, new AbortController().signal); + + assert.deepEqual(result, { packageName: 'com.example.app', launchTarget: 'com.example.app' }); + assert.deepEqual(fixture.bodyFor('upload-url'), { + file_size: 9, + content_type: 'application/vnd.android.package-archive', + }); + const upload = fixture.requests.find((request) => request.path === UPLOAD_PATH); + assert.equal(upload?.method, 'PUT'); + // The presigned URL carries its own authorization; the API key never goes to storage. + assert.equal(upload?.authorization, undefined); + assert.deepEqual(fixture.bodyFor('install_async'), { + app_url: DOWNLOAD_URL, + platform: 'android', + }); +}); + +test('an iOS simulator .app directory is packed before it is uploaded', async () => { + const { fixture, runtime } = await installingBackend({ + success: true, + bundle_id: 'com.example.app', + }); + const { session } = await liveSession(runtime, 'ios'); + const dir = await mkdtempForTest('revyl-deploy-'); + const app = path.join(dir, 'Example.app'); + await fs.mkdir(app); + await fs.writeFile(path.join(app, 'Info.plist'), 'plist'); + + const result = await deployRevylApp(session, app, ENV, new AbortController().signal); + + assert.deepEqual(result, { bundleId: 'com.example.app', launchTarget: 'com.example.app' }); + assert.equal(fixture.bodyFor('upload-url').content_type, 'application/gzip'); +}); + +test('a build Revyl cannot install on the platform is refused before anything is uploaded', async () => { + const { fixture, runtime } = await installingBackend({ success: true }); + const { session } = await liveSession(runtime, 'ios'); + const dir = await mkdtempForTest('revyl-deploy-'); + const ipa = path.join(dir, 'Example.ipa'); + await fs.writeFile(ipa, 'ipa'); + + await assert.rejects( + () => deployRevylApp(session, ipa, ENV, new AbortController().signal), + (error: unknown) => + error instanceof AppError && error.details?.reason === 'unsupported_app_artifact', + ); + assert.equal( + fixture.paths().some((request) => request.includes('upload-url')), + false, + ); +}); + +test('an install the worker reports as failed is an error that carries its reason', async () => { + const { runtime } = await installingBackend( + { success: false, error: 'not a simulator build' }, + 'failed', + ); + const { session } = await liveSession(runtime, 'android'); + const dir = await mkdtempForTest('revyl-deploy-'); + const apk = path.join(dir, 'app.apk'); + await fs.writeFile(apk, 'apk'); + + await assert.rejects( + () => deployRevylApp(session, apk, ENV, new AbortController().signal), + (error: unknown) => + error instanceof AppError && error.details?.providerDetail === 'not a simulator build', + ); +}); + +test('an install that outlasts its budget reports an unconfirmed install, not a hang', async () => { + const { runtime } = await installingBackend({}, 'running'); + const { session } = await liveSession(runtime, 'android'); + const dir = await mkdtempForTest('revyl-deploy-'); + const apk = path.join(dir, 'app.apk'); + await fs.writeFile(apk, 'apk'); + + await assert.rejects( + () => deployRevylApp(session, apk, ENV, new AbortController().signal, 200), + (error: unknown) => + error instanceof AppError && error.details?.reason === 'provider-unconfirmed', + ); +}); + +test('a canceled install reports the cancellation', async () => { + const { runtime } = await installingBackend({}, 'running'); + const { session } = await liveSession(runtime, 'android'); + const dir = await mkdtempForTest('revyl-deploy-'); + const apk = path.join(dir, 'app.apk'); + await fs.writeFile(apk, 'apk'); + const controller = new AbortController(); + + const install = deployRevylApp(session, apk, ENV, controller.signal); + setTimeout(() => controller.abort(), 100); + await assert.rejects( + () => install, + (error: unknown) => error instanceof AppError && error.details?.reason === 'request_canceled', + ); +}); diff --git a/packages/provider-revyl/src/deployment.ts b/packages/provider-revyl/src/deployment.ts new file mode 100644 index 0000000000..4f34cb61db --- /dev/null +++ b/packages/provider-revyl/src/deployment.ts @@ -0,0 +1,257 @@ +import { randomUUID } from 'node:crypto'; +import fs from 'node:fs/promises'; +import os from 'node:os'; +import path from 'node:path'; +import { setTimeout as sleep } from 'node:timers/promises'; +import type { + AppDeploymentResult, + MaterializedAppSource, +} from '@agent-device/contracts/app-deployment-runtime'; +import { runCmd } from '@agent-device/host-kit/command'; +import { AppError } from '@agent-device/kernel/errors'; +import type { EnvMap } from '@agent-device/kernel/source-value'; +import type { RevylClient } from './revyl-client.ts'; +import type { RevylWorkerActionResponse } from './revyl-types.ts'; + +/** + * The whole install's budget: packing, upload, and Revyl's install. It stays inside the daemon's + * share of the install command's 480 s envelope, so the plugin reports its own timeout before the + * client gives up and resets the daemon that holds the rented device. + */ +const REVYL_INSTALL_BUDGET_MS = 420_000; +const POLL_BASE_DELAY_MS = 500; +const POLL_MAX_DELAY_MS = 5_000; + +/** What an install reads from the session it targets. */ +export type RevylDeploymentSession = Readonly<{ + runId: string; + sessionId: string; + platform: 'ios' | 'android'; + client: RevylClient; +}>; + +type PackagedBuild = Readonly<{ + filePath: string; + contentType: string; + cleanup(): Promise; +}>; + +/** + * Installs a local build on a running Revyl session: the build goes to the session's own storage, and + * the worker installs it from there. A simulator `.app` directory is packed as a gzip tar, which Revyl + * accepts for iOS the same as a zip. + */ +export async function deployRevylApp( + session: RevylDeploymentSession, + appPath: string, + env: Readonly, + signal: AbortSignal, + budgetMs = REVYL_INSTALL_BUDGET_MS, +): Promise { + const budget = AbortSignal.timeout(budgetMs); + const scoped = AbortSignal.any([signal, budget]); + try { + return await uploadAndInstall(session, appPath, env, scoped); + } catch (error) { + if (signal.aborted) + throw installStopped('request_canceled', 'The install was canceled.', error); + if (budget.aborted) { + throw installStopped( + 'provider-unconfirmed', + `Revyl did not finish the install within ${budgetMs / 1000} s.`, + error, + ); + } + throw error; + } +} + +async function uploadAndInstall( + session: RevylDeploymentSession, + appPath: string, + env: Readonly, + signal: AbortSignal, +): Promise { + const build = await packageBuild(session.platform, appPath, env, signal); + try { + const body = new Uint8Array(await fs.readFile(build.filePath)); + const upload = await session.client.createSessionArtifactUpload( + session.sessionId, + body.byteLength, + build.contentType, + signal, + ); + await session.client.uploadSessionArtifact(upload.upload_url, body, build.contentType, signal); + return deploymentResult( + session.platform, + await installAndWait(session, upload.download_url, signal), + ); + } finally { + await build.cleanup(); + } +} + +function installStopped(reason: string, message: string, cause: unknown): AppError { + return new AppError( + 'COMMAND_FAILED', + message, + { + reason, + hint: 'Check the session in Revyl; an install it already accepted may still complete.', + }, + cause, + ); +} + +/** The build files Revyl installs as they are, by platform: suffix, then upload content type. */ +const FILE_BUILDS: Readonly>> = { + ios: [ + ['.zip', 'application/zip'], + ['.tar.gz', 'application/gzip'], + ['.tgz', 'application/gzip'], + ], + android: [['.apk', 'application/vnd.android.package-archive']], +}; + +async function packageBuild( + platform: 'ios' | 'android', + appPath: string, + env: Readonly, + signal: AbortSignal, +): Promise { + const stat = await fs.stat(appPath); + const lower = appPath.toLowerCase().replace(/[\\/]+$/, ''); + if (platform === 'ios' && stat.isDirectory() && lower.endsWith('.app')) { + return await packAppBundle(appPath, env, signal); + } + const match = stat.isFile() + ? FILE_BUILDS[platform].find(([suffix]) => lower.endsWith(suffix)) + : undefined; + if (match) return fileBuild(appPath, match[1]); + throw unsupportedBuild(platform, appPath); +} + +/** Packs a simulator `.app` directory as a gzip tar, which Revyl accepts for iOS. */ +async function packAppBundle( + appPath: string, + env: Readonly, + signal: AbortSignal, +): Promise { + const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), `agent-device-revyl-${randomUUID()}-`)); + const archive = path.join(tempDir, `${path.basename(appPath)}.tar.gz`); + const cleanup = async () => await fs.rm(tempDir, { recursive: true, force: true }); + try { + await runCmd('tar', ['czf', archive, '-C', path.dirname(appPath), path.basename(appPath)], { + // Keeps macOS tar from adding AppleDouble `._` entries to the bundle. + env: { ...env, COPYFILE_DISABLE: '1' }, + signal, + }); + } catch (error) { + await cleanup(); + throw error; + } + return { filePath: archive, contentType: 'application/gzip', cleanup }; +} + +function unsupportedBuild(platform: 'ios' | 'android', appPath: string): AppError { + return platform === 'ios' + ? new AppError( + 'INVALID_ARGS', + 'Revyl installs an iOS simulator build: a .app directory, or one zipped or tarred.', + { + reason: 'unsupported_app_artifact', + appPath, + hint: 'Build for the iOS simulator; a device .ipa does not run on a simulator.', + }, + ) + : new AppError('INVALID_ARGS', 'Revyl installs an Android build from an .apk file.', { + reason: 'unsupported_app_artifact', + appPath, + hint: 'Pass the .apk the build produced.', + }); +} + +function fileBuild(filePath: string, contentType: string): PackagedBuild { + return { filePath, contentType, cleanup: async () => undefined }; +} + +async function installAndWait( + session: RevylDeploymentSession, + appUrl: string, + signal: AbortSignal, +): Promise { + const accepted = await session.client.startInstall( + session.runId, + { app_url: appUrl, platform: session.platform }, + signal, + ); + const installId = accepted.install_id?.trim(); + if (accepted.status !== 'accepted' || !installId) { + throw new AppError('COMMAND_FAILED', 'Revyl did not accept the app install.', { + reason: 'provider-refused', + ...(accepted.status === undefined ? {} : { providerDetail: accepted.status }), + }); + } + let delay = POLL_BASE_DELAY_MS; + for (;;) { + await sleep(delay, undefined, { signal }); + const status = await session.client.getInstallStatus(session.runId, installId, signal); + if ( + status.status === 'completed' || + status.status === 'failed' || + status.status === 'cancelled' + ) { + return requireInstalled(status.status, status.result ?? undefined); + } + if (status.status !== 'running') { + throw new AppError('COMMAND_FAILED', `Revyl reported install status "${status.status}".`, { + reason: 'provider-refused', + installId, + }); + } + delay = Math.min(delay * 2, POLL_MAX_DELAY_MS); + } +} + +function requireInstalled( + status: string, + result: RevylWorkerActionResponse | undefined, +): RevylWorkerActionResponse { + const error = typeof result?.error === 'string' && result.error !== '' ? result.error : undefined; + const succeeded = result?.success ?? result?.Success; + if (status === 'completed' && result !== undefined && succeeded !== false && !error) + return result; + throw new AppError( + 'COMMAND_FAILED', + `Revyl could not install the app${error === undefined ? '' : `: ${error}`}`, + { + reason: 'provider-refused', + installStatus: status, + ...(error === undefined ? {} : { providerDetail: error }), + }, + ); +} + +function deploymentResult( + platform: 'ios' | 'android', + result: RevylWorkerActionResponse, +): AppDeploymentResult { + const id = + (platform === 'ios' ? result.bundle_id : (result.package_name ?? result.bundle_id)) ?? + undefined; + if (!id) return {}; + return platform === 'ios' + ? { bundleId: id, launchTarget: id } + : { packageName: id, launchTarget: id }; +} + +/** The app a materialized build names, read before Revyl installs it. */ +export function materializedIdentity(artifact: MaterializedAppSource): AppDeploymentResult { + const id = artifact.bundleId ?? artifact.packageName; + return { + ...(artifact.bundleId ? { bundleId: artifact.bundleId } : {}), + ...(artifact.packageName ? { packageName: artifact.packageName } : {}), + ...(artifact.appName ? { appName: artifact.appName } : {}), + ...(id ? { launchTarget: id } : {}), + }; +} diff --git a/packages/provider-revyl/src/facts-runtime.test.ts b/packages/provider-revyl/src/facts-runtime.test.ts index f6a4f95340..4015b33bc9 100644 --- a/packages/provider-revyl/src/facts-runtime.test.ts +++ b/packages/provider-revyl/src/facts-runtime.test.ts @@ -62,8 +62,8 @@ const EXPECTED_CELLS = { captureSnapshotWithCustomActions: 'mode', clearRuntimeHints: 'mode', configureProviderPortReverse: 'mode', - deployApp: 'mode', - deployMaterializedApp: 'mode', + deployApp: 'available', + deployMaterializedApp: 'available', dismissAlert: 'mode', fillRef: 'mode', findText: 'mode', @@ -74,7 +74,7 @@ const EXPECTED_CELLS = { keyboardEnter: 'mode', keyboardStatus: 'mode', listApps: 'mode', - materializeAppSource: 'mode', + materializeAppSource: 'available', mediaFastForward: 'mode', mediaNext: 'mode', mediaPlayPause: 'mode', diff --git a/packages/provider-revyl/src/facts-runtime.ts b/packages/provider-revyl/src/facts-runtime.ts index 0def664276..f494cf6d01 100644 --- a/packages/provider-revyl/src/facts-runtime.ts +++ b/packages/provider-revyl/src/facts-runtime.ts @@ -21,11 +21,6 @@ import { REVYL_TELEPHONY_UNAVAILABLE, } from './interaction-operations.ts'; -/** Revyl installs the app it is given when the session starts; the worker's install action takes a URL. */ -const installUnavailable = unavailableFact( - 'unsupported-provider-mode', - 'Revyl installs an app when the session starts. Pass --provider-app to connect, and run open afterwards.', -); const uninstallUnavailable = unavailableFact( 'unsupported-provider-mode', 'Revyl does not uninstall an app from a session.', @@ -153,9 +148,10 @@ export function revylFacts(device: DeviceInfo): RuntimeFacts true, hasLiveSession: () => options.hasLiveSession, getInteractor: () => options.interactor, + getDeploymentSession: () => options.deploymentSession, }); } @@ -121,3 +130,82 @@ test('a facts inspection of an unowned device reports the target refusal, not a assert.equal(facts?.operations.openApplication.available, false); assert.equal(facts?.operations.openApplication.reason, 'unsupported-provider-mode'); }); + +/** A session whose installs succeed without naming the app, so the materializer's reading shows. */ +function installingSession(installs: string[]): RevylDeploymentSession { + const client = { + createSessionArtifactUpload: async () => ({ + upload_url: 'https://storage.test/put', + download_url: 'https://storage.test/get', + }), + uploadSessionArtifact: async () => undefined, + startInstall: async (_runId: string, body: { app_url: string }) => { + installs.push(body.app_url); + return { install_id: 'install-1', status: 'accepted' }; + }, + getInstallStatus: async () => ({ status: 'completed', result: { success: true } }), + } as unknown as RevylClient; + return { + runId: 'run-1', + sessionId: 'session-1', + platform: 'ios', + client, + }; +} + +test('a live session installs a build through its deployment operations', async () => { + const dir = await mkdtempForTest('revyl-platform-deploy-'); + const build = path.join(dir, 'Example.zip'); + await fs.writeFile(build, 'zip'); + const artifact: MaterializedAppSource = { + installablePath: build, + bundleId: 'com.example.app', + appName: 'Example', + cleanup: async () => undefined, + }; + const installs: string[] = []; + const binding = await bind( + owner({ + hasLiveSession: true, + deploymentSession: installingSession(installs), + host: { + ...HOST, + hostEnvironment: { env: {}, cwd: dir }, + appleDeployment: { prepareArtifact: async () => artifact }, + } as unknown as PlatformRuntimeHost, + }), + ); + + const materialized = await binding.operations.materializeAppSource!({ + source: { kind: 'url', url: 'https://apps.test/Example.zip' }, + }); + assert.equal(materialized, artifact); + assert.deepEqual(await binding.operations.deployMaterializedApp!({ artifact }), { + bundleId: 'com.example.app', + appName: 'Example', + launchTarget: 'com.example.app', + }); + assert.deepEqual( + await binding.operations.deployApp!({ + app: 'com.example.app', + appPath: build, + replaceExisting: false, + }), + {}, + ); + assert.deepEqual(installs, ['https://storage.test/get', 'https://storage.test/get']); +}); + +test('a deployment operation whose session ended refuses rather than installing', async () => { + const binding = await bind(owner({ hasLiveSession: true })); + await assert.rejects( + () => + binding.operations.deployApp!({ + app: 'com.example.app', + appPath: '/tmp/x.zip', + replaceExisting: false, + }), + (error: unknown) => + error instanceof AppError && error.details?.reason === 'provider-session-unavailable', + ); +}); diff --git a/packages/provider-revyl/src/platform-runtime.ts b/packages/provider-revyl/src/platform-runtime.ts index 8a03962ac8..7570aa55d4 100644 --- a/packages/provider-revyl/src/platform-runtime.ts +++ b/packages/provider-revyl/src/platform-runtime.ts @@ -19,6 +19,7 @@ import { bindAdmittedProviderInteractorOperations } from '@agent-device/contract import { bindRevylInteractionOperations } from './interaction-operations.ts'; import { bindRevylApplicationLifecycle } from './lifecycle.ts'; import { revylFacts, revylUnavailableCells, revylLifecycleFacts } from './facts-runtime.ts'; +import { deployRevylApp, materializedIdentity, type RevylDeploymentSession } from './deployment.ts'; export type RevylPlatformRuntimeOwnerOptions = Readonly<{ host: PlatformRuntimeHost; @@ -26,12 +27,13 @@ export type RevylPlatformRuntimeOwnerOptions = Readonly<{ ownsDevice(device: DeviceInfo): boolean; hasLiveSession(device: DeviceInfo): boolean; getInteractor(device: DeviceInfo, runner?: RunnerContext): Interactor | undefined; + getDeploymentSession(device: DeviceInfo): RevylDeploymentSession | undefined; }>; /** * The owner a Revyl runtime hands the host. It owns one thing per device: the interactor bound to - * that device's live session. Every operation is either an admitted interactor call or a classified - * refusal, which is why there is no app-log, deployment, or recording machinery beside it. + * that device's live session. Every operation is either an admitted interactor call, an install + * through the session's storage, or a classified refusal. */ export function createRevylPlatformRuntimeOwner( options: RevylPlatformRuntimeOwnerOptions, @@ -103,6 +105,7 @@ function bindRevylRuntime( getInteractor: options.getInteractor, presentIosAcquisition: options.host.snapshot.presentIosAcquisition, }), + ...bindRevylDeployment(options, device, signal), ...bindAdmittedProviderInteractorOperations({ device, signal, @@ -136,3 +139,30 @@ function admittedOperations( } return admitted; } + +function bindRevylDeployment( + options: RevylPlatformRuntimeOwnerOptions, + device: DeviceInfo, + signal: AbortSignal, +): Pick { + const env = () => options.host.hostEnvironment.env; + const session = () => { + const live = options.getDeploymentSession(device); + if (live) return live; + throw new AppError('UNSUPPORTED_OPERATION', 'Revyl provider session is no longer live.', { + reason: 'provider-session-unavailable', + }); + }; + return { + deployApp: async (input) => await deployRevylApp(session(), input.appPath, env(), signal), + materializeAppSource: async (input) => + device.platform === 'apple' + ? await options.host.appleDeployment.prepareArtifact(input, { signal }) + : await options.host.androidDeployment.prepareArtifact(input, { signal }), + // What Revyl reports wins; the materializer's reading fills in what it leaves out. + deployMaterializedApp: async ({ artifact }) => ({ + ...materializedIdentity(artifact), + ...(await deployRevylApp(session(), artifact.installablePath, env(), signal)), + }), + }; +} diff --git a/packages/provider-revyl/src/revyl-client.ts b/packages/provider-revyl/src/revyl-client.ts index 86b2dd6fae..d61d663b4e 100644 --- a/packages/provider-revyl/src/revyl-client.ts +++ b/packages/provider-revyl/src/revyl-client.ts @@ -4,6 +4,9 @@ import net from 'node:net'; import { setTimeout as sleep } from 'node:timers/promises'; import type { RevylDeviceSessionStopResponse, + RevylInstallAccepted, + RevylInstallStatus, + RevylSessionArtifactUpload, RevylStartDeviceRequest, RevylStartDeviceResponse, RevylWorkerActionResponse, @@ -23,6 +26,8 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 30_000; /** How long `start_device` may take to answer: Revyl assigns a worker and boots the device in it. */ export const REVYL_START_DEVICE_TIMEOUT_MS = 120_000; const RETRY_DELAYS_MS = [500, 1_500] as const; +/** How long one build upload may take to reach Revyl's storage; the install's whole budget. */ +const ARTIFACT_UPLOAD_TIMEOUT_MS = 420_000; /** Device-proxy actions Revyl answers to a GET; every other action is a POST. */ const DEVICE_PROXY_GET_ACTIONS = new Set(['screenshot', 'health', 'device_info', 'hierarchy']); @@ -88,6 +93,30 @@ export type RevylClient = Readonly<{ signal?: AbortSignal, ): Promise; stopDeviceSession(sessionId: string): Promise; + /** Presigned URLs for one build the session installs. */ + createSessionArtifactUpload( + sessionId: string, + fileSize: number, + contentType: string, + signal?: AbortSignal, + ): Promise; + /** Sends the build to the presigned URL; the URL carries its own authorization. */ + uploadSessionArtifact( + uploadUrl: string, + body: Uint8Array, + contentType: string, + signal?: AbortSignal, + ): Promise; + startInstall( + workflowRunId: string, + body: unknown, + signal?: AbortSignal, + ): Promise; + getInstallStatus( + workflowRunId: string, + installId: string, + signal?: AbortSignal, + ): Promise; /** Cheap enough to run on every `connect`: it authenticates without starting a device. */ verifyCredentials(signal?: AbortSignal): Promise; }>; @@ -209,6 +238,54 @@ export function createRevylClient(options: RevylClientOptions): RevylClient { assertLifecycleAccepted('stop', response); return response; }, + createSessionArtifactUpload(sessionId, fileSize, contentType, signal) { + return json({ + method: 'POST', + path: `/api/v1/execution/device-sessions/${encodeURIComponent(sessionId)}/artifacts/upload-url`, + body: { file_size: fileSize, content_type: contentType }, + route: 'session', + ...(signal === undefined ? {} : { signal }), + }); + }, + async uploadSessionArtifact(uploadUrl, body, contentType, signal) { + const timeout = AbortSignal.timeout(ARTIFACT_UPLOAD_TIMEOUT_MS); + let response: Response; + try { + response = await fetchImpl(uploadUrl, { + method: 'PUT', + headers: { 'Content-Type': contentType }, + body, + redirect: 'error', + signal: signal ? AbortSignal.any([signal, timeout]) : timeout, + }); + } catch (error) { + throw new AppError( + 'COMMAND_FAILED', + 'Revyl storage did not accept the app upload.', + { reason: 'provider-unreachable' }, + error, + ); + } + if (!response.ok) { + throw new AppError( + 'COMMAND_FAILED', + `Revyl storage refused the app upload with HTTP ${response.status}.`, + { reason: 'provider-refused', status: response.status }, + ); + } + }, + startInstall(workflowRunId, body, signal) { + return json({ + ...workerRequest(workflowRunId, 'install_async', signal), + body, + }); + }, + getInstallStatus(workflowRunId, installId, signal) { + return json({ + ...workerRequest(workflowRunId, `install_status/${encodeURIComponent(installId)}`, signal), + method: 'GET', + }); + }, async verifyCredentials(signal) { await json({ method: 'GET', diff --git a/packages/provider-revyl/src/revyl-types.ts b/packages/provider-revyl/src/revyl-types.ts index 28366603ef..58f646a192 100644 --- a/packages/provider-revyl/src/revyl-types.ts +++ b/packages/provider-revyl/src/revyl-types.ts @@ -69,3 +69,18 @@ export type RevylWorkerActionResponse = Readonly<{ bundle_id?: string | null; package_name?: string | null; }>; + +/** Presigned URLs for one build the session installs; Revyl drops the object with the session. */ +export type RevylSessionArtifactUpload = Readonly<{ + upload_url: string; + download_url: string; +}>; + +/** `install_async` accepts an install and names it; `install_status` reports it until it ends. */ +export type RevylInstallAccepted = Readonly<{ install_id?: string; status?: string }>; + +export type RevylInstallStatus = Readonly<{ + install_id?: string; + status?: string; + result?: RevylWorkerActionResponse | null; +}>; diff --git a/packages/provider-revyl/src/runtime.ts b/packages/provider-revyl/src/runtime.ts index 75eabce4e5..bf398afef8 100644 --- a/packages/provider-revyl/src/runtime.ts +++ b/packages/provider-revyl/src/runtime.ts @@ -43,6 +43,7 @@ import { providerRuntimeOwner } from '@agent-device/contracts/platform-runtime'; import { resolveRevylRuntimeInstance } from './runtime-instance.ts'; import { revylSessionIdForLease } from './session-identity.ts'; import type { RevylStartRequest } from './session-allocation.ts'; +import type { RevylDeploymentSession } from './deployment.ts'; /** What one lease's start asks Revyl for, with the platform the lease was admitted for. */ type RevylLeaseRequest = RevylStartRequest & Readonly<{ platform: RevylPlatform }>; @@ -69,6 +70,7 @@ export type RevylRuntimeRegistration = Readonly<{ export type RevylRuntime = ProviderDeviceRuntime & { recoverExpiredLease: ProviderExpiredLeaseRecovery; hasLiveSession(device: DeviceInfo): boolean; + getDeploymentSession(device: DeviceInfo): RevylDeploymentSession | undefined; }; /** @@ -149,6 +151,18 @@ class RevylRuntimeImplementation implements ProviderDeviceRuntime { return session ? createRevylInteractor(session, runner?.signal) : undefined; } + getDeploymentSession(device: DeviceInfo): RevylDeploymentSession | undefined { + const session = this.sessionForDevice(device); + return session + ? { + runId: session.runId, + sessionId: session.sessionId, + platform: session.platform, + client: session.client, + } + : undefined; + } + async shutdown(): Promise { await this.leases.shutdown(); } @@ -339,6 +353,7 @@ async function loadRevylPlatformRuntime( ownsDevice: (device) => runtime.ownsDevice(device), hasLiveSession: (device) => runtime.hasLiveSession(device), getInteractor: (device, runner) => runtime.getInteractor(device, runner), + getDeploymentSession: (device) => runtime.getDeploymentSession(device), }); } diff --git a/packages/provider-revyl/tsconfig.json b/packages/provider-revyl/tsconfig.json index 71c7fd8f75..2ec5eba134 100644 --- a/packages/provider-revyl/tsconfig.json +++ b/packages/provider-revyl/tsconfig.json @@ -21,6 +21,9 @@ { "path": "../contracts" }, + { + "path": "../host-kit" + }, { "path": "../kernel" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 655e62ee8e..cd8278da6a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -898,6 +898,9 @@ importers: '@agent-device/contracts': specifier: workspace:* version: link:../contracts + '@agent-device/host-kit': + specifier: workspace:* + version: link:../host-kit '@agent-device/kernel': specifier: workspace:* version: link:../kernel diff --git a/website/docs/docs/capabilities.md b/website/docs/docs/capabilities.md index f380545e69..82fcb3e115 100644 --- a/website/docs/docs/capabilities.md +++ b/website/docs/docs/capabilities.md @@ -179,9 +179,9 @@ What a **Yes** does not claim: | Capability and reference | BrowserStack Android / TestMu AI Android | BrowserStack iOS / TestMu AI iOS | AWS Device Farm Android | AWS Device Farm iOS | Limrun iOS | Limrun Android | Revyl iOS | Revyl Android | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | [Open and close apps, URLs, and deep links](/docs/commands#navigation) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | -| [Install and reinstall an app](/docs/commands#app-install-in-place) | Yes | Yes | No | No | Yes | Yes | No | No | +| [Install and reinstall an app](/docs/commands#app-install-in-place) | Yes | Yes | No | No | Yes | Yes | Yes | Yes | | [Uninstall an app](/docs/commands#app-uninstall) | No | No | No | No | Yes | Yes | No | No | -| [Install from a source URL](/docs/commands#app-install-from-source-url) | Yes | Yes | No | No | Yes | Yes | No | No | +| [Install from a source URL](/docs/commands#app-install-from-source-url) | Yes | Yes | No | No | Yes | Yes | Yes | Yes | | [Installed app list](/docs/commands#app-state-and-app-lists) | No | No | No | No | Yes | Yes | No | No | | [Foreground app state](/docs/commands#app-state-and-app-lists) | No | No | No | No | XCTest foreground state; without runner state, checks the instance and returns session identity only | Yes | No | No | | [App switcher](/docs/commands#navigation) | Yes | Yes | Yes | Yes | Yes | Yes | No | No | diff --git a/website/docs/docs/revyl.md b/website/docs/docs/revyl.md index 46d0c84f88..4ce12d0c94 100644 --- a/website/docs/docs/revyl.md +++ b/website/docs/docs/revyl.md @@ -26,9 +26,7 @@ next device command loads the plugin. ```bash export REVYL_API_KEY=... export AGENT_DEVICE_SESSION=checkout-ios -agent-device connect revyl \ - --platform ios \ - --provider-app https://apps.example.com/MyApp-simulator.zip +agent-device connect revyl --platform ios ``` `connect` authenticates against the Revyl backend with one cheap request and saves the profile. It @@ -42,9 +40,18 @@ that is already running. A session can take longer to start when Revyl also inst device. Start the session early and keep it open between steps. To relaunch the app, run `open` again on the same session instead of `disconnect` and `connect`. -`--provider-app` is required and must be a public HTTPS URL. Revyl downloads and installs the build -when it starts the device, so a local path or a provider-specific app reference has no meaning -there. Pass the zipped `.app` for iOS the way Revyl expects it, and the `.apk` URL for Android. +Without `--provider-app`, the device starts with no app. Run `install` to put a local build on it: + +```bash +agent-device install com.example.app ./build/Example.app +``` + +`install` uploads the build to the session's storage, and Revyl installs it from there. For iOS, pass +a simulator `.app` directory, or the directory zipped or tarred. A device `.ipa` does not run on a +simulator. For Android, pass the `.apk`. + +`--provider-app` installs a hosted build when the device starts instead. It must be a public HTTPS URL +that Revyl can download: the zipped `.app` for iOS, or the `.apk` for Android. `open` takes the app's installed bundle identifier or package name, not the file name in that URL. Run these commands in the same shell, so they use the `AGENT_DEVICE_SESSION` you exported: @@ -73,7 +80,8 @@ A Revyl session runs the commands that reach a device through Revyl's device act the drag takes, from 1 to 10000 ms, when Revyl's worker supports it. An older worker picks the speed itself, so there the flag refuses rather than running the drag at a speed nobody chose. `fill --delay-ms` is paced by typing one character per pause. -- `open` (the session's app), `open` with a deep link or URL, and `close` for the app the session opened. +- `install` of a local build, `open` with the app's bundle identifier or package name, `open` with a + deep link or URL, and `close` for the app the session opened. - `home`, and `back` on Android. iOS has no system back button; click the app's own back control. The plugin refuses every other command with a reason that names the substitute. It does not @@ -84,9 +92,8 @@ report a refused command as a success: - `swipe` and `gesture` refuse. Use `scroll`, which plans the path itself and sends one drag. - `keyboard`, `clipboard`, `settings`, `orientation`, `alert`, `fold`, `telephony`, and `tv-remote` are not supported. -- `install`, `apps`, `push`, `logs`, `network dump`, `artifacts`, and `recordings` are not supported - by this version of the plugin. Use `--provider-app` to put the build on the device when the - session starts. +- `uninstall`, `apps`, `push`, `logs`, `network dump`, `artifacts`, and `recordings` are not + supported by this version of the plugin. - `port reverse` is unavailable. Publish your app server at a public HTTPS URL instead of pointing Metro at `localhost`. From 8716f86f8d2d0388639dc428664134d5066e70fd Mon Sep 17 00:00:00 2001 From: KayaanT Date: Mon, 16 Nov 2026 12:43:06 -0500 Subject: [PATCH 2/2] refactor(revyl): share the gzip tar packer, poll installs with host-kit, refuse reinstall The .app packer was a third copy of the one in remote and daemon artifact tracking. host-kit now owns it as packGzipTar, with the -- guard and an optional timeout, and all three call it. The Revyl install polls install_status with pollUntilSettled against a Deadline, accepts a completed install without a result, and streams the build to storage with its length declared instead of reading it into memory. reinstall refuses with UNSUPPORTED_OPERATION: Revyl has no uninstall, and an install over an app keeps its data. An app-less connect reports a deferred device and a missing app, so its next steps run install before open. --- .../src/resources/artifact-tracking.test.ts | 7 + .../daemon/src/resources/artifact-tracking.ts | 49 +++---- packages/host-kit/package.json | 4 + packages/host-kit/src/gzip-tar.test.ts | 80 +++++++++++ packages/host-kit/src/gzip-tar.ts | 57 ++++++++ .../provider-revyl/src/connection.test.ts | 10 +- packages/provider-revyl/src/connection.ts | 9 +- .../provider-revyl/src/deployment.test.ts | 30 +++++ packages/provider-revyl/src/deployment.ts | 127 ++++++++---------- packages/provider-revyl/src/index.ts | 5 +- .../src/platform-runtime.test.ts | 20 +++ .../provider-revyl/src/platform-runtime.ts | 16 ++- .../src/revyl-backend.fixtures.ts | 8 +- packages/provider-revyl/src/revyl-client.ts | 32 +++-- packages/remote/src/upload-client-artifact.ts | 49 ++----- scripts/capability-matrix/annotations.ts | 6 + scripts/layering/package-boundaries.test.ts | 1 + src/__tests__/test-utils/connect-command.ts | 8 +- .../__tests__/connection-revyl.test.ts | 23 ++++ website/docs/docs/capabilities.md | 2 +- website/docs/docs/revyl.md | 21 ++- 21 files changed, 392 insertions(+), 172 deletions(-) create mode 100644 packages/host-kit/src/gzip-tar.test.ts create mode 100644 packages/host-kit/src/gzip-tar.ts diff --git a/packages/daemon/src/resources/artifact-tracking.test.ts b/packages/daemon/src/resources/artifact-tracking.test.ts index ad81e95bd8..e318c92593 100644 --- a/packages/daemon/src/resources/artifact-tracking.test.ts +++ b/packages/daemon/src/resources/artifact-tracking.test.ts @@ -217,11 +217,16 @@ test.each(['deadline-aborted', 'late-aborted'] as const)( const succeeded = new Promise((resolve) => { tarSucceeded = resolve; }); + let tarStarted!: () => void; + const started = new Promise((resolve) => { + tarStarted = resolve; + }); let firstArchiveDir = ''; const runCmd = command.runCmd; const archive = vi.spyOn(command, 'runCmd').mockImplementationOnce(async (...args) => { firstArchiveDir = path.dirname(String(args[1]?.[1])); args[2]?.signal?.addEventListener('abort', aborted, { once: true }); + tarStarted(); if (failure === 'late-aborted') { const result = await runCmd(...args); tarSucceeded(); @@ -242,6 +247,8 @@ test.each(['deadline-aborted', 'late-aborted'] as const)( void first.catch(() => {}); const deadline = timers.mock.calls.find(([, delay]) => delay === 15 * 60 * 1000)?.[0]; timers.mockRestore(); + // The packer loads on demand, so tar starts a tick after the open; the deadline fires once it runs. + await started; if (failure === 'late-aborted') await succeeded; expect(deadline).toBeTypeOf('function'); runtime.run(() => deadline!()); diff --git a/packages/daemon/src/resources/artifact-tracking.ts b/packages/daemon/src/resources/artifact-tracking.ts index 4af16a65a2..2418b802a2 100644 --- a/packages/daemon/src/resources/artifact-tracking.ts +++ b/packages/daemon/src/resources/artifact-tracking.ts @@ -1,14 +1,13 @@ import { runtimeSlot } from '@agent-device/host-kit/runtime-slots'; import crypto from 'node:crypto'; import fs from 'node:fs'; -import os from 'node:os'; import path from 'node:path'; import { finished } from 'node:stream/promises'; import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; import type { DaemonArtifactType } from '@agent-device/kernel/contracts'; import type { DeviceRotation } from '@agent-device/contracts/device'; import type { DaemonArtifactInventoryEntry } from '@agent-device/contracts/observability'; -import { runCmd } from '@agent-device/host-kit/command'; +import type { PackedGzipTar } from '@agent-device/host-kit/gzip-tar'; import { expiredTenantOwnedEntryError, requireTenantOwnedEntry, @@ -29,7 +28,7 @@ const DIRECTORY_ARCHIVE_MIME_TYPE = 'application/gzip'; type DirectoryArchive = { archivePath: string; - tempDir: string; + cleanup(): void; fileName: string; sizeBytes: number; }; @@ -389,7 +388,7 @@ async function createDirectoryArchive( hostEnv: NodeJS.ProcessEnv, controller: AbortController, ): Promise { - let tempDir: string | undefined; + let packed: PackedGzipTar | undefined; try { cleanupDirectoryArchive(entry); @@ -398,35 +397,19 @@ async function createDirectoryArchive( path.basename(entry.artifactPath) || artifactId, ); const fileName = archiveFilename(sourceName); - tempDir = fs.mkdtempSync( - path.join(os.tmpdir(), `agent-device-download-${crypto.randomUUID()}-`), - ); - const archivePath = path.join(tempDir, fileName); - await runCmd( - 'tar', - [ - 'czf', - archivePath, - '-C', - path.dirname(entry.artifactPath), - '--', - path.basename(entry.artifactPath), - ], - { - signal: controller.signal, - timeoutMs: ARTIFACT_DOWNLOAD_MAX_LIFETIME_MS, - env: { - ...hostEnv, - COPYFILE_DISABLE: '1', - }, - }, - ); - controller.signal.throwIfAborted(); + // Loaded on demand: only a directory artifact packs, and the daemon's eager closure stays small. + const { packGzipTar } = await import('@agent-device/host-kit/gzip-tar'); + packed = await packGzipTar(entry.artifactPath, { + env: hostEnv, + signal: controller.signal, + timeoutMs: ARTIFACT_DOWNLOAD_MAX_LIFETIME_MS, + fileName, + }); const archive = { - archivePath, - tempDir, + archivePath: packed.archivePath, + cleanup: packed.cleanup, fileName, - sizeBytes: fs.statSync(archivePath).size, + sizeBytes: fs.statSync(packed.archivePath).size, }; entry.directoryArchive = archive; return archive; @@ -441,7 +424,7 @@ async function createDirectoryArchive( { artifactPath: entry.artifactPath }, error instanceof Error ? error : undefined, ); - if (tempDir) fs.rmSync(tempDir, { recursive: true, force: true }); + packed?.cleanup(); throw failure; } } @@ -510,7 +493,7 @@ function removeBestEffort(targetPath: string): void { function cleanupDirectoryArchive(entry: ArtifactEntry): void { if (!entry.directoryArchive) return; - removeBestEffort(entry.directoryArchive.tempDir); + entry.directoryArchive.cleanup(); entry.directoryArchive = undefined; } diff --git a/packages/host-kit/package.json b/packages/host-kit/package.json index eb3cf54bfb..4f91957f06 100644 --- a/packages/host-kit/package.json +++ b/packages/host-kit/package.json @@ -52,6 +52,10 @@ "types": "./src/file.ts", "default": "./src/file.ts" }, + "./gzip-tar": { + "types": "./src/gzip-tar.ts", + "default": "./src/gzip-tar.ts" + }, "./host-file": { "types": "./src/host-file.ts", "default": "./src/host-file.ts" diff --git a/packages/host-kit/src/gzip-tar.test.ts b/packages/host-kit/src/gzip-tar.test.ts new file mode 100644 index 0000000000..92759362c8 --- /dev/null +++ b/packages/host-kit/src/gzip-tar.test.ts @@ -0,0 +1,80 @@ +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { afterEach, test } from 'vitest'; +import { runCmd, withCommandExecutorOverride } from './command.ts'; +import { packGzipTar } from './gzip-tar.ts'; +import { mkdtempForTestSync } from './internal/tmp-dir.fixtures.ts'; + +const roots: string[] = []; +afterEach(() => { + for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true }); +}); + +function bundle(name: string): string { + const root = mkdtempForTestSync('gzip-tar-fixture-'); + roots.push(root); + const directory = path.join(root, name); + fs.mkdirSync(directory); + fs.writeFileSync(path.join(directory, 'Info.plist'), 'plist'); + return directory; +} + +async function entries(archivePath: string): Promise { + const { stdout } = await runCmd('tar', ['tzf', archivePath], { env: process.env }); + return stdout.split('\n').filter(Boolean).sort(); +} + +test('packs the directory as the archive’s one top-level entry, and cleanup removes it', async () => { + const packed = await packGzipTar(bundle('Example.app'), { env: process.env }); + assert.equal(path.basename(packed.archivePath), 'Example.app.tar.gz'); + assert.deepEqual(await entries(packed.archivePath), ['Example.app/', 'Example.app/Info.plist']); + packed.cleanup(); + assert.equal(fs.existsSync(path.dirname(packed.archivePath)), false); + packed.cleanup(); +}); + +test('a directory name that starts with a dash is packed as a name, not read as an option', async () => { + const packed = await packGzipTar(bundle('-v.app'), { env: process.env, fileName: 'build.tgz' }); + try { + assert.equal(path.basename(packed.archivePath), 'build.tgz'); + assert.deepEqual(await entries(packed.archivePath), ['-v.app/', '-v.app/Info.plist']); + } finally { + packed.cleanup(); + } +}); + +test('a pack that fails leaves no temporary directory behind', async () => { + let archivePath = ''; + await assert.rejects( + withCommandExecutorOverride( + (cmd, args) => { + if (cmd !== 'tar') return undefined; + archivePath = String(args[1]); + throw new Error('tar unavailable'); + }, + async () => await packGzipTar(bundle('Example.app'), { env: process.env }), + ), + /tar unavailable/, + ); + assert.notEqual(archivePath, ''); + assert.equal(fs.existsSync(path.dirname(archivePath)), false); +}); + +test('an already-aborted pack starts no tar and leaves nothing behind', async () => { + const controller = new AbortController(); + controller.abort(new Error('canceled')); + let ran = false; + await assert.rejects( + withCommandExecutorOverride( + (cmd) => { + if (cmd === 'tar') ran = true; + return undefined; + }, + async () => + await packGzipTar(bundle('Example.app'), { env: process.env, signal: controller.signal }), + ), + /canceled/, + ); + assert.equal(ran, false); +}); diff --git a/packages/host-kit/src/gzip-tar.ts b/packages/host-kit/src/gzip-tar.ts new file mode 100644 index 0000000000..cb6bd5f34d --- /dev/null +++ b/packages/host-kit/src/gzip-tar.ts @@ -0,0 +1,57 @@ +import { randomUUID } from 'node:crypto'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +// Through the public module, so a test that stubs `runCmd` there also stubs the pack. +import { runCmd } from './command.ts'; + +export type GzipTarPackOptions = Readonly<{ + /** The host environment `tar` runs with. */ + env: Readonly>; + signal?: AbortSignal; + timeoutMs?: number; + /** The archive's file name; `.tar.gz` when omitted. */ + fileName?: string; +}>; + +export type PackedGzipTar = Readonly<{ + archivePath: string; + /** Removes the archive and its temporary directory. Safe to call more than once. */ + cleanup(): void; +}>; + +/** + * Packs a directory, such as a simulator `.app`, into a gzip tar in a fresh temporary directory, for + * upload or download. The archive holds the directory itself as its one top-level entry. On failure + * nothing is left behind. + */ +export async function packGzipTar( + directory: string, + options: GzipTarPackOptions, +): Promise { + options.signal?.throwIfAborted(); + const name = path.basename(directory); + const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `agent-device-pack-${randomUUID()}-`)); + const cleanup = () => { + try { + fs.rmSync(tempDir, { recursive: true, force: true }); + } catch { + // best-effort cleanup only + } + }; + const archivePath = path.join(tempDir, options.fileName ?? `${name}.tar.gz`); + try { + // `--` keeps a directory name that starts with `-` from being read as an option. + await runCmd('tar', ['czf', archivePath, '-C', path.dirname(directory), '--', name], { + // Keeps macOS tar from adding AppleDouble `._` entries. + env: { ...options.env, COPYFILE_DISABLE: '1' }, + ...(options.signal === undefined ? {} : { signal: options.signal }), + ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }), + }); + options.signal?.throwIfAborted(); + } catch (error) { + cleanup(); + throw error; + } + return { archivePath, cleanup }; +} diff --git a/packages/provider-revyl/src/connection.test.ts b/packages/provider-revyl/src/connection.test.ts index f197e26c14..90066d5113 100644 --- a/packages/provider-revyl/src/connection.test.ts +++ b/packages/provider-revyl/src/connection.test.ts @@ -47,7 +47,7 @@ test('verify authenticates with the cheap call and reports the profile without r // The literals are asserted so a reworded report fails the test instead of being compared with // itself. assert.deepEqual(result.device, { - status: 'configured', + status: 'deferred', name: 'iPhone 16', platform: 'ios', osVersion: '18.0', @@ -70,7 +70,7 @@ test('verify reports a profile that names no device or OS version', async () => { appUrl: 'https://apps.test/app.apk' }, ); assert.deepEqual(result.device, { - status: 'configured', + status: 'deferred', platform: 'android', message: 'Revyl assigns a device of this platform when the session starts; a model or OS version it has no device for is reported then.', @@ -85,8 +85,10 @@ test('verify reports a profile without an app as one the device starts without', 'ios', {}, ); - assert.equal(result.app.status, 'deferred'); - assert.equal(result.app.reference, undefined); + assert.deepEqual(result.app, { + status: 'missing', + message: 'No app URL; the device starts without one. Install a build, then open it.', + }); }); test('verify reports a rejected key as an unauthorized error before checking the app', async () => { diff --git a/packages/provider-revyl/src/connection.ts b/packages/provider-revyl/src/connection.ts index 7f9bb1bf08..3b0a6566c3 100644 --- a/packages/provider-revyl/src/connection.ts +++ b/packages/provider-revyl/src/connection.ts @@ -96,8 +96,9 @@ export async function verifyRevylProfile( provider: REVYL_PROVIDER, service: REVYL_SERVICE, verificationMessage: `Credentials verified; ${REVYL_SERVICE} picks the device when the session starts.`, + // Revyl picks the device when the session starts, so connect has none to verify yet. device: { - status: 'configured', + status: 'deferred', ...(profile.deviceModel === undefined ? {} : { name: profile.deviceModel }), platform, ...(profile.osVersion === undefined ? {} : { osVersion: profile.osVersion }), @@ -106,8 +107,10 @@ export async function verifyRevylProfile( app: profile.appUrl === undefined ? { - status: 'deferred', - message: `No app URL; the device starts without an app. Run install to add a local build.`, + // With the device still to start, a missing app is the state the connect workflow answers + // with `install` before `open`. + status: 'missing', + message: 'No app URL; the device starts without one. Install a build, then open it.', } : { status: 'configured', diff --git a/packages/provider-revyl/src/deployment.test.ts b/packages/provider-revyl/src/deployment.test.ts index 784f2a42c8..98fcc55ca6 100644 --- a/packages/provider-revyl/src/deployment.test.ts +++ b/packages/provider-revyl/src/deployment.test.ts @@ -84,6 +84,9 @@ test('an Android install uploads the apk to the session and installs it from the }); const upload = fixture.requests.find((request) => request.path === UPLOAD_PATH); assert.equal(upload?.method, 'PUT'); + // Streamed from disk with its length declared, as a presigned PUT requires. + assert.equal(upload?.bytes, 9); + assert.equal(upload?.contentLength, '9'); // The presigned URL carries its own authorization; the API key never goes to storage. assert.equal(upload?.authorization, undefined); assert.deepEqual(fixture.bodyFor('install_async'), { @@ -173,3 +176,30 @@ test('a canceled install reports the cancellation', async () => { (error: unknown) => error instanceof AppError && error.details?.reason === 'request_canceled', ); }); + +test('an install Revyl reports completed without a result is installed, with no identity of its own', async () => { + const sessionId = revylSessionIdForLease('lease-1'); + let backendUrl = ''; + const fixture = await startRevylFixtureBackend({ + respond: { + [`POST /api/v1/execution/device-sessions/${sessionId}/artifacts/upload-url`]: () => ({ + body: { upload_url: `${backendUrl}${UPLOAD_PATH}`, download_url: DOWNLOAD_URL }, + }), + [`PUT ${UPLOAD_PATH}`]: { body: {} }, + 'POST /api/v1/execution/device-proxy/run-1/install_async': { + body: { install_id: 'install-1', status: 'accepted' }, + }, + 'GET /api/v1/execution/device-proxy/run-1/install_status/install-1': { + body: { install_id: 'install-1', status: 'completed' }, + }, + }, + }); + backendUrl = fixture.backendUrl; + openBackends.push(fixture); + const { session } = await liveSession(fixture.createRuntime(), 'android'); + const dir = await mkdtempForTest('revyl-deploy-'); + const apk = path.join(dir, 'app.apk'); + await fs.writeFile(apk, 'apk'); + + assert.deepEqual(await deployRevylApp(session, apk, ENV, new AbortController().signal), {}); +}); diff --git a/packages/provider-revyl/src/deployment.ts b/packages/provider-revyl/src/deployment.ts index 4f34cb61db..bd66ae3b35 100644 --- a/packages/provider-revyl/src/deployment.ts +++ b/packages/provider-revyl/src/deployment.ts @@ -1,13 +1,10 @@ -import { randomUUID } from 'node:crypto'; import fs from 'node:fs/promises'; -import os from 'node:os'; -import path from 'node:path'; -import { setTimeout as sleep } from 'node:timers/promises'; import type { AppDeploymentResult, MaterializedAppSource, } from '@agent-device/contracts/app-deployment-runtime'; -import { runCmd } from '@agent-device/host-kit/command'; +import { packGzipTar } from '@agent-device/host-kit/gzip-tar'; +import { Deadline, type DeadlineClock, pollUntilSettled } from '@agent-device/host-kit/retry'; import { AppError } from '@agent-device/kernel/errors'; import type { EnvMap } from '@agent-device/kernel/source-value'; import type { RevylClient } from './revyl-client.ts'; @@ -19,8 +16,8 @@ import type { RevylWorkerActionResponse } from './revyl-types.ts'; * client gives up and resets the daemon that holds the rented device. */ const REVYL_INSTALL_BUDGET_MS = 420_000; -const POLL_BASE_DELAY_MS = 500; -const POLL_MAX_DELAY_MS = 5_000; +/** How often `install_status` is read while Revyl installs; an install takes seconds to minutes. */ +const INSTALL_POLL_INTERVAL_MS = 1_000; /** What an install reads from the session it targets. */ export type RevylDeploymentSession = Readonly<{ @@ -33,7 +30,7 @@ export type RevylDeploymentSession = Readonly<{ type PackagedBuild = Readonly<{ filePath: string; contentType: string; - cleanup(): Promise; + cleanup(): void; }>; /** @@ -48,46 +45,54 @@ export async function deployRevylApp( signal: AbortSignal, budgetMs = REVYL_INSTALL_BUDGET_MS, ): Promise { + const deadline = Deadline.fromTimeoutMs(budgetMs); const budget = AbortSignal.timeout(budgetMs); const scoped = AbortSignal.any([signal, budget]); + const timedOut = (cause?: unknown) => + installStopped( + 'provider-unconfirmed', + `Revyl did not finish the install within ${budgetMs / 1000} s.`, + cause, + ); try { - return await uploadAndInstall(session, appPath, env, scoped); + const installed = await uploadAndInstall(session, appPath, env, scoped, deadline); + if (!installed) throw timedOut(); + return installed; } catch (error) { if (signal.aborted) throw installStopped('request_canceled', 'The install was canceled.', error); - if (budget.aborted) { - throw installStopped( - 'provider-unconfirmed', - `Revyl did not finish the install within ${budgetMs / 1000} s.`, - error, - ); - } + if (budget.aborted) throw timedOut(error); throw error; } } +/** The installed app, or `undefined` when Revyl was still installing at the deadline. */ async function uploadAndInstall( session: RevylDeploymentSession, appPath: string, env: Readonly, signal: AbortSignal, -): Promise { + deadline: DeadlineClock, +): Promise { const build = await packageBuild(session.platform, appPath, env, signal); try { - const body = new Uint8Array(await fs.readFile(build.filePath)); + const { size } = await fs.stat(build.filePath); const upload = await session.client.createSessionArtifactUpload( session.sessionId, - body.byteLength, + size, build.contentType, signal, ); - await session.client.uploadSessionArtifact(upload.upload_url, body, build.contentType, signal); - return deploymentResult( - session.platform, - await installAndWait(session, upload.download_url, signal), + await session.client.uploadSessionArtifact( + upload.upload_url, + { filePath: build.filePath, size }, + build.contentType, + signal, ); + const installed = await installAndWait(session, upload.download_url, signal, deadline); + return installed && deploymentResult(session.platform, installed); } finally { - await build.cleanup(); + build.cleanup(); } } @@ -122,7 +127,13 @@ async function packageBuild( const stat = await fs.stat(appPath); const lower = appPath.toLowerCase().replace(/[\\/]+$/, ''); if (platform === 'ios' && stat.isDirectory() && lower.endsWith('.app')) { - return await packAppBundle(appPath, env, signal); + // Revyl accepts a gzip tar of the bundle for iOS the same as a zip. + const packed = await packGzipTar(appPath, { env, signal }); + return { + filePath: packed.archivePath, + contentType: 'application/gzip', + cleanup: packed.cleanup, + }; } const match = stat.isFile() ? FILE_BUILDS[platform].find(([suffix]) => lower.endsWith(suffix)) @@ -131,33 +142,11 @@ async function packageBuild( throw unsupportedBuild(platform, appPath); } -/** Packs a simulator `.app` directory as a gzip tar, which Revyl accepts for iOS. */ -async function packAppBundle( - appPath: string, - env: Readonly, - signal: AbortSignal, -): Promise { - const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), `agent-device-revyl-${randomUUID()}-`)); - const archive = path.join(tempDir, `${path.basename(appPath)}.tar.gz`); - const cleanup = async () => await fs.rm(tempDir, { recursive: true, force: true }); - try { - await runCmd('tar', ['czf', archive, '-C', path.dirname(appPath), path.basename(appPath)], { - // Keeps macOS tar from adding AppleDouble `._` entries to the bundle. - env: { ...env, COPYFILE_DISABLE: '1' }, - signal, - }); - } catch (error) { - await cleanup(); - throw error; - } - return { filePath: archive, contentType: 'application/gzip', cleanup }; -} - function unsupportedBuild(platform: 'ios' | 'android', appPath: string): AppError { return platform === 'ios' ? new AppError( 'INVALID_ARGS', - 'Revyl installs an iOS simulator build: a .app directory, or one zipped or tarred.', + 'Revyl installs an iOS simulator build: a .app directory, or a .zip, .tar.gz, or .tgz of one.', { reason: 'unsupported_app_artifact', appPath, @@ -172,14 +161,16 @@ function unsupportedBuild(platform: 'ios' | 'android', appPath: string): AppErro } function fileBuild(filePath: string, contentType: string): PackagedBuild { - return { filePath, contentType, cleanup: async () => undefined }; + return { filePath, contentType, cleanup: () => undefined }; } +/** Revyl's install result once the install ends, or `undefined` if it is still running at the deadline. */ async function installAndWait( session: RevylDeploymentSession, appUrl: string, signal: AbortSignal, -): Promise { + deadline: DeadlineClock, +): Promise { const accepted = await session.client.startInstall( session.runId, { app_url: appUrl, platform: session.platform }, @@ -192,25 +183,21 @@ async function installAndWait( ...(accepted.status === undefined ? {} : { providerDetail: accepted.status }), }); } - let delay = POLL_BASE_DELAY_MS; - for (;;) { - await sleep(delay, undefined, { signal }); - const status = await session.client.getInstallStatus(session.runId, installId, signal); - if ( - status.status === 'completed' || - status.status === 'failed' || - status.status === 'cancelled' - ) { - return requireInstalled(status.status, status.result ?? undefined); - } - if (status.status !== 'running') { - throw new AppError('COMMAND_FAILED', `Revyl reported install status "${status.status}".`, { - reason: 'provider-refused', - installId, - }); - } - delay = Math.min(delay * 2, POLL_MAX_DELAY_MS); + const { settled, value } = await pollUntilSettled({ + probe: async () => await session.client.getInstallStatus(session.runId, installId, signal), + settled: (status) => status.status !== 'running', + deadline, + intervalMs: INSTALL_POLL_INTERVAL_MS, + signal, + }); + if (!settled) return undefined; + if (value.status === 'completed' || value.status === 'failed' || value.status === 'cancelled') { + return requireInstalled(value.status, value.result ?? undefined); } + throw new AppError('COMMAND_FAILED', `Revyl reported install status "${value.status}".`, { + reason: 'provider-refused', + installId, + }); } function requireInstalled( @@ -219,8 +206,8 @@ function requireInstalled( ): RevylWorkerActionResponse { const error = typeof result?.error === 'string' && result.error !== '' ? result.error : undefined; const succeeded = result?.success ?? result?.Success; - if (status === 'completed' && result !== undefined && succeeded !== false && !error) - return result; + // A completed install without a result is still installed; the build supplies the identity. + if (status === 'completed' && succeeded !== false && !error) return result ?? {}; throw new AppError( 'COMMAND_FAILED', `Revyl could not install the app${error === undefined ? '' : `: ${error}`}`, diff --git a/packages/provider-revyl/src/index.ts b/packages/provider-revyl/src/index.ts index 6f419fbeea..6e14615904 100644 --- a/packages/provider-revyl/src/index.ts +++ b/packages/provider-revyl/src/index.ts @@ -43,8 +43,9 @@ function revyl(options: RevylPluginOptions = {}): AgentDevicePlugin { requiresAppAttachment: false, requiresRemoteDaemon: false, supportsArtifacts: false, - // Revyl installs the app as part of starting the device, so the app has to be known before the - // lease exists and cannot be attached to a device that is already up. + // Deferred app selection means `open ` creates the device from an asset + // already uploaded to the provider. Revyl starts a device with or without an app and puts a + // build on a running one with `install`, so the first device command allocates as usual. supportsDeferredAppSelection: false, supportsDirectPortReverse: false, usesCloudWebDriverLease: false, diff --git a/packages/provider-revyl/src/platform-runtime.test.ts b/packages/provider-revyl/src/platform-runtime.test.ts index 6d42ad9f96..6653e212f9 100644 --- a/packages/provider-revyl/src/platform-runtime.test.ts +++ b/packages/provider-revyl/src/platform-runtime.test.ts @@ -209,3 +209,23 @@ test('a deployment operation whose session ended refuses rather than installing' error instanceof AppError && error.details?.reason === 'provider-session-unavailable', ); }); + +test('a reinstall refuses before uploading, because Revyl cannot reset the app it would replace', async () => { + const installs: string[] = []; + const binding = await bind( + owner({ hasLiveSession: true, deploymentSession: installingSession(installs) }), + ); + await assert.rejects( + () => + binding.operations.deployApp!({ + app: 'com.example.app', + appPath: '/tmp/x.zip', + replaceExisting: true, + }), + (error: unknown) => + error instanceof AppError && + error.code === 'UNSUPPORTED_OPERATION' && + error.details?.reason === 'unsupported-provider-mode', + ); + assert.deepEqual(installs, []); +}); diff --git a/packages/provider-revyl/src/platform-runtime.ts b/packages/provider-revyl/src/platform-runtime.ts index 7570aa55d4..3a2ae44e2d 100644 --- a/packages/provider-revyl/src/platform-runtime.ts +++ b/packages/provider-revyl/src/platform-runtime.ts @@ -154,7 +154,21 @@ function bindRevylDeployment( }); }; return { - deployApp: async (input) => await deployRevylApp(session(), input.appPath, env(), signal), + deployApp: async (input) => { + // Revyl cannot uninstall an app, and an install over one keeps its data, so a reinstall would + // not reset the app the way `reinstall` promises. + if (input.replaceExisting) { + throw new AppError( + 'UNSUPPORTED_OPERATION', + 'Revyl cannot reinstall an app: it has no uninstall, and installing over an app keeps its data.', + { + reason: 'unsupported-provider-mode', + hint: 'Run install to update the build in place, or start a new session for a clean app.', + }, + ); + } + return await deployRevylApp(session(), input.appPath, env(), signal); + }, materializeAppSource: async (input) => device.platform === 'apple' ? await options.host.appleDeployment.prepareArtifact(input, { signal }) diff --git a/packages/provider-revyl/src/revyl-backend.fixtures.ts b/packages/provider-revyl/src/revyl-backend.fixtures.ts index 4ec2fb55d7..e55f885b07 100644 --- a/packages/provider-revyl/src/revyl-backend.fixtures.ts +++ b/packages/provider-revyl/src/revyl-backend.fixtures.ts @@ -9,6 +9,9 @@ export type RevylFixtureRequest = Readonly<{ method: string; path: string; body: Record | undefined; + /** The request body's length as received, and the length its header declared. */ + bytes: number; + contentLength: string | undefined; authorization: string | undefined; clientHeader: string | undefined; agentHeader: string | undefined; @@ -118,7 +121,8 @@ export async function startRevylFixtureBackend( const chunks: Buffer[] = []; request.on('data', (chunk: Buffer) => chunks.push(chunk)); request.on('end', () => { - const raw = Buffer.concat(chunks).toString('utf8'); + const received = Buffer.concat(chunks); + const raw = received.toString('utf8'); const url = request.url ?? '/'; const method = request.method ?? 'GET'; // The fixture listens on an ephemeral localhost port that any process on the host can reach. A @@ -134,6 +138,8 @@ export async function startRevylFixtureBackend( method, path: url, body: recorded, + bytes: received.byteLength, + contentLength: header(request, 'content-length'), authorization: header(request, 'authorization'), clientHeader: header(request, 'x-revyl-client'), agentHeader: header(request, 'x-revyl-agent'), diff --git a/packages/provider-revyl/src/revyl-client.ts b/packages/provider-revyl/src/revyl-client.ts index d61d663b4e..b6569f6d1a 100644 --- a/packages/provider-revyl/src/revyl-client.ts +++ b/packages/provider-revyl/src/revyl-client.ts @@ -1,6 +1,8 @@ import { AppError, type AppErrorCode } from '@agent-device/kernel/errors'; import { isRecord } from '@agent-device/kernel/record'; +import fs from 'node:fs'; import net from 'node:net'; +import { Readable } from 'node:stream'; import { setTimeout as sleep } from 'node:timers/promises'; import type { RevylDeviceSessionStopResponse, @@ -26,8 +28,6 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 30_000; /** How long `start_device` may take to answer: Revyl assigns a worker and boots the device in it. */ export const REVYL_START_DEVICE_TIMEOUT_MS = 120_000; const RETRY_DELAYS_MS = [500, 1_500] as const; -/** How long one build upload may take to reach Revyl's storage; the install's whole budget. */ -const ARTIFACT_UPLOAD_TIMEOUT_MS = 420_000; /** Device-proxy actions Revyl answers to a GET; every other action is a POST. */ const DEVICE_PROXY_GET_ACTIONS = new Set(['screenshot', 'health', 'device_info', 'hierarchy']); @@ -100,10 +100,13 @@ export type RevylClient = Readonly<{ contentType: string, signal?: AbortSignal, ): Promise; - /** Sends the build to the presigned URL; the URL carries its own authorization. */ + /** + * Streams the build file to the presigned URL; the URL carries its own authorization. The caller's + * signal bounds the upload. + */ uploadSessionArtifact( uploadUrl: string, - body: Uint8Array, + file: Readonly<{ filePath: string; size: number }>, contentType: string, signal?: AbortSignal, ): Promise; @@ -247,17 +250,20 @@ export function createRevylClient(options: RevylClientOptions): RevylClient { ...(signal === undefined ? {} : { signal }), }); }, - async uploadSessionArtifact(uploadUrl, body, contentType, signal) { - const timeout = AbortSignal.timeout(ARTIFACT_UPLOAD_TIMEOUT_MS); + async uploadSessionArtifact(uploadUrl, file, contentType, signal) { + // Node streams a request body only in half-duplex mode, which the DOM `RequestInit` type omits. + const init: RequestInit & { duplex: 'half' } = { + method: 'PUT', + // A presigned PUT needs the length up front; a streamed body would otherwise go chunked. + headers: { 'Content-Type': contentType, 'Content-Length': String(file.size) }, + body: Readable.toWeb(fs.createReadStream(file.filePath)) as ReadableStream, + duplex: 'half', + redirect: 'error', + ...(signal === undefined ? {} : { signal }), + }; let response: Response; try { - response = await fetchImpl(uploadUrl, { - method: 'PUT', - headers: { 'Content-Type': contentType }, - body, - redirect: 'error', - signal: signal ? AbortSignal.any([signal, timeout]) : timeout, - }); + response = await fetchImpl(uploadUrl, init); } catch (error) { throw new AppError( 'COMMAND_FAILED', diff --git a/packages/remote/src/upload-client-artifact.ts b/packages/remote/src/upload-client-artifact.ts index b037d7e59e..fad2b4d0b8 100644 --- a/packages/remote/src/upload-client-artifact.ts +++ b/packages/remote/src/upload-client-artifact.ts @@ -1,12 +1,11 @@ import type { EnvMap } from '@agent-device/kernel/source-value'; -import { createHash, randomUUID } from 'node:crypto'; +import { createHash } from 'node:crypto'; import fs from 'node:fs'; -import os from 'node:os'; import path from 'node:path'; import { Writable } from 'node:stream'; import { pipeline } from 'node:stream/promises'; import { AppError } from '@agent-device/kernel/errors'; -import { runCmd } from '@agent-device/host-kit/command'; +import type { PackedGzipTar } from '@agent-device/host-kit/gzip-tar'; const ARTIFACT_HASH_ALGORITHM = 'sha256'; const DEFAULT_CONTENT_TYPE = 'application/octet-stream'; @@ -34,11 +33,14 @@ export async function prepareUploadArtifact( const isDirectory = stat.isDirectory(); const platform = normalizeUploadPlatform(requestedPlatform) ?? inferArtifactPlatform(localPath, stat); - const cleanupPaths: string[] = []; + let packed: PackedGzipTar | undefined; try { - const payloadPath = isDirectory - ? await createGzipTarArchive(localPath, cleanupPaths, env, signal) - : localPath; + if (isDirectory) { + // Loaded on demand: only a directory upload packs, and the CLI's eager closure stays small. + const { packGzipTar } = await import('@agent-device/host-kit/gzip-tar'); + packed = await packGzipTar(localPath, signal ? { env, signal } : { env }); + } + const payloadPath = packed?.archivePath ?? localPath; signal?.throwIfAborted(); const payloadStat = fs.statSync(payloadPath); @@ -50,37 +52,14 @@ export async function prepareUploadArtifact( contentType: isDirectory ? 'application/gzip' : DEFAULT_CONTENT_TYPE, sha256: await computeFileHash(payloadPath, signal), sizeBytes: payloadStat.size, - cleanup: () => cleanupUploadPaths(cleanupPaths), + cleanup: () => packed?.cleanup(), }; } catch (error) { - cleanupUploadPaths(cleanupPaths); + packed?.cleanup(); throw error; } } -async function createGzipTarArchive( - localPath: string, - cleanupPaths: string[], - env: Readonly, - signal?: AbortSignal, -): Promise { - const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `agent-device-upload-${randomUUID()}-`)); - cleanupPaths.push(tempDir); - const archivePath = path.join(tempDir, `${path.basename(localPath)}.tar.gz`); - await runCmd( - 'tar', - ['czf', archivePath, '-C', path.dirname(localPath), path.basename(localPath)], - { - signal, - env: { - ...env, - COPYFILE_DISABLE: '1', - }, - }, - ); - return archivePath; -} - function inferArtifactPlatform( localPath: string, stat: { isDirectory(): boolean }, @@ -96,12 +75,6 @@ function normalizeUploadPlatform(value: string | undefined): 'ios' | 'android' | return value === 'ios' || value === 'android' ? value : undefined; } -function cleanupUploadPaths(cleanupPaths: string[]): void { - for (const cleanupPath of cleanupPaths) { - fs.rmSync(cleanupPath, { recursive: true, force: true }); - } -} - async function computeFileHash(localPath: string, signal?: AbortSignal): Promise { const hash = createHash(ARTIFACT_HASH_ALGORITHM); const sink = new Writable({ diff --git a/scripts/capability-matrix/annotations.ts b/scripts/capability-matrix/annotations.ts index fb846fbc27..c9e61e6300 100644 --- a/scripts/capability-matrix/annotations.ts +++ b/scripts/capability-matrix/annotations.ts @@ -237,6 +237,12 @@ export const MATRIX_SECTIONS: readonly MatrixSection[] = [ label: 'Install and reinstall an app', commands: ['install', 'reinstall'], link: docs('commands', 'app-install-in-place'), + cells: { + 'revyl-ios': { text: 'Install only; reinstall refuses because Revyl cannot uninstall' }, + 'revyl-android': { + text: 'Install only; reinstall refuses because Revyl cannot uninstall', + }, + }, }, { id: 'uninstall', diff --git a/scripts/layering/package-boundaries.test.ts b/scripts/layering/package-boundaries.test.ts index cee6d6dc56..f8d4271fd0 100644 --- a/scripts/layering/package-boundaries.test.ts +++ b/scripts/layering/package-boundaries.test.ts @@ -613,6 +613,7 @@ test('the real tree parses, declares, and passes R11', () => { '@agent-device/host-kit/diagnostics', '@agent-device/host-kit/doctor-lines', '@agent-device/host-kit/file', + '@agent-device/host-kit/gzip-tar', '@agent-device/host-kit/host-file', '@agent-device/host-kit/interaction-outcome', '@agent-device/host-kit/local-artifact-adapter', diff --git a/src/__tests__/test-utils/connect-command.ts b/src/__tests__/test-utils/connect-command.ts index 0da4c39dcc..f66dc578d5 100644 --- a/src/__tests__/test-utils/connect-command.ts +++ b/src/__tests__/test-utils/connect-command.ts @@ -3,13 +3,16 @@ import type { HostEnvironment } from '@agent-device/kernel/source-value'; import { connectCommand } from '../../cli/commands/connection.ts'; import type { AgentDeviceClient } from '@agent-device/command-surface'; -/** Runs `connect` the way the CLI does, writing its generated profile under `stateDir`. */ +/** + * Runs `connect` the way the CLI does, writing its generated profile under `stateDir`, and returns + * what it printed (JSON unless the flags say otherwise). + */ export async function connectWithGeneratedProviderProfile(options: { stateDir: string; host?: HostEnvironment; positionals: string[]; flags: Partial[0]['flags']>; -}): Promise { +}): Promise { const stdoutCapture = beginStdoutCapture(); try { await connectCommand({ @@ -24,6 +27,7 @@ export async function connectWithGeneratedProviderProfile(options: { }, client: {} as AgentDeviceClient, }); + return stdoutCapture.read(); } finally { stdoutCapture.restore(); } diff --git a/src/cli/commands/__tests__/connection-revyl.test.ts b/src/cli/commands/__tests__/connection-revyl.test.ts index ba9a563eaf..769c895c39 100644 --- a/src/cli/commands/__tests__/connection-revyl.test.ts +++ b/src/cli/commands/__tests__/connection-revyl.test.ts @@ -155,6 +155,29 @@ test('connect revyl verifies credentials and stores a profile without renting a } }); +test('connect revyl without an app URL points the next steps at install before open', async () => { + await startRevylVerificationStub(); + const tempRoot = mkdtempForTestSync('agent-device-connect-revyl-no-app-'); + + try { + const { providerApp: _app, ...flags } = connectFlags; + const printed = await connectWithGeneratedProviderProfile({ + stateDir: path.join(tempRoot, '.state'), + positionals: ['revyl'], + flags, + }); + const output = (JSON.parse(printed) as { data: Record }).data; + assert.equal(output.app.status, 'missing'); + assert.equal(output.device.status, 'deferred'); + assert.deepEqual(output.nextSteps, [ + `agent-device install --session ${output.session}`, + `agent-device open --relaunch --session ${output.session}`, + ]); + } finally { + fs.rmSync(tempRoot, { recursive: true, force: true }); + } +}); + test('connect revyl refuses a missing API key before calling the backend', async () => { const backend = await startRevylVerificationStub(); const tempRoot = mkdtempForTestSync('agent-device-connect-revyl-no-key-'); diff --git a/website/docs/docs/capabilities.md b/website/docs/docs/capabilities.md index 82fcb3e115..e4d0767c17 100644 --- a/website/docs/docs/capabilities.md +++ b/website/docs/docs/capabilities.md @@ -179,7 +179,7 @@ What a **Yes** does not claim: | Capability and reference | BrowserStack Android / TestMu AI Android | BrowserStack iOS / TestMu AI iOS | AWS Device Farm Android | AWS Device Farm iOS | Limrun iOS | Limrun Android | Revyl iOS | Revyl Android | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | [Open and close apps, URLs, and deep links](/docs/commands#navigation) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | -| [Install and reinstall an app](/docs/commands#app-install-in-place) | Yes | Yes | No | No | Yes | Yes | Yes | Yes | +| [Install and reinstall an app](/docs/commands#app-install-in-place) | Yes | Yes | No | No | Yes | Yes | Install only; reinstall refuses because Revyl cannot uninstall | Install only; reinstall refuses because Revyl cannot uninstall | | [Uninstall an app](/docs/commands#app-uninstall) | No | No | No | No | Yes | Yes | No | No | | [Install from a source URL](/docs/commands#app-install-from-source-url) | Yes | Yes | No | No | Yes | Yes | Yes | Yes | | [Installed app list](/docs/commands#app-state-and-app-lists) | No | No | No | No | Yes | Yes | No | No | diff --git a/website/docs/docs/revyl.md b/website/docs/docs/revyl.md index 4ce12d0c94..cf5ef68458 100644 --- a/website/docs/docs/revyl.md +++ b/website/docs/docs/revyl.md @@ -47,8 +47,19 @@ agent-device install com.example.app ./build/Example.app ``` `install` uploads the build to the session's storage, and Revyl installs it from there. For iOS, pass -a simulator `.app` directory, or the directory zipped or tarred. A device `.ipa` does not run on a -simulator. For Android, pass the `.apk`. +a simulator `.app` directory, or a `.zip`, `.tar.gz`, or `.tgz` of one. A device `.ipa` does not run on +a simulator. For Android, pass the `.apk`. + +`install-from-source` takes a build from a URL or a CI artifact instead. agent-device downloads it, +reads the app's identifier from it, and installs it the same way: + +```bash +agent-device install-from-source https://builds.example.com/app-debug.apk --platform android +``` + +`reinstall` refuses. Revyl cannot uninstall an app, and installing over one keeps its data, so it +cannot give you the clean app `reinstall` promises. Run `install` to update the build in place, or +start a new session for a clean app. `--provider-app` installs a hosted build when the device starts instead. It must be a public HTTPS URL that Revyl can download: the zipped `.app` for iOS, or the `.apk` for Android. @@ -80,8 +91,9 @@ A Revyl session runs the commands that reach a device through Revyl's device act the drag takes, from 1 to 10000 ms, when Revyl's worker supports it. An older worker picks the speed itself, so there the flag refuses rather than running the drag at a speed nobody chose. `fill --delay-ms` is paced by typing one character per pause. -- `install` of a local build, `open` with the app's bundle identifier or package name, `open` with a - deep link or URL, and `close` for the app the session opened. +- `install` of a local build, `install-from-source` from a URL or CI artifact, `open` with the app's + bundle identifier or package name, `open` with a deep link or URL, and `close` for the app the + session opened. - `home`, and `back` on Android. iOS has no system back button; click the app's own back control. The plugin refuses every other command with a reason that names the substitute. It does not @@ -92,6 +104,7 @@ report a refused command as a success: - `swipe` and `gesture` refuse. Use `scroll`, which plans the path itself and sends one drag. - `keyboard`, `clipboard`, `settings`, `orientation`, `alert`, `fold`, `telephony`, and `tv-remote` are not supported. +- `reinstall` refuses, as described above. - `uninstall`, `apps`, `push`, `logs`, `network dump`, `artifacts`, and `recordings` are not supported by this version of the plugin. - `port reverse` is unavailable. Publish your app server at a public HTTPS URL instead of pointing