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	/**
24	* A bound socket that can carry more than one write/read round-trip
25	* before being released.
26	*
27	* The strict RFC 3507 §4.5 preview-continue flow needs this: the
28	* client sends the preview, reads the server's `100 Continue`, then
29	* sends the rest of the body — all on the same connection, all part
30	* of one logical ICAP request. The plain
31	* {@see TransportInterface::request()} method is one-shot and can't
32	* model that.
33	*
34	* Sessions are obtained from
35	* {@see SessionAwareTransport::openSession()}. Callers MUST call
36	* either {@see release()} (return to the pool when configured, close
37	* otherwise) or {@see close()} (force-close), exactly once.
38	*/
39	interface TransportSession
40	{
41	/**
42	* Push request bytes onto the socket. Honours the cancellation
43	* token the session was opened with.
44	*
45	* @param iterable<string> $chunks
46	*/
47	public function write(iterable $chunks): void;
48
49	/**
50	* Read one fully-framed ICAP response from the socket. The
51	* underlying {@see ResponseFrameReader} stops as soon as the
52	* message is complete, leaving any trailing bytes in the kernel
53	* buffer for the next call.
54	*/
55	public function readResponse(): string;
56
57	/**
58	* Return the socket to the underlying pool when one is configured;
59	* otherwise close it. Idempotent in the sense that further calls
60	* are no-ops.
61	*/
62	public function release(): void;
63
64	/**
65	* Force-close the socket without offering it back to a pool.
66	* Required when the protocol exchange went off the rails (parse
67	* error, server-side `Connection: close`, exception inside the
68	* request flow).
69	*/
70	public function close(): void;
71	}