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\Transport;
22
23	use Amp\Cancellation;
24	use Amp\Socket\Socket;
25	use Ndrstmr\Icap\Config;
26
27	/**
28	* Process-local cache of TCP/TLS connections to ICAP servers.
29	*
30	* The transport calls {@see acquire()} before sending the request
31	* and {@see release()} only after the caller has validated the whole
32	* exchange; a socket whose exchange was not validated is closed by the
33	* transport and never offered. The pool decides whether to hand out an
34	* existing idle socket or open a new one, and whether to keep a
35	* returned socket idle or close it.
36	*
37	* The default implementation is {@see AmpConnectionPool}; the no-op
38	* variant {@see NullConnectionPool} opens a fresh connection on every
39	* acquire and closes it on release.
40	*
41	* Implementations MUST be safe to use across concurrent
42	* acquire/release cycles within a single fiber-driven event loop;
43	* cross-process safety is the implementer's choice.
44	*/
45	interface ConnectionPoolInterface
46	{
47	/**
48	* Hand back a socket connected to the host described by $config.
49	* Returns either a previously released, still-alive socket or a
50	* freshly opened one. May suspend the current fiber while
51	* connecting; honours $cancellation if supplied.
52	*
53	* An implementation that limits its connections ({@see AmpConnectionPool})
54	* throws {@see \Ndrstmr\Icap\Exception\IcapConnectionException} when it has
55	* none to give, or lets the call wait for one and then throws
56	* {@see \Ndrstmr\Icap\Exception\IcapTimeoutException} when the wait runs out.
57	* A call that was cancelled before it began connects to nobody.
58	*/
59	public function acquire(Config $config, ?Cancellation $cancellation = null): Socket;
60
61	/**
62	* Hand a socket back to the pool. The caller MUST NOT continue
63	* using the socket after this call. Implementations may close
64	* the socket if it isn't reusable (already closed, pool full,
65	* server signalled `Connection: close`), and close one that did
66	* not come from them.
67	*/
68	public function release(Config $config, Socket $socket): void;
69
70	/**
71	* Close every pooled idle socket. Idempotent. Sockets currently
72	* in use by callers are unaffected — they will be closed when
73	* released against this pool, since the pool won't accept new
74	* idle entries after close().
75	*/
76	public function close(): void;
77	}