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;
22
23	use Amp\Cancellation;
24	use Amp\Future;
25	use Ndrstmr\Icap\DTO\ScanResult;
26
27	/**
28	* Optional capability of a client: the scan helpers for a caller who needs the result and the metadata
29	* of the response, not its body.
30	*
31	* A server that is not offered `Allow: 204` has to send the whole message back (RFC 3507 §4.6), so the
32	* answer to a large file is as large as the file. The methods of this interface receive each response of the
33	* exchange as it arrives, check it to its last byte, count the body and drop it: what the client holds does not
34	* depend on its size, and the result has an empty body and its length in
35	* {@see \Ndrstmr\Icap\DTO\IcapResponse::$discardedBodyBytes}. Request, checks and verdict are those of
36	* {@see IcapClientInterface}; `Allow: 204` is not added.
37	*
38	* `$maxResponseBytes` has no default: it bounds the bytes of each response (head, headers, chunk framing, body and
39	* trailer) in place of `Config::getMaxResponseSize()`. The stream timeout is the time a whole response may take once
40	* it has begun, so it and the operation timeout have to allow for the transfer of a large one.
41	*
42	* A client whose transport or parser cannot discard throws a \LogicException from these methods, before it opens a
43	* file or a connection; so does a client with a preview strategy of its own, which may judge the body of the answer
44	* to the preview. Bytes behind a response, already read, are an {@see \Ndrstmr\Icap\Exception\IcapMalformedResponseException}.
45	*/
46	interface DiscardingIcapClient
47	{
48	/**
49	* {@see IcapClientInterface::scanFile()} with the body of the response discarded.
50	*
51	* @param array<string, string|string[]> $extraHeaders
52	*
53	* @return Future<ScanResult>
54	*
55	* @throws \InvalidArgumentException When the budget is below 1
56	* @throws \LogicException           When the transport or the parser cannot discard
57	*/
58	public function scanFileDiscardingBody(
59	string $service,
60	string $filePath,
61	int $maxResponseBytes,
62	array $extraHeaders = [],
63	?Cancellation $cancellation = null,
64	): Future;
65
66	/**
67	* {@see IcapClientInterface::scanFileWithPreview()} with the body of every response of the exchange discarded,
68	* the final answer after `100 Continue` included.
69	*
70	* @param array<string, string|string[]> $extraHeaders
71	*
72	* @return Future<ScanResult>
73	*
74	* @throws \InvalidArgumentException When the budget is below 1, or $previewSize is outside 0..1 MiB
75	* @throws \LogicException           When the transport or the parser cannot discard, or the preview strategy
76	*                                   is not that of the library
77	*/
78	public function scanFileWithPreviewDiscardingBody(
79	string $service,
80	string $filePath,
81	int $maxResponseBytes,
82	?int $previewSize = null,
83	array $extraHeaders = [],
84	?Cancellation $cancellation = null,
85	): Future;
86	}