wabur 0.2.0d1 → 0.4.0d1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 86b81a950a3090451b79d8d4841b4acaa340f208
-  data.tar.gz: 2ac14502f2dabdd7f294be9eeae7c16f068ffadb
+  metadata.gz: f7d968658f0ee232237f5817e4edd4b79484564e
+  data.tar.gz: cb9cf59b684c7fdc5cdc2e3df9b858d1cf351ca9
 SHA512:
-  metadata.gz: 16411e53df75d17339ecdf1efe6b6afc84945c01a71ce2ff2f34a83a3a8e965ba73177286afaf273543711cc5a4646b9742c166699e2f01e80cb813cfa20a32f
-  data.tar.gz: 8f9ca7584c9395e39ccabaab4e0229b0f4e306651adaea727efdf4460dac1ed45e21df33073b54cdd09a3992c4ba35a0f6adf10fe496ce5a82b85cf9c9bf703e
+  metadata.gz: 1730e21a9f21877d3d2f4919423af5bd6c9c23256a163a480ed5474552c61f987a20d3dcf1386a418c5142fc8aaeedb6b5b023ac4aecafd81d346433c5fe69af
+  data.tar.gz: a3ec0dca31b501e31f6faa076db5e070f25492a023d4a37f725ec73329e92c1d663a33d175c19fcd1f1fb6c0c7536166f2262c848e9f6350c4468e2960a8cad4

data/README.md

@@ -16,19 +16,21 @@ performance Ruby web framework.
 Ruby on Rails has made Ruby mainstream. While RoR is fine for some
 applications there are others that might be better served with an alternative.
 This project was started as an alternative to Ruby on Rails with a focus on
-performance and ease of use.
+performance and ease of use. The use of Javascript for views and NoSQL JSON
+databases are some of the most notable differences.
 
-Why develop an alternative to Rails? The popularity of Rails has been waning.
-It is still huge but not as popular as it used to be. RoR is not going away
-any time soon but for some applications, alternatives are needed.
+Why develop an alternative to Rails? Developers that want to make more custom
+web sites with heavier use of Javascript, Websockets, and SSE along with a
+JSON database don't fit nicely in the Rails mold. WAB attempts to address that
+area that falls outside of Rail's strengths.
 
 ## Goals
 
-Lets start with the assumption that we want to continue using Ruby. The goal
-of this project is to provide a high performance, easy to use, and a fully
-featured web framework with Ruby at the core. By keeping the core, the
-business logic, in Ruby but allowing options for other parts to be in different
-languages, the best of each can be utilized.
+Lets start with the primary assumption, that we want to continue using
+Ruby. The goal of this project is to provide a high performance, easy to use,
+and a fully featured web framework with Ruby at the core. By keeping the core,
+the business logic, in Ruby but allowing options for other parts to be in
+different languages, the best of each language can be utilized.
 
 Targets are a throughput of 100K page fetches per second at a latency of no
 more than 1 millisecond on a desktop machine. That is more than an order of
@@ -39,15 +41,39 @@ web frameworks across all languages.
 
 ## Architecture
 
-The architecture provides many options but it keeps clean and clear APIs
-between modules. This pluggable design allows for unit test drivers and
-various levels of deployment options from straight Ruby to a high performance
-C shell that handles HTTP and data storage.
+The architecture provides many options but keeps a clean and clear API between
+modules. This pluggable design allows for unit test drivers and various levels
+of deployment options from straight Ruby to a high performance C runner that
+handles HTTP and data storage.
 
