Spring Slack Bot

The Spring Slack Bot library enforces a Unix CLI-style structure allowing for a flat list of commands or a command hierarchy of arbitrary depth. Each command supports a syntax as defined by the command, with help available via the -h flag.

As a very contrived example, a Slack bot might have a hierarchy of groups and commands.

The reports releases example from above might support some command line options to tailor the timeframe the report uses for its data. For example:

The bot can be interacted with by mentioning the Slack bot’s account in a channel where the bot account has been invited. Command messages sent to the bot must begin with the mention, followed by the complete path to the command, and finally any command arguments.

For example:

Using the example releases command from above, a request might resemble the following.

Help can be requested for any command that is configured with a picocli command line specification by passing the -h flag to the command. A help request might resemble the following.

Additionally, requesting help for a command that contains sub-commands will display the list of supported sub-commands.

Before any code is written, a Slack application must be created for use with the bot. The application appears as a user in the Slack namespace it is registered to, and part of the setup generates keys or tokens needed to run the Slack bot.

Spring Slack Bot is implemented as a Spring Boot library, and the flow of bootstrapping an application follows the typical process for creating a Spring Boot application by setting up the project build (using Maven or Gradle), adding the required dependencies, and creating custom Slack commands.

The Slack bot library is built on top of the spring-slack libraries, and most configuration of the bot is applied to this underlying library. See the Spring Slack documentation for a base set of configuration properties that must be configured.

In addition to the configuration required by the spring-slack libraries, the following configuration is available.

The following configuration properties are prefixed by slack.cli.

Slack commands may be created in a few different ways, and applications may choose the most convenient method according to the needs of the application.

Command line utilities typically support command line options. Those options may also be validated to ensure they are within bounds. Help output makes it easier to interact with tooling without having to look up documentation.

The bot library supports defining command line options and parameters via the picocli library. This allows applications to define a command contract, where command line flags are defined, along with their types. Defining the supported options for a command also builds up to a helpful usage output.

While picocli helps define the supported command line options for a command, arguments are validated against constraints through the use of JSR-380 annotations. Combining these two technologies creates a powerful way to both define the contract of a command and ensure that options are within the bounds that the command expects, keeping the business logic of a command free from input validation.

Command options for a command are simply classes with properties that are annotated with picocli and JSR_380 annotation.

To use a command options definition, the type of the arguments class should be provided to the argumentsClass property of a @SlackCommand annotation.

To provide commands details of the invocation of a specific request, a context object is built as a result of parsing the request and is optionally provided to the commands when the command execution occurs.

The SlackCommandContext provides the following details.

A Slack command method may return any object. Objects returned from a command method will receive further processing which may ultimately result in a response back to the user. See the Response Handling section for more details.

Slack’s Bolt API socket mode app objects contain a thread pool which services incoming events. Each incoming request from the Slack service allocates a new thread from the pool for the duration of the request. To avoid exhausting the Bolt thread pool by holding on to threads for the entire duration of a command’s execution, all commands are instead executed in a separate thread pool called the command thread pool. In this manner, the underlying Bolt thread pool should not become exhausted, and any potential thread contention will instead occur at the command thread pool. If the command thread pool becomes exhausted because the bot is receiving more commands at once that it can concurrently handle, there will be a delay in processing requests from users.

It is up to the authors of applications using the library to determine the size of the command thread pool that the bot will require to serve its audience and its processing time requirements.

The Spring Slack Bot library supports project Reactor for commands implemented with non-blocking I/O.

For a command to be processed as a reactive stream, command methods should return instances of Mono or Flux. The framework will recognize these types, set up the Spring Security authentication in the stream’s context, and subscribe to the reactive stream.

Just as with normal, threaded commands, each non-null result from a stream will be submitted to response handlers for automatic responses to the user.

Response handlers are beans that are responsible for accepting values returned by command methods and performing some operation on them. They typically will respond to a user with the contents of objects it supports, but the specifics of how objects are handled is left to these handlers.

Response handlers may use Spring’s ordering system (either by implementing Ordered or annotation the bean with @Order).

Response handlers advertise what they may handle via a method named supports which receives the class type of the object. If this method returns true, the object will be passed to the handler for processing.

