DEV Community: Daniel Azuma

Beware Twitter/X

Daniel Azuma — Mon, 04 Aug 2025 00:00:00 +0000

So the TL;DR here is simply: please unfollow and disregard any account on Twitter/X that claims to be me. I am not posting on that disgraced platform, and never will in the future. Earlier this year, my old username was taken over by a bot— one that I suspect was actually installed and run by Twitter itself— that spewed, with my name and profile, a deluge of apparently AI-generated nonsense that I would never say myself. I’ve been able to get that content removed for now, but with Musk at the helm, who knows what the platform might do in the future.

The fall of Twitter

An eon ago, I gave a talk at RailsConf 2013 on philosophical issues around technology, and stirred the pot a bit with my opinion of Twitter. It was, I thought, a platform with a net negative effect on culture due to how it intentionally filled public discourse with noise, and at the same time, an example of how technology controls us since I felt professionally obligated to maintain a presence on it anyway.

That was, of course, many years ago, at the height of Twitter’s popularity and influence, long before Elon Musk’s takeover and the subsequent business, technical, and political issues now surrounding it. You can imagine what I think about it now.

(And yes, I’m intentionally deadnaming Twitter. Its new identity is what is dead to me: a zombification of what was once, if a societal net-negative, at least an interesting and influential techno-cultural phenomenon.)

So it should come as no surprise that I was one of perhaps many who chose to delete their accounts after the recent election and regime change in the US.

My subsequent experience should serve as a bit of a cautionary tale for anyone else considering that step in the future.

The consequences of deleting your Twitter account

In hindsight, I probably should have read the terms of service more closely and thought about the potential consequences. Among other things, Twitter’s terms of service state:

Once your account is deleted after the 30-day deactivation window, your username will be available for registration by other X accounts.

(From How to deactivate your account, retrieved Aug 4, 2025)

This should be an instant red flag, as it implies that any entity, including a hostile one, can usurp your old username and impersonate you.

And sure enough, a bit over a month after I deleted my account, I suddenly noticed a deluge of new content on it, from puzzling announcements of the imminent commercial release of random open source projects, to shills of nonexistent memecoins, to retweets of accounts that real me might find disreputable or even offensive. Worse, the account still had all its previous followers, and the description and mug photo remained as I had originally set it up. In all, it was nearly impossible to tell the account had been deleted, unless you know me and know what actually to expect of my posting habits.

In other words, there was now a Twitter account masquerading as me, with content that was at best embarrassing, and at worst reputation-damaging. I’m also not alone in this; a quick Reddit search reveals a broad swath of similar experiences.

Now, I do not know for certain what actually took place with the account. It is possible a real user took it over, although for what purpose I can’t fathom. However, I suspect Twitter itself simply decided to spew AI-generated garbage from deleted but well-followed accounts in an attempt to maintain the illusion of activity and relevance. Which, if true, would be an interesting instance of Twitter violating their own terms of use, by creating what is effectively an impersonation account.

I eventually complained to Twitter support. To their credit, they disabled the account within a few days. The account page now says the account is “suspended” for “rule violation” which I, uhh, guess is better than before. But now I have zero trust in what they might do next. What is to prevent Musk’s Twitter-zombie from unsuspending the account in the future and proceeding to impersonate me again?

Where to go from here

If you still for some reason have a Twitter account, and are still following my old username, please unfollow it. It is not me, and if there was any remote possibility of my ever rejoining the platform before, there isn’t anymore.

And if you do still have an account and are considering deleting it, consider this a bit of a cautionary tale. It might be a good idea to take steps to strip the account of any ties to yourself and your profile before taking that action.

Recent political, social, and tech industry developments have been difficult to say the least. I can consider myself lucky that I haven’t (yet) been impacted as deeply as some. The Musk-ification of Twitter and subsequent impact on people like myself who once felt obligated to use it for work, has been annoying, but at least not life- or livelihood-threatening. I pray for those not so lucky, and hope that, sometime soon, we’ll all come back to our senses and turn away from the insanity that seems to have gripped us.

Building a Discord Command in Ruby on Google Cloud Functions: Part 4

Daniel Azuma — Tue, 04 May 2021 00:00:00 +0000

This is the last of a four-part series on writing a Discord “slash” command in Ruby using Google Cloud Functions. In previous parts, we created a Discord command that displays a short Scripture passage, and implemented it in a webhook. In this part, we show how to split a longer passage across multiple messages, by triggering a second Function that makes Discord API calls. It will illustrate how to use Google Cloud Pub/Sub to run background jobs in Cloud Functions, combining an event architecture with the Discord API to implement a more complex application.

Previous articles in this series:

The challenge: size and timing

So far in this series, we’ve accomplished quite a bit. We’ve written a Discord app in Ruby. We’ve integrated with the Discord API and the Bible API. We’ve added a Discord command to a server, and implemented it in our app. And we’ve followed best practices for handling secrets such as API keys.

However, Part 3 left off with two significant issues that are impairing the usability of our Discord command.

First, Discord imposes a 2000-character limit on message size. This means our command response cannot display a Scripture passage longer than 2000 characters. It can display John 1:1-5, for example, but not the first chapter of John in its entirety.

Second, if the webhook has been idle for a while, the first call to it sometimes fails because it takes too long. This happens because Cloud Functions may need to spin up a new instance of our webhook to handle the request, and that involves not only starting up the Ruby process, but also making calls to Secret Manager to obtain API credentials, in addition to the latency of the Bible API itself. Together, this “cold start” latency sometimes takes longer than the 3 seconds allowed by Discord.

One way to address these problems is to defer processing of the command. Discord’s documentation describes this technique, which involves sending back an initial response quickly, but then continuing processing in the background and posting further updates to the response later. For our command, we could use a background process to retrieve a long passage, break it up into sections that are under the 2000-character limit, and issue Discord API calls to post each section in a separate message to the channel.

To implement this kind of “deferred” processing in a serverless environment, we’ll have our app post an event to itself, triggering the background task in a separate Function. We could do so using an event broker such as Apache Kafka, or we can remain within Google’s ecosystem by using a service like Cloud Pub/Sub.

The following diagrams illustrate how this works. Previously we had a single responder that makes lengthy calls and can return only a single message response.

Now we’ll modify the responder to instead just post an event to Cloud Pub/Sub, and return a message saying “I’m working on it…” Then, the Pub/Sub event will trigger another Cloud Function that performs the actual work. This Pub/Sub initiated function is not subject to the 3 second time limit, and can post an arbitrary number of messages to the channel by calling the Discord API.

That’s our goal for part 4! Let’s get started.

Deferred processing using pub/sub

These days, the excitement around serverless often has to do with DevOps—or more specifically, the potential to reduce or simplify DevOps. It’s true that DevOps is way too hard, and we’re making progress on improving it, but I think the long-term impact of functions-as-a-service will actually be on software architecture. FaaS has a close affinity with evented systems. As applications get more distributed, and we see more interest in evented control flow to manage that complexity, Functions has the potential to make that really easy.

Acknowledging that trend, Google Cloud Functions already has tight integration with Google’s Pub/Sub service. You can deploy functions that are triggered on Pub/Sub messages, and we’ll use that strategy to implement deferred processing.

Deploying a pub/sub subscriber

Before we can handle events coming from Pub/Sub, we need to create a topic to publish to.

$ gcloud pubsub topics create discord-bot-topic --project=$MY_PROJECT

Now we’ll write and deploy a second function for the deferred task.

First we’ll add the new function to app.rb. Because it handles events coming from Pub/Sub, it takes a CloudEvent (instead of a Rack HTTP request) as the argument. For now we’ll log the event so that we can see when events are triggered.

# app.rb

# ...

# Existing webhook function (http)
FunctionsFramework.http "discord_webhook" do |request|
  global(:responder).respond(request)
end

# New subscriber function (cloud event)
FunctionsFramework.cloud_event "discord_subscriber" do |event|
  logger.info("Received event: #{event.data.inspect}")
end

Note that our app now defines multiple functions. When you deploy to Cloud Functions, you deploy one function at a time, and you must specify which one to deploy by name. So to deploy this new Function, we identify it by its name "discord_subscriber" and indicate that it should be triggered from the Pub/Sub topic we created.

$ gcloud functions deploy discord_subscriber \
    --project=$MY_PROJECT --region=us-central1 \
    --trigger-topic=discord-bot-topic --entry-point=discord_subscriber \
    --runtime=ruby27

This time, instead of triggering on http requests, we configure this function to trigger when a message is published to our pubsub topic. We can test this by publishing to the topic manually, and then looking at the Cloud Functions logs to see the log entry written by our function.

$ gcloud pubsub topics publish discord-bot-topic \
    --project=$MY_PROJECT --message=hello

Publishing an event

But what we actually want is for our webhook to publish the event. So we’ll start by adding the client library for the Pub/Sub API to our Gemfile.

Now, normally, I’d recommend using the main google-cloud-pubsub gem for interacting with Pub/Sub, but for this app, we’re actually going to use the lower-level google-cloud-pubsub-v1 library. This is to improve cold start time. The higher-level library takes measurably longer to load in the Cloud Functions environment, and with a three-second budget, any milliseconds we can shave off will be useful. Addintionally, for our purposes, we only need to publish a single message, and don’t need the advanced subscription management code in the higher-level library.

So let’s add the library to our Gemfile:

# Gemfile

source "https://rubygems.org"

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

After bundle installing, we’ll update our Responder class to publish a message to trigger our job. First, we construct a pubsub client in the initialize method. Again, we’re using the low-level publisher client.

# responder.rb

# ...

require "google/cloud/pubsub/v1/publisher"

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 (from part 3)
    @bible_api = BibleApi.new(api_key: api_key)

    # Create a Pub/Sub client
    @pubsub = Google::Cloud::PubSub::V1::Publisher::Client.new
  end

  # ...

end

Now we can enhance the handle_command method to publish an event. For now we’ll keep the existing functionality (i.e. calling the Bible API and returning its content), and we’ll just provide additional code to publish to Pub/Sub.

# responder.rb

# ...

class Responder

  PROJECT_ID = "my-project-id"
  TOPIC_NAME = "discord-bot-topic"

  # ...

  def handle_command(interaction)
    reference = reference_from_interaction(interaction)

    # Publish a simple pubsub event
    topic = "projects/#{PROJECT_ID}/topics/#{TOPIC_NAME}"
    attributes = {message: "Looked up #{reference}"}
    @pubsub.publish(topic: topic, messages: [{attributes: attributes}])

    # We'll leave this here for now.
    content = @bible_api.lookup_passage(reference)
    {
      type: 4,
      data: {
        content: "#{reference}\n#{content}"
      }
    }
  end

  # ...

end

Now let’s redeploy the webhook function to put this change into production. Recall the command to deploy the webhook function:

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

After redploying, we can now invoke the comamnd in Discord, and now in addition to seeing the response in Discord, we can look at the Cloud Function logs and see it trigger the subscriber function.

So far so good—we now know how to trigger background tasks in Cloud Functions using Pub/Sub. Next, we’ll use this mechanism to support splitting a long passage across multiple chat postings.

Creating a multi-part response

For commands that require a longer time to process, or that need to post mulitple responses to the channel, Discord recommends returning an initial “deferred” response (which displays a “thinking” message in the channel) and following it up with additional responses sent via the Discord API. We’ll now change our response to a deferred response, and move the Scripture lookup logic into the Pub/Sub subscriber.

Sending a deferred response

A deferred response is simply a JSON message with the type set to 5. We’ll delete our code that calls the Bible API, and just return a static response:

# responder.rb

# ...

