Skip to content

Latest commit

 

History

History
190 lines (134 loc) · 9.1 KB

README.md

File metadata and controls

190 lines (134 loc) · 9.1 KB
Raw

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

Build Status Gem Version Support

BoltOps Badge

Please watch/star this repo to help grow and support the project.

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

What is Ruby on 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 and deploy an application to AWS Lambda.

Understanding AWS Lambda and API Gateway is key to understanding Jets conceptually. Jets map your code to Lambda functions and other AWS Resources like API Gateway and Event Rules.

  • 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.
  • EventBridge Rules are events as a service. You can automatically run Lambda functions triggered from AWS services. You decide what events to catch and how to react to them.

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 lambda_handler(event:, context:)
  puts "hello world"
  {hello: "world"}
end

Here's the function in the Lambda console:

Code Example in AWS Lambda console

Though simple functions are supported by Jets, they do not add as much value as other ways to write Ruby code with Jets. Classes like Controllers and Jobs add many conveniences and are more powerful to use. We’ll cover them next.

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 compatible 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

Helper methods like params provide the parameters from the API Gateway event. The render method returns a Lambda Proxy structure that API Gateway understands.

Jets creates single Lambda functions to handle your Jets Controller requests. The Lambda Function handler is a shim that routes to your controller action.

Jets Routing

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

config/routes.rb:

Jets.application.routes.draw do
  resources :posts
  any "posts/hot", to: "posts#hot" # GET, POST, PUT, etc request all work
end

The routes.rb gets translated to API Gateway resources:

API Gateway Resources generated from routes in AWS console

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 outside 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

Jets Jobs in AWS Lambda Console

HardJob#dig runs every 10 hours, and HardJob#lift runs every 12 hours. The rate and cron methods created CloudWatch Event Rules. Example:

CloudWatch Event Rules in AWS Console

This simple example uses Scheduled Events. There are many more possibilities, see the Events Docs.

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.

Live Demos

Here are some demos of Jets applications:

Please feel free to add your examples to the rubyonjets/examples repo.

More Info

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

Learning Content