snapi 0.0.2

data/CHANGELOG

@@ -0,0 +1,6 @@
+0.0.2
+-- Added SinatraExtension 
+0.0.1
+-- Capability Declaration DSL
+-- Funcation Argument Validation
+-- Pass valid function name + args hash to 

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gem 'sinatra'
+gem 'sinatra-contrib'
+
+group :development, :test do
+  gem 'rspec'
+  gem 'pry'
+end
+

data/Gemfile.lock

@@ -0,0 +1,47 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    backports (3.3.4)
+    coderay (1.0.9)
+    diff-lcs (1.2.4)
+    method_source (0.8.2)
+    multi_json (1.8.0)
+    pry (0.9.12.2)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rack (1.5.2)
+    rack-protection (1.5.0)
+      rack
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.5)
+    rspec-expectations (2.14.3)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.3)
+    sinatra (1.4.3)
+      rack (~> 1.4)
+      rack-protection (~> 1.4)
+      tilt (~> 1.3, >= 1.3.4)
+    sinatra-contrib (1.4.1)
+      backports (>= 2.0)
+      multi_json
+      rack-protection
+      rack-test
+      sinatra (~> 1.4.0)
+      tilt (~> 1.3)
+    slop (3.4.6)
+    tilt (1.4.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  pry
+  rspec
+  sinatra
+  sinatra-contrib

data/README.md

@@ -0,0 +1,92 @@
+# Snapi
+
+Snapi is a modular API functionality definition tool.
+
+## Installation
+
+This hasn't been put on Rubygems yet so you still have to build the gem
+manually for now. 
+
+```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+`
+
+## Usage
+
+Simple Exmaple:
+
+```ruby
+require 'snapi'
+require 'json'
+
+class ScannerLibrary
+  def self.scan(args)
+    #                                  
+    #  _| _    _|_|_  _    _|_|_  o __  _ 
+    # (_|(_)    |_| |(/_    |_| | | | |(_|
+    #                                  __|
+  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
+  end
+  library ScannerLibrary
+end
+```
+
+## Sinatra Extension
+
+A Sinatra application can be extended with this functionality as follows.
+
+```ruby
+class MyAPi < Sinatra::Base
+  register Sinatra::Namespace
+
+  namespace Snapi.capability_root do
+    register Snapi::SinatraExtension
+  end
+end
+```
+
+When loaded this application will offer the following routes:
+
+```
+# /plugins/
+# /plugins/scanner/
+# /plugins/scanner/scan/
+```
+
+## Project Goals & Name
+
+I literally woke up in the middle of the night with the idea for a modular
+Sinatra Api plugin system and wrote down the name "Snapi" which is a
+contraction of "Sinatra Api". It might better be spelled "SnApi" but I prefer
+"Snapi" because it snake cases to `snapi`, not `sn_api`. I like the concept of
+snap-in modularity.
+
+As of now the only real behavior is that of declaring functions and arguments
+for a class as a way of doing meta-programming funcationality / arrity
+disclosure.
+
+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`)
+* Self Documentation

data/lib/snapi.rb

@@ -0,0 +1,31 @@
+# include all the things!
+require "snapi/validator"
+require "snapi/errors"
+require "snapi/argument"
+require "snapi/function"
+require "snapi/capability"
+require "snapi/version"
+
+module Snapi
+  @@capabilities = {}
+
+  def self.capabilities
+    @@capabilities || {}
+  end
+
+  def self.register_capability(klass)
+    @@capabilities[klass.namespace] = klass
+  end
+
+  def self.valid_capabilities
+    @@capabilities.keys
+  end
+
+  def self.capability_root
+    "/plugins/?"
+  end
+end
+
+# This depends on Snapi module being defined as above
+require "snapi/sinatra_extension"
+

data/lib/snapi/argument.rb

@@ -0,0 +1,148 @@
+module Snapi
+  # Arguments are an intrinsic part of Capability and Function declaration
+  # in that Capabilities are made up of Functions and Functions may have
+  # one or more Arguments defined for them.
+  #
+  # Arguments are a code representation of a meta-programming way of defining
+  # what arguments or paramater SHOULD or MUST be passed to a method
+  # which represents a function on the Capabilities library class
+  class Argument
+
+    # @attributes tracks the various meta-attributes which can be
+    # set for the argument record.  This initializer simply sets that
+    # value as
+    def initialize
+      @attributes = {}
+    end
+
+    # Allow the record to behave like a hash by giving access to @attributes
+    # via [] getter
+    #
+    # @params key, key to query @attributes with
+    def [](key)
+      @attributes[key]
+    end
+
+    # Allow the record to behave like a hash by giving access to @attributes
+    # via []= setter
+    #
+    # Validates the key requested to set is included in the valid_attributes
+    # white list and then uses the uses the various setter methods below to
+    # set the value.
+    #
+    # @param key, attribute name
+    # @param value, value to set
+    def []=(key, value)
+      raise InvalidArgumentAttributeError unless valid_attributes.include?(key)
+      send(key, value)
+    end
+
+    # Get the @attributes hash
+    #
+    # @returns Hash
+    def attributes
+      @attributes
+    end
+
+    # Whitelist of attribute names
+    #
+    # @returns Array of Symbols
+    def valid_attributes
+      [:default_value, :format, :list, :required, :type, :values]
+    end
+
+    # DSL Setter
+    # Set a default value for the argument if one is not provided
+    #
+    # @param val, Value to use in case one isn't provided,
+    def default_value(val)
+      raise InvalidStringError unless val.class == String
+      @attributes[:default_value] = val
+    end
+
+    # DSL Setter
+    # Set a format the check string types against using the
+    # format_types outlined in Snapi::Validator
+    #
+    # @param format, Symbol of format to match against
+    def format(format)
+      raise InvalidFormatError unless Validator.valid_regex_format?(format)
+      @attributes[:format] = format
+    end
+
+    # DSL Setter
+    # Is the argument a list of options? If true it will be assumed that
+    # this argument will be an array of objects of the sort set as type
+    #
+    # @param bool, Boolean value
+    def list(bool)
+      raise InvalidBooleanError unless [true,false].include? bool
+      @attributes[:list] = bool
+    end
+
+    # DSL Setter
+    # Is the argument a required?
+    #
+    # @param bool, Boolean value
+    def required(bool)
+      raise InvalidBooleanError unless [true,false].include? bool
+      @attributes[:required] = bool
+    end
+
+    # DSL Setter
+    # What type of value is this argument. This will impact the way in which
+    # this argument value gets validated later on
+    #
+    #  Valid types are: :boolean, :enum, :string, :number, :timestamp
+    #
+    # @param type, Symbol indicating type
+    def type(type)
+      valid_types = [:boolean, :enum, :string, :number, :timestamp]
+      raise InvalidTypeError unless valid_types.include?(type)
+      @attributes[:type] = type
+    end
+
+    # DSL Setter
+    # What are the values that can be selected? This only applies to :enum typed arguments
+    # and allow the argument to define a list of valid values to select from for this.
+    #
+    # In a form this would map to a select box. Alternative to using a :string argument
+    # with a format to validate against.
+    #
+    # Basically creates a whitelist of values for this argument.
+    #
+    # @param values, Array
+    def values(values)
+      raise InvalidValuesError unless values.class == Array
+      @attributes[:values] = values
+    end
+
+    # Check if a value provided will suffice for the way
+    # this argument is defined.
+    #
+    # @param input, Just about anything...
+    # @returns Boolean. true if valid
+    def valid_input?(input)
+      case @attributes[:type]
+      when :boolean
+        [true,false].include?(input)
+      when :enum
+        raise MissingValuesError unless @attributes[:values]
+        raise InvalidValuesError unless @attributes[:values].class == Array
+
+        @attributes[:values].include?(input)
+      when :string
+        format = @attributes[:format] || :anything
+        Validator.valid_input?(format, input)
+      when :number
+        [Integer, Fixnum].include?(input.class)
+      when :timestamp
+        # TODO timestamp pending
+        raise PendingBranchError
+      else
+        false
+      end
+    end
+  end
+end
+

data/lib/snapi/capability.rb

@@ -0,0 +1,130 @@
+module Snapi
+  # This class is exists as a way of definining an API capability
+  # using a handy DSL to define functions, their arguments, arity,
+  # validations and return types.
+  module Capability
+
+    # When this module is included into a given Class
+    # this will wbe run. It will extend the clas with
+    # the methods found in the the Snapi::Capability::ClassMethods
+    # module and register the class in question with the Snapi
+    # module.
+    #
+    # @params klass, Class
+    def self.included(klass)
+      klass.extend(ClassMethods)
+      Snapi.register_capability(klass)
+    end
+
+    module ClassMethods
+      # modify the class to track @functions and @library_class
+      # at the class level
+      class << self
+        attr_accessor :functions, :library_class
+      end
+
+      # Getter to query the internally tracked list of supported
+      # functions.
+      #
+      # @returns Hash, @functions or new Hash
+      def functions
+        @functions || {}
+      end
+
+      # Getter to query the class which is responsible for having
+      # methods which map to the names of the functions.
+      #
+      # @returns Class, @library_class || self
+      def library_class
+        @library_class || self
+      end
+
+      # DSL setter to add a function to the @functions hash
+      #
+      # @params name, Name of function being defined
+      # @params Block to modify function
+      # @returns Hash of function data
+      def function(name)
+        raise InvalidFunctionNameError unless Validator.valid_input?(:snapi_function_name, name)
+        fn = Function.new
+        if block_given?
+          yield(fn)
+        end
+        @functions ||= {}
+        @functions[name] = fn
+      end
+
+      # DSL Setter to define the ruby class (or module) which
+      # contains methods that should map to the function names
+      # in the @functions hash
+      #
+      # @params klass, Class which default to self
+      # @returns Class
+      def library(klass=self)
+        @library_class = klass
+      end
+
+
+      # Convert the class name to a snake-cased symbol namespace
+      # representation of class name for use in namespacing
+      #
+      # @returns Symbol, snake_cased
+      def namespace
+        self.name
+        .split('::').last
+        .scan(/([A-Z]+[a-z0-9]+)/)
+        .flatten.map(&:downcase)
+        .join("_")
+        .to_sym
+      end
+
+      # Helper to conver the class itself to a hash representation
+      # including the functions hash keyed off the namespace
+      #
+      # @returns Hash
+      def to_hash
+        fn_hash = {}
+        functions.each {|k,v| fn_hash[k] = v.to_hash } if functions
+        {
+          self.namespace => fn_hash
+        }
+      end
+
+      # Helper to check if a function call to the capability would
+      # be valid with the given arguments
+      #
+      # @param function Symbolic name to reference the function out of the @functions hash
+      # @param args hash of arguments
+      # @returns Boolean
+      def valid_function_call?(function, args)
+        return false unless functions[function]
+        functions[function].valid_args?(args)
+      end
+
+      # Accepts arguments and sends the args to the library class
+      # version of the function assuming that the function has been declared
+      # and the library class also includes that function
+      #
+      # @param function Symbolic name to reference the function out of the @functions hash
+      # @param args hash of arguments
+      # @returns God only knows, my friend, God only know
+      def run_function(function,args)
+        raise InvalidFunctionCallError         unless valid_function_call?(function, args)
+        raise LibraryClassMissingFunctionError unless valid_library_class?
+        library_class.send(function,args)
+      end
+
+      # Test if the set library class is valid based on mapping
+      # the keys of the @functions hash against the methods available
+      # to the @library_class
+      #
+      # @returns Boolean, true if @library_class offers all the methods needed
+      def valid_library_class?
+        self.functions.keys.each do |function_name|
+          return false unless library_class.methods.include?(function_name)
+        end
+        true
+      end
+    end
+  end
+end

data/lib/snapi/errors.rb

@@ -0,0 +1,30 @@
+module Snapi
+  #
+  #
+  #  _________________ ___________ _______
+  #  |  ___| ___ \ ___ \  _  | ___ \___  / |
+  #  | |__ | |_/ / |_/ / | | | |_/ /  / /| |
+  #  |  __||    /|    /| | | |    /  / / | |
+  #  | |___| |\ \| |\ \\ \_/ / |\ \./ /__|_|
+  #  \____/\_| \_\_| \_|\___/\_| \_\_____(_)
+  #
+  #
+  #
+  #
+  InvalidArgumentAttributeError    = Class.new(StandardError)
+  InvalidBooleanError              = Class.new(StandardError)
+  InvalidCapabilityError           = Class.new(StandardError)
+  InvalidFormatError               = Class.new(StandardError)
+  InvalidFunctionCallError         = Class.new(StandardError)
+  InvalidFunctionNameError         = Class.new(StandardError)
+  InvalidReturnTypeError           = Class.new(StandardError)
+  InvalidStringError               = Class.new(StandardError)
+  InvalidTypeError                 = Class.new(StandardError)
+  InvalidValuesError               = Class.new(StandardError)
+  LibraryClassMissingFunctionError = Class.new(StandardError)
+  MissingValuesError               = Class.new(StandardError)
+
+
+  # TODO remove
+  PendingBranchError       = Class.new(StandardError)
+end

data/lib/snapi/function.rb

@@ -0,0 +1,73 @@
+module Snapi
+  # Functions are a core part of capability declaration as a
+  # capability is basically a collection of functions.
+  #
+  # Functions take arguments and return a pre-defined type of
+  # data structure.
+  #
+  # Right now Functions are structs which accept arguments
+  # and return_type messages as well as a few DSL methods
+  # to help define them dynamically
+  #
+  Function = Struct.new(:arguments, :return_type ) do
+
+
+    # DSL setter to define a the meta information for an
+    # argument for the Function
+    #
+    # Yields the argument to a given block for nice defition
+    #
+    # @params name
+    def argument(name)
+      arg = Argument.new
+      if block_given?
+        yield(arg)
+      end
+      self.arguments = {} if self.arguments == nil
+      self.arguments[name] = arg
+    end
+
+    # DSL Setter to define the type of data returned by this function
+    #
+    # TODO currently allows types of 'none', 'raw' or 'structured' but
+    # should support 'structured[stucture_type']
+    #
+    # @params type of returned data
+    def return(type)
+      valid = %w{ none raw structured }.include? type.to_s
+      raise InvalidReturnTypeError unless valid
+
+      self.return_type = type
+    end
+
+    # Hash representation of function including argument meta-data
+    # as a hash.
+    #
+    # @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
+    end
+
+    # This method accepts a hash (as from a web request) which it
+    # uses to compare against its argument definitions in order to
+    # do some upfront validation before trying to run the function
+    # names as defined in the library_class
+    #
+    # TODO: build up an errors hash to disclose what the issue is
+    #
+    # @params args Hash
+    # @returns Boolean
+    def valid_args?(args={})
+      valid = false
+      arguments.each do |name, argument|
+        if argument[:required]
+          return false if args[name] == nil
+        end
+        valid =  argument.valid_input?(args[name])
+      end
+      return valid
+    end
+  end
+end

data/lib/snapi/sinatra_extension.rb

@@ -0,0 +1,42 @@
+require 'json'
+require 'sinatra/contrib'
+
+module Snapi
+  # TODO document, test, make more robust
+  module SinatraExtension
+    extend Sinatra::Extension
+
+    get "/?" do
+      JSON.generate(Snapi.capabilities)
+    end
+
+    get "/:capability/?" do
+      @capability = params.delete("capability").to_sym
+
+      unless Snapi.valid_capabilities.include?(@capability)
+        raise InvalidCapabilityError
+      end
+
+      JSON.generate(Snapi.capabilities[@capability].to_hash)
+    end
+
+    get "/:capability/:function/?" do
+      @capability = params.delete("capability").to_sym
+      @function   = params.delete("function").to_sym
+
+      unless Snapi.valid_capabilities.include?(@capability)
+        raise InvalidCapabilityError
+      end
+
+      unless Snapi.capabilities[@capability].valid_function_call?(@function,params)
+        raise InvalidFunctionCallError
+      end
+
+      # 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)
+    end
+
+  end
+end

data/lib/snapi/validator.rb

@@ -0,0 +1,133 @@
+module Snapi
+
+  # Helpful module to check strings against named Regexp patterns which
+  # are stored in here.
+  module Validator
+
+    # Core method of the module which attempts to check if a provided
+    # string matches any of the regex's as identified by the key
+    #
+    # @params key, Symbol key which maps to one of the keys in the validation_regex method below
+    # @params string, String to check
+    # @returns Boolean, true if string checks out
+    def valid_input?(key,string)
+      raise InvalidFormatError unless valid_regex_format?(key)
+
+      boolarray = validation_regex[key].map do |regxp|
+        (string =~ regxp) == 0 ? true : false
+      end
+
+      return true if boolarray.include?(true)
+      false
+    end
+
+    # A helper to get get the keys off the validation_regex hash
+    #
+    # @returns Array of symbols
+    def format_types
+      validation_regex.keys
+    end
+
+    # A helper to validate that the requested symbols is a valid
+    # type of format we can check against
+    #
+    # @param format, Symbol to check
+    # @returns Boolean, true if the requested format is in format_types array
+    def valid_regex_format?(format)
+      format_types.include?(format)
+    end
+
+    # A helper dictionary which returns and array of valid Regexp patterns
+    # in exchange for a valid key
+    #
+    # @returns Hash, dictionary of symbols and Regexp arrays
+    def validation_regex
+      {
+        :address             => [HOSTNAME_REGEX, DOMAIN_REGEX, IP_V4_REGEX, IP_V6_REGEX],
+        :anything            => [/.*/],
+        :bool                => [TRUEFALSE_REGEX],
+        :command             => [SIMPLE_COMMAND_REGEX],
+        :cron                => [CRON_REGEX],
+        :gsm_adapter         => [ADAPTER_REGEX],
+        :hostname            => [HOSTNAME_REGEX],
+        :interface           => [INTERFACE_REGEX],
+        :ip                  => [IP_V4_REGEX, IP_V6_REGEX],
+        :ipv6                => [IP_V6_REGEX],
+        :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
+
+    module_function :valid_input?, :validation_regex, :format_types, :valid_regex_format?
+
+    ############################################################################
+    #  ______ _____ _   _ _____ _    ______
+    #  | ___ \  ___| | | |  _  | |   |  _  \
+    #  | |_/ / |__ | |_| | | | | |   | | | |
+    #  | ___ \  __||  _  | | | | |   | | | |
+    #  | |_/ / |___| | | \ \_/ / |___| |/ /
+    #  \____/\____/\_| |_/\___/\_____/___( )
+    #                                    |/
+    #
+    #   _____ _   _  _____  ______  ___ _____ _____ ___________ _   _  _____
+    #  |_   _| | | ||  ___| | ___ \/ _ \_   _|_   _|  ___| ___ \ \ | |/  ___|
+    #    | | | |_| || |__   | |_/ / /_\ \| |   | | | |__ | |_/ /  \| |\ `--.
+    #    | | |  _  ||  __|  |  __/|  _  || |   | | |  __||    /| . ` | `--. \
+    #    | | | | | || |___  | |   | | | || |   | | | |___| |\ \| |\  |/\__/ /
+    #    \_/ \_| |_/\____/  \_|   \_| |_/\_/   \_/ \____/\_| \_\_| \_/\____/
+    #
+    #
+    #
+    # 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
+    #
+    # Source: RFC952, RFC1034
+    HOSTNAME_REGEX = /^[a-z0-9-]{1,63}$/i
+    #
+    # Source: RFC952, RFC1034, does not take max length into account
+    DOMAIN_REGEX = /^([a-z0-9-]{1,63}\.)*[a-z0-9-]{1,63}$/i
+    #
+    # validate the name for a function name
+    SNAPI_FUNCTION_NAME = /[a-z0-9_]/
+    #
+    INTERFACE_REGEX = /^([a-z]+)+([0-9]+)+$/i
+    #
+    # IPV4 Source: http://answers.oreilly.com/topic/318-how-to-match-ipv4-addresses-with-regular-expressions/
+    IP_V4_REGEX = /^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/
+    #
+    # IPV6 Source: https://gist.github.com/294476
+    IP_V6_REGEX = /^\s*((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6}(:[0-9A-Fa-f]{1,4}|((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){5}(((:[0-9A-Fa-f]{1,4}){1,2})|:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){4}(((:[0-9A-Fa-f]{1,4}){1,3})|((:[0-9A-Fa-f]{1,4})?:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){3}(((:[0-9A-Fa-f]{1,4}){1,4})|((:[0-9A-Fa-f]{1,4}){0,2}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){2}(((:[0-9A-Fa-f]{1,4}){1,5})|((:[0-9A-Fa-f]{1,4}){0,3}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){1}(((:[0-9A-Fa-f]{1,4}){1,6})|((:[0-9A-Fa-f]{1,4}){0,4}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(:(((:[0-9A-Fa-f]{1,4}){1,7})|((:[0-9A-Fa-f]{1,4}){0,5}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:)))(%.+)?\s*$/
+    #
+    # Mac Source: http://www.ruby-forum.com/topic/139401
+    MAC_REGEX = /^([0-9a-f]{2}[:-]){5}[0-9a-f]{2}$/i
+    #
+    # 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
+    #
+    # mmmmmmmm
+    PORT_REGEX = /^(6[0-5][0-5][0-3][0-5]|6[0-4][0-9]{3}|[1-5][0-9]{4}|[1-9][0-9]{1,3}|[1-9])$/
+    #
+    NUM_LETTERS_SP_CHARS = /^[\w\[\]\!\@\#\$\%\^\&\*\(\)\{\}\:\;\<\>\+\-]*$/i
+    #
+    URI_REGEX = /https?:\/\/[\S]+/
+  end
+end

data/lib/snapi/version.rb

@@ -0,0 +1,3 @@
+module Snapi
+  VERSION = "0.0.2"
+end

data/spec/argument_spec.rb

@@ -0,0 +1,128 @@
+require 'spec_helper'
+
+describe Snapi::Argument do
+  it "is a class"  do
+    subject.class.class.should == Class
+  end
+
+  it "has an attributes hash" do
+    subject.attributes.should == {}
+  end
+
+  it "responds to hash style queries" do
+    subject[:does_not_exist].should == nil
+  end
+
+  it "responds to hash style queries" do
+    subject[:default_value] = "some value"
+    subject[:default_value].should == subject.attributes[:default_value]
+  end
+
+  it "protects from illegal keys being set" do
+    begin
+    subject[:dude_why_would_you_do_this] = "WHO CARES WHAT THIS IS BECAUSE IT WILL NOT GET SET"
+    rescue => error
+      error.class.should == Snapi::InvalidArgumentAttributeError
+    end
+  end
+
+  it "can have default_value set" do
+    subject.default_value("test").should == "test"
+  end
+
+  it "can have required set" do
+    subject.required(true).should == true
+  end
+
+  it "can have list set" do
+    subject.list(true).should == true
+  end
+
+  it "can have type set" do
+    subject.type(:string).should == :string
+  end
+
+  it "can return a hash of its own options" do
+    subject.attributes.keys.sort.should == []
+  end
+
+  describe "can validated types such as" do
+    it ":boolean" do
+      a = Snapi::Argument.new
+      a.type :boolean
+      a.valid_input?(true).should     == true
+      a.valid_input?(false).should    == true
+      a.valid_input?(String).should   == false
+      a.valid_input?("String").should == false
+      a.valid_input?({}).should       == false
+      a.valid_input?([]).should       == false
+    end
+
+    it ":string" do
+      a = Snapi::Argument.new
+      a.type :string
+      a.valid_input?(10.0).should     == false
+      a.valid_input?(100).should      == false
+      a.valid_input?(false).should    == false
+      a.valid_input?([]).should       == false
+      a.valid_input?({}).should       == false
+      a.valid_input?(String).should   == false
+      a.valid_input?("String").should == true
+      a.valid_input?(true).should     == false
+    end
+
+    it ":string with format" do
+      a = Snapi::Argument.new
+      a.type :string
+      a.format :ip
+      a.valid_input?(10.0).should          == false
+      a.valid_input?(100).should           == false
+      a.valid_input?("192.168.1.1").should == true
+      a.valid_input?(false).should         == false
+      a.valid_input?([]).should            == false
+      a.valid_input?({}).should            == false
+      a.valid_input?("String").should      == false
+      a.valid_input?(String).should        == false
+      a.valid_input?(true).should          == false
+    end
+
+    it ":enum with values" do
+      a = Snapi::Argument.new
+      a.type :enum
+      a.values [:a,:b,:c]
+      a.valid_input?(10.0).should     == false
+      a.valid_input?(100).should      == false
+      a.valid_input?(:a).should       == true
+      a.valid_input?(:b).should       == true
+      a.valid_input?(:c).should       == true
+      a.valid_input?(false).should    == false
+      a.valid_input?([]).should       == false
+      a.valid_input?({}).should       == false
+      a.valid_input?("String").should == false
+      a.valid_input?(String).should   == false
+      a.valid_input?(true).should     == false
+    end
+
+    it ":number" do
+      a = Snapi::Argument.new
+      a.type :number
+      a.valid_input?(100000000).should == true
+      a.valid_input?(10.0).should      == false
+      a.valid_input?(100).should       == true
+      a.valid_input?(:a).should        == false
+      a.valid_input?(:b).should        == false
+      a.valid_input?(:c).should        == false
+      a.valid_input?(false).should     == false
+      a.valid_input?([]).should        == false
+      a.valid_input?({}).should        == false
+      a.valid_input?("String").should  == false
+      a.valid_input?(String).should    == false
+      a.valid_input?(true).should      == false
+    end
+
+    it ":timestamp" do
+      pending
+    end
+  end
+end
+

data/spec/basic_capability_spec.rb

@@ -0,0 +1,160 @@
+require "spec_helper"
+
+describe Snapi::BasicCapability do
+  describe "has a namespace which" do
+    it "can convert its class name into a route namespace" do
+      subject.class.namespace.should == :basic_capability
+    end
+
+    it "passes this to inherited BasicCapability objects" do
+      LadyRainicornAndPrinceMonochromocorn = Class.new(subject.class)
+      LadyRainicornAndPrinceMonochromocorn.namespace.should == :lady_rainicorn_and_prince_monochromocorn
+    end
+
+    it "can return a hash representation of itself" do
+      class PrinceLemonGrab < Snapi::BasicCapability
+        function :summon_zombies do |fn|
+          fn.return :raw
+        end
+      end
+      lemon_grab = {:prince_lemon_grab => {:summon_zombies => { :return_type => :raw}}}
+
+      PrinceLemonGrab.to_hash.should == lemon_grab
+    end
+  end
+
+  describe "DSL" do
+    it "can take a function" do
+      class PrincessBubblegum < Snapi::BasicCapability
+        function :create_candy_person do |fn|
+          fn.argument :candy_base do |arg|
+            arg.default_value "sugar"
+            arg.format :anything
+            arg.list true
+            arg.required true
+            arg.type :enum
+          end
+          fn.return :structured
+        end
+      end
+
+      expected_return = {
+        :create_candy_person => {
+          :return_type =>:structured,
+          :candy_base  => {
+            :default_value => "sugar",
+            :format => :anything,
+            :required => true,
+            :list => true,
+            :type => :enum,
+            }
+          }
+        }
+      PrincessBubblegum.to_hash.should == { PrincessBubblegum.namespace => expected_return}
+    end
+
+    it "doesn't shared functions between inherited classes" do
+      class FinnTheHuman < Snapi::BasicCapability
+        function :enchyridion do |fn|
+          fn.return :raw
+        end
+      end
+      class JakeTheDog < Snapi::BasicCapability
+        function :beemo do |fn|
+          fn.return :raw
+        end
+      end
+
+      FinnTheHuman.functions[:enchyridion].should_not == nil
+      FinnTheHuman.functions[:beemo].should           == nil
+
+      JakeTheDog.functions[:enchyridion].should == nil
+      JakeTheDog.functions[:beemo].should_not   == nil
+
+      Snapi::BasicCapability.functions.should == {}
+
+    end
+  end
+
+  describe "tracks a :library class or module which provides methods as defined by the function block" do
+    it "defaults to self" do
+      class TheLich < Snapi::BasicCapability
+      end
+      TheLich.library_class.should == TheLich
+    end
+    it "can be set via self.library " do
+      class BillysLittleFriend
+        def help_somebody
+        end
+      end
+      class BillyTheHero < Snapi::BasicCapability
+        library BillysLittleFriend
+        function :help_somebody
+      end
+      BillyTheHero.library_class.should == BillysLittleFriend
+    end
+    it "can validate if the library has the valid methods" do
+      class BillysLittleFriend
+        def self.help_somebody
+        end
+      end
+      class BillyTheHero < Snapi::BasicCapability
+        library BillysLittleFriend
+        function :help_somebody
+      end
+      class FrankTheVillain < Snapi::BasicCapability
+        library BillysLittleFriend
+        function :hurt_somebody
+      end
+      BillyTheHero.valid_library_class?.should == true
+      FrankTheVillain.valid_library_class?.should == false
+    end
+  end
+
+  describe "can run a function with a hash of arguments" do
+    class IceKing < Snapi::BasicCapability
+      function :ice_attack do |fn|
+        fn.argument :victim do |arg|
+          arg.required true
+          arg.type :string
+        end
+      end
+    end
+
+    it "validates a hash of arguments against a function" do
+      IceKing.valid_function_call?(:icicle, {:victim => "Gunther"}).should == false
+      IceKing.valid_function_call?(:ice_attack, {}).should == false
+      IceKing.valid_function_call?(:ice_attack, {:victim => "Gunther"}).should == true
+    end
+
+    it "raises errors when invalid args or function are sent" do
+      begin
+        IceKing.run_function(:icicle, {:victim => "Gunther"}).should == false
+      rescue => e
+        e.class.should == Snapi::InvalidFunctionCallError
+      end
+    end
+
+    it "raises errors when the library class does not support the requested library " do
+      begin
+        IceKing.run_function(:ice_attack, {:victim => "Gunther"}).should == false
+      rescue => e
+        e.class.should == Snapi::LibraryClassMissingFunctionError
+      end
+    end
+
+    it "runs the function if available in the library class" do
+      class IceWand
+        def self.ice_attack(args={})
+          "ZAP #{args[:victim].upcase}!"
+        end
+      end
+
+      class IceKing
+        library IceWand
+      end
+
+      IceKing.run_function(:ice_attack, {:victim => "Gunther"}).should == "ZAP GUNTHER!"
+    end
+  end
+end

data/spec/function_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper'
+
+describe Snapi::Function do
+  it "can take an argument" do
+    subject.argument :test do |arg|
+      arg.default_value  "test"
+      arg.list  true
+      arg.type  :string
+    end
+
+    subject.argument :test2 do |arg|
+      arg.default_value  "testing more"
+      arg.required  true
+      arg.type  :string
+    end
+
+    subject.arguments[:test][:required].should == nil
+    subject.arguments[:test2][:required].should == true
+
+  end
+
+  it "can validate a ruby hash of keys and values against its arguments" do
+    subject.argument :argument do |arg|
+      arg.default_value  "test"
+      arg.required true
+      arg.type  :string
+    end
+
+    subject.valid_args?({}).should == false
+    subject.valid_args?({:not_argument => "test value"}).should == false
+    subject.valid_args?({:argument => "test value"}).should == true
+    # ignores
+    subject.valid_args?({:argument => "test value", :not => :relevant}).should == true
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'rspec'
+require 'pry'
+
+require File.expand_path('../../lib/snapi.rb', __FILE__)
+
+class Snapi::BasicCapability
+  include Snapi::Capability
+end

data/spec/validator_spec.rb

@@ -0,0 +1,33 @@
+require "spec_helper"
+describe "Snapi::Validator" do
+  it "is a module" do
+    Snapi::Validator.class.should == Module
+  end
+
+  it "includes an array of format types it can validate" do
+    Snapi::Validator.format_types.class.should == Array
+  end
+
+  it "can identify valid format types" do
+    test_format = Snapi::Validator.format_types.shuffle.first
+    Snapi::Validator.valid_regex_format?(test_format).should == true
+  end
+
+  it "can identify invalid format types" do
+    test_format = :no_frakin_way_this_key_exists_seriously_dude
+    Snapi::Validator.valid_regex_format?(test_format).should == false
+  end
+
+  it "offers an array of regular expressions in exchange for a format type" do
+    test_format = Snapi::Validator.format_types.shuffle.first
+    v_reg = Snapi::Validator.validation_regex[test_format]
+    v_reg.class.should == Array
+    v_reg.first.class.should == Regexp
+  end
+
+  it "will attempt to confirm if a string matches the specified regex" do
+    Snapi::Validator.valid_input?( :ip, "192.168.10.129" ).should == true
+    Snapi::Validator.valid_input?( :ip, "192.168.10.256" ).should == false
+    Snapi::Validator.valid_input?( :ip, "Jake the Dog"   ).should == false
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: snapi
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Gabe Koss
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Modular Capability Disclosure DSL
+email: gabe@pwnieexpress.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/snapi.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/errors.rb
+- README.md
+- CHANGELOG
+- Gemfile.lock
+- Gemfile
+- spec/basic_capability_spec.rb
+- spec/validator_spec.rb
+- spec/spec_helper.rb
+- spec/function_spec.rb
+- spec/argument_spec.rb
+homepage: https://github.com/pwnieexpress/snapi
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Snapi
+test_files: []