phaedra 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9629e11c78d2a35fa9929d69a79f57fe1711fa4c6f6b4d73e70f8be43019918
-  data.tar.gz: 65a0caf688ea9172723fe398e29861f2c22f99df02dce2d2e34523fbbb4c929b
+  metadata.gz: ed786e8ee4e64448d25817144069d17839cbae1416b6d55daec427f336183101
+  data.tar.gz: 8d436c4e1560ca6acda2a03c5c68a86c6d82909a78cef5c4b0052d132fa9438c
 SHA512:
-  metadata.gz: 8c54e4a03e0cbbd16c4d444215ce29102315e1be92942a9c1d3542eb6eeb948de8b78fff6f5f5913e3ef1ee2c7eae11aaac70545682bcc8f4884987cdb5c28a1
-  data.tar.gz: 666994b4fbb211c6a3bc555ac4f663997d6ed9ae24fcae4d670c76fe6392bb1f3761206000657edaa21e51778a2ebac5dad5a0171cfa45f032d9dbd69939f7d6
+  metadata.gz: 54debc72ff247af26e5414dd4684ac1fe543e4390a7ad96ed8f784ab8f8c32febb4b1b95076afb3aa62c6c72de6d9f7f6cacfaca9b9a39628fe2ba71cbe46de5
+  data.tar.gz: 7b1489588052128fd22902674ad41c3d28fb620ca1bdeefbf5d8131651aaa240478e6ee52d4d1f2f0758c64edb13f71edb02ceece474994eb3d18fdccf546fcf

data/README.md

@@ -53,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:
 
@@ -77,30 +77,109 @@ 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.
 
-## OpenFaaS
+### Shared Code You Only Want to Run Once
 
-We recommend using OpenFaaS' [ruby-http template](https://github.com/openfaas-incubator/ruby-http). It boots up a Sinatra/WEBrick server and then passes all requests along to a Handler object.
-
-In your OpenFaaS project's function folder (e.g., `testphaedra`), simply define a file `handler.rb` which will load Phaedra's default Rack app:
+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
-# testphaedra/handler.rb
+# 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
+```
 
-class Handler
-  def run(_body, env)
-    status, headers, body = Phaedra::RackApp.new({
-      "root_dir" => File.join(Dir.pwd, "function")
-    }).call(env)
+```ruby
+# lib/shared_code.rb
 
-    # The OpenFaaS ruby-http return array is backwards from Rack :/
-    [body.join(""), headers, status]
+module SharedCode
+  def self.run_once
+    @one_time ||= Time.now
   end
 end
 ```
 
-Next, add a YAML file that lives alongside your function folder:
+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    .   .
+
+# 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
@@ -111,24 +190,24 @@ provider:
   gateway: http://127.0.0.1:8080
 functions:
   testphaedra:
-    lang: ruby-http
+    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
-
-# output of the Ruby function
 ```
 
-In case you're wondering: yes, with Phaedra you can write multiple Ruby functions accessible via different URL paths that will all get handled by a single OpenFaaS function. Obviously you're welcome to set up multiple Phaedra projects and deploy them as separate OpenFaaS functions if you wish.
+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
+### Rack
 
-Booting Phaedra up as Rack app is very simple. All you need is a `config.ru` file alongside your `api` folder:
+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"
@@ -136,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:
+
+```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:
 
-## WEBrick
+```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:
 
@@ -172,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

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

data/example/config.ru

@@ -1,3 +1,3 @@
-require "phaedra"
+require "phaedra/rack_app"
 
 run Phaedra::RackApp.new

data/example/phaedra/initializers.rb

@@ -0,0 +1,11 @@
+require "phaedra"
+
+module Phaedra
+  Initializers.register self do
+    the_time("123")
+  end
+
+  def self.the_time(init = nil)
+    @the_time ||= "#{Time.now} + #{init}"
+  end
+end

data/lib/phaedra.rb

@@ -1,7 +1,4 @@
 require "phaedra/version"
-
 require "webrick"
-require "rack"
-
+require "phaedra/initializers"
 require "phaedra/base"
-require "phaedra/rack_app"

data/lib/phaedra/base.rb

@@ -7,6 +7,10 @@ module Phaedra
   class Base
     include CallbacksActionable
 
+    before_action do
+      Initializers.run
+    end
+
     # Used by WEBrick
     def self.get_instance(server, *options)
       self.new(server, *options)
@@ -112,7 +116,7 @@ module Phaedra
 
     def set_initial_status
       @res.status = 200
