LFA 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f5b77411891b6b8397a92d8c12dabb238673b7cd1c0d0b63aa8d7c1028f82d5b
+  data.tar.gz: 3d5c792faefa9d0ec321e0b1c18e32c962f1b805cb33e87a50624615f2ff5cfe
+SHA512:
+  metadata.gz: 3d9d9dbd849df541ee2f35e6f72d4699f925d657213c874b48405fcf004bdfe3be61899ab094afd4dcea3bc6cb6121aa21f05a74e36a816ed71faaac2456d505
+  data.tar.gz: 00e90234cdfadff79c2107e26717e671b39515e7ab301c21cde26e98952a7ada9f7881cdd546e5da9f4e2a75b1e26f7e76d97ec832f3bb74f7de6ca8d04547b9

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in LFA.gemspec
+gemspec
+
+# To launch LFA for testing
+gem "rackup"
+gem "puma"
+
+gem "rake", "~> 13.0"
+
+gem "test-unit", "~> 3.0"

data/LFA.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/LFA/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "LFA"
+  spec.version = LFA::VERSION
+  spec.authors = ["Satoshi Tagomori"]
+  spec.email = ["tagomoris@gmail.com"]
+
+  spec.summary = "Lambda Function Adapter for web applications"
+  spec.description = "Web application framework to mount AWS Lambda functions as request handlers"
+  spec.homepage = "https://github.com/tagomoris/LFA"
+  spec.license = "MIT"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.add_dependency "rack"
+  spec.add_development_dependency "test-unit"
+  spec.add_development_dependency "rake"
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Satoshi Tagomori
+
+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,363 @@
+# LFA - Lambda Function Adapter
+
+**LFA is under development, and not released yet.**
+
+LFA is a web application framework in Ruby (Rack framework), to run AWS Lambda functions (migrated from AWS API Gateway integration) on Ruby's application servers (Unicorn, Puma, etc).
+
+The main purposes of LFA are:
+
+* run Lambda functions on EC2 (or container hosting services) **temporarily**
+* test Lambda function as web request handler on our laptop
+
+LFA was initially designed to host webapps migrated from AWS Lambda to EC2/ECS/k8s/etc by moving functions to app servers as-is. This provides time to engineers for re-implemention of native stand alone web applications.
+
+The 2nd purpose (testing on laptop) was found eventually during the development of LFA. We can't test web request handlers of AWS Lambda functions on our laptop directly (because we don't have local API Gateway), but we can do it locally with LFA on laptop. This MAY improve our dev-experience a little, or more.
+
+## Features
+
+LFA mounts Lambda functions on request paths, and routes requests to those functions.
+
+Lambda functions are:
+
+* mounted on specified paths, by AWS Lambda's handler specification `funcfile.Modname.method_name`
+* configured by `ENV` environment variables (just like AWS Lambda)
+* called with `event` and `context` arguments per HTTP request (translated from Rack `env`)
+
+LFA uses a YAML file to:
+
+* configure functions with those environment variables
+* configure resource-function relations (just like AWS API Gateway)
+
+Functions on LFA will be loaded in (semi-)isolated module spaces. Functions will not effect to other functions (at least, unintentionally). See "Limitations" section below about the function isolation.
+
+### Features not supported yet
+
+The features below are not supported yet, but will be implemented eventually.
+
+* CORS support and built-in `OPTIONS` method request handler
+* Loading functions from `.zip` archives
+
+## How to run LFA
+
+### Installation
+
+Add LFA to your application's Gemfile:
+
+```ruby
+gem 'LFA'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install LFA
+
+### Configuration
+
+Write a YAML configuration file, and a `config.ru` Rack app file.
+
+Rack app file is just to load LFA with the following YAML file.
+
+```ruby
+# config.ru
+require 'LFA'
+run LFA.ignition!('config.yaml')
+```
+
+The YAML configuration file is to describe application resources, and functions to be called per request. The YAML requires 2 child elements:
+
+* `resources`: the list of nested resources, almost equal to the resources on AWS API Gateway
+* `functions`: the list of functions, referred from resources
+
+```yaml
+# config.yaml
+---
+resources:
+  - path: /api
+    resources:
+      - path: /country
+        methods:
+          GET: myfunc-countries
+      - path: /data
+        resources:
+          - path: /csv
+            methods:
+              GET: myfunc-data-csv
+          - path: /json
+            methods:
+              GET: myfunc-data-json
+  - path: /web
+    resources:
+      - path: /blog/{entry_id}
+        methods:
+          GET: blog-entry-get
+      - path: /assets/{asset_path+}
+        methods:
+          ANY: blog-asset-access
+functions:
+  - name: myfunc-countries
+    handler: myfunc.Countries.process
+    env:
+      DATABASE_HOSTNAME: mydb.local
+      DATABASE_PASSWORD: this-is-the-top-secret
+  - name: myfunc-data-csv
+    handler: myfunc.Data.process
+    env:
+      OUTPUT_DATA_TYPE: csv
+  - name: myfunc-data-json
+    handler: myfunc.Data.process
+    env:
+      OUTPUT_DATA_TYPE: json
+# omit blog-entry-get and blog-asset-access
+```
+
+The actual Lambda functions should be placed on the same directory with those configuration files.
+LFA will load `Countries` module from `myfunc.rb`, then call its `process` method for the request path `/api/country`.
+
+### Ignition
+
+Run your Rack application as usual (for example, with `puma`):
+
+    $ puma config.ru
+
+Or, using `rackup` (requires `gem i rackup`)
+
+    $ rackup --server puma config.ru
+
+## Limitation
+
+The separation of Lambda functions is not perfect. That means:
+
+* The Ruby script `funcfile` of Lambda handler `funcfile.Modname.method_name` is loaded in an isolated namespace
+* Libraries `require`-ed from the Lambda file are NOT isolated, and be shared by all Lambda functions in the process
+* `ENV` access out of Lambda handler context in `require`-ed files will see the original `ENV`, instead of `env` configured
+
+To avoid those limitations, the Lambda functions loaded by LFA should take care of the following things.
+
+### Use common set of libraries
+
+Lambda functions should use the common set of libraries. That means, Lambda functions should:
+
+* have a common `lib` directory for its internal libraries
+* have a single `Gemfile` (and `Gemfile.lock`) to use the common set of gems
+
+If the Lambda functions are of single application, these things will be satisfied usually. Otherwise, don't share a single LFA process.
+
+### Create handler object/module in function files
+
+If your Lambda function's handler module is defined in `funcfile`, it's totally OK.
+
+```ruby
+# func.rb
+
+module Modname
+  def self.method_name(event:, context:)
+    # ...
+  end
+end
+# OK
+```
+
+But if the `funcfile` just requires your library and the library defines the handler module or instantiate the handler object, it MAY be NOT OK because that module/object are shared between different functions. It SHOULD be BAD when the handler object has internal states.
+
+```ruby
+# func.rb
+require_relative './lib/myapp/handler'
+# and it provides Modname module
+
+# MAY be NOT OK
+```
+
+If your Lambda handler has to have internal states, you should define a class, and instantiate it in `funcfile`, as following:
+
+```ruby
+# lib/myapp/handler.rb
+class MyHandler
+  def initialize
+    @internal_cache = {}
+  end
+
+  def process(event:, context:)
+    # ...
+  end
+end
+
+# func.rb
+require_relative './lib/myapp/handler'
+Handler = MyHandler.new
+
+# and specify the handler: func.Handler.process
+# OK!
+```
+
+### Refer ENV in dynamic manner
+
+LFA overrides the `ENV` reference in `funcfile`.
+
+```ruby
+# func.rb
+module HandlerA
+  DB_HOST = ENV['DB_HOST'] # this refers configured `env`
+
+  def process(event:, context:)
+    # ...
+  end
+end
+```
+
+But the `ENV` reference in the static context (code not in methods) in required libraries will refer the original environment variables of the LFA process, instead of configured `env` key-value pairs.
+
+```ruby
+# func.rb
+require_relative './lib/myapp/handler'
+Handler = HandlerB.new
+
+# lib/myapp/handler.rb
+class HandlerB
+  DB_HOST = ENV['DB_HOST'] # this refers the process's environment variables
+
+  def process(event:, context:)
+    # ...
+  end
+end
+```
+
+Even in libraries, code in methods called from `funcfile` will refer the configured `env`. So, `ENV` references should be written in methods, called dynamically.
+
+```ruby
+# func.rb
+require_relative './lib/myapp/handler'
+Handler = HandlerB.new
+
+# lib/myapp/handler.rb
+class HandlerB
+  def initialize
+    @db_host = ENV['DB_HOST'] # this refers the `env` configured
+  end
+
+  def process(event:, context:)
+    # Or, refer ENV in this handler method
+    # ...
+  end
+end
+```
+
+Gem libraries referring `ENV` should be initiated in methods, dynamically, as well.
+
+## Predefined Handlers
+
+### CORS: Preflight Request Handler
+
+Just like enabling `CORS` on AWS API Gateway, LFA has the built-in CORS preflight request handler. It can respond to `OPTIONS` request on resources, instead of Lambda functions.
+
+For the details of CORS requests/responses, see [MDN documents](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) or any other resources.
+
+To enable CORS preflight request handler, specify `CORS` as `handler`:
+
+```yaml
+resources:
+  - path: /a
+    methods:
+      GET: func1-myapp1-yay
+      OPTIONS: cors-1
+functions:
+  - name: cors-1
+    handler: CORS
+    params:
+      allowOrigins:
+        - '*'
+      allowMethods:
+        - GET
+        - OPTIONS
+      allowHeaders:
+        - Content-Type
+        - Authorization
+```
+
+All parameters of the handler should be under `params` key. Available parameters are:
+
+#### allowOrigins
+
+Fixed values for the response header `access-control-allow-origin`. A string, or list of strings.
+
+```yaml
+allowOrigins: '*'
+allowOrigins: 'https://example.com, https://www.example.com'
+allowOrigins:
+    - 'https://example.com'
+    - 'https://www.example.com'
+```
+
+Exclusive with `mirrorAllowOrigin`. One of `allowOrigins` or `mirrorAllowOrigin` should be specified.
+
+#### mirrorAllowOrigin
+
+`true` or `false` (or missing) value, which specifies to respond `access-control-allow-origin` value with the value of the request header `Origin`.
+
+```yaml
+mirrorAllowOrigin: true
+```
+
+The handler with `mirrorAllowOrigin: true` will respond `access-control-allow-origin: https://example.com` for the request with a header `origin: https://example.com`.
+
+Exclusive with `allowOrigins`. One of `allowOrigins` or `mirrorAllowOrigin` should be specified.
+
+#### allowMethods
+
+Fixed values for the response header `access-control-allow-methods`. A string, or list of strings. Should be specified.
+
+```yaml
+allowMethods: GET, POST, PUT, DELETE, OPTIONS
+allowMethods:
+  - GET
+  - POST
+  - OPTIONS
+```
+
+#### allowHeaders
+
+Fixed values for the response header `access-control-allow-headers`. A string, or list of strings. Optional.
+
+```yaml
+allowHeaders: x-my-custom-header
+allowHeaders:
+  - authorization
+  - x-my-custom-header
+```
+
+#### allowCredentials
+
+`true` or `false` (or missing) to specify `access-control-allow-credentials`. Optional.
+
+```yaml
+allowCredentials: true
+```
+
+#### exposeHeaders
+
+Fixed values for the response header `access-control-expose-headers`. A string, or list of strings. Optional.
+
+```yaml
+exposeHeaders: x-my-custom-header
+exposeHeaders:
+  - x-my-custom-header
+```
+
+#### maxAge
+
+A fixed number (seconds) for the response header `access-control-max-age`. Optional.
+
+```yaml
+maxAge: 86400
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/tagomoris/LFA.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/config.ru

@@ -0,0 +1,2 @@
+require 'LFA'
+run LFA.ignition!('config.yaml')

data/config.yaml

@@ -0,0 +1,79 @@
+---
+resources:
+  - path: /api
+    resources:
+      - path: /country
+        methods:
+          GET: myfunc-countries
+      - path: /language
+        methods:
+          GET: myfunc2-list-language
+          PUT: myfunc2-register-language
+      - path: /data
+        resources:
+          - path: /csv
+            methods:
+              GET: myfunc-data-csv
+          - path: /json
+            methods:
+              GET: myfunc-data-json
+      - path: /city
+        resources:
+          - path: /{city_name}
+            methods:
+              GET: myfunc-cities
+      - path: /town
+        resources:
+          - path: /{town_params+}
+            methods:
+              ANY: myfunc-towns
+  - path: /webapi
+    methods:
+      GET: webapi-func-handler
+      POST: webapi-func-handler
+      OPTIONS: cors-1
+
+functions:
+  - name: myfunc-countries
+    handler: myfunc.Countries.process
+    env:
+      KEY1: yay
+      KEY2: foooooo
+  - name: myfunc2-list-language
+    handler: myfunc2.Handler::Language.list
+    env:
+      KEY1: yayyay
+      KEY2: foooooooooo
+  - name: myfunc2-register-language
+    handler: myfunc2.Handler::Language.register
+    env:
+      KEY1: yyyyay
+      KEY2: foo?
+  - name: myfunc-data-csv
+    handler: myfunc.Data.process
+    env:
+      OUTPUT_DATA_TYPE: csv
+  - name: myfunc-data-json
+    handler: myfunc.Data.process
+    env:
+      OUTPUT_DATA_TYPE: json
+  - name: myfunc-cities
+    handler: myfunc.City.process
+  - name: myfunc-towns
+    handler: myfunc.Town.process
+  - name: webapi-func-handler
+    handler: webapi.Func.process
+  - name: cors-1
+    handler: CORS
+    params:
+      mirrorAllowOrigin: true
+      # allowOrigin: '*'
+      allowCredentials: true
+      allowMethods:
+        - GET
+        - POST
+        - OPTIONS
+      allowHeaders:
+        - Content-Type
+        - Authorization
+      maxAge: 3600

data/data.rb

@@ -0,0 +1,27 @@
+require "json"
+
+module Data
+  def self.process(event:, context:)
+    data_type = ENV.fetch("OUTPUT_DATA_TYPE", "txt")
+    case data_type
+    when "json"
+      {
+        statusCode: 200,
+        body: {"data" => "boo", "message" => "foo"}.to_json,
+        headers: {"content-type" => "application/json"},
+      }
+    when "csv"
+      {
+        statusCode: 200,
+        body: "data,yaaaay",
+        headers: {"content-type" => "text/csv"},
+      }
+    else
+      {
+        statusCode: 200,
+        body: "data. yaaaaay!",
+        headers: {"content-type" => "text/plain"},
+      }
+    end
+  end
+end

data/lib/LFA/adapter/environment.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module LFA
+  class Adapter
+    class EnvMimic < Delegator
+      def initialize
+        @is_active = false
+        @box = nil
+        @env = ENV
+      end    
+
+      def __getobj__
+        if @is_active
+          @box
+        else
+          @env
+        end
+      end
+
+      def __setobj__(obj)
+        @box = obj
+      end
+
+      def mimic!(env)
+        @box = env.dup
+        @is_active = true
+        yield
+      ensure
+        @box = nil
+        @is_active = false
+      end
+    end
+  end
+end

data/lib/LFA/adapter/executor.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative '../handler/cors'
+
+module LFA
+  class Adapter
+    class Executor
+      BUILT_IN_HANDLERS = {
+        'CORS' => Handler::CORSPreflight,
+      }
+
+      def self.setup(function)
+        if function.handler.builtin?
+          BUILT_IN_HANDLERS[function.handler.name].new(function.params)
+        else
+          env = Hash[*(function.env.map{|k,v| [k.to_s, v] }.flatten)]
+          Executor.new(function.name, env, function.handler)
+        end
+      end
+
+      def initialize(name, env, handler)
+        @name = name
+        @env = env
+        @klass = handler.klass.to_s
+        # @klass must be a string because `const_get(:"A::B")` is not resolved
+        # https://bugs.ruby-lang.org/issues/12319
+        @method = handler.method.to_sym
+
+        @enclosure = Module.new
+        @enclosure.const_set(:ENV, @env)
+        m1 = Module.new
+        m1.const_set(:ENV, @env)
+        path = handler.path
+        ENV.mimic!(@env) do
+          load(path, @enclosure)
+        end
+        @handler_instance = @enclosure.const_get(@klass)
+        raise "failed to load the handler module '#{@klass}'" unless @handler_instance
+        @handler_method = @handler_instance.method(@method)
+      end
+
+      def call(event:, context:)
+        ENV.mimic!(@env) do
+          @handler_method.call(event: event, context: context)
+        end
+      end
+    end
+  end
+end