<?php

declare(strict_types=1);

namespace Drupal\flowdrop_runtime\Service\Orchestrator;

use Drupal\flowdrop_orchestration\DTO\Orchestrator\OrchestrationResponse;
use Drupal\flowdrop_pipeline\Entity\FlowDropPipelineRuntimeInterface;

/**
 * Interface for orchestrators that can execute pipeline entities.
 *
 * This interface defines the contract for resuming or executing an existing
 * pipeline entity. It is used by event subscribers that need to resume
 * pipeline execution after an interrupt is resolved.
 *
 * @internal
 *   This class is not part of the public API and may change without notice.
 */
interface PipelineExecutorInterface {

  /**
   * Executes (or resumes) a pipeline entity.
   *
   * @param \Drupal\flowdrop_pipeline\Entity\FlowDropPipelineRuntimeInterface $pipeline
   *   The pipeline to execute.
   * @param int|null $maxIterations
   *   Maximum number of iterations before pausing (default: 100).
   *   NULL means no limit.
   * @param float|null $maxExecutionTime
   *   Maximum execution time in seconds before pausing
   *   (default: NULL = no limit).
   * @param string|null $executionId
   *   Optional execution ID to reuse (e.g. when resuming after an interrupt).
   *   If NULL, a new unique ID is generated.
   *
   * @return \Drupal\flowdrop_orchestration\DTO\Orchestrator\OrchestrationResponse
   *   The orchestration response.
   */
  public function executePipeline(
    FlowDropPipelineRuntimeInterface $pipeline,
    ?int $maxIterations = 100,
    ?float $maxExecutionTime = NULL,
    ?string $executionId = NULL,
  ): OrchestrationResponse;

}
