<?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;

  /**
   * Broadcast a session-keyed event.
   *
   * Session events ride the same broadcast channel as node and execution
   * events (RealTimeBroadcastEvent), with type 'session' and the session
   * id as the keying id — one subscription point carries node status,
   * pipeline status, and session turn lifecycle, all keyed.
   *
   * @param string $sessionId
   *   The session entity id the event is keyed by.
   * @param string $event
   *   The event name (e.g. 'turn_started', 'turn_completed').
   * @param array<string, mixed> $data
   *   The event payload (correlation ids, status, ...).
   */
  public function broadcastSessionEvent(
    string $sessionId,
    string $event,
    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;

}
