phaedra 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 50fe608ca2567e6f1262fcfd1d7a9cc4171a5b467989b115692442dd1ae82e4a
+  data.tar.gz: 3a0da1de124ebd66b6d70ab25a9eee6e9288f28bad0adca7b800e8d82ecd0c31
+SHA512:
+  metadata.gz: 6ef12e516dbbbfdbc487554d6422bfba931933598934a960c71bb4946b31c3d0b9e2e568bd818b1dd3c2bfbda5ebd556af99f8df62284f33d14ff8578b30c1b9
+  data.tar.gz: ae9bd0c2850334dd67b58e18e19a3444b7230539c45fb1b995b7441240930abecb3ff47c6211da5cb2bd2998b4454f3a7a6390fe7f2509d2718e2af13b0932f5

data/.gitignore

@@ -0,0 +1,10 @@
+.DS_Store
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+Gemfile.lock

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,77 @@
+# Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at
+[jared@whitefusion.io](mailto:jared@whitefusion.io). All complaints will
+be reviewed and investigated and will result in a response that is deemed
+necessary and appropriate to the circumstances. The project team is obligated
+to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://www.contributor-covenant.org/version/1/4/code-of-conduct.html](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html)
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq)

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in phaedra.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Jared White
+
+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,144 @@
+# Phaedra: Serverless Ruby Functions
+
+_NOTE: not yet released! Check back in June 2020!_
+
+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.).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "phaedra"
+```
+
+And then execute:
+
+```sh
+$ bundle
+```
+
+Or install it yourself as:
+
+```sh
+$ gem install phaedra
+```
+
+## Usage
+
+Functions are single Ruby files which respond to a URL path (aka `/api/path/to/function`). The path is determined by the location of the file on the filesystem relative to the functions root (aka `api`). So, given a path of `./api/folder/run-me.rb`, the URL path would be `/api/folder/run-me`.
+
+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.
+
+Here's a basic example:
+
+```ruby
+require "phaedra"
+
+class PhaedraFunction < Phaedra::Base
+  def get(params)
+    {
+      text: "I am a response!",
+      equals: params[:left].to_i + params[:right].to_i
+    }
+  end
+end
+
+Handler = PhaedraFunction
+```
+
+Your function can support `get`, `post`, `put`, `patch`, and `delete` methods which map to the corresponding HTTP verbs.
+
+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
+
+Functions can define `action` callbacks:
+
+```ruby
+class PhaedraFunction < Phaedra::Base
+  before_action :do_stuff_before
+  after_action :do_stuff_after
+  around_action :do_it_all_around
+
+  def do_stuff_before
+    # code
+  end
+
+  # do_stuff_after, etc.
+
+  def get(params)
+    # this will be run within the callback chain
+  end
+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
+
+Booting Phaedra up as Rack app is very simple. All you need is a `config.ru` file alongside your `api` folder:
+
+```ruby
+require "phaedra"
+
+run Phaedra::RackApp.new
+```
+
+Then run `rackup` in the terminal.
+
+## WEBrick
+
+Integrating Phaedra into a WEBrick server is pretty straightforward. Given a `server` object, it can be accomplished thusly:
+
+```ruby
+full_api_path = File.expand_path("api", Dir.pwd)
+base_api_folder = File.basename(full_api_path)
+
+server.mount_proc "/#{base_api_folder}" do |req, res|
+  api_folder = File.dirname(req.path).sub("/#{base_api_folder}", "")
+  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
+    load ruby_path
+    $VERBOSE = original_verbosity
+
+    handler = Handler.new(server)
+    handler.service(req, res)
+  else
+    raise HTTPStatus::NotFound, "`#{req.path}' not found."
+  end
+end
+```
+
+You also have the option of loading and mounting `Handler` directly to the server:
+
+```ruby
+load File.join(Dir.pwd, "api", "func.rb")
+@server.mount '/path', Handler
+```
+
+----
+
+## Development
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/whitefusionhq/phaedra.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Phaedra project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/whitefusionhq/phaedra/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/example/api/the-time.rb

@@ -0,0 +1,24 @@
+require "phaedra"
+
+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
+
+  def post(params)
+    {message: "POST works!", params: params}
+  end
+  
+  private
+
+  def earlier_stuff
+    request.query["search"] += " SEARCH!" if request.query["search"]
+
+    if request.body
+      request.body.sub!("Works", "Lurks")
+    end
+  end
+end

data/example/config.ru

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

data/lib/phaedra.rb

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

data/lib/phaedra/base.rb

@@ -0,0 +1,133 @@
+require "json"
+require "webrick"
+require "active_support/core_ext/hash/indifferent_access"
+require "phaedra/concerns/callbacks_actionable"
+
+module Phaedra
+  class Base
+    include CallbacksActionable
+
+    # Used by WEBrick
+    def self.get_instance(server, *options)
+      self.new(server, *options)
+    end
+
+    # Context might be a WEBrick server, nil if coming from Rack
+    def initialize(context = nil)
+      @context = context
+    end
+
+    ######################
+    # Override in subclass
+    def get(params)
+      raise WEBrick::HTTPStatus::NotFound, "`#{request.path}' not found."
+    end
+
+    def post(params)
+      raise WEBrick::HTTPStatus::NotFound, "`#{request.path}' not found."
+    end
+
+    def put(params)
+      raise WEBrick::HTTPStatus::NotFound, "`#{request.path}' not found."
+    end
+
+    def patch(params)
+      put(params)
+    end
+
+    def delete(params)
+      raise WEBrick::HTTPStatus::NotFound, "`#{request.path}' not found."
+    end
+    ######################
+
+    def request; @req; end
+    def response; @res; end
+
+    def service(req, res)
+      method_name = "do_" + req.request_method.gsub(/-/, "_")
+      if respond_to?(method_name)
+        __send__(method_name, req, res)
+      else
+        raise WEBrick::HTTPStatus::MethodNotAllowed,
+              "unsupported method `#{req.request_method}'."
+      end
+    end
+
+    def do_GET(req, res)
+      @req = req
+      @res = res
+
+      set_initial_status
+
+      result = run_callbacks :action do
+        # WEBrick's query string handler with DELETE is funky
+        params = if @req.request_method == "DELETE"
+                   WEBrick::HTTPUtils::parse_query(@req.query_string)
+                 else
+                   @req.query
+                 end
+
+        @res.body = call_method_action(params)
+      end
+
+      return error_condition unless result
+      
+      complete_response
+    end
+
+    def do_POST(req, res)
+      @req = req
+      @res = res
+
+      set_initial_status
+
+      result = run_callbacks :action do
+        params = if (@req.header["content-type"] || @req.header["content_type"]).to_s.include?("multipart/form-data")
+          if @req.respond_to?(:params) # Rack
+            @req.params
+          else
+            @req.query # WEBrick
+          end
+        else
+          begin
+            JSON.parse(@req.body)
+          rescue JSON::ParserError, TypeError
+            @req.body
+          end
+        end
+
+        @res.body = call_method_action(params)
+      end
+
+      return error_condition unless result
+
+      complete_response
+    end
+
+    alias_method :do_PUT, :do_POST
+    alias_method :do_PATCH, :do_POST
+    alias_method :do_DELETE, :do_GET
+
+    protected
+
+    def set_initial_status
+      @res.status = 200
+      @res["Content-Type"] = 'application/json'
+    end
+
+    def call_method_action(params)
+      params = params.is_a?(Hash) ? params.with_indifferent_access : params
+      send(@req.request_method.downcase, params)
+    end
+
+    def complete_response
+      @res.body = @res.body.to_json if @res["Content-Type"] == "application/json"
+    end
+
+    def error_condition
+      @res.status = 500
+      @res["Content-Type"] = "text/plain"
+      @res.body = "Internal Server Error (callback chain halted)"
+    end
+  end
+end

