events: Implement event system

[francislavoie]

See #4984 for contextual discussion and documentation.

Events currently emitted, along with their data fields:

• unhealthy when a reverse proxy backend goes down
  • host: The host address
• healthy when a reverse proxy backend comes back up
  • host: The host address
• cert_obtaining before a certificate is obtained or renewed - can be aborted
  • renewal: True if renewed an existing certificate, false otherwise
  • identifier: The domain or IP address
  • If renewal:
    • issuer: The name or unique string for the issuer of the cert
    • forced: Whether renewal is being forced (early renewal)
    • remaining: Time left before expiration
• cert_obtained after a certificate is obtained OR renewed
  • renewal: True if renewed an existing certificate, false otherwise
  • identifier: The domain or IP address
  • issuer: The name or unique string for the issuer of the cert
  • storage_key: Part of the key/path to find cert resource in storage
• cert_failed after a certificate obtain failed
  • renewal: True if renewed an existing certificate, false otherwise
  • identifier: The domain or IP address
  • issuer: The name or unique string for the issuer of the cert
  • storage_key: Part of the key/path to find cert resource in storage
  • error: The error value
• cert_ocsp_revoked when a certificate's new OCSP status is Revoked
  • subjects: The SANs/identifiers on the certificate
  • cert: The certificate value itself (don't modify it; TODO: might remove this)
  • reason: The revocation reason
  • revoked_at: Time when the certificate was revoked
• tls_get_certificate when GetCertificate is called during a TLS handshake
  • client_hello: The tls.ClientHelloInfo structure
• cached_managed_cert when a managed/automated certificate is loaded into memory
  • sans: the certificate SANs
• cached_unmanaged_cert when a manual certificate is loaded into memory
  • sans: the certificate SANs

One big question is whether to have distinct event names for obtaining a new certificate and renewing an existing one. (To the ACME protocol, they are exactly identical, no distinction is made.) We have the renewal field to distinguish the two cases if needed, but we figure most users will just want to listen to one event and then if they care they can use the data field to discern renewals from first-time certs.

[mholt]

Thanks for this. I'm also inventing an eventing system (say that 10x fast) in parallel, so we'll take ideas from both probably and make something awesome. Great start!

[mholt]

This branch is now being continued.

Please see #4984 for additional context and documentation

[mholt]

Will probably move the exec event handler plugin out into its own repo for now.

(There is rationale for this decision. No known security issues -- except perhaps an abundance of caution -- rather, just going to wait and see what demand there is for event handler plugins. Most users might end up writing their own anyway!)

[mholt]

After chatting in Slack, we've agreed this feature is ready to be merged in its experimental state. It will be iterated upon through time and production experience.

One lingering question is whether users will want to plug in event handler modules that don't need any configuration -- i.e. custom modules that should only subscribe to events. Right now there's not really an API for a module that only subscribes to events. Right now an App module is probably the best fit. But even then it has to appear in the configuration.

I'm not sure how much demand there will be for this, since right now all Caddy modules that are used appear in the configuration. So let's see what the requirements are and the feedback is over time and we can tune this. Because it is experimental we can make breaking changes (though we will try not to).

Thanks @francislavoie for making this possible and laying the groundwork!

[hevisko]

The next event handler that would be great to have, will be a webhook/call

my use case: opening port 80 incoming (and any other) firewall rule(s) only during the ACME authentication phase. The 3xx/4xx/5xx responses could be an early certification failure event, while the 2xx a continue with the cert_obtaining event.

[mholt]

@hevisko So basically, make an HTTP request? Sounds logical.