class Responder

  # ...

  def handle_command(interaction)
    reference = reference_from_interaction(interaction)

    # Publish a simple pubsub event
    topic = "projects/#{PROJECT_ID}/topics/#{TOPIC_NAME}"
    attributes = {message: "Looked up #{reference}"}
    @pubsub.publish(topic: topic, messages: [{attributes: attributes}])

    # Return a Type 5 response
    { type: 5 }
  end

  # ...

end

Next, in order to perform the logic, the deferred task needs two pieces of information. First is, of course, the scripture reference to look up. And second is the interaction token which lets us associate additional responses we send, to the original request. So we’ll update the Pub/Sub message to include these two pieces of information:

# responder.rb

# ...

class Responder

  # ...

  def handle_command(interaction)
    reference = reference_from_interaction(interaction)

    # Publish a pubsub event including the reference and interaction token
    topic = "projects/#{PROJECT_ID}/topics/#{TOPIC_NAME}"
    attributes = {reference: reference, token: interaction["token"]}
    @pubsub.publish(topic: topic, messages: [{attributes: attributes}])

    # Return a Type 5 response
    { type: 5 }
  end

  # ...

end

Finally, since we no longer use the BibleApi class here in the Responder, we no longer need to pass in the api_key. So we can remove that code from the Responder’s initialize method. And we can remove the on_startup code that loads the API key from secrets.

# responder.rb

# ...

require "google/cloud/pubsub/v1/publisher"

class Responder

  # ...

  def initialize
    # 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)

    # We can now delete this code
    # @bible_api = BibleApi.new(api_key: api_key)

    # Create a Pub/Sub client
    @pubsub = Google::Cloud::PubSub::V1::Publisher::Client.new
  end

  # ...

end

Deploying this webhook update, we can see the effect on the command. It now displays a “thinking” message in response to the “type 5” response:

Creating a deferred task handler

Now that we’re going to write some non-trivial code for the Pub/Sub-triggered Function, let’s create a class for it, like we did previously for the Responder class.

# deferred_task.rb

class DeferredTask
  def initialize
    # TODO
  end

  def handle_event(event)
    # TODO
  end
end

Now to create a DeferredTask object on cold start, we can add code to the on_startup block, just as we did for the Responder class. But hang on… we now have two separate functions—the webhook uses only the Responder class but not DeferredTask, and the subscriber uses only the DeferredTask class but not Responder. It would be nice to for each function to construct only the objects that it needs. This will be especially important in the next section because the DeferredTask will require a round-trip to the Secret Manager, and we’d like to avoid needlessly incurring that latency in the webhook Function.

To ensure each Function constructs only the objects that it needs, we can use lazy initialization of globals. The Ruby Functions Framework supports this feature by passing a block to set_global.

# app.rb

FunctionsFramework.on_startup do
  # Define how to construct a Responder
  set_global(:responder) do
    # This does not actually run until the discord_webhook
    # function actually accesses it.
    require_relative "responder"
    Responder.new
  end

  # Define how to construct a DeferredTask
  set_global(:deferred_task) do
    # This does not actually run until the discord_subscriber
    # function actually accesses it.
    require_relative "deferred_task"
    DeferredTask.new
  end
end

# Call the Responder from the webhook function
FunctionsFramework.http "discord_webhook" do |request|
  global(:responder).respond(request)
end

# Call the DeferredTask from the pubsub subscriber function
FunctionsFramework.cloud_event "discord_subscriber" do |event|
  global(:deferred_task).handle_event(event)
end

Notice how even the require instructions are executed lazily, ensuring the libraries are loaded only if they’re actually going to be used. This can often make a significant difference in a serverless or container-based environment where file system access may be relatively slow.

Passing secrets to the deferred task

Now for the functionality of DeferredTask. We’ll need to call both the Bible API and the Discord API, so we’ll need both the Bible API key and the Discord Bot Token. In Part 3, we set up the Bible API key in a local file for local testing, and uploaded it to the Google Secret Manager for production. Now let’s enhance that Secrets class to add support for the Discord Bot Token:

# secrets.rb

# ...

class Secrets

  # ...

  attr_reader :bible_api_key
  attr_reader :discord_bot_token

  # ..

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

Now add discord_bot_token to the secrets.yaml file. (Once again, you can find the token in your bot’s page in the Discord developer console.)

# secrets.yaml

bible_api_key: "mybibleapikey12345"
discord_bot_token: "mydiscordbottoken12345"

And upload the updated file to Secret Manager:

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

Now let’s update our startup code to access these secrets and pass them into the DeferredTask constructor:

# app.rb

# ...

FunctionsFramework.on_startup do

  # ...

  # Define how to construct a DeferredTask
  set_global(:deferred_task) do
    # This does not actually run until the discord_subscriber
    # function actually accesses it.
    require_relative "secrets"
    require_relative "deferred_task"
    secrets = Secrets.new
    DeferredTask.new(api_key: secrets.bible_api_key,
                     bot_token: secrets.discord_bot_token)
  end
end

# ...

# deferred_task.rb

require_relative "bible_api"
require_relative "discord_api"

class DeferredTask

  def initialize(api_key:, bot_token:)
    @bible_api_client = BibleApi.new(api_key: api_key)
    @discord_api_client = DiscordApi.new(bot_token: bot_token)
  end

  # ...

end

Now that we’ve accessed the secrets and constructed the needed clients, we’re ready to implement the task.

Sending multiple ressages

Our DeferredTask will make two types of calls to the Discord API. First, we’ll call Edit Original Interaction Response to update the original response (which was a Type 5 “thinking” message) to indicate that the bot is done “thinking” and is ready to display content. Then we’ll call Create Followup Message potentially multiple times, to post messages with Scripture content.

First, let’s implement those calls in our Discord API client:

# discord_api.rb

# ,,,

class DiscordApi

  # ...

  def edit_interaction_response(interaction_token, content)
    data_json = JSON.dump({content: content})
    headers = {"Content-Type" => "application/json"}
    call_api("/webhooks/#{@client_id}/#{interaction_token}/messages/@original",
             method: :patch, body: data_json, headers: headers)
  end

  def create_followup(interaction_token, content)
    data_json = JSON.dump({content: content})
    headers = {"Content-Type" => "application/json"}
    call_api("/webhooks/#{@client_id}/#{interaction_token}",
             method: :post, body: data_json, headers: headers)
  end

  # ...

end

And finally, implement the logic in DeferredTask. For simplicity, this code will naively split the content into 2000-character chunks. For a better experience, we’d probably want to split on word boundaries, or even better, verse boundaries.

# deferred_task.rb

class DeferredTask

  # ...

  def handle_event(event)
    # Get data from the Pub/Sub message
    attributes = event.data["message"]["attributes"]
    reference = attributes["reference"]
    interaction_token = attributes["token"]

    # Get the content from the Bible API
    full_content = @bible_api_client.lookup_passage(reference)

    # Edit the original interaction response to signal we're done "thinking"
    @discord_api_client.edit_interaction_response(
      interaction_token, "Looked up #{reference}")

    # Split the content into 2000-character sections and send Discord meessages
    full_content.scan(/.{1,2000}/m) do |section|
      # Space API calls out a bit, to avoid Discord's rate limiting.
      sleep 0.5
      @discord_api_client.create_followup(interaction_token, section)
    end
  end

end

Redeploy both the webhook and the subscriber, and our final app is ready!

Now what?

We now have a working, nontrivial Discord command, running in Google Cloud Functions! We’ve also covered some of the key techniques in a robust serverless app, including handling secrets in production, and using a pub/sub system to schedule tasks.

We do still have a few TODOs, which I will leave as “exercises for the reader”. For example:

It would make for a better experience to parse “normal” Scripture reference syntax such as “Matthew 1:2-3” rather than forcing users to use the Bible API’s reference format. When I wrote this app for my church, I also used a string distance metric to detect book name abbreviations such as “Matt” or “Mt”.
Currently, if the Bible API returns an error (e.g. because the Scripture reference was invalid), our BibleApi client raises an exception. This causes the deferred task function to terminate, but the user doesn’t see any indication of this in the discord channel. It would be a good idea to catch any exceptions and post an error message to the channel.
It would be nice to split content into sections on verse boundaries rather than just taking 2000-character chunks. When I wrote this for my church, I actually passed an option to the Bible API call that causes it to return the passage in semantic structured JSON rather than a simple string. I then had to parse that data structure to construct a displayable string, but because it was structured data, I could extract the exact verse boundaries, and customize the output format.

Additionally, there are alternative approaches that could be explored. One might consider, for example, using a background task manager such as Google Cloud Tasks instead of Pub/Sub to schedule the deferred task, and there are pros and cons to that approach. Discord also supports receiving events via WebSocket rather than a webhook. This option could provide much better performance, but would require reworking much of the design and deployment of the app, and may increase the cost of running it.

But overall, the techniques that we’ve covered should provide a good foundation for writing a variety of serverless applications using Google Cloud Platform. It should also provide a good set of getting-started information on writing Discord apps. I hope it was helpful!

Building a Discord Command in Ruby on Google Cloud Functions: Part 3

Daniel Azuma — Mon, 03 May 2021 00:00:00 +0000

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:

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.

Building a Discord Command in Ruby on Google Cloud Functions: Part 2

Daniel Azuma — Sun, 02 May 2021 00:00:00 +0000

This is the second of a four-part series on writing a Discord “slash” command in Ruby using Google Cloud Functions. In the previous part, we set up a Discord application and deployed its webhook to Google Cloud Functions. In this part, we investigate how to add a command to a Discord channel. It will illustrate how to authenticate and interact with the Discord API, how to use it to add a command to a Discord server, and demonstrate some nice tools for invoking these tasks from the command line.

Previous articles in this series:

Installing on a Discord server

In part 1, we set up a Discord application. But to make commands available in a Discord server, we’ll need to add our application to the server.

First, we’ll create a Bot user for the application. According to the Discord documentation, this is not always necessary for slash commands, but in our case we’ll need it later to make additional API calls. Back in the application page in the Discord Developer console, under the Bot tab, click “Add Bot.”

Next, we need to add the bot to a Discord server (also known as a “guild” in the Discord API). More precisely, we’re granting it permissions in the guild to behave as a bot user and to respond to commands.

Discord’s documentation shows how you can authorize a bot via an OAuth2 flow. If you have “manage server” permissions on the guild, you can go to a particular page and grant guild permissions to the bot. The URL for that page looks something like this:

https://discord.com/api/oauth2/authorize?client_id=MY_APPLICATION_ID&scope=bot%20applications.commands

Replace MY_APPLICATION_ID with the application ID from the Discord application’s page in the Discord developer console.

On the authorization page, choose the server from the dropdown, and authorize the application. Once this is done, the bot will show up as a user in the server. Behind the scenes, it will have the bot and applications.commands permissions that it will need to implement commands.

Creating a command

Next we’ll use the bot to create a command on the Discord server. This requires making calls to the Discord API. In this section, I’ll demonstrate how to call the API, provide credentials with those calls, and perform them from the command line.

Toys Scripts

I kind of wish Discord had a UI in its console for registering and managing commands, or at least an official CLI that will do so. As it is, creating a command is pretty involved and you pretty much have to write code to make an API call. To make it a bit easier to invoke this code, we’ll use the Toys gem to write quick command line scripts. Toys works similar to the familiar tool Rake, but is designed specifically for writing command line tools rather than make-style dependencies.

$ gem install toys

Writing a hello-world script is simple. Create a file called .toys.rb (the leading period is important.)

# .toys.rb

tool "hello" do
  def run
    puts "Hello, world!"
  end
end

The script can be run using:

$ toys hello
Hello, world!
$

Below, we’ll use scripts like this to run code that talks to the API.

Writing an API client

There are a few gems out there for Discord—I briefly looked into discordrb—but the needs of this bot are simple, and it’s instructive to roll your own client. Start by adding the HTTP client library Faraday to your Gemfile:

