Ruby Serverless Framework
Latest commit 56a04d4 Nov 13, 2018

README.md

Ruby and Lambda splat out a baby and that child's name is Jets.

Build Status CircleCI Gem Version

Upgrading: If you are upgrading Jets, please check on the Upgrading Notes.

What is Jets?

Jets is a Ruby Serverless Framework. Jets allows you to create serverless applications with a beautiful language: Ruby. It includes everything required to build an application and deploy it to AWS Lambda.

It is key to understand AWS Lambda and API Gateway to understand Jets conceptually. Jets maps your code to Lambda functions and API Gateway resources.

  • AWS Lambda is Functions as a Service. It allows you to upload and run functions without worrying about the underlying infrastructure.
  • API Gateway is the routing layer for Lambda. It is used to route REST URL endpoints to Lambda functions.

The official documentation is at Ruby on Jets.

Refer to the official docs for more info, but here's a quick intro.

Jets Functions

Jets supports writing AWS Lambda functions with Ruby. You define them in the app/functions folder. A function looks like this:

app/functions/simple.rb:

def handle(event, context)
  puts "hello world"
  {hello: "world"}
end

Though simple functions are supported by Jets, aside from the ability to use Ruby, they do not as much value as other ways to write code with Jets.

Jets Controllers

A Jets controller handles a web request and renders a response. Here's an example:

app/controllers/posts_controller.rb:

class PostsController < ApplicationController
  def index
    # renders Lambda Proxy structure compatiable with API Gateway
    render json: {hello: "world", action: "index"}
  end

  def show
    id = params[:id] # params available
    # puts goes to the lambda logs
    puts event # raw lambda event available
    render json: {action: "show", id: id}
  end
end

Jets creates Lambda functions for each public method in your controller.

Jets Routing

You connect Lambda functions to API Gateway URL endpoints with a routes file:

config/routes.rb:

Jets.application.routes.draw do
  get  "posts", to: "posts#index"
  get  "posts/new", to: "posts#new"
  get  "posts/:id", to: "posts#show"
  post "posts", to: "posts#create"
  get  "posts/:id/edit", to: "posts#edit"
  put  "posts", to: "posts#update"
  delete  "posts", to: "posts#delete"

  resources :comments # expands to the RESTful routes above

  any "posts/hot", to: "posts#hot" # GET, POST, PUT, etc request all work
end

Test your API Gateway endpoints with curl or postman. Note, replace the URL endpoint with the one that is created:

$ curl -s "https://quabepiu80.execute-api.us-east-1.amazonaws.com/dev/posts" | jq .
{
  "hello": "world",
  "action": "index"
}

Jets Jobs

A Jets job handles asynchronous background jobs performed outside of the web request/response cycle. Here's an example:

app/jobs/hard_job.rb:

class HardJob < ApplicationJob
  rate "10 hours" # every 10 hours
  def dig
    puts "done digging"
  end

  cron "0 */12 * * ? *" # every 12 hours
  def lift
    puts "done lifting"
  end
end

HardJob#dig runs every 10 hours and HardJob#lift runs every 12 hours.

Jets Deployment

You can test your application with a local server that mimics API Gateway: Jets Local Server. Once ready, deploying to AWS Lambda is a single command.

jets deploy

After deployment, you can test the Lambda functions with the AWS Lambda console or the CLI.

AWS Lambda Console

Lambda Console

Live Demo

Here's a Live Demo of the quintessential CRUD Jets app.

Rails Support

Jets Mega Mode provides Rails support with little effort. This allows you to run a Rails application on AWS Lambda. Refer to the Rails Support docs for more info. Also here's a Tutorial Blog Post on Mega Mode: Run Rails on AWS Lambda.

More Info

For more documentation, check out the official docs: Ruby on Jets. Here's a list of useful links:

Learning Content