-![](http://www.opo.technology/wab/wab_arch.svg)
+Three configuration are planned. One is to use a Runner that calls to the Ruby
+core controller through pipes on ```$stdin``` and ```$stdout```. A second is to implement
+a runner in Ruby. The third is to use a C Runner with embedded Ruby.
+
+A Runner that spawns (forks) and runs a Ruby Controller makes use of the
+```::WAB::IO::Shell```.
+
+![](http://www.opo.technology/wab/wab_remote_arch.svg)
+
+The Ruby Runner and C Runner with embedded ruby follow the same architecture.
+
+![](http://www.opo.technology/wab/wab_embedded_arch.svg)
+
+Access to data can follow two paths. A direct access to the data is possible
+as portrayed by the red line that flows from HTTP server to the runner and
+onto the Model. The other path is to dive down into the Ruby Controller and
+allow the Controller to modify and control what is returned by a request. The
+Benchmark results in the example/sample/README.md includes the latest results.
+
+![](http://www.opo.technology/wab/wab_access_paths.svg)
 
 [Continue reading ...](pages/Architecture.md)
 
+## Try It!
+
+A sample is now available in the ```examples/sample/``` directory. There are
+some preliminary laptop benchmark results described in the README.
+
 ## Participate and Contribute
 
 If you like the idea and want to help out, or become a core developer on the

data/bin/wabur

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+while (index = ARGV.index('-I'))
+  _, path = ARGV.slice!(index, 2)
+  $: << path
+end
+
+require 'optparse'
+require 'logger'
+
+require 'wab'
+require 'wab/impl'
+
+# The options for this application are determined by the
+# +WAB::Impl::Configuration+ class which takes an +usage+ string and an
+# +options+ hash. The returned object is a +WAB::Impl::Configuration+
+# object that is used by the Shell to configure itself before being started.
+
+# Prepare the +usage+ string.
+# Basically a banner text and description passed on +OptionParser+.
+usage = %{
+Usage: wabur [options]
+
+A pure Ruby WAB Runner.
+Configured directly via command-line options or via a configuration file which
+can either be a UNIX-style conf file, or a JSON file, or a YAML file.
+The configuration typically includes designating Controller classes for each
+URL path to be handled.
+
+}
+
+# Prepare the +options+ hash. Basically a mapping of supported switches and
+# their description that gets parsed by +OptionParser+. It is also used to
+# generate default values.
+options = {
+  base: {
+    val: '.',
+    type: String,
+    doc: 'App root directory which is $BASE.',
+    arg: 'PATH',
+    short: '-b'
+  },
+  store: {
+    dir: {
+      val: '$BASE/data',
+      type: String,
+      doc: "Directory to use for data storage.",
+      arg: 'PATH',
+    }
+  },
+  path_prefix: {
+    val: '/v1',
+    type: String,
+    doc: 'URL path prefix for relative handler routing.',
+    arg: 'PREFIX',
+  },
+  handler: {
+    val: [],
+    doc: 'Type and handler/controller class in the form <type>=<controller class>.',
+    short: '-t',
+    parse: [:type, :handler],
+    arg: 'PAIR',
+  },
+  type_key: {
+    val: 'kind',
+    type: String,
+    doc: 'Shell type_key.',
+    arg: 'KEY',
+  },
+  http: {
+    dir: {
+      val: '$BASE/pages',
+      type: String,
+      doc: 'Directory where HTTP content resides.',
+      arg: 'PATH',
+    },
+    port: {
+      val: 6363,
+      type: Integer,
+      doc: 'HTTP Port to listen on.',
+      arg: 'PORT',
+    },
+  },
+  verbosity: {
+    val: 'WARN',
+    type: String,
+    doc: 'Log level. (ERROR, WARN, INFO, DEBUG)',
+    arg: 'LEVEL',
+  },
+}
+
+config = WAB::Impl::Configuration.new(usage, options)
+
+# The Configuration object can be modified before initializing the Shell. By
+# setting the +config[:logger]+ the Shell will use that as the logger. The
+# +config[:handler]+ array can also be modified by setting path values along
+# with a Controller instance, a Controller class, or the name of a Controller
+# class.
+config[:logger] = Logger.new(STDOUT)
+
+# Start a shell initialized with the final configuration.
+WAB::Impl::Shell.new(config).start

data/lib/wab/controller.rb

@@ -2,17 +2,22 @@ module WAB
 
   # A Controller class or a duck-typed alternative should be created and
   # registered with a Shell for any type that implements behavior other than
-  # the default REST API processing. If a public method is not found on the
-  # class instance then the default REST API processing will be used.
+  # the default REST API processing.
+  #
+  # When a request arrives at the Shell, the expected Controller method is
+  # identifed and a check is made to verify if the Controller responds to the
+  # method. If it does not, then the +handle+ method is called.  Since
+  # +respond_to+ includes only public methods, only those methods made public
+  # in a Controller subclass are considered. The candidates for making public
+  # are +create+, +read+, +update+, and +delete+.
   #
   # A description of the available methods is included as private methods.
   class Controller # :doc: all
     attr_accessor :shell
 
     # Create a instance.
-    def initialize(shell, async=false)
+    def initialize(shell)
       @shell = shell
-      # TBD handle async
     end
 
     # Handler for paths that do not match the REST pattern or for unregistered
@@ -22,7 +27,7 @@ module WAB
     # on to the requester. The result, if not nil, should be a Data instance.
     #
     # data:: data to be processed
-    def handle(data)
+    def handle(_data)
       nil
     end
 
@@ -34,8 +39,6 @@ module WAB
     # Create a new data object. If a query is provided it is treated as a
     # check against an existing object with the same key/value pairs.
     #
-    # The reference to the object created is returned on success.
-    #
     # On error an Exception should be raised.
     #
     # path:: array of tokens in the path.
@@ -44,50 +47,46 @@ module WAB
     def create(path, query, data) # :doc:
       tql = { }
       kind = path[@shell.path_pos]
-      if query.is_a?(Hash) && 0 < query.size
-        where = ['AND']
-        where << form_where_eq(@shell.type_key, kind)
-        query.each_pair { |k,v| where << form_where_eq(k, v) }
-        tql[:where] = where
+      if WAB::Utils.populated_hash?(query)
+        tql[:where] = and_where(kind, query)
       end
       tql[:insert] = data.native
       shell_query(tql, kind, 'create')
     end
 
-    # Return the objects according to the path and query arguments.
-    #
-    # If the path includes an object reference then that object is returned as
-    # the only member of the results list of a WAB::Data returned.
+    # Return the objects according to the path and query arguments. The
+    # following patterns supported:
     #
-    # If there is no object reference in the path then the attributes are used
-    # to find matching objects. The objects that have the same key/value pairs
-    # are returned.
+    # * [MyType/12345] looks for MyType with reference ID of 12345
+    # * [MyType?name=fred&age=63] looks for all MyTypes with a name of 'fred'
+    #                             and an age of 63.
+    # * [MyType/list?Name=name&Age=age] returns only the name and age
+    #                                   attributes and places them in a Hash
+    #                                   with the keys :Name and :Age along
+    #                                   with the record reference as :ref.
     #
     # path:: array of tokens in the path.
-    # query:: query parameters from a URL as a Hash with keys matching paths
-    #         into the target objects and value equal to the target attribute
-    #         values. A path can be an array of keys used to walk a path to
-    #         the target or a +.+ delimited set of keys.
+    # query:: query parameters from a URL as a Hash with key and value
+    #         pairs. Note that duplicate keys will result in only the last
+    #         option being present,
     def read(path, query) # :doc:
-      if @shell.path_pos + 2 == path.length # has an object reference in the path
-        ref = path[@shell.path_pos + 1].to_i
-        obj = @shell.get(ref)
-        obj = obj.native if obj.is_a?(::WAB::Data)
-        return @shell.data({ code: 0, results: [ { id: ref, data: obj } ]})
-      end
-      tql = { }
       kind = path[@shell.path_pos]
-      # No id so must be either a simple query by attribute or a list.
-      if query.is_a?(Hash) && 0 < query.size
-        where = ['AND']
-        where << form_where_eq(@shell.type_key, kind)
-        query.each_pair { |k,v| where << form_where_eq(k, v) }
+      # Check for the type and object reference pattern as well as the list
+      # pattern.
+      if @shell.path_pos + 2 == path.length
+        ref = path[@shell.path_pos + 1]
+        return list_select(kind, query) if 'list' == ref
+
+        # Read a single object/record.
+        ref = ref.to_i
+        obj = @shell.get(ref)
+        obj = obj.native if obj.is_a?(WAB::Data)
+        results = []
+        results << {id: ref, data: obj} unless obj.nil?
+        @shell.data({ code: 0, results: results})
       else
-        where = form_where_eq(@shell.type_key, kind)
+        list_match(kind, query)
       end
-      tql[:where] = where
-      tql[:select] = { id: '$ref', data: '$' }
-      shell_query(tql, kind, 'read')
     end
 
     # Replaces the object data for the identified object.
@@ -104,13 +103,10 @@ module WAB
       kind = path[@shell.path_pos]
       if @shell.path_pos + 2 == path.length # has an object reference in the path
         tql[:where] = path[@shell.path_pos + 1].to_i
-      elsif query.is_a?(Hash) && 0 < query.size
-        where = ['AND']
-        where << form_where_eq(@shell.type_key, kind)
-        query.each_pair { |k,v| where << form_where_eq(k, v) }
-        tql[:where] = where
+      elsif WAB::Utils.populated_hash?(query)
+        tql[:where] = and_where(kind, query)
       else
-        raise ::WAB::Error.new("update on all #{kind} not allowed.")
+        raise WAB::Error.new("update on all #{kind} not allowed.")
       end
       tql[:update] = data.native
       shell_query(tql, kind, 'update')
@@ -133,16 +129,13 @@ module WAB
     def delete(path, query) # :doc:
       tql = { }
       kind = path[@shell.path_pos]
-      if @shell.path_pos + 2 == path.length # has an object reference in the path
-        tql[:where] = path[@shell.path_pos + 1].to_i
-      elsif query.is_a?(Hash) && 0 < query.size
-        where = ['AND']
-        where << form_where_eq(@shell.type_key, kind)
-        query.each_pair { |k,v| where << form_where_eq(k, v) }
-        tql[:where] = where
-      else
-        tql[:where] = form_where_eq(@shell.type_key, kind)
-      end
+      tql[:where] = if @shell.path_pos + 2 == path.length # has an object reference in the path
+                      path[@shell.path_pos + 1].to_i
+                    elsif WAB::Utils.populated_hash?(query)
+                      and_where(kind, query)
+                    else
+                      form_where_eq(@shell.type_key, kind)
+                    end
       tql[:delete] = nil
       shell_query(tql, kind, 'delete')
     end
@@ -167,6 +160,33 @@ module WAB
       @shell.changed(data)
     end
 
+    # A private method to gather sets of Hashes that include the fields
+    # specified in the fields Hash.
+    def list_select(kind, fields)
+      tql = {}
+      select = { ref: '$ref' }
+      if WAB::Utils.populated_hash?(fields)
+        fields.each_pair { |k,v| select[k] = v }
+      end
+      tql[:where] = form_where_eq(@shell.type_key, kind)
+      tql[:select] = select
+      shell_query(tql, kind, 'read')
+    end
+
+    # A private method to gather a list of objects that match the query
+    # parameters.
+    def list_match(kind, query)
+      tql = {}
+      # If there is a query set up a where clause.
+      tql[:where] = if WAB::Utils.populated_hash?(query)
+                      and_where(kind, query)
+                    else
+                      form_where_eq(@shell.type_key, kind)
+                    end
+      tql[:select] = { id: '$ref', data: '$' }
+      shell_query(tql, kind, 'read')
+    end
+
     # Form a EQ expression for a TQL where clause. Used as a helper to the
     # primary API calls.
     #
@@ -175,48 +195,71 @@ module WAB
     def form_where_eq(key, value)
       value_class = value.class
       x = ['EQ', key.to_s]
-      if value.is_a?(String)
-        x << "'" + value
-      elsif Time == value_class
-        x << value.utc.iso8601(9)
-      elsif value.nil? ||
-          TrueClass == value_class ||
-          FalseClass == value_class ||
-          Integer == value_class ||
-          Float == value_class
-        x << value
-      elsif String == value_class
-        if 0 < value.length && '\'' == value[0] 
-          x << value[1..-1]
-        elsif /^-?\d+$/.match?(value)
-          x << value.to_i
-        elsif /^-?\d*\.?\d+([eE][-+]?\d+)?$/.match?(value)
-          x << value.to_f
-        end
-        # TBD detect other types UUID, HTTP, Time
-        
-      elsif '2' == RbConfig::CONFIG['MAJOR'] && '4' > RbConfig::CONFIG['MINOR'] && Fixnum == value_class
-        x << value
-      else
-        x << value.to_s
-      end
+      x << if Time == value_class
+             value.utc.iso8601(9)
+           elsif value.nil? ||
+               TrueClass == value_class ||
+               FalseClass == value_class ||
+               Integer == value_class ||
+               Float == value_class
+             value
+           elsif String == value_class
+             # if the string matches a detectable type then don't quote it
+             detect_string(value)
+           elsif WAB::Utils.pre_24_fixnum?(value)
+             value
+           else
+             value.to_s
+           end
       x
     end
 
-    # Helper to send TQL requests to the shell either synchronously or
-    # asynchronously depending on the controller type.
-    def shell_query(tql, kind, op)
+    # Form an AND expression for a TQL where clause.
+    def and_where(kind, query)
+      where = ['AND']
+      where << form_where_eq(@shell.type_key, kind)
+      query.each_pair { |k,v| where << form_where_eq(k, v) }
+      where
+    end
 
-      # TBD check for async or not
+    # Detects strings that are representation of something else such as an
+    # integer, UUID, Time, or URI. Used to convert URL query parameters to TQL
+    # types. That also means string are quoted for TQL with a single leading
+    # single quote character unless one is already present. No trailing single
+    # quote is added.
+    def detect_string(value)
+      # if the string matches a detectable type then don't quote it
+      # ok as is
+      return value if !value.empty? && value.start_with?("'")
 
-      result = @shell.query(tql, nil) # synchronous call
-      if result.nil? || 0 != result[:code]
-        if result.nil?
-          raise ::WAB::Error.new("nil result on #{kind} #{op}.")
-        else
-          raise ::WAB::Error.new("error on #{kind} #{op}. #{result[:error]}")
+      if !/^-?\d+$/.match(value).nil?
+        value.to_i
+      elsif !/^-?\d*\.?\d+([eE][-+]?\d+)?$/.match(value).nil?
+        value.to_f
+      elsif WAB::Utils.uuid_format?(value)
+        WAB::UUID.new(value)
+      elsif WAB::Utils.wab_time_format?(value)
+        begin
+          DateTime.parse(value).to_time
+        rescue
+          "'" + value
+        end
+      elsif value.downcase.start_with?('http://')
+        begin
+          URI(value)
+        rescue
+          "'" + value
         end
+      else
+        "'" + value
       end
+    end
+
+    # Helper to send TQL requests to the shell.
+    def shell_query(tql, kind, op)
+      result = @shell.query(tql)
+      raise WAB::Error.new("nil result on #{kind} #{op}.") if result.nil?
+      raise WAB::Error.new("error on #{kind} #{op}. #{result[:error]}") if 0 != result[:code]
       result
     end
 

data/lib/wab/data.rb

@@ -9,14 +9,22 @@ module WAB
   # class (has the same methods and behavior).
   class Data
 
+    # Returns true if the Data element or value identified by the path
+    # exists where the path elements are separated by the '.' character. The
+    # path can also be a array of path node identifiers. For example,
+    # child.grandchild is the same as ['child', 'grandchild'].
+    def has?(_path)
+      raise NotImplementedError.new
+    end
+
     # Gets the Data element or value identified by the path where the path
     # elements are separated by the '.' character. The path can also be a
     # array of path node identifiers. For example, child.grandchild is the
     # same as ['child', 'grandchild'].
-    def get(path)
+    def get(_path)
       raise NotImplementedError.new
     end
-    
+
     # Sets the node value identified by the path where the path elements are
     # separated by the '.' character. The path can also be a array of path
     # node identifiers. For example, child.grandchild is the same as ['child',
@@ -30,7 +38,7 @@ module WAB
     # path:: path to location to be set
     # value:: value to set
     # repair:: flag indicating invalid value should be repaired if possible
-    def set(path, value)
+    def set(_path, _value)
       raise NotImplementedError.new
     end
 
@@ -49,7 +57,7 @@ module WAB
     end
 
     # Make a deep copy of the Data instance.
-    def clone()
+    def deep_dup()
       raise NotImplementedError.new
     end
 
@@ -59,29 +67,8 @@ module WAB
       raise NotImplementedError.new
     end
 
-    # Returns true if self and other are either the same or have the same
-    # contents. This is a deep comparison.
-    def eql?(other)
-      raise NotImplementedError.new
-    end
-
-    # Returns the length of the root element.
-    def length()
-      raise NotImplementedError.new
-    end
-
-    # Returns the number of leaves in the data tree.
-    def leaf_count()
-      raise NotImplementedError.new
-    end
-
-    # Returns the number of nodes in the data tree.
-    def size()
-      raise NotImplementedError.new
-    end
-
     # Encode the data as a JSON string.
-    def json(indent=0)
+    def json(_indent=0)
       raise NotImplementedError.new
     end
 
@@ -102,7 +89,7 @@ module WAB
     # of the Hash or Array must be nil, boolean, String, Integer, Float,
     # BigDecimal, Array, Hash, Time, URI::HTTP, or WAB::UUID. Keys to Hashes
     # must be Symbols.
-    def initialize(value=nil, repair=false)
+    def initialize(_value=nil, _repair=false)
       raise NotImplementedError.new
     end
 

data/lib/wab/errors.rb

@@ -1,13 +1,19 @@
 
 module WAB
 
-  # Base for WAB errors and exceptions.
-  class Error < StandardError
-  end # Error
+  Error      = Class.new(StandardError) # Base for WAB errors and exceptions.
+  ParseError = Class.new(Error)         # Raised as a result of a error while parsing.
 
-  # An Exception that is raised as a result of a parse error while parsing a
-  # JSON document.
-  class ParseError < Error
-  end # ParseError
+  class TypeError < Error
+    def initialize(msg='Data values must either be a Hash or an Array')
+      super(msg)
+    end
+  end
 
-end # Oj
+  class KeyError < Error
+    def initialize(msg='Hash keys must be Symbols')
+      super(msg)
+    end
+  end
+
+end # WAB

data/lib/wab/impl/bool_expr.rb

@@ -0,0 +1,25 @@
+
+module WAB
+  module Impl
+
+    class BoolExpr < Expr
+
+      # Create an expression with the provided arguments which must be
+      # instances of subclasses of the Expr class.
+      #
+      # args:: argument to the expression
+      def initialize(*args)
+        @args = args
+      end
+
+      def append_arg(arg)
+        @args << arg
+      end
+
+      def eval(_data)
+        false
+      end
+
+    end # BoolExpr
+  end # Impl
+end # WAB