This is the third of a four-part series on writing a Discord “slash” command in Ruby using Google Cloud Functions. In previous parts, we deployed a Discord app to Google Cloud Functions, and added a command to a server using the Discord API. In this part, we actually implement the command, calling an external API and displaying results in the channel. It will illustrate how to respond to commands, and how to handle secrets such as API keys in production.

Previous articles in this series:

• Introduction
• Part 1
• Part 2

Responding to commands

When we left off in part 2, we had created a command in a Discord server, but hadn’t yet implemented the back end. We’ll do so now.

When someone invokes a command, an interaction request of type 2 gets sent to our webhook. The JSON data sent with this request will include the command that was sent, and any options that were provided. For our command, that includes a Scripture reference.

To start off, let’s update the Responder#respond method to recognize type 2, and call a new method handle_command that we will implement:

# responder.rb

# ...

class Responder

  # ...

  def respond(rack_request)
    raw_body = rack_request.body.read
    unless verify_request(raw_body, rack_request.env)
      # Discord expects a 401 response if the verification failed
      return [401,
        {"Content-Type" => "text/plain"},
        ["invalid request signature"]]
    end
    interaction = JSON.parse(raw_body)
    case interaction["type"]
    when 1
      # Ping
      {type: 1}
    when 2
      # Command
      handle_command(interaction)
    else
      [400,
        {"Content-Type" => "text/plain"},
        ["Unrecognized interaction type"]]
    end
  end

  # ...

end

Now for the handle_command method. Discord expects an interaction response JSON message in the HTTP response. Typically, the response includes a message that the command will then display in the Discord channel. We signal such a response by setting the “type” field to 4, and returning the text to display in a “content” field.

To start off, let’s construct a response by echoing back the Scripture reference that we were asked to look up. First we’ll write code to parse the interaction and get the option with name “reference”. For simplicity, we’ll just raise an exception (which Cloud Functions will translate to a 500 response) if the command data doesn’t have the expected format.

# responder.rb

# ...

class Responder

  # ...

  def reference_from_interaction(interaction)
    command_data = interaction["data"]
    unless command_data["name"] == "bible"
      raise "Unexpected command: #{command_data['name']}"
    end
    command_data["options"].each do |option|
      if option["name"] == "reference"
        return option["value"]
      end
    end
    raise "No reference option found"
  end

  # ...

end

Now we’ll use that to implement handle_command to return a message to display. Remember that if we return a hash from a Cloud Function, it is automatically rendered as JSON in the HTTP response.

# responder.rb

# ...

class Responder

  # ...

  def handle_command(interaction)
    reference = reference_from_interaction(interaction)
    {
      type: 4,
      data: {
        content: "You looked up #{reference}"
      }
    }
  end

  # ...

end

Now let’s redeploy the function:

$ bundle install
$ gcloud functions deploy discord_webhook \
    --project=$MY_PROJECT --region=us-central1 \
    --trigger-http --entry-point=discord_webhook \
    --runtime=ruby27 --allow-unauthenticated

And when we go back to our Discord channel and invoke the command… success!

Calling an external API

Now it’s time to implement the main functionality of our command, that of actually returning Scripture content from an API. We’ll access a suitable API, show how to manage its API key in production using Google Secret Manager, and write code to make API calls and include the results in the command response.

Signing up with API.Bible

API.Bible is a basic Scripture lookup API that boasts thousands of versions and translations, and allows reference lookup and keyword search. Their free tier includes access to public domain translations like the World English Bible, and a modest number of calls per day that will be more than adequate for my church’s needs.

I created an account and registered an application. The site claims that new accounts are subject to approval, but it looks like, since mine was for non-commercial use by a small church, it pretty much went through immediately. As part of my account, they gave me an API key. This is effectively a password to my account, and I need to handle it like any secret, keeping it out of code, source control, and any unencrypted communication.

The API website also includes “live” reference documentation that includes the ability to make API calls directly from the web page. From here, I identified the “passages” API call as the likely call I’ll need for my Discord command. The resource path for the request includes the ID of the Bible version, and the reference in a specific format. Then the response is a JSON payload including the passage content. Looks good, let’s experiment with it!

Calling the API

As we did in part 2 with the Discord API, we’ll create a simple client class for the Bible API. We’ll start with a helper method that makes HTTP calls and handles results. This helper will also set the needed API key header. As we did with the Discord client, we’ll pass in the API key as a constructor argument.

# bible_api.rb

require "faraday"
require "json"

