<?php

declare(strict_types=1);

namespace App\Framework\Mcp\Core\Interfaces;

/**
 * Interface für Caching in MCP Tools
 *
 * Bietet einheitliches Caching für alle MCP Tools zur Performance-Optimierung
 */
interface CacheProvider
{
    /**
     * Holt einen Wert aus dem Cache
     *
     * @param string $key Der Cache-Key
     * @return mixed Der gecachte Wert oder null wenn nicht gefunden
     */
    public function get(string $key): mixed;

    /**
     * Speichert einen Wert im Cache
     *
     * @param string $key Der Cache-Key
     * @param mixed $value Der zu speichernde Wert
     * @param int $ttl Time-to-live in Sekunden (default: 3600 = 1 Stunde)
     * @return void
     */
    public function set(string $key, mixed $value, int $ttl = 3600): void;

    /**
     * Löscht einen Wert aus dem Cache
     *
     * @param string $key Der Cache-Key
     * @return bool True wenn erfolgreich gelöscht
     */
    public function delete(string $key): bool;

    /**
     * Prüft ob ein Key im Cache existiert
     *
     * @param string $key Der Cache-Key
     * @return bool True wenn Key existiert
     */
    public function has(string $key): bool;

    /**
     * Leert den gesamten Cache
     *
     * @return bool True wenn erfolgreich geleert
     */
    public function clear(): bool;

    /**
     * Holt multiple Werte auf einmal
     *
     * @param array $keys Liste der Cache-Keys
     * @return array Assoziatives Array mit Key => Value Paaren
     */
    public function getMultiple(array $keys): array;

    /**
     * Speichert multiple Werte auf einmal
     *
     * @param array $values Assoziatives Array mit Key => Value Paaren
     * @param int $ttl Time-to-live in Sekunden
     * @return bool True wenn alle erfolgreich gespeichert
     */
    public function setMultiple(array $values, int $ttl = 3600): bool;

    /**
     * Remember Pattern - holt aus Cache oder führt Callback aus
     *
     * @param string $key Der Cache-Key
     * @param callable $callback Callback der ausgeführt wird wenn nicht im Cache
     * @param int $ttl Time-to-live in Sekunden
     * @return mixed Der Wert aus Cache oder Callback-Result
     */
    public function remember(string $key, callable $callback, int $ttl = 3600): mixed;

    /**
     * Generiert einen Cache-Key für MCP Tools
     *
     * @param string $toolName Name des Tools
     * @param string $method Name der Methode
     * @param array $parameters Parameter für eindeutigen Key
     * @return string Generierter Cache-Key
     */
    public function generateKey(string $toolName, string $method, array $parameters = []): string;
}
