RFC: Http Reaction

[danielgerlag]

Abstract

This is a proposal for a new Reaction to invoke an Http request for each change diff produced by a continuous query. This RFC aims to gather feedback on the proposed design and configuration for the Http Reaction.

Description

This Reaction enables the user to craft Http calls that will be invoked when query result set changes occur.

The URL of the request and the payload can be constructed from a handlebars template.

For example, the following configuration will post to https://api.github.com/repos/{{repo}}/issues/{{issue_number}}/comments, where the variables are sourced from the result set item that was added. The JSON body of the request is also constructed using handlebars.

kind: Reaction
apiVersion: v1
name: test-http
spec:
  kind: Http
  properties:
    baseUrl: "https://api.github.com"
    token: xxxx
  queries:
    issue-comments: >
      added:
        url: "/repos/{{after.repo}}/issues/{{after.issue_number}}/comments"
        method: "POST"
        body: > 
          {
            "body": "Hello! @{{after.creator}}"
          }
        headers:
          X-GitHub-Api-Version: "2022-11-28"
      updated: 
            ....
      deleted: 
            ....

Configuration Schema

Reaction-Level configuration

• baseUrl: The base URL to use for all Http requests that will be made. eg. https://api.github.com. Query specific requests will build on this URL by adding a path,
• token (optional): The bearer token to use for authentication.

Per-Query Configuration

The following 3 sections can be included per query

• added (optional): Describes the Http request for items added to the result set.
• updated (optional): Describes the Http request for items updated the result set.
• deleted (optional): Describes the Http request for items deleted from the result set.

Each of these will describe the Http request to make for added, updated, and deleted changes respectively.
The configuration for each of these is as follows:

• url: The path to append to the baseUrl for the request. This can be a handlebars template, where you can merge data from the result set diff. Added results will have an after field that contains an object that is the added item, updated results will have before and after objects, and deleted results will only have a before object. For example: /repos/{{after.repo}}/issues/{{after.issue_number}}/comments
• method: The Http method to use, PUT, POST, GET, DELETE, etc.
• body: The body of the request. This can be a handlebars template, where you can merge data from the result set diff. Added results will have an after field that contains an object that is the added item, updated results will have before and after objects, and deleted results will only have a before object.
• headers: An object containing any additional custom headers to include in the Http request.

Deferred functionality

The initial version is not intended to be production ready, but only to enable the concept of Http reactions to be used in proof-of-concept projects and demonstrations.

Authentication support

For the initial version we will support bearer token authentication for the Http requests. Subsequent versions will include additional authentication mechanisms.

Resiliency

The initial version will not provide any resiliency strategies for when Http calls fail. This functionality will be added in subsequent versions.

Testing ground for templated messages

This Reaction will be the first to employ a templating engine to construct a custom request body / message for downstream consumers. If this proves successful, our existing message producing reactions could be extended to support custom templated message payloads using the same implementation.