Add event stream

[samdbmg]

Details

Adds an ADR proposing a couple of possible approaches to an event notification stream, along with a proposal about what the message format might look like.

I think Option 3 (telemetry) probably doesn't make sense, but I'd appreciate thoughts on Option 1 (specify notification mechanism) vs Option 2 (leave it up to implementations). For now I've done the implementation for Option 2, but Option 1 is a build on that.

Also, it might seem like AsyncAPI is the better fit for describing this, but it's quite high-friction for both HTTP webhooks and AWS EventBridge, which are the two possible implementations we've previously talked about, so using OpenAPI seemed the better approach for a spec.

I'd also appreciate thoughts on how Sources should work - see comments in the OpenAPI doc.

Pivotal Story (if relevant)

Story URL: https://www.pivotaltracker.com/story/show/187071067

Related PRs

N/A

Submitter PR Checks

(tick as appropriate)

• PR completes task/fixes bug
• API version has been incremented if necessary
• ADR status has been updated, and ADR implementation has been recorded
• Documentation updated (README, etc.)
• PR added to Pivotal story (if relevant)
• Follow-up stories added to Pivotal

Reviewer PR Checks

(tick as appropriate)

• PR completes task/fixes bug
• Design makes sense, and fits with our current code base
• Code is easy to follow
• PR size is sensible
• Commit history is sensible and tidy

Info on PRs

The checks above are guidelines. They don't all have to be ticked, but they should all have been considered.

[philipnbbc]

Some comments inline and otherwise LGTM.

I agree that Option 1 or 2 makes sense over Option 3. I think the structure of the message format will probably change for different delivery mechanisms and so I see it's more about getting maximum commonality between implementations. Similar to the HTTP object store choice, maybe a message format plus a implementation would help get some form consensus of what is needed? Something like Option 2 plus a simple example implementation, but not going as far as Option 1 just yet.

[samdbmg]

Similar to the HTTP object store choice, maybe a message format plus a implementation would help get some form consensus of what is needed? Something like Option 2 plus a simple example implementation, but not going as far as Option 1 just yet.

How's 8dcf44d for that?
Downside is it adds a bit of complexity to the API and it's a bit difficult to specify adequately in schema without being unduly prescriptive. But I think making it optional mitigates that a bit? Plus webhooks come with quite a few additional security considerations - I found https://webhooks.fyi/best-practices/webhook-providers#implement-security-on-egress-communication to be interesting reading.

[philipnbbc]

Similar to the HTTP object store choice, maybe a message format plus a implementation would help get some form consensus of what is needed? Something like Option 2 plus a simple example implementation, but not going as far as Option 1 just yet.

How's 8dcf44d for that? Downside is it adds a bit of complexity to the API and it's a bit difficult to specify adequately in schema without being unduly prescriptive. But I think making it optional mitigates that a bit? Plus webhooks come with quite a few additional security considerations - I found https://webhooks.fyi/best-practices/webhook-providers#implement-security-on-egress-communication to be interesting reading.

I think that looks great, thanks. I think it's a good starting option to have.