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/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..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,13 +70,27 @@ 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.', }); }); +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.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 () => { const fixture = await backend({ respond: { 'GET /api/v1/entity/users/get_user_uuid': { status: 401, body: { error: 'nope' } } }, @@ -201,10 +215,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..3b0a6566c3 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.`, @@ -94,18 +96,27 @@ 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 }), 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 + ? { + // 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', + reference: profile.appUrl, + message: `App URL configured; ${REVYL_SERVICE} fetches and installs it when the session starts.`, + }, }; } @@ -133,14 +144,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 +156,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..98fcc55ca6 --- /dev/null +++ b/packages/provider-revyl/src/deployment.test.ts @@ -0,0 +1,205 @@ +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'); + // 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'), { + 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', + ); +}); + +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 new file mode 100644 index 0000000000..bd66ae3b35 --- /dev/null +++ b/packages/provider-revyl/src/deployment.ts @@ -0,0 +1,244 @@ +import fs from 'node:fs/promises'; +import type { + AppDeploymentResult, + MaterializedAppSource, +} from '@agent-device/contracts/app-deployment-runtime'; +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'; +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; +/** 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<{ + runId: string; + sessionId: string; + platform: 'ios' | 'android'; + client: RevylClient; +}>; + +type PackagedBuild = Readonly<{ + filePath: string; + contentType: string; + cleanup(): void; +}>; + +/** + * 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 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 { + 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 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, + deadline: DeadlineClock, +): Promise { + const build = await packageBuild(session.platform, appPath, env, signal); + try { + const { size } = await fs.stat(build.filePath); + const upload = await session.client.createSessionArtifactUpload( + session.sessionId, + size, + build.contentType, + 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 { + 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')) { + // 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)) + : undefined; + if (match) return fileBuild(appPath, match[1]); + throw unsupportedBuild(platform, appPath); +} + +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 a .zip, .tar.gz, or .tgz of one.', + { + 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: () => 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, + deadline: DeadlineClock, +): 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 }), + }); + } + 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( + status: string, + result: RevylWorkerActionResponse | undefined, +): RevylWorkerActionResponse { + const error = typeof result?.error === 'string' && result.error !== '' ? result.error : undefined; + const succeeded = result?.success ?? result?.Success; + // 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}`}`, + { + 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` 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 4037622dfe..6653e212f9 100644 --- a/packages/provider-revyl/src/platform-runtime.test.ts +++ b/packages/provider-revyl/src/platform-runtime.test.ts @@ -8,7 +8,13 @@ import { providerRuntimeOwner } from '@agent-device/contracts/platform-runtime'; import type { Interactor } from '@agent-device/contracts/interactor-types'; import { AppError } from '@agent-device/kernel/errors'; import type { DeviceInfo } from '@agent-device/kernel/device'; +import fs from 'node:fs/promises'; +import path from 'node:path'; +import { mkdtempForTest } from '@agent-device/test-kit'; +import type { MaterializedAppSource } from '@agent-device/contracts/app-deployment-runtime'; import { createRevylPlatformRuntimeOwner } from './platform-runtime.ts'; +import type { RevylDeploymentSession } from './deployment.ts'; +import type { RevylClient } from './revyl-client.ts'; const IOS_DEVICE: DeviceInfo = { platform: 'apple', @@ -30,13 +36,16 @@ const HOST = { function owner(options: { hasLiveSession: boolean; interactor?: Interactor; + host?: PlatformRuntimeHost; + deploymentSession?: RevylDeploymentSession; }): PlatformRuntimeOwner { return createRevylPlatformRuntimeOwner({ - host: HOST, + host: options.host ?? HOST, runtimeInstance: OWNER.instance, ownsDevice: () => true, hasLiveSession: () => options.hasLiveSession, getInteractor: () => options.interactor, + getDeploymentSession: () => options.deploymentSession, }); } @@ -121,3 +130,102 @@ 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', + ); +}); + +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 8a03962ac8..3a2ae44e2d 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,44 @@ 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) => { + // 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 }) + : 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-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 86b2dd6fae..b6569f6d1a 100644 --- a/packages/provider-revyl/src/revyl-client.ts +++ b/packages/provider-revyl/src/revyl-client.ts @@ -1,9 +1,14 @@ 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, + RevylInstallAccepted, + RevylInstallStatus, + RevylSessionArtifactUpload, RevylStartDeviceRequest, RevylStartDeviceResponse, RevylWorkerActionResponse, @@ -88,6 +93,33 @@ 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; + /** + * Streams the build file to the presigned URL; the URL carries its own authorization. The caller's + * signal bounds the upload. + */ + uploadSessionArtifact( + uploadUrl: string, + file: Readonly<{ filePath: string; size: number }>, + 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 +241,57 @@ 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, 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, init); + } 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/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/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/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 f380545e69..e4d0767c17 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 | 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 | 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..cf5ef68458 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,29 @@ 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 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. `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 +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. -- `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, `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 @@ -84,9 +104,9 @@ 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. +- `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 Metro at `localhost`.