Expose stoppable.increment and stoppable.decrement

[snakamura]

I'm using stoppable with WebSocket. Since stoppable itself doesn't handle WebSocket (and it's impossible for stoppable itself to know when it can shutdown), I manually manipulate server._pendingSockets and close connections in my code. But I'm not comfortable depending on private APIs.

This patch exposes two new methods (stoppable.increment and stoppable.decrement) from a server. With these methods, I can tell stoppable from my code when is appropriate to shutdown.

[ronkorving]

What does "a new counter" mean? The new "current count" of the socket?

[snakamura]

Yes, the incremented pending count of the specified socket.

[ronkorving]

Perhaps rephrase to "This method returns the new count." or something like that? Apparently I guessed right, but it really was a guess :)

[snakamura]

Thank you for pointing it out. Updated.

[snakamura]

@hunterloftis Is there any chance for this PR to be merged?

[boneskull]

This will need some tests, but also: can you please explain more about why this change is necessary?

[boneskull]

This will need some tests, but also: can you please explain more about why this change is necessary?

[snakamura]

@boneskull With normal HTTP requests, stoppable can determine whether a server is processing requests or not. I mean, it can think a server starts processing after request event is fired on the server, and stops processing after finish event is fired on a socket. Stoppable can stop the server gracefully while it's not processing any requests by closing its socket.

On the other hand, when it comes to WebSocket, there are no clear definitions when a server is processing. For example, imagine you're designing an application using WebSocket, and decided a server sends two WebSocket messages when it receives one WebSocket message from a client. In this case, you don't want to shutdown the server after it sends the first message but before sending the second one. So it's up to an application if a server can be shutdown gracefully.

To tell stoppable whether it can stop the server gracefully, we need help from an application, hence these new APIs.

[Lewiscowles1986]

Note: if an application can hang the server unless correctly configured, I'd question the server design. It should be possible (using another codebase) to close the other connections separately, or just force quit the server after n seconds, which this lib says it supports.