Shut down gracefully, and clean up when starting up fails

[digitalresistor]

Stopping a waitress server drops whatever is in flight on the floor. The main loop is torn down the moment the interrupt arrives, but the task threads hand their output back to that loop and use the trigger to wake it up — so anything not already written to the socket is lost, and a task thread parked on outbuf_lock waiting for the loop to drain a buffer never wakes up again.

Interrupting a 4MB response on main:

received 327356 of 4194447 bytes                                        <- truncated
1 thread(s) still running                                               <- wedged forever
ResourceWarning: unclosed file <waitress.wasyncore.file_wrapper ...>    <- the trigger's pipe
ResourceWarning: unclosed <socket.socket fd=6, ...>                     <- listening socket
ResourceWarning: unclosed <socket.socket fd=7, ...>                     <- client socket

Same thing on this branch: full 4,194,448 bytes, stderr clean, and it exits faster because nothing is left wedged.

This started as a fix for #480 so that #490 could land, and grew to cover the shutdown path it exposed.

Graceful shutdown

Follows the steps from #269 (comment) and @mmerickel's list in #198:

1. close the listening sockets, so the port is released and no new connections arrive;
2. stop reading new requests off the channels that are still open (new HTTPChannel.draining);
3. keep running the main loop so requests already being serviced get answered;
4. close the connections as they finish;
5. only then stop the worker threads and tear down the trigger.

Exposed as server.graceful_shutdown(). run() uses it on SIGINT/SystemExit, and a second interrupt during the drain gives up immediately, as discussed with @viktordick in #198.

Closes #198, closes #264.

shutdown_timeout — closes #134

New adjustment, default 5, 0 to tear everything down immediately. Bounds the drain, and replaces the timeout that was hardcoded in ThreadedTaskDispatcher.shutdown(). Wired through waitress-serve and documented.

start() / stop() — closes #290

server = create_server(app, host="127.0.0.1", port=0)
server.start()
url = f"http://{server.effective_host}:{server.effective_port}/"
...
server.stop()

stop() signals the main loop through the trigger instead of closing things underneath it from another thread, so it is safe to call from anywhere — including from within the WSGI application, where it deliberately does not block (waiting there would deadlock on the request making the call). This is what WebTest's StopableWSGIServer has to work around today, and binding to port 0 and reading back effective_port avoids the free-port race @evandrocoan raised in #290.

Cleanup on startup failure — closes #480, closes #402

• Worker threads are no longer started until every socket has been bound, so a failed bind doesn't strand a ThreadedTaskDispatcher nobody has a reference to.
• A listener that bound successfully is now closed if a later one fails, instead of being left in the socket map.
• BaseWSGIServer.__init__ cleans up after itself — trigger, socket, map entry, dispatcher.
• BaseWSGIServer.close() shuts down the task dispatcher and closes the connections that are still open, matching MultiSocketServer.close(). An ownership flag keeps one listener closing from killing a MultiSocketServer's shared thread pool.

With #480 fixed, the socket leak that #490 ran into is gone — its test_port_bind_failure_logging no longer leaves anything behind. I left the bind logging itself out of this PR so it can land on its own.

Also

pull_trigger() is a no-op once the trigger is closed. A task thread finishing as the server went away could previously write to a closed file descriptor — one that may well have been handed out to something else by then.

Notes for review

• Tests: 822 passing locally, 100% coverage, black/isort/sphinx -W clean. The new coverage includes end-to-end tests over real sockets that assert a large in-flight response survives shutdown intact. CI is green across the full matrix; the 29 new tests run everywhere except the two bind-failure ones, which are skipped on Windows because SO_REUSEADDR there lets you rebind a port that is already being listened on.
• shutdown_timeout is marked .. versionadded:: 3.1.0. pyproject.toml is deliberately left at 3.0.2 and CHANGES.txt at Unreleased, since this repo bumps the version as a separate release step.
• Keeping this as a single commit rather than splitting it per issue.

[kgaughan]

I see nothing blocking merging this, though I think the error message fix is worth adding.

[kgaughan]

This is more something that bugged me about #215, and I know changing this would mean a change in behaviour so this PR probably isn't the place to deal with it, but shouldn't the path with Unix sockets when adj.unix_socket be mutually exclusive with adj.sockets not being empty, just like TCP sockets are? It'd simplify the logic a tad as a benefit to something more like this:

try:
    if not adj.sockets:
        if adj.unix_socket and hasattr(socket, "AF_UNIX"):
            ...
        for sockinfo in adj.listen:
            ...
    for sock in adj.sockets:
        ...

[kgaughan]

Missed unix_socket:

Suggested change

	"There are no sockets to listen on, both 'listen' and 'sockets' "
	"are empty."
	"There are no sockets to listen on: 'unix_socket', 'listen', "
	"and 'sockets' are all empty."