<?php

namespace App\Support;

use Closure;
use Illuminate\Support\Facades\Cache;

/**
 * Gemeinsame Cache-Konvention der öffentlichen Web-Seitendaten (HomePageData,
 * CategoryPageData, TickerData, NewsroomDetail/NewsroomsPageData,
 * SuchePageData, CategoryNavigation). Bündelt TTL und `web.`-Präfix an einer
 * Stelle, statt mehrere Konstanten/Magic-Numbers zu pflegen.
 *
 * Stale-while-revalidate (Cache::flexible): Innerhalb der Frische-TTL kommt
 * der Wert direkt aus dem Cache. Danach wird bis zur Stale-Grenze sofort der
 * alte Stand serviert und der Neuaufbau läuft NACH der Response (deferred) —
 * Besucher zahlen den teuren Seitenaufbau (~25–30 Archiv-Queries) nicht mehr
 * im Request, solange die Seite mindestens einmal pro Stale-Fenster besucht
 * wird. Erst nach Ablauf der Stale-Grenze baut der Request wieder synchron.
 */
class WebPageCache
{
    /**
     * Frische-Fenster der Web-Seitendaten in Sekunden: solange gilt der
     * Cache-Eintrag als aktuell und wird ohne Neuaufbau ausgeliefert.
     */
    public const TtlSeconds = 300;

    /**
     * Stale-Grenze in Sekunden (ab Cache-Write): bis hierhin wird ein
     * abgelaufener Eintrag noch serviert, während der Neuaufbau im
     * Hintergrund läuft.
     */
    public const StaleSeconds = 3600;

    /**
     * Cache-Key der Generations-Nummer (siehe generation()).
     *
     * Bewusst OHNE `web.`-Präfix: Der Zähler ist der eine Eintrag, der eine
     * Verwerfung des `web.`-Namensraums überleben muss. Läge er darin, würde
     * ihn ein pauschales Aufräumen dieses Präfixes mitnehmen — und ein Flush
     * wäre danach stillschweigend wirkungslos.
     */
    private const GenerationKey = 'page-cache.generation';

    /**
     * Generations-Nummer innerhalb des Requests, damit key() nicht bei jedem
     * Aufruf erneut den Cache-Store befragt.
     *
     * ACHTUNG Lebensdauer: Der Wert gilt für einen Request. In langlebigen
     * Prozessen (queue:work, künftig Octane) muss er zwischen zwei Vorgängen
     * verworfen werden — sonst arbeitet der Worker beliebig lange mit einer
     * veralteten Generation und würde etwa in BoostService::forgetPlacementCaches()
     * die Keys einer alten Generation löschen, während der aktuelle Eintrag
     * stehen bliebe. Dafür sorgt resetMemo(), registriert im AppServiceProvider
     * auf `Queue::looping()`.
     */
    private static ?int $generation = null;

    /**
     * Baut einen `web.`-Cache-Key aus Segmenten (leere Segmente entfallen).
     *
     * Der Key enthält eine Generations-Nummer: Der Store kennt keine Tags, und
     * die Keys der Listenseiten sind über Portal, Sprache, Seite und Filter
     * verstreut. Um eine Entfernung (410/Depublikation) sofort wirksam zu
     * machen, wird deshalb die Generation erhöht — dadurch verfallen alle
     * `web.`-Seiten-Caches auf einen Schlag. Das ist bewusst grob, aber
     * Entfernungen sind selten und dürfen nicht bis zu einer Stunde nachhängen.
     *
     * @param  array<int, string|int>  $segments
     */
    public static function key(string $group, array $segments = []): string
    {
        $parts = array_filter(
            array_map(static fn (string|int $segment): string => (string) $segment, $segments),
            static fn (string $segment): bool => $segment !== '',
        );

        return implode('.', array_merge(['web', 'g'.self::generation(), $group], $parts));
    }

    /**
     * Aktuelle Generation der Seiten-Caches.
     */
    public static function generation(): int
    {
        return self::$generation ??= (int) Cache::get(self::GenerationKey, 0);
    }

    /**
     * Verwirft die prozessinterne Merkung der Generation, sodass der nächste
     * Zugriff wieder den Store fragt. Für langlebige Prozesse (Queue-Worker)
     * und für Tests, die den Cache-Store zurücksetzen.
     */
    public static function resetMemo(): void
    {
        self::$generation = null;
    }

    /**
     * Verwirft sämtliche `web.`-Seiten-Caches, indem die Generation erhöht
     * wird. Die alten Einträge laufen über ihre TTL aus und werden nie wieder
     * gelesen.
     */
    public static function flush(): void
    {
        $current = self::generation();
        $next = (int) Cache::increment(self::GenerationKey);

        // Der Zähler MUSS echt weiterlaufen. Wurde er im Store verworfen
        // (Eviction, `cache:clear`), liefert increment() wieder 1 und die alte
        // Generation bliebe gültig — dann würde ein Flush stillschweigend
        // wirkungslos und entfernte Inhalte blieben in den Listen stehen.
        if ($next <= $current) {
            $next = $current + 1;
            Cache::forever(self::GenerationKey, $next);
        }

        self::$generation = $next;
    }

    /**
     * @template TValue
     *
     * @param  Closure(): TValue  $callback
     * @return TValue
     */
    public static function remember(string $key, Closure $callback): mixed
    {
        return Cache::flexible($key, [self::TtlSeconds, self::StaleSeconds], $callback);
    }
}