# Gemfile

source "https://rubygems.org"

gem "ed25519", "~> 1.2"
gem "faraday", "~> 1.4"
gem "functions_framework", "~> 0.9"

Then start a basic API client class. First, a helper method that makes different kinds of API calls and handles results.

# discord_api.rb

require "faraday"
require "json"

class DiscordApi

  private

  def call_api(path,
               method: :get,
               body: nil,
               params: nil,
               headers: nil)
    faraday = Faraday.new(url: "https://discord.com")
    response = faraday.run_request(method, "/api/v9#{path}", body, headers) do |req|
      req.params = params if params
    end
    unless (200...300).include?(response.status)
      raise "Discord API failure: #{response.status} #{response.body.inspect}"
    end
    return nil if response.body.nil? || response.body.empty?
    JSON.parse(response.body)
  end
end

Next, let’s write a method that lists the commands defined in a server by a Discord application.

# discord_api.rb

require "faraday"
require "json"

class DiscordApi
  DISCORD_APPLICATION_ID = "838132693479850004"
  DISCORD_GUILD_ID = "828125771288805436"

  def initialize
    @client_id = DISCORD_APPLICATION_ID
    @guild_id = DISCORD_GUILD_ID
  end

  def list_commands
    call_api("/applications/#{@client_id}/guilds/#{@guild_id}/commands")
  end

  private

  # def call_api...

end

The DISCORD_APPLICATION_ID is the Application ID of the Discord app (from the application’s general information page in the Discord developer console). The DISCORD_GUILD_ID is the ID of the Discord server, which is part of the server URL. Replace these with the values for your app. These are not secret values, and are safe to have in code, although normally you might want to read them from environment variables or a config file.

Now it should be easy to write a quick Toys script to call this method.

# .toys.rb

tool "list-commands" do
  def run
    require_relative "discord_api"
    result = DiscordApi.new.list_commands
    puts JSON.pretty_generate(result)
  end
end

And try running it:

$ toys list-commands
RuntimeError: Discord API failure: 401 "{\"message\": \"401: Unauthorized\", \"code\": 0}"
$

So that didn’t quite work. We got a 401 Unauthorized result from the API call. And of course that makes sense: we need to provide credentials, otherwise anyone can access our commands.

Authorizing Discord API calls

Discord uses a variety of OAuth2 flows for authorization, and these can of course be complicated, especially for applications that need to act on behalf of other users. For our case, however, a simple flow will work: authorizing as the bot user.

Each bot is assigned a bot token that it can use to authenticate to the Discord API. The bot token is a secret value; it’s essentialy the bot’s password. If you own a bot, you can find it on the bot’s page in the Discord developer console. Find your Discord application, navigate to the “Bot” tab, and click the “Copy” button for the Token, to copy the token to your clipboard. It will be a series of around 60 characters.

Because a token is sensitive information, it should not live in your code or source control. For now, we’ll alter our command line tool to read the token from a command line argument. In later articles, we’ll discuss strategies for accessing such secrets in production using Google Cloud Secret Manager.

First, modify the DiscordApi constructor to take the bot token as an argument.

# discord_api.rb

# ...

class DiscordApi
  def initialize(bot_token:)
    @client_id = DISCORD_APPLICATION_ID
    @guild_id = DISCORD_GUILD_ID
    @bot_token = bot_token
  end

  # ...

end

The token needs to be set in an authorization header in API requests. So modify the call_api helper method to set this header in the Faraday object’s constructor:

# discord_api.rb

# ...

class DiscordApi

  # ...

  private

  def call_api(path,
               method: :get,
               body: nil,
               params: nil,
               headers: nil)
    faraday = Faraday.new(url: "https://discord.com") do |conn|
      # Set the authorization header to include a token of type "Bot"
      conn.authorization(:Bot, @bot_token)
    end
    # make the request ...

  end
end

Finally, add a command line flag to set the token in the Toys script, and pass it into the DiscordApi constructor:

# .toys.rb

tool "list-commands" do
  flag :token, "--token TOKEN"

  def run
    require_relative "discord_api"
    client = DiscordApi.new(bot_token: token)
    result = client.list_commands
    puts JSON.pretty_generate(result)
  end
end

Now we can run the command line tool again, substituting in the actual token:

$ toys list-commands --token=$MY_BOT_TOKEN
[

]
$

If all went well, this should now display an empty array, indicating that the application has not yet installed any commands in this server.

Creating the Command

Now we finally have all the parts in place to make an API call to create a command in a Discord server. First, we’ll add a method to the client class that calls the Create Guild Application Command API. This API adds a command to a specific guild. (You can also create “global commands” that apply to multiple guilds, but they’re a bit more complicated to manage, so we’ll use guild-specific commands for now.)

# discord_api.rb

# ,,,

class DiscordApi

  # ...

  def create_command(command_definition)
    definition_json = JSON.dump(command_definition)
    headers = {"Content-Type" => "application/json"}
    call_api("/applications/#{@client_id}/guilds/#{@guild_id}/commands",
            method: :post,
            body: definition_json,
            headers: headers)
  end

  private

  # def call_api...

end

That method takes a hash object that describes the command to create. For this project, this is a Scripture lookup command called /bible, which takes one required option, the Scripture reference to look up. Here’s the definition of this command:

{
  name: "bible",
  description: "Simple Scripture lookup",
  options: [
    {
      type: 3,
      name: "reference",
      description: "Scripture reference (e.g. `JHN.1.1-JHN.1.5`)",
      required: true
    }
  ]
}

The full format is specified in the Discord documentation.

So I wrote a quick Toys script that takes the above description and feeds it into the API:

# .toys.rb

tool "create-command" do
  flag :token, "--token TOKEN"

  def run
    require_relative "discord_api"
    client = DiscordApi.new(bot_token: token)
    definition = {
      name: "bible",
      description: "Simple Scripture lookup",
      options: [
        {
          type: 3,
          name: "reference",
          description: "Scripture reference (e.g. `JHN.1.1-JHN.1.5`)",
          required: true
        }
      ]
    }
    result = client.create_command(definition)
    puts JSON.pretty_generate(result)
  end
end

# The "list" command from before is still here ...
tool "list-commands" do
  flag :token, "--token TOKEN"

  def run
    require_relative "discord_api"
    client = DiscordApi.new(bot_token: token)
    result = client.list_commands
    puts JSON.pretty_generate(result)
  end
end

Now I was able to call the new script, again substituting in the bot token. The script creates the command and displays the result:

$ toys create-command --token=$MY_BOT_TOKEN
{
  "id": "838195819437228113",
  "application_id": "838132693479850004",
  "name": "bible",
  "description": "Simple Scripture lookup",
  "version": "838195819437228114",
  "default_permission": true,
  "guild_id": "828125771288805436",
  "options": [
    {
      "type": 3,
      "name": "reference",
      "description": "Scripture reference (e.g. `JHN.1.1-JHN.1.5`)",
      "required": true
    }
  ]
}
$

And now calling list again, shows the new command:

$ toys list-commands --token=$MY_BOT_TOKEN
[
  {
    "id": "838195819437228113",
    "application_id": "838132693479850004",
    "name": "bible",
    "description": "Simple Scripture lookup",
    "version": "838195819437228114",
    "default_permission": true,
    "guild_id": "828125771288805436",
    "options": [
      {
        "type": 3,
        "name": "reference",
        "description": "Scripture reference (e.g. `JHN.1.1-JHN.1.5`)",
        "required": true
      }
    ]
  }
]
$

Now what?

Great, we’e created a command in our Discord server! The Discord UI updates immediately, so now it should be possible to go to a chat room in the Discord server, and type /bible, and see the autocomplete kick in.

But of course, if you’re following along, and try to invoke an entire command:

…you’ll get this:

And that’s because we haven’t actually implemented the command in our webhook yet. That will be the topic of part 3.

Building a Discord Command in Ruby on Google Cloud Functions: Part 1

Daniel Azuma — Sat, 01 May 2021 00:00:00 +0000

This is the first of a four-part series on writing a Discord “slash” command in Ruby using Google Cloud Functions. In this part, we cover setting up a Discord bot, deploying a webhook to Cloud Functions, and validating webhook requests from Discord using the Ruby ed25519 library. At the end of this part, we’ll have a working webhook that Discord recognizes, but that doesn’t yet actually implement a command.

Previous articles in this series:

Introduction

Creating a Discord application

Discord is a big system. Often used for gaming and streaming, but also increasingly for online community interaction, it includes a wide variety of features involving chat, voice, video, and content. Bots are an integral part of the ecosystem, and all bots start in the same place: with a Discord application.

Discord’s developer portal can be accessed at https://discord.com/developers. Once you’ve registered and logged in, it shows you a list of your applications. I created a new application here called scripture-bot.

Each application comes with a number of properties. These appear in the “general information” tab of the application, and include the following:

The application ID is a unique number identifying your application. It’s kind of like your application’s “username”, and will be important later when we call the Discord API to register with servers and create commands.
The public key will be used by your bot to authenticate requests—that is, to verify that HTTP requests you receive actually came from Discord and not from someone else trying to spoof Discord.
The interactions endpoint URL is the URL of the webhook that will be called when someone invokes your command. It starts off empty because you need to fill it in. And that’s what we’ll be doing next.

There’s also a tab labeled “Bot” that includes information about the “bot user”. It also starts off empty, but we will create a bot user later when we install our command into a Discord server.

Writing a webhook

A Discord application can respond to commands in two ways: via the Gateway or by implementing a webhook. The Gateway communicates over a websocket, which is flexible and low-latency, but complicated to implement, and requires running a permanent process. For this project, we’ll opt for the simpler approach of providing a webhook that Discord will call whenever a command is invoked. The webhook option has limitations, but a key advantage: it can be deployed as a serverless web app, and thus likely to be inexpensive to run if it’s not heavily used.

Writing and deploying webhooks is quite easy with functions-as-a-service, or “FaaS”, a serverless architecture that models your app as a simple function that handles events. Many major cloud providers offer a FaaS environment, for example Lambda from AWS, or Cloud Functions from Google. For this article, we’ll use Cloud Functions.

Hello Functions

Deploying a hello-world app to Cloud Functions is quite simple even if you haven’t done it before. Create a project in the Google Cloud Console, and install the Google Cloud SDK, Google Cloud’s command-line tool. Then you can write a quick function called “discord_webook” using the Functions Framework:

# Gemfile

source "https://rubygems.org"

gem "functions_framework", "~> 0.9"

# app.rb

require "functions_framework"

FunctionsFramework.http "discord_webhook" do |request|
  "Hello, world!\n"
end

You can then deploy the function from the command line. Cloud Functions requires that an up-to-date Gemfile.lock file is present in order to deploy, so that means installing the bundle, then running the gcloud command to deploy a function:

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

Substitute your own project ID (or use gcloud config set project to set it globally.) The command above deploys to the us-central1 availability region, and specifies a function that responds to HTTP requests using a Ruby 2.7 runtime. Note that it also disables Google’s default authentication. Instead, we will implement Discord’s authentication mechansim below.

If successful, the output of the gcloud deployment command will display the URL for the function. At this point you can use curl to send http requests to the function and see the response.

$ curl https://us-central1-$MY_PROJECT.cloudfunctions.net/discord_webhook
Hello, world!
$

Even though it’s very simple to get started, Google Cloud Functions has a long and growing list of features to make it easy to write and test your functions. You can run your function locally with a single command, and there’s a useful set of tools for running functions in isolation so you can write unit tests in Minitest or Rspec. I won’t cover the details here, but a lot of imformation is available in the Functions Framework documentation.

Responding to pings

