A new receiver: HTTPReceiver (eventually the default)

[aoberoi]

The problem

Currently, Bolt ships with one implementation of the Receiver interface called ExpressReceiver. It works great for lots of developers, but there are some issues we've heard about:

• Developers might not care for express in their app at all. It's an implementation detail.
  • Using express makes Bolt's internals a little easier to write, but it comes with quite a few dependencies and opinions. Those dependencies matter quite a bit for apps bound to run on serverless platforms (like AWS Lambda) because it impacts load time (and cold start time).
• Developers want to compose their Bolt app into a larger web app, often times using a different framework (such as koa).

Our current recommendation for developers facing the issues above is to implement their own Receiver. But that comes with new issues:

• It takes a lot of code to write a new Receiver, and often times its repeated code that is copied and pasted from ExpressReceiver.
  • Copied and pasted code becomes tech debt that the developer has to pay for. Bug fixes and new features in ExpressReceiver are not automatically inherited unless the developer pays attention to every release and copies and pastes all the changes.

Lastly, developers want access to more context from the HTTP requests and response. However, Bolt was built to support Receivers that do not interface directly with HTTP. For example, it should be possible to built a LambdaReceiver that doesn't use an HTTP server at all, which receives data from a function call. Another example is a TestReceiver which also doesn't start an HTTP server, and receives data loaded from fixtures from test scenarios. This list goes on. App developers should expect that they can swap one receiver for another and their app to continue working. Therefore adding context from HTTP in the current state, without a a larger plan, would allow and encourage developers to write more coupled, less reusable, code. This would undermine the potential future value of a vibrant ecosystem of shared code (receivers, middleware, etc).

Our solution

We will build a more generalized HTTPReceiver that has no dependency on express.

The HTTPReceiver will have its own built in server (just like ExpressReceiver) that can be .start()ed easily. But alternatively the receiver can be used as a listener for the request event - a common low-level interface that can easily be used with most existing web frameworks.

The goal is nobody should want to write another HTTP-specific receiver because this one is flexible enough to work for everyone's needs. If we achieve this goal, the issues derived from copying and pasting the code from the ExpressReceiver are also solved.

We will also generalize the OAuth implementation so that it can easily be started as part of the HTTPReceiver or without it. We have not yet designed what an API for what this might look like. It could be an object which has its own built-in HTTP server that can be started, or be used as a request listener. In the worst case, OAuth is supported in the HTTPReceiver, but when using any other receiver developers need to use the @slack/oauth API directly.

The ReceiverEvent interface will be extended to carry receiver-specific data, such as HTTP headers, AWS Lambda context, test scenario data, etc. The exact shape of the change has not been decided yet. Although extending the interface with receiver-specific data can lead to tightly coupled code and later a fragmented ecosystem, we believe by generalizing the receiver to the point where nobody would want to implement another HTTP one sufficiently mitigates the risk of too many similar receivers putting similar data (like HTTP headers) in different places in different formats. We'd like to make the separation between the Slack data and the receiver-specific context very obvious, and discourage people from using the latter in reusable code.

Lastly, we will start working on this change soon. It might be released in a 2.x minor release, but it will surely arrive by 3.0. And on 3.0, we'd like to make HTTPReceiver the default.

Requirements (place an x in each of the [ ])

• [x] I've read and understood the Contributing guidelines and have done my best effort to follow them.
• [x] I've read and agree to the Code of Conduct.
• [x] I've searched for any related issues and avoided creating a duplicate issue.

[aoberoi]

These are the parts we'd still like to discuss, and nail down before implementation begins:

• How will the ReceiverEvent interface change (or be extended)?
• How will the OAuth implementation be factored out of the ExpressReceiver?

[seratch]

759 looks related to the part:

The ReceiverEvent interface will be extended to carry receiver-specific data, such as HTTP headers, AWS Lambda context, test scenario data, etc. The exact shape of the change has not been decided yet.

@aoberoi @stevengill Do you already have design ideas for this in your mind?

[stevengill]

@seratch the plan was to break that out of this issue into its own issue and do it after the 3.0 release. I think we can safely use #759 as the issue now.