httpcaddyfile: allow modules to customize listener wrappers

[disintegrator]

This changes grants modules the ability to customize the listener wrapppers by introducing a new server block pile called listener_wrappers.
For example directives can now return ConfigValues like so:

package custom

type CustomModule struct {}

func init() {
	caddy.RegisterModule(CustomModule{})
	httpcaddyfile.RegisterDirective("custom_listener", parseCaddyfile)
}

var (
	_ caddy.Module          = (*CustomModule)(nil)
	_ caddy.ListenerWrapper = (*CustomModule)(nil)
)

func (c *CustomModule) WrapListener(listener net.Listener) net.Listener {
	// omitted to keep the example short but you probably want to wrap this
	// incoming listener with your own customised one
	return listener
}

func parseCaddyfile(h httpcaddyfile.Helper) ([]httpcaddyfile.ConfigValue, error) {
	var mod CustomModule

	// initialize your custom module from by parsing the directive

	return []ConfigValue{{
		Class: "listener_wrapper",
		Value: &mod,
	}}
}

Closes #3394

[CLAassistant]

All committers have signed the CLA.

[disintegrator]

@mholt here's my attempt at allowing modules to add listener wrappers. I'm gonna to carry on with writing tests tomorrow - bit late in the UK :)

[mholt]

Really good for a first contribution!

Just a few personal preferences about line breaks is my only nit. :)

One thing to be careful of: listener wrappers apply at the server level. They don't translate well from Caddyfiles because Caddyfile server blocks are typically (but not always) scoped by a particular host and maybe even request path (and may even span multiple servers/listeners!), but listener wrappers happen at the layer underneath.

So a directive in one server block that adds a listener wrapper may also end up adding it for the other server blocks.

This should probably be reconciled either in the documentation for those directives or the Caddyfile adapter should make sure that duplicates aren't unintentionally added if a user adds a listener wrapper directive to multiple site blocks that actually are on the same listener. The problem of course is that it's almost impossible to tell which might be duplicates, implicitly...

Thoughts?

(Other than that, I'd be willing to merge this already.)

[mholt]

Thanks for the updates. LGTM.

I can merge this when you're ready. On the side, I'd still be interested in your take on how to handle the unintuitiveness I described above. Do you think it will be confusing? (We already have this problem with things like the tls directive, and it's manageable with decent error messages, but we still get a fair number of questions on the forum.)

[mholt]

@disintegrator Anything else on this? Any thoughts ^ ?

[mholt]

@disintegrator Do you still need this? I don't want to add code to the core that is unneeded...

[disintegrator]

All good for now @mholt. I'll close this PR until I'm able to resume the work.

[disintegrator]

sorry for my absence :/

[mholt]

No worries -- and no need to close this, in fact I'm going to reopen it if that's OK.

To clarify: I just wanted to make sure this PR does indeed do what you need. If so, I'll merge it -- if any further review is required though, I can hold off.