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, all chunks of the call within one
43	* window of `streamTimeout` seconds and under the cancellation token the
44	* session was opened with. A call that does not finish ends the session
45	* for good (it is closed, and {@see release()} cannot pool it): a
46	* cancellation by the caller, also a `TimeoutCancellation`, throws
47	* `Amp\CancelledException`, the window passing throws
48	* {@see \Ndrstmr\Icap\Exception\IcapTimeoutException}. Both are looked
49	* at before the producer is asked for anything, whenever it hands a chunk
50	* back, an empty one too, after every write and before the call returns:
51	* a call that is cancelled or out of time before it begins asks the
52	* producer for nothing, and a producer that is slow, or blocks the event
53	* loop, cannot extend the window or finish the call after it.
54	*
55	* @param iterable<string> $chunks
56	*/
57	public function write(iterable $chunks): void;
58
59	/**
60	* Read one fully-framed ICAP response from the socket. The response ends
61	* where its layout says ({@see ResponseFrameReader}); one that is illegal,
62	* that the stream cuts off, or behind which the read brought in further
63	* bytes throws {@see \Ndrstmr\Icap\Exception\IcapMalformedResponseException}
64	* and ends the session: a connection carries one outstanding request at a
65	* time (RFC 3507 §4.1), so those bytes answer nothing. Bytes that arrive
66	* later are not waited for. Cancellation and failure behave as for
67	* {@see write()}; the windows are two, one after the other (M10): the
68	* server's time to begin its answer once the request is sent
69	* (`Config::getResponseStartTimeout()`), then, from the first byte, a
70	* maximum for the answer to arrive in full (`Config::getStreamTimeout()`)
71	* that no further byte starts again.
72	*/
73	public function readResponse(): string;
74
75	/**
76	* Return the socket to the underlying pool when one is configured;
77	* otherwise close it. Call it only after the whole exchange has been
78	* validated (frame, status, verdict, no `Connection: close`): a
79	* released socket is out of reach of {@see close()}. Idempotent in
80	* the sense that further calls are no-ops.
81	*/
82	public function release(): void;
83
84	/**
85	* Force-close the socket without offering it back to a pool.
86	* Required when the protocol exchange went off the rails (parse
87	* error, server-side `Connection: close`, exception inside the
88	* request flow).
89	*/
90	public function close(): void;
91	}