data/lib/phaedra/concerns/callbacks_actionable.rb

@@ -0,0 +1,25 @@
+require "active_support/callbacks"
+require "active_support/concern"
+
+module Phaedra
+  module CallbacksActionable
+    extend ActiveSupport::Concern
+    include ActiveSupport::Callbacks
+
+    included do
+      define_callbacks :action
+    end
+
+    module ClassMethods
+      def before_action(*args)
+        set_callback :action, :before, *args
+      end
+      def after_action(*args)
+        set_callback :action, :after, *args
+      end
+      def around_action(*args)
+        set_callback :action, :around, *args
+      end
+    end
+  end
+end

data/lib/phaedra/rack_app.rb

@@ -0,0 +1,57 @@
+module Phaedra
+  class Request < Rack::Request
+    def query
+      self.GET
+    end
+
+    def header
+      @env.dup.transform_keys do |key|
+        key.respond_to?(:downcase) ? key.downcase : key
+      end
+    end
+
+    def body
+      @request_body ||= get_header(Rack::RACK_INPUT).read
+    end
+  end
+
+  class RackApp
+    def initialize(settings = {})
+      @settings = {
+        "root_dir" => Dir.pwd,
+        "serverless_api_dir" => "api"
+      }.merge(settings)
+    end
+
+    def call(env)
+      full_api_path = File.expand_path(@settings["serverless_api_dir"], @settings["root_dir"])
+      base_api_folder = File.basename(full_api_path)
+      req = Request.new(env)
+      res = Rack::Response.new
+
+      api_folder = File.dirname(req.path).sub("/#{base_api_folder}", "")
+      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
+        load ruby_path
+        $VERBOSE = original_verbosity
+        
+        func = PhaedraFunction.new
+        func.service(req, res)
+
+        output = res.finish
+        unless output[2].respond_to?(:each)
+          output[2] = Array(output[2])
+        end
+
+        output
+      else
+        raise WEBrick::HTTPStatus::NotFound, "`#{req.path}' not found."
+      end
+    rescue WEBrick::HTTPStatus::Status => e
+      [e.code, { "Content-Type" => "text/plain" }, [e.reason_phrase]]
+    end
+  end
+end

data/lib/phaedra/version.rb

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

data/phaedra.gemspec

@@ -0,0 +1,26 @@
+require_relative "lib/phaedra/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "phaedra"
+  spec.version       = Phaedra::VERSION
+  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.description   = spec.summary
+  spec.homepage      = "https://github.com/whitefusionhq/phaedra"
+  spec.license       = "MIT"
+
+  # 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('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "activesupport", "~> 6.0"
+  spec.add_runtime_dependency "rack", "~> 2.0"
+  
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake", "~> 12.0"
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: phaedra
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Jared White
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-06-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+description: Write serverless Ruby functions via a REST microframework compatible
+  with Rack or WEBrick.
+email:
+- jared@whitefusion.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- example/api/the-time.rb
+- example/config.ru
+- lib/phaedra.rb
+- lib/phaedra/base.rb
+- lib/phaedra/concerns/callbacks_actionable.rb
+- lib/phaedra/rack_app.rb
+- lib/phaedra/version.rb
+- phaedra.gemspec
+homepage: https://github.com/whitefusionhq/phaedra
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.8
+signing_key: 
+specification_version: 4
+summary: Write serverless Ruby functions via a REST microframework compatible with
+  Rack or WEBrick.
+test_files: []