hollow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9c801b879198a619db7318ae1e087400770a028c
+  data.tar.gz: fc4610a928d38fb161f944cbb5fec161450b6c16
+SHA512:
+  metadata.gz: a9962e37390da57a4b0e46b773ab572d2c4cdfc1f416f7fc7e391cac7e0f6eaf740c23878664f8fd77558ddb99d0cb0999f4160083abc9c2300f598ca0429a5c
+  data.tar.gz: 50be0715f27254029af1a380a71176a2b06fd521f3c7ebe7c2b77d6d4ff358235301c86efbe5e8ffef250c52f29a95409fabf9ac0cc3f25c61065b378e083eca

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Tom Simmons
+
+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,38 @@
+Hollow is a simple REST server skeleton built atop Sinatra. It provides a dynamic routing configuration and simple a resource scheme for creating API servers that respond to requests of the form `HTTP_METHOD www.site.com/resource/?id`, where `resource` is an API resource capable of responding to requests and `id` is an optional parameter that uniquely identifies resource records.
+
+An application built on Hollow primarily relies on a collection of classes in the `/resources` folder (the location and name of which is arbitrary and configurable), each of which implement a *resource interface* that registers them within the application as being publicly available to service requests. Resources define methods named after HTTP method types, such as :get and :post, which are invoked by the application to respond to corresponding requests. For instance, a request to `GET /MyResource/5` triggers the application to invoke the :get method of the MyResource class. However, Hollow applications will discriminate when doing so, rejecting requests that name non-existent resources or name classes that do not extend the `ResourceInterface` module. If a requested resource is valid, Hollow applications will only invoke the HTTP-named methods of the resource, and then only if they are public, so that you may attach server-private functionality to your resource files. As implementors of the `ResourceInterface` contract, all resource classes come with some basic functionality provided by the module. Until you override the default functionality of a HTTP-named method of a resource, it will respond to requests with the following message:
+
+    { "error": "The resource you requested can not respond to this request (see OPTIONS)" }
+
+Do note that this message encourages your user to send an OPTIONS request to the resource to learn how to use the API, so make sure you override the :options method. Incidentally, it... also generates that message.
+
+To launch your application, run `launch.rb`.
+
+Config.yml
+----------
+This is the configuration file for your server. Hollow allows you to configure which HTTP methods your resources are allowed to respond to by adjusting the items in the development.resource_methods array. If a method is not listed in this array, requests utilizing this method will garner a response prompting the user to send an OPTIONS request. The location of resources and other necessary system files may be added to the development.autorequire.directories array to further configure your system. Note that *any* folder may act as the "resources" folder, or many folders can act in this capacity. Thus, this is your means of deciding where your resources are (which are indicated to the system by extending the `ResourceInterface`, see below). The development environment configuration is the default from which test and production inherit, so changes made here will cascade to the other environments, as well. The provided config.yml has an overriding setup for the test environment, allowing different files to be included in the system for testing purposes.
+
+    # Config.yml snippet showing the default development settings
+    development: &common_settings
+      autorequire:
+        directories: [/resource]
+      resource_methods: [get, post, put, patch, delete, options]
+
+ResourceInterface
+-----------------
+This module is the interface which all resources in your system must implement. It provides no functionality other than defaulting every Resource::HTTP_METHOD call to raise a ResourceMethodInvalidEception, which is caught by Hollow and returned to the user as the informative message we say earlier. Any class which implements ResourceInterface via extending the module is considered a resource by Hollow and will have its public HTTP-named methods made available to service requests. Private and protected methods will not be available, and nor will any methods whose names do not match HTTP request methods (as configured in Config.yml). Any class which does not implement ResourceInterface will not be publicly accessible. Note that it is the act of extending `ResourceInterface` which makes a class a resource, *not* the virtue of being in a particular folder.
+
+Hollow Exceptions
+------------------
+Hollow comes with three custom StdError classes: `ApplicationException`, `ResourceInvalidException`, and `ResourceMethodInvalidException`. The former is raised for generic user-error related issues, such as bad data payloads with invalid or missing parameters. There are meant for you to raise to send informative messages to the user, such as 'Missing ID' or 'A record with id 10 was not found', since Hollow will rescue all such exceptions and package their message in a standardized error payload. ResourceInvalidExceptions and ResourceMethodInvalidExceptions are raised and rescued by Hollow in order to standardize API messages reporting that a requested resource was not found or that it can not service a given request (because your Resource does not override the ResourceInterface for the given HTTP name).
+
+Examples
+--------
+The `test/resource` folder contains two classes, Access and NoAccess. The former is a valid resource in the application and can be accessed via API calls to `GET /Access/id?`, where id may be any value or none at all. The static method Access::get will be invoked and the result parsed by Hollow into JSON, which will respond to the request. NoAccess does NOT implement ResourceInterface, and so even though it is in the resources folder and included in the system, it will not be available under `METHOD /NoAccess/id?' for any METHOD or any id.
+
+Gotchas
+-------
+- Resource names are case-sensitive in the API. A request to `/MyResource/` is different from a request to `/myResource/`.
+- Resources should return data as it should appear within the `data` structure of the response payload. Hollow will standardize the output of your resources so you don't need to do so yourself.
+- Error messages should always be sent to the user via ApplicationException.new, not by returning a string within a resource. Hollow will rescue these exceptions and package their messages into the `error` structure of the response payload.
+- Internal server errors are reported via payloads with `internal_error` keys. The message sent back is entirely banal, but if your UI only listens for `data` and `error` but not `internal_error`, it may miss these responses and silently fail.

data/lib/hollow.rb

@@ -0,0 +1,17 @@
+require_relative "hollow/application"
+require_relative "hollow/exceptions"
+require_relative "hollow/resource"
+require_relative "hollow/version"
+require_relative "hollow/resource/chains"
+require_relative "hollow/resource/stateful"
+require_relative "hollow/resource/stateless"
+
+module Hollow
+  DEFAULT_SETTINGS = {
+    autorequire: {
+      root: "#{File.dirname __FILE__}/../..",
+      directories: []
+    },
+    resource_methods: ["get", "post", "put", "patch", "delete", "options"]
+  }
+end

data/lib/hollow/application.rb

@@ -0,0 +1,63 @@
+require 'require_all'
+
+module Hollow
+
+  class Application
+
+    attr_reader :settings
+
+    def initialize(settings = {})
+      @settings = Hollow::DEFAULT_SETTINGS.merge(settings)
+      @settings[:resource_methods].map! { |m| m.to_sym }
+      @settings[:autorequire][:directories].each do |dir|
+        require_all "#{@settings[:autorequire][:root]}/#{dir}"
+      end
+    end
+
+    def handle_request(resource: nil, method: nil, data: {})
+      begin
+        resource_class = Application::get_resource(resource.to_sym)
+        handler = resource_class.get_instance
+        method = method.to_sym.downcase
+      rescue NoMethodError, NameError
+        fail Hollow::ResourceException,
+            "The resource #{resource} does not exist."
+      end
+
+      if @settings[:resource_methods].include?(method) &&
+          handler.respond_to?(method)
+        invoke_chain(resource_class, data, :before, method)
+        response = handler.public_send(method, data)
+        invoke_chain(resource_class, data, :after, method)
+        return response
+      else
+        fail Hollow::ResourceMethodException,
+            "The %s resource does not respond to %s requests" % [ resource,
+                method ]
+      end
+    end
+
+    private
+    def Application::get_resource(resource)
+      if Module.const_defined?(resource)
+        it = Object.const_get(resource)
+
+        if it.is_a?(Class) &&
+            it.class != Hollow::Resource &&
+            it.is_a?(Hollow::Resource)
+          return it
+        else
+          fail Hollow::ResourceException,
+              "The requested resource (\"#{resource}\") does not exist."
+        end
+      end
+    end
+
+    def invoke_chain(resource, request, chain, method)
+      chains = resource.class_variable_get(:@@chains)
+      links = (chains[chain][:all] || []) + (chains[chain][method] || [])
+      links.each { |chain_link| chain_link.call(request) }
+    end
+  end
+
+end

data/lib/hollow/exceptions.rb

@@ -0,0 +1,7 @@
+module Hollow
+
+  class HollowException < StandardError ; end
+  class ResourceException < HollowException ; end
+  class ResourceMethodException < ResourceException ; end
+
+end

data/lib/hollow/resource.rb

@@ -0,0 +1,14 @@
+module Hollow
+
+  # A mixin that marks a class as a Resource.
+  module Resource
+
+    def self.extended(base)
+      base.class_variable_set(:@@chains, {
+        before: {},
+        after:  {}
+      })
+    end
+
+  end
+end

data/lib/hollow/resource/chains.rb

@@ -0,0 +1,15 @@
+module Hollow
+  module Resource
+
+    module Chains
+      def self.included(base)
+
+        def base.chain(chain, method, behavior)
+          (self.class_variable_get(:@@chains)[chain][method] ||= []) <<
+              behavior
+        end
+      end
+    end
+
+  end
+end

data/lib/hollow/resource/chains/chains.rb

@@ -0,0 +1,15 @@
+module Hollow
+  module Resource
+
+    module Chains
+      def self.included(base)
+
+        def base.chain(chain, method, behavior)
+          (self.class_variable_get(:@@chains)[chain][method] ||= []) <<
+              behavior
+        end
+      end
+    end
+
+  end
+end

data/lib/hollow/resource/resource.rb

@@ -0,0 +1,14 @@
+module Hollow
+
+  # A mixin that marks a class as a Resource.
+  module Resource
+
+    def self.extended(base)
+      base.class_variable_set(:@@chains, {
+        before: {},
+        after:  {}
+      })
+    end
+
+  end
+end

data/lib/hollow/resource/stateful.rb

@@ -0,0 +1,18 @@
+module Hollow
+  module Resource
+
+    # A resource which handles each request with a new instance
+    module Stateful
+      def self.included(base)
+        unless base.is_a?(Hollow::Resource)
+          base.extend(Hollow::Resource)
+        end
+
+        def base.get_instance
+          self.new
+        end
+      end
+    end
+
+  end
+end

data/lib/hollow/resource/stateful/stateful.rb

@@ -0,0 +1,18 @@
+module Hollow
+  module Resource
+
+    # A resource which handles each request with a new instance
+    module Stateful
+      def self.included(base)
+        unless base.is_a?(Hollow::Resource)
+          base.extend(Hollow::Resource)
+        end
+
+        def base.get_instance
+          self.new
+        end
+      end
+    end
+
+  end
+end

data/lib/hollow/resource/stateless.rb

@@ -0,0 +1,19 @@
+module Hollow
+  module Resource
+
+    # A resource that handles all requests with the same instance
+    module Stateless
+      def self.included(base)
+        unless base.is_a?(Hollow::Resource)
+          base.extend(Hollow::Resource)
+        end
+
+        base.class_variable_set(:@@instance, base.new)
+        def base.get_instance
+          self.class_variable_get(:@@instance)
+        end
+      end
+    end
+
+  end
+end

data/lib/hollow/resource/stateless/stateless.rb

@@ -0,0 +1,19 @@
+module Hollow
+  module Resource
+
+    # A resource that handles all requests with the same instance
+    module Stateless
+      def self.included(base)
+        unless base.is_a?(Hollow::Resource)
+          base.extend(Hollow::Resource)
+        end
+
+        base.class_variable_set(:@@instance, base.new)
+        def base.get_instance
+          self.class_variable_get(:@@instance)
+        end
+      end
+    end
+
+  end
+end

data/lib/hollow/version.rb

@@ -0,0 +1,3 @@
+module Hollow
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: hollow
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tom Simmons
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-08-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: require_all
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+description: "\n    Hollow is a drop-in component for building RESTful services that
+  bridges\n    from any routing solution (like Sinatra) to your back-end. You flesh
+  out\n    your service with Resource classes, you pick a Router to forward some\n
+  \   traffic to Hollow, and it works. GET /HelloWorld becomes HelloWorld.get().\n
+  \ "
+email:
+- tomasimmons@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/hollow.rb
+- lib/hollow/application.rb
+- lib/hollow/exceptions.rb
+- lib/hollow/resource.rb
+- lib/hollow/resource/chains.rb
+- lib/hollow/resource/chains/chains.rb
+- lib/hollow/resource/resource.rb
+- lib/hollow/resource/stateful.rb
+- lib/hollow/resource/stateful/stateful.rb
+- lib/hollow/resource/stateless.rb
+- lib/hollow/resource/stateless/stateless.rb
+- lib/hollow/version.rb
+homepage: https://www.github.com/tomboyo/hollow
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+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: []
+rubyforge_project: 
+rubygems_version: 2.6.12
+signing_key: 
+specification_version: 4
+summary: Bridge the gap from routing to Resource.
+test_files: []