path
{string|Buffer|URL}headers
{HTTP/2 Headers Object}options
{Object}statCheck
{Function}onError
{Function} Callback function invoked in the case of an error before send.waitForTrailers
{boolean} Whentrue
, theHttp2Stream
will emit the'wantTrailers'
event after the finalDATA
frame has been sent.offset
{number} The offset position at which to begin reading.length
{number} The amount of data from the fd to send.
Sends a regular file as the response. The path
must specify a regular file
or an 'error'
event will be emitted on the Http2Stream
object.
When used, the Http2Stream
object’s Duplex
interface will be closed
automatically.
The optional options.statCheck
function may be specified to give user code
an opportunity to set additional content headers based on the fs.Stat
details
of the given file:
If an error occurs while attempting to read the file data, the Http2Stream
will be closed using an RST_STREAM
frame using the standard INTERNAL_ERROR
code. If the onError
callback is defined, then it will be called. Otherwise
the stream will be destroyed.
Example using a file path:
const http2 = require('http2');
const server = http2.createServer();
server.on('stream', (stream) => {
function statCheck(stat, headers) {
headers['last-modified'] = stat.mtime.toUTCString();
}
function onError(err) {
if (err.code === 'ENOENT') {
stream.respond({ ':status': 404 });
} else {
stream.respond({ ':status': 500 });
}
stream.end();
}
stream.respondWithFile('/some/file',
{ 'content-type': 'text/plain; charset=utf-8' },
{ statCheck, onError });
});
The options.statCheck
function may also be used to cancel the send operation
by returning false
. For instance, a conditional request may check the stat
results to determine if the file has been modified to return an appropriate
304
response:
const http2 = require('http2');
const server = http2.createServer();
server.on('stream', (stream) => {
function statCheck(stat, headers) {
// Check the stat here...
stream.respond({ ':status': 304 });
return false; // Cancel the send operation
}
stream.respondWithFile('/some/file',
{ 'content-type': 'text/plain; charset=utf-8' },
{ statCheck });
});
The content-length
header field will be automatically set.
The offset
and length
options may be used to limit the response to a
specific range subset. This can be used, for instance, to support HTTP Range
requests.
The options.onError
function may also be used to handle all the errors
that could happen before the delivery of the file is initiated. The
default behavior is to destroy the stream.
When the options.waitForTrailers
option is set, the 'wantTrailers'
event
will be emitted immediately after queuing the last chunk of payload data to be
sent. The http2stream.sendTrailers()
method can then be used to sent trailing
header fields to the peer.
When options.waitForTrailers
is set, the Http2Stream
will not automatically
close when the final DATA
frame is transmitted. User code must call either
http2stream.sendTrailers()
or http2stream.close()
to close the
Http2Stream
.
const http2 = require('http2');
const server = http2.createServer();
server.on('stream', (stream) => {
stream.respondWithFile('/some/file',
{ 'content-type': 'text/plain; charset=utf-8' },
{ waitForTrailers: true });
stream.on('wantTrailers', () => {
stream.sendTrailers({ ABC: 'some value to send' });
});
});