diff options
author | James M Snell <jasnell@gmail.com> | 2020-07-02 22:44:57 +0300 |
---|---|---|
committer | James M Snell <jasnell@gmail.com> | 2020-07-06 00:17:33 +0300 |
commit | 7b062ca015d5a2545c9d66992c183c325d938a23 (patch) | |
tree | 8575c0b5ee9fc74a48b7d82d56ee8306b5f5b279 /doc/api/quic.md | |
parent | e4d369e96e0f75786c84dacb45f0a8790615b386 (diff) |
quic: refactor qlog handling
Because of the timing of qlog events emitted by ngtcp2, it
becomes difficult to handle those as events on the QuicSession
object because the final qlog entry is not emitted until the
ngtcp2_conn is freed, which can occur when the object is being
garbage collected (meaning, we a: can't call out to javascript
and b: don't have an object we can use to emit the event).
This refactors it into a QLogStream object that allows the
qlog data to be piped out using a separate Readable stream.
PR-URL: https://github.com/nodejs/node/pull/34160
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Diffstat (limited to 'doc/api/quic.md')
-rw-r--r-- | doc/api/quic.md | 45 |
1 files changed, 28 insertions, 17 deletions
diff --git a/doc/api/quic.md b/doc/api/quic.md index 42a8b756909..3667a05b394 100644 --- a/doc/api/quic.md +++ b/doc/api/quic.md @@ -274,7 +274,7 @@ added: REPLACEME * `maxStatelessResetsPerHost` {number} The maximum number of stateless resets that the `QuicSocket` is permitted to send per remote host. Default: `10`. - * `qlog` {boolean} Whether to emit ['qlog'][] events for incoming sessions. + * `qlog` {boolean} Whether to enable ['qlog'][] for incoming sessions. (For outgoing client sessions, set `client.qlog`.) Default: `false`. * `retryTokenTimeout` {number} The maximum number of *seconds* for retry token validation. Default: `10` seconds. @@ -633,20 +633,6 @@ The callback will be invoked with three arguments: The `'pathValidation'` event will be emitted multiple times. -#### Event: `'qlog'` -<!-- YAML -added: REPLACEME ---> - -* `jsonChunk` {string} A JSON fragment. - -Emitted if the `qlog: true` option was passed to `quicsocket.connect()` or -`net.createQuicSocket()` functions. - -The argument is a JSON fragment according to the [qlog standard][]. - -The `'qlog'` event will be emitted multiple times. - #### Event: `'secure'` <!-- YAML added: REPLACEME @@ -1044,6 +1030,19 @@ added: REPLACEME A `BigInt` representing the total number of `QuicStreams` initiated by the connected peer. +#### quicsession.qlog +<!-- YAML +added: REPLACEME +--> + +* Type: {stream.Readable} + +If `qlog` support is enabled for `QuicSession`, the `quicsession.qlog` property +provides a [`stream.Readable`][] that may be used to access the `qlog` event +data according to the [qlog standard][]. For client `QuicSessions`, the +`quicsession.qlog` property will be `undefined` untilt the `'qlog'` event +is emitted. + #### quicsession.remoteAddress <!-- YAML added: REPLACEME @@ -1183,6 +1182,17 @@ The `sessionTicket` and `remoteTransportParams` are useful when creating a new The `'sessionTicket'` event may be emitted multiple times. +#### Event: `'qlog'` +<!-- YAML +added: REPLACEME +--> + +The `'qlog'` event is emitted when the `QuicClientSession` is ready to begin +providing `qlog` event data. The callback is invoked with a single argument: + +* `qlog` {stream.Readable} A [`stream.Readable`][] that is also available using + the `quicsession.qlog` property. + #### Event: `'usePreferredAddress'` <!-- YAML added: REPLACEME @@ -1573,7 +1583,7 @@ added: REPLACEME transport parameters from a previously established session. These would have been provided as part of the `'sessionTicket'` event on a previous `QuicClientSession` object. - * `qlog` {boolean} Whether to emit ['qlog'][] events for this session. + * `qlog` {boolean} Whether to enable ['qlog'][] for this session. Default: `false`. * `requestOCSP` {boolean} If `true`, specifies that the OCSP status request extension will be added to the client hello and an `'OCSPResponse'` event @@ -2278,6 +2288,7 @@ added: REPLACEME Set to `true` if the `QuicStream` is unidirectional. [`crypto.getCurves()`]: crypto.html#crypto_crypto_getcurves +[`stream.Readable`]: #stream_class_stream_readable [`tls.DEFAULT_ECDH_CURVE`]: #tls_tls_default_ecdh_curve [`tls.getCiphers()`]: tls.html#tls_tls_getciphers [ALPN]: https://tools.ietf.org/html/rfc7301 @@ -2286,5 +2297,5 @@ Set to `true` if the `QuicStream` is unidirectional. [modifying the default cipher suite]: tls.html#tls_modifying_the_default_tls_cipher_suite [OpenSSL Options]: crypto.html#crypto_openssl_options [Perfect Forward Secrecy]: #tls_perfect_forward_secrecy -['qlog']: #quic_event_qlog +['qlog']: #quic_quicsession_qlog [qlog standard]: https://tools.ietf.org/id/draft-marx-qlog-event-definitions-quic-h3-00.html |