1	<?php
2
3	/**
4	* SPDX-License-Identifier: EUPL-1.2
5	*
6	* This file is part of icap-flow.
7	*
8	* Licensed under the EUPL, Version 1.2 only (the "Licence");
9	* you may not use this work except in compliance with the Licence.
10	* You may obtain a copy of the Licence at:
11	*
12	*     https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
13	*
14	* Unless required by applicable law or agreed to in writing, software
15	* distributed under the Licence is distributed on an "AS IS" basis,
16	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17	*/
18
19	declare(strict_types=1);
20
21	namespace Ndrstmr\Icap\Cache;
22
23	use Ndrstmr\Icap\DTO\IcapResponse;
24
25	/**
26	* Storage for cached ICAP OPTIONS responses (RFC 3507 §4.10.2).
27	*
28	* The library ships a default in-memory implementation
29	* ({@see InMemoryOptionsCache}); production deployments that want
30	* cross-process caching can implement this interface against
31	* Redis / APCu / file system / PSR-16 adapter / etc.
32	*
33	* Implementations MUST honour the TTL passed to {@see set()} and
34	* return null from {@see get()} once the entry has expired.
35	*/
36	interface OptionsCacheInterface
37	{
38	/**
39	* Return the cached response for $key, or null on cache miss
40	* (entry absent or expired).
41	*/
42	public function get(string $key): ?IcapResponse;
43
44	/**
45	* Store $response under $key for at most $ttlSeconds. A value
46	* <= 0 means "do not cache".
47	*
48	* When $istag is not null, the implementation SHOULD use it to
49	* invalidate stale entries: if the ISTag (RFC 3507 §4.10.2
50	* "Implementation Status Tag") has changed since the last store,
51	* the server's configuration or signature database was updated
52	* and all previously cached entries are potentially stale.
53	*/
54	public function set(string $key, IcapResponse $response, int $ttlSeconds, ?string $istag = null): void;
55
56	/**
57	* Remove the cached entry for $key. Idempotent.
58	*/
59	public function delete(string $key): void;
60	}