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	use Ndrstmr\Icap\DTO\IcapResponse;
26
27	/**
28	* Optional capability of a transport: to receive a response without keeping it.
29	*
30	* {@see TransportInterface::request()} returns the whole response as a string, which bounds it by what fits in
31	* memory. A transport that implements this interface reads the response as it arrives, checks it to its last byte
32	* and keeps neither its frame nor its body ({@see IcapResponse::$discardedBodyBytes}). The scan helpers use it when
33	* their caller asks for the body to be discarded ({@see \Ndrstmr\Icap\DiscardingIcapClient}); a transport without it
34	* is refused there, not asked to buffer. A transport that is also a {@see SessionAwareTransport} opens sessions that
35	* are {@see DiscardingTransportSession}s.
36	*/
37	interface DiscardingTransport extends TransportInterface
38	{
39	/**
40	* Like {@see TransportInterface::request()}, with a response that is not kept. Framing, windows, cancellation and
41	* the closing of the socket are the same. `$maxResponseBytes` is the budget for the bytes of the whole response in
42	* place of `Config::getMaxResponseSize()`; a response over it, or an illegal one, fails with an
43	* {@see \Ndrstmr\Icap\Exception\IcapMalformedResponseException}. The limits for header lines and their number are
44	* those of the configuration.
45	*
46	* @param iterable<string> $rawRequest
47	*
48	* @return \Amp\Future<IcapResponse>
49	*/
50	public function requestDiscardingBody(
51	Config $config,
52	iterable $rawRequest,
53	int $maxResponseBytes,
54	?Cancellation $cancellation = null,
55	): \Amp\Future;
56	}