bolt v4 #2254

filmaj · 2024-09-13T16:20:26Z

Summary

bolt-js v4 release PR. Breaking changes are planned for this release!

This PR is currently published under the 4.0.0-rc.4 version on npm. Feel free to give it a spin and give us feedback!

Breaking Changes

Middleware Type Changes

This one I'm particularly excited about! In bolt we have a set of Slack*MiddlewareArgs types: for events, shortcuts, commands, and so on. They 'wrap' the underlying event payloads with additional middleware-relevant bits like a next() method, a context object for devs to augment, and so on.

Many of these types, for example the SlackEventMiddlewareArgs type, previously used a conditional to sometimes define particular additional helper utilities on the middleware arguments. For example, the say utility, or tacking on a convenience message property for message-event-related payloads. This was problematic in practice in TypeScript situations, not just internally (this change fixes #2135) within the bolt codebase but for developers as well: when the payload was not of a type that required the extra utility, these properties would be required to exist on the middleware arguments but have a value of undefined. Those of us trying to build generic middleware utilities would have to deal with TS compilation errors and needing to liberally type-cast to avoid these conditional mismatches with undefined.

Instead, these MiddlewareArgs types now conditionally create a type intersection when appropriate in order to provide this conditional-utility-extension mechanism. In practice that looks something like:

type SomeMiddlewareArgs<EventType extends string = string> = {
  // some type in here
} & (EventType extends 'message'
  // If this is a message event, add a `message` property
  ? { message: EventFromType<EventType> }
  : unknown
)

With the above, now when a message payload is wrapped up into middleware arguments, it will contain an appropriate message property, whereas a non-message payload will be intersected with unknown - effectively a type "noop." No more e.g. say: undefined or message: undefined to deal with!

Other Breaking Changes

drops node v14 and v16 (are now EOL'ed)
express to v4->v5; ExpressReceiver users will be exposed to express v4 -> v5 breaking changes
- fixes package vulnerabilities with dependency "path-to-regexp" and "send" #2242
upgrades to @slack/socket-mode v2; SocketModeReceiver users who have attached custom event listeners to the public socketModeClient directly should read the v1 -> v2 migration guide in case the major upgrade could affect them
- fixes Socket mode: Unhandled event 'server explicit disconnect' in state 'connecting' #2225
upgrades @slack/web-api v7; all users should read the web-api v6->v7 migration guide to see what the scope of breaking changes the client within listeners is affected by
removed exported type: KnownKeys
@slack/types now exist under a named export types.
removed the SocketModeFunctions class that had a single static method on it and instead directly exposed the defaultProcessEventErrorHandler method from it.
the built-in middleware functions ignoreSelf and directMention now no longer must be invoked as a method in order to return middleware; instead they are middleware to be used directly. this lines up the API for these built-in middlewares to match the other builtins.
AWSReceiver's AwsEvent interface now models event payloads a bit differently; we now properly model AWS API Gateway v1 and v2 payloads separately.
- This would resolve Add support for Amazon API Gateway payload format version 2.0 (for HTTP API and Lambda function URLs) #2272
remove deprecated methods/modules/properties:
- OptionsRequest interface
- authed_users and authed_teams from event payload envelope
- render-html-for-install-path module
- verify and VerifyOptions from the verify-request module
- src/receivers/http-utils.ts module

Non-breaking Changes

try some cleanup and a bit of modernization in tsconfig.json
- since we do use fallthrough in switch statements, removed that from tsconfig.json; the alternative of using @ts-ignore comments in places where we do is dangerous, as non-fallthrough-in-switch type errors are also ignored from it
adds a type predicate for asserting a fulfilled vs. rejected promise (for use in array methods like map)
remove some unnecessary type casts in processEvent
expose the bundled @slack/web-api dependency under the webApi named export
dependency updates:
- upgrades raw-body to v3
- upgrades @slack/oauth to v3
- removes promise.allsettled since that is natively supported in node since v14
- moves @types/tsscmp to dev dependencies since that is not exposed to developers

TODO

add deprecations to Steps from Apps things
ci/tests: move to biome, v4 linter fixes #2259 prep a separate lint-passing PR to merge into this PR prior to acceptance (For ease of reviewing the major v4 changes)
Tested with the following samples:
Write a migration guide wiki; work in progress here: https://github.com/slackapi/bolt-js/wiki/Bolt-v3-%E2%80%90--v4-Migration-Guide
Do a pass through all the docs

Post-release TODO

update all examples and sample dependencies to use bolt v4

codecov · 2024-09-13T16:22:08Z

Codecov Report

Attention: Patch coverage is 95.06726% with 66 lines in your changes missing coverage. Please review.

Project coverage is 92.47%. Comparing base (1ebd657) to head (a954a40).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/App.ts	92.77%	18 Missing ⚠️
src/receivers/HTTPModuleFunctions.ts	91.14%	17 Missing ⚠️
src/receivers/HTTPReceiver.ts	81.08%	14 Missing ⚠️
src/Assistant.ts	92.85%	5 Missing ⚠️
src/receivers/AwsLambdaReceiver.ts	93.58%	5 Missing ⚠️
src/middleware/builtin.ts	97.05%	3 Missing and 1 partial ⚠️
src/AssistantThreadContextStore.ts	87.50%	1 Missing ⚠️
src/receivers/ExpressReceiver.ts	98.70%	1 Missing ⚠️
src/receivers/SocketModeReceiver.ts	97.36%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #2254       +/-   ##
===========================================
+ Coverage   81.21%   92.47%   +11.26%     
===========================================
  Files          21       36       +15     
  Lines        1799     7453     +5654     
  Branches      498      646      +148     
===========================================
+ Hits         1461     6892     +5431     
- Misses        218      553      +335     
+ Partials      120        8      -112

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

filmaj · 2024-09-27T18:09:54Z

src/middleware/builtin.ts

-  // Filter out any non-actions
-  if (action === undefined) {
-    return;
+export const onlyActions: Middleware<AnyMiddlewareArgs> = async (args) => {


Breaking change: no longer need to call this as onlyActions(), instead, it is a middleware itself and can be simply passed as onlyActions. The wrapping closure within was unnecessary. This lines it up with other, non-parameterized middleware in this module.

filmaj · 2024-09-27T18:10:30Z

src/middleware/builtin.ts

-  if (action === undefined) {
-    return;
+export const onlyActions: Middleware<AnyMiddlewareArgs> = async (args) => {
+  if ('action' in args && args.action) {


Instead of casting, in TS we should be using more of 'property' in object style checks and let TS do the type narrowing for us.

filmaj · 2024-09-27T18:11:06Z

src/middleware/builtin.ts

-  // Filter out any non-shortcuts
-  if (shortcut === undefined) {
-    return;
+export const onlyShortcuts: Middleware<AnyMiddlewareArgs> = async (args) => {


Another breaking change: this is a middleware, no need for extra internal closure.

filmaj · 2024-09-27T18:11:20Z

src/middleware/builtin.ts

-  // Filter out any non-commands
-  if (command === undefined) {
-    return;
+export const onlyCommands: Middleware<AnyMiddlewareArgs> = async (args) => {


Same deal! This is middleware, remove internal closure.

filmaj · 2024-09-27T18:11:32Z

src/middleware/builtin.ts

-  // Filter out any non-options requests
-  if (options === undefined) {
-    return;
+export const onlyOptions: Middleware<AnyMiddlewareArgs> = async (args) => {


Broken record: middleware, remove internal closure.

filmaj · 2024-09-27T18:11:49Z

src/middleware/builtin.ts

-  // Filter out any non-events
-  if (event === undefined) {
-    return;
+export const onlyEvents: Middleware<AnyMiddlewareArgs> = async (args) => {


You guessed it: middleware, 🔪 closure

filmaj · 2024-09-27T18:11:57Z

src/middleware/builtin.ts

-  // Filter out anything that doesn't have a view
-  if (view === undefined) {
-    return;
+export const onlyViewActions: Middleware<AnyMiddlewareArgs> = async (args) => {


💡 🧠 Big fan of it all!

filmaj · 2024-09-27T18:12:44Z

src/middleware/builtin.ts

-            return;
-          }
-        }
+export const ignoreSelf: Middleware<AnyMiddlewareArgs> = async (args) => {


Same: 🔪 internal closure since we don't use any of the outer function's parameters.

filmaj · 2024-09-27T18:13:15Z

src/middleware/builtin.ts

+    if (isMessageEventArgs(args)) {
+      const { message } = args;
+      // Look for an event that is identified as a bot message from the same bot ID as this app, and return to skip
+      if (message.subtype === 'bot_message' && message.bot_id === botId) {


The combination of cleaning up the middleware types and use of type predicates lets us clean up the type casting and simplify the logic in this method ❤️

filmaj · 2024-09-27T18:13:59Z

src/middleware/builtin.ts

-  | GlobalShortcut
-  | InteractiveMessageSuggestion
-  | DialogSuggestion;
+export const directMention: Middleware<SlackEventMiddlewareArgs<'message'>> = async ({ message, context, next }) => {


🔪 closure, straight middleware

src/receivers/AwsLambdaReceiver.ts

filmaj · 2024-09-27T18:15:28Z

src/receivers/ExpressReceiver.spec.ts

@@ -529,7 +529,7 @@ describe('ExpressReceiver', function () {
        // Act
        const req = { body: { }, url: 'http://localhost/slack/oauth_redirect', method: 'GET' } as Request;
        const resp = { send: () => { } } as Response;
-        (receiver.router as any).handle(req, resp);
+        (receiver.router as any).handle(req, resp, () => {});


A change that was required as part of the move from express v4 -> v5

seratch

Great work; Left a few comments!

src/receivers/AwsLambdaReceiver.ts

tsconfig.json

…e invoked as a method to return middleware; instead, they are directly middleware, like other built-in middleware functions.

…e `message` parameter. THIS FIXES SO MUCH! shouts to jcalz on stackoverflow

…ntMiddlewareArgs when event contains channel information.

…ionMiddlewareArgs when a non-dialog or step from app action

…rtcutMiddlewareArgs when a non-dialog or step from app action. also TODOs

… flat map of strings to strings

…inder removal todos for eventual removal

…e events twice.

…2259)

…andlers (#2285)

filmaj added semver:major draft A pull request that is currently in active development and not yet ready for review labels Sep 13, 2024

filmaj added this to the 4.0.0 milestone Sep 13, 2024

filmaj self-assigned this Sep 13, 2024

filmaj mentioned this pull request Sep 13, 2024

Fix #2242 by upgrading express and its dependencies to newer major versions #2244

Closed

2 tasks

filmaj mentioned this pull request Sep 15, 2024

ci/tests: move to biome, v4 linter fixes #2259

Merged

1 task

This was referenced Sep 23, 2024

release candidate: pull in socket-mode RC to test stability improvements #2095

Closed

bug: buildSource does not take into account authorizations array when sourcing user_id during user-token retrieval/authorization #2271

Open

filmaj force-pushed the bolt-four branch from 249a3bc to e0988da Compare September 27, 2024 17:46

filmaj marked this pull request as ready for review September 27, 2024 17:50

filmaj changed the title ~~v4 draft~~ bolt v4 Sep 27, 2024

filmaj removed the draft A pull request that is currently in active development and not yet ready for review label Sep 27, 2024

filmaj commented Sep 27, 2024

View reviewed changes

src/receivers/AwsLambdaReceiver.ts Outdated Show resolved Hide resolved

filmaj commented Sep 27, 2024

View reviewed changes

src/receivers/AwsLambdaReceiver.ts Outdated Show resolved Hide resolved

filmaj commented Sep 27, 2024

View reviewed changes

src/receivers/AwsLambdaReceiver.ts Outdated Show resolved Hide resolved

filmaj commented Sep 27, 2024

View reviewed changes

filmaj requested a review from a team September 27, 2024 18:18

seratch reviewed Sep 28, 2024

View reviewed changes

src/receivers/AwsLambdaReceiver.ts Outdated Show resolved Hide resolved

src/receivers/AwsLambdaReceiver.ts Outdated Show resolved Hide resolved

src/receivers/AwsLambdaReceiver.ts Outdated Show resolved Hide resolved

tsconfig.json Show resolved Hide resolved

filmaj force-pushed the bolt-four branch from e0988da to 50c9fd0 Compare October 1, 2024 13:27

filmaj and others added 21 commits October 17, 2024 10:07

breaking change: remove deprecated http-utils module.

a80f9a7

breaking change: ignoreSelf and directMention now no longer need to b…

cfdc1a4

…e invoked as a method to return middleware; instead, they are directly middleware, like other built-in middleware functions.

redo how the SlackEventMiddlewareArgs type conditionally exposes th…

54fc209

…e `message` parameter. THIS FIXES SO MUCH! shouts to jcalz on stackoverflow

use conditional typing w/ unknown to add a say property to SlackEve…

3a429b2

…ntMiddlewareArgs when event contains channel information.

use conditional typing w/ unknown to add a say property to SlackAct…

be98ce2

…ionMiddlewareArgs when a non-dialog or step from app action

use conditional typing w/ unknown to add a say property to SlackSho…

3d87510

…rtcutMiddlewareArgs when a non-dialog or step from app action. also TODOs

awsEvent breaking change: header and querystrings can be modeled as a…

0a555c3

… flat map of strings to strings

adding deprecation notices to Steps from Apps stuff, and dropping rem…

c8695f9

…inder removal todos for eventual removal

Bolt v4 addendum: stricter typing of AWS API Gateway payloads (#2277)

69f73f4

addressing review comment re: small tweak to example

74244f2

re-export slack/types as a types named export

cef05ff

combine type utilities and helpers

490f093

fix refs to combined type utils/helpers

ac9c553

bump socket-mode to 2.0.2, to include a fix regarding handling messag…

187664e

…e events twice.

ci/tests: move to biome, v4 linter fixes, audit tests and reorganize (#…

1b793c0

…2259)

tag+publish 4.0.0-rc.2

9bc9e8a

expose web-api package as webApi export in bolt

63dd5ef

[email protected]

c90f278

fix: do not log ack timeout error if aws receiver has no registered h…

8354b1a

…andlers (#2285)

[email protected]

c61d3e2

docs: add bolt v3->v4 migration guide to docs.

06c670b

filmaj force-pushed the bolt-four branch from a65dec7 to 06c670b Compare October 17, 2024 14:37

filmaj added 6 commits October 17, 2024 10:41

shuffle assistant test files around

690c4e7

linting assistant stuff

c3261cc

a few more unit test fixes

a5ab2d5

fix up assistant tests, drop todos for type improvements

efcce08

fixing last of assistant unit tests

727a2e5

[email protected]

a954a40

filmaj merged commit 91750c2 into main Oct 17, 2024
20 checks passed

filmaj deleted the bolt-four branch October 17, 2024 19:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

bolt v4 #2254

bolt v4 #2254

filmaj commented Sep 13, 2024 •

edited

Loading

codecov bot commented Sep 13, 2024 •

edited

Loading

filmaj Sep 27, 2024

filmaj Sep 27, 2024

filmaj Sep 27, 2024

filmaj Sep 27, 2024

filmaj Sep 27, 2024

filmaj Sep 27, 2024

filmaj Sep 27, 2024

zimeg Oct 2, 2024

filmaj Sep 27, 2024

filmaj Sep 27, 2024

filmaj Sep 27, 2024

filmaj Sep 27, 2024

seratch left a comment

bolt v4 #2254

bolt v4 #2254

Conversation

filmaj commented Sep 13, 2024 • edited Loading

Summary

Breaking Changes

Middleware Type Changes

Other Breaking Changes

Non-breaking Changes

TODO

Post-release TODO

codecov bot commented Sep 13, 2024 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seratch left a comment

Choose a reason for hiding this comment

filmaj commented Sep 13, 2024 •

edited

Loading

codecov bot commented Sep 13, 2024 •

edited

Loading