From 30911157f6b186628ffc527b89b84eb10becda84 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 b015b3e84ae249..1022eeb913563a 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -1749,11 +1749,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])