To add a custom response handler, implement the ResponseHandler<T> interface as a Spring bean, and it will automatically be registered and used.

A default, fallback handler is used when no other handler indicates that it can handle the response type. This handler accepts any object type, calls toString() on the object, and hands the resulting string to the response strategy bean.

As an example, imagine an object type the contains a header and body that should be translated to a rich layout-based output. While this logic can also live directly in a command method, it may be moved into a response handler so that it may be used by all command methods.

The ResponseStrategy bean is responsible for sending a Slack message as a response to any message generated internally by the bot framework. This includes string-type messages generated by the default response handler.

Command methods and response handlers have the option to maintain full control over the manner by which content is posted to Slack via the Slack API. The response strategy bean offers a common and consistent way to post content when fine-grain control over user interaction is not needed or desired.

The default response strategy sends messages to the user in threaded replies to the message that originated the bot command/request. To change this behavior, applications only need to register their own implementation of the ResponseStrategy interface.

For example, a response strategy that sends a response directly to a channel instead of a thread might look like the following.

The MethodsClient is Slack’s Java API binding for its suite of APIs. An instance of this object is provided as a bean and may be injected as desired. The client is pre-configured with the API key required to interact with the API using the same token used to configure the underlying Slack App instance.

Slack also provides an AsyncMethodsClient, which contains the same API methods as MethodsClient. However, all API calls are handled via an internal thread pool and methods return futures. This version of the client is also exposed as a Spring bean and is suitable for reactive streams.

The SlackClientHelper bean contains several convenience methods that makes it much easier and more concise to perform common operations. It wraps the Slack MethodsClient, which is a Java API binding for the Slack API.

The bot framework itself uses this class extensively in favor using the MethodsClient.

Reactive commands should prioritize non-blocking I/O, and so an AsyncSlackClientHelper bean is also defined which may be used in a reactive stream. Where the SlackClientHelper uses Slack’s MethodsClient, the AsyncSlackClientHelper uses Slack’s AsyncMethodsClient.

Ideally, command methods should handle their own error handling logic in order to provide appropriate and accurate feedback to users. In order for the library continue to function if errors leak from command methods, all errors stemming from command invocations are passed to a CommandErrorHandler.

A built-in, default error handler is defined that provides a generic error message back to the user when errors in commands occur. Additionally, the default error handler will unwrap and handle InvocationTargetException errors (which are thrown as part of reflectively executing command methods) to handle the actual error thrown by the command method. This also captures AccessDeniedException errors thrown by the Spring Framework security chain when users attempt to execute a command they do not have access to.

If a change in the behavior of this feedback is desired, applications may implement their own version of the CommandErrorHandler bean instead.

A MentionHandlerErrorHandler bean is responsible for handling errors thrown by the internals of the bot library. It handles both errors that result from parsing and invoking commands and responding to the user command usage.

While applications may replace this bean by defining their own implementation of MentionHandlerErrorHandler, it is not recommended.

The security configuration contained in the library enables global method security. This allows authors to annotate secured methods with authorization criteria.

Individual command methods may be annotated with @PreAuthorize, and the criteria contained within the annotation must be met for the user to be granted access to the command.

As an example, the following command implementation requires the user to have the role ROLE_FOO in order to be able to invoke the command.

The SlackAuthProvider bean is a Spring Security authentication provider that gets registered in the security configuration. It specifically authenticates users by their Slack ID, which it accomplishes through the use of a SlackUserDetailsService.

The SlackUserDetailsService specifically returns instances of SlackUser as its user details. The default implementation provided by the bot library uses the application’s configuration file as a source for Slack user details.

Users are configured under the slack.security.users key. This is a mapped key, where the next key is the Slack ID of a user, and additional properties underneath the users pertain to that user.

The following examples should illustrate how to configure users who will be authenticated.

Before invoking command methods, authentication tokens are provided to and stored in a security context to make it available to both the command’s execution and to the Spring Security framework. Commands do not need to implement any logic around authenticating users.

For standard, threaded commands, the authentication token is stored in the SecurityContextHolder. This makes the authentication available to the current thread for the duration of the request.

For reactor-based commands, the authentication token is configured in the ReactiveSecurityContextHolder, and subsequently injected into the reactive stream’s context.