Now that we have a working function, it’s time to configure it as the webhook endpoint for our Discord application. This is set in the “General Information” tab on your application’s page in the Discord console. However, if you just attempt to set the field now, Discord gives an error:

This is because verification failed. When you set up a webhook for an application, Discord will verify it is running correctly by sending it a ping message and expecting the proper reply. So we first need to update our function to handle pings.

Since we’re about to implement some real logic, let’s break it out into a separate class. The Functions Framework lets you define a function as a block, and you can put all the logic there. But for maintainability sake, it’s often a good idea to write separate Ruby classes encapsulating your application logic. So we’ll start by creating a Responder class to respond to HTTP requests sent by Discord, and refactoring our function to call it:

# responder.rb

class Responder
  def respond(rack_request)
    "Hello, world!\n"
  end
end

# app.rb

require "functions_framework"
require_relative "responder"

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

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

Note: The above code uses a startup block to instantiate our Responder and set it in a “global” that can be accessed by our function. The startup block and global storage are features of the Ruby Functions Framework. You could also use a Ruby global variable, or even a local variable scoped to the file, but the globals mechanism provided by the Functions Framework makes it easier to isolate runs when you write unit tests.

At this point, you can redeploy the function and verify that it still works. It should still just respond with the “Hello, world!” message. But we’ll change that now.

Discord’s messages, known in the Discord API as “interactions”, are sent as JSON and have a “type” field indicating the interaction type. Ping interactions have a type of 1, and when Discord sends you a ping, it expects you to respond with a similar JSON object, also with the “type” field set to 1. Let’s implement this in our Responder.

# responder.rb

require "json"

class Responder
  def respond(rack_request)
    raw_body = rack_request.body.read
    interaction = JSON.parse(raw_body)
    if interaction["type"] == 1
      {type: 1}
    else
      [400,
        {"Content-Type" => "text/plain"},
        ["Unrecognized interaction type"]]
    end
  end
end

Notice the return types: we return a hash if we receive a ping, or a standard Rack response array to report a 400 Bad Request if we receive anything else. The Functions Framework recognizes a variety of return types: a string will be encoded as plain text, a hash will be encoded as JSON, and Rack response types are also recognized.

Redeploy to Cloud Functions, and you can test it there by posting a JSON request using curl and seeing the expected response:

$ curl https://us-central1-$MY_PROJECT.cloudfunctions.net/discord_webhook \
  --data '{"type":1}'
{"type":1}
$

Now you can go back to the Discord developer site, and fill in the interactions endpoint url field with the URL of your function. And…

We’re still getting a verification failure. It turns out, even though we’re returning the correct response to a ping, Discord also requires that we verify request signatures correctly before it will let us set the endpoint. So we’ll turn our attention there next.

Validating Discord requests

When you write a web service, it’s always good practice to validate that any requests you receive are actually from whom you think they’re from. Before it lets you set your endpoint URL, Discord will enforce this practice by checking that you’ve implemented validation correctly. It does this by sending send test requests to your endpoint with both correct and incorrect credentials, and making sure you respond appropriately

So let’s implement this verification, following the instructions from Discord.

First, we’ll need a library that can validate ED25519 signatures. There are several to choose from, but we’ll use the ed25519 gem because it doesn’t depend on outside C libraries, making it easier to deploy it to serverless runtimes.

# Gemfile

source "https://rubygems.org"

gem "ed25519", "~> 1.2"
gem "functions_framework", "~> 0.9"

Run bundle install to install the gem and ensure that your Gemfile.lock is updated. If you forget to do this when you update your bundle, Cloud Functions will fail to deploy your app, and will report an error that your lockfile is out of date.

Then it’s time to write the signature verification code. First, create a verification key from the app’s public key (which is available from the General Information tab on Discord.) Set this in the constructor for the Responder class because it’s the same for all requests.

# responder.rb

require "json"
require "ed25519"

class Responder
  # Substitute your Discord app's public key here
  DISCORD_PUBLIC_KEY = "1904a4821ccb7f5212ad0ce8cfd32a385dee845d9f7dc5113b35066e3b05db78"

  def initialize
    public_key = DISCORD_PUBLIC_KEY
    public_key_binary = [public_key].pack("H*")
    @verification_key = Ed25519::VerifyKey.new(public_key_binary)
  end

  # ...
end

In the above example code, substitute your app’s public key for mine.

Note: We’ve hard-coded the public key for now. This is not great practice, but it’s generally safe because a public key is not secret. In a real application you’ll likely want to load it from an environment variable or configuration file instead.

Once you have a verification key, you can verify a request by checking the contents of the request against the signature sent by Discord, using your key. The signature will match only if it was created using the corresponding private key, which only Discord should have. Additionally, the request content will include a timestamp, and you should check that it is close to the current time, in order to prevent replay attacks. Here’s the final code:

# responder.rb

require "json"
require "ed25519"

class Responder
  # Substitute your Discord app's public key here
  DISCORD_PUBLIC_KEY = "1904a4821ccb7f5212ad0ce8cfd32a385dee845d9f7dc5113b35066e3b05db78"

  # Allowed difference in seconds betwen the current time and
  # the timestamp sent by Discord
  ALLOWED_CLOCK_SKEW = 10

  def initialize
    public_key = DISCORD_PUBLIC_KEY
    public_key_binary = [public_key].pack("H*")
    @verification_key = Ed25519::VerifyKey.new(public_key_binary)
  end

  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)
    if interaction["type"] == 1
      {type: 1}
    else
      [400,
        {"Content-Type" => "text/plain"},
        ["Unrecognized interaction type"]]
    end
  end

  private

  # Verify a request by checking the timestamp and signature
  def verify_request(raw_body, rack_env)
    # Get the timestamp and check for replay attacks
    timestamp = rack_env["HTTP_X_SIGNATURE_TIMESTAMP"].to_s
    current_time = Process.clock_gettime(Process::CLOCK_REALTIME)
    clock_skew = (current_time - timestamp.to_i).abs
    return false if clock_skew > ALLOWED_CLOCK_SKEW

    # Get the signature and verify it against the content and timestamp
    signature_hex = rack_env["HTTP_X_SIGNATURE_ED25519"].to_s
    signature = [signature_hex].pack("H*")
    begin
      @verification_key.verify(signature, timestamp + raw_body)
      true
    rescue Ed25519::VerifyError
      false
    end
  end
end

A quick redeploy, and now at last we can set our Discord application’s endpoint URL. If you go look at the Cloud Functions logs in the Google Cloud Console, you’ll be able to see the test requests that Discord sends you. Typically it will send two requests when you attempt to set the webhook URL: one with a correct signature and one with an incorrect signature, just to make sure you have pings and verification implemented.

Note: It can take a few seconds, even after Cloud Functions finishes deploying your function, for the backend to “switch over” to the new deployment. So if you’re following along, and you believe you’ve implemented the verification, but Discord is still reporting a verification error, wait about a minute and then try setting the endpoint field in Discord again.

Now what?

So far so good. We have a working Discord application, deployed to Google Cloud Functions, and responding correctly to requests sent by Discord. Next we actually have to create a command. We’ll cover that in part 2.

Building a Discord Command in Ruby on Google Cloud Functions

Daniel Azuma — Fri, 30 Apr 2021 00:00:00 +0000

I recently spent a weekend experimenting with Discord integration. My church had decided to move our online services from Zoom to Discord, and, being a software geek, I thought it would be fun to try to build some things for the community.

So far I’ve built a simple command that does Scripture lookups. You can type a command in one of our Discord channels:

…and the bot will look up the passage using an API, and display it in the channel:

“Slash” commands such as this, are a relatively recent adition to the Discord API. They’re easy for users to interact with, and convenient to deploy as a webhook.

Following will be a short series of articles describing how to write a Discord command such as this “scripture-bot” in Ruby, along with how to deploy it to the cloud. Along the way, we’ll cover a lot of the issues you may encounter with a real-world application, including:

Deploying to a “serverless” environment. Specifically, we’ll use Cloud Functions, a functions-as-a-service offering from Google.
Verifying request signatures using Ruby libraries, in this case using the ed25519 gem.
Good practices for handling secrets , such as API keys, in production. For this project, we’ll demonstrate the use of Google Secret Manager.
Techniques for reducing cold start time , including lazy initialization.
Using an event-driven architecture to schedule and run background tasks. In this project we’ll use Google Pub/Sub.

Because there’s a lot to cover, I’ll be splitting this article into four parts:

In part 1, we’ll cover setting up a Discord bot, deploying a webhook to Google Cloud Functions, and validating webhook requests from Discord using the Ruby ed25519 library. At the end of this part, we’ll have a working webhook that Discord recognizes, but that doesn’t yet actually implement a command.

In part 2, we’ll add our bot to a Discord server, and use the Discord API to register a command with the server. At the end of this part, we’ll know how to authenticate with the Discord API, and we’ll have a command set up, but it won’t yet be implemented.

In part 3, we’ll implement the command, calling an external API to get the actual Scripture text to display on the Discord channel. We’ll also learn how to use Google’s Secret Manager to access the API key securely in production. At the end of this part, our command will be working, with a few caveats.

In part 4, we’ll deal with one of the main issues with our implementation so far, which is that Discord doesn’t let you display more than 2000 characters in a chat message. To display a longer Scripture passage, we’ll need to send follow-up messages using the Discord API, and we’ll do that by scheduling a follow-up task using Google Pub/Sub.

All the code will be included, so at the end, if you follow along, you’ll have your own fully-functional Discord bot.

Ready? On to part 1…

Should I use instance_eval or class_eval?

Daniel Azuma — Tue, 02 Feb 2021 00:00:00 +0000

Ruby objects have methods called instance_eval and class_eval. They both execute a block with self referencing the object.

class C; end

C.instance_eval { puts "instance_eval: self = #{self}" }
# prints "instance_eval: self = C"

C.class_eval { puts "class_eval: self = #{self}" }
# prints "class_eval: self = C"

For a long time I thought these methods were basically synonymous, that for some reason I was simply supposed to use class_eval for classes (and module_eval for modules) and instance_eval for everything else. Just accept it and don’t ask questions, I told myself.

But there is a difference, one that points to an important but seldom understood aspect of Ruby. In this article, we’ll explore the distinction and what it means for our Ruby code.

The “current object”

Let’s start with what many Ruby programmers already know.

Like many object-oriented languages, Ruby has the notion of a “current object”. This is the object that receives method calls by default, and it is the object that owns any instance variables you reference. Ruby sets the current object inside every method call, so the method can access the object’s instance variables and easily call other methods of the object.

class Greeter
  def initialize(name)
    @name = name
  end

  def greeting
    # Reference "@name" from the current object
    "Hello, #{@name}!"
  end

  def print_greeting
    # Call the "greeting" method in the current object
    puts greeting
  end
end

You can get a reference to the current object using the self keyword, but for the most part, it’s used implicitly when resolving methods or instance variables.

There is always a current object, even when you’re not in a method. Within a class definition, the current object is the class. And Ruby even provides a “main” object that is the current object at the top level of a Ruby script.

class Greeter
  puts self
  # Prints "Greeter"
end

puts self
# Prints "main"

Changing the current object with instance_eval

You can also change the current object using the instance_eval method (or the closely related instance_exec).

greet = Greeter.new("world")

# Change the object context within the given block.
greet.instance_eval do
  # Self now references the greeter object
  assert self == greet

  # You can call its methods without a receiver
  print_greeting

  # You can even access its instance variables
  puts @name
end

The instance_eval method is commonly used for building domain-specific-languages (DSLs) because it lets us control how methods are looked up. When you write Rails routes, for example, Rails is using instance_eval to give you a simple syntax for declaring paths and resources.

