A lot of the docs don’t explain what a module does - for example:
> dns.providers.azure wraps the provider implementation as a Caddy module.
Well great what does the provider implementation do? It’s the same for all DNS and not so useful if I’m coming from Apache or Nginx. At least explain what I’ll be able to do with this module.
From http.handlers.push:
> http.handlers.push is a middleware for manipulating the request body.
That’s a bit generic - any examples? There’s a lot of ways to modify the request body so what can I do with this?
There are 2 http.authentication.providers.jwt - both unofficial and both with 0 documentation. There has to be some standards here, why link to blank docs from your site?
All-in-all it just feels meh. I like to read docs that’ll give me the technical ins and outs of every function with some examples ideally.
Microsoft does a decent job of this as does Postgres (and others but these two come to mind immediately). Envoy is pretty nice here too and Nginx close.
Re "dns.providers.azure", that's a third-party module, we don't maintain that. The documentation you see in the JSON docs is auto-generated from code comments (godoc) so it's the maintainer's responsibility to write good comments that can act as documentation.
Re "http.handlers.push", fair point, that one's lacking/misleading. But this is a feature that was just added to satisfy a specific need, then fell by the wayside. Mostly because now Chrome is removing support for Server Push, so we'll need to deprecate this feature, in favor of HTTP 103 Early Hints which is the effective replacement for it.
Also, in general, we tend to spend more effort on maintaining the Caddyfile docs than the JSON docs, because the large majority of users use the Caddyfile. See https://caddyserver.com/docs/caddyfile/directives/push for the push handler, complete with examples.
Re "http.authentication.providers.jwt", well again, I think that's an issue with the module's maintainer not sufficiently using godoc comments. The maintainer registered the module under two different module paths (renamed repo) so it caused a duplicate. We'll need to manually remove the duplicate from the database, I think. It might be because there's conflicting ones that no docs are shown (cause the backend which serves the API docs is confused, I dunno, it's a bug clearly, will need to dig deeper).
Another example that was tricky in Caddy: setting up access via either whitelisted ip, or basic_auth (aka apache satisfy-any).
Useful for example for staging environments, whitelisted from certain ips, but allowing access via user-name/password from other IPs and/or the Internet.
Pretty easy (if I understand what you're asking for):
@needsAuth not remote_ip private_ranges
basicauth @needsAuth {
user pass
}
This uses a named matcher[0] `@needsAuth` with the `not` and `remote_ip` matchers, to match all public IP ranges (change `private_ranges` to a list of CIDRs if you prefer), then applies that request matcher to the `basicauth` handler[1], and pass in user/pass pairs to it (passwords are bcrypt hashed).
If the user fails authentication, then they won't be able to get in, as you'd expect. But users inside your allowed IP ranges will get through without basicauth.
