phaedra 0.2.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50fe608ca2567e6f1262fcfd1d7a9cc4171a5b467989b115692442dd1ae82e4a
-  data.tar.gz: 3a0da1de124ebd66b6d70ab25a9eee6e9288f28bad0adca7b800e8d82ecd0c31
+  metadata.gz: 47c1b79ae715e83f3dd098fb9d0d29c5d89299f96c01d084f1cb44573f216022
+  data.tar.gz: e716ca8ef384fdeadd773485042099d7bf7840b007e636588ce6fb28e40ab4b3
 SHA512:
-  metadata.gz: 6ef12e516dbbbfdbc487554d6422bfba931933598934a960c71bb4946b31c3d0b9e2e568bd818b1dd3c2bfbda5ebd556af99f8df62284f33d14ff8578b30c1b9
-  data.tar.gz: ae9bd0c2850334dd67b58e18e19a3444b7230539c45fb1b995b7441240930abecb3ff47c6211da5cb2bd2998b4454f3a7a6390fe7f2509d2718e2af13b0932f5
+  metadata.gz: cf41193d15f6bc3678ebccd9239e7185479b3bd4029f593887202ca3e88b02529702688f64f2b373c90e54fed766b264a9f12c2a8a39e4c90039d0d708d9b89a
+  data.tar.gz: 23686c007d52d61763ac393ced71d6485dbf3b3c45cc153828950f6e9c1e8018934834a0dfb90a7908d3357334c3542b34e74629d9774663607f86b21080fb94

data/README.md

@@ -1,10 +1,8 @@
 # Phaedra: Serverless Ruby Functions
 
