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 Ndrstmr\Icap\Config;
25
26	/**
27	* Contract for ICAP transport implementations.
28	*
29	* The raw request is supplied as an iterable of byte chunks so large
30	* encapsulated HTTP bodies are streamed onto the socket without being
31	* concatenated in memory.
32	*
33	* The optional {@see Cancellation} parameter lets a caller abort a
34	* request in flight (combined with the transport's own timeouts derived
35	* from Config). Implementations MUST honour the cancellation by aborting
36	* the read and write loops with `Amp\CancelledException`. The client hands
37	* its transport the end of the operation (M10) as this cancellation: it
38	* ends with the caller's cancellation and with the end of the operation
39	* alike. A timeout of the transport's own is not a cancellation: it
40	* surfaces as {@see \Ndrstmr\Icap\Exception\IcapTimeoutException}.
41	*/
42	interface TransportInterface
43	{
44	/**
45	* @param iterable<string> $rawRequest Request bytes, in transport order
46	*
47	* @return \Amp\Future<string>
48	*/
49	public function request(Config $config, iterable $rawRequest, ?Cancellation $cancellation = null): \Amp\Future;
50	}