The current object has a strong effect on looking up method names, but what about defining a method? This is where the story gets a bit more complicated.

Defining methods

The def keyword is typically used to define a new method. Normally, def appears within a class or module definition, so it’s clear where the method is defined. But Ruby is very flexible. You can put a def almost anywhere: outside any class, in a block, even within another method.

What do you think happens when a method is defined inside another method?

class Greeter
  def greeting
    def dismissal
      "Bye, world!"
    end
    "Hello, world!"
  end
end

No, Ruby doesn’t have any weird notion of “nested” methods. All that’s happening here is that defining the dismissal method is part of the functionality of the greeting method. dismissal is defined when you call greeting.

So what class is dismissal defined on? One might guess that it’s also defined on the Greeter class, and in this case you’d be right. But why is that the case? It may seem “obvious” or “intuitive,” but it’s very important to understand what’s actually going on, because things won’t always be obvious. Take this example:

class Greeter
  def greeting
    "Hello, world!"
  end
end

Greeter.instance_eval do
  def dismissal
    "Bye, world!"
  end
end

We’re using instance_eval to set the object context to the Greeter class when we define the method. So where is dismissal defined? You might guess, on the Greeter class. But you’d be wrong. It gets defined on the Object class.

So what’s really going on? What actually governs on which class a method is defined?

The “current class”

The answer is that “self” isn’t the only piece of context that Ruby maintains. The “current object” governs lookup of method names (and instance variables), but method definitions are governed by a separate piece of context that I’ll call the “current class”.

Note: other terms have been used elsewhere for the “current class”. For example, Yugui used the term “default definee” when she wrote about the Ruby contexts in an earlier article.

When you define a class using the class keyword, it creates a class and sets the current class context so that methods are attached to it. Similarly, when a method is called, the current class context is set to self’s class.

class Greeter
  # Current class is set to Greeter.
  # This ensures the greeting method is defined on Greeter.
  def greeting
    # Current class is set to self's class, which is Greeter.
    # This ensures the dismissal method is also defind on Greeter.
    def dismissal
      "Bye, world!"
    end
    "Hello, world!"
  end
end

However, importantly, instance_eval sets the current object but not the current class.

# Current class is Object at the top level of a Ruby file

Greeter.instance_eval do
  # The instance_eval method sets self but not the current class,
  # so the current class is still Object here.
  def dismissal
    "Bye, world!"
  end
end

And this is where class_eval is different. Whereas instance_eval sets only the current object, class_eval sets both the current object and current class.

Greeter.class_eval do
  # The current class is now Greeter.
  def dismissal
    "Bye, world!"
  end
end

So we’ve seen that Ruby maintains separate, independent class and object contexts. And that brings up an interesting question: Why?

Why are “current class” and “current object” distinct?

Why maintain two separate pieces of state? Isn’t that needlessly complicated?

It turns out there’s a good reason for it, and it has to do with Ruby’s goal of making programming intuitive. Let’s look again at the two places we’ve seen method definitions.

When you use a class declaration, Ruby sets both the current object and the current class to the same thing, the class. This lets you both define methods and call class methods such as attr_reader, include, and even private.

class Greeter
  # current class == self
  # This means you can define methods on the class
  def greeting
    "Hello, world!"
  end

  # And you can also call class methods
  attr_reader :language
end

But when you define a method in another method, the current object and the current class are not the same. An arbitrary object doesn’t have methods; only classes do. So the current class is set to the class of the object.

class Greeter
  def greeting
    # current class != self
    # current class == self.class
    def dismissal
      "Bye, world!"
    end
    "Hello, world!"
  end
end

In order to support reasonable behavior in both of these two cases, Ruby needs the flexibility to be able to set up the two values, current object and current class, differently.

Why does this matter?

So Ruby has more context than just self. Why does it matter?

Well, it might help you avoid some bugs, and it’s always useful to understand the details of the language you are using. But it’s particularly important when you are designing interfaces for other developers to use, especially if you’re designing a domain-specific language.

Ruby is a flexible language, and Ruby programmers expect to be able to use that flexibility, calling code, writing helper methods, and generally doing things you might not expect. If the Rails router had set the current class to some strange value and made it difficult for users to write helper methods, Rails would have been much more brittle and difficult to use, and ultimately less successful.

So it’s important for Ruby library writers to make sure you choose the correct method when using class_eval or instance_eval. And in general, library designers need to pay attention to the current class in order to avoid unexpected behavior.

If you’re interested in learning some tips for designing interfaces that pay attention to these issues, see my talk “Ruby Ate My DSL!” from RubyConf 2019.

Investigating further

It turns out, the rabbit hole goes even deeper. A third independent piece of Ruby context governs constants, where they are defined and how they are looked up. This piece of context, known internally as the cref, represents the lexical nesting of classes and modules, basically what you get from calling Module.nesting. However, unlike the current object and current class, the cref can’t be changed programmatically, at least not without dropping into C.

class Greeter
  # The cref points to Greeter, so GREETING is defined there
  GREETING = "hello"
end

puts Greeter::GREETING
# prints "hello"

Greeter.class_eval do
  # class_eval doesn't affect cref, so SALUTATION is defined on Object
  SALUTATION = "hi"
end

puts Object::SALUTATION
# prints "hi"

puts Greeter::SALUTATION
# Raises NameError

Because cref can’t be modified from Ruby, it’s difficult to control how constants are defined and managed in DSLs. This is generally why many DSLs eschew constants or provide alternatives.

And indeed, there are several other elements to the Ruby “context”, controlling such functionality as what super calls, how iteration keywords like next and break behave, and so forth. If you’re interested in exploring this further, the old Ruby hacking guide has a chapter dedicated to the context, but it’s from the Ruby 1.7 era and might be out of date. Pat Shaughnessy’s excellent book Ruby Under a Microsocope is somewhat newer and also covers some of these topics. (If anyone knows of other resources, leave a note in the comments!)

Designing a Ruby Serverless Runtime

Daniel Azuma — Wed, 20 Jan 2021 00:00:00 +0000

Last week, Google announced the public beta of the Ruby runtime for Cloud Functions, Google’s functions-as-a-service (FaaS) hosting platform. Ruby support has lagged a bit behind other languages over the past year or so, but now that we’ve caught up, I thought I’d share some of the design process behind the product.

This article is not a traditional design document. I won’t go through the design itself step-by-step. Instead, I want to discuss some of the design issues we faced, the decisions we made, and why we made them, because it was an interesting exercise in figuring out how to fuse Ruby conventions with those of the public cloud. Some of the trade-offs we made are, I think, emblematic of the challenges the Ruby community as a whole is facing as the industry evolves.

A Ruby way of doing serverless

Bringing Ruby support to a serverless product is a lot more involved than you might expect. At the most basic level, a language runtime is just a Ruby installation, and sure, it’s not hard to configure a Ruby image and install it on a VM. But things become more complex when you bring “serverless” into the mix. Severless is much more than just automatic maintenance and scaling. It’s an entirely different way of thinking about compute resources, one that goes contrary to much of we’ve been taught about deploying Ruby apps for the past fifteen years. When the Ruby team at Google Cloud took on the task of designing the Ruby runtime for Cloud Functions, we were also taking on the daunting task of proposing a Ruby way of doing serverless. While remaining true to the Ruby idioms, practices, and tools familiar to our community, we also had to rethink how we approach web application development at almost every level, from code, to dependencies, persistence, testing, everything.

This article will examine our approach to five different aspects of the design: function syntax, concurrency and lifecycle, testing, dependencies, and standards. In each case, we’ll see a balance between the importance of remaining true to our Ruby roots, and the desire to embrace the new serverless paradigms. We tried very hard to maintain continuity with the traditional Ruby way of doing things, and we also took cues from other Google Cloud Functions language runtimes, as well as precedents set by serverless products from other cloud providers. However, in a few cases, we chose to blaze a different trail. We did so when we felt that current approaches either abused a language feature, or were misleading and encouraged the wrong ideas about serverless app development.

It’s possible, even likely, that some of these decisions will eventually prove to have been wrong. That’s why I’m offering this article now, to discuss what we’ve done and to start the conversation about how we as the Ruby community practice serverless app development. The good news is that Ruby is a very flexible language, and we will have plenty of opportunity to adapt as we learn and as our needs evolve.

So let’s take a look at some of the initial design decisions and trade-offs we made and why we made them.

Functional Ruby

“Functions-as-a-Service” (FaaS) is currently one of the more popular serverless paradigms. Google’s Cloud Functions is just one implementation. Many other major cloud providers have their own FaaS product, and there are open source implementations as well.

The idea, of course, is to use a programming model centered not around web servers, but around functions: stateless pieces of code that take input arguments and return results. It seems like a simple, almost obvious, change in terminology, but it actually has profound implications.

The first challenge for Ruby is that, unlike many other programming languages, Ruby actually doesn’t have first-class functions. Ruby is first and foremost an object-oriented language. When we write code and wrap it in a def, we are writing a method, code that runs in response to a message sent to an object. This is an important distinction, because the objects and classes that form the context of a method call are not part of the serverless abstraction. So their presence can complicate a serverless application, and even mislead us when we’re writing it.

For example, some FaaS frameworks let you write a function with a def at the top level of a Ruby file:

def handler(event:, context:)
  "Hello, world!"
end

While this code appears straightforward, it’s important to remember what it actually does. It adds this “function” as a private method on the Object class, the base class of the Ruby class hierarchy. In other words, the “function” has been added to nearly every object in the Ruby virtual machine. (Unless, of course, the application changes the main object and class context when loading the file, a technique that carries other risks.) At best, this breaks encapsulation and single responsibility. At worst, it risks interfering with the functionality of your application, its dependencies, or even the Ruby standard library. This is why such “top level” methods, while common in simple single-file Ruby scripts and Rakefiles, are not recommended in larger Ruby applications.

The Google Ruby team decided this issue was serious enough that we chose a different syntax, writing functions as blocks:

require "functions_framework"
FunctionsFramework.http("handler") do |request|
  "Hello, world!"
end

This provides a Ruby-like way to define functions without modifying the Object base class. It also has a few side benefits:

The name (“handler” in this case) is just a string argument. It doesn’t need to be a legal Ruby method name, nor is there any concern of it colliding with a Ruby keyword.
Blocks exhibit more traditional lexical scoping than do methods, so this will behave more similarly to functions in other languages.
The block syntax makes it easier to manage function definitions. For example, it’s possible to “undefine” functions cleanly, which is important for testing.

Of course, there are trade-offs. Among them:

The syntax is slightly more verbose.
It requires a library to provide the interface for defining functions as blocks. (Here, Ruby follows other language runtimes for Cloud Functions by utilizing a Functions Framework library.)

We decided it was worth these trade-offs for the goal of properly distinguishing functions.

To share or not to share

Concurrency is hard. This is one of the key observations underlying the design of serverless in general, and functions-as-a-service in particular: that we live in a concurrent world and we need ways to cope. The functional paradigm addresses concurrency by insisting that functions not share state (except through an external persistence system such as a queue or database).

This is in fact another reason we chose to use block syntax rather than method syntax. Methods imply objects, which carry state in the form of instance variables, state that might not work as expected in a stateless FaaS environment. Eschewing methods is a subtle but effective syntactic way to discourage practices we know to be problematic.

That said, what if you need to share resources, such as database connection pools? When would you initialize such resources, and how would you access them?

For this purpose, the Ruby runtime supports startup functions that can initialize resources and passes them into function calls. Importantly, while the startup function can create resources, normal functions can only read them.

require "functions_framework"

# Use an on_startup block to initialize a shared client and store it in
# the global shared data.
FunctionsFramework.on_startup do
  require "google/cloud/storage"
  set_global :storage_client, Google::Cloud::Storage.new
