Make array cache request-local and add worker-array store

src/boost/docs/cache.md

@@ -2,6 +2,7 @@
 
 - [Introduction](#introduction)
 - [Configuration](#configuration)
+    - [Array Cache Stores](#array-cache-stores)
     - [Driver Prerequisites](#driver-prerequisites)
     - [Swoole Table Cache](#swoole-table-cache)
     - [Building Cache Stacks](#building-cache-stacks)
@@ -45,10 +46,37 @@ Thankfully, Hypervel provides an expressive, unified API for various cache backe
 <a name="configuration"></a>
 ## Configuration
 
-Your application's cache configuration file is located at `config/cache.php`. In this file, you may specify which cache store you would like to be used by default throughout your application. Hypervel supports Redis, relational databases, file storage, Swoole tables, session storage, cache stacks, failover stores, and the `array` and `null` stores that are convenient for automated tests.
+Your application's cache configuration file is located at `config/cache.php`. In this file, you may specify which cache store you would like to be used by default throughout your application. Hypervel supports Redis, relational databases, file storage, Swoole tables, session storage, cache stacks, failover stores, and the `array`, `worker-array`, and `null` stores that are convenient for automated tests and in-memory cache data.
 
 The cache configuration file also contains a variety of other options that you may review. By default, Hypervel is configured to use the `database` cache driver, which stores serialized cache values in your application's database.
 
+<a name="array-cache-stores"></a>
+### Array Cache Stores
+
+Hypervel provides two in-memory array cache stores.
+
+The `array` store is per-request. Values written to this store are visible only during the current HTTP request, queued job, scheduled task, or other unit of work. When that work finishes, the values are discarded.
+
+Hypervel implements this with coroutine context. Child coroutines start with a fresh context by default. If you intentionally copy parent context with APIs such as `parallel(..., copyContext: true)` or `Coroutine::fork()`, the child receives the parent array cache's current values as a starting point. Later cache writes remain isolated to that child coroutine. If serialization is disabled and a cached value is an object, normal PHP object-reference behavior still applies to that object.
+
+The `worker-array` store keeps values for the lifetime of the current worker process. Values are shared by all requests, jobs, tasks, and coroutines handled by that worker. They are not shared across worker processes, servers, or restarts.
+
+Use `array` for request-local test and scratch data. Use `worker-array` only when worker-local persistence is the intended behavior:
+
+```php
+'stores' => [
+    'array' => [
+        'driver' => 'array',
+        'serialize' => false,
+    ],
+
+    'worker-array' => [
+        'driver' => 'worker-array',
+        'serialize' => false,
+    ],
+],
+```
+
 <a name="driver-prerequisites"></a>
 ### Driver Prerequisites
 

src/cache/README.md

@@ -5,4 +5,8 @@ Cache for Hypervel
 
 ## Differences From Laravel
 
+The `array` cache store is request-local in Hypervel. Laravel can keep array-store values on the store object because the PHP process normally ends after each request; Hypervel workers are long-lived, so mutable array-store data lives in `CoroutineContext` and resets when the current unit of work finishes.
+
+Hypervel also provides a `worker-array` cache store for deliberate worker-lifetime in-memory cache data. It is shared by coroutines in the same worker process and is cleared when that worker exits.
+
 `Cache::memo()` stores its per-request memoized repository directly in coroutine context instead of Laravel's scoped container binding. Coroutine teardown provides the request reset boundary in Hypervel without dynamic container bindings.

src/cache/src/AbstractArrayStore.php

@@ -0,0 +1,298 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Cache;
+
+use Hypervel\Contracts\Cache\CanFlushLocks;
+use Hypervel\Contracts\Cache\LockProvider;
+use Hypervel\Support\Carbon;
+use Hypervel\Support\InteractsWithTime;
+use RuntimeException;
+
+abstract class AbstractArrayStore extends TaggableStore implements CanFlushLocks, LockProvider
+{
+    use InteractsWithTime;
+    use RetrievesMultipleKeys;
+
+    /**
+     * Indicates if values are serialized within the store.
+     */
+    protected bool $serializesValues;
+
+    /**
+     * The classes that should be allowed during unserialization.
+     */
+    protected array|bool|null $serializableClasses;
+
+    /**
+     * Create a new array-family store.
+     */
+    public function __construct(bool $serializesValues = false, array|bool|null $serializableClasses = null)
+    {
+        $this->serializesValues = $serializesValues;
+        $this->serializableClasses = $serializableClasses;
+    }
+
+    /**
+     * Get all of the cached values and their expiration times.
+     *
+     * @return array<string, array{value: mixed, expiresAt: float}>
+     */
+    public function all(bool $unserialize = true): array
+    {
+        $storage = $this->getCacheItems();
+
+        if ($unserialize === false || $this->serializesValues === false) {
+            return $storage;
+        }
+
+        foreach ($storage as $key => $data) {
+            $storage[$key] = [
+                'value' => $this->unserialize($data['value']),
+                'expiresAt' => $data['expiresAt'],
+            ];
+        }
+
+        return $storage;
+    }
+
+    /**
+     * Retrieve an item from the cache by key.
+     */
+    public function get(string $key): mixed
+    {
+        $item = $this->getCacheItem($key);
+
+        if ($item === null) {
+            return null;
+        }
+
+        $expiresAt = $item['expiresAt'];
+
+        if ($expiresAt !== 0.0 && (now()->getPreciseTimestamp(3) / 1000) >= $expiresAt) {
+            $this->forget($key);
+
+            return null;
+        }
+
+        return $this->serializesValues ? $this->unserialize($item['value']) : $item['value'];
+    }
+
+    /**
+     * Store an item in the cache for a given number of seconds.
+     */
+    public function put(string $key, mixed $value, int $seconds): bool
+    {
+        $this->putCacheItem($key, [
+            'value' => $this->serializesValues ? serialize($value) : $value,
+            'expiresAt' => $this->calculateExpiration($seconds),
+        ]);
+
+        return true;
+    }
+
+    /**
+     * Increment the value of an item in the cache.
+     */
+    public function increment(string $key, int $value = 1): int
+    {
+        // When backed by WorkerArrayStore, this read/modify/write path is shared across coroutines; keep it non-yielding.
+        if (! is_null($existing = $this->get($key))) {
+            $incremented = ((int) $existing) + $value;
+
+            /** @var array{value: mixed, expiresAt: float} $item */
+            $item = $this->getCacheItem($key);
+            $item['value'] = $this->serializesValues ? serialize($incremented) : $incremented;
+            $this->putCacheItem($key, $item);
+
+            return $incremented;
+        }
+
+        $this->forever($key, $value);
+
+        return $value;
+    }
+
+    /**
+     * Decrement the value of an item in the cache.
+     */
+    public function decrement(string $key, int $value = 1): int
+    {
+        return $this->increment($key, $value * -1);
+    }
+
+    /**
+     * Store an item in the cache indefinitely.
+     */
+    public function forever(string $key, mixed $value): bool
+    {
+        return $this->put($key, $value, 0);
+    }
+
+    /**
+     * Adjust the expiration time of a cached item.
+     */
+    public function touch(string $key, int $seconds): bool
+    {
+        $item = $this->getCacheItem($key);
+
+        if ($item === null) {
+            return false;
+        }
+
+        $item['expiresAt'] = $this->calculateExpiration($seconds);
+        $this->putCacheItem($key, $item);
+
+        return true;
+    }
+
+    /**
+     * Remove an item from the cache.
+     */
+    public function forget(string $key): bool
+    {
+        return $this->forgetCacheItem($key);
+    }
+
+    /**
+     * Remove all items from the cache.
+     */
+    public function flush(): bool
+    {
+        $this->clearCacheItems();
+
+        return true;
+    }
+
+    /**
+     * Remove all locks from the store.
+     *
+     * @throws RuntimeException
+     */
+    public function flushLocks(): bool
+    {
+        if (! $this->hasSeparateLockStore()) {
+            throw new RuntimeException('Flushing locks is only supported when the lock store is separate from the cache store.');
+        }
+
+        $this->clearLockRecords();
+
+        return true;
+    }
+
+    /**
+     * Get the cache key prefix.
+     */
+    public function getPrefix(): string
+    {
+        return '';
+    }
+
+    /**
+     * Get a lock instance.
+     */
+    public function lock(string $name, int $seconds = 0, ?string $owner = null): ArrayLock
+    {
+        return new ArrayLock($this, $name, $seconds, $owner);
+    }
+
+    /**
+     * Restore a lock instance using the owner identifier.
+     */
+    public function restoreLock(string $name, string $owner): ArrayLock
+    {
+        return $this->lock($name, 0, $owner);
+    }
+
+    /**
+     * Determine if the lock store is separate from the cache store.
+     */
+    public function hasSeparateLockStore(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the lock record for the given name.
+     *
+     * @return null|array{owner: ?string, expiresAt: ?Carbon}
+     */
+    abstract public function getLockRecord(string $name): ?array;
+
+    /**
+     * Store the lock record for the given name.
+     *
+     * @param array{owner: ?string, expiresAt: ?Carbon} $record
+     */
+    abstract public function putLockRecord(string $name, array $record): void;
+
+    /**
+     * Remove the lock record for the given name.
+     */
+    abstract public function forgetLockRecord(string $name): void;
+
+    /**
+     * Remove all lock records.
+     */
+    abstract public function clearLockRecords(): void;
+
+    /**
+     * Get the cached item for the given key.
+     *
+     * @return null|array{value: mixed, expiresAt: float}
+     */
+    abstract protected function getCacheItem(string $key): ?array;
+
+    /**
+     * Store the cached item for the given key.
+     *
+     * @param array{value: mixed, expiresAt: float} $item
+     */
+    abstract protected function putCacheItem(string $key, array $item): void;
+
+    /**
+     * Remove the cached item for the given key.
+     */
+    abstract protected function forgetCacheItem(string $key): bool;
+
+    /**
+     * Remove all cached items.
+     */
+    abstract protected function clearCacheItems(): void;
+
+    /**
+     * Get all cached items.
+     *
+     * @return array<string, array{value: mixed, expiresAt: float}>
+     */
+    abstract protected function getCacheItems(): array;
+
+    /**
+     * Get the expiration time of the key.
+     */
+    protected function calculateExpiration(int $seconds): float
+    {
+        return $this->toTimestamp($seconds);
+    }
+
+    /**
+     * Get the UNIX timestamp, with milliseconds, for the given number of seconds in the future.
+     */
+    protected function toTimestamp(int $seconds): float
+    {
+        return $seconds > 0 ? (now()->getPreciseTimestamp(3) / 1000) + $seconds : 0;
+    }
+
+    /**
+     * Unserialize the given value.
+     */
+    protected function unserialize(string $value): mixed
+    {
+        if ($this->serializableClasses !== null) {
+            return unserialize($value, ['allowed_classes' => $this->serializableClasses]);
+        }
+
+        return unserialize($value);
+    }
+}