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\IcapRequest;
26	use Ndrstmr\Icap\DTO\IcapResponse;
27	use Ndrstmr\Icap\DTO\ScanResult;
28
29	/**
30	* Public contract for ICAP clients.
31	*
32	* Implementations are async-native and return Amp Futures. The synchronous
33	* decorator {@see SynchronousIcapClient} awaits those Futures behind a
34	* blocking facade.
35	*
36	* Every method takes an optional {@see Cancellation} so a caller can
37	* abort an in-flight scan from the outside (e.g. when an upstream HTTP
38	* upload has been aborted). The user-supplied token is combined with the
39	* per-request timeout cancellation derived from
40	* {@see Config::getStreamTimeout()}; whichever fires first wins.
41	*/
42	interface IcapClientInterface
43	{
44	/**
45	* Send a raw ICAP request.
46	*
47	* @return Future<ScanResult>
48	*/
49	public function request(IcapRequest $request, ?Cancellation $cancellation = null): Future;
50
51	/**
52	* Issue an OPTIONS request against the given service. Returns the raw
53	* {@see IcapResponse} on success so callers can inspect capability
54	* headers (`Preview`, `Options-TTL`, `Methods`, `Allow`, `Service`,
55	* `ISTag`, …) directly. The fail-secure status-code interpretation
56	* still applies — 4xx throws {@see IcapClientException}, 5xx throws
57	* {@see IcapServerException}, `100 Continue` throws
58	* {@see IcapProtocolException}.
59	*
60	* @return Future<IcapResponse>
61	*/
62	public function options(string $service, ?Cancellation $cancellation = null): Future;
63
64	/**
65	* Scan a local file via RESPMOD.
66	*
67	* @param array<string, string|string[]> $extraHeaders Extra ICAP request
68	*        headers, e.g. `['X-Client-IP' => '203.0.113.5']`. Library-managed
69	*        headers (`Host`, `Encapsulated`, `Connection`) always take precedence.
70	* @return Future<ScanResult>
71	*/
72	public function scanFile(
73	string $service,
74	string $filePath,
75	array $extraHeaders = [],
76	?Cancellation $cancellation = null,
77	): Future;
78
79	/**
80	* Scan a file using preview mode, streaming the remainder on demand.
81	*
82	* When $previewSize is null the client queries the OPTIONS cache for
83	* the server's advertised `Preview` header (RFC 3507 §4.10.2) and
84	* uses that value. Falls back to 1024 when the cache has no entry
85	* or the response carries no `Preview` header.
86	*
87	* @param array<string, string|string[]> $extraHeaders See {@see scanFile()}.
88	*        `Preview` and `Allow` are library-managed and cannot be
89	*        overridden via this parameter.
90	* @return Future<ScanResult>
91	*/
92	public function scanFileWithPreview(
93	string $service,
94	string $filePath,
95	?int $previewSize = null,
96	array $extraHeaders = [],
97	?Cancellation $cancellation = null,
98	): Future;
99	}