-_NOTE: not yet released! Check back in June 2020!_
+Phaedra is a web microframework for writing serverless Ruby functions. They are isolated pieces of logic which respond to HTTP requests (GET, POST, etc.) and typically get mounted at a particular URL path. They can be tested locally and deployed to a supported serverless hosting platform or to any [Rack-compatible web server](https://github.com/rack/rack).
 
-Phaedra is a REST microframework for writing serverless Ruby functions. They are isolated pieces of logic which respond to HTTP requests (GET, POST, etc.) and typically get mounted at a particular URL path. They can be tested locally and deployed to a supported serverless hosting platform or to any [Rack-compatible web server](https://github.com/rack/rack).
-
-Serverless compatibility is presently focused on [Vercel](https://vercel.com), but there are likely additional platforms we'll be adding support for in the future (OpenFaaS, Fission, etc.).
+Serverless compatibility is presently focused on [Vercel](https://vercel.com) and [OpenFaaS](https://openfaas.com), but there are likely additional platforms we'll be adding support for in the future.
 
 ## Installation
 
@@ -32,7 +30,7 @@ Functions are single Ruby files which respond to a URL path (aka `/api/path/to/f
 
 Functions are written as subclasses of `Phaedra::Base` using the name `PhaedraFunction`. The `params` argument is a Hash containing the parsed contents of the incoming query string, form data, or body JSON. The response object returned by your function is typically a Hash which will be transformed into JSON output automatically, but it can also be plain text.
 
-Some platforms require the function class name to be `Handler`, so you can put that at the bottom of your file for full compatibility.
+Some platforms such as Vercel require the function class name to be `Handler`, so you can put that at the bottom of your file for full compatibility.
 
 Here's a basic example:
 
@@ -55,7 +53,7 @@ Your function can support `get`, `post`, `put`, `patch`, and `delete` methods wh
 
 Each method is provided access to `request` and `response` objects. If your function was directly instantiated by WEBrick, those will be `WEBrick::HTTPRequest` and `WEBrick::HTTPResponse` respectively. If your function was instantiated by Rack, those will be `Phaedra::Request` (a thin wrapper around `Rack::Request`) and `Rack::Response` respectively.
 
-## Callbacks
+### Callbacks
 
 Functions can define `action` callbacks:
 
@@ -79,9 +77,137 @@ end
 
 You can modify the `request` object in a `before_action` callback to perform setup tasks before the actions are executed, or you can modify `response` in a `after_action` to further process the response.
 
-## Rack
+### Shared Code You Only Want to Run Once
+
+You can use `require_relative` to load and execute shared Ruby code from another folder, say `lib`. This is particularly useful when setting up a database connection or performing expensive operations you only want to do once, rather than for every request.
+
+```ruby
+# api/run-it-once.rb
+
+require "phaedra"
+require_relative "../lib/shared_code"
+
+class PhaedraFunction < Phaedra::Base
+  def get(params)
+    "Run it once! #{SharedCode.run_once} / #{Time.now}"
+  end
+end
+```
+
+```ruby
+# lib/shared_code.rb
+
+module SharedCode
+  def self.run_once
+    @one_time ||= Time.now
+  end
+end
+```
+
+Now each time you invoke the function at `/api/run-it-once`, the first timestamp will never change until the next redeployment.
+
+**NOTE:** When running in a Rack-based configuration (see below), Ruby's `load` method is invoked for every request to any Phaedra function. This means Ruby has to parse and compile the code in your function each time. For small functions this happens extremely quickly, but if you find yourself writing a large function and seeing some performance slowdowns, consider extracting most of the function code to additional Ruby files and use the `require_relative` technique as mentioned above. The Ruby code in those required files will only be compiled once and all classes/modules/etc. will be saved in memory until the next redeployment.
+
+## Deployment
+
+### Vercel
+
+All you have to do is create a static site repo ([Bridgetown](https://www.bridgetownrb.com), Jekyll, Middleman, etc.) with an `api` folder and Vercel will automatically set up the serverless functions every time there's a new branch or production deployment. As mentioned above, you'll need to ensure you add `Handler = PhaedraFunction` to the bottom of each Ruby function.
+
+### OpenFaaS
+
+We recommend using OpenFaaS' dockerfile template so you can define your own `Dockerfile` to book Rack + Phaedra using the Puma web server. This also allows you to customize the Docker image configuration to install and configure other tools as necessary.
+
+First, make sure you've pulled down the template:
+
+```sh
+faas-cli template store pull dockerfile
+```
+
+Then add a `Dockerfile` to your OpenFaaS project's function folder (e.g., `testphaedra`):
+
+```dockerfile
+# testphaedra/Dockerfile
+
+FROM openfaas/of-watchdog:0.7.7 as watchdog
+
+FROM ruby:2.6.6-slim-stretch
+
+COPY --from=watchdog /fwatchdog /usr/bin/fwatchdog
+RUN chmod +x /usr/bin/fwatchdog
+
+ARG ADDITIONAL_PACKAGE
+RUN apt-get update \
+  && apt-get install -qy --no-install-recommends build-essential ${ADDITIONAL_PACKAGE}
+
+WORKDIR /home/app
+
+# Use cache layer for Gemfile
+COPY Gemfile   	.
+RUN bundle install
+RUN gem install puma -N
+
+# Copy over the rest
+COPY    .   .
 
-Booting Phaedra up as Rack app is very simple. All you need is a `config.ru` file alongside your `api` folder:
+# Create a non-root user
+RUN addgroup --system app \
+    && adduser --system --ingroup app app
+RUN chown app:app -R /home/app
+USER app
+
+# Run Puma as the server process
+ENV fprocess="puma -p 5000"
+
+EXPOSE 8080
+
+HEALTHCHECK --interval=2s CMD [ -e /tmp/.lock ] || exit 1
+
+ENV upstream_url="http://127.0.0.1:5000"
+ENV mode="http"
+
+CMD ["fwatchdog"]
+```
+
+Next add the `config.ru` file to boot Rack:
+
+```ruby
+# testphaedra/config.ru
+
+require "phaedra"
+
+run Phaedra::RackApp.new
+```
+
+Finally, add a YAML file that lives alongside your function folder:
+
+```yaml
+# testphaedra.yml
+
+version: 1.0
+provider:
+  name: openfaas
+  gateway: http://127.0.0.1:8080
+functions:
+  testphaedra:
+    lang: dockerfile
+    handler: ./testphaedra
+    image: yourdockerusername/testphaedra:latest
+```
+
+(Replace `yourdockerusername` with your [Docker Hub](https://hub.docker.com) username.)
+
+Now run `faas-cli up -f testphaedra.yml` to build and deploy the function. Given the Ruby function `testphaedra/api/run-me.rb`, you'd call it like so:
+
+```sh
+curl http://127.0.0.1:8080/function/testphaedra/api/run-me
+```
+
+In case you're wondering: yes, with Phaedra you can write multiple Ruby functions which will be accessible via different URL paths—all handled by a single OpenFaaS function. Of course it's possible set up multiple Phaedra projects and deploy them as separate OpenFaaS functions if you wish.
+
+### Rack
+
+Booting Phaedra up as Rack app is very simple. All you need to do is add a `config.ru` file alongside your `api` folder:
 
 ```ruby
 require "phaedra"
@@ -89,9 +215,38 @@ require "phaedra"
 run Phaedra::RackApp.new
 ```
 
-Then run `rackup` in the terminal.
+Then run `rackup` in the terminal, or use another Rack-compatible server like Puma or Passenger.
+
+The settings (and their defaults) you can pass to the `new` method are as follows:
 
-## WEBrick
+```ruby
+{
+  "root_dir" => Dir.pwd,
+  "serverless_api_dir" => "api"
+}
+```
+
+Wondering if you can deploy a static site with an `api` folder via Nginx + Passenger? Yes, you can! Just configure your `my_site.conf` file like so:
+
+```nginxconf
+server {
+    listen 80;
+    server_name www.domain.com;
+
+    # Tell Nginx and Passenger where your site destination folder is
+    root /home/me/my_site/output;
+
+    # Turn on Passenger
+    location /api {
+      passenger_enabled on;
+      passenger_ruby /usr/local/rvm/gems/ruby-2.6.6@mysite/wrappers/ruby;
+    }
+}
+```
+
+Change the `server_name`, `root`, and `passenger_ruby` paths to your particular setup and you'll be good to go. (If you run into any errors, double-check there's a `config.ru` in the parent folder of your site destination folder.)
+
+### WEBrick
 
 Integrating Phaedra into a WEBrick server is pretty straightforward. Given a `server` object, it can be accomplished thusly:
 
@@ -105,13 +260,13 @@ server.mount_proc "/#{base_api_folder}" do |req, res|
   ruby_path = File.join(full_api_path, api_folder, "#{endpoint}.rb")
 
   if File.exist?(ruby_path)
-    original_verbosity = $VERBOSE
-    $VERBOSE = nil
+    if Object.constants.include?(:PhaedraFunction)
+      Object.send(:remove_const, :PhaedraFunction)
+    end
     load ruby_path
-    $VERBOSE = original_verbosity
 
-    handler = Handler.new(server)
-    handler.service(req, res)
+    func = PhaedraFunction.new
+    func.service(req, res)
   else
     raise HTTPStatus::NotFound, "`#{req.path}' not found."
   end
@@ -125,6 +280,8 @@ load File.join(Dir.pwd, "api", "func.rb")
 @server.mount '/path', Handler
 ```
 
+This method precludes any automatic routing by Phaedra, so it's discouraged unless you are using WEBrick within a larger setup that utilizes its own routing method. (Interestingly enough, that's how Vercel works under the hood.)
+
 ----
 
 ## Development

data/example/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gem "phaedra", path: ".."
+gem "puma"

data/example/api/simple.rb

@@ -0,0 +1,10 @@
+require "phaedra"
+
+class PhaedraFunction < Phaedra::Base
+  def get(params)
+    response["Content-Type"] = "text/html; charset=utf-8"
+    "<p>This is Interesting. 😁</p>"
+  end
+end
+
+Handler = PhaedraFunction

data/example/api/the-time.rb

@@ -4,7 +4,6 @@ class PhaedraFunction < Phaedra::Base
   before_action :earlier_stuff
 
   def get(params)
-    response["Content-Type"] = 'text/plain; charset=utf-8'
     "The Current Time is: #{Time.new} and Search Param is #{params[:search]}."
   end
 

data/lib/phaedra/base.rb

@@ -112,7 +112,7 @@ module Phaedra
 
     def set_initial_status
       @res.status = 200
-      @res["Content-Type"] = 'application/json'
+      @res["Content-Type"] = "application/json"
     end
 
     def call_method_action(params)
@@ -121,7 +121,11 @@ module Phaedra
     end
 
     def complete_response
-      @res.body = @res.body.to_json if @res["Content-Type"] == "application/json"
+      if @res.body.is_a?(String) && !@res["Content-Type"].start_with?("text/")
+        @res["Content-Type"] = "text/plain; charset=utf-8"
+      elsif @res["Content-Type"] == "application/json"
+        @res.body = @res.body.to_json
+      end
     end
 
     def error_condition

data/lib/phaedra/middleware.rb

@@ -0,0 +1,2 @@
+require "phaedra/middleware/not_found"
+require "phaedra/middleware/static"

data/lib/phaedra/middleware/not_found.rb

@@ -0,0 +1,21 @@
+module Phaedra
+  module Middleware
+    class NotFound
+      def initialize(app, path, content_type = 'text/html; charset=utf-8')
+        @app = app
+        @content = File.read(path)
+        @length = @content.bytesize.to_s
+        @content_type = content_type
+      end
+
+      def call(env)
+        response = @app.call(env)
+        if response[0] == 404
+          [404, {'Content-Type' => @content_type, 'Content-Length' => @length}, [@content]]
+        else
+          response
+        end
+      end
+    end
+  end
+end

data/lib/phaedra/middleware/static.rb

@@ -0,0 +1,26 @@
+module Phaedra
+  module Middleware
+    # Based on Rack::TryStatic middleware
+    # https://github.com/rack/rack-contrib/blob/master/lib/rack/contrib/try_static.rb
+
+    class Static
+      def initialize(app, options)
+        @app = app
+        @try = ["", ".html", "index.html", "/index.html", *options[:try]]
+        @static = Rack::Static.new(
+          lambda { |_| [404, {}, []] },
+          options)
+      end
+
+      def call(env)
+        orig_path = env['PATH_INFO']
+        found = nil
+        @try.each do |path|
+          resp = @static.call(env.merge!({'PATH_INFO' => orig_path + path}))
+          break if !(403..405).include?(resp[0]) && found = resp
+        end
+        found or @app.call(env.merge!('PATH_INFO' => orig_path))
+      end
+    end
+  end
+end

data/lib/phaedra/rack_app.rb

@@ -11,7 +11,7 @@ module Phaedra
     end
 
     def body
-      @request_body ||= get_header(Rack::RACK_INPUT).read
+      @request_body ||= "" + get_header(Rack::RACK_INPUT).read
     end
   end
 
@@ -33,10 +33,10 @@ module Phaedra
       endpoint = File.basename(req.path)
       ruby_path = File.join(full_api_path, api_folder, "#{endpoint}.rb")
       if File.exist?(ruby_path)
-        original_verbosity = $VERBOSE
-        $VERBOSE = nil
+        if Object.constants.include?(:PhaedraFunction)
+          Object.send(:remove_const, :PhaedraFunction)
+        end
         load ruby_path
-        $VERBOSE = original_verbosity
         
         func = PhaedraFunction.new
         func.service(req, res)

data/lib/phaedra/version.rb

@@ -1,3 +1,3 @@
 module Phaedra
-  VERSION = "0.2.0"
+  VERSION = "0.4.1"
 end

data/phaedra.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Jared White"]
   spec.email         = ["jared@whitefusion.io"]
 
-  spec.summary       = %q{Write serverless Ruby functions via a REST microframework compatible with Rack or WEBrick.}
+  spec.summary       = %q{Write serverless Ruby functions via a REST-like microframework compatible with Rack or WEBrick.}
   spec.description   = spec.summary
   spec.homepage      = "https://github.com/whitefusionhq/phaedra"
   spec.license       = "MIT"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phaedra
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Jared White
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-06 00:00:00.000000000 Z
+date: 2020-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -66,7 +66,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '12.0'
-description: Write serverless Ruby functions via a REST microframework compatible
+description: Write serverless Ruby functions via a REST-like microframework compatible
   with Rack or WEBrick.
 email:
 - jared@whitefusion.io
@@ -80,11 +80,16 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- example/Gemfile
+- example/api/simple.rb
 - example/api/the-time.rb
 - example/config.ru
 - lib/phaedra.rb
 - lib/phaedra/base.rb
 - lib/phaedra/concerns/callbacks_actionable.rb
+- lib/phaedra/middleware.rb
+- lib/phaedra/middleware/not_found.rb
+- lib/phaedra/middleware/static.rb
 - lib/phaedra/rack_app.rb
 - lib/phaedra/version.rb
 - phaedra.gemspec
@@ -107,9 +112,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.8
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
-summary: Write serverless Ruby functions via a REST microframework compatible with
-  Rack or WEBrick.
+summary: Write serverless Ruby functions via a REST-like microframework compatible
+  with Rack or WEBrick.
 test_files: []