<?php
// SPDX-License-Identifier: GPL-3.0-or-later
declare(strict_types=1);

namespace Aiwend\Db;

use Aiwend\Support\Clock;
use Aiwend\Support\OptionStore;

/**
 * The request-time database upgrade and what happens when it fails. A site that is current costs nothing. Otherwise the schema
 * runner is tried (it can be re-run, and serialises concurrent attempts); a failure is never recorded as success, leaves a trace the
 * administrator can see (a class name and a time: no SQL, parameters or data) and is retried at most once a minute, so a broken
 * upgrade cannot turn into an error loop or a pile of requests waiting on the migration lock.
 */
final class UpgradeGuard
{
    public const CURRENT = 'current';
    public const DONE = 'done';
    public const WAITING = 'waiting';
    public const FAILED = 'failed';

    public const VERSION_OPTION = 'aiwend_schema_version';
    public const FAILURE_OPTION = 'aiwend_schema_failure';
    public const RETRY_SECONDS = 60;

    public function __construct(private Connection $db, private OptionStore $options, private Clock $clock, private int $lockTimeout = 5)
    {
    }

    /** @return self::CURRENT|self::DONE|self::WAITING|self::FAILED */
    /**
     * @param bool $force an administrator asked to try again now: the one-minute wait is skipped (the upgrade steps are safe to repeat and
     *        run under the migration lock, so a second request at the same moment simply waits for the first)
     */
    public function run(bool $force = false): string
    {
        if ((int) $this->options->get(self::VERSION_OPTION, 0) >= Schema::VERSION) {
            return self::CURRENT;
        }
        $failure = $this->failure();
        if (!$force && $failure !== null && $this->clock->now() < $failure['at'] + self::RETRY_SECONDS) {
            return self::WAITING;
        }
        try {
            $version = (new Schema($this->db, $this->lockTimeout))->migrate();
        } catch (\Throwable $e) {
            $this->options->set(self::FAILURE_OPTION, ['at' => $this->clock->now(), 'error' => get_class($e)]);
            return self::FAILED;
        }
        $this->options->set(self::VERSION_OPTION, $version);
        if ($failure !== null) {
            $this->options->set(self::FAILURE_OPTION, []);
        }
        return self::DONE;
    }

    /** @return array{at:int, error:string}|null the last failed attempt, until an attempt succeeds */
    public function failure(): ?array
    {
        $f = $this->options->get(self::FAILURE_OPTION, []);
        return is_array($f) && isset($f['at'], $f['error']) ? ['at' => (int) $f['at'], 'error' => (string) $f['error']] : null;
    }
}