snapi 0.0.6 → 0.0.7

data/CHANGELOG

@@ -1,3 +1,16 @@
+0.0.7
+-- remove support for Snapi.capability_root
+-- Import deep_merge, and deep_merge! methods for Ruby
+   core Has class
+-- Improve Snapi module API
+-- Improvements to Sinatra Extension
+-- Sinatra Extension helper with repsonse_wrapper method
+-- to_hash method on function now includes and Array of argument
+-- utilize default_value if set for a :string argument
+-- remove useless regexes from validator
+-- Improve spec tests
+-- Improve Documentation in README.md
+
 0.0.6
 -- fix bug around @@capabilities overide in Sinatra Extension
 0.0.5

data/README.md

@@ -2,55 +2,203 @@
 
 Snapi is a modular API functionality definition tool.
 
-## Installation
+[![Gem Version](https://badge.fury.io/rb/snapi.png)](http://badge.fury.io/rb/snapi) [![Code Climate](https://codeclimate.com/github/pwnieexpress/snapi.png)](https://codeclimate.com/github/pwnieexpress/snapi)
 
-This hasn't been put on Rubygems yet so you still have to build the gem
-manually for now. 
+## Usage
 
-```sh
-git clone git@github.com:pwnieexpress/snapi.git
-cd snapi
-gem build snapi.gemspec
-gem install snapi
-```
-This has only been used on `1.9.3` but is should run fine on `1.9+` and `2.x+`
+### Installation
 
-## Usage
+Install by simply typing `gem install snapi`. This has only been tested on
+`1.9.3` but is should run fine on `1.9+` and `2.x+`
+
+### Snapi
+
+The main access point to the functionality that has been defined is through the
+top level `Snapi` module.
+
+#### Functionality Disclosure
 
-Simple Example:
+`Snapi` is intended to provided *functionality disclosure* so that different
+APIs can be defined for different purposes quickly and in a way that self
+documents and organizes the functionality.
+
+
+### Capabilities
+
+Capabilities are core to Snapis API organizational structure. A capability
+represents a collection of functions and can, for many intents and purposes, be
+thought of as a kind of module.
+
+To create a capability start with a Ruby class and include the
+`Snapi::Capability` module.
 
 ```ruby
 require 'snapi'
-require 'json'
-
-class ScannerLibrary
-  def self.scan(args)
-    #                                  
-    #  _| _    _|_|_  _    _|_|_  o __  _ 
-    # (_|(_)    |_| |(/_    |_| | | | |(_|
-    #                                  __|
+
+class SayHello
+  include Snapi::Capability
+  function :hello_world
+
+  # Note, even if this doesn't require any external args it still requires an
+  # arity of 1.
+  def self.hello_world(params)
+    "Hello World"
   end
 end
+```
 
-class Scanner
-  include Snapi::Capability
-  function :scan do |fn|
-    fn.argument :target do |arg|
-      arg.required true
-      arg.list true
-      arg.type :string
-      arg.format :address
-    end
-    fn.argument :port do |arg|
-      arg.type :string
-    end
-    fn.return :structured
+#### Working with Snapi Capabilities
+
+`Snapi` provides a number of helpful ways to view and access and work with
+capabilities.
+
+##### Check for the presence of a capability:
+
+```ruby
+Snapi.has_capability?(:capability)
+#=> true / false
+```
+
+##### Access a specific capability by name:
+
+```ruby
+Snapi[:capability]
+#=> the class in question
+```
+##### See all capabilities
+
+```ruby
+Snapi.capabilities
+#=> Hash of Capability information
+
+Snapi.valid_capabilities
+#=> Array of the names of valid capabilities
+```
+
+### Functions
+
+Functions are declared inside the capability class.  At a minimum the functions
+take a name which maps to a class method defined on the capability class.
+
+The minimal function as declared above looks like:
+
+```ruby
+function :hello_world
+```
+
+:exclamation: *Note:* class methods which serve functions demand having an
+arity of 1. They should expect a hash containing keyed values which map to the
+arguments defined in the `Snapi` function definition.
+
+#### Arguments
+
+Functions are handy but they are much more useful when you begin to declare
+arguments for them. Lets define a more interested method for our capability.
+
+```ruby
+function :hello do |fn|
+  fn.argument :friend do |arg|
+    arg.required true
+    arg.type :string
   end
-  library ScannerLibrary
 end
 ```
 
-## Sinatra Extension
+Now we can create more dynamic method to serve this function.
+
+```ruby
+def self.hello(params)
+  "Hello #{params[:friend]}"
+end
+```
+
+##### Argument Attributes
+
+Arguments can collect a bit of meta information as they are being defined.
+
+###### type
+
+Arguments can come in the following types:
+
+* `:boolean`
+* `:enum`: *not currently implemented*
+* `:string`
+* `:number`
+* `:timestamp`: *not currently implemented*
+
+###### default_value
+
+Provide a default value for non-required `:string` typed arguments.
+
+###### format
+
+Provide an expected validation format for `:string` typed arguments. 
+
+The following formats are currently implemented:
+
+* `:address`: a valid hostname, domain name, IPv4 or IPv6 address
+* `:anything`: Any string. This is the default used. (regex: `/.*/`)
+* `:bool`: A boolean value string containing `'true'` or `'false'`.
+* `:command`: Simple command regex containing alphanumeric, characters and basic punctionation
+* `:hostname`: A hostname
+* `:interface`: Simple interface validation like `<string><number>`
+* `:ip`, `ipv6`, `ipv4`: IP addresses
+* `:mac`: MAC Address
+* `:snapi_function_name`: Valid function name for Snapi
+* `:on_off`: A string containing `on` or `off` 
+* `:port`: A valid network port (1-65535)
+* `:uri`: Simplistic URI validation 
+
+###### list
+
+The `argument.list` attribute takes a boolean value and indicates that the
+argument should come as an array of elements, rather than a single one. 
+
+This is mostly useful as meta-information for the purposes of functionality
+disclosure and does not 
+
+:exclamation: *Note* list arguments are currently *not* validated even if
+defined as such.
+
+###### required
+
+Expecting `true` or `false` the required argument indicates to snapi if the argument MUST be included.
+
+###### values
+
+*Pending...*
+
+###### description
+
+*Pending...*
+
+#### Return Type
+
+A return type can be defined for a function.
+
+```ruby
+fn.return :structured
+```
+
+Valid types:
+
+* `:structured`: Indicates structured output of some type
+* `:raw`: indicates a hash containing shell command run information like `:stdout` or `:exitstatus`
+* `:none`: indicates an unformated string output
+
+### Library Class
+
+The `library` option on a capability can be used to make `Snapi` expect its
+defined functions to be served from another class. 
+
+```ruby
+library ExternalRubyClass
+```
+
+:exclamation: *Note:* This class *must* have valid class methods with an arity
+of 1 for each function declared in the capability defition. 
+
+### Sinatra Extension
 
 A Sinatra application can be extended with this functionality as follows.
 
@@ -58,7 +206,7 @@ A Sinatra application can be extended with this functionality as follows.
 class MyAPi < Sinatra::Base
   register Sinatra::Namespace
 
-  namespace Snapi.capability_root do
+  namespace "/snapi" do
     register Snapi::SinatraExtension
   end
 end
@@ -67,9 +215,84 @@ end
 When loaded this application will offer the following routes:
 
 ```
-# /plugins/
-# /plugins/scanner/
-# /plugins/scanner/scan/
+# /snapi/
+# /snapi/say_hello/
+# /snapi/say_hello/hello_world
+# /snapi/say_hello/hello
+...
+```
+
+#### The API
+
+If we run the [sample app](https://github.com/pwnieexpress/snapi/blob/develop/readme_sample.rb) we can make the following requests as either GET or
+POST:
+
+##### http://localhost:4567/snapi
+
+```
+{
+   "status":200,
+   "data":{
+      "say_hello":{
+         "hello_world":{
+            "return_type":null,
+            "arguments":[
+
+            ]
+         },
+         "hello":{
+            "return_type":null,
+            "arguments":[
+               {
+                  "name":"friend",
+                  "required":false,
+                  "type":"string"
+               }
+            ]
+         }
+      }
+   },
+   "execution_time":2.602e-05
+}
+```
+
+##### http://localhost:4567/snapi/hello_world
+
+```
+{
+   "status":200,
+   "data":{
+      "hello_world":{
+         "return_type":null,
+         "arguments":[
+
+         ]
+      },
+      "hello":{
+         "return_type":null,
+         "arguments":[
+            {
+               "name":"friend",
+               "required":true,
+               "type":"string"
+            }
+         ]
+      }
+   },
+   "execution_time":3.4522e-05
+}
+```
+
+##### http://localhost:4567/snapi/say_hello/hello?friend=Snapi
+
+```
+{
+   "status":200,
+   "data":{
+      "result":"Hello Snapi"
+   },
+   "execution_time":0.000346298
+}
 ```
 
 ## Project Goals & Name
@@ -88,5 +311,6 @@ The ultimate goal being for an API to be able to define itself dynamically and
 dislose that functionality to remote systems and even do things like:
 
 * Dynamic Form Generation
-* API generation (TODO `snapi generate hosts plugin:crud`)
+* CLI Tool / Option Parser
 * Self Documentation
+

data/lib/core_ext/hash.rb

@@ -0,0 +1,30 @@
+# The core Hash class
+# This adds the deep_merge method to this core class which is used to join nested hashes
+class Hash
+
+  # Non destructive version of deep_merge using a dup
+  #
+  # @param [Hash] the hash to be merged with
+  # @returns [Hash] A copy of a new hash merging the hash
+  # this was called on and the param hash
+  def deep_merge(other_hash)
+    dup.deep_merge!(other_hash)
+  end
+
+  # Recusively merges hashes into each other. Any value that is not a Hash will
+  # be overridden with the value in the other hash.
+  #
+  # @param [Hash] the hash to be merged with
+  # @returns [Hash] A copy of itself with the new hash merged in
+  def deep_merge!(other)
+    raise ArgumentError unless other.is_a?(Hash)
+
+    other.each do |k, v|
+      self[k] = (self[k].is_a?(Hash) && self[k].is_a?(Hash)) ? self[k].deep_merge(v) : v
+    end
+
+    self
+  end
+
+end
+

data/lib/snapi.rb

@@ -1,4 +1,6 @@
 # include all the things!
+require "core_ext/hash"
+
 require "snapi/validator"
 require "snapi/errors"
 require "snapi/argument"
@@ -10,7 +12,11 @@ module Snapi
   @@capabilities = {}
 
   def self.capabilities
-    @@capabilities || {}
+    @@capabilities
+  end
+
+  def self.[](key)
+    @@capabilities[key]
   end
 
   def self.register_capability(klass)
@@ -21,11 +27,26 @@ module Snapi
     @@capabilities.keys
   end
 
-  def self.capability_root
-    "/plugins/?"
+  def self.capability_hash
+    valid_capabilities.each_with_object({}) do |cap,coll|
+      coll[cap] = Snapi[cap].to_hash
+    end
+  end
+
+  def self.has_capability?(capability)
+    valid_capabilities.include?(capability)
+  end
+
+  def self.supports?(capability,function,params)
+    if Snapi.has_capability?(capability) &&
+       Snapi[capability].valid_function_call?(function, params)
+      true
+    else
+      false
+    end
   end
 end
 
 # This depends on Snapi module being defined as above
+require "snapi/sinatra_extension_helper"
 require "snapi/sinatra_extension"
-

data/lib/snapi/argument.rb

@@ -50,7 +50,8 @@ module Snapi
     def valid_attributes
       [
         :default_value, :format, :list,
-        :required, :type, :values, :name, :description
+        :required, :type, :values, :name,
+        :description
       ]
     end
 
@@ -79,6 +80,7 @@ module Snapi
     #
     # @param bool, Boolean value
     def list(bool)
+      #TODO work out kinks in list behavior...
       raise InvalidBooleanError unless [true,false].include? bool
       @attributes[:list] = bool
     end
@@ -132,7 +134,6 @@ module Snapi
       when :enum
         raise MissingValuesError unless @attributes[:values]
         raise InvalidValuesError unless @attributes[:values].class == Array
-
         @attributes[:values].include?(input)
       when :string
         format = @attributes[:format] || :anything
@@ -141,7 +142,8 @@ module Snapi
         [Integer, Fixnum].include?(input.class)
       when :timestamp
         # TODO timestamp pending
-        raise PendingBranchError
+        # raise PendingBranchError
+        true
       else
         false
       end

data/lib/snapi/errors.rb

@@ -24,7 +24,6 @@ module Snapi
   LibraryClassMissingFunctionError = Class.new(StandardError)
   MissingValuesError               = Class.new(StandardError)
 
-
   # TODO remove
   PendingBranchError       = Class.new(StandardError)
 end

data/lib/snapi/function.rb

@@ -45,9 +45,9 @@ module Snapi
     #
     # @returns Hash representation of Function
     def to_hash
-      args_hash =  {}
-      arguments.each { |k,v| args_hash[k] = v.attributes } if arguments
-      { return_type: return_type }.merge args_hash
+      args =  []
+      arguments.each { |k,v| args <<  {name: k }.merge(v.attributes) } if arguments
+      { return_type: return_type, arguments: args }
     end
 
     # This method accepts a hash (as from a web request) which it
@@ -61,12 +61,23 @@ module Snapi
     # @returns Boolean
     def valid_args?(args={})
       valid = false
-      arguments.each do |name, argument|
-        if argument[:required]
-          return false if args[name] == nil
+
+      if arguments
+        arguments.each do |name, argument|
+          if argument[:required]
+            return false if args[name] == nil
+          end
+
+          if argument[:default_value] && !args[name]
+            args[name] = argument[:default_value]
+          end
+
+          valid = argument.valid_input?(args[name])
         end
-        valid =  argument.valid_input?(args[name])
+      else
+        valid = true
       end
+
       return valid
     end
   end

data/lib/snapi/sinatra_extension.rb

@@ -3,42 +3,53 @@ require 'sinatra/contrib'
 
 module Snapi
   module SinatraExtension
+
     extend Sinatra::Extension
 
-    get "/?" do
-      capabilities = Snapi.capabilities.dup
-      capabilities.keys.each do |key|
-        capabilities[key] = capabilities[key].to_hash
+    helpers Snapi::SinatraExtensionHelper
+
+    # Hello darkness, my old friend
+    def self.get_or_post(url,&block)
+      get(url,&block)
+      post(url,&block)
+    end
+
+    get_or_post "/?" do
+      response_wrapper do
+        Snapi.capability_hash
       end
-      JSON.generate(capabilities)
     end
 
-    get "/:capability/?" do
+    get_or_post "/:capability/?" do
       @capability = params.delete("capability").to_sym
 
-      unless Snapi.valid_capabilities.include?(@capability)
-        raise InvalidCapabilityError
+      response_wrapper do
+        if Snapi.has_capability?(@capability)
+          Snapi[@capability].to_hash
+        else
+          raise InvalidCapabilityError
+        end
       end
-
-      JSON.generate(Snapi.capabilities[@capability].to_hash)
     end
 
-    get "/:capability/:function/?" do
+    get_or_post "/:capability/:function/?" do
       @capability = params.delete("capability").to_sym
       @function   = params.delete("function").to_sym
 
-      unless Snapi.valid_capabilities.include?(@capability)
-        raise InvalidCapabilityError
-      end
+      response_wrapper do
 
-      unless Snapi.capabilities[@capability].valid_function_call?(@function,params)
-        raise InvalidFunctionCallError
-      end
+        unless Snapi.supports?(@capability, @function, params)
+          raise InvalidFunctionCallError
+        end
+
+        response = Snapi[@capability].run_function(@function,params)
 
-      # TODO add response_wrapper which ensures that the return data from the
-      # function matches the type declared in the capabilities function defitition
-      response = Snapi.capabilities[@capability].run_function(@function,params)
-      response.class == String ? response : JSON.generate(response)
+        unless response.class == Hash
+          response = { raw_result: response }
+        end
+
+        response
+      end
     end
   end
 end

data/lib/snapi/sinatra_extension_helper.rb

@@ -0,0 +1,39 @@
+require 'digest/sha2'
+
+module Snapi
+  module SinatraExtensionHelper
+    # Helper that handles wrapping all API data requests in a standard format
+    # that includes status and error messages (if there were any).
+    #
+    # @param data [Hash] Singular or multiple data objects the client
+    #   requested, should include a JSON schema attribute to allow for response
+    #   validation.
+    # @param response_code [Fixnum] HTTP Status code to return
+    # @param errors [Array<String>] List of errors that occured while processing
+    #   the request.
+    def response_wrapper(data = {}, response_code = 200, errors = [])
+      time_taken = nil
+
+      if block_given?
+        time_start = Time.now
+
+        begin
+          data = data.deep_merge(yield)
+        rescue Exception => e
+          response_code = 500
+          errors << "#{e.class.name}: #{e.backtrace}"
+        end
+
+        time_end = Time.now
+        time_taken = (time_end - time_start)
+      end
+
+      response = { status: response_code, data: data }
+      response[:errors] = errors unless errors.empty?
+      response[:execution_time] = time_taken unless time_taken.nil?
+
+      # Use halt to prevent all further processing
+      halt(response_code, response.to_json)
+    end
+  end
+end

data/lib/snapi/validator.rb

@@ -47,7 +47,6 @@ module Snapi
         :anything            => [/.*/],
         :bool                => [TRUEFALSE_REGEX],
         :command             => [SIMPLE_COMMAND_REGEX],
-        :cron                => [CRON_REGEX],
         :gsm_adapter         => [ADAPTER_REGEX],
         :hostname            => [HOSTNAME_REGEX],
         :interface           => [INTERFACE_REGEX],
@@ -56,12 +55,9 @@ module Snapi
         :ipv4                => [IP_V4_REGEX],
         :mac                 => [MAC_REGEX],
         :snapi_function_name => [SNAPI_FUNCTION_NAME],
-        :string              => [STRING_REGEX],
         :on_off              => [ON_OFF_REGEX],
         :port                => [PORT_REGEX],
         :uri                 => [URI_REGEX],
-        :username            => [HOSTNAME_REGEX],
-        :password            => [NUM_LETTERS_SP_CHARS]
       }
     end
 
@@ -88,9 +84,6 @@ module Snapi
     # Note base on lib/shells/gsm.rb
     ADAPTER_REGEX = /^(unlocked_gsm|verizon_virgin_mobile|tmobile)$/
     #
-    # Note set in lib/shells/scheduler.rb
-    CRON_REGEX = /^(1_minute|5_minutes|15_minutes|60_minutes)$/
-    #
     # Source:
     SIMPLE_COMMAND_REGEX = /^([a-zA-Z0-9\.\s\-\_\/\\\,\=]+)*$/i
     #
@@ -117,9 +110,6 @@ module Snapi
     # SIMPLE ON / OFF (CHECKBOXES)
     ON_OFF_REGEX = /^(on|off)$/i
     #
-    # Source:
-    STRING_REGEX = /^([a-zA-Z0-9\.\-\_]+)*$/i
-    #
     # TRUE OR FALSE
     TRUEFALSE_REGEX = /^(true|false)$/i
     #

data/lib/snapi/version.rb

@@ -1,3 +1,3 @@
 module Snapi
-  VERSION = "0.0.6"
+  VERSION = "0.0.7"
 end

data/spec/argument_spec.rb

@@ -2,7 +2,7 @@ require 'spec_helper'
 
 describe Snapi::Argument do
   it "is a class"  do
-    subject.class.class.should == Class
+    Snapi::Argument.class.should == Class
   end
 
   it "has an attributes hash" do
@@ -46,7 +46,7 @@ describe Snapi::Argument do
     subject.attributes.keys.sort.should == []
   end
 
-  describe "can validated types such as" do
+  describe "can validate types such as" do
     it ":boolean" do
       a = Snapi::Argument.new
       a.type :boolean

data/spec/basic_capability_spec.rb

@@ -17,7 +17,7 @@ describe Snapi::BasicCapability do
           fn.return :raw
         end
       end
-      lemon_grab = {:summon_zombies => { :return_type => :raw}}
+      lemon_grab = {:summon_zombies=>{:return_type=>:raw, :arguments=>[]}}
 
       PrinceLemonGrab.to_hash.should == lemon_grab
     end
@@ -40,17 +40,19 @@ describe Snapi::BasicCapability do
 
       expected_return = {
         :create_candy_person => {
-          :return_type =>:structured,
-          :candy_base  => {
+          :return_type => :structured,
+          :arguments => [{
+            :name          => :candy_base,
             :default_value => "sugar",
-            :format => :anything,
-            :required => true,
-            :list => true,
-            :type => :enum,
-            }
-          }
+            :format        => :anything,
+            :list          => true,
+            :required      => true,
+            :type          => :enum
+        }]
         }
-      PrincessBubblegum.to_hash.should ==  expected_return
+      }
+
+        PrincessBubblegum.to_hash.should ==  expected_return
     end
 
     it "doesn't shared functions between inherited classes" do

data/spec/snapi_spec.rb

@@ -0,0 +1,43 @@
+require 'spec_helper'
+
+describe Snapi do
+  it "is a module" do
+    Snapi.class.should == Module
+  end
+
+  it "can return a hash of registered capabilities" do
+    Snapi.capabilities.class.should == Hash
+    Snapi.capabilities[:basic_capability].should == Snapi::BasicCapability
+  end
+
+  it "provides direct hash style access to its capabilities" do
+    Snapi[:basic_capability].should == Snapi.capabilities[:basic_capability]
+  end
+
+  it "allows other ruby classes to register as capabilities" do
+    TmpClass = Class.new(Snapi::BasicCapability)
+
+    Snapi.capabilities.length.should == 1
+    Snapi.register_capability(TmpClass)
+
+    Snapi.capabilities.length.should == 2
+    Snapi[:tmp_class].should == TmpClass
+  end
+
+  it "provides a list of known capabilities" do
+    Snapi.valid_capabilities.class.should == Array
+    Snapi.valid_capabilities.should == [:basic_capability, :tmp_class]
+  end
+
+  it "provides a hash containing a full functionality disclosure" do
+    hash = Snapi.capability_hash
+    hash.class.should == Hash
+    hash[:tmp_class].should == TmpClass.to_hash
+    hash[:basic_capability].should == Snapi::BasicCapability.to_hash
+  end
+
+  it "can test is a capability is valid" do
+    Snapi.has_capability?(:basic_capability).should == true
+    Snapi.has_capability?(:sexy_ninja).should       == false # :(
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: snapi
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-09 00:00:00.000000000 Z
+date: 2014-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -34,12 +34,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/snapi.rb
+- lib/core_ext/hash.rb
 - lib/snapi/argument.rb
 - lib/snapi/validator.rb
 - lib/snapi/function.rb
 - lib/snapi/version.rb
 - lib/snapi/sinatra_extension.rb
 - lib/snapi/capability.rb
+- lib/snapi/sinatra_extension_helper.rb
 - lib/snapi/errors.rb
 - README.md
 - CHANGELOG
@@ -47,6 +49,7 @@ files:
 - Gemfile.lock
 - Gemfile
 - spec/basic_capability_spec.rb
+- spec/snapi_spec.rb
 - spec/validator_spec.rb
 - spec/spec_helper.rb
 - spec/function_spec.rb