Unexposed graceful server causes integration issues

[awfm9]

First, let me applaud you for great work on version 3 of echo. I like the API changes and the overall feel to it a lot better.

The issue I'm posting about is a new one, however; I was actually just about to build my own wrapper around v2 for graceful shutdowns when I saw you added the graceful library. Unfortunately, you don't expose any of the graceful parameters. In particular, the fact that the NoSignalHandling is not available creates an issue for us, because the webserver will now catch our signals.

I think echo can still do a better job at being a minimalist toolbox that fits into the users' applications, rather than the other way around. If anyone has an idea about a nice approach to this, I could work on a PR.

[vishr]

Thanks for reporting.

Related issue #752

Ideas are welcome.

/cc @Anon-Penguin

[mathvav]

umMMMmm letmethink.

The core issue here is we are building for two different versions of Go, so without some weird tricks (build tags, global variables, etc.), it's hard to build for both versions.

I don't particularly think that Go's version of Graceful would be much better than the original Graceful (disclaimer: I haven't yet seen the proposed API for Go's version), and maintaining two libraries seems unnecessarily complex for something as simple as clean shutdown.

If you disagree, we can start talking solutions. Unless Go supports conditional builds for version (like it does for OS), there's nothing we can do without making it more complex. It'd likely be in the form of an interface from an external package, similar to fasthttp's implementation in v2.

[ansel1]

Two things:

1. It's fairly straightforward to build alternate implementation with build tags referencing go versions. Implement one in a *.go file with:

   // +build go1.8

and the other in a *.go file with:

// +build !go1.8

This would be a good approach for switching the internal graceful shutdown implementation between graceful and native.

2. if callers need more control, they can make their own http.Server and use what ever graceful shutdown package they want, and just treat echo as a handler. This is a simple escape-hatch. Don't see the need to add complexity to echo's surface for this.

[mathvav]

1. It's fairly straightforward to build alternate implementation with build tags referencing go versions. Implement one in a *.go file with:

Thanks! I thought I've seen that around before, but I was looking for documentation and apparently wasn't able to Google properly (ironically about a language made by Google).

2. I swear starting the server with Echo directly does some extra magic besides Graceful that you would have to do manually. EDIT: read code; I guess not. This is a viable solution.

So, options:

1. Add slight complexity for the sake of a more intuitive workflow. Add a note somewhere in the docs that would be easy to find for the power users who need the parts of Graceful we deem unnecessary.
2. Leave API as-is. Add a note somewhere in the docs, at least somewhat prominently placed. Make several examples of how to use Graceful.

I like option one because it isn't forcing anyone to add anything new and it's not restricting anyone; however, it is a lot more clean and intuitive. I do admit that may be biased towards my current usage of echo, so it's not important to me as long as something is added to the docs (because 2 separate issues == probably many more people who have given up). :)

[ansel1]

I'd lean toward not exposing the graceful package. Keep it hidden.

• If echo exposes graceful, graceful becomes part of echo's API surface, and echo's backward compatibility becomes dependent on a 3rd party lib
• I'd expect echo to switch over to the native graceful support when widely available
• If power users want to use uncommon or advanced graceful features, it's probably easier for them to just set it up themselves. An example in the docs of how to use echo has a handler for a custom http server should be sufficient. Especially in echov3 (it's more straightfoward than echov2, where *echo.Echo was not an http.Handler)
• Eventually, if some graceful options are tweaked by most users, and can be easily normalized to other graceful shutdown libraries, then consider exposing just those options to Echo's surface. In other words, keep Echo simply by requiring a high bar of convenience value before elevating config options to the API surface. This should maintain Echo's core strengths: simple, batteries included, but plays well with others.

[vishr]

I agree to @ansel1. This can be easily achieved using Echo has http.Server handler. I will update the docs to mention it.

[awfm9]

An example in the documents would indeed be nice, but it's good to hear there is a way around it. I will look at it again for our use case tomorrow.

I do not completely agree with the conclusion, though. As it is now, there is too much implied behaviour in my opinion. I personally consider catching signals inside a library by default highly questionable.

[vishr]

Similar issues are being raised more often, what's your opinion about separating out graceful from Echo? We can update the graceful shutdown examples as they were earlier.

/cc @ansel1 @Anon-Penguin

[ansel1]

If there's generally pushback, I'd remove the integrated graceful. It's so trivial for the developer to add it themselves, especially now that echo v3 is just an http.Handler again.