var assert = process.env.HTTP2_ASSERT ? require('assert') : function noop() {};
var assert = process.env.HTTP2_ASSERT ? require('assert') : function noop() {};
Flow is a Duplex stream subclass which implements HTTP/2 flow control. It is designed to be
subclassed by Connection and the upstream
component of Stream.
var Duplex = require('stream').Duplex;
exports.Flow = Flow;
Event: 'error' (type): signals an error
setInitialWindow(size): the initial flow control window size can be changed any time (as described in the standard) using this method
disableRemoteFlowControl(): sends a WINDOW_UPDATE signaling that we don't want flow control
disableLocalFlowControl(): disables flow control for outgoing frames
new Flow([flowControlId]): creating a new flow that will listen for WINDOW_UPDATES frames
with the given flowControlId
(or every update frame if not given)
Event: 'receiving' (frame): there's an incoming frame
Event: 'sending' (frame): a frame was added to the output queue
_send(): called when more frames should be pushed. The child class is expected to override
this (instead of the _read
method of the Duplex class).
_receive(frame, readyCallback): called when there's an incoming frame. The child class is
expected to override this (instead of the _write
method of the Duplex class).
push(frame): bool: schedules frame
for sending.
Returns true
if it needs more frames in the output queue, false
if the output queue is
full, and null
if did not push the frame into the output queue (instead, it pushed it into
the flow control queue).
_push(frame, remainderCallback): bool: like push, but never puts the frame into the flow control queue.
Instead, it pushes directly into the output queue if possible (according to the flow control
window) and calls remainderCallback
with the remaining non-pushable part of the frame. It is
capable of dividing DATA frames into multiple chunks.
Use this instead of push
if you always want to have empty flow control queue (but never mix
the two).
getLastQueuedFrame(): frame: returns the last frame in output buffers
_log: the Flow class uses the _log
object of the parent
When a HTTP/2.0 connection is first established, new streams are created with an initial flow control window size of 65535 bytes.
var INITIAL_WINDOW_SIZE = 65535;
flowControlId
is needed if only specific WINDOW_UPDATEs should be watched.
function Flow(flowControlId) {
Duplex.call(this, { objectMode: true });
this._window = this._initialWindow = INITIAL_WINDOW_SIZE;
this._flowControlId = flowControlId;
this._queue = [];
this._ended = false;
this._received = 0;
this._remoteFlowControlDisabled = false;
}
Flow.prototype = Object.create(Duplex.prototype, { constructor: { value: Flow } });
_receive
is called when there's an incoming frame.
Flow.prototype._receive = function _receive(frame, callback) {
throw new Error('The _receive(frame, callback) method has to be overridden by the child class!');
};
_receive
is called by _write
which in turn is called by Duplex when someone write()
s
to the flow. It emits the 'receiving' event and notifies the window size tracking code if the
incoming frame is a WINDOW_UPDATE.
Flow.prototype._write = function _write(frame, encoding, callback) {
this.emit('receiving', frame);
if (frame.flags.END_STREAM) {
this._ended = true;
}
if ((frame.type === 'DATA') && (frame.data.length > 0) && !this._remoteFlowControlDisabled) {
this._receive(frame, function() {
this._received += frame.data.length;
if (!this._restoreWindowTimer) {
this._restoreWindowTimer = setImmediate(this._restoreWindow.bind(this));
}
callback();
}.bind(this));
}
else {
this._receive(frame, callback);
}
if ((frame.type === 'WINDOW_UPDATE') &&
((this._flowControlId === undefined) || (frame.stream === this._flowControlId))) {
this._updateWindow(frame);
}
};
_restoreWindow
basically acknowledges the DATA frames received since it's last call. It sends
a WINDOW_UPDATE that restores the flow control window of the remote end.
Flow.prototype._restoreWindow = function _restoreWindow() {
delete this._restoreWindowTimer;
if (!this._ended && !this._remoteFlowControlDisabled && (this._received > 0)) {
this.push({
type: 'WINDOW_UPDATE',
stream: this._flowControlId,
window_size: this._received
});
this._received = 0;
}
};
Must be called after sending a SETTINGS frame that turns off flow control on the remote side.
Flow.prototype.disableRemoteFlowControl = function disableRemoteFlowControl() {
this._log.debug('Turning off remote flow control');
this._remoteFlowControlDisabled = true;
};
flow
+-------------------------------------------------+
| |
+--------+ +---------+ |
read() | output | _read() | flow | _send() |
<----------| |<----------| control |<------------- |
| buffer | | buffer | |
+--------+ +---------+ |
| input | |
---------->| |-----------------------------------> |
write() | buffer | _write() _receive() |
+--------+ |
| |
+-------------------------------------------------+
_send
is called when more frames should be pushed to the output buffer.
Flow.prototype._send = function _send() {
throw new Error('The _send() method has to be overridden by the child class!');
};
_send
is called by _read
which is in turn called by Duplex when it wants to have more
items in the output queue.
Flow.prototype._read = function _read() {
if (this._queue.length === 0) {
this._send();
}
else if (this._window > 0) {
var frame;
var moreNeeded = true;
var unshiftRemainder = this._queue.unshift.bind(this._queue);
while (moreNeeded && (frame = this._queue.shift())) {
moreNeeded = this._push(frame, unshiftRemainder);
}
assert((moreNeeded == false) || // output queue is full
(this._queue.length === 0) || // flow control queue is empty
((this._window === 0) && (this._queue[0].type === 'DATA'))); // waiting for window update
}
this._readableState.reading = false;
};
_push(frame)
is the low-level version of push
. Use this instead of push
if you always want
to have empty flow control queue (but never mix the two). It pushes frame
into the output queue
and decreases the flow control window size. It is capable of splitting DATA frames into smaller
parts, if the window size is not enough to push the whole frame. It calls remainderCallback
synchronously before returning with the frame it was not able to push to the output queue. The
remainder may be the whole frame or the remaining part of a DATA frame. The return value is
similar to push
except that it returns null
if it did not push anything to the output queue.
var MAX_PAYLOAD_SIZE = 4096; // Must not be greater than MAX_HTTP_PAYLOAD_SIZE which is 16383
Flow.prototype._push = function _push(frame, remainderCallback) {
do {
var forwardable = undefined, remainder = undefined;
if ((frame === null) || (frame.type !== 'DATA') ||
((frame.data.length <= this._window) && (frame.data.length <= MAX_PAYLOAD_SIZE))) {
forwardable = frame;
}
else if (this._window <= 0) {
remainder = frame;
}
else {
var chunkSize = Math.min(this._window, MAX_PAYLOAD_SIZE);
forwardable = {
stream: frame.stream,
type: 'DATA',
flags: {},
data: frame.data.slice(0, chunkSize)
};
this._log.trace({ frame: frame, size: frame.data.length, forwardable: chunkSize },
'Splitting out forwardable part of a DATA frame.');
frame.data = frame.data.slice(chunkSize);
remainder = frame;
}
var moreNeeded = null;
if (forwardable !== undefined) {
this._log.trace({ frame: forwardable }, 'Pushing frame into the output queue');
if (forwardable && (forwardable.type === 'DATA') && (this._window !== Infinity)) {
this._log.trace({ window: this._window, by: forwardable.data.length },
'Decreasing flow control window size.');
this._window -= forwardable.data.length;
assert(this._window >= 0);
}
moreNeeded = Duplex.prototype.push.call(this, forwardable);
}
frame = remainder;
} while (remainder && moreNeeded);
if (remainder !== undefined) {
remainderCallback(remainder);
}
return moreNeeded;
};
Push frame
into the flow control queue, or if it's empty, then directly into the output queue
Flow.prototype.push = function push(frame) {
if (frame === null) {
this._log.debug('Enqueueing outgoing End Of Stream');
} else {
frame.flags = frame.flags || {};
this._log.debug({ frame: frame }, 'Enqueueing outgoing frame');
this.emit('sending', frame);
}
if (this._queue.length === 0) {
return this._push(frame, this._queue.push.bind(this._queue));
} else {
this._queue.push(frame);
return null;
}
};
getLastQueuedFrame
returns the last frame in output buffers. This is primarily used by the
Stream class to mark the last frame with END_STREAM flag.
Flow.prototype.getLastQueuedFrame = function getLastQueuedFrame() {
var readableQueue = this._readableState.buffer;
return this._queue[this._queue.length - 1] || readableQueue[readableQueue.length - 1];
};
Flow control window size is manipulated using the _increaseWindow
method.
Infinite
means turning off flow control. Flow control cannot be enabled
again once disabled. Any attempt to re-enable flow control MUST be rejected with a
FLOW_CONTROL_ERROR error code.var WINDOW_SIZE_LIMIT = Math.pow(2, 31) - 1;
Flow.prototype._increaseWindow = function _increaseWindow(size) {
if ((this._window === Infinity) && (size !== Infinity)) {
this._log.error('Trying to increase flow control window after flow control was turned off.');
this.emit('error', 'FLOW_CONTROL_ERROR');
} else {
this._log.trace({ window: this._window, by: size }, 'Increasing flow control window size.');
this._window += size;
if ((this._window !== Infinity) && (this._window > WINDOW_SIZE_LIMIT)) {
this._log.error('Flow control window grew too large.');
this.emit('error', 'FLOW_CONTROL_ERROR');
} else {
this.read(0);
}
}
};
The _updateWindow
method gets called every time there's an incoming WINDOW_UPDATE frame. It
modifies the flow control window:
Flow.prototype._updateWindow = function _updateWindow(frame) {
this._increaseWindow(frame.flags.END_FLOW_CONTROL ? Infinity : frame.window_size);
};
A SETTINGS frame can alter the initial flow control window size for all current streams. When the
value of SETTINGS_INITIAL_WINDOW_SIZE changes, a receiver MUST adjust the size of all stream by
calling the setInitialWindow
method. The window size has to be modified by the difference
between the new value and the old value.
Flow.prototype.setInitialWindow = function setInitialWindow(initialWindow) {
this._increaseWindow(initialWindow - this._initialWindow);
this._initialWindow = initialWindow;
};
Flow control for outgoing frames can be disabled by the peer with various methods.
Flow.prototype.disableLocalFlowControl = function disableLocalFlowControl() {
this._increaseWindow(Infinity);
};