| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| |
| import { randomUUID } from 'node:crypto'; |
| import { homedir } from 'node:os'; |
| import { join, resolve } from 'node:path'; |
| import { isDeepStrictEqual } from 'node:util'; |
| import { truncateUtf8 } from '@maka/core/diagnostic-log'; |
| import { generalizedErrorMessage } from '@maka/core/redaction'; |
| import { |
| activateRuntimeHostManagedDeployment, |
| connectRemoteRuntimeHost, |
| ensureRuntimeHostPeerIdentity, |
| RuntimeHostOperationError, |
| } from '@maka/runtime-host/client'; |
| import { |
| RuntimeHostManagedDeploymentError as RuntimeHostDeploymentAuthorityError, |
| encodeRuntimeHostSetupFrame, |
| isSha512PackageIntegrity, |
| resolveRuntimeHostManagedDeployment, |
| resolveRuntimeHostManagedDeploymentAuthority, |
| runtimeHostManagedOperatorCommand, |
| RUNTIME_HOST_SETUP_ERROR_CODE_MAX_BYTES, |
| RUNTIME_HOST_SETUP_ERROR_MESSAGE_MAX_BYTES, |
| type RuntimeHostManagedDeploymentConfig, |
| type RuntimeHostNodeOperatorCommand, |
| type RuntimeHostSetupFrame, |
| type RuntimeHostSetupPhase, |
| } from '@maka/runtime-host/operator'; |
| import { |
| INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID, |
| RUNTIME_HOST_PROTOCOL_VERSION, |
| } from '@maka/runtime-host/protocol'; |
| import { |
| prepareRuntimeHostAccessCredential, |
| replaceRuntimeHostAccessCredential, |
| revokeRuntimeHostAccessCredential, |
| RuntimeHostAccessUnavailableError, |
| type RuntimeHostAccessPreset, |
| } from './runtime-host-access-command.js'; |
| import { |
| convergeRuntimeHostManagedOperator, |
| verifyRuntimeHostManagedOperator, |
| isRuntimeHostDevelopmentPackageVersion, |
| openRuntimeHostManagedPackageDeployment, |
| prepareRuntimeHostManagedPackageDeployment, |
| pruneRuntimeHostManagedPackages, |
| removeRuntimeHostManagedDeployment, |
| resolveRuntimeHostManagedPackageCliPath, |
| resolveRuntimeHostManagedControlRoot, |
| resolveRuntimeHostManagedDeploymentRoot, |
| restoreRuntimeHostLegacyManagedOperator, |
| RuntimeHostManagedDeploymentError, |
| } from './runtime-host-managed-deployment.js'; |
| import { |
| RuntimeHostUpdatePackageError, |
| withRuntimeHostRegistryUpdatePackage, |
| } from './runtime-host-update-package.js'; |
| import { |
| readRuntimeHostManagedUpdatePolicy, |
| writeRuntimeHostManagedUpdatePolicy, |
| } from './runtime-host-update-policy-store.js'; |
| import { |
| resolveRuntimeHostRegistryUpdateCandidate, |
| RuntimeHostUpdateDiscoveryError, |
| type RuntimeHostUpdateCandidate, |
| } from './runtime-host-update-discovery.js'; |
| import { repairStorageRootAfterRemount, resolveStorageRoot } from '@maka/storage/root-authority'; |
| import { |
| createPlatformRuntimeHostServiceBackend, |
| discoverRuntimeHostLifecycleProvider, |
| resolveRuntimeHostLifecycleProvider, |
| } from './runtime-host-service-management-command.js'; |
| import { |
| allocateRuntimeHostLoopbackPort, |
| allocateRuntimeHostPeerPort, |
| effectiveRuntimeHostProjectDirectoryRoots, |
| manageRuntimeHostService, |
| readRuntimeHostManagedServiceConfig, |
| removeRuntimeHostServiceFile, |
| resolveRuntimeHostManagedServiceConfigPath, |
| resolveRuntimeHostManagedServiceId, |
| resolveRuntimeHostManagedProjectDirectoryRoots, |
| RuntimeHostServiceManagerError, |
| withRuntimeHostManagedServiceDeploymentLock, |
| withRuntimeHostManagedServiceLifecycleLock, |
| type RuntimeHostManagedServiceResult, |
| type RuntimeHostManagedServiceConfig, |
| type RuntimeHostManagedServiceTarget, |
| type RuntimeHostServiceBackend, |
| } from './runtime-host-service-manager.js'; |
| import { expandWildcardListenAddresses } from './runtime-host-peer-management-command.js'; |
| import { |
| canDiscardRuntimeHostLifecycleDesiredArtifacts, |
| replaceRuntimeHostLifecycle, |
| resolveRecoverableRuntimeHostManagedDeployment, |
| RUNTIME_HOST_READY_TIMEOUT_MS, |
| RuntimeHostLifecycleTransactionError, |
| type RuntimeHostLifecycleTransactionDeps, |
| } from './runtime-host-lifecycle-transaction.js'; |
| import type { |
| RuntimeHostLifecycleProvider, |
| RuntimeHostLifecycleProviderOffer, |
| } from './runtime-host-lifecycle-provider.js'; |
| import { |
| resolveRuntimeHostManagedPeerKeyPath, |
| resolveRuntimeHostNativePath, |
| } from './runtime-host-peer-artifact.js'; |
| import { activateRuntimeHostManagedDeploymentWithReconciliation } from './runtime-host-activation-command.js'; |
| |
| const SETUP_LOCK_TIMEOUT_MS = 5 * 60_000; |
| const PAIRING_AVAILABILITY_POLL_MS = 100; |
| |
| export interface RuntimeHostSetupCliOptions { |
| readonly json: boolean; |
| readonly clientDataRoot: string; |
| readonly defaultRootPath: string; |
| readonly sourcePackageRoot: string; |
| readonly version: string; |
| readonly sourcePackageIntegrity?: string; |
| readonly principalId: string; |
| readonly preset: RuntimeHostAccessPreset; |
| readonly lifecycle?: 'supervised' | 'on_demand'; |
| readonly deferPairingCommit?: boolean; |
| readonly bindPairingToClient?: boolean; |
| readonly repairRootAfterRemount?: true; |
| readonly updateExisting?: boolean; |
| readonly reuseExistingEnvironment?: boolean; |
| readonly allowInterruptActiveTasks?: boolean; |
| readonly rootPath?: string; |
| readonly projectDirectoryRoots?: readonly { |
| readonly label: string; |
| readonly path: string; |
| }[]; |
| readonly websocketPort?: number; |
| readonly websocketPath?: string; |
| readonly directPeer?: { |
| readonly coordinationRelays: readonly string[]; |
| }; |
| readonly expectedTarget?: RuntimeHostManagedServiceTarget; |
| } |
| |
| interface RuntimeHostSetupDeps { |
| readonly manageService: typeof manageRuntimeHostService; |
| readonly createBackend: (serviceId: string, clientDataRoot: string) => RuntimeHostServiceBackend; |
| readonly discoverLifecycleProvider: ( |
| rootId: string, |
| ) => Promise<RuntimeHostLifecycleProviderOffer>; |
| readonly resolveLifecycleProvider: ( |
| config: RuntimeHostManagedDeploymentConfig, |
| ) => RuntimeHostLifecycleProvider; |
| readonly replaceLifecycle: typeof replaceRuntimeHostLifecycle; |
| readonly openDeployment: typeof openRuntimeHostManagedPackageDeployment; |
| readonly prepareDeployment: typeof prepareRuntimeHostManagedPackageDeployment; |
| readonly prunePackages: typeof pruneRuntimeHostManagedPackages; |
| readonly prepareCredential: typeof prepareRuntimeHostAccessCredential; |
| readonly replaceCredential: typeof replaceRuntimeHostAccessCredential; |
| readonly revokeCredential: typeof revokeRuntimeHostAccessCredential; |
| readonly verifyCredential: typeof verifyRuntimeHostSetupCredential; |
| readonly activateDesired: typeof activateRuntimeHostManagedDeployment; |
| readonly activateManaged: typeof activateRuntimeHostManagedDeployment; |
| readonly convergeOperator: typeof convergeRuntimeHostManagedOperator; |
| readonly verifyOperator: typeof verifyRuntimeHostManagedOperator; |
| readonly resolveRegistryCandidate: typeof resolveRuntimeHostRegistryUpdateCandidate; |
| readonly withRegistryPackage: typeof withRuntimeHostRegistryUpdatePackage; |
| readonly ensurePeerIdentity: typeof ensureRuntimeHostPeerIdentity; |
| readonly resolvePeerNativePath: typeof resolveRuntimeHostNativePath; |
| readonly allocateLoopbackPort: typeof allocateRuntimeHostLoopbackPort; |
| readonly allocatePeerPort: typeof allocateRuntimeHostPeerPort; |
| readonly writeOutput: (value: string) => unknown; |
| readonly writeError: (value: string) => unknown; |
| } |
| |
| class RuntimeHostSetupError extends Error { |
| constructor( |
| readonly code: string, |
| message: string, |
| options?: ErrorOptions, |
| ) { |
| super(message, options); |
| this.name = 'RuntimeHostSetupError'; |
| } |
| } |
| |
| interface ResolvedRuntimeHostSetupPackage { |
| readonly candidate: RuntimeHostUpdateCandidate; |
| use<T>(operation: (packageRoot: string) => Promise<T>): Promise<T>; |
| } |
| |
| async function resolveRuntimeHostSetupPackage( |
| options: RuntimeHostSetupCliOptions, |
| deps: Pick<RuntimeHostSetupDeps, 'resolveRegistryCandidate' | 'withRegistryPackage'>, |
| ): Promise<ResolvedRuntimeHostSetupPackage> { |
| if (isRuntimeHostDevelopmentPackageVersion(options.version)) { |
| const integrity = options.sourcePackageIntegrity; |
| if (typeof integrity !== 'string' || !isSha512PackageIntegrity(integrity)) { |
| throw new RuntimeHostSetupError( |
| 'development_package_unverified', |
| 'The Runtime Host development package is missing exact artifact evidence', |
| ); |
| } |
| return { |
| candidate: { |
| kind: 'npm_registry', |
| version: options.version, |
| integrity, |
| }, |
| use: (operation) => operation(options.sourcePackageRoot), |
| }; |
| } |
| const candidate = await deps.resolveRegistryCandidate({ |
| kind: 'exact', |
| version: options.version, |
| }); |
| return { |
| candidate, |
| use: (operation) => deps.withRegistryPackage(candidate, operation), |
| }; |
| } |
| |
| export async function runRuntimeHostSetupCli( |
| options: RuntimeHostSetupCliOptions, |
| overrides: Partial<RuntimeHostSetupDeps> = {}, |
| ): Promise<number> { |
| const deps: RuntimeHostSetupDeps = { |
| manageService: manageRuntimeHostService, |
| createBackend: createPlatformRuntimeHostServiceBackend, |
| discoverLifecycleProvider: discoverRuntimeHostLifecycleProvider, |
| resolveLifecycleProvider: resolveRuntimeHostLifecycleProvider, |
| replaceLifecycle: replaceRuntimeHostLifecycle, |
| openDeployment: openRuntimeHostManagedPackageDeployment, |
| prepareDeployment: prepareRuntimeHostManagedPackageDeployment, |
| prunePackages: pruneRuntimeHostManagedPackages, |
| prepareCredential: prepareRuntimeHostAccessCredential, |
| replaceCredential: replaceRuntimeHostAccessCredential, |
| revokeCredential: revokeRuntimeHostAccessCredential, |
| verifyCredential: verifyRuntimeHostSetupCredential, |
| activateDesired: (input) => |
| activateRuntimeHostManagedDeployment(input, { |
| reconcileActivation: async () => undefined, |
| }), |
| activateManaged: (input) => |
| activateRuntimeHostManagedDeploymentWithReconciliation(input, { |
| deploymentLockHeld: true, |
| }), |
| convergeOperator: convergeRuntimeHostManagedOperator, |
| verifyOperator: verifyRuntimeHostManagedOperator, |
| resolveRegistryCandidate: resolveRuntimeHostRegistryUpdateCandidate, |
| withRegistryPackage: withRuntimeHostRegistryUpdatePackage, |
| ensurePeerIdentity: ensureRuntimeHostPeerIdentity, |
| resolvePeerNativePath: resolveRuntimeHostNativePath, |
| allocateLoopbackPort: allocateRuntimeHostLoopbackPort, |
| allocatePeerPort: allocateRuntimeHostPeerPort, |
| writeOutput: (value) => process.stdout.write(value), |
| writeError: (value) => process.stderr.write(value), |
| ...overrides, |
| }; |
| const emit = createEmitter(options.json, deps); |
| try { |
| const rootId = await resolveRuntimeHostSetupRootId(options); |
| const controlRoot = resolveRuntimeHostManagedControlRoot(rootId); |
| await withRuntimeHostManagedServiceDeploymentLock( |
| options.clientDataRoot, |
| () => |
| withRuntimeHostManagedServiceLifecycleLock( |
| options.clientDataRoot, |
| () => |
| withRuntimeHostManagedServiceDeploymentLock( |
| controlRoot, |
| () => |
| withRuntimeHostManagedServiceLifecycleLock( |
| controlRoot, |
| () => runRuntimeHostSetupLocked(options, deps, emit, rootId), |
| SETUP_LOCK_TIMEOUT_MS, |
| ), |
| SETUP_LOCK_TIMEOUT_MS, |
| ), |
| SETUP_LOCK_TIMEOUT_MS, |
| ), |
| SETUP_LOCK_TIMEOUT_MS, |
| ); |
| return 0; |
| } catch (error) { |
| const failure = setupFailure(error); |
| emit({ kind: 'error', error: failure }); |
| return 1; |
| } |
| } |
| |
| async function resolveRuntimeHostSetupRootId(options: RuntimeHostSetupCliOptions): Promise<string> { |
| const legacyRootPath = (await readOptionalLegacyServiceConfig(options.clientDataRoot))?.rootPath; |
| const path = resolve( |
| options.rootPath ?? |
| legacyRootPath ?? |
| options.expectedTarget?.rootPath ?? |
| options.defaultRootPath, |
| ); |
| if (options.repairRootAfterRemount) { |
| await repairStorageRootAfterRemount({ path, kind: 'interactive' }); |
| } |
| return (await resolveStorageRoot({ path, kind: 'interactive' })).rootId; |
| } |
| |
| async function readOptionalLegacyServiceConfig( |
| clientDataRoot: string, |
| ): Promise<RuntimeHostManagedServiceConfig | null> { |
| try { |
| return await readRuntimeHostManagedServiceConfig( |
| resolveRuntimeHostManagedServiceConfigPath(clientDataRoot), |
| ); |
| } catch (error) { |
| if (error instanceof RuntimeHostServiceManagerError && error.code === 'not_installed') { |
| return null; |
| } |
| throw error; |
| } |
| } |
| |
| async function runRuntimeHostSetupLocked( |
| options: RuntimeHostSetupCliOptions, |
| deps: RuntimeHostSetupDeps, |
| emit: SetupEmitter, |
| rootId: string, |
| ): Promise<void> { |
| if (options.reuseExistingEnvironment) { |
| if (options.lifecycle !== 'on_demand' || options.updateExisting) { |
| throw new RuntimeHostSetupError( |
| 'invalid_setup', |
| 'Environment discovery cannot replace a deployment', |
| ); |
| } |
| const existing = await resolveRuntimeHostManagedDeploymentAuthority(rootId); |
| if (existing) { |
| const { config, capability } = await resolveRuntimeHostManagedDeployment(rootId); |
| assertCanonicalSetupTarget(options.expectedTarget, rootId, capability.canonicalPath); |
| assertExpectedDeploymentGeneration(options.expectedTarget, config); |
| // The binding comes from canonical authority. The installed operator validates |
| // its own projection when connected; discovery must not rewrite an older launcher. |
| emit({ |
| kind: 'existing_environment', |
| version: config.launch.package.version, |
| serviceId: rootId, |
| deploymentId: config.deploymentId, |
| rootId, |
| rootPath: capability.canonicalPath, |
| operator: runtimeHostManagedOperatorCommand( |
| config, |
| process.platform === 'win32' ? 'win32' : 'posix', |
| ), |
| }); |
| return; |
| } |
| } |
| if (options.lifecycle === 'on_demand') { |
| await runRuntimeHostOnDemandSetupLocked(options, deps, emit); |
| return; |
| } |
| const target = await runRuntimeHostSupervisedSetupLocked(options, deps, emit); |
| await pairAndVerifyRuntimeHostSetup(options, target, deps, emit); |
| } |
| |
| async function runRuntimeHostSupervisedSetupLocked( |
| options: RuntimeHostSetupCliOptions, |
| deps: RuntimeHostSetupDeps, |
| emit: SetupEmitter, |
| ): Promise<{ |
| readonly serviceId: string; |
| readonly deploymentId: string; |
| readonly operator: RuntimeHostNodeOperatorCommand; |
| readonly rootPath: string; |
| readonly endpoint: string; |
| readonly directPeer?: { |
| readonly peerId: string; |
| readonly routeHints: readonly string[]; |
| readonly coordinationRelays: readonly string[]; |
| }; |
| }> { |
| emit({ kind: 'progress', phase: 'checking_environment' }); |
| const legacyServiceId = resolveRuntimeHostManagedServiceId(options.clientDataRoot); |
| const legacyConfig = await readOptionalLegacyServiceConfig(options.clientDataRoot); |
| const legacyBackend = legacyConfig |
| ? deps.createBackend(legacyServiceId, options.clientDataRoot) |
| : undefined; |
| const legacyCommon = { |
| clientDataRoot: options.clientDataRoot, |
| defaultRootPath: options.defaultRootPath, |
| nodePath: process.execPath, |
| cliPath: join(options.sourcePackageRoot, 'dist', 'cli.js'), |
| ...(options.expectedTarget |
| ? { expectedTarget: legacyManagedTarget(options.expectedTarget, legacyServiceId) } |
| : {}), |
| } as const; |
| const legacyStatus = legacyBackend |
| ? await deps.manageService({ ...legacyCommon, action: 'status' }, legacyBackend) |
| : undefined; |
| const capability = await resolveStorageRoot({ |
| path: resolve( |
| options.rootPath ?? |
| legacyConfig?.rootPath ?? |
| options.expectedTarget?.rootPath ?? |
| options.defaultRootPath, |
| ), |
| kind: 'interactive', |
| }); |
| assertCanonicalSetupTarget(options.expectedTarget, capability.rootId, capability.canonicalPath); |
| const lifecycleDeps: RuntimeHostLifecycleTransactionDeps = { |
| convergeOperator: (currentConfig, desiredConfig) => |
| deps.convergeOperator(currentConfig, desiredConfig), |
| verifyOperator: deps.verifyOperator, |
| resolveProvider: deps.resolveLifecycleProvider, |
| ...(legacyConfig && legacyBackend |
| ? legacyMigrationDeps(legacyConfig, legacyBackend, legacyServiceId, options.clientDataRoot) |
| : {}), |
| }; |
| const recovered = await resolveRecoverableRuntimeHostManagedDeployment( |
| capability.rootId, |
| lifecycleDeps, |
| { |
| ...(legacyBackend ? { retirementSupervisor: legacyBackend } : {}), |
| ...(legacyBackend |
| ? { |
| activatePrevious: () => |
| deps |
| .manageService({ ...legacyCommon, action: 'start' }, legacyBackend) |
| .then(() => undefined), |
| } |
| : {}), |
| ...(options.expectedTarget ? { expectedTarget: options.expectedTarget } : {}), |
| }, |
| ); |
| const current = recovered.kind === 'active' ? recovered.config : undefined; |
| assertExpectedDeploymentGeneration(options.expectedTarget, current); |
| const legacyToMigrate = current ? null : legacyConfig; |
| if (current && legacyBackend) await assertLegacyArtifactsAbsent(legacyBackend); |
| if (legacyToMigrate && legacyStatus) { |
| await assertCompatibleExistingVersion(legacyStatus, options.version); |
| } |
| if (current && current.launch.package.version !== options.version && !options.updateExisting) { |
| throw new RuntimeHostSetupError( |
| 'version_change_requires_update', |
| `Runtime Host ${current.launch.package.version} is already installed; changing to ${options.version} requires the update workflow`, |
| ); |
| } |
| |
| const resolvedPackage = await resolveRuntimeHostSetupPackage(options, deps); |
| const { candidate } = resolvedPackage; |
| const packageChanged = current !== undefined && !sameExactPackage(current, candidate); |
| if (current && packageChanged && !options.updateExisting) { |
| throw new RuntimeHostSetupError( |
| 'version_change_requires_update', |
| `Runtime Host ${current.launch.package.version} is already installed; changing its exact package requires the update workflow`, |
| ); |
| } |
| const lifecycleOffer: RuntimeHostLifecycleProviderOffer = |
| current?.lifecycle.mode === 'supervised' |
| ? { |
| provider: deps.resolveLifecycleProvider(current), |
| availability: current.lifecycle.availability, |
| } |
| : await deps.discoverLifecycleProvider(capability.rootId); |
| return resolvedPackage.use(async (packageRoot) => { |
| emit({ kind: 'progress', phase: 'installing_package' }); |
| const deployment = await deps.prepareDeployment({ |
| serviceId: capability.rootId, |
| clientDataRoot: options.clientDataRoot, |
| sourcePackageRoot: packageRoot, |
| version: candidate.version, |
| packageIntegrity: candidate.integrity, |
| ...(current ? { deploymentRoot: current.deploymentRoot } : {}), |
| }); |
| let committed = false; |
| try { |
| const desired = await prepareSupervisedDeploymentConfig( |
| options, |
| deps, |
| capability, |
| deployment.cliPath, |
| deployment.root, |
| candidate, |
| current, |
| legacyToMigrate, |
| lifecycleOffer, |
| ); |
| if ( |
| current && |
| !sameDesiredManagedDeployment(current, desired) && |
| !options.updateExisting && |
| current.lifecycle.mode === 'supervised' |
| ) { |
| throw new RuntimeHostSetupError( |
| 'configuration_changed', |
| 'Change an existing supervised Runtime Host through its explicit configure or update workflow', |
| ); |
| } |
| emit({ kind: 'progress', phase: 'installing_service' }); |
| if (legacyToMigrate && legacyBackend) { |
| await legacyBackend.verifyDeployment(legacyToMigrate, { |
| acceptLegacyConfigLaunch: true, |
| }); |
| } |
| const replacement = await deps.replaceLifecycle({ |
| operation: legacyToMigrate |
| ? 'legacy_migration' |
| : current |
| ? packageChanged |
| ? 'update' |
| : isDeepStrictEqual(current.lifecycle, desired.lifecycle) |
| ? 'configure' |
| : 'lifecycle_change' |
| : 'install', |
| ...(current ? { current } : {}), |
| desired, |
| ...(legacyToMigrate && legacyBackend ? { retirementSupervisor: legacyBackend } : {}), |
| ...(legacyToMigrate && legacyBackend |
| ? { |
| activatePrevious: () => |
| deps |
| .manageService({ ...legacyCommon, action: 'start' }, legacyBackend) |
| .then(() => undefined), |
| } |
| : {}), |
| allowInterruptActiveTasks: options.allowInterruptActiveTasks === true, |
| deps: lifecycleDeps, |
| }); |
| if (replacement.kind === 'active_tasks') { |
| throw new RuntimeHostSetupError( |
| 'active_tasks', |
| 'Runtime Host setup is waiting for active work to finish', |
| ); |
| } |
| committed = true; |
| if (legacyConfig) { |
| await removeRuntimeHostServiceFile( |
| resolveRuntimeHostManagedServiceConfigPath(options.clientDataRoot), |
| 'legacy service config', |
| ); |
| if ( |
| legacyConfig.managedDeploymentRoot && |
| resolve(legacyConfig.managedDeploymentRoot) !== resolve(deployment.root) |
| ) { |
| await removeRuntimeHostManagedDeployment( |
| legacyConfig.managedDeploymentRoot, |
| legacyServiceId, |
| ); |
| } |
| } |
| await deps.prunePackages(desired); |
| const websocket = desired.listeners.websocket; |
| if (!websocket) { |
| throw new RuntimeHostSetupError( |
| 'service_not_ready', |
| 'Supervised Runtime Host setup requires a WebSocket listener', |
| ); |
| } |
| const directPeer = desired.listeners.directPeer?.enabled |
| ? desired.listeners.directPeer |
| : undefined; |
| return { |
| serviceId: capability.rootId, |
| deploymentId: desired.deploymentId, |
| operator: runtimeHostManagedOperatorCommand( |
| desired, |
| process.platform === 'win32' ? 'win32' : 'posix', |
| ), |
| rootPath: capability.canonicalPath, |
| endpoint: websocketUrl(websocket), |
| ...(directPeer |
| ? { |
| directPeer: { |
| peerId: directPeer.peerId, |
| routeHints: expandWildcardListenAddresses(directPeer.listenAddresses), |
| coordinationRelays: [...directPeer.coordinationRelays], |
| }, |
| } |
| : {}), |
| }; |
| } catch (error) { |
| if (!committed && canDiscardRuntimeHostLifecycleDesiredArtifacts(error)) { |
| if (current && packageChanged) { |
| await deployment.rollback().catch(() => undefined); |
| } else if (!current) { |
| await removeRuntimeHostManagedDeployment(deployment.root, capability.rootId).catch( |
| () => undefined, |
| ); |
| } |
| } |
| throw error; |
| } |
| }); |
| } |
| |
| async function prepareSupervisedDeploymentConfig( |
| options: RuntimeHostSetupCliOptions, |
| deps: RuntimeHostSetupDeps, |
| capability: Awaited<ReturnType<typeof resolveStorageRoot>>, |
| cliPath: string, |
| deploymentRoot: string, |
| candidate: { readonly version: string; readonly integrity: string }, |
| current: RuntimeHostManagedDeploymentConfig | undefined, |
| legacy: RuntimeHostManagedServiceConfig | null, |
| offer: RuntimeHostLifecycleProviderOffer, |
| ): Promise<RuntimeHostManagedDeploymentConfig> { |
| const projectDirectoryRoots = await resolveRuntimeHostManagedProjectDirectoryRoots( |
| options.projectDirectoryRoots ?? |
| current?.projectDirectoryRoots ?? |
| (legacy |
| ? effectiveRuntimeHostProjectDirectoryRoots(legacy) |
| : [{ label: '~', path: resolve(homedir()) }]), |
| ); |
| const currentWebSocket = current?.listeners.websocket; |
| const websocketPort = |
| options.websocketPort ?? |
| (currentWebSocket && currentWebSocket.port > 0 |
| ? currentWebSocket.port |
| : legacy?.websocket.port) ?? |
| (await deps.allocateLoopbackPort()); |
| const directPeer = await prepareSupervisedDirectPeer( |
| options, |
| deps, |
| cliPath, |
| deploymentRoot, |
| current?.listeners.directPeer, |
| ); |
| const draft: RuntimeHostManagedDeploymentConfig = { |
| schemaVersion: 1, |
| state: 'active', |
| deploymentId: current?.deploymentId ?? randomUUID(), |
| configRevision: current ? current.configRevision + 1 : 1, |
| deploymentRoot, |
| root: { path: capability.canonicalPath, id: capability.rootId }, |
| projectDirectoryRoots: [...projectDirectoryRoots], |
| launch: { |
| kind: 'exact_package', |
| nodePath: current?.launch.nodePath ?? process.execPath, |
| package: { |
| kind: 'npm_registry', |
| version: candidate.version, |
| integrity: candidate.integrity, |
| }, |
| }, |
| listeners: { |
| localIpc: true, |
| websocket: { |
| host: '127.0.0.1', |
| port: websocketPort, |
| path: |
| options.websocketPath ?? |
| currentWebSocket?.path ?? |
| legacy?.websocket.path ?? |
| '/runtime-host', |
| }, |
| ...(directPeer ? { directPeer } : {}), |
| }, |
| lifecycle: { |
| mode: 'supervised', |
| provider: offer.provider.supervisor.provider, |
| availability: offer.availability, |
| }, |
| reconciliation: { |
| trigger: 'scheduled', |
| provider: offer.provider.reconciliationTrigger.provider, |
| }, |
| }; |
| return draft; |
| } |
| |
| async function prepareSupervisedDirectPeer( |
| options: RuntimeHostSetupCliOptions, |
| deps: RuntimeHostSetupDeps, |
| cliPath: string, |
| deploymentRoot: string, |
| current: RuntimeHostManagedDeploymentConfig['listeners']['directPeer'], |
| ): Promise<RuntimeHostManagedDeploymentConfig['listeners']['directPeer']> { |
| if (!options.directPeer && !current) return undefined; |
| const keyPath = current?.keyPath ?? resolveRuntimeHostManagedPeerKeyPath(deploymentRoot); |
| const peerId = await deps.ensurePeerIdentity({ |
| nativePath: await deps.resolvePeerNativePath(cliPath), |
| keyPath, |
| }); |
| const expectedPeerId = current?.peerId; |
| if (expectedPeerId && expectedPeerId !== peerId) { |
| throw new RuntimeHostSetupError( |
| 'invalid_config', |
| 'The Runtime Host peer identity does not match its persisted deployment', |
| ); |
| } |
| return { |
| enabled: options.directPeer ? true : (current?.enabled ?? true), |
| keyPath, |
| peerId, |
| listenAddresses: [ |
| ...(current?.listenAddresses ?? [ |
| `/ip4/0.0.0.0/udp/${String(await deps.allocatePeerPort())}/quic-v1`, |
| ]), |
| ], |
| coordinationRelays: [ |
| ...(options.directPeer?.coordinationRelays ?? current?.coordinationRelays ?? []), |
| ], |
| automaticRelayDiscovery: current?.automaticRelayDiscovery ?? true, |
| webRtcStunPolicy: current?.webRtcStunPolicy ?? { kind: 'default' }, |
| }; |
| } |
| |
| function sameDesiredManagedDeployment( |
| current: RuntimeHostManagedDeploymentConfig, |
| desired: RuntimeHostManagedDeploymentConfig, |
| ): boolean { |
| const { configRevision: _currentRevision, ...currentState } = current; |
| const { configRevision: _desiredRevision, ...desiredState } = desired; |
| return isDeepStrictEqual(currentState, desiredState); |
| } |
| |
| async function runRuntimeHostOnDemandSetupLocked( |
| options: RuntimeHostSetupCliOptions, |
| deps: RuntimeHostSetupDeps, |
| emit: SetupEmitter, |
| ): Promise<void> { |
| if (options.directPeer) { |
| throw new RuntimeHostSetupError( |
| 'unsupported_lifecycle_configuration', |
| 'On-demand setup does not support a Direct peer listener', |
| ); |
| } |
| emit({ kind: 'progress', phase: 'checking_environment' }); |
| const legacyServiceId = resolveRuntimeHostManagedServiceId(options.clientDataRoot); |
| const legacyConfig = await readOptionalLegacyServiceConfig(options.clientDataRoot); |
| const legacyBackend = legacyConfig |
| ? deps.createBackend(legacyServiceId, options.clientDataRoot) |
| : undefined; |
| let legacyStatus: RuntimeHostManagedServiceResult | undefined; |
| if (legacyBackend) { |
| legacyStatus = await deps.manageService( |
| { |
| action: 'status', |
| clientDataRoot: options.clientDataRoot, |
| defaultRootPath: options.defaultRootPath, |
| nodePath: process.execPath, |
| cliPath: join(options.sourcePackageRoot, 'dist', 'cli.js'), |
| ...(options.expectedTarget |
| ? { expectedTarget: legacyManagedTarget(options.expectedTarget, legacyServiceId) } |
| : {}), |
| }, |
| legacyBackend, |
| ); |
| } |
| const capability = await resolveStorageRoot({ |
| path: resolve( |
| options.rootPath ?? |
| legacyConfig?.rootPath ?? |
| options.expectedTarget?.rootPath ?? |
| options.defaultRootPath, |
| ), |
| kind: 'interactive', |
| }); |
| assertCanonicalSetupTarget(options.expectedTarget, capability.rootId, capability.canonicalPath); |
| const recoveryDeps: RuntimeHostLifecycleTransactionDeps = { |
| convergeOperator: (currentConfig, desiredConfig) => |
| deps.convergeOperator(currentConfig, desiredConfig), |
| verifyOperator: deps.verifyOperator, |
| resolveProvider: deps.resolveLifecycleProvider, |
| ...(legacyConfig && legacyBackend |
| ? legacyMigrationDeps(legacyConfig, legacyBackend, legacyServiceId, options.clientDataRoot) |
| : {}), |
| }; |
| const recovered = await resolveRecoverableRuntimeHostManagedDeployment( |
| capability.rootId, |
| recoveryDeps, |
| { |
| ...(legacyBackend ? { retirementSupervisor: legacyBackend } : {}), |
| ...(legacyBackend ? { activatePrevious: () => legacyBackend.start() } : {}), |
| ...(options.expectedTarget ? { expectedTarget: options.expectedTarget } : {}), |
| }, |
| ); |
| const current = recovered.kind === 'active' ? recovered.config : undefined; |
| const legacyToMigrate = current ? null : legacyConfig; |
| if (current && legacyBackend) await assertLegacyArtifactsAbsent(legacyBackend); |
| if (legacyToMigrate && legacyStatus) { |
| await assertCompatibleExistingVersion(legacyStatus, options.version); |
| } |
| assertExpectedDeploymentGeneration(options.expectedTarget, current); |
| const resolvedPackage = await resolveRuntimeHostSetupPackage(options, deps); |
| const { candidate } = resolvedPackage; |
| const serviceId = capability.rootId; |
| const deploymentRoot = |
| current?.deploymentRoot ?? resolveRuntimeHostManagedDeploymentRoot(serviceId); |
| const packageChanged = current !== undefined && !sameExactPackage(current, candidate); |
| if (current && packageChanged && !options.updateExisting) { |
| throw new RuntimeHostSetupError( |
| 'version_change_requires_update', |
| `Runtime Host ${current.launch.package.version} is already installed; changing its exact package requires the update workflow`, |
| ); |
| } |
| const draft: RuntimeHostManagedDeploymentConfig = { |
| schemaVersion: 1, |
| state: 'active', |
| deploymentId: current?.deploymentId ?? randomUUID(), |
| configRevision: current ? current.configRevision + 1 : 1, |
| deploymentRoot, |
| root: { path: capability.canonicalPath, id: capability.rootId }, |
| projectDirectoryRoots: options.projectDirectoryRoots?.map(({ label, path }) => ({ |
| label, |
| path: resolve(path), |
| })) ?? |
| current?.projectDirectoryRoots ?? [{ label: '~', path: resolve(homedir()) }], |
| launch: { |
| kind: 'exact_package', |
| nodePath: current?.launch.nodePath ?? process.execPath, |
| package: { |
| kind: 'npm_registry', |
| version: candidate.version, |
| integrity: candidate.integrity, |
| }, |
| }, |
| listeners: { |
| localIpc: true, |
| websocket: { |
| host: '127.0.0.1', |
| port: options.websocketPort ?? 0, |
| path: options.websocketPath ?? current?.listeners.websocket?.path ?? '/runtime-host', |
| }, |
| ...(current?.listeners.directPeer |
| ? { directPeer: { ...current.listeners.directPeer, enabled: false } } |
| : {}), |
| }, |
| lifecycle: { mode: 'on_demand', availability: 'activation' }, |
| reconciliation: { trigger: 'activation' }, |
| }; |
| const reuseCurrent = |
| current?.lifecycle.mode === 'on_demand' && sameDesiredManagedDeployment(current, draft); |
| const config = reuseCurrent ? current : draft; |
| let activation: Awaited<ReturnType<typeof activateRuntimeHostManagedDeployment>> | undefined; |
| const lifecycleDeps: RuntimeHostLifecycleTransactionDeps = { |
| convergeOperator: (currentConfig, desiredConfig) => |
| deps.convergeOperator(currentConfig, desiredConfig), |
| verifyOperator: deps.verifyOperator, |
| resolveProvider: deps.resolveLifecycleProvider, |
| ...(legacyToMigrate && legacyBackend |
| ? legacyMigrationDeps(legacyToMigrate, legacyBackend, legacyServiceId, options.clientDataRoot) |
| : {}), |
| }; |
| const deployedConfig = await resolvedPackage.use(async (packageRoot) => { |
| let committed = false; |
| const created = !current; |
| let deployment: Awaited<ReturnType<typeof deps.prepareDeployment>> | undefined; |
| try { |
| emit({ kind: 'progress', phase: 'installing_package' }); |
| deployment = |
| current && !packageChanged |
| ? await deps.openDeployment({ |
| serviceId, |
| clientDataRoot: options.clientDataRoot, |
| deploymentRoot, |
| cliPath: resolveRuntimeHostManagedPackageCliPath( |
| deploymentRoot, |
| candidate.version, |
| candidate.integrity, |
| ), |
| version: candidate.version, |
| }) |
| : await deps.prepareDeployment({ |
| serviceId, |
| clientDataRoot: options.clientDataRoot, |
| sourcePackageRoot: packageRoot, |
| version: candidate.version, |
| packageIntegrity: candidate.integrity, |
| ...(current ? { deploymentRoot } : {}), |
| }); |
| const desiredConfig: RuntimeHostManagedDeploymentConfig = current |
| ? config |
| : { ...config, deploymentRoot: deployment.root }; |
| emit({ kind: 'progress', phase: 'installing_service' }); |
| if (legacyToMigrate && legacyBackend) { |
| await legacyBackend.verifyDeployment(legacyToMigrate, { |
| acceptLegacyConfigLaunch: true, |
| }); |
| } |
| if (reuseCurrent) { |
| await deps.convergeOperator(current, current); |
| await deps.verifyOperator(current); |
| } else { |
| const replacement = await deps.replaceLifecycle({ |
| operation: legacyToMigrate |
| ? 'legacy_migration' |
| : packageChanged |
| ? 'update' |
| : current |
| ? isDeepStrictEqual(current.lifecycle, config.lifecycle) |
| ? 'configure' |
| : 'lifecycle_change' |
| : 'install', |
| ...(current ? { current } : {}), |
| desired: desiredConfig, |
| ...(legacyToMigrate && legacyBackend ? { retirementSupervisor: legacyBackend } : {}), |
| ...(legacyToMigrate && legacyBackend |
| ? { activatePrevious: () => legacyBackend.start() } |
| : {}), |
| activateDesired: async () => { |
| await deps.activateDesired({ rootId: capability.rootId }); |
| }, |
| allowInterruptActiveTasks: options.allowInterruptActiveTasks === true, |
| deps: lifecycleDeps, |
| }); |
| if (replacement.kind === 'active_tasks') { |
| throw new RuntimeHostSetupError( |
| 'active_tasks', |
| 'Runtime Host setup is waiting for active work to finish', |
| ); |
| } |
| } |
| committed = true; |
| await deps.prunePackages( |
| (await resolveRuntimeHostManagedDeployment(capability.rootId)).config, |
| ); |
| return desiredConfig; |
| } catch (error) { |
| if (!committed && canDiscardRuntimeHostLifecycleDesiredArtifacts(error)) { |
| if (packageChanged && deployment) await deployment.rollback().catch(() => undefined); |
| else if (created) { |
| await removeRuntimeHostManagedDeployment(deploymentRoot, serviceId).catch( |
| () => undefined, |
| ); |
| } |
| } |
| throw error; |
| } |
| }); |
| activation = await deps.activateManaged({ rootId: capability.rootId }); |
| if (legacyConfig) { |
| await removeRuntimeHostServiceFile( |
| resolveRuntimeHostManagedServiceConfigPath(options.clientDataRoot), |
| 'legacy service config', |
| ); |
| if ( |
| legacyConfig.managedDeploymentRoot && |
| resolve(legacyConfig.managedDeploymentRoot) !== resolve(config.deploymentRoot) |
| ) { |
| await removeRuntimeHostManagedDeployment(legacyConfig.managedDeploymentRoot, legacyServiceId); |
| } |
| } |
| await pairAndVerifyRuntimeHostSetup( |
| options, |
| { |
| serviceId, |
| deploymentId: deployedConfig.deploymentId, |
| operator: runtimeHostManagedOperatorCommand( |
| deployedConfig, |
| process.platform === 'win32' ? 'win32' : 'posix', |
| ), |
| rootPath: capability.canonicalPath, |
| endpoint: websocketUrl({ |
| host: activation.endpoint.host, |
| port: activation.endpoint.port, |
| path: activation.endpoint.websocketPath, |
| }), |
| }, |
| deps, |
| emit, |
| ); |
| } |
| |
| function legacyMigrationDeps( |
| config: RuntimeHostManagedServiceConfig, |
| backend: RuntimeHostServiceBackend, |
| legacyServiceId: string, |
| clientDataRoot: string, |
| ): Pick<RuntimeHostLifecycleTransactionDeps, 'uninstallLegacy' | 'restoreLegacy'> { |
| return { |
| uninstallLegacy: async (transition) => { |
| await projectLegacyUpdatePolicy(config, legacyServiceId, transition.to ?? transition.from); |
| await backend.uninstall(); |
| }, |
| restoreLegacy: async (transition) => { |
| await removeProjectedLegacyUpdatePolicy(config, transition.to ?? transition.from); |
| if (config.managedDeploymentRoot) { |
| await restoreRuntimeHostLegacyManagedOperator({ |
| deploymentRoot: config.managedDeploymentRoot, |
| nodePath: config.launch.nodePath, |
| cliPath: config.launch.cliPath, |
| clientDataRoot, |
| serviceId: legacyServiceId, |
| }); |
| } |
| const restoration = await backend.stageDeployment(); |
| await restoration.apply(config, false); |
| }, |
| }; |
| } |
| |
| async function projectLegacyUpdatePolicy( |
| config: RuntimeHostManagedServiceConfig, |
| legacyServiceId: string, |
| desired: RuntimeHostManagedDeploymentConfig | null, |
| ): Promise<void> { |
| if (!config.managedDeploymentRoot || !desired) return; |
| const record = await readRuntimeHostManagedUpdatePolicy(config.managedDeploymentRoot); |
| if (record) { |
| if ( |
| record.target.serviceId !== legacyServiceId || |
| record.target.rootId !== desired.root.id || |
| resolve(record.target.rootPath) !== resolve(desired.root.path) |
| ) { |
| throw new RuntimeHostSetupError( |
| 'target_mismatch', |
| 'The legacy automatic update policy does not match the Runtime Host migration target', |
| ); |
| } |
| await writeRuntimeHostManagedUpdatePolicy(desired.deploymentRoot, { |
| ...record, |
| target: { |
| serviceId: desired.root.id, |
| rootId: desired.root.id, |
| rootPath: desired.root.path, |
| deploymentId: desired.deploymentId, |
| }, |
| }); |
| } else { |
| await writeRuntimeHostManagedUpdatePolicy(desired.deploymentRoot, null); |
| } |
| } |
| |
| async function removeProjectedLegacyUpdatePolicy( |
| config: RuntimeHostManagedServiceConfig, |
| desired: RuntimeHostManagedDeploymentConfig | null, |
| ): Promise<void> { |
| if ( |
| config.managedDeploymentRoot && |
| desired && |
| resolve(config.managedDeploymentRoot) !== resolve(desired.deploymentRoot) |
| ) { |
| await writeRuntimeHostManagedUpdatePolicy(desired.deploymentRoot, null); |
| } |
| } |
| |
| function legacyManagedTarget( |
| target: RuntimeHostManagedServiceTarget, |
| legacyServiceId: string, |
| ): RuntimeHostManagedServiceTarget { |
| return { |
| serviceId: legacyServiceId, |
| rootPath: target.rootPath, |
| rootId: target.rootId, |
| }; |
| } |
| |
| function assertCanonicalSetupTarget( |
| target: RuntimeHostManagedServiceTarget | undefined, |
| rootId: string, |
| rootPath: string, |
| ): void { |
| if ( |
| target && |
| (target.serviceId !== rootId || target.rootId !== rootId || target.rootPath !== rootPath) |
| ) { |
| throw new RuntimeHostSetupError( |
| 'target_mismatch', |
| 'The managed Runtime Host does not match the expected deployment identity', |
| ); |
| } |
| } |
| |
| function assertExpectedDeploymentGeneration( |
| target: RuntimeHostManagedServiceTarget | undefined, |
| current: RuntimeHostManagedDeploymentConfig | undefined, |
| ): void { |
| if ( |
| target?.deploymentId !== undefined && |
| (!current || target.deploymentId !== current.deploymentId) |
| ) { |
| throw new RuntimeHostSetupError( |
| 'target_mismatch', |
| 'The managed Runtime Host deployment generation changed before setup', |
| ); |
| } |
| } |
| |
| async function assertLegacyArtifactsAbsent(backend: RuntimeHostServiceBackend): Promise<void> { |
| const status = await backend.status(); |
| if (status.installed || status.enabled || status.active) { |
| throw new RuntimeHostSetupError( |
| 'lifecycle_owner_exists', |
| 'The canonical deployment is active but its legacy lifecycle artifact can still start', |
| ); |
| } |
| } |
| |
| function sameExactPackage( |
| config: RuntimeHostManagedDeploymentConfig, |
| candidate: { readonly version: string; readonly integrity: string }, |
| ): boolean { |
| return ( |
| config.launch.package.version === candidate.version && |
| config.launch.package.integrity === candidate.integrity |
| ); |
| } |
| |
| async function pairAndVerifyRuntimeHostSetup( |
| options: RuntimeHostSetupCliOptions, |
| target: { |
| readonly serviceId: string; |
| readonly deploymentId: string; |
| readonly operator: RuntimeHostNodeOperatorCommand; |
| readonly rootPath: string; |
| readonly endpoint: string; |
| readonly directPeer?: { |
| readonly peerId: string; |
| readonly routeHints: readonly string[]; |
| readonly coordinationRelays: readonly string[]; |
| }; |
| }, |
| deps: RuntimeHostSetupDeps, |
| emit: SetupEmitter, |
| ): Promise<void> { |
| emit({ kind: 'progress', phase: 'pairing_client' }); |
| let paired: Awaited<ReturnType<typeof prepareRuntimeHostAccessCredential>>; |
| try { |
| const pairCredential = options.deferPairingCommit |
| ? deps.prepareCredential |
| : deps.replaceCredential; |
| const credentialInput = { |
| rootPath: target.rootPath, |
| principalKind: 'remote_owner' as const, |
| principalId: options.principalId, |
| operationGrants: [], |
| canPublishClientCapabilities: false, |
| canUseHostPaths: false, |
| preset: options.preset, |
| ...(options.bindPairingToClient ? { bindClientInstance: true } : {}), |
| }; |
| const deadline = Date.now() + RUNTIME_HOST_READY_TIMEOUT_MS; |
| while (true) { |
| try { |
| paired = await pairCredential(credentialInput); |
| break; |
| } catch (error) { |
| if (!isTransientPairingAvailabilityError(error) || Date.now() >= deadline) { |
| throw error; |
| } |
| await new Promise<void>((resolveWait) => |
| setTimeout(resolveWait, Math.min(PAIRING_AVAILABILITY_POLL_MS, deadline - Date.now())), |
| ); |
| } |
| } |
| } catch (error) { |
| const reason = |
| error instanceof RuntimeHostAccessUnavailableError |
| ? error.message |
| : generalizedErrorMessage(error, 'Runtime Host access service is unavailable'); |
| throw new RuntimeHostSetupError( |
| 'pairing_failed', |
| `Runtime Host could not pair the requested Client identity: ${reason}`, |
| { cause: error }, |
| ); |
| } |
| |
| emit({ kind: 'progress', phase: 'verifying_connection' }); |
| try { |
| await deps.verifyCredential({ |
| endpoint: target.endpoint, |
| rootId: paired.rootId, |
| credential: paired.credential, |
| }); |
| emit({ |
| kind: 'complete', |
| version: options.version, |
| serviceId: target.serviceId, |
| deploymentId: target.deploymentId, |
| operator: target.operator, |
| rootPath: target.rootPath, |
| rootId: paired.rootId, |
| endpoint: target.endpoint, |
| credentialId: paired.credentialId, |
| credential: paired.credential, |
| ...(target.directPeer |
| ? { |
| directPeer: { |
| peerId: target.directPeer.peerId, |
| routeHints: [...target.directPeer.routeHints], |
| coordinationRelays: [...target.directPeer.coordinationRelays], |
| }, |
| } |
| : {}), |
| }); |
| } catch (error) { |
| if (options.deferPairingCommit) { |
| try { |
| await deps.revokeCredential({ |
| rootPath: target.rootPath, |
| credentialId: paired.credentialId, |
| }); |
| } catch (rollbackError) { |
| throw new AggregateError( |
| [error, rollbackError], |
| 'Runtime Host pairing failed and its candidate credential could not be revoked', |
| ); |
| } |
| } |
| throw error; |
| } |
| } |
| |
| function isTransientPairingAvailabilityError(error: unknown): boolean { |
| return ( |
| error instanceof RuntimeHostAccessUnavailableError || |
| (error instanceof RuntimeHostOperationError && |
| (error.code === 'host_not_ready' || error.code === 'host_draining')) |
| ); |
| } |
| |
| async function assertCompatibleExistingVersion( |
| status: RuntimeHostManagedServiceResult, |
| version: string, |
| ): Promise<void> { |
| if (!status.service.config) { |
| if (!status.service.installed) return; |
| throw new RuntimeHostSetupError( |
| 'existing_installation_unknown', |
| 'The installed Runtime Host configuration is unavailable; repair it before setup', |
| ); |
| } |
| const existingVersion = status.service.installedVersion; |
| if (!existingVersion) { |
| throw new RuntimeHostSetupError( |
| 'existing_installation_unknown', |
| 'The installed Runtime Host version could not be identified; repair it before setup', |
| ); |
| } |
| if ( |
| existingVersion !== version && |
| !( |
| isRuntimeHostDevelopmentPackageVersion(existingVersion) && |
| isRuntimeHostDevelopmentPackageVersion(version) |
| ) |
| ) { |
| throw new RuntimeHostSetupError( |
| 'version_change_requires_update', |
| `Runtime Host ${String(existingVersion)} is already installed; changing to ${version} requires the update workflow`, |
| ); |
| } |
| } |
| |
| async function verifyRuntimeHostSetupCredential(input: { |
| readonly endpoint: string; |
| readonly rootId: string; |
| readonly credential: string; |
| }): Promise<void> { |
| const result = await connectRemoteRuntimeHost({ |
| url: input.endpoint, |
| credential: input.credential, |
| expectedRootId: input.rootId, |
| compositionId: INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID, |
| protocol: { |
| min: RUNTIME_HOST_PROTOCOL_VERSION, |
| max: RUNTIME_HOST_PROTOCOL_VERSION, |
| }, |
| }); |
| if (result.kind !== 'connected') { |
| throw new RuntimeHostSetupError( |
| 'verification_failed', |
| `The paired Runtime Host connection could not be verified (${result.kind})`, |
| ); |
| } |
| try { |
| const status = await result.connection.status(); |
| if (status.state !== 'ready') { |
| throw new RuntimeHostSetupError( |
| 'verification_failed', |
| `The paired Runtime Host is ${status.state}`, |
| ); |
| } |
| } finally { |
| await result.connection.close(); |
| } |
| } |
| |
| type SetupEmitter = ( |
| frame: |
| | Omit<Extract<RuntimeHostSetupFrame, { kind: 'progress' }>, 'schemaVersion' | 'sequence'> |
| | Omit<Extract<RuntimeHostSetupFrame, { kind: 'complete' }>, 'schemaVersion' | 'sequence'> |
| | Omit< |
| Extract<RuntimeHostSetupFrame, { kind: 'existing_environment' }>, |
| 'schemaVersion' | 'sequence' |
| > |
| | Omit<Extract<RuntimeHostSetupFrame, { kind: 'error' }>, 'schemaVersion' | 'sequence'>, |
| ) => void; |
| |
| function createEmitter(json: boolean, deps: RuntimeHostSetupDeps): SetupEmitter { |
| let sequence = 0; |
| return (input) => { |
| const frame = { |
| schemaVersion: 1, |
| sequence: sequence++, |
| ...input, |
| } as RuntimeHostSetupFrame; |
| if (json) { |
| deps.writeOutput(encodeRuntimeHostSetupFrame(frame)); |
| return; |
| } |
| if (frame.kind === 'progress') { |
| deps.writeOutput(`${humanPhase(frame.phase)}\n`); |
| } else if (frame.kind === 'complete' || frame.kind === 'existing_environment') { |
| deps.writeOutput(`${JSON.stringify(frame, null, 2)}\n`); |
| } else { |
| deps.writeError(`${frame.error.message}\n`); |
| } |
| }; |
| } |
| |
| function setupFailure(error: unknown): { code: string; message: string } { |
| let code = 'internal_setup_failure'; |
| let message = 'Runtime Host setup failed'; |
| if ( |
| error instanceof RuntimeHostSetupError || |
| error instanceof RuntimeHostServiceManagerError || |
| error instanceof RuntimeHostManagedDeploymentError || |
| error instanceof RuntimeHostDeploymentAuthorityError || |
| error instanceof RuntimeHostUpdateDiscoveryError || |
| error instanceof RuntimeHostUpdatePackageError || |
| error instanceof RuntimeHostLifecycleTransactionError |
| ) { |
| code = error.code; |
| message = error.message; |
| } |
| return { |
| code: truncateUtf8(code, RUNTIME_HOST_SETUP_ERROR_CODE_MAX_BYTES) || 'internal_setup_failure', |
| message: |
| truncateUtf8(message, RUNTIME_HOST_SETUP_ERROR_MESSAGE_MAX_BYTES) || |
| 'Runtime Host setup failed', |
| }; |
| } |
| |
| function websocketUrl(input: { |
| readonly host: string; |
| readonly port: number; |
| readonly path: string; |
| }) { |
| return `ws://${input.host}:${input.port}${input.path}`; |
| } |
| |
| function humanPhase(phase: RuntimeHostSetupPhase): string { |
| switch (phase) { |
| case 'checking_environment': |
| return 'Checking the remote environment...'; |
| case 'installing_package': |
| return 'Installing the managed Maka package...'; |
| case 'installing_service': |
| return 'Installing the Runtime Host deployment...'; |
| case 'pairing_client': |
| return 'Pairing the Client...'; |
| case 'verifying_connection': |
| return 'Verifying the Runtime Host connection...'; |
| } |
| } |