end

# The shared storage_client can be accessed by all function invocations
# via the global shared data.
FunctionsFramework.http "storage_example" do |request|
  bucket = global(:storage_client).bucket "my-bucket"
  file = bucket.file "path/to/my-file.txt"
  file.download.to_s
end

Notice that we chose to define special methods global and set_global to interact with global resources. (By the way, these are not methods on Object, but methods on a specific class we use as the function context.) Again, we could have used more traditional idioms such as Ruby global variables, or even a constructor and instance variables, to pass information from startup code to function calls. However, those idioms would have communicated the wrong things. We’re not writing ordinary Ruby classes and methods where sharing data is normal, but serverless functions where sharing data is hazardous if even possible, and we felt it was important for the syntax to emphasize the distinction. The special methods were a deliberate design decision, to discourage practices could be dangerous in the presence of concurrency.

Test first

A strong testing culture is central to the Ruby community. Popular frameworks, such as Rails, acknowledge this and encourage active testing by providing testing tools and scaffolding as part of the framework, and the Ruby runtime for Google Cloud Functions follows suit by providing testing tools for serverless functions.

The FaaS paradigm actually fits very well with tests. Functions are by nature easily testable; simply pass in arguments and assert against results. In particular, you don’t need to spin up a web server to run tests, because web servers are not part of the abstraction. The Ruby runtime provides a module of helper methods for creating HTTP request and Cloud Event objects to use as inputs, and otherwise most tests are very straightforward to write.

One of the main testing challenges we encountered, though, had to do with testing initialization code. Indeed, this is an issue that some of Google’s Ruby team members have had with other frameworks, including Rails: it is difficult to test an app’s initialization process, because framework initialization typically happens outside the tests, before they run. We therefore designed a way for tests to isolate the entire lifecycle of a function, including initialization. This allows us to run initialization within a test, and even repeat it multiple times allowing tests of different aspects:

require "minitest/autorun"
require "functions_framework/testing"

class MyTest < Minitest::Test
  # Include testing helper methods
  include FunctionsFramework::Testing

  def test_startup_tasks
    # Run the lifecycle, and test the startup tasks in isolation.
    load_temporary "app.rb" do
      globals = run_startup_tasks "storage_example"
      assert_kind_of Google::Cloud::Storage, globals[:storage_client]
    end
  end

  def test_storage_request
    # Rerun the entire lifecycle, including the startup tasks, and
    # test a function call.
    load_temporary "app.rb" do
      request = make_get_request "https://example.com/foo"
      response = call_http "storage_example", request
      assert_equal 200, response.status
    end
  end
end

The load_temporary method loads function definitions in a sandbox, isolating them and their initialization from other test runs. That and other helper methods are defined in the FunctionsFramework::Testing module, which can be included in minitest or rspec tests.

So far we’ve really provided only basic testing tools for the Ruby runtime, and I expect we’ll add significantly to the toolset as our users develop more apps and we identify more of the common testing patterns. But I strongly believe testing tools are an important part of any library, especially one that purports to be a framework or runtime, and so it was a core part of our design from the start.

The dependable runtime

Most nontrivial Ruby apps require third-party gems. For Ruby apps that use Google Cloud Functions, we require at least one gem, the functions_framework that provides the Ruby interfaces for writing functions. You may also need other gems for handling data, authenticating and integrating with other services, and so forth. Dependency management is a crucial part of any runtime framework.

We made several design decisions around dependency management. And the first and most important was to embrace Bundler.

I know that sounds a bit frivolous. Most Ruby apps these days use Bundler anyway, and there are very few alternatives, hardly any in widespread use. But we actually took it a step further and built Bundler deep into our infrastructure, requiring that apps use it in order to work with Cloud Functions. We did this because, knowing exactly how an app will manage its dependencies would allow us to implement some important optimizations.

Vital to a good FaaS system is the speed of deployments and cold starts. In a serverless world, your code might be updated, deployed, and torn down many times in rapid succession, so it’s crucial to eliminate bottlenecks such as resolving and installing dependencies. Because we standardize on one system for dependency management, we are able to cache dependencies aggressively. We judged that the performance gains of implementing such caching, as well as the reduced load on the Rubygems.org infrastructure, far outweighed the reduced flexibility of not being able to use an alternative to Bundler.

Another feature, or maybe quirk, of the Ruby runtime for Google Cloud Functions, is that it will fail deployments if the gem lockfile is missing or inconsistent. We require that Gemfile.lock is present when you deploy. This was another decision made to enforce a best practice. If the lockfile gets reresolved during deployment, your builds may not be repeatable, and you may not be running against the same dependencies you tested with. We avoid this by requiring an up-to-date Gemfile.lock file, and again, we are able to enforce this because we require the use of Bundler.

Standards old and new

Finally, good designs lean on standards and prior art. We had to innovate a bit to define robust functions in Ruby, but when it comes to representing the function arguments, there were already existing libraries or emerging standards to follow.

For example, in the near term, many functions will respond to web hooks, and will need information about the incoming HTTP request. It would not be difficult to design a class that represents an HTTP request, but the Ruby community already has a standard API for this sort of thing: Rack. We adopted the Rack request class for our event parameters, and we support standard Rack responses for return values.

require "functions_framework"

FunctionsFramework.http "http_example" do |request|
  # request is a Rack::Request object.
  logger.info "I received #{request.request_method} from #{request.url}!"
  # You can return a standard Rack response array, or use one of
  # several convenience formats.
  [200, {}, "ok"]
end

Not only does this provide a familiar API, but it also makes it easy to integrate with other Rack-based libraries. For example, it is easy to layer a Sinatra app atop Cloud Functions because they both speak Rack.

In the longer term, we increasingly expect functions-as-a-service to fit as a component in evented systems. Event-based architectures are rapidly growing in popularity, often surrounding event queues such as Apache Kafka. And a crucial element of an event architecture is a standard way to describe the events themselves, a standard understood by event senders, brokers, transport, and consumers.

Google Cloud Functions has thrown its support behind CNCF CloudEvents, an emerging standard for describing and delivering events. In addition to HTTP requests, Cloud Functions can also receive data in the form of a CloudEvent, and the runtime will even convert some legacy event types to CloudEvents when calling your function.

require "functions_framework"

FunctionsFramework.cloud_event "my_handler" do |event|
  # event is a CloudEvent object defined by the cloud_events gem
  logger.info "I received a CloudEvent of type #{event.type}!"
end

To support CloudEvents in Ruby, the Google Ruby team worked closely with the CNCF Serverless Working Group, and even volunteered to take over development of the Ruby SDK for CloudEvents. This turned out to be a lot of work, but we considered it crucial to be able to use the official, standard Ruby interfaces, even if we had to implement it ourselves.

The serverless future

“Serverless” and “functions-as-a-service” hosting has garnered a lot of interest over the past few years. I think the jury is still out on how useful it will be for most workloads, but the possibilities are intriguing. “Zero”-devops, automatic maintenance and scaling, no servers to maintain, and pay only for the compute resources you actually use. I recently moved this very blog from a personal Kubernetes cluster to Google’s managed Cloud Run service, and slashed my monthly bill from dozens of dollars down to pennies.

That said, serverless is a fundamentally different way of thinking about compute resources, and as an industry we are still very early in our understanding of the implications. As my team designed the Ruby runtime for Google Cloud Functions, we were mindful about the ways the serverless paradigm interacts with our normal Ruby practices. In some cases, as with testing, it encourages us to double down on the good parts of Ruby culture. In others, as with how to express and notate a function in a language that strictly speaking doesn’t have them, it challenges our ideas of how to present code and communicate its intent.

But in all cases, the experience of designing the runtime reminded me that we’re in a industry of constant change. Serverless is just the latest in a string of disruptions that have included the public cloud in general, and even Rails, and Ruby itself. It’s not yet clear how much serverless will stick, but it is here today, and it’s up to us to respond with curiosity, creativity, and a willingness not to take what we know for granted.

Is it time to replace Rake?

Daniel Azuma — Wed, 06 Nov 2019 00:00:00 +0000

Do you have really heavy Rakefiles?

I do. My day job includes working in a Ruby-based repository with a lot of test, build, and release tooling, living in an enormous Rakefile. Actually, an enormous main Rakefile, plus lots of additional Rakefiles in dozens of subdirectories. Combined, it’s well over seven thousand lines of Rakefile—and that’s actually quite a bit smaller than it has been in the past.

Rakefiles are the ugly junk closets of our Ruby projects. Our app might have nicely factored classes, short methods, and excellent test coverage for our application code, but that seldom extends to our Rakefiles. Is your Rakefile covered by your code health tools? Do you have tests for your Rake tasks? Didn’t think so.

And running Rake tasks is another adventure. Simple cases such as rake test work great. But what if you need to pass in flags or arguments to a task? Yes, you can do it with Rake. There are several ways in fact. But it’s not pretty.

Rake is an incredibly useful tool that has served the community really well for many years. But I’ve always felt like it was not quite right, that its design didn’t quite match up. And that’s not surprising, because… it doesn’t.

Rake and Make

Rake was written as a replacement for the unix make tool. As a make tool, it excels, covering all the essential aspects of file-based dependencies and builds. And the Rakefile format is, to a Rubyist, much nicer to work with than Makefile.

But it is still a make replacement, designed for building projects in languages like C with file-based compilation dependencies. Where you have to recompile object files because source and header files changed.

We generally don’t do that sort of thing in Ruby.

Indeed I think the only time Ruby devs compile C regularly is when we install a gem with C extensions. And for that, most gems use mkmf to create, yes, a Makefile. That’s right, we generally don’t even use Rake to build our C extensions. Maybe we should. But I digress.

When was the last time you wrote a Rakefile with a FileTask? Maybe you have, but most of us seldom if ever use Rake’s primary features. We don’t use Rake for what it’s designed for.

Instead, we mostly use Rake to write scripts. Scripts to run our tests, build assets, initiate deployments, and so forth.

Managing project scripts

Now when it comes to writing and using scripts, there are a few capabilities I find important.

I might need to pass arguments or flags to the script. For example, a test script might use arguments to configure the test environment or select which tests to run. Rake does have a syntax for arguments, but I’d like to use normal unix arguments and flags. It would be much nicer to say

run-test --integration --env=production

rather than

rake 'run-test[integration,production]'

Online help for my scripts is also very important. I’m not going to remember the usage for all my scripts, and I don’t want to have to open the source every time. Rake provides a way to set a short description for each task, but it’s not well suited for long or complex content, or especially for documenting arguments.

I want my implementation to be organized, testable, and maintainable , just like application code. Large scripts should be broken into smaller methods. There should be principled ways to share code and data, and to break big projects into multiple files. Yes, all this is technically possible with Rake. It’s just Ruby after all. But, let’s face it: the Rakefile format doeesn’t exactly encourage good software practice.

Support for typical script-y features would be nice. Terminal features such as input, progress meters, and styled text. Shell completion. Rich file system manipulation and process control features. Not a lot of this is provided by Rake, and while you can bring in some additional gems, it’s not common practice.

But there’s one thing I like about Rake that I want to keep: the Rakefile. Or something like it. The ability to define scripts in a file in the current directory, with a simple DSL. That’s why I’ve been using Rake all this time, despite its limitations. I suspect that’s why we all still use it.

Alternatives to Rake

So is there an alternative?

Actually, there are a few. Thor is probably best known as a framework for building command line applications in your own gems. But it also can read “Thorfiles” in the current directory, and run them as tasks using the thor executable. Your tasks then have access to all the features of Thor, including normal unix-style command line options and flags, and automatic help.

