<?php

declare(strict_types=1);

namespace Drupal\flowdrop_memory\Plugin\MemoryBackend;

/**
 * Interface for FlowDrop memory backend plugins.
 *
 * A memory backend provides scoped key-value storage accessible during
 * and across workflow executions. Scopes and scope IDs are arbitrary strings
 * — the backend does not validate or constrain them.
 *
 * Common scope conventions used by the context-aware node processors:
 * - "global"    — no sub-scope, shared across everything
 * - "workflow"  — keyed by workflow ID
 * - "pipeline"  — keyed by pipeline ID
 * - "execution" — keyed by execution ID
 * - "session"   — keyed by session ID (soft convention via metadata)
 *
 * @api
 */
interface MemoryBackendInterface {

  /**
   * Retrieves a value from memory.
   *
   * @param string $scope
   *   The memory scope (arbitrary string).
   * @param string $scope_id
   *   The scope identifier. Use empty string when not applicable.
   * @param string $key
   *   The memory key.
   * @param mixed $default
   *   Default value if the key does not exist or has expired.
   *
   * @return mixed
   *   The stored value or $default.
   */
  public function get(string $scope, string $scope_id, string $key, mixed $default = NULL): mixed;

  /**
   * Stores a value in memory.
   *
   * @param string $scope
   *   The memory scope.
   * @param string $scope_id
   *   The scope identifier.
   * @param string $key
   *   The memory key.
   * @param mixed $value
   *   The value to store. Must be JSON-serializable.
   * @param int|null $ttl
   *   Time-to-live in seconds. NULL means no expiry. Backends that do not
   *   support TTL silently ignore this parameter.
   */
  public function set(string $scope, string $scope_id, string $key, mixed $value, ?int $ttl = NULL): void;

  /**
   * Deletes a value from memory.
   *
   * @param string $scope
   *   The memory scope.
   * @param string $scope_id
   *   The scope identifier.
   * @param string $key
   *   The memory key to delete.
   */
  public function delete(string $scope, string $scope_id, string $key): void;

  /**
   * Checks whether a key exists in memory (and has not expired).
   *
   * @param string $scope
   *   The memory scope.
   * @param string $scope_id
   *   The scope identifier.
   * @param string $key
   *   The memory key.
   *
   * @return bool
   *   TRUE if the key exists and has not expired.
   */
  public function has(string $scope, string $scope_id, string $key): bool;

  /**
   * Lists all keys for a given scope.
   *
   * @param string $scope
   *   The memory scope.
   * @param string $scope_id
   *   The scope identifier.
   *
   * @return array<string>
   *   An array of key names within this scope.
   */
  public function keys(string $scope, string $scope_id): array;

  /**
   * Deletes all keys for a given scope.
   *
   * @param string $scope
   *   The memory scope.
   * @param string $scope_id
   *   The scope identifier.
   */
  public function clearScope(string $scope, string $scope_id): void;

}
