ArrayStore.php

<?php
/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
/**
 * Italix Crypto - ArrayStore
 *
 * @package Italix\Crypto
 */

declare(strict_types=1);

namespace Italix\Crypto;

use Italix\Contracts\KeyValueStore;

/**
 * In-memory storage, for tests and for single-process scripts.
 *
 * Dies with the request, which makes it useless as a limiter in production —
 * every request would start from zero. It is here because a limiter whose only
 * implementation needs a database is a limiter that cannot be tested quickly,
 * and because the clock is injectable, so an expiry test does not have to sleep.
 */
final class ArrayStore implements KeyValueStore
{
    /** @var array<string, array{value: mixed, expires_t: int|null}> */
    private array $rows = [];

    /** @var callable():int */
    private $clock;

    /**
     * @param callable():int|null $clock injectable so tests can move time without sleeping
     */
    public function __construct(?callable $clock = null)
    {
        $this->clock = $clock ?? static function (): int {
            return time();
        };
    }

    public function get(string $key)
    {
        $row = $this->live($key);

        return $row === null ? null : $row['value'];
    }

    public function put(string $key, $value, int $ttl_n): void
    {
        $this->rows[$key] = [
            'value'     => $value,
            'expires_t' => $ttl_n > 0 ? ($this->clock)() + $ttl_n : ($this->clock)(),
        ];
    }

    public function forget(string $key): void
    {
        unset($this->rows[$key]);
    }

    public function increment(string $key, int $ttl_n): int
    {
        $row = $this->live($key);

        if ($row === null) {
            $this->put($key, 1, $ttl_n);

            return 1;
        }

        // The expiry is left alone: the window must not slide forward on every hit.
        $next = ((int) $row['value']) + 1;
        $this->rows[$key]['value'] = $next;

        return $next;
    }

    public function expires_t(string $key): ?int
    {
        $row = $this->live($key);

        return $row === null ? null : $row['expires_t'];
    }

    /**
     * Number of live keys — diagnostics only.
     */
    public function count(): int
    {
        $n = 0;

        foreach (array_keys($this->rows) as $key) {
            if ($this->live((string) $key) !== null) {
                $n++;
            }
        }

        return $n;
    }

    /**
     * @return array{value: mixed, expires_t: int|null}|null
     */
    private function live(string $key): ?array
    {
        if (!isset($this->rows[$key])) {
            return null;
        }

        $row = $this->rows[$key];

        if ($row['expires_t'] !== null && ($this->clock)() >= $row['expires_t']) {
            unset($this->rows[$key]);

            return null;
        }

        return $row;
    }
}