Usage in Deno
import { type ServerHttp2Stream } from "node:http2";
headersSent: boolean
True if headers were sent, false otherwise (read-only).
pushAllowed: boolean
Read-only property mapped to the SETTINGS_ENABLE_PUSH
flag of the remote
client's most recent SETTINGS
frame. Will be true
if the remote peer
accepts push streams, false
otherwise. Settings are the same for everyHttp2Stream
in the same Http2Session
.
additionalHeaders(headers: OutgoingHttpHeaders): void
Sends an additional informational HEADERS
frame to the connected HTTP/2 peer.
pushStream(headers: OutgoingHttpHeaders,callback?: () => void,): void
Initiates a push stream. The callback is invoked with the new Http2Stream
instance created for the push stream passed as the second argument, or anError
passed as the first argument.
const http2 = require('node:http2'); const server = http2.createServer(); server.on('stream', (stream) => { stream.respond({ ':status': 200 }); stream.pushStream({ ':path': '/' }, (err, pushStream, headers) => { if (err) throw err; pushStream.respond({ ':status': 200 }); pushStream.end('some pushed data'); }); stream.end('some data'); });
Setting the weight of a push stream is not allowed in the HEADERS
frame. Pass
a weight
value to http2stream.priority
with the silent
option set totrue
to enable server-side bandwidth balancing between concurrent streams.
Calling http2stream.pushStream()
from within a pushed stream is not permitted
and will throw an error.
pushStream(): void
respond(headers?: OutgoingHttpHeaders,options?: ServerStreamResponseOptions,): void
const http2 = require('node:http2'); const server = http2.createServer(); server.on('stream', (stream) => { stream.respond({ ':status': 200 }); stream.end('some data'); });
Initiates a response. 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 eitherhttp2stream.sendTrailers()
or http2stream.close()
to close theHttp2Stream
.
const http2 = require('node:http2'); const server = http2.createServer(); server.on('stream', (stream) => { stream.respond({ ':status': 200 }, { waitForTrailers: true }); stream.on('wantTrailers', () => { stream.sendTrailers({ ABC: 'some value to send' }); }); stream.end('some data'); });
respondWithFD(fd: number | fs.promises.FileHandle,headers?: OutgoingHttpHeaders,options?: ServerStreamFileResponseOptions,): void
Initiates a response whose data is read from the given file descriptor. No
validation is performed on the given file descriptor. If an error occurs while
attempting to read data using the file descriptor, the Http2Stream
will be
closed using an RST_STREAM
frame using the standard INTERNAL_ERROR
code.
When used, the Http2Stream
object's Duplex
interface will be closed
automatically.
const http2 = require('node:http2'); const fs = require('node:fs'); const server = http2.createServer(); server.on('stream', (stream) => { const fd = fs.openSync('/some/file', 'r'); const stat = fs.fstatSync(fd); const headers = { 'content-length': stat.size, 'last-modified': stat.mtime.toUTCString(), 'content-type': 'text/plain; charset=utf-8', }; stream.respondWithFD(fd, headers); stream.on('close', () => fs.closeSync(fd)); });
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 fd. If the statCheck
function is provided, thehttp2stream.respondWithFD()
method will perform an fs.fstat()
call to
collect details on the provided file descriptor.
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 file descriptor or FileHandle
is not closed when the stream is closed,
so it will need to be closed manually once it is no longer needed.
Using the same file descriptor concurrently for multiple streams
is not supported and may result in data loss. Re-using a file descriptor
after a stream has finished is supported.
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 eitherhttp2stream.sendTrailers()
or http2stream.close()
to close theHttp2Stream
.
const http2 = require('node:http2'); const fs = require('node:fs'); const server = http2.createServer(); server.on('stream', (stream) => { const fd = fs.openSync('/some/file', 'r'); const stat = fs.fstatSync(fd); const headers = { 'content-length': stat.size, 'last-modified': stat.mtime.toUTCString(), 'content-type': 'text/plain; charset=utf-8', }; stream.respondWithFD(fd, headers, { waitForTrailers: true }); stream.on('wantTrailers', () => { stream.sendTrailers({ ABC: 'some value to send' }); }); stream.on('close', () => fs.closeSync(fd)); });
respondWithFile(): void
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('node:http2'); const server = http2.createServer(); server.on('stream', (stream) => { function statCheck(stat, headers) { headers['last-modified'] = stat.mtime.toUTCString(); } function onError(err) { // stream.respond() can throw if the stream has been destroyed by // the other side. try { if (err.code === 'ENOENT') { stream.respond({ ':status': 404 }); } else { stream.respond({ ':status': 500 }); } } catch (err) { // Perform actual error handling. console.error(err); } 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 appropriate304
response:
const http2 = require('node: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 eitherhttp2stream.sendTrailers()
or http2stream.close()
to close theHttp2Stream
.
const http2 = require('node: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' }); }); });