From 6f3ebb8787d2def925ac28a4a6b8c836e42e364d Mon Sep 17 00:00:00 2001 From: cjihrig Date: Sat, 6 Jul 2019 11:08:30 -0400 Subject: [PATCH] doc: clarify http2 server.close() behavior This commit is an attempt to clarify the behavior of HTTP2's server.close() method. Specifically, this makes it more clear that the server stops allowing new sessions although the callback may not be invoked for some time due to previously existing sessions. PR-URL: https://github.com/nodejs/node/pull/28581 Fixes: https://github.com/nodejs/node/issues/28214 Reviewed-By: Luigi Pinca Reviewed-By: Jiawen Geng Reviewed-By: Rich Trott --- doc/api/http2.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 6be7464cc6bf4e..e75618b9abe086 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -1748,11 +1748,14 @@ added: v8.4.0 --> * `callback` {Function} -Stops the server from accepting new connections. See [`net.Server.close()`][]. +Stops the server from establishing new sessions. This does not prevent new +request streams from being created due to the persistent nature of HTTP/2 +sessions. To gracefully shut down the server, call [`http2session.close()`] on +all active sessions. -This is not analogous to restricting new requests since HTTP/2 -connections are persistent. To achieve a similar graceful shutdown behavior, -consider also using [`http2session.close()`] on active sessions. +If `callback` is provided, it is not invoked until all active sessions have been +closed, although the server has already stopped allowing new sessions. See +[`net.Server.close()`][] for more details. #### server.setTimeout([msecs][, callback]) * `callback` {Function} -Stops the server from accepting new connections. See [`tls.Server.close()`][]. +Stops the server from establishing new sessions. This does not prevent new +request streams from being created due to the persistent nature of HTTP/2 +sessions. To gracefully shut down the server, call [`http2session.close()`] on +all active sessions. -This is not analogous to restricting new requests since HTTP/2 -connections are persistent. To achieve a similar graceful shutdown behavior, -consider also using [`http2session.close()`] on active sessions. +If `callback` is provided, it is not invoked until all active sessions have been +closed, although the server has already stopped allowing new sessions. See +[`tls.Server.close()`][] for more details. #### server.setTimeout([msecs][, callback])