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