Motivation

Athens makes a number of decisions in a request's lifecycle. An administrator might want to hook into some of the functionality for automation or other reasons.

We already have one validation hook which can be used to block incoming requests.

However, there are more events that an Athens admin might be interested in automating:

1. An event triggered when a new module is stored so they can do their own indexing.

2. An event triggered when a module is blocked so they can know who is still requesting a certain module.

3. An event triggered when a checksum request is made to a NoSumPattern so they know the rate of misconfiguration amongst their employees.

Proposal

I propose that we add an EventHook that an Athens admin can use to be able to hook into the Athens lifecycle.

The EventHook is a URL that Athens will make POST requests to for various events. We can start small and expand based on need for these events.

An Athens admin should be able to know (whether through documentation, code, or both) what events will be sent to their URL and what the shape of the data will look like.

Unlike the ValidationHook, the EventHook will not fail if the POST request returned an error. However, it should wait on the request to finish and log if the response is not 200.

Note that since the EventHook is blocking, it is the implementer's responsibility to make sure the hook does not cause time outs. For example, the hook server can accept requests and forward to a message broker like RabbitMQ or Kafka to process requests asynchronously.

Implementation

However the implementation might be, we should be able to provide an easy way for users to know what events are available and what the payload looks like.

Twirp and gRPC are natural fits here where we can automate client/server communication as well as documentation. However, they require additional build steps and tooling which could complicate the development process.

For simplicity we can use pure "net/http" and maintain our own documentation and client server code. I like this idea though it's a bit more work to maintain.

However, in both cases the user will just be able to import a package and get started so both will provide a good end user experience.

One thing to be aware of is that our semantic versioning so far has been based on the "server protocol" and not our code. Therefore, if we expect our users to import a library to use a hook, then our semver should take into account code-compatibility as well. One thing we can do is put the code in another repo to keep Athens semver based server protocol only. Or we can put the code in Athens and keep the semver promise on code optional.