class BibleApi
  def initialize(api_key:)
    @api_key = api_key
  end

  private

  def call_api(path, params: nil)
    faraday = Faraday.new(
      url: "https://api.scripture.api.bible",
      headers: {
        "api-key" => @api_key
      }
    )
    response = faraday.get(path) do |req|
      req.params = params if params
    end
    body = JSON.parse(response.body)
    unless response.status == 200 && body["data"]
      raise body["message"] || "Unknown error"
    end
    body["data"]
  end
end

Now we’ll implement a method for the “passages” call. It will take the reference as an argument. For simplicity, we’ll just hard-code the Bible ID for a reasonable translation, the World English Bible, Ecumenical version.

# bible_api.rb

# ...

class BibleApi

  WEB_BIBLE_ID = "9879dbb7cfe39e4d-01"

  # ...

  def lookup_passage(reference)
    params = {
      "content-type" => "text",
      "include-titles" => "false"
    }
    resource = "/v1/bibles/#{WEB_BIBLE_ID}/passages/#{reference}"
    response_object = call_api(resource, params: params)
    response_object["content"]
  end

  # ...

end

We can now test this by creating a simple command-line script using Toys. As before, we’ll pass the API key in on the command line, to keep it out of our code. We’ll also pass the Scripture reference on the command line.

# .toys.rb

tool "lookup" do
  flag :api_key, "--api-key TOKEN"
  required_arg :reference

  def run
    require_relative "bible_api"
    client = BibleApi.new(api_key: api_key)
    result = client.lookup_passage(reference)
    puts result
  end
end

# ... and other scripts from before

Note that the Bible API uses a particular format for Scripture references. We need to use that format when we test our API client:

$ toys lookup --api-key=$MY_API_KEY JHN.1.1
     [1] In the beginning was the Word, and the Word was with God, and the Word was God.

Calling the API from the webhook

Now that we have the Bible API working, we can write the rest of the code to integrate it into our webhook. We’ll construct a Bible API client in our Responder class, and rewrite our Responder#handle_command method to call it to get the passage content.

# responder.rb

# ...

require_relative "bible_api"

class Responder

  # ...

  def initialize(api_key:)
    # Create a verification key (from part 1)
    public_key = DISCORD_PUBLIC_KEY
    public_key_binary = [public_key].pack("H*")
    @verification_key = Ed25519::VerifyKey.new(public_key_binary)

    # Create a Bible API client
    @bible_api = BibleApi.new(api_key: api_key)
  end

  # ...

  def handle_command(interaction)
    # Call the Bible API to get the content to return
    reference = reference_from_interaction(interaction)
    content = @bible_api.lookup_passage(reference)
    {
      type: 4,
      data: {
        content: "#{reference}\n#{content}"
      }
    }
  end

  # ...

end

Okay, we’re almost there. We have a working Bible API client, and our webhook command handler calls it to get content, and returns it to Discord for display. There’s just one problem. The Bible API client needs an API key. We’ve added an api_key argument to the Responder constructor so we can pass it down, but where does the Responder get the API key from? Remember from part 1 that a Responder is created when the function starts up:

# app.rb

require "functions_framework"
require_relative "responder"

FunctionsFramework.on_startup do
  set_global(:responder, Responder.new(api_key: "???"))
end

FunctionsFramework.http "discord_webhook" do |request|
  global(:responder).respond(request)
end

Somehow we need to pass a secret into this app, and do so safely and securely. Let’s talk about how to do that.

Handling secrets

There are many ways to handle secrets without exposing them in our code. In the past, it has been common to set secrets in environment variables, or store them in special source files that we exclude from source control. These techniques work, but each has its flaws. Environment variables can be logged by accident or read by malicious code. Files can be accessed by anyone with access to the deployment image.

The technique we’ll implement here uses a local file for local testing, but uses a secret handling service, Google Cloud Secret Manager, for production. When we test locally, the secrets will be present in a local file that is excluded from source control, letting us test without having to make calls to a cloud service. When we deploy, however, we exclude this file, avoiding the security risk of having the file present in our deployment image. Instead, in production, we load the secret directly into memory from the Secret Manager service.

So the basic logic is: first check for a file, and if that’s not present, invoke Secret Manager. We’ll implement this logic in a new class, Secrets.

First, we’ll add the client library for Secret Manager to our Gemfile:

# Gemfile

source "https://rubygems.org"

gem "ed25519", "~> 1.2"
gem "faraday", "~> 1.4"
gem "functions_framework", "~> 0.9"
gem "google-cloud-secret_manager", "~> 1.1"

Don’t forget to bundle install to ensure your Gemfile.lock gets updated.

Now let’s implement the Secrets class. In the code below, make sure you substitute the name of your Google Cloud project as the value of thePROJECT_ID constant. I’ve also chosen a name for the secret in the SECRET_NAME constant, but you can use a different name if you want.

# secrets.rb

