Debian Codegraph @

vendor/react/promise-stream/src/functions.php

raw
1 <?php
2
3 namespace React\Promise\Stream;
4
5 use Evenement\EventEmitterInterface;
6 use React\Promise;
7 use React\Promise\PromiseInterface;
8 use React\Stream\ReadableStreamInterface;
9 use React\Stream\WritableStreamInterface;
10
11 /**
12 * Create a `Promise` which will be fulfilled with the stream data buffer.
13 *
14 * ```php
15 * $stream = accessSomeJsonStream();
16 *
17 * React\Promise\Stream\buffer($stream)->then(function (string $contents) {
18 * var_dump(json_decode($contents));
19 * });
20 * ```
21 *
22 * The promise will be fulfilled with a `string` of all data chunks concatenated once the stream closes.
23 *
24 * The promise will be fulfilled with an empty `string` if the stream is already closed.
25 *
26 * The promise will be rejected with a `RuntimeException` if the stream emits an error.
27 *
28 * The promise will be rejected with a `RuntimeException` if it is cancelled.
29 *
30 * The optional `$maxLength` argument defaults to no limit. In case the maximum
31 * length is given and the stream emits more data before the end, the promise
32 * will be rejected with an `OverflowException`.
33 *
34 * ```php
35 * $stream = accessSomeToLargeStream();
36 *
37 * React\Promise\Stream\buffer($stream, 1024)->then(function ($contents) {
38 * var_dump(json_decode($contents));
39 * }, function ($error) {
40 * // Reaching here when the stream buffer goes above the max size,
41 * // in this example that is 1024 bytes,
42 * // or when the stream emits an error.
43 * });
44 * ```
45 *
46 * @param ReadableStreamInterface<string> $stream
47 * @param ?int $maxLength Maximum number of bytes to buffer or null for unlimited.
48 * @return PromiseInterface<string>
49 */
50 function buffer(ReadableStreamInterface $stream, $maxLength = null)
51 {
52 // stream already ended => resolve with empty buffer
53 if (!$stream->isReadable()) {
54 return Promise\resolve('');
55 }
56
57 $buffer = '';
58
59 $promise = new Promise\Promise(function ($resolve, $reject) use ($stream, $maxLength, &$buffer, &$bufferer) {
60 $bufferer = function ($data) use (&$buffer, $reject, $maxLength) {
61 $buffer .= $data;
62
63 if ($maxLength !== null && isset($buffer[$maxLength])) {
64 $reject(new \OverflowException('Buffer exceeded maximum length'));
65 }
66 };
67
68 $stream->on('data', $bufferer);
69
70 $stream->on('error', function (\Exception $e) use ($reject) {
71 $reject(new \RuntimeException(
72 'An error occured on the underlying stream while buffering: ' . $e->getMessage(),
73 $e->getCode(),
74 $e
75 ));
76 });
77
78 $stream->on('close', function () use ($resolve, &$buffer) {
79 $resolve($buffer);
80 });
81 }, function ($_, $reject) {
82 $reject(new \RuntimeException('Cancelled buffering'));
83 });
84
85 return $promise->then(null, function (\Exception $error) use (&$buffer, $bufferer, $stream) {
86 // promise rejected => clear buffer and buffering
87 $buffer = '';
88 $stream->removeListener('data', $bufferer);
89
90 throw $error;
91 });
92 }
93
94 /**
95 * Create a `Promise` which will be fulfilled once the given event triggers for the first time.
96 *
97 * ```php
98 * $stream = accessSomeJsonStream();
99 *
100 * React\Promise\Stream\first($stream)->then(function (string $chunk) {
101 * echo 'The first chunk arrived: ' . $chunk;
102 * });
103 * ```
104 *
105 * The promise will be fulfilled with a `mixed` value of whatever the first event
106 * emitted or `null` if the event does not pass any data.
107 * If you do not pass a custom event name, then it will wait for the first "data"
108 * event.
109 * For common streams of type `ReadableStreamInterface<string>`, this means it will be
110 * fulfilled with a `string` containing the first data chunk.
111 *
112 * The promise will be rejected with a `RuntimeException` if the stream emits an error
113 * – unless you're waiting for the "error" event, in which case it will be fulfilled.
114 *
115 * The promise will be rejected with a `RuntimeException` once the stream closes
116 * – unless you're waiting for the "close" event, in which case it will be fulfilled.
117 *
118 * The promise will be rejected with a `RuntimeException` if the stream is already closed.
119 *
120 * The promise will be rejected with a `RuntimeException` if it is cancelled.
121 *
122 * @param ReadableStreamInterface|WritableStreamInterface $stream
123 * @param string $event
124 * @return PromiseInterface<mixed>
125 */
126 function first(EventEmitterInterface $stream, $event = 'data')
127 {
128 if ($stream instanceof ReadableStreamInterface) {
129 // readable or duplex stream not readable => already closed
130 // a half-open duplex stream is considered closed if its readable side is closed
131 if (!$stream->isReadable()) {
132 return Promise\reject(new \RuntimeException('Stream already closed'));
133 }
134 } elseif ($stream instanceof WritableStreamInterface) {
135 // writable-only stream (not duplex) not writable => already closed
136 if (!$stream->isWritable()) {
137 return Promise\reject(new \RuntimeException('Stream already closed'));
138 }
139 }
140
141 return new Promise\Promise(function ($resolve, $reject) use ($stream, $event, &$listener) {
142 $listener = function ($data = null) use ($stream, $event, &$listener, $resolve) {
143 $stream->removeListener($event, $listener);
144 $listener = null;
145 $resolve($data);
146 };
147 $stream->on($event, $listener);
148
149 if ($event !== 'error') {
150 $stream->on('error', function (\Exception $e) use ($stream, $event, $listener, $reject) {
151 $stream->removeListener($event, $listener);
152 $reject(new \RuntimeException(
153 'An error occured on the underlying stream while waiting for event: ' . $e->getMessage(),
154 $e->getCode(),
155 $e
156 ));
157 });
158 }
159
160 $stream->on('close', function () use ($stream, $event, &$listener, $reject) {
161 if ($listener !== null) {
162 $stream->removeListener($event, $listener);
163 $listener = null;
164 }
165 $reject(new \RuntimeException('Stream closed'));
166 });
167 }, function ($_, $reject) use ($stream, $event, &$listener) {
168 $stream->removeListener($event, $listener);
169 $reject(new \RuntimeException('Operation cancelled'));
170 });
171 }
172
173 /**
174 * Create a `Promise` which will be fulfilled with an array of all the event data.
175 *
176 * ```php
177 * $stream = accessSomeJsonStream();
178 *
179 * React\Promise\Stream\all($stream)->then(function (array $chunks) {
180 * echo 'The stream consists of ' . count($chunks) . ' chunk(s)';
181 * });
182 * ```
183 *
184 * The promise will be fulfilled with an `array` once the stream closes. The array
185 * will contain whatever all events emitted or `null` values if the events do not pass any data.
186 * If you do not pass a custom event name, then it will wait for all the "data"
187 * events.
188 * For common streams of type `ReadableStreamInterface<string>`, this means it will be
189 * fulfilled with a `string[]` array containing all the data chunk.
190 *
191 * The promise will be fulfilled with an empty `array` if the stream is already closed.
192 *
193 * The promise will be rejected with a `RuntimeException` if the stream emits an error.
194 *
195 * The promise will be rejected with a `RuntimeException` if it is cancelled.
196 *
197 * @param ReadableStreamInterface|WritableStreamInterface $stream
198 * @param string $event
199 * @return PromiseInterface<array>
200 */
201 function all(EventEmitterInterface $stream, $event = 'data')
202 {
203 // stream already ended => resolve with empty buffer
204 if ($stream instanceof ReadableStreamInterface) {
205 // readable or duplex stream not readable => already closed
206 // a half-open duplex stream is considered closed if its readable side is closed
207 if (!$stream->isReadable()) {
208 return Promise\resolve(array());
209 }
210 } elseif ($stream instanceof WritableStreamInterface) {
211 // writable-only stream (not duplex) not writable => already closed
212 if (!$stream->isWritable()) {
213 return Promise\resolve(array());
214 }
215 }
216
217 $buffer = array();
218 $bufferer = function ($data = null) use (&$buffer) {
219 $buffer []= $data;
220 };
221 $stream->on($event, $bufferer);
222
223 $promise = new Promise\Promise(function ($resolve, $reject) use ($stream, &$buffer) {
224 $stream->on('error', function (\Exception $e) use ($reject) {
225 $reject(new \RuntimeException(
226 'An error occured on the underlying stream while buffering: ' . $e->getMessage(),
227 $e->getCode(),
228 $e
229 ));
230 });
231
232 $stream->on('close', function () use ($resolve, &$buffer) {
233 $resolve($buffer);
234 });
235 }, function ($_, $reject) {
236 $reject(new \RuntimeException('Cancelled buffering'));
237 });
238
239 return $promise->then(null, function ($error) use (&$buffer, $bufferer, $stream, $event) {
240 // promise rejected => clear buffer and buffering
241 $buffer = array();
242 $stream->removeListener($event, $bufferer);
243
244 throw $error;
245 });
246 }
247
248 /**
249 * Unwrap a `Promise` which will be fulfilled with a `ReadableStreamInterface<T>`.
250 *
251 * This function returns a readable stream instance (implementing `ReadableStreamInterface<T>`)
252 * right away which acts as a proxy for the future promise resolution.
253 * Once the given Promise will be fulfilled with a `ReadableStreamInterface<T>`, its
254 * data will be piped to the output stream.
255 *
256 * ```php
257 * //$promise = someFunctionWhichResolvesWithAStream();
258 * $promise = startDownloadStream($uri);
259 *
260 * $stream = React\Promise\Stream\unwrapReadable($promise);
261 *
262 * $stream->on('data', function (string $data) {
263 * echo $data;
264 * });
265 *
266 * $stream->on('end', function () {
267 * echo 'DONE';
268 * });
269 * ```
270 *
271 * If the given promise is either rejected or fulfilled with anything but an
272 * instance of `ReadableStreamInterface`, then the output stream will emit
273 * an `error` event and close:
274 *
275 * ```php
276 * $promise = startDownloadStream($invalidUri);
277 *
278 * $stream = React\Promise\Stream\unwrapReadable($promise);
279 *
280 * $stream->on('error', function (Exception $error) {
281 * echo 'Error: ' . $error->getMessage();
282 * });
283 * ```
284 *
285 * The given `$promise` SHOULD be pending, i.e. it SHOULD NOT be fulfilled or rejected
286 * at the time of invoking this function.
287 * If the given promise is already settled and does not fulfill with an instance of
288 * `ReadableStreamInterface`, then you will not be able to receive the `error` event.
289 *
290 * You can `close()` the resulting stream at any time, which will either try to
291 * `cancel()` the pending promise or try to `close()` the underlying stream.
292 *
293 * ```php
294 * $promise = startDownloadStream($uri);
295 *
296 * $stream = React\Promise\Stream\unwrapReadable($promise);
297 *
298 * $loop->addTimer(2.0, function () use ($stream) {
299 * $stream->close();
300 * });
301 * ```
302 *
303 * @param PromiseInterface<ReadableStreamInterface<T>> $promise
304 * @return ReadableStreamInterface<T>
305 */
306 function unwrapReadable(PromiseInterface $promise)
307 {
308 return new UnwrapReadableStream($promise);
309 }
310
311 /**
312 * unwrap a `Promise` which will be fulfilled with a `WritableStreamInterface<T>`.
313 *
314 * This function returns a writable stream instance (implementing `WritableStreamInterface<T>`)
315 * right away which acts as a proxy for the future promise resolution.
316 * Any writes to this instance will be buffered in memory for when the promise will
317 * be fulfilled.
318 * Once the given Promise will be fulfilled with a `WritableStreamInterface<T>`, any
319 * data you have written to the proxy will be forwarded transparently to the inner
320 * stream.
321 *
322 * ```php
323 * //$promise = someFunctionWhichResolvesWithAStream();
324 * $promise = startUploadStream($uri);
325 *
326 * $stream = React\Promise\Stream\unwrapWritable($promise);
327 *
328 * $stream->write('hello');
329 * $stream->end('world');
330 *
331 * $stream->on('close', function () {
332 * echo 'DONE';
333 * });
334 * ```
335 *
336 * If the given promise is either rejected or fulfilled with anything but an
337 * instance of `WritableStreamInterface`, then the output stream will emit
338 * an `error` event and close:
339 *
340 * ```php
341 * $promise = startUploadStream($invalidUri);
342 *
343 * $stream = React\Promise\Stream\unwrapWritable($promise);
344 *
345 * $stream->on('error', function (Exception $error) {
346 * echo 'Error: ' . $error->getMessage();
347 * });
348 * ```
349 *
350 * The given `$promise` SHOULD be pending, i.e. it SHOULD NOT be fulfilled or rejected
351 * at the time of invoking this function.
352 * If the given promise is already settled and does not fulfill with an instance of
353 * `WritableStreamInterface`, then you will not be able to receive the `error` event.
354 *
355 * You can `close()` the resulting stream at any time, which will either try to
356 * `cancel()` the pending promise or try to `close()` the underlying stream.
357 *
358 * ```php
359 * $promise = startUploadStream($uri);
360 *
361 * $stream = React\Promise\Stream\unwrapWritable($promise);
362 *
363 * $loop->addTimer(2.0, function () use ($stream) {
364 * $stream->close();
365 * });
366 * ```
367 *
368 * @param PromiseInterface<WritableStreamInterface<T>> $promise
369 * @return WritableStreamInterface<T>
370 */
371 function unwrapWritable(PromiseInterface $promise)
372 {
373 return new UnwrapWritableStream($promise);
374 }