I’ve also been experimenting with a similar tool myself, called Toys. Like Thor, Toys reads its scripts from files in the current directory, and it supports unix-style command line options and flags, and automatically generates help screens. But it goes further, providing features that I’ve found helpful to manage the complex projects I work on. It provides better code organization, integrates with tab completion and the did_you_mean gem, includes templates for generating common tasks, provides helpers for building terminal apps and controlling subprocesses, has built-in logging, and a whole lot more. Toys can also read an existing Rakefile, making it easy to migrate.

I’ve been using Toys to manage workflow scripts at my day job for several years already. And recently I’ve started replacing the Rakefiles for my open-source Ruby projects. Both usability and maintainability have improved significantly.

The Rails team also decided to move on from Rake for Rails apps. Several versions ago, the Rake tasks in new Rails apps were deprecated in favor of bin/rails, a custom command line tool.

So we already have some good alternatives. I think it’s just a matter of the Ruby community at large trying them out.

Is it time to replace Rake?

Rake has served the community well for many years, and for some uses it’s still very appropriate. Do you need to orchestrate building files in your project—whether that’s C source, assets, codegen, or other tasks with file-based dependencies? Then Rake will continue to be your friend.

But for many, maybe most, of your project tasks—running tests, deploying code, performing admin tasks, etc.—it may make more sense to use a tool that is optimized for writing scripts. For these cases, maybe it is indeed time to replace Rake.

If you agree, consider checking out Toys. I’d love to hear whether it works for you, and how it could be better. And if you think Rake should continue to be the tool of choice, I’d also love to hear your thoughts.

Deploying My Blog to Google Cloud Run

Daniel Azuma — Mon, 01 Jul 2019 00:00:00 +0000

For the past few years, my blog (the canonical copy at https://daniel-azuma.com/blog) has been hosted on a personal Kubernetes cluster. In addition to my blog, I used the cluster to host a few other websites, as well as run occasional compute jobs. Kubernetes is a great, very flexible technology, and since (full disclosure) I work at Google, throwing container images at a server infrastructure feels very natural to me. But maintaining a Kubernetes cluster means paying for the VMs, and lately I’ve been wondering if I can avoid those costs.

So I started to move my sites and my jobs off Kubernetes, and finally, a month ago, I was able to turn down the cluster completely. I migrated this blog to Cloud Run, a container-based serverless environment that Google introduced in April. It’s been working perfectly so far, and since it fits easily into the free tier, my costs have gone down to effectively zero. And I know that if I ever get slashdotted… this is Google: they’ll scale me up as needed.

In this article, I’ll discuss whether a serverless platform might be a good fit for a static site. Then I’ll provide a tutorial for deploying a Jekyll-based static site to Cloud Run. Along the way you’ll also learn some good practices for containerizing static sites. It shouldn’t be too difficult to adapt these instructions for other static site generators such as Hugo.

Why serverless for static sites?

These days we have a number of choices for hosting static sites. One of the easiest is to use a cloud storage service such as Amazon S3 or Google Cloud Storage. Just upload your static content to a storage bucket, configure a few knobs, and you have a website. Source control services such as GitHub and Bitbucket also often provide web hosting for content pushed to their repositories. For simple static sites, options such as these are generally straightforward and inexpensive.

With the advent of the serverless cloud, we now have a third inexpensive option. With many serverless platforms, you don’t pay for containers or VMs or storage—just the compute resources that you actually use. And for a static site, you don’t use very much.

But still, why choose a general-purpose serverless platform over storage-based or source control hosting?

Different deployment options always have pros and cons. One of the chief benefits of general-purpose serverless, however, is flexibility. Static sites are almost never “purely” static. Maybe you need custom error handling and error documents. Maybe you need more sophisticated redirects. Maybe you need to hide some content behind authentication. Maybe the majority of your site is static, but you still need server-side scripts for a few cases. Simple content-based hosting generally provides some configuration knobs to help with these extras, but they can’t always handle every case.

In my blog, I have a large number of redirects, and a few special cases handled by specially crafted Nginx configuration. So for me, one of the big draws of Google Cloud Run was the ability to provide my own container with my own Nginx config files.

There’s of course no one size that fits all. But if you’re having trouble getting S3 to handle your site the way you need, or if you’re currently running on VMs or on your own servers and want to cut costs, a serverless platform might be your sweet spot as well.

Jekyll on Cloud Run

The rest of this article is a tutorial for deploying a Jekyll-based site to Google Cloud Run. Cloud Run is particularly effective for static sites because it uses containers, letting you configure your own web server for static content. (In contrast, “function” or “lambda” based platforms are typically tailored for specific dynamic web languages or frameworks, and might not support static sites at all.)

Note that there are two “flavors” of Cloud Run: a fully-managed flavor that runs directly in Google’s infrastructure, and a flavor that runs on your own Kubernetes Engine cluster. For static sites, you will probably prefer the former, because it’s the one that gives you the very cheap pay-per-use model. (And in my case, part of the whole purpose was to get rid of my Kubernetes cluster.) However, it’s still easy to adapt these instructions to deploy to Cloud Run on GKE if you want more control over the infrastructure. This video has additional info on the differences between the two Cloud Run flavors.

Jekyll is written in Ruby. I’ll assume you already have Ruby and Jekyll installed, but if you need help, the Jekyll documentation has detailed instructions.

Creating and testing a Jekyll project

We’ll start by creating a new Jekyll project. (If you have an existing project, feel free to use it instead.)

$ jekyll new mysite
$ cd mysite

Now to run your site locally:

$ bundle exec jekyll serve

Jekyll will build your site locally and serve it on port 4000. Point your web browser to localhost:4000 to see.

You can edit your site by editing posts in the _posts directory, or by making changes to the configuration and layouts. As you make changes, jekyll serve will notice the file edits and rebuild your site automatically. We won’t go through all the details of how to use Jekyll here, but there’s a good tutorial in the Jekyll documentation.

Type CTRL-C to stop the server.

Using jekyll serve is a convenient way to view your site during development, but it’s not how you should run it in production. In fact, as we shall see, you don’t need Jekyll, or even Ruby, installed at all in your final production container. So let’s explore how to create an efficient production image of your site.

Creating a production Docker image

Docker has become the de facto standard way to package applications for deployment, and Cloud Run conveniently uses Docker images as its input format. Here we’ll create a Docker image to deploy your site.

Our desired image will serve our static site directly from Nginx, a high-performance web server. It’s a static site, so we don’t need Jekyll or even Ruby at runtime. However, we do need Jekyll to build the static site. That is, building and running have different requirements, so we’re going to separate them into different phases, as diagrammed below.

We will write the items in the blue boxes:

Site content and Jekyll configs as inputs to Jekyll
Nginx config files and startup scripts that launch Nginx with the correct configuration.
A Dockerfile that describes the build process.

Then when we perform a docker build, it will proceed in two phases. First, the build phase runs, taking our blog posts and Jekyll configs, and running Jekyll to produce HTML output. Second, the built HTML, along with the Nginx configs and startup scripts, are installed into the runtime image.

Configuring Nginx

Inside our mysite directory, create a subdirectory called _app. This directory will contain our Nginx configuration files and startup script. Because it begins with an underscore, Jekyll won’t try to build it as part of your site html. It will just pass directly through into your final runtime image.

$ mkdir _app
$ cd _app

Let’s write the Nginx configuration. Create a file called _app/nginx.conf.in with the following content:

worker_processes 1;
working_directory /app;
daemon off;

events {
  worker_connections 80;
}

http {
  include /etc/nginx/mime.types;

  server {
    listen $PORT;
    root /app/site;

    location / {
      try_files $uri $uri.html $uri/ /404.html;
    }
  }
}

This isn’t an Nginx tutorial, so I won’t go over everything here in detail. However, I’ll point out a couple of things.

First, we intentionally set worker_connections to 80. Cloud Run currently has a maximum concurrency of 80 (meaning it will allow up to 80 simultaneous connections to each instance). Nginx can often handle more, but because Cloud Run currently has this limit, we’ll pass that info on to Nginx so it can optimize itself.

Second, notice that we’re listening to port $PORT. This is actually not “valid” Nginx config syntax by itself. Instead, we’re going to write a startup script that treats this Nginx config as a template, and substitutes the actual port number here at runtime. This is because Cloud Run’s runtime specification states that the port isn’t actually known until runtime: it will tell you what port to listen to via the PORT environment variable.

So our next task is to write a script that reads the environment variable and substitutes the correct value into the config template. Create a file called _app/start.sh with the following content:

#!/bin/bash

[[-z "$PORT"]] && export PORT=8080
envsubst '$PORT' < /app/nginx.conf.in > /app/nginx.conf

exec nginx -c /app/nginx.conf

Let’s pick apart what this is doing. First, it checks that the PORT variable is set, and if not, it sets it to a default value of 8080. Cloud Run always sets the variable, but we’re also going to test this image locally outside Cloud Run, so we’ll make sure it has a value in that case.

Next, we substitute the value of the PORT environment variable in the nginx.conf.in file, and write the result to the final nginx.conf that we’ll use. Finally, we start Nginx.

It’s important to tell envsubst to substitute only the PORT environment variable (because our Nginx configuration file also includes syntax like $uri that we want envsubst to leave alone.)

It’s also important to prefix our Nginx command with exec. This causes Nginx to replace the script process so that it receives signals. This is important for Cloud Run to be able to control the container effectively.

Save the two files, and set the execute bit on your start script:

$ chmod a+x start.sh

You should now have the two files nginx.conf.in and start.sh inside the _app directory in your mysite project.

Writing the Dockerfile

Next we’re going to write a Dockerfile to build a Docker image of your site.

Go back to your mysite project directory, and create another subdirectory called _build. Again, because this name begins with an underscore, Jekyll won’t try to treat any of its files as site content.

$ cd /path/to/mysite
$ mkdir _build
$ cd _build

Create a file called _build/Dockerfile with the following content:

FROM ruby:2 AS build

RUN gem install bundler

WORKDIR /workspace
COPY Gemfile* /workspace/
RUN bundle install

COPY . /workspace
ENV JEKYLL_ENV=production
RUN bundle exec jekyll build

FROM nginx:1

WORKDIR /app
COPY _app /app
COPY --from=build /workspace/_site /app/site

CMD ["/app/start.sh"]

This may look a bit more complex than other “getting started” Dockerfiles you may have seen, so let’s take a closer look at what it’s doing.

Remember that our build process was going to proceed in two stages. You can see that now in this multi-stage Dockerfile. The first stage stage starts with the standard Ruby-Debian base image, installs your bundle (which should include Jekyll), and performs a production Jekyll build. The results are left in the /workspace/_site directory.

Then the second stage creates the final image that we will deploy to Cloud Run. It starts with the standard Nginx base image, copies in our Nginx config file and startup script, and also copies in the built html files from the first stage. Note that the final image includes only what is needed to serve your site: Nginx, but not Ruby or Jekyll. This two-stage strategy is a common best practice when building Docker images.

Testing your image locally

Now that we have a Dockerfile, we can build the image locally. Return to your mysite directory, and perform a docker build, pointing at our Dockerfile.

$ cd /path/to/mysite
$ docker build -t mysite -f _build/Dockerfile .

This will build your site as a Docker image and tag it with the name mysite. We can now try running it.

$ docker run --rm -it -p 8080:8080 mysite

This will run your image with your static site, and expose port 8080. Now you can test it by pointing your web browser to localhost:8080.

Hit CTRL-C to stop your Docker image.

Deploying to Cloud Run

Now that we have a working Docker image, it’s time to deploy to Cloud Run.

Setting up Google Cloud

If you do not yet have a Google Cloud project, go to the console and create one. You’ll need to enable billing in order to use Cloud Run. But don’t worry—unless your site has a truly massive amount of traffic, you’ll easily fit into the free tier for this tutorial.

Enable Cloud Build and Cloud Run in your project, if you haven’t already:

Navigate to Cloud Build in the console and click “Enable Cloud Build API”.
Navigate to Cloud Run in the console and click “Start Using Cloud Run”.

You’ll also need the Google Cloud SDK installed. Set the default project as follows (substituting your project ID for $MY_PROJECT_ID)

$ gcloud config set project $MY_PROJECT_ID

Building in the cloud

You could push a local image to the cloud in preparation to deploy to Cloud Run, but it is easier and safer to build in the cloud. We’ll create a simple configuration to build your site image in Google Cloud Build.

Create a file _build/cloudbuild.yaml. Copy the following into it:

steps:
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '--no-cache', '--pull',
      '--file', '_build/Dockerfile',
      '--tag', '$_IMAGE',
      '.']

