hollow 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9c801b879198a619db7318ae1e087400770a028c
-  data.tar.gz: fc4610a928d38fb161f944cbb5fec161450b6c16
+  metadata.gz: 913d652bacfc36cf0de16de872e48834aff704b1
+  data.tar.gz: 779d456eafe4c34533a0435f97ea976b7167bcb7
 SHA512:
-  metadata.gz: a9962e37390da57a4b0e46b773ab572d2c4cdfc1f416f7fc7e391cac7e0f6eaf740c23878664f8fd77558ddb99d0cb0999f4160083abc9c2300f598ca0429a5c
-  data.tar.gz: 50be0715f27254029af1a380a71176a2b06fd521f3c7ebe7c2b77d6d4ff358235301c86efbe5e8ffef250c52f29a95409fabf9ac0cc3f25c61065b378e083eca
+  metadata.gz: 4cedfa66c2db9f2c03e68efa1021c90d7d24f836d65e9b6183b6f866160ccb147b5c0cd67034c4a4c43d06eb0f1b26e939d31d2f14dcf04a7aa56980c9809f55
+  data.tar.gz: 241ef0f0b0446aa28dd21266d9f42b9fd3da6324293c1346bb70da5f6f5ad65a3690b640b28ded8594348afcabcce36bce81584f1e06d6c47f8f569ab28bd97a

data/README.md

@@ -1,38 +1,49 @@
-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.
+# Hollow
+
+> Hollow is a drop-in component for building RESTful services that bridges from any routing solution (like Sinatra) to your back-end. You flesh out your service with Resource classes, you pick a Router to forward some traffic to Hollow, and it works. GET /HelloWorld becomes HelloWorld.get().
+
+With Hollow, any class which includes `Hollow::Resource::Stateless` or `Stateful` is a REST resource capable of servicing certain kinds of requests. Let's say we want to respond to POST requests with a greeting like, "Hello, Tomboyo!":
+
+```ruby
+class HelloWorld
+  include Hollow::Resource::Stateless
+  def post(request)
+    if (request['name'] && !request['name'].empty?)
+      "Hello, #{request['name']}!"
+    else
+      "Hello, whoever you are!"
+    end
+  end
+end
+```
+
+We save that to `./resources/HelloWorld.rb`. Now we want to expose it to the world, so we make a `./server.rb` script. Using Hollow, we first create an `Application` object:
+
+```ruby
+my_app = Hollow::Application.new(
+  autorequire: {
+    root: "#{File.dirname __FILE__}",
+    directories: ['resources']
+  },
+  resource_methods: %i(post)
+)
+```
+The application instance is configured to look for resources in `./resources`, which is where `HelloWorld` is defined. We've also decided that we only want to handle POST requests for now. Finally, we simply pipe HTTP traffic to the application’s `handle_request` method. Using Sinatra:
+
+```ruby
+get '/:resource' do |resource|
+  my_app.handle_request(
+    resource: resource,
+    method:   request.request_method,
+    data:     request.params
+)
+```
+Start the server and `curl 127.0.0.1:4567/HelloWorld -d "name=Tomboyo"` to be given an enthusiastic greeting (that is, send a post request with your name). If we want to create any more functionality, we just create new classes where Hollow can find them. That's it!
+
+# What about other classes and methods?
+
+Only classes, and only classes which include `Hollow::Resource::Stateless` or `Hollow::Resource::Stateful` can service requests. Only resource methods matching the symbols configured via the `resource_methods: %i(post)` parameter during application instantiation can be invoked, as well; other methods are hidden. That means if you only make a `HelloWorld` resource and your application only has `post` configured, your application only invokes `HelloWorld`'s `post`. Nothing else, ever.
+
+# Is this only for REST?
+
+Hollow was designed for REST, but it's not limited in that respect. `Application` can be configured with nonstandard request methods (making resource.myRequestMethodHere a legal request handler), so really `Application` is a mapping from binary identifiers (HelloWorld, post) to methods (HelloWorld post(resource)).

data/lib/hollow.rb

@@ -1,17 +1,11 @@
+require_relative "hollow/hollow_exception"
 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"
 
+# Root namespace for Hollow
 module Hollow
