StudioLifecycleManager.ts

import type { StudioManager } from './studio'
import { ProtocolManager } from './protocol'
import { getAndInitializeStudioManager } from './api/studio/get_and_initialize_studio_manager'
import Debug from 'debug'
import type { CloudDataSource } from '@packages/data-context/src/sources'
import type { Cfg } from '../project-base'
import _ from 'lodash'
import type { DataContext } from '@packages/data-context'
import api from './api'
import { reportStudioError } from './api/studio/report_studio_error'
import { CloudRequest } from './api/cloud_request'
import { isRetryableError } from './network/is_retryable_error'
import { asyncRetry } from '../util/async_retry'
import { postStudioSession } from './api/studio/post_studio_session'
import type { StudioStatus } from '@packages/types'

const debug = Debug('cypress:server:studio-lifecycle-manager')
const routes = require('./routes')

export class StudioLifecycleManager {
  private studioManagerPromise?: Promise<StudioManager | null>
  private studioManager?: StudioManager
  private listeners: ((studioManager: StudioManager) => void)[] = []
  private ctx?: DataContext
  private lastStatus?: StudioStatus

  public get cloudStudioRequested () {
    return !!(process.env.CYPRESS_ENABLE_CLOUD_STUDIO || process.env.CYPRESS_LOCAL_STUDIO_PATH)
  }

  /**
   * Initialize the studio manager and possibly set up protocol.
   * Also registers this instance in the data context.
   * @param projectId The project ID
   * @param cloudDataSource The cloud data source
   * @param cfg The project configuration
   * @param debugData Debug data for the configuration
   * @param ctx Data context to register this instance with
   */
  initializeStudioManager ({
    projectId,
    cloudDataSource,
    cfg,
    debugData,
    ctx,
  }: {
    projectId?: string
    cloudDataSource: CloudDataSource
    cfg: Cfg
    debugData: any
    ctx: DataContext
  }): void {
    // Register this instance in the data context
    ctx.update((data) => {
      data.studioLifecycleManager = this
    })

    this.ctx = ctx

    this.updateStatus('INITIALIZING')

    const studioManagerPromise = this.createStudioManager({
      projectId,
      cloudDataSource,
      cfg,
      debugData,
    }).catch(async (error) => {
      debug('Error during studio manager setup: %o', error)

      const cloudEnv = (process.env.CYPRESS_CONFIG_ENV || process.env.CYPRESS_INTERNAL_ENV || 'production') as 'development' | 'staging' | 'production'
      const cloudUrl = ctx.cloud.getCloudUrl(cloudEnv)
      const cloudHeaders = await ctx.cloud.additionalHeaders()

      reportStudioError({
        cloudApi: {
          cloudUrl,
          cloudHeaders,
          CloudRequest,
          isRetryableError,
          asyncRetry,
        },
        studioHash: projectId,
        projectSlug: cfg.projectId,
        error,
        studioMethod: 'initializeStudioManager',
        studioMethodArgs: [],
      })

      this.updateStatus('IN_ERROR')

      // Clean up any registered listeners
      this.listeners = []

      return null
    })

    this.studioManagerPromise = studioManagerPromise
  }

  isStudioReady (): boolean {
    return !!this.studioManager
  }

  async getStudio () {
    if (!this.studioManagerPromise) {
      throw new Error('Studio manager has not been initialized')
    }

    const studioManager = await this.studioManagerPromise

    if (studioManager) {
      this.updateStatus(studioManager.status)
    }

    return studioManager
  }

  private async createStudioManager ({
    projectId,
    cloudDataSource,
    cfg,
    debugData,
  }: {
    projectId?: string
    cloudDataSource: CloudDataSource
    cfg: Cfg
    debugData: any
  }): Promise<StudioManager> {
    const studioSession = await postStudioSession({
      projectId,
    })

    const studioManager = await getAndInitializeStudioManager({
      studioUrl: studioSession.studioUrl,
      projectId,
      cloudDataSource,
      shouldEnableStudio: this.cloudStudioRequested,
      lifecycleManager: this,
    })

    if (studioManager.status === 'ENABLED') {
      debug('Cloud studio is enabled - setting up protocol')
      const protocolManager = new ProtocolManager()
      const script = await api.getCaptureProtocolScript(studioSession.protocolUrl)

      await protocolManager.prepareProtocol(script, {
        runId: 'studio',
        projectId: cfg.projectId,
        testingType: cfg.testingType,
        cloudApi: {
          url: routes.apiUrl,
          retryWithBackoff: api.retryWithBackoff,
          requestPromise: api.rp,
        },
        projectConfig: _.pick(cfg, ['devServerPublicPathRoute', 'port', 'proxyUrl', 'namespace']),
        mountVersion: api.runnerCapabilities.protocolMountVersion,
        debugData,
        mode: 'studio',
      })

      studioManager.protocolManager = protocolManager
    } else {
      debug('Cloud studio is not enabled - skipping protocol setup')
    }

    debug('Studio is ready')
    this.studioManager = studioManager
    this.callRegisteredListeners()
    this.updateStatus(studioManager.status)

    return studioManager
  }

  private callRegisteredListeners () {
    if (!this.studioManager) {
      throw new Error('Studio manager has not been initialized')
    }

    const studioManager = this.studioManager

    debug('Calling all studio ready listeners')
    this.listeners.forEach((listener) => {
      listener(studioManager)
    })

    this.listeners = []
  }

  /**
   * Register a listener that will be called when the studio is ready
   * @param listener Function to call when studio is ready
   */
  registerStudioReadyListener (listener: (studioManager: StudioManager) => void): void {
    // if there is already a studio manager, call the listener immediately
    if (this.studioManager) {
      debug('Studio ready - calling listener immediately')
      listener(this.studioManager)
    } else {
      debug('Studio not ready - registering studio ready listener')
      this.listeners.push(listener)
    }
  }

  public updateStatus (status: StudioStatus) {
    if (status === this.lastStatus) {
      debug('Studio status unchanged: %s', status)

      return
    }

    debug('Studio status changed: %s → %s', this.lastStatus, status)
    this.lastStatus = status

    if (this.ctx) {
      this.ctx?.emitter.studioStatusChange()
    } else {
      debug('No ctx available, cannot emit studioStatusChange')
    }
  }
}