images:
  - '$_IMAGE'

This configuration performs a Docker build using the _build/Dockerfile you created, and tags it with an image name that you need to specify when you invoke the build.

Move back into the root directory for your Jekyll site, and build using this command (substituting your project ID for $MY_PROJECT_ID).

$ cd /path/to/mysite
$ gcloud builds submit --config _build/cloudbuild.yaml \
    --substitutions _IMAGE=gcr.io/$MY_PROJECT_ID/mysite:v1

This will build your site’s Docker image, and upload it to Google Container Registry. If you like, you can view your images by visiting your container registry in the cloud console. You can also view your build results and logs in the console.

The image name you provide as the value of _IMAGE should be of the form gcr.io/$MY_PROJECT_ID/$SITE_NAME:$TAG in order to upload to Google Container Registry. In that name, $MY_PROJECT_ID must be your project ID. $SITE_NAME should be some identifying name for this image. (We used mysite in this case.) $TAG should be a name for this build. (We used v1 here, but you might consider using a timestamp, git hash, or other system of generating build IDs.)

Deploying to Cloud Run

Now, to deploy to Cloud run, type this command (substituting your project ID for $MY_PROJECT_ID).

$ gcloud beta run deploy mysite \
    --platform managed --region us-central1 \
    --image gcr.io/$MY_PROJECT_ID/mysite:v1 \
    --allow-unauthenticated --concurrency 80

Unless you have a very large site, this should take only a few seconds. When deployment is done, the command will output your site’s URL. It will look something like https://mysite-somecode.a.run.app. Open that URL in your web browser to view your site.

If this is a real site, you’ll probably want to point your own domain at it. You can do this in the console. Go to the Cloud Run section and click “Manage custom domains”.

Deploying updates

When you have updates, you should repeat the build and run steps above. I recommend using a different $TAG for each update. This will let you identify each build uniquely, making it easy to roll your site forward and back as needed.

For example, our initial deployment used a tag of v1. Make some edits to your site (maybe add or edit a post), and test it out locally using jekyll serve. Then, let’s build v2:

$ gcloud builds submit --config _build/cloudbuild.yaml \
    --substitutions _IMAGE=gcr.io/$MY_PROJECT_ID/mysite:v2
$ gcloud beta run deploy mysite \
    --platform managed --region us-central1 \
    --image gcr.io/$MY_PROJECT_ID/mysite:v2 \
    --allow-unauthenticated --concurrency 80

As you work with your site, you’ll probably want to create a rake task or similar script to generate new tags and automate those commands. I use Toys for this purpose, and my .toys.rb file looks something like this:

LOCAL_IMAGE = "mysite"
PROJECT = "my-project-id"
SERVICE = "mysite"

tool "run-local" do
  flag :no_cache
  include :exec, exit_on_nonzero_status: true
  def run
    cache_args = no_cache ? ["--pull", "--no-cache"] : []
    exec ["docker", "build"] + cache_args +
         ["-t", LOCAL_IMAGE, "-f", "_build/Dockerfile", "."]
    puts "Running on http://localhost:8080"
    exec ["docker", "run", "--rm", "-it", "-p", "8080:8080", LOCAL_IMAGE]
  end
end

tool "deploy" do
  flag :tag, default: Time.new.strftime("%Y-%m-%d-%H%M%S")
  include :exec, exit_on_nonzero_status: true
  def run
    image = "gcr.io/#{PROJECT}/#{SERVICE}:#{tag}"
    exec ["gcloud", "builds", "submit", "--project", PROJECT,
          "--config", "_build/cloudbuild.yaml",
          "--substitutions", "_IMAGE=#{image}"]
    exec ["gcloud", "beta", "run", "deploy", SERVICE,
          "--project", PROJECT, "--platform", "managed",
          "--region", "us-central1", "--allow-unauthenticated",
          "--image", image, "--concurrency", "80"]
  end
end

Cleaning up

When you’re done with this tutorial, if you do not want to continue serving your site, you can delete the project so you do not incur any expenses related to it.

Note that deleting the project will delete all resources related to it, including any VMs, databases, storage, and networking resources. If you are still using some of the project’s resources and do not want to delete the entire project, you can clean up after this tutorial by doing this:

Go to the Cloud Run console and delete the service you deployed for your site. (It might be called “mysite”.)
Go to your container registry in the console and delete the images for your site.

Where to go from here

The Cloud Run documentation includes a lot of additional information about deploying and running your site. Of particular interest are:

For more information about the runtime environment, or if you want to customize your container further, you should refer to the container runtime contract.

There’s a lot of hype around serverless these days, and not all of it is justified. For me, Cloud Run is the first product I’ve actually been somewhat excited about, because of how it successfully fuses serverless with containers, and because of how well it works for common use cases such as static sites.

Yes, you should provide a client library for your API! (RubyConf 2018)

Daniel Azuma — Tue, 13 Nov 2018 00:00:00 +0000

On Nov 13, 2018, I spoke on "Yes, you should provide a client library for your API!" at RubyConf in Los Angeles, CA. The talk discussed the benefits of providing client libraries for HTTP-based APIs, and some techniques for writing them.

Here’s a small list of resources that I either mentioned in the talk or are closely related. Feel free to share more in the comments!

Talk resources

Code generation frameworks

OpenAPI is an open standard that works well for REST APIs.
gRPC is a high-performance RPC framework originally developed by Google, that uses HTTP/2 and protocol buffers.
Apache Thrift is an RPC framework originally developed by Facebook.

Resources related to OpenAPI

Schema-first API Design is a great article for getting oriented with OpenAPI.
Generating OpenAPI From Code
Swagger integration libraries
Swagger editor for editing OpenAPI spec.

Resources related to gRPC

Protocol buffers is the structured data serialization mechanism used by gRPC.
HTTP/2: Smarter at Scale is a useful article describing HTTP/2 which underlies gRPC.
gRPC on HTTP/2: Engineering a Robust High Performance Protocol is another article useful for understanding gRPC.

Related resources

Slide deck discussing how Oracle and Azure manage APIs
GraphQL is a data schema system, similar in some respects but more limited in scope. You might find it useful in conjunction with a full API specification framework.
OpenCensus is an open framework for collecting and reporting instrumentation information.

Other API design resources

Google’s API design guide is public, and describes Google’s API design principles, some of which are specific to Google, but most of which should apply broadly to APIs in general.

Thanks

Thanks to Jeff who did a bunch of preliminary research and presented an earlier version of this talk at CodeBEAM, and to Graham for reviewing and providing suggestions. Thanks to Google for sponsoring my appearance at RubyConf this year.

Docker and OTP: Friends or Foes? (ElixirConf 2018)

Daniel Azuma — Fri, 07 Sep 2018 00:00:00 +0000

On Sept 7, 2018, I spoke on "Docker and OTP: Friends or Foes?" at ElixirConf in Bellevue, WA. The talk discussed ideas for making OTP applications work together with container-based deployments.

As a community, we sometimes believe that OTP and containers/cloud are incompatible, and we too often conclude that we must choose one over the other. I argued that we should instead look for creative ways to combine the strengths of the two platforms. As an example, I demonstrated an online real-time game, written using Elixir/Phoenix, that uses process migration to survive container-based updates.

Talk resources

Code and libraries used in the talk

The Elixir Tank game is on Github at https://github.com/ElixirSeattle/tanx.
The LibCluster library used to build an Erlang cluster from the Kubernetes API is on Github at https://github.com/bitwalker/libcluster.
The Horde library that provides “distributed” supervisor and registry implementations is on Github at https://github.com/derekkraan/horde.
The CRDT library underlying the handoff process is on Github at https://github.com/derekkraan/delta_crdt_ex.

Other libraries of interest

An alternate library that could be used for process migration is Swarm, which can be found on Github at https://github.com/bitwalker/swarm.
Lasp is a collection of libraries for building large distributed systems in Erlang/Elixir. It includes a replacement for distributed Erlang, as well as implementations for global registries, CRDTs, and more. Information is available at https://lasp-lang.org.

Links and articles

Gigalixir is a hosting service that is optimized for Elixir applications, and is able to perform OTP hot upgrades in containers.
Derek Kraan wrote a couple of articles useful for getting started with Horde: Introducing Horde and Getting Started with Horde.
Ellis Pritchard discusses the Kubernetes/OTP shutdown process in some depth in his article Graceful shutdown on Kubernetes with signals and Erlang OTP 20.
Chirag Singh Toor wrote up his experience writing a similar system, including detailed code. A very useful read!

I also intend to write a few posts myself covering some of this material in a bit more detail, so watch this space in the future.

Thanks

Thanks to Ben, Kyle, and Greg for joining me in writing the original Tanx app… has it really been three years?? Thanks to Google for sponsoring my appearance at ElixirConf this year, and to the Elixir team at Google for helpful feedback on my talk and demo.

DEV Community: Daniel Azuma

Beware Twitter/X

The fall of Twitter

The consequences of deleting your Twitter account

Where to go from here

Building a Discord Command in Ruby on Google Cloud Functions: Part 4

The challenge: size and timing

Deferred processing using pub/sub

Deploying a pub/sub subscriber

Publishing an event

Creating a multi-part response

Sending a deferred response

Creating a deferred task handler

Passing secrets to the deferred task

Sending multiple ressages

Now what?

Building a Discord Command in Ruby on Google Cloud Functions: Part 3

Responding to commands

Calling an external API

Signing up with API.Bible

Calling the API

Calling the API from the webhook

Handling secrets

Now what?

Building a Discord Command in Ruby on Google Cloud Functions: Part 2

Installing on a Discord server

Creating a command

Toys Scripts

Writing an API client

Authorizing Discord API calls

Creating the Command

Now what?

Building a Discord Command in Ruby on Google Cloud Functions: Part 1

Creating a Discord application

Writing a webhook

Hello Functions

Responding to pings

Validating Discord requests

Now what?

Building a Discord Command in Ruby on Google Cloud Functions

Contents

Should I use instance_eval or class_eval?

The “current object”

Changing the current object with instance_eval

Defining methods

The “current class”

Why are “current class” and “current object” distinct?

Why does this matter?

Investigating further

Designing a Ruby Serverless Runtime

A Ruby way of doing serverless

Functional Ruby

To share or not to share

Test first

The dependable runtime

Standards old and new

The serverless future

Is it time to replace Rake?

Rake and Make

Managing project scripts

Alternatives to Rake

Is it time to replace Rake?

Deploying My Blog to Google Cloud Run

Why serverless for static sites?

Jekyll on Cloud Run

Creating and testing a Jekyll project

Creating a production Docker image

Configuring Nginx

Writing the Dockerfile

Testing your image locally

Deploying to Cloud Run

Setting up Google Cloud

Building in the cloud

Deploying to Cloud Run

Deploying updates

Cleaning up

Where to go from here

Yes, you should provide a client library for your API! (RubyConf 2018)

Talk resources

Code generation frameworks