From 6b41ea01e9c41aea27e81dc5bdb91c8710464ced Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Sun, 23 Apr 2017 13:37:07 +0200 Subject: [PATCH] Only emit `error` event for fatal errors --- README.md | 53 ++++++++++++++++----------------- src/ReadableStreamInterface.php | 28 ++++++++--------- src/WritableStreamInterface.php | 25 ++++++++-------- 3 files changed, 52 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 4fddecb..41f95bd 100644 --- a/README.md +++ b/README.md @@ -124,7 +124,7 @@ stream. #### error event -The `error` event will be emitted whenever an error occurs, usually while +The `error` event will be emitted once a fatal error occurs, usually while trying to read from this stream. The event receives a single `Exception` argument for the error instance. @@ -134,23 +134,23 @@ $server->on('error', function (Exception $e) { }); ``` -This event MAY be emitted any number of times, which should be zero -times if this is a stream that is successfully terminated. -It SHOULD be emitted whenever the stream detects an error, such as a -transmission error or after an unexpected `data` or premature `end` event. -It SHOULD NOT be emitted after a `close` event. +This event SHOULD be emitted once the stream detects a fatal error, such +as a fatal transmission error or after an unexpected `data` or premature +`end` event. +It SHOULD NOT be emitted after a previous `error`, `end` or `close` event. +It MUST NOT be emitted if this is not a fatal error condition, such as +a temporary network issue that did not cause any data to be lost. + +After the stream errors, it MUST close the stream and SHOULD thus be +followed by a `close` event and then switch to non-readable mode, see +also `close()` and `isReadable()`. Many common streams (such as a TCP/IP connection or a file-based stream) only deal with data transmission and do not make assumption about data boundaries (such as unexpected `data` or premature `end` events). In other words, many lower-level protocols (such as TCP/IP) may choose -to only emit this for a fatal transmission error once and will thus -likely close (terminate) the stream in response. -If this is a fatal error that results in the stream being closed, it -SHOULD be followed by a `close` event. - -Other higher-level protocols may choose to keep the stream alive after -this event, if they can recover from an error condition. +to only emit this for a fatal transmission error once and will then +close (terminate) the stream in response. If this stream is a `DuplexStreamInterface`, you should also notice how the writable side of the stream also implements an `error` event. @@ -177,7 +177,7 @@ see also `isReadable()`. Unlike the `end` event, this event SHOULD be emitted whenever the stream closes, irrespective of whether this happens implicitly due to an unrecoverable error or explicitly when either side closes the stream. -If you only want to detect a *succesful* end, you should use the `end` +If you only want to detect a *successful* end, you should use the `end` event instead. Many common streams (such as a TCP/IP connection or a file-based stream) @@ -434,7 +434,7 @@ This event is mostly used internally, see also `pipe()` for more details. #### error event -The `error` event will be emitted whenever an error occurs, usually while +The `error` event will be emitted once a fatal error occurs, usually while trying to write to this stream. The event receives a single `Exception` argument for the error instance. @@ -444,21 +444,20 @@ $stream->on('error', function (Exception $e) { }); ``` -This event MAY be emitted any number of times, which should be zero -times if this is a stream that is successfully terminated. -It SHOULD be emitted whenever the stream detects an error, such as a -transmission error. -It SHOULD NOT be emitted after a `close` event. +This event SHOULD be emitted once the stream detects a fatal error, such +as a fatal transmission error. +It SHOULD NOT be emitted after a previous `error` or `close` event. +It MUST NOT be emitted if this is not a fatal error condition, such as +a temporary network issue that did not cause any data to be lost. + +After the stream errors, it MUST close the stream and SHOULD thus be +followed by a `close` event and then switch to non-writable mode, see +also `close()` and `isWritable()`. Many common streams (such as a TCP/IP connection or a file-based stream) only deal with data transmission and may choose -to only emit this for a fatal transmission error once and will thus -likely close (terminate) the stream in response. -If this is a fatal error that results in the stream being closed, it -SHOULD be followed by a `close` event. - -Other higher-level protocols may choose to keep the stream alive after -this event, if they can recover from an error condition. +to only emit this for a fatal transmission error once and will then +close (terminate) the stream in response. If this stream is a `DuplexStreamInterface`, you should also notice how the readable side of the stream also implements an `error` event. diff --git a/src/ReadableStreamInterface.php b/src/ReadableStreamInterface.php index bba1834..87c5ad3 100644 --- a/src/ReadableStreamInterface.php +++ b/src/ReadableStreamInterface.php @@ -79,7 +79,7 @@ * stream. * * error event: - * The `error` event will be emitted whenever an error occurs, usually while + * The `error` event will be emitted once a fatal error occurs, usually while * trying to read from this stream. * The event receives a single `Exception` argument for the error instance. * @@ -89,23 +89,23 @@ * }); * ``` * - * This event MAY be emitted any number of times, which should be zero - * times if this is a stream that is successfully terminated. - * It SHOULD be emitted whenever the stream detects an error, such as a - * transmission error or after an unexpected `data` or premature `end` event. - * It SHOULD NOT be emitted after a `close` event. + * This event SHOULD be emitted once the stream detects a fatal error, such + * as a fatal transmission error or after an unexpected `data` or premature + * `end` event. + * It SHOULD NOT be emitted after a previous `error`, `end` or `close` event. + * It MUST NOT be emitted if this is not a fatal error condition, such as + * a temporary network issue that did not cause any data to be lost. + * + * After the stream errors, it MUST close the stream and SHOULD thus be + * followed by a `close` event and then switch to non-readable mode, see + * also `close()` and `isReadable()`. * * Many common streams (such as a TCP/IP connection or a file-based stream) * only deal with data transmission and do not make assumption about data * boundaries (such as unexpected `data` or premature `end` events). * In other words, many lower-level protocols (such as TCP/IP) may choose - * to only emit this for a fatal transmission error once and will thus - * likely close (terminate) the stream in response. - * If this is a fatal error that results in the stream being closed, it - * SHOULD be followed by a `close` event. - * - * Other higher-level protocols may choose to keep the stream alive after - * this event, if they can recover from an error condition. + * to only emit this for a fatal transmission error once and will then + * close (terminate) the stream in response. * * If this stream is a `DuplexStreamInterface`, you should also notice * how the writable side of the stream also implements an `error` event. @@ -131,7 +131,7 @@ * Unlike the `end` event, this event SHOULD be emitted whenever the stream * closes, irrespective of whether this happens implicitly due to an * unrecoverable error or explicitly when either side closes the stream. - * If you only want to detect a *succesful* end, you should use the `end` + * If you only want to detect a *successful* end, you should use the `end` * event instead. * * Many common streams (such as a TCP/IP connection or a file-based stream) diff --git a/src/WritableStreamInterface.php b/src/WritableStreamInterface.php index 836fc7a..c991201 100644 --- a/src/WritableStreamInterface.php +++ b/src/WritableStreamInterface.php @@ -59,7 +59,7 @@ * This event is mostly used internally, see also `pipe()` for more details. * * error event: - * The `error` event will be emitted whenever an error occurs, usually while + * The `error` event will be emitted once a fatal error occurs, usually while * trying to write to this stream. * The event receives a single `Exception` argument for the error instance. * @@ -69,21 +69,20 @@ * }); * ``` * - * This event MAY be emitted any number of times, which should be zero - * times if this is a stream that is successfully terminated. - * It SHOULD be emitted whenever the stream detects an error, such as a - * transmission error. - * It SHOULD NOT be emitted after a `close` event. + * This event SHOULD be emitted once the stream detects a fatal error, such + * as a fatal transmission error. + * It SHOULD NOT be emitted after a previous `error` or `close` event. + * It MUST NOT be emitted if this is not a fatal error condition, such as + * a temporary network issue that did not cause any data to be lost. + * + * After the stream errors, it MUST close the stream and SHOULD thus be + * followed by a `close` event and then switch to non-writable mode, see + * also `close()` and `isWritable()`. * * Many common streams (such as a TCP/IP connection or a file-based stream) * only deal with data transmission and may choose - * to only emit this for a fatal transmission error once and will thus - * likely close (terminate) the stream in response. - * If this is a fatal error that results in the stream being closed, it - * SHOULD be followed by a `close` event. - * - * Other higher-level protocols may choose to keep the stream alive after - * this event, if they can recover from an error condition. + * to only emit this for a fatal transmission error once and will then + * close (terminate) the stream in response. * * If this stream is a `DuplexStreamInterface`, you should also notice * how the readable side of the stream also implements an `error` event.