<?php

declare(strict_types=1);

namespace Drupal\flowdrop_workflow_executor\Service;

use Drupal\flowdrop_workflow_executor\DTO\WorkflowExecutionResult;
use Drupal\flowdrop_workflow_executor\Enum\WorkflowExecutionMode;
use Drupal\flowdrop_workflow_executor\Enum\WorkflowExecutionStatus;
use Drupal\flowdrop_workflow\FlowDropWorkflowInterface;

/**
 * Interface for the workflow execution service.
 *
 * This service provides methods to execute FlowDrop workflows programmatically,
 * supporting various execution modes including synchronous job-based execution,
 * async execution, and fire-and-forget patterns.
 *
 * @api
 */
interface WorkflowExecutionServiceInterface {

  /**
   * Executes a workflow with the specified mode.
   *
   * @param \Drupal\flowdrop_workflow\FlowDropWorkflowInterface $workflow
   *   The workflow to execute.
   * @param array<string, mixed> $inputData
   *   Input data to pass to the workflow.
   * @param \Drupal\flowdrop_workflow_executor\Enum\WorkflowExecutionMode $mode
   *   Execution mode.
   * @param int $timeout
   *   Timeout in seconds for 'job' mode (default: 300).
   * @param int $pollIntervalMs
   *   Polling interval in milliseconds (default: 2000).
   * @param array<string, mixed> $parentContext
   *   Parent workflow context for recursion tracking.
   *
   * @return \Drupal\flowdrop_workflow_executor\DTO\WorkflowExecutionResult
   *   The execution result.
   */
  public function execute(
    FlowDropWorkflowInterface $workflow,
    array $inputData = [],
    WorkflowExecutionMode $mode = WorkflowExecutionMode::Job,
    int $timeout = 300,
    int $pollIntervalMs = 2000,
    array $parentContext = [],
  ): WorkflowExecutionResult;

  /**
   * Gets results for an existing session.
   *
   * @param string $sessionId
   *   The session ID to get results for.
   * @param bool $waitForCompletion
   *   Whether to wait for completion.
   * @param int $timeout
   *   Timeout in seconds.
   * @param int $pollIntervalMs
   *   Polling interval in milliseconds.
   *
   * @return \Drupal\flowdrop_workflow_executor\DTO\WorkflowExecutionResult
   *   The execution result.
   */
  public function getResults(
    string $sessionId,
    bool $waitForCompletion = TRUE,
    int $timeout = 300,
    int $pollIntervalMs = 2000,
  ): WorkflowExecutionResult;

  /**
   * Checks if a workflow session has completed.
   *
   * @param string $sessionId
   *   The session ID.
   *
   * @return bool
   *   TRUE if completed, FALSE otherwise.
   */
  public function isComplete(string $sessionId): bool;

  /**
   * Gets the current status of a workflow session.
   *
   * @param string $sessionId
   *   The session ID.
   *
   * @return \Drupal\flowdrop_workflow_executor\Enum\WorkflowExecutionStatus
   *   The execution status.
   */
  public function getStatus(string $sessionId): WorkflowExecutionStatus;

}