-  DEFAULT_SETTINGS = {
-    autorequire: {
-      root: "#{File.dirname __FILE__}/../..",
-      directories: []
-    },
-    resource_methods: ["get", "post", "put", "patch", "delete", "options"]
-  }
 end

data/lib/hollow/application.rb

@@ -2,26 +2,111 @@ require 'require_all'
 
 module Hollow
 
+  # A RESTful service provider framework which provides dynamic access to REST
+  # resource objects, allowing routers to service reqeusts without any knowledge
+  # of the types that exist in business code.
+  #
+  # - Resource classes compose the service provider aspect of Hollow and
+  # encapsulate all or part of a system's business logic.
+  # - Any class can be registered as a resource by including one of the
+  # Stateless[Resource/Stateless] or Stateful[Resource/Stateful] modules.
+  # - The service provider API is defined dynamically by application instance
+  # configuration (see settings[Application#settings-instance_method]).
+  # Different application instances can use the same underlying resources, but
+  # they will filter access to those resources differently. Requests through one
+  # application instance may succeed while requests through another may raise
+  # access exceptions.
+  # - Application instances provide service access to resources via the
+  # handle_request[#handle_request] method.
   class Application
 
+    # Indicates an illegal resource name.
+    class ResourceException < Hollow::HollowException
+      # The illegal resource name.
+      attr_reader :resource_name
+
+      private
+      def initialize(resource_name)
+        super("The resource #{resource_name} does not exist.")
+        @resource_name = resource_name
+      end
+    end
+
+    # Indicates an illegal resource method name.
+    class ResourceMethodException < Hollow::HollowException
+      # The legal resource name provided for the request.
+      attr_reader :resource_name
+
+      # The illegal method name.
+      attr_reader :method_name
+
+      private
+      def initialize(resource_name, method_name)
+        super("The %s resource does not respond to %s requests" % [
+            resource_name,
+            method_name
+        ])
+
+        @resource_name = resource_name
+        @method_name = method_name
+      end
+    end
+
+    # Default application settings.
+    DEFAULT_SETTINGS = {
+      autorequire: {
+        root: "#{File.dirname __FILE__}/../..",
+        directories: []
+      },
+      resource_methods: ["get", "post", "put", "patch", "delete", "options"]
+    }
+
+    # @return [Hash] the application settings
     attr_reader :settings
 
+    # Create a new application instance.
+    # @param [Hash] settings application settings. See {DEFAULT_SETTINGS} for
+    #   defaults.
+    # @option settings [Array<Symbol>, Array<String>] :resource_methods
+    #   Resource method names which may be invoked on resource instances by
+    #   this application. This effectively defines the service provider API.
+    # @option settings [String] :autorequire[:root]
+    #   location in the file system relative to which other filesystem locations
+    #   are evaluated.
+    # @option settings [Array<String>] :autorequire[:directories]
+    #   file system locations where resource classes may be found; all classes
+    #   in these directories will be required immediately. These locations are
+    #   relative to `:autorequire[:root]`.
     def initialize(settings = {})
-      @settings = Hollow::DEFAULT_SETTINGS.merge(settings)
+      @settings = 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
 
+    # Attempt to invoke a resource method with the given data.
+    #
+    # @param [String, Symbol] resource
+    #   The case-sensitive name of a desired resource.
+    # @param [String, Symbol] method
+    #   The case-sensitive resource method name to invoke.
+    # @param [Hash] data
+    #   Any data which the resource may or may not use to handle the reqeust.
+    # @raise [ResourceException]
+    #   If the indicated resource is not defined, is not a Class, is
+    #   {Hollow::Resource} itself, or is not a type of {Hollow::Resource}.
+    # @raise [ResourceMethodException]
+    #   If the indicated resource exists and:
+    #     1. The indicated method is not accessible or defined, or
+    #     2. The method name is not included in `settings[:resource_methods]`.
     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."
+        fail ResourceException.new resource
       end
 
       if @settings[:resource_methods].include?(method) &&
@@ -31,9 +116,7 @@ module Hollow
         invoke_chain(resource_class, data, :after, method)
         return response
       else
-        fail Hollow::ResourceMethodException,
-            "The %s resource does not respond to %s requests" % [ resource,
-                method ]
+        fail ResourceMethodException.new resource, method
       end
     end
 
@@ -47,8 +130,7 @@ module Hollow
             it.is_a?(Hollow::Resource)
           return it
         else
