<?php

declare(strict_types=1);

namespace Drupal\flowdrop_runtime\Service\Storage;

use Drupal\flowdrop_pipeline\Entity\FlowDropPipelineRuntimeInterface;

/**
 * Interface for pipeline storage operations.
 *
 * This interface abstracts pipeline persistence, allowing different storage
 * backends (Drupal entities, in-memory, Redis, etc.) to be used
 * interchangeably.
 *
 * Implementations:
 * - DrupalPipelineStorage: Persistent storage using Drupal entities
 * - InMemoryPipelineStorage: Fast ephemeral storage for synchronous execution
 * - (Future) RedisPipelineStorage: Fast persistent storage
 *
 * @internal
 *   This class is not part of the public API and may change without notice.
 */
interface PipelineStorageInterface {

  /**
   * Creates a new pipeline.
   *
   * @param array $data
   *   The pipeline data with the following keys:
   *   - label: (string) Human-readable label
   *   - bundle: (string) Bundle/type (default: 'default')
   *   - workflow_id: (string|array) Workflow ID or ['target_id' => id]
   *   - input_data: (array|string) Initial input data
   *   - status: (string) Initial status (default: 'pending')
   *   - max_concurrent_jobs: (int) Max concurrent jobs
   *   - job_priority_strategy: (string) Priority strategy
   *   - retry_strategy: (string) Retry strategy
   *   - execution_context: (array) Optional execution context.
   *
   * @return \Drupal\flowdrop_pipeline\Entity\FlowDropPipelineRuntimeInterface
   *   The created pipeline (not yet saved).
   */
  public function create(array $data): FlowDropPipelineRuntimeInterface;

  /**
   * Loads a pipeline by ID.
   *
   * @param string|int $id
   *   The pipeline ID.
   *
   * @return \Drupal\flowdrop_pipeline\Entity\FlowDropPipelineRuntimeInterface|null
   *   The pipeline entity, or NULL if not found.
   */
  public function load(string|int $id): ?FlowDropPipelineRuntimeInterface;

  /**
   * Saves a pipeline.
   *
   * @param \Drupal\flowdrop_pipeline\Entity\FlowDropPipelineRuntimeInterface $pipeline
   *   The pipeline to save.
   */
  public function save(FlowDropPipelineRuntimeInterface $pipeline): void;

  /**
   * Deletes a pipeline.
   *
   * @param \Drupal\flowdrop_pipeline\Entity\FlowDropPipelineRuntimeInterface $pipeline
   *   The pipeline to delete.
   */
  public function delete(FlowDropPipelineRuntimeInterface $pipeline): void;

  /**
   * Resets the storage cache.
   *
   * For entity-based storage, this clears the static entity cache.
   * For in-memory storage, this may be a no-op.
   *
   * @param array|null $ids
   *   Optional array of pipeline IDs to reset. If NULL, reset all.
   */
  public function resetCache(?array $ids = NULL): void;

}
