Forem: Kevin White

Deploy a Unity WebGL Package to AWS S3 Static Site with GitHub Actions

Kevin White — Thu, 09 Feb 2023 04:09:05 +0000

I've been learning about Unity recently and wanted to have an easily shareable artifact. It seemed like a common use case, but I ended up having to pull disparate pieces and learnings together to get it working. In this article I'll review how I setup GitHub Actions CI/CD for a Unity WebGL package deployed to an AWS S3 static site... in my case, https://unity.kwhitejr.com.

Just take me to GitHub, I'll figure it out.

The setup can easily be tweaked to accommodate other package types. This is intended to provide a baseline!

Prerequisites

An AWS account.
A GitHub account.
A Unity account.
Terraform (used for one-time setup of AWS resources).

Setup for these tools is outside the scope of this article. Some basic know-how with each tool will help avoid headaches.

Overview

The goal is to deploy your Unity WebGL package to AWS S3 storage, accessible as a static site. This article assumes that you already have a domain and we will deploy it to a subdomain (such as https://unity.yoursite.com).

A rough outline of the steps:

Build AWS resources with Terraform (one time setup).
Source control your Unity project with GitHub (one time setup).
Acquire a Unity personal-use license (one time setup).
Use GitHub Actions to build and deploy your Unity project as a WebGL package to AWS S3 (iterable final state).

Setup AWS Resources with Terraform

In this section I'll review setup of AWS resources to enable a subdomain: S3 storage for the origin, Route53 for DNS routing, CloudFront for CDN, and ACM for an https certificate.

This process is helpful for setting up any static site subdomain, regardless of whether you use it for Unity or not.

Terraform Modules

Terraform is a framework for deploying infrastructure as code. Because it is code, common use cases (such as static sites) can be formed into version-controlled modules. In order to set up the AWS resources for this project, I leaned on pre-existing and well-vetted modules from CloudPosse:

Here are the modules in action, annotated with notes. Your mileage may vary, but I had to deploy the ACM Request Certificate alone first, then re-run with the CloudFront S3 CDN module. Additionally, I wrote a quick helper script to speed up iteration time.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

# Configure the AWS Provider
provider "aws" {
  region = "us-east-1"
}

locals {
  domain_name     = "kwhitejr.com" # Use your own domain.
  sub             = "unity"        # Choose your subdomain
  sub_domain_name = "${local.sub}.${local.domain_name}"
}

# My domain, kwhitejr.com, is already a Route53 Zone on AWS.
# You may have extra work to get your domain setup in AWS.
data "aws_route53_zone" "main" {
  name         = local.domain_name
  private_zone = false
}
##### NOTE
# Annoyingly, these modules only created successfully 
# when doing the acm-request-certificate by itself first,
# then adding in the cloudfront-s3-cdn on a second run
#####

module "acm_request_certificate" {
  source = "cloudposse/acm-request-certificate/aws"

  # Cloud Posse recommends pinning every module to a specific version
  version                           = "0.17.0"
  domain_name                       = local.sub_domain_name
  process_domain_validation_options = true
  ttl                               = "300"
}

module "cdn" {
  source = "cloudposse/cloudfront-s3-cdn/aws"

  version = "0.84.0"
  name    = local.sub_domain_name

  # DNS Settings
  aliases                 = [local.sub_domain_name]
  dns_alias_enabled       = true
  parent_zone_id          = data.aws_route53_zone.main.zone_id
  allow_ssl_requests_only = false

  # Caching Settings
  default_ttl = 300
  compress    = true

  # Website settings
  website_enabled             = true
  s3_website_password_enabled = true
  index_document              = "index.html"
  error_document              = "index.html"

  acm_certificate_arn = module.acm_request_certificate.arn

  # NOTE: not sure why this dependency assertion doesn't seem to work.
  # Deploy of this module fails (for me) unless the ACM is deployed first and independently.
  depends_on = [module.acm_request_certificate]
}

What Did We Build and Why?

Route53 handles DNS routing; essentially, it tells the world that https://unity.yoursite.com redirects to your S3 bucket static site, which holds your website code (e.g. index.html). Sitting between them is a CloudFront CDN, which handles caching.

The S3 bucket is configured to be public and therefore makes the static assets available to the world... except not. Public S3 buckets are a big security no-no. The workaround is make the bucket public but enforce password access. Only the CDN knows the password (this is automated by the CloudPosse module).

To convince yourself, try accessing the bucket assets via its S3 url. If everything has gone according to plan, then you shouldn't be able to!

Once you successfully create the AWS resources, you can verify the setup by uploading a valid index.html document into your new bucket. Next, navigate to the declared subdomain and see your new site!

CAUTION. There are a couple cache layers that may give you bad signals while iterating: browser cache and CDN cache. When testing your initial setup, I recommend using incognito tabs and invalidating your CloudFront cache after major changes. Hopefully you avoid banging your head like I did.

Last but not least, you'll want to git ignore certain generated Terraform files.

Source Control Unity Project in GitHub

The next piece of the puzzle is to source control your Unity project in GitHub. I recommend colocating your Unity project with the Terraform setup files.

Brackeys has a great video on setting up GitHub source control for your Unity project. I followed his advice on sequestering Unity files to a subdirectory. I found this made repo management much easier.

There isn't much for me to add to the process. If you follow his video, you should end with a source-controlled Unity project colocated with your Terraform files.

// end state project structure
/MyUnityProject
  /etc
/terraform
  /make-bucket
    /main.tf
/scripts
  /make-bucket.sh
.gitignore

Acquire a Unity Personal-Use License

The GitHub Actions pipeline uses game-ci to build and package the Unity project. You will need a Unity personal-use license to utilize these capabilities. Acquiring the license is a one-time setup requirement.

game-ci provides detailed instructions on acquiring the necessary license. Essentially...

Manually run this workflow.
Download the manual activation file that now appeared as an artifact and extract the Unity_v20XX.X.XXXX.alf file from the zip.
Visit license.unity3d.com and upload the Unity_v20XX.X.XXXX.alf file.
You should now receive your license file (Unity_v20XX.x.ulf) as a download. It's ok if the numbers don't match your Unity version exactly.
Open Github > > Settings > Secrets.
Create the following secrets:
- UNITY_LICENSE - (Copy the contents of your license file into here)
- UNITY_EMAIL - (Add the email address that you use to login to Unity)
- UNITY_PASSWORD - (Add the password that you use to login to Unity)

These secrets will be consumed by the build and deploy pipeline.

Build and Deploy with GitHub Actions

All of the component pieces should now be ready to integrate to produce the deployment pipeline. Remember, the goal is to deploy the latest build to S3 upon merge to main.

Below is the GitHub Actions deploy pipeline, annotated with notes.

name: Build & Deploy Unity WebGL

# Fire pipeline on merge to main.
on:
  push:
    branches:
      - main
env:
  BUCKET: unitykwhitejrcom-origin # The bucket created by Terraform.
jobs:
  # The Build job primarily uses game-ci containers to test and build your package.
  build:
    name: Build For WebGL Platform
    runs-on: ubuntu-latest
    # Run this job from local Unity project directory.
    defaults:
      run:
        working-directory: EventDrivenCharacterController
    steps:
      # 1. Checkout code.
      - uses: actions/checkout@v2
        name: Checkout
      # 2. Use cache, if available.
      - uses: actions/cache@v2
        name: Cache
        with:
          path: Library
          key: Library-${{ hashFiles('Assets/**', 'Packages/**', 'ProjectSettings/**') }}
          restore-keys: |
            Library-

      # TODO: when you ready to run tests as part of your deploy, uncomment.
      # 3. Test
      # - uses: game-ci/unity-test-runner@v2
      #   name: Test
      #   env:
      #     UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
      #   with:
      #     githubToken: ${{ secrets.GITHUB_TOKEN }}

      # 4. Build WebGL Package
      # NOTE: you can expand target platforms to include other package types, if you like.
      - uses: game-ci/unity-builder@v2
        name: Build
        # Requires Unity-related secrets.
        env:
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
          UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
          UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
        with:
          targetPlatform: WebGL
          projectPath: EventDrivenCharacterController
      # 5. Upload Package
      - uses: actions/upload-artifact@v2
        name: Upload
        with:
          name: Build
          path: build

  # The Deploy job primarily uses AWS containers to upload assets to S3.
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      # 1. Checkout code.
      - uses: actions/checkout@v3
        name: Checkout
      # 2. Download package from build job (the WebGL package).
      - uses: actions/download-artifact@v3
        name: Download artifacts
        with:
          name: Build
          path: build
      # 3. Configure AWS credentials. You will need to get these from IAM.
      - uses: aws-actions/configure-aws-credentials@v1
        name: Configure AWS credentials from Test account
        with:
          aws-region: us-east-1
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          # You can skip role-to-assume if your access keys contain power user credentials.
          # Best practice is to implement least-based privileges,
          # where the deploy service user (the pipeline) is limited to just assuming a role
          # and assumed role has the rights to actually create and update the assets.
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          role-duration-seconds: 1200
          role-skip-session-tagging: true
      # 4. Sync assets to bucket.
      - name: "[Deploy Phase 1] Sync everything from public dir to S3 bucket"
        working-directory: build
        run: aws s3 sync ./WebGL/WebGL s3://$BUCKET --delete
      # 5. HERE BE DRAGONS - update metadata
      # "aws s3 sync" is a blunt tool.
      # Your assets will be synced, but missing necessary metadata,
      # e.g. content-type and content-encoding.
      # Although it is hacky, the next few commands iterate over certain file types
      # and re-copy them with the correct metadata.
      - name: "[Deploy Phase 2] Brotli-compressed files"
        working-directory: build
        run: |
          aws s3 cp ./WebGL/WebGL s3://$BUCKET \
            --exclude="*" --include="*.br" \
            --content-encoding br \
            --content-type="binary/octet-stream" \
            --metadata-directive REPLACE --recursive;

      - name: "[Deploy Phase 3] Brotli-compressed Javascript"
        working-directory: build
        run: |
          aws s3 cp ./WebGL/WebGL s3://$BUCKET \
            --exclude="*" --include="*.js.br" \
            --content-encoding br \
            --content-type="application/javascript" \
            --metadata-directive REPLACE --recursive;

      - name: "[Deploy Phase 4] Brotli-compressed WASM"
        working-directory: build
        run: |
          aws s3 cp ./WebGL/WebGL s3://$BUCKET \
            --exclude="*" --include="*.wasm.br" \
            --content-encoding br \
            --content-type="application/wasm" \
            --metadata-directive REPLACE --recursive;

As you can surmise, there are a couple wrinkles with the pipeline.

I'm not sure why the build contains double directories of /WebGL/WebGL/. I probably have some configuration slightly off, but not sure what. I reached out to Game CI team on discord but didn't hear anything back ¯_(ツ)_/¯
The final few steps of the deploy job are suboptimal because you need to re-upload files to correct their metadata. I lifted this hack from here. It is a clever workaround, but I hope that aws s3 sync gets updated to allow similar capability. Otherwise, in theory you could use Terraform instead of AWS CLI to perform the file uploads. The aws_s3_object API includes the necessary metadata options, but this route feels like more trouble than it's worth.

Voilá. You should now be able to iterate on your Unity project and easily deploy updates to a static site to share with the world!

useAuth: AWS Amplify Auth + React Hooks = Easy Auth Management

Kevin White — Mon, 11 Apr 2022 02:38:09 +0000

This is a short post providing a sample implementation of AWS Amplify authentication management in a React app with hooks.

tl;dr

When Auth.signIn() succeeds, it sets a cookie with session data that can be accessed by Auth.currentSession(). This doesn't seem to be well documented, but it unlocks the ability to preserve authentication state on browser refresh.
Raw source code and tests.
Shout out to useHooks.com for the inspiration on the useAuth hook source code.
Shout out to Kent C. Dodds for the inspiration on the React hook testing strategy and implementation.

The Problem

The desirable outcome addressed by this article is an auth management strategy that...

Centrally manages auth state such that it is easily available to all components.
Implements this strategy with React hook syntax.
The authentication service is AWS Amplify (AWS Cognito under the hood).
Is tested.

One thing I found in my initial time with AWS Amplify is that, upon browser refresh, my app would lose the current authentication state. In short, a logged-in user is logged out on browser refresh. And that is annoying.

Additionally, I couldn't find much written on this issue. It is entirely possible that I missed an important line in the AWS documentation, but the discovering that Auth.currentSession() accessed a session cookie retained in the browser was a major epiphany.

The Hook

// use-auth.js

import React, {
  useState, useEffect, useContext, createContext,
} from 'react';
import { Auth } from '@aws-amplify/auth';

// Implement your particular AWS Amplify configuration
const amplifyConfigurationOptions = {
  userPoolRegion: "REGION",
  userPoolId: "POOL_ID",
  userPoolWebClientId: "CLIENT_ID",
};

Auth.configure(amplifyConfigurationOptions);

const AuthContext = createContext();

// Wrap your app with <ProvideAuth />
export function ProvideAuth({ children }) {
  const auth = useProvideAuth();
  return <AuthContext.Provider value={auth}>{children}</AuthContext.Provider>;
}

// Access auth values and functions with custom useAuth hook
export const useAuth = () => useContext(AuthContext);

function useProvideAuth() {
  const [user, setUser] = useState(null);
  const [isSignedIn, setIsSignedIn] = useState(false);

  useEffect(() => {
    // NOTE: check for user or risk an infinite loop
    if (!user) {
      // On component mount
      // If a session cookie exists
      // Then use it to reset auth state
      Auth.currentSession()
        .then((session) => {
          const {
            idToken,
            accessToken,
          } = session;

          // Define your user schema per your needs
          const user = {
            email: idToken.payload.email,
            username: idToken.payload.preferred_username,
            userId: idToken.payload.sub,
            accessToken: accessToken.jwtToken,
          };

          setIsSignedIn(true);
          setUser(user);
        })
        .catch((err) => {
          // handle it
        });
    }
  }, [user]);

  const signIn = ({ email, password }) => Auth.signIn(email, password)
    .then((cognitoUser) => {
      // Set user data and access token to memory
      const {
        attributes,
        signInUserSession: {
          accessToken,
        },
      } = cognitoUser;

      const user = {
        email: attributes.email,
        username: attributes.preferred_username,
        userId: attributes.sub,
        accessToken: accessToken.jwtToken,
      };

      setIsSignedIn(true);
      setUser(user);

      return user;
    });

  const signOut = () => Auth.signOut()
    .then(() => {
      setIsSignedIn(false);
      setUser(null);
    });

  return {
    user,
    isSignedIn,
    signIn,
    signOut,
  };
}

I am an admitted neophyte when it comes to useEffect, so there may be a better implementation for recovering auth state within this callback. In particular, I initially ran into an infinite loop when calling setUser() because user is one of the callback's dependencies. Happy to hear advice on this one.

The Usage

Much pseudo-code, but you get the idea...

// AppRoot.jsx
import React from 'react';

import App from './app'; // uses <MyComponent />
import { ProvideAuth } from './use-auth';

return (
  <ProvideAuth>
    <App />
  </ProvideAuth>
);

// MyComponent.jsx
import React from 'react';

import { useAuth } from './use-auth';

function MyComponent() {
  const { isSignedIn, user, signIn, signOut } = useAuth();

  return (
    <div>
      <div>{`IsSignedIn: ${isSignedIn}`}</div>
      <div>{`Username: ${user?.username}`}</div>
      {isSignedIn ? (
        <button onClick={signOut} type="button">Sign Out</button>
      ) : (
        <button onClick={signIn} type="button">Sign In</button>
      )}
    </div>
  )
};

The Test

It's perfectly feasible to test a hook in the abstract, but Kent C. Dodds convinced me that it is better to test the hook in its natural habitat... a component.

Essentially, set up an example component that uses the hook, then compose expectations that for the state of that component that could only be achieved by the hook.

// Example Component

import React from 'react';
import { ProvideAuth, useAuth } from '../src/use-auth';

function TestComponent() {
  const {
    user,
    isSignedIn,
    signIn,
    signOut,
  } = useAuth();

  const handleSignIn = () => {
    const mockCreds = {
      email: 'user@email.com',
      password: 'pw',
    }

    signIn(mockCreds);
  }

  const handleSignOut = () => signOut()

  return (
    <div>
      <div>{`IsSignedIn: ${isSignedIn}`}</div>
      <div>{`Username: ${user?.username}`}</div>
      <div>{`AccessToken: ${user?.accessToken}`}</div>
      <button onClick={handleSignIn} type="button">SignInButton</button>
      <button onClick={handleSignOut} type="button">SignOutButton</button>
    </div>
  );
}

function UseAuthExample() {
  return (
    <ProvideAuth>
      <TestComponent />
    </ProvideAuth>
  );
}

export { UseAuthExample };

// use-auth.test.jsx

import React from 'react';
import {
  render, screen, fireEvent, act,
} from '@testing-library/react';
import { Auth } from '@aws-amplify/auth';

import { UseAuthExample } from './UseAuthExample';

describe('useAuth', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('should provide default values on load when user is not authenticated', () => {
    const currentSessionMock = jest.fn().mockRejectedValue('No user found.');
    Auth.currentSession = currentSessionMock;

    render(<UseAuthExample />);

    const isSignedIn = screen.getByText(/issignedin/i);
    const username = screen.getByText(/username/i);
    const accessToken = screen.getByText(/accesstoken/i);

    expect(isSignedIn).toHaveTextContent('IsSignedIn: false');
    expect(username).toHaveTextContent('Username:');
    expect(accessToken).toHaveTextContent('AccessToken:');
  });

  it('should provide current user on load when current session is found', async () => {
    const currentSessionMock = jest.fn().mockResolvedValue({
      idToken: {
        payload: {
          email: 'user@email.com',
          preferred_username: 'myuser',
          sub: '1234-abcd',
        },
      },
      accessToken: {
        jwtToken: 'fake-token',
      },
    });
    Auth.currentSession = currentSessionMock;

    await act(async () => {
      render(<UseAuthExample />);
    });

    const isSignedIn = screen.getByText(/issignedin/i);
    const username = screen.getByText(/username/i);
    const accessToken = screen.getByText(/accesstoken/i);

    expect(isSignedIn).toHaveTextContent('IsSignedIn: true');
    expect(username).toHaveTextContent('Username: myuser');
    expect(accessToken).toHaveTextContent('AccessToken: fake-token');
  });

  it('should login the user and update ui', async () => {
    const currentSessionMock = jest.fn().mockRejectedValue('No user found.');
    const signInMock = jest.fn().mockResolvedValue({
      attributes: {
        email: 'user@email.com',
        preferred_username: 'myuser',
        sub: '1234-abcd',
      },
      signInUserSession: {
        accessToken: {
          jwtToken: 'fake-token',
        },
      },
    });
    Auth.currentSession = currentSessionMock;
    Auth.signIn = signInMock;

    render(<UseAuthExample />);

    const isSignedIn = screen.getByText(/issignedin/i);
    const username = screen.getByText(/username/i);
    const accessToken = screen.getByText(/accesstoken/i);

    expect(isSignedIn).toHaveTextContent('IsSignedIn: false');
    expect(username).toHaveTextContent('Username:');
    expect(accessToken).toHaveTextContent('AccessToken:');

    const signInButton = screen.getByText(/signinbutton/i);

    await act(async () => {
      fireEvent.click(signInButton);
    });

    expect(isSignedIn).toHaveTextContent('IsSignedIn: true');
    expect(username).toHaveTextContent('Username: myuser');
    expect(accessToken).toHaveTextContent('AccessToken: fake-token');
  });
});