-          fail Hollow::ResourceException,
-              "The requested resource (\"#{resource}\") does not exist."
+          fail ResourceException.new resource
         end
       end
     end

data/lib/hollow/hollow_exception.rb

@@ -0,0 +1,7 @@
+module Hollow
+
+  # Indicate any Hollow-specific exception which has no dedicated sublass of
+  # HollowException.
+  class HollowException < StandardError ; end
+
+end

data/lib/hollow/resource.rb

@@ -1,8 +1,12 @@
 module Hollow
 
-  # A mixin that marks a class as a Resource.
+  # A mixin that marks a class as a resource. Only instances of Resource can be
+  # accessed by {Hollow::Application#handle_request}. This module should not be
+  # used directly; prefer {Hollow::Resource::Stateless} or
+  # {Hollow::Resource::Stateful} instead.
   module Resource
 
+    private
     def self.extended(base)
       base.class_variable_set(:@@chains, {
         before: {},

data/lib/hollow/resource/chains.rb

@@ -1,13 +1,29 @@
 module Hollow
   module Resource
 
+    # Indicates that a {Hollow::Resource} class uses chains to perform logic
+    # before or after each request.
     module Chains
-      def self.included(base)
 
-        def base.chain(chain, method, behavior)
-          (self.class_variable_get(:@@chains)[chain][method] ||= []) <<
-              behavior
-        end
+      # Register a function to invoke before or after a given resource method
+      # (or any resource method) is invoked.
+      #
+      # Behaviors are invoked in the order in which they are defined within
+      # their respective chains, the exception being that behaviors associated
+      # with `:all` methods are invoked before more specific methods.
+      #
+      # @param [Symbol] chain
+      #   Which chain to register the designated behavior with. Must be one of
+      #   either `:before` or `:after`.
+      # @param [Symbol] method
+      #   Which request method triggers the behavior. If `:all` is provded,
+      #   any request method will invoke the behavior.
+      # @param [Proc, Lambda] behavior
+      #   Behavior which accepts one argument (the data accompanying the
+      #   current request).
+      def chain(chain, method, behavior)
+        (self.class_variable_get(:@@chains)[chain][method] ||= []) <<
+            behavior
       end
     end
 

data/lib/hollow/resource/stateful.rb

@@ -1,8 +1,13 @@
 module Hollow
   module Resource
 
-    # A resource which handles each request with a new instance
+    # Marks a class as a {Hollow::Resource} that may be used by
+    # {Hollow::Application} instances to handle requests. Each time
+    # {Hollow::Application#handle_request} delegates to a Stateful resource, a
+    # new instance of the resource is created to service the request.
+    # @see Hollow::Resource::Stateless
     module Stateful
+      private
       def self.included(base)
         unless base.is_a?(Hollow::Resource)
           base.extend(Hollow::Resource)

data/lib/hollow/resource/stateless.rb

@@ -1,8 +1,13 @@
 module Hollow
   module Resource
 
-    # A resource that handles all requests with the same instance
+    # Marks a class as a {Hollow::Resource} that may be used by
+    # {Hollow::Application} instances to handle requests. Including this module
+    # creates a singleton instance of the class which will service all requests
+    # from all Application instances.
+    # @see Hollow::Resource::Stateful
     module Stateless
+      private
       def self.included(base)
         unless base.is_a?(Hollow::Resource)
           base.extend(Hollow::Resource)

data/lib/hollow/version.rb

@@ -1,3 +1,4 @@
 module Hollow
-  VERSION = "0.1.0"
+  # Hollow version number
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hollow
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Tom Simmons
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-26 00:00:00.000000000 Z
+date: 2017-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: require_all
@@ -80,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: yard
+  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'
 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
@@ -95,21 +109,18 @@ files:
 - README.md
 - lib/hollow.rb
 - lib/hollow/application.rb
-- lib/hollow/exceptions.rb
+- lib/hollow/hollow_exception.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
+  yard.run: yard
 post_install_message: 
 rdoc_options: []
 require_paths:

data/lib/hollow/exceptions.rb

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

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

@@ -1,15 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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/stateful.rb

@@ -1,18 +0,0 @@
-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/stateless.rb

@@ -1,19 +0,0 @@
-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