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

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

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

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

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

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

使用文件路径的示例：

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) {
    // 如果流已被另一方销毁，
    // 则 stream.respond() 可能抛出错误。
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 });
      } else {
        stream.respond({ ':status': 500 });
      }
    } catch (err) {
      // 执行实际的错误处理。
      console.log(err);
    }
    stream.end();
  }

  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck, onError });
});

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

const http2 = require('http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    // 检查这里的统计数据...
    stream.respond({ ':status': 304 });
    return false; // 取消发送操作
  }
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck });
});

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

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

options.onError 函数也可用于处理在启动文件传递之前可能发生的所有错误。 默认行为是销毁流。

当设置了 options.waitForTrailers 选项时，'wantTrailers' 事件将在将要发送的最后一块有效负载数据排队后立即发出。 然后可以使用 http2stream.sendTrailers() 方法将尾随标头字段发送到对等方。

当设置了 options.waitForTrailers，则传输完最后的 DATA 帧时，Http2Stream 不会自动关闭。 用户代码必须调用 http2stream.sendTrailers() 或 http2stream.close() 来关闭 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' });
  });
});

• 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> When true, the Http2Stream will emit the 'wantTrailers' event after the final DATA 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) {
    // 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.log(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 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' });
  });
});