require "psych"
require "google/cloud/secret_manager"

class Secrets
  SECRETS_FILE = File.join( __dir__ , "secrets.yaml")
  SECRET_NAME = "discord-bot-secrets"
  PROJECT_ID = "my-project-id"

  def initialize
    if File.file?(SECRETS_FILE)
      load_from_file
    else
      load_from_secret_manager
    end
  end

  attr_reader :bible_api_key

  def load_from_file
    secret_data = Psych.load_file(SECRETS_FILE)
    load_from_hash(secret_data)
  end

  def load_from_secret_manager
    secret_manager = Google::Cloud::SecretManager.secret_manager_service
    version_name = secret_manager.secret_version_path(
      project: PROJECT_ID, secret: SECRET_NAME, secret_version: "latest"
    )
    version_data = secret_manager.access_secret_version(name: version_name)
    secret_data = Psych.load(version_data.payload.data)
    load_from_hash(secret_data)
  end

  def load_from_hash(hash)
    @bible_api_key = hash["bible_api_key"]
  end
end

Now we can invoke this class from our function and use it to retrieve the API key:

# app.rb

require "functions_framework"
require_relative "responder"
require_relative "secrets"

FunctionsFramework.on_startup do
  secrets = Secrets.new
  set_global(:responder, Responder.new(api_key: secrets.bible_api_key))
end

FunctionsFramework.http "discord_webhook" do |request|
  global(:responder).respond(request)
end

To get this to work for local testing, we just need to create the “secrets.yaml” file, substituting your actual API key:

# secrets.yaml

bible_api_key: "mybibleapikey12345"

Make sure it stays out of source control. I use git, so I’ll add a .gitignore file:

# .gitignore

secrets.yaml

We also want to avoid deploying this file. By default, Cloud Functions honors .gitignore when deploying, so it will do this by default. But if you don’t use git, or you have more complex requirements, you can configure which files are omitted from deployment by providing a gcloudignore file.

In production, we want to read this data from Secret Manager, so we’ll need to upload it to Secret Manager first, using the Google Cloud command line:

$ gcloud secrets create discord-bot-secrets \
    --project=$MY_PROJECT --data-file=secrets.yaml

There’s one more thing we need to do. We’ve written code that loads the secrets from Secret Manager in production, but we need to grant that code access to Secret Manager. To do so, we note that when an app runs in Cloud Functions, by default it uses a particular service account called $MY_PROJECT@appspot.gserviceaccount.com to talk to Google Cloud APIs. So we need to grant that service account access to the secret:

$ gcloud secrets add-iam-policy-binding discord-bot-secrets \
    --project=$MY_PROJECT --role=roles/secretmanager.secretAccessor \
    --member=serviceAccount:$MY_PROJECT@appspot.gserviceaccount.com

For both the above commands, make sure the project name and the secret name discord-bot-secrets matches the corresponding names you used in the constants in the Secrets class.

Now we can redeploy our Function, and try it out.

Woot!

Now what?

When I got to this point, things were mostly working, but I encountered a few issues.

The bot wasn’t very stable. Sometimes, the first time I tried running a command, I’d get a failure message, but then the next time it would work. Oddly, when I looked at the logs in Cloud Functions, everything seemed to be fine, even for the supposedly failed request.

The cause, it turns out, was that Discord will wait for a maximum of 3 seconds for a response, and if it doesn’t receive one in a timely manner, it will give up and display an error. This can sometimes be a challenge for a webhook that makes API requests to external services, if those calls may incur significant latency. It’s also a particular issue for serverless hosting. An environment like Cloud Functions might shut down your app if it’s not in use, in order to conserve resources. Then, the next time it receives a request, it might take some time to boot back up. This is called a “cold start” in serverless lingo, and it can be a challenge for app developers to keep it low. In addition to calling the Bible API, our app makes a call out to the Secret Manager during cold start, and sometimes the latency of that additional call is enough to push the entire cold start over the 3 second threshold.

Additionally, the syntax that the Bible API requires to specify the scripture reference, wasn’t very nice. Culturally, we’re used to a syntax like “John 1:1-5” rather than “JHN.1.1-JHN.1.5”. So I had to write a parser for “human” references, and convert them to the format needed by the Bible API.

Finally, displaying longer passages would also fail. There was no way, for example, to display the entire first chapter of John. Even though the Bible API would return the passage content, it turns out that Discord imposes a 2000-character limit on message length, and it refused to post a message that is any longer.

So I had a working command, but I wasn’t really satisfied with the results. Parsing reference syntax is just programming, and I’ll leave improving it as an exercise for the reader. But the latency and the longer passages were a real usability hindrance. The good news is, there are solutions, and we’ll explore them in part 4.