serverless-rack 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0e289b85392f4e213d35b038b1fdb7799465808977279b3c851d15e3f38a31cf
+  data.tar.gz: 5cfa5111685c7d22109325c0bbb6539aadcae750c7ea2407cd62285619a73544
+SHA512:
+  metadata.gz: 9c906ef876675f6df4bae686f50623bdb31769122e8ce36b82110c9eb92baab10c9a48308bfa7f9c2a8a7b3e27b2a4b531e95618f6898002a496666c7d9a98c6
+  data.tar.gz: 88c461157b7449c9fd4e974767d452e10059b87805916aed60392cd421b7745865d1dec7e23e0a1c645dd03b190a976ac09a2d913fdb29bc156c9c05ed1c5301

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# 1.0.0
+
+Feature parity with `serverless-wsgi`.
+
+# 0.0.1
+
+Initial release.

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'rack'
+
+group :test do
+  gem 'codecov', require: false
+  gem 'rake'
+  gem 'rspec'
+  gem 'rubocop', require: false
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Logan Raarup
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,392 @@
+<p align="center">
+  <img src="https://logandk.github.io/serverless-rack/assets/header.svg">
+</p>
+
+[![npm package](https://nodei.co/npm/serverless-rack.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/serverless-rack/)
+
+[![serverless](http://public.serverless.com/badges/v3.svg)](http://www.serverless.com)
+[![Build Status](https://travis-ci.org/logandk/serverless-rack.png?branch=master)](https://travis-ci.org/logandk/serverless-rack)
+[![Coverage Status](https://codecov.io/gh/logandk/serverless-rack/branch/master/graph/badge.svg)](https://codecov.io/gh/logandk/serverless-rack)
+[![Dependency Status](https://david-dm.org/logandk/serverless-rack.png)](https://david-dm.org/logandk/serverless-rack)
+[![Dev Dependency Status](https://david-dm.org/logandk/serverless-rack/dev-status.png)](https://david-dm.org/logandk/serverless-rack?type=dev)
+
+A Serverless v1.x plugin to build your deploy Ruby Rack applications using Serverless. Compatible
+Rack application frameworks include Sinatra, Cuba and Padrino.
+
+### Features
+
+- Transparently converts API Gateway and ALB requests to and from standard Rack requests
+- Supports anything you'd expect from Rack such as redirects, cookies, file uploads etc.
+- Bundler integration, including dockerized bundling of binary dependencies
+- Convenient `rack serve` command for serving your application locally during development
+- CLI commands for remote execution of Ruby code (`rack exec`), rake tasks ('rack rake') and shell commands (`rack command`)
+
+## Install
+
+```
+sls plugin install -n serverless-rack
+```
+
+This will automatically add the plugin to `package.json` and the plugins section of `serverless.yml`.
+
+## Sinatra configuration example
+
+```
+project
+├── api.rb
+├── config.ru
+├── Gemfile
+└── serverless.yml
+```
+
+### api.rb
+
+A regular Sinatra application.
+
+```ruby
+require 'sinatra'
+
+get '/cats' do
+  'Cats'
+end
+
+get '/dogs/:id' do
+  'Dog'
+end
+```
+
+### config.ru
+
+```
+require './api'
+run Sinatra::Application
+```
+
+### serverless.yml
+
+All functions that will use Rack need to have `rack_adapter.handler` set as the Lambda handler and
+use the default `lambda-proxy` integration for API Gateway. This configuration example treats
+API Gateway as a transparent proxy, passing all requests directly to your Sinatra application,
+and letting the application handle errors, 404s etc.
+
+```yaml
+service: example
+
+provider:
+  name: aws
+  runtime: ruby2.5
+
+plugins:
+  - serverless-rack
+
+functions:
+  api:
+    handler: rack_adapter.handler
+    events:
+      - http: ANY /
+      - http: ANY {proxy+}
+```
+
+### Gemfile
+
+Add Sinatra to the application bundle.
+
+```
+source 'https://rubygems.org'
+
+gem 'sinatra'
+```
+
+## Deployment
+
+Simply run the serverless deploy command as usual:
+
+```
+$ bundle install --path vendor/bundle
+$ sls deploy
+Serverless: Packaging Ruby Rack handler...
+Serverless: Packaging gem dependencies using docker...
+Serverless: Packaging service...
+Serverless: Excluding development dependencies...
+Serverless: Uploading CloudFormation file to S3...
+Serverless: Uploading artifacts...
+Serverless: Uploading service .zip file to S3 (1.64 MB)...
+Serverless: Validating template...
+Serverless: Updating Stack...
+Serverless: Checking Stack update progress...
+..............
+Serverless: Stack update finished...
+```
+
+## Usage
+
+### Automatic bundling of gems
+
+You'll need to include any gems that your application uses in the bundle
+that's deployed to AWS Lambda. This plugin helps you out by doing this automatically,
+as long as you specify your required gems in a [Gemfile](https://bundler.io/gemfile.html):
+
+```
+source 'https://rubygems.org'
+
+gem 'rake'
+gem 'sinatra'
+```
+
+For more information, see https://bundler.io/docs.html.
+
+### Dockerized bundling
+
+If your application depends on any gems that include compiled binaries, these
+must be compiled for the lambda execution environment. Enabling the `dockerizeBundler` configuration
+option will fetch and build the gems using a [docker image](https://hub.docker.com/r/logandk/serverless-rack-bundler)
+that emulates the lambda environment:
+
+```yaml
+custom:
+  rack:
+    dockerizeBundler: false
+```
+
+### Bundler configuration
+
+You can use the automatic bundling functionality of _serverless-rack_ without the Rack request
+handler itself by including the plugin in your `serverless.yml` configuration, without specifying
+`rack_adapter.handler` as the handler for any of your lambda functions.
+This will omit the Rack handler from the package, but include any gems specified in the `Gemfile`.
+
+If you don't want to use automatic gem bundling you can set `custom.rack.enableBundler` to `false`:
+
+```yaml
+custom:
+  rack:
+    enableBundler: false
+```
+
+In order to pass additional arguments to `bundler` when installing requirements, the `bundlerArgs`
+configuration option is available:
+
+```yaml
+custom:
+  rack:
+    bundlerArgs: --no-cache
+```
+
+If your `bundler` executable is not in `$PATH`, set the path explicitly using the `bundlerBin`
+configuration option:
+
+```yaml
+custom:
+  rack:
+    bundlerBin: /path/to/bundler
+```
+
+### Local server
+
+For convenience, a `sls rack serve` command is provided to run your Rack application
+locally. This command requires the `rack` gem to be installed, and acts as a simple
+wrapper for `rackup`.
+
+By default, the server will start on port 5000.
+
+```
+$ sls rack serve
+[2019-01-03 18:13:21] INFO  WEBrick 1.4.2
+[2019-01-03 18:13:21] INFO  ruby 2.5.1 (2018-03-29) [x86_64-linux-gnu]
+[2019-01-03 18:13:21] INFO  WEBrick::HTTPServer#start: pid=25678 port=5000
+```
+
+Configure the port using the `-p` parameter:
+
+```
+$ sls rack serve -p 8000
+[2019-01-03 18:13:21] INFO  WEBrick 1.4.2
+[2019-01-03 18:13:21] INFO  ruby 2.5.1 (2018-03-29) [x86_64-linux-gnu]
+[2019-01-03 18:13:21] INFO  WEBrick::HTTPServer#start: pid=25678 port=8000
+```
+
+When running locally, an environment variable named `IS_OFFLINE` will be set to `True`.
+So, if you want to know when the application is running locally, check `ENV["IS_OFFLINE"]`.
+
+### Remote command execution
+
+The `rack exec` command lets you execute ruby code remotely:
+
+```
+$ sls rack exec -c "puts (1 + Math.sqrt(5)) / 2"
+1.618033988749895
+
+$ cat count.rb
+3.times do |i|
+  puts i
+end
+
+$ sls rack exec -f count.rb
+0
+1
+2
+```
+
+The `rack command` command lets you execute shell commands remotely:
+
+```
+$ sls rack command -c "pwd"
+/var/task
+
+$ cat script.sh
+#!/bin/bash
+echo "dlrow olleh" | rev
+
+$ sls rack command -f script.sh
+hello world
+```
+
+The `rack rake` command lets you execute Rake tasks remotely:
+
+```
+$ sls rack rake -t "db:rollback STEP=3"
+```
+
+### Explicit routes
+
+If you'd like to be explicit about which routes and HTTP methods should pass through to your
+application, see the following example:
+
+```yaml
+service: example
+
+provider:
+  name: aws
+  runtime: ruby2.5
+
+plugins:
+  - serverless-rack
+
+functions:
+  api:
+    handler: rack_adapter.handler
+    events:
+      - http:
+          path: cats
+          method: get
+          integration: lambda-proxy
+      - http:
+          path: dogs/{id}
+          method: get
+          integration: lambda-proxy
+```
+
+### Custom domain names
+
+If you use custom domain names with API Gateway, you might have a base path that is
+at the beginning of your path, such as the stage (`/dev`, `/stage`, `/prod`). In this case, set
+the `API_GATEWAY_BASE_PATH` environment variable to let `serverless-rack` know.
+
+The example below uses the [serverless-domain-manager](https://github.com/amplify-education/serverless-domain-manager)
+plugin to handle custom domains in API Gateway:
+
+```yaml
+service: example
+
+provider:
+  name: aws
+  runtime: ruby2.5
+  environment:
+    API_GATEWAY_BASE_PATH: ${self:custom.customDomain.basePath}
+
+plugins:
+  - serverless-rack
+  - serverless-domain-manager
+
+functions:
+  api:
+    handler: rack_adapter.handler
+    events:
+      - http: ANY /
+      - http: ANY {proxy+}
+
+custom:
+  customDomain:
+    basePath: ${opt:stage}
+    domainName: mydomain.name.com
+    stage: ${opt:stage}
+    createRoute53Record: true
+```
+
+### File uploads
+
+In order to accept file uploads from HTML forms, make sure to add `multipart/form-data` to
+the list of content types with _Binary Support_ in your API Gateway API. The
+[serverless-apigw-binary](https://github.com/maciejtreder/serverless-apigw-binary)
+Serverless plugin can be used to automate this process.
+
+Keep in mind that, when building Serverless applications, uploading
+[directly to S3](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingHTTPPOST.html)
+from the browser is usually the preferred approach.
+
+### Raw context and event
+
+The raw context and event from AWS Lambda are both accessible through the Rack
+request. The following example shows how to access them when using Flask:
+
+```ruby
+require 'sinatra'
+
+get '/' do
+  puts request.env['serverless.event']
+  puts request.env['serverless.context']
+end
+```
+
+### Text MIME types
+
+By default, all MIME types starting with `text/` and the following whitelist are sent
+through API Gateway in plain text. All other MIME types will have their response body
+base64 encoded (and the `isBase64Encoded` API Gateway flag set) in order to be
+delivered by API Gateway as binary data (remember to add any binary MIME types that
+you're using to the _Binary Support_ list in API Gateway).
+
+This is the default whitelist of plain text MIME types:
+
+- `application/json`
+- `application/javascript`
+- `application/xml`
+- `application/vnd.api+json`
+- `image/svg+xml`
+
+In order to add additional plain text MIME types to this whitelist, use the
+`textMimeTypes` configuration option:
+
+```yaml
+custom:
+  rack:
+    textMimeTypes:
+      - application/custom+json
+      - application/vnd.company+json
+```
+
+## Usage without Serverless
+
+The AWS API Gateway to Rack mapping module is available as a gem.
+
+Use this gem if you need to deploy Ruby functions to handle
+API Gateway events directly, without using the Serverless framework.
+
+```
+gem install --install-dir vendor/bundle serverless-rack
+```
+
+Initialize your Rack application and in your Lambda event handler, call
+the request mapper:
+
+```ruby
+require 'serverless_rack'
+
+$app ||= Proc.new do |env|
+  ['200', {'Content-Type' => 'text/html'}, ['A barebones rack app.']]
+end
+
+def handler(event:, context:)
+  handle_request(app: $app, event: event, context: context)
+end
+```

data/lib/serverless_rack.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+# This module handles conversion between API Gateway/ALB and Rack requests/responses.
+#
+# Author: Logan Raarup <logan@logan.dk>
+
+require 'rack'
+require 'base64'
+
+TEXT_MIME_TYPES = [
+  'application/json',
+  'application/javascript',
+  'application/xml',
+  'application/vnd.api+json',
+  'image/svg+xml'
+].freeze
+
+def keepalive_event?(event)
+  ['aws.events', 'serverless-plugin-warmup'].include?(event['source'])
+end
+
+def parse_script_name(event, headers)
+  if ENV['API_GATEWAY_BASE_PATH']
+    "/#{ENV['API_GATEWAY_BASE_PATH']}"
+  elsif (headers['Host'] || '').include?('amazonaws.com')
+    "/#{event['requestContext']['stage']}"
+  else
+    ''
+  end
+end
+
+def parse_path_info(event)
+  # If a user is using a custom domain on API Gateway, they may have a base
+  # path in their URL. This allows us to strip it out via an optional
+  # environment variable.
+  if ENV['API_GATEWAY_BASE_PATH']
+    base_path = "/#{ENV['API_GATEWAY_BASE_PATH']}"
+    return event['path'][base_path.length..-1] if event['path'].start_with?(base_path)
+  end
+
+  event['path']
+end
+
+def parse_body(event)
+  if event['isBase64Encoded']
+    Base64.decode64(event['body'])
+  else
+    event['body'] || ''
+  end
+end
+
+def parse_http_headers(headers)
+  headers = headers.map do |key, value|
+    ["HTTP_#{key.upcase.tr('-', '_')}", value]
+  end
+
+  headers = headers.reject do |key, _value|
+    %w[HTTP_CONTENT_TYPE HTTP_CONTENT_LENGTH].include?(key)
+  end
+
+  headers.to_h
+end
+
+def build_environ(event:, context:, headers:, body:)
+  {
+    'REQUEST_METHOD' => event['httpMethod'],
+    'SCRIPT_NAME' => parse_script_name(event, headers),
+    'PATH_INFO' => parse_path_info(event),
+    'QUERY_STRING' => Rack::Utils.build_query(event['queryStringParameters'] || {}),
+    'SERVER_NAME' => headers['Host'] || 'lambda',
+    'SERVER_PORT' => headers['X-Forwarded-Port'] || '80',
+    'CONTENT_LENGTH' => body.bytesize.to_s,
+    'CONTENT_TYPE' => headers['Content-Type'] || '',
+    'SERVER_PROTOCOL' => 'HTTP/1.1',
+    'REMOTE_ADDR' => (event['requestContext']['identity'] || {})['sourceIp'] || '',
+    'REMOTE_USER' => (event['requestContext']['authorizer'] || {})['principalId'] || '',
+    'rack.version' => Rack::VERSION,
+    'rack.url_scheme' => headers['X-Forwarded-Proto'] || 'http',
+    'rack.input' => StringIO.new(body),
+    'rack.errors' => $stderr,
+    'rack.multithread' => false,
+    'rack.multiprocess' => false,
+    'rack.run_once' => false,
+    'serverless.event' => event,
+    'serverless.context' => context,
+    'serverless.authorizer' => event['requestContext']['authorizer']
+  }.merge(parse_http_headers(headers))
+end
+
+def format_status_description(event:, status:)
+  return {} unless event['requestContext']['elb']
+
+  # If the request comes from ALB we need to add a status description
+  description = Rack::Utils::HTTP_STATUS_CODES[status]
+
+  { 'statusDescription' => "#{status} #{description}" }
+end
+
+def text_mime_type?(headers:, text_mime_types:)
+  mime_type = headers['Content-Type'] || 'text/plain'
+
+  return false if headers['Content-Encoding']
+  return true if mime_type.start_with?('text/')
+  return true if text_mime_types.include?(mime_type)
+
+  false
+end
+
+def format_body(body:, headers:, text_mime_types:)
+  response_data = ''
+  body.each { |part| response_data += part }
+
+  return {} if response_data.empty?
+
+  if text_mime_type?(headers: headers, text_mime_types: text_mime_types)
+    {
+      'body' => response_data,
+      'isBase64Encoded' => false
+    }
+  else
+    {
+      'body' => Base64.strict_encode64(response_data),
+      'isBase64Encoded' => true
+    }
+  end
+end
+
+def all_casings(input_string)
+  # Permute all casings of a given string.
+  # A pretty algoritm, via @Amber
+  # http://stackoverflow.com/questions/6792803/finding-all-possible-case-permutations-in-python
+  if input_string.empty?
+    yield ''
+  else
+    first = input_string[0]
+    if first.downcase == first.upcase
+      all_casings(input_string[1..-1]) do |sub_casing|
+        yield first + sub_casing
+      end
+    else
+      all_casings(input_string[1..-1]) do |sub_casing|
+        yield first.downcase + sub_casing
+        yield first.upcase + sub_casing
+      end
+    end
+  end
+end
+
+def format_headers(headers:)
+  headers = headers.to_hash
+
+  # If there are headers multiple occurrences, e.g. Set-Cookie, create
+  # case-mutated variations in order to pass them through APIGW.
+  # This is a hack that's currently needed.
+  headers.keys.each do |key|
+    values = headers[key].split("\n")
+
+    next if values.size < 2
+
+    headers.delete(key)
+
+    all_casings(key) do |casing|
+      headers[casing] = values.shift
+      break if values.empty?
+    end
+  end
+
+  { 'headers' => headers }
+end
+
+def format_response(event:, status:, headers:, body:, text_mime_types:)
+  response = { 'statusCode' => status }
+
+  response.merge!(
+    format_headers(headers: headers)
+  )
+
+  response.merge!(
+    format_status_description(event: event, status: status)
+  )
+
+  response.merge!(
+    format_body(
+      body: body,
+      headers: headers,
+      text_mime_types: text_mime_types
+    )
+  )
+
+  response
+end
+
+def handle_request(app:, event:, context:, config: {})
+  return {} if keepalive_event?(event)
+
+  status, headers, body = app.call(
+    build_environ(
+      event: event,
+      context: context,
+      headers: Rack::Utils::HeaderHash.new(event['headers'] || {}),
+      body: parse_body(event)
+    )
+  )
+
+  format_response(
+    event: event,
+    status: status,
+    headers: headers,
+    body: body,
+    text_mime_types: TEXT_MIME_TYPES + config['text_mime_types'].to_a
+  )
+end

data/serverless-rack.gemspec

@@ -0,0 +1,26 @@
+Gem::Specification.new do |s|
+  s.name        = 'serverless-rack'
+  s.version     = '1.0.0'
+  s.summary     =
+    'Serverless plugin to deploy Ruby Rack applications (Sinatra/Padrino/Cuba etc.) '\
+    'and bundle gems'
+  s.description =
+    'A Serverless v1.x plugin to build your deploy Ruby Rack applications using '\
+    'Serverless. Compatible Rack application frameworks include Sinatra, '\
+    'Cuba and Padrino.'
+  s.authors     = ['Logan Raarup']
+  s.email       = 'logan@logan.dk'
+  s.files       = [
+    'lib/serverless_rack.rb',
+    'CHANGELOG.md',
+    'Gemfile',
+    'LICENSE',
+    'README.md',
+    'serverless-rack.gemspec'
+  ]
+  s.homepage = 'https://github.com/logandk/serverless-rack'
+  s.license = 'MIT'
+
+  s.required_ruby_version = '>= 2.2.0'
+  s.add_dependency 'rack', '~> 2.0'
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: serverless-rack
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Logan Raarup
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-01-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A Serverless v1.x plugin to build your deploy Ruby Rack applications
+  using Serverless. Compatible Rack application frameworks include Sinatra, Cuba and
+  Padrino.
+email: logan@logan.dk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- lib/serverless_rack.rb
+- serverless-rack.gemspec
+homepage: https://github.com/logandk/serverless-rack
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Serverless plugin to deploy Ruby Rack applications (Sinatra/Padrino/Cuba
+  etc.) and bundle gems
+test_files: []