http2stream.respondWithFile(path[, headers[, options]])

• path <string> | <Buffer> | <URL>
• headers HTTP/2 头对象
• options <Object>
  • statCheck <Function>
  • onError <Function> 在发送前发生错误时调用的回调函数。
  • waitForTrailers <boolean> 当设置为 true 时，Http2Stream 会在最后一个 DATA 帧发送后触发 'wantTrailers' 事件。
  • offset <number> 开始读取的偏移位置。
  • length <number> 要从文件描述符发送的数据量。

将普通文件作为响应发送。path 必须指定一个普通文件，否则将在 Http2Stream 对象上触发 'error' 事件。

【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.】

使用时，Http2Stream 对象的 Duplex 接口将会被自动关闭。

【When used, the Http2Stream object's Duplex interface will be closed automatically.】

可以指定可选的 options.statCheck 函数，让用户代码有机会根据给定文件的 fs.Stat 详细信息设置额外的内容头：

【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:】

如果在尝试读取文件数据时发生错误，Http2Stream 将使用 RST_STREAM 帧关闭，并使用标准的 INTERNAL_ERROR 代码。如果定义了 onError 回调，则会调用该回调。否则，流将被销毁。

【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:】

import { createServer } from 'node:http2';
const server = 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 });
});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 });
});拷贝

options.statCheck 函数也可以通过返回 false 来取消发送操作。例如，条件请求可以检查 stat 结果，以确定文件是否已被修改，从而返回适当的 304 响应：

【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:】

import { createServer } from 'node:http2';
const server = 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 });
});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 });
});拷贝

content-length 头字段将会自动设置。

【The content-length header field will be automatically set.】

offset 和 length 选项可用于将响应限制在特定范围的子集。例如，这可以用于支持 HTTP 范围请求。

【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.】

options.onError 函数也可以用来处理在文件传输开始之前可能发生的所有错误。默认行为是销毁流。

【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.】

当设置 options.waitForTrailers 选项时，在将要发送的最后一块负载数据入队之后，将立即触发 'wantTrailers' 事件。然后可以使用 http2stream.sendTrailers() 方法向对端发送尾部头字段。

【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.】

当设置 options.waitForTrailers 时，Http2Stream 在发送最后一个 DATA 帧后不会自动关闭。用户代码必须调用 http2stream.sendTrailers() 或 http2stream.close() 来关闭 Http2Stream。

【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.】

import { createServer } from 'node:http2';
const server = 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' });
  });
});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' });
  });
});拷贝