<?php

declare(strict_types=1);

namespace Drupal\flowdrop_runtime\Service\RealTime;

/**
 * Interface for the real-time execution update manager.
 *
 * @internal This interface is not part of the public API and may change without notice.
 */
interface RealTimeManagerInterface {

  /**
   * Start real-time monitoring for an execution.
   *
   * @param string $executionId
   *   The execution ID.
   * @param array<string, mixed> $workflow
   *   The workflow definition array.
   */
  public function startMonitoring(string $executionId, array $workflow): void;

  /**
   * Update node status in real-time.
   *
   * @param string $executionId
   *   The execution ID.
   * @param string $nodeId
   *   The node ID.
   * @param string $status
   *   The new status.
   * @param array<string, mixed> $data
   *   Additional status data.
   */
  public function updateNodeStatus(
    string $executionId,
    string $nodeId,
    string $status,
    array $data = [],
  ): void;

  /**
   * Update overall execution status.
   *
   * @param string $executionId
   *   The execution ID.
   * @param string $status
   *   The new status.
   * @param array<string, mixed> $data
   *   Additional status data.
   */
  public function updateExecutionStatus(
    string $executionId,
    string $status,
    array $data = [],
  ): void;

  /**
   * Get current execution status for polling.
   *
   * @param string $executionId
   *   The execution ID.
   *
   * @return array<string, mixed>
   *   The execution status data.
   */
  public function getExecutionStatus(string $executionId): array;

  /**
   * Get detailed node statuses for an execution.
   *
   * @param string $executionId
   *   The execution ID.
   *
   * @return array<string, mixed>
   *   The node statuses data.
   */
  public function getNodeStatuses(string $executionId): array;

}
