Fixes #1477 Add customPropertiesExtractor to receiver options docs #1864
Conversation
|
|
||
| --- | ||
|
|
||
| #### Customizing built-in receivers |
There was a problem hiding this comment.
Would it be better to move this into its own concepts page?
There was a problem hiding this comment.
No I think this is great where it is!
Codecov Report
@@ Coverage Diff @@
## main #1864 +/- ##
=======================================
Coverage 82.18% 82.18%
=======================================
Files 18 18
Lines 1521 1521
Branches 436 436
=======================================
Hits 1250 1250
Misses 175 175
Partials 96 96 📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more |
docs/_advanced/receiver.md
Outdated
| @@ -6,6 +6,9 @@ order: 9 | |||
| --- | |||
|
|
|||
| <div class="section-content"> | |||
|
|
|||
| #### Writing a custom receiver | |||
|
|
|||
| A receiver is responsible for handling and parsing any incoming requests from Slack then sending it to the app, so that the app can add context and pass the request to your listeners. Receivers must conform to the Receiver interface: | |||
There was a problem hiding this comment.
I know this isn't exactly part of your PR, but perhaps we can link Receiver interface to https://github.com/slackapi/bolt-js/blob/main/src/types/receiver.ts#L27-L31?
| A receiver is responsible for handling and parsing any incoming requests from Slack then sending it to the app, so that the app can add context and pass the request to your listeners. Receivers must conform to the Receiver interface: | |
| A receiver is responsible for handling and parsing any incoming requests from Slack then sending it to the app, so that the app can add context and pass the request to your listeners. Receivers must conform to the [Receiver interface](https://github.com/slackapi/bolt-js/blob/main/src/types/receiver.ts#L27-L31): |
There was a problem hiding this comment.
@filmaj We should avoid pointing code lines in the main branch as the code can be changed in the future. How about using a release tag instead? https://github.com/slackapi/bolt-js/blob/%40slack/bolt%403.13.1/src/types/receiver.ts#L27-L31
|
|
||
| --- | ||
|
|
||
| #### Customizing built-in receivers |
There was a problem hiding this comment.
No I think this is great where it is!
docs/_tutorials/reference.md
Outdated
| @@ -98,6 +98,7 @@ Bolt includes a collection of initialization options to customize apps. There ar | |||
| | `unhandledRequestHandler` | Error handler triggered when a request from Slack goes unacknowledged. More details available in the [Error Handling documentation](/bolt-js/concepts#error-handling). | | |||
| | `unhandledRequestTimeoutMillis` | How long to wait, in milliseconds, from the time a request is received to when the `unhandledRequestHandler` should be triggered. Default is `3001`. More details available in the [Error Handling documentation](/bolt-js/concepts#error-handling). | | |||
| | `signatureVerification` | `boolean` that determines whether Bolt should [verify Slack's signature on incoming requests](https://api.slack.com/authentication/verifying-requests-from-slack). Defaults to `true`. | | |||
| | `customPropertiesExtractor` | Optional `function` that can extract custom properties from a request -- for example, extracting custom headers to propagate to other services. More details available in the [Customizing a receiver documentation](/bolt-js/concepts#receiver). | | |||
There was a problem hiding this comment.
Let's clarify two things:
- what the function argument is (at least, what type it is: for HTTP-based receivers, it would be an HTTP request, but for e.g. Socket Mode, it would be a WebSocket message.
- what the function needs to return, and then how those custom properties are available in the context of a wider app. If I understand correctly, the returned object becomes part of the
contextargument provided to Bolt middleware.
There was a problem hiding this comment.
Indeed, Fil's points can be mentioned quickly in the descrption.
In addition to that, I think we can remove the following part because the linked document section is about how to build your own receiver, not how to customize a built-in one.
More details available in the Customizing a receiver documentation.
... Ah never mind about my point. This PR is goind to add sub section for it.
docs/_advanced/receiver.md
Outdated
|
|
||
| ##### Extracting custom properties | ||
|
|
||
| Use the `customPropertiesExtractor` option to extract custom properties from requests. This is particularly useful for extracting HTTP headers that you want to propagate to other services, for example, if you need to propagate a header for distributed tracing. |
There was a problem hiding this comment.
Maybe we should add a note here that, depending on what kind of receiver you are building, or which pre-existing receiver you are extending with customPropertiesExtractor, the "from requests" part may not be exactly technically correct. For HTTP-based receivers, they would indeed be an HTTP request, but for socket-mode-based receivers, the argument to the extractor would be a websocket message sent from the server.
There was a problem hiding this comment.
Checking examples/custom-properties code should be helplful to understand the difference between the two (HTTP vs Socket Mode)
|
meant to turn off my formatter to avoid those whitespace changes and then forgot, i can remove them if it's an issue |
|
Thanks so much for your contribution! |
Summary
Fixes #1477 Add customPropertiesExtractor to receiver options docs
Slightly rearranges existing
Custom receiverconcepts section to include an example of usingcustomPropertiesExtractor.Details
This may be over the top relative to what you all had in mind. It seemed nice to include a usage example, and I couldn't think where else to put it.
I worried that it might be confusing to include this example in the section on writing a custom receiver, so I tried to edit it to make it clear. I left the writing a custom receiver section first because the main example on the side demonstrates writing your own custom receiver.
Requirements (place an
xin each[ ])