-      @res["Content-Type"] = "application/json"
+      @res["Content-Type"] = "application/json; charset=utf-8"
     end
 
     def call_method_action(params)
@@ -122,8 +126,8 @@ module Phaedra
 
     def complete_response
       if @res.body.is_a?(String) && !@res["Content-Type"].start_with?("text/")
-        @res["Content-Type"] = "text/plain"
-      elsif @res["Content-Type"] == "application/json"
+        @res["Content-Type"] = "text/plain; charset=utf-8"
+      elsif @res["Content-Type"].start_with? "application/json"
         @res.body = @res.body.to_json
       end
     end

data/lib/phaedra/concerns/callbacks_actionable.rb

@@ -11,14 +11,14 @@ module Phaedra
     end
 
     module ClassMethods
-      def before_action(*args)
-        set_callback :action, :before, *args
+      def before_action(*args, &block)
+        set_callback :action, :before, *args, &block
       end
-      def after_action(*args)
-        set_callback :action, :after, *args
+      def after_action(*args, &block)
+        set_callback :action, :after, *args, &block
       end
-      def around_action(*args)
-        set_callback :action, :around, *args
+      def around_action(*args, &block)
+        set_callback :action, :around, *args, &block
       end
     end
   end

data/lib/phaedra/initializers.rb

@@ -0,0 +1,69 @@
+module Phaedra
+  module Initializers
+    Registration = Struct.new(
+      :origin,
+      :priority,
+      :block,
+      keyword_init: true
+    ) do
+      def to_s
+        "#{owner}:#{priority} for #{block}"
+      end
+    end
+
+    DEFAULT_PRIORITY = 20
+
+    PRIORITY_MAP = {
+      low: 10,
+      normal: 20,
+      high: 30,
+    }.freeze
+
+    # initial empty hooks
+    @registry = []
+
+    NotAvailable = Class.new(RuntimeError)
+    Uncallable = Class.new(RuntimeError)
+
+    # Ensure the priority is a Fixnum
+    def self.priority_value(priority)
+      return priority if priority.is_a?(Integer)
+
+      PRIORITY_MAP[priority] || DEFAULT_PRIORITY
+    end
+
+    def self.register(origin, priority: DEFAULT_PRIORITY, &block)
+      raise Uncallable, "Initializers must respond to :call" unless block.respond_to? :call
+
+      @registry << Registration.new(
+        origin: origin,
+        priority: priority_value(priority),
+        block: block
+      )
+
+      block
+    end
+
+    def self.remove(origin)
+      @registry.delete_if { |item| item.origin == origin }
+    end
+
+    def self.run(force: false)
+      if !@initializers_ran || force
+        prioritized_initializers.each do |initializer|
+          initializer.block.call
+        end
+      end
+
+      @initializers_ran = true
+    end
+
+    def self.prioritized_initializers
+      # sort initializers according to priority and load order
+      grouped_initializers = @registry.group_by(&:priority)
+      grouped_initializers.keys.sort.reverse.map do |priority|
+        grouped_initializers[priority]
+      end.flatten
+    end
+  end
+end

data/lib/phaedra/rack_app.rb

@@ -1,3 +1,6 @@
+require "rack"
+require "phaedra"
+
 module Phaedra
   class Request < Rack::Request
     def query
@@ -11,7 +14,7 @@ module Phaedra
     end
 
     def body
-      @request_body ||= get_header(Rack::RACK_INPUT).read
+      @request_body ||= "" + get_header(Rack::RACK_INPUT).read
     end
   end
 

data/lib/phaedra/rack_middleware.rb

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

data/lib/phaedra/rack_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/rack_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/version.rb

@@ -1,3 +1,3 @@
 module Phaedra
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phaedra
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Jared White
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-07 00:00:00.000000000 Z
+date: 2020-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -80,13 +80,19 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- example/Gemfile
 - example/api/simple.rb
 - example/api/the-time.rb
 - example/config.ru
+- example/phaedra/initializers.rb
 - lib/phaedra.rb
 - lib/phaedra/base.rb
 - lib/phaedra/concerns/callbacks_actionable.rb
+- lib/phaedra/initializers.rb
 - lib/phaedra/rack_app.rb
+- lib/phaedra/rack_middleware.rb
+- lib/phaedra/rack_middleware/not_found.rb
+- lib/phaedra/rack_middleware/static.rb
 - lib/phaedra/version.rb
 - phaedra.gemspec
 homepage: https://github.com/whitefusionhq/phaedra