Serverless SlackBots Pt 1: Architecture and Musings

Kevin White — Fri, 21 May 2021 17:02:08 +0000

Motivation

Slack Bots provide a great entry point to backend functionalities. My team uses SlackBots to automate common tasks and to provide non-technical teammates with access to self-serve utilities. Serverless architectures are generally easier to set up, easier to maintain, and cost less than traditional servers, especially for sporadic use cases. In short, serverless architecture is a great fit for the irregular usage of our Slack Bots.

My initial research into serverless-based Slack Bots did not yield a lot of examples. In fact, much of Slack's API documentation seems to assume that the developer is running a traditional server. Stubborn mule that I am, I insisted on a fully serverless implementation anyway. This article describes the architecture that we landed upon, as well as its quirks and shortcomings. In a future article I hope to share more of the application code.

In this article, the terms Slack Bot and Slack App are used interchangeably. Technically, everything is a Slack App. But "Bots" are chic and cool and hip, man, and I'm no jive turkey.

Requirements

The solution must abide by the following requirements and constraints:

The architecture must be 100% serverless managed resources (and in this case will be on AWS).
The architecture must support Slack slash commands.
The architecture must support Slack interactions.
The architecture should minimize usage of Slack's developer APIs.
Build atop AWS.

This author is of the opinion that the only thing less consistent and cohesive than Slack's developer APIs is its associated documentation. While SlackBots are great, the development experience is awful. One silver lining of this architectural approach is the increased isolation of the bot application code from the Slack interface; in other words, your application functionality will not be limited to Slack!

Step One: Slash Commands

Slack Slash Commands are the perfect first step to take if you are new to SlackBots. A slash command very much embodies a "Push button, get thing" simplicity that is easy to wrap you head around. As a super basic example, you may want /random-number to return to you a random number. When it comes to automating more complex workflows, you may want /create-order --env=test --type=SHIP_TO_CONSUMER --items=2 to create an order resource, of type ship-to-consumer, in the test environment, and containing two random items.

In either case, the required application does not run in Slack itself. The slash command essentially collects inputs and sends the data to a webhook.

The sequence diagram below describes an extensible architecture for ingesting Slack slash commands.

Slash Command Architecture Overview

Slack

Slack requires that you create a SlackBot from the developer console and assign it necessary permissions. Creation and permissioning are outside the scope of this article, but I hope that the linked resources can help.

One SlackBot can accommodate many slash commands. From your Slack app's developer console, you are required to submit a Request URL for each registered slash command; Slack will POST the input payload to this URL whenever the slash command is run. To avoid superfluous infrastructure, use the same URL for every slash command and then use a controller to send the request to the appropriate worker.

API Gateway

This architecture requires a single API Gateway to accept all slash command POSTs. These payloads are forwarded to the slash command controller lambda, whose job it is to redirect the workload to the correct worker.

The dynamically generated raw API Gateway URL might change over time, if you happen to destroy and recreate your CloudFormation stack. If it changes, then your slash command integration would also break until you made appropriate manual corrections in the Slack app developer console. It is advisable to front the API Gateway with a static URL via Route 53 in order to avoid this problem.

Slash Command Controller Lambda

The main job of the slash command controller lambda is to redirect the command payload to the correct worker. For example, /do-thing commands should be redirected to the DoThing Worker Lambda and /create-order commands should be redirected to the CreateOrder Worker Lambda. As you can see, adding new functionality is as simple as (1) register new slack command with same old Request URL; (2) update controller lambda with new redirect; and (3) build out your new functionality in a new worker lambda.

However, Slack has some quirks that the controller lambda is also responsible for resolving. The main issue is the 3 second timeout; if the slash command does not receive some response within 3 seconds, then the request times out and is treated as a failure.

Therefore, as described in the diagram above, the controller lambda should send an immediate 200 response as soon as basic validations take place and before the workload is forwarded. This can be accompanied by a basic message to inform the user to hang out while the workload is assigned and processed.

Some example helpful messages:

Okay! Working on it, boss...

Message received! Spinning up the hamster wheels...

Roger that. Too close for missiles, switching to guns.

Really anything to let the user know how much you care.

It depends on your use case, but it is probably not necessary for the controller lambda to wait for worker lambda to finish its workload. The controller lambda's execution generally can end after it forwards the payload.

Worker Lambda(s)

The content of the worker lambda is really up to you; this is where your feature logic lives. This lambda has two jobs: (1) do the work; and (2) send response to the user.

In theory, it need not be a single lambda, or even a lambda at all! It could be a Step Function or any number of async processes. It's main job to perform the requested work.

If you wanted to completely isolate the worker lambda from any Slack-ification (and that's not a terrible idea), you could have the controller lambda wait for the workload result and send the response back to Slack. This would have the extremely positive benefit of allowing the worker lambda to interface with many input channels, not just Slack! The downside is that you'll have a potentially long-lived controller lambda execution while it waits for the workload to finish. In short, your mileage may vary!

Step Two: Add an Interaction

A Slack Interaction provides a friendly UX for Slack App user inputs. For example, you've trained your business users to use /create-order to create their own test data; now you want them to update the order state themselves (e.g. complete an order) instead of asking you to manually POST updates to the test environment. Slack Interactions to the rescue!

In this example, an order can be COMPLETED or CANCELLED; under the hood, your service simply patches an order resource to status: 'COMPLETED' or status: 'CANCELLED'. You want to provide these options to your business user with a simple button interface after an order is created.

Interaction Architecture Overview

As before, initiate the SlackBot with the slash command, /create-order. This time, however, the worker lambda is additionally responsible for constructing an Interaction config and sending it back to the channel whence it came. There are a number of interaction types and Slack provides Block Kit Builder, a playground for designing them.

Regardless of the Block Kit Builder, I've found the developer APIs for creating and interacting with Slack Interactions to be awful. I will summarize some pain points below. Your mileage may vary.

Next, after you send an interaction back to the initiating user, there must be some means by which your application can ingest the subsequent user input. Every Slack App can optionally configure an Interaction Request URL. From the Slack App dashboard, enable interactivity and configure the Request URL with your API Gateway. Slack will send an HTTP POST request with information to this URL when users interact with a shortcut or interactive component.

Per the infrastructure diagram, I use the same API Gateway to ingest requests for slash commands and interactions, but have configured different paths (/commands and /interactions, respectively) for each callback type.

Once interaction payloads are flowing into API Gateway, the setup is very much similar to slash commands: a controller lambda provides initial checks and routes the interaction payload to the appropriate worker, and the worker lambda performs the work defined in the interaction payload. In our example...

the user clicks either the COMPLETE or CANCEL button,
this interaction payload is delivered via API Gateway to the interaction controller lambda,
the interaction controller lambda inspects the payload and routes it to the appropriate worker lambda (i.e. an Update Order Worker),
the worker lambda patches the order to COMPLETED or CANCELLED, then posts a success message back to Slack.

Potential Improvements

Decouple controller and worker lambdas with SNS or SQS. The result would be that the worker lambda must take ownership of communicating results back to Slack.
Eliminate slash command controller lambda entirely by linking a more detailed API Gateway path (e.g. /commands/create-order) directly to the relevant worker lambda. Similar to decoupling, this setup forces the worker lambda to both send the synchronous response and communicate final results back to Slack.
Conversely, enforce that the controller lambdas are the sole interface with Slack so that worker lambdas can isolate their single responsibility. This would allow workers to interface with other triggers, not just Slack.

Pain Points

Through this article I've alluded to some pain points that I found working with Slack developer APIs. Some of these may be due to my own ignorance.

Manual set-up steps. So far as I can tell, there is no way to avoid manually configuring slash command endpoints and an interactivity endpoint via the Slack App console. Which is to say, this infrastructure can never be fully automated (e.g. with Terraform) because you are forced into the console to configure these data points. I would love to be wrong about this.
Capability inconsistencies. A slack app can have any number of slash command URLs, but can only have one interaction URL. It is like they had the foresight to understand that developers would want to point different commands at different backends, but somehow missed the same logic for interaction inputs. I would love to understand more about this.
Interaction payloads. Maybe the worst part of trying to implement interactivity is handling the interaction payloads. There are three interaction types: Messages, Home Tab, and Modals. Their payloads have different schema and their callbacks fire at different times. For example, let's say you want to collect several user inputs and then send a single payload -- you know, a classic form. Message Interactions do not support forms, and instead every input fires the callback. Modals do support forms... so if you want to receive an aggregated user input payload (as you probably must in a serverless context), you are forced to use Modals. Modals, meanwhile, are implemented with an awkward API that does not even retain the channel id it came from (whereas channel id is always baked into a Message payload). Knowledge of the originating channel id is, of course, critical to sending the response back the user.
Slack developer documentation is a hot mess. For any given question you have about how to use Slack's developer APIs, there are probably three or seven official pages claiming to answer your question, they all cross-reference each other, and none of them really gets to the heart of your problem (I challenge you to look up how to build a Slack Interaction and come away with reasonable answer). There is no repository of curated infrastructure templates to help you set up on AWS, Azure, or wherever (and hence this article came to be). Most tellingly of all, Slack's official documentation is bifurcated from its GitHub presence, which makes it that much harder to connect the dots when explanations do not add up (or if you want to open an issue to rectify the documentation).

Conclusion

Slack does not make it easy to build out any Apps, and less so on serverless infrastructure, but if you bang your head on it long enough you can build some really useful functionality. My team has dramatically decreased its hand-holding overhead by giving our business user teammates easy-to-use self-service tools. I hope to follow up the architecture described in this article with a sample implementation sometime soon!

useAxios: React hook for any Axios call

Kevin White — Thu, 20 May 2021 02:40:01 +0000

useAxios() is a React hook that simplifies async fetching and state management. Source code and live example

Want to suggest an improvement? I'm all ears! Please file an issue or open a PR!

Usage

import React, { useState } from "react";
import { useAxios } from "./use-axios";

const App = () => {
  const [id, setId] = useState("1");
  const axiosConfig = { method: "get", timeout: 2500 };
  const { isLoading, isError, response } = useAxios(
    `https://pokeapi.co/api/v2/pokemon/${id}`,
    axiosConfig
  );

  return (
    {response?.data && <div>{data}</div>}
    {isLoading && <LoadingIcon/>}
    {isError && <ErrorMsg/>}
  );
};

Overview

useAxios is an Axios-specific implementation of my generic useAsyncFunc React hook.

One issue for async operations is when the return value is no longer required. For example, the user leaves the page (the requesting component is unmounted) or the user provides a new search query (the old search query's response is superfluous).

You might see an error like this:

Warning: Can't perform a React state update on an unmounted component. This is a no-op, but it indicates a memory leak in your application. To fix, cancel all subscriptions and asynchronous tasks in a useEffect cleanup function.

In these situations, we want to cancel the initial request. The browser Web API provides the AbortController interface; it is a controller object that allows you to abort one or more Web requests. Axios provides similar capability with the CancelToken class. CancelTokens are straightforward to implement if you are already using the Axios library. You read a little more about each implementation here.

useAxios

/**
 *
 * @param {string} url      - The url to call
 * @param {object} [config] - The axios config object; defaults to GET, etc
 * @returns {state}         - { isLoading, isError, response }
 */
const useAxios = (url, config) => {
  // useReducer manages the local complex state of the async func hook's lifecycle.
  // See the source code for the full reducer!
  // NOTE: it is easy to modify or expand the reducer to fit your needs.
  const [state, dispatch] = useReducer(axiosReducer, {
    isLoading: false,
    isError: false
  });

  useEffect(() => {
    // Declare Axios cancel token
    const source = CancelToken.source();

    // Define the axios call
    const callAxios = async () => {
      // Begin with a clean state
      dispatch({ type: "AXIOS_INIT" });

      try {
        // Straightforward axios call,
        // With cancel token inserted into config
        const response = await axios(url, {
          ...config,
          cancelToken: source.token
        });
        dispatch({ type: "AXIOS_SUCCESS", payload: response });
      } catch (err) {
        // Two options on error:
        // 1. If error is an axios cancel, simply return and move on
        // 2. For all other errors, assume async failure and dispatch failure action
        if (isCancel(err)) {
          console.log("Canceled request.");
          return;
        }
        dispatch({ type: "AXIOS_FAILURE" });
      }
    };

    // Invoke the defined axios call
    callAxios();

    // On unmount, cancel the request
    return () => {
      source.cancel("Operation canceled.");
    };

    // NOTE: here be dragon!
    // My instinct was include the axios config in this array, e.g. [url, config]
    // This causes an infinite re-render loop that I have not debugged yet :-/
  }, [url]);

  return state;
};

export default useAxios;

Conclusion

It is good to cancel superfluous requests so that they do not become memory leaks! I hope you find this example helpful.

useAsyncFunc: React hook for any async function

Kevin White — Thu, 13 May 2021 17:06:56 +0000

Source code and demo for generic async operation React hook. Live example.

Want to suggest an improvement? I'm all ears! Please file an issue or open a PR!

Usage

import useAsyncFunc from "useAsyncFunc";

const myAsyncFunc = (arg1, arg2) => {
  // do work
};

const App = () => {
  const [{ isLoading, isError, data }, setArgs] = useAsyncFn(myAsyncFunc, ['firstArg', 'secondArg']);

  return (
    {data && <div>{data}</div>}
    {isLoading && <LoadingIcon/>}
    {isError && <ErrorMsg/>}
  );
};

Overview

This useAsyncFunc React hook stands on the shoulders of giants. Robin Wieruch's excellent How to fetch data with React Hooks walks you step-by-step through the creation of a robust useDataApi hook, which provides an exhaustively capable data fetching hook.

The purpose of this post is to further build on that work by genericizing it to run any async function (and not just fetch(myUrl)).

useAsyncFunc

/**
 * @param {function} fn   - The asynchronous function to be called
 * @param {Array} fnArgs  - Optionally, the arguments to be passed to `fn`, expressed as an array
 * @param {*} initialData - Optionally, default value(s) to returned as `data`
 * @returns {[state, setArgs]}
 */
const useAsyncFunc = (fn, fnArgs = [], initialData) => {

  // useState manages the async func arguments.
  const [args, setArgs] = useState(fnArgs);

  // useReducer manages the local complex state of the async func hook's lifecycle.
  // See the source code for the full reducer!
  // NOTE: it'd be easy to modify the reducer to fit your needs.
  const [state, dispatch] = useReducer(asyncReducer, {
    isLoading: false,
    isError: false,
    data: initialData,
  });

  useEffect(() => {
    let didCancel = false;

    const callAsyncFn = async () => {
      // Begin each async func call with a clean slate.
      dispatch({ type: 'ASYNC_INIT' });

      try {
        // Because this is a generic hook for any async func,
        // simply call the function with the args!
        const result = await fn(...args);

        // Set success with result
        if (!didCancel) {
          dispatch({ type: 'ASYNC_SUCCESS', payload: result });
        }
      } catch (error) {
        // Otherwise, set failure
        if (!didCancel) {
          dispatch({ type: 'ASYNC_FAILURE' });
        }
      }
    };

    // Actual invocation
    callAsyncFn();

    // Cleanup function to optionally prevent setting state for unmounted component.
    // Ref: https://reactjs.org/docs/hooks-effect.html#example-using-hooks-1
    // Ref: https://www.robinwieruch.de/react-warning-cant-call-setstate-on-an-unmounted-component
    return () => {
      didCancel = true;
    };

    // useEffect will consider `fn` and `args` when deciding whether to skip a re-render.
    // In short, skip re-render if `fn` or `args` do not change.
  }, [fn, args]);

  // `state` provides the status updates: { isLoading, isError, data }
  // `setArgs` allows you to update the arguments passed to the async func
  return [state, setArgs];
};

Conclusion

Really, that is it! Again, this is a slight modification to genericize Robin Wieruch's already-thorough useDataApi() hook. My other small contribution is a basic test suite. Enjoy!