Guarantee return value of serve

[SabrinaJewson]

Motivation

Currently, serve and with_graceful_shutdown do not document anything about their return values. The type system says that both return io::Result<()>, but in context it is not obvious how this should be interpreted, and the user is left to guess.

As it happens, in the current implementation it is impossible for serve to ever return, and likewise with_graceful_shutdown will never error. It seems unlikely to me that we would want to change this behaviour, and so it would be useful if people could instead rely on it.

Alternatively, if we do plan on allowing serve to return or error in future, this fact should be documented, and it should be specified what action the user is expected to take in that scenario (quit the app? restart the server?).

Solution

This commit adds to the documentation a guarantee that Serve and WithGracefulShutdown are both infallible, that Serve never completes successfully, and that WithGracefulShutdown only completes after its signal future has finished.

It refactors the implementations of both to guarantee this fact in the type system as well.

Future Possibilities

Of course, it would be nice if serve would instead return ! and with_graceful_shutdown (), but that will have to wait for a breaking change.

[jplatte]

How much do you care about this being in v0.7.x? If you don't care so much, I'd like to (only) revisit this after #2479 (which I want to rebase soon) and actually implement the breaking change you mention in future possibilities if still possible and correct.

[SabrinaJewson]

Oh, I see! That would be very nice :)