wabur 0.1.0d1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f881d414a328e743c262513bde6977d3a28a3ec3
+  data.tar.gz: f3d99084f2ad9ccb619ceb3572a4c0bc66863c5f
+SHA512:
+  metadata.gz: 0b4ca9f500c474908d6a4b740a86ec360f0386332e7d55bd724743124d041983c1854834cbac66a874c73b2a7f1b3c674224c830a4d0b3dee3f50204efe89b3f
+  data.tar.gz: b71155371f81f098034483486ff036e36ccaee5c460072dc61a7fe3012df97de643c2eea5514c9561f50ace56c5b1685cbde4cd04e3a322d5dd490ce15f71f1a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Peter Ohler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,58 @@
+# WABuR (Web Application Builder using Ruby)
+
+Ruby is a great language but for performance C is a better alternative. It is
+possible to get the best of both as evident with [Oj](http://www.ohler.com/oj)
+and [Ox](http://www.ohler.com/ox). C by itself allowed
+[Piper](http://piperpushcache.com), a fast push web server to be developed and
+is being used to develop [OpO](http://opo.technology) a high performance graph
+and JSON database. This project takes from all of those projects for a hight
+performance Ruby web framework.
+
+Ruby on Rails has made Ruby main stream. 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 easy of use.
+
+Why develop an alternative to Rails? Rails popularity 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.
+
+## Goals
+
+Lets start with the assumption that we want to continue to use Ruby. The goal
+of this project is to provide a high performance, easy to use, and 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 use of each 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
+magnitude faster than Rails and on par with other top of the performance tier
+web frameworks across all languages.
+
+[Continue reading ...](pages/Goals.md)
+
+## 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.
+
+![](http://www.opo.technology/wab/wab_arch.svg)
+
+[Continue reading ...](pages/Architecture.md)
+
+## Participate
+
+If you like the idea and want to help out or become a core developer on the
+project send me an [email](mailto:peter@ohler.com). Get in on the ground floor
+and lets make something awesome together.
+
+## Planning
+
+The plan is informal and high level until more details are defined.
+
+[Details ...](pages/Plan.md)
+
+  

data/lib/wab/controller.rb

@@ -0,0 +1,175 @@
+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.
+  #
+  # A description of the available methods is included as private methods.
+  class Controller # :doc: all
+    attribute_accessor :shell
+    attribute_accessor :view
+    attribute_accessor :model
+
+    # Create a instance.
+    def initialize()
+      @shell = nil
+      @view = shell.view
+      @model = shell.model
+      # TBD
+    end
+
+    # Handler for paths that do not match the REST pattern. Only called on the
+    # default controller.
+    #
+    # Processing result are passed back to the view which forward the result
+    # on to the requester. The result, is not nil, should be a Data instance.
+    #
+    # path:: identifies operation and additional data in a / delimited
+    #        format. It is up to the controller to decide how to process the
+    #        request.
+    # data:: data to be processed
+    def handle(path, data)
+      nil
+    end
+
+    # To make the desired methods active while processing the desired method
+    # should be made public in the subclasses. If the methods remain private
+    # they will not be called.
+    private
+
+    # Should create a new data object.
+    #
+    # The return should be the identifier for the object created or if
+    # +with_data+ is true a Data object with an +id+ attribute and a +data+
+    # attribute that contains the full object details.
+    #
+    # On error an Exception should be raised.
+    #
+    # data:: the data to use as a new object.
+    # with_data:: flag indicating the response should include the new object
+    def create(data, with_data=false) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Should return the object with the +id+ provided.
+    #
+    # The function should return the result of a fetch on the model with the
+    # provided +id+. The result should be a Data instance which is either the
+    # object data or a wrapper that include the object id in an +id+ attribute
+    # and the object data itself in a +data+ attribute depending on the value
+    # of the +with_id+ argument.
+    #
+    # id:: identifier of the object
+    # with_id:: if true wrap the object data with an envelope that includes
+    #           the id as well as the object data.
+    def read(id, with_id=false) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Should return the objects with attributes matching the +attrs+ argument.
+    #
+    # The return should be a Hash where the keys are the matching object
+    # identifiers and the value are the object data. An empty Hash or nil
+    # indicates there were no matches.
+    #
+    # attrs:: 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.
+    def read_by_attrs(attrs) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Replaces the object data for the identified object.
+    #
+    # The return should be the identifier for the object updated or if
+    # +with_data+ is true a Data object with an +id+ attribute and a +data+
+    # attribute that contains the full object details. Note that depending on
+    # the implemenation the identifier may change as a result of an update.
+    #
+    # On error an Exception should be raised.
+    #
+    # id:: identifier of the object to be replaced
+    # data:: the data to use as a new object.
+    # with_data:: flag indicating the response should include the new object
+    def update(id, data, with_data=false) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Delete the identified object.
+    #
+    # On success the deleted object identifier is returned. If the object is
+    # not found then nil is returned. On error an Exception should be raised.
+    #
+    # id:: identifier of the object to be deleted
+    def delete(id) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Delete all object that match the set of provided attribute values.
+    #
+    # An array of deleted object identifiers should be returned.
+    #
+    # attrs:: 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.
+    def delete_by_attrs(attrs) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Return a Hash of all the objects of the type associated with the
+    # controller.
+    #
+    # The return hash keys should be the identifiers of the objects and the
+    # the values should be either nil or the object data if the +with_data+
+    # flag is true. If the response will be larger than supported one of the
+    # keys should be the empty string which indicated additional instance
+    # exists and were not provided.
+    #
+    # Note that this could return a very large set of data. If the number of
+    # instances in the type is large the +search()+ might be more appropriate
+    # as it allows for paging of results and sorting.
+    #
+    # with_data:: flag indicating the return should include object data
+    def list(with_data=false) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Search using a TQL SELECT.
+    #
+    # The provided TQL[http://opo.technology/pages/doc/tql/index.html] can be
+    # either the JSON syntax or the friendly syntax. The call exists on the
+    # controller to allow filtering and permission checking before
+    # execution. Only the default controller is expected to provide a public
+    # version of this method.
+    #
+    # query:: query
+    # format:: can be one of :TQL or :TQL_JSON. The :GraphQL option is
+    #          reserved for the future.
+    def search(query, format=:TQL) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Subscribe to changes in data pushed from the model that will be passed
+    # to the view with the +push+ method if it passes the supplied filter.
+    #
+    # The +view+ +changed+ method is called when changes in data cause
+    # the associated object to pass the provided filter.
+    #
+    # filter:: the filter to apply to the data. TBD the nature of the filter is pending.
+    def subscribe(filter)
+      # TBD
+    end
+
+    # Called by the model when data changes if supported by the model storage
+    # component.
+    #
+    # data:: the data that has changed
+    def changed(data) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+  end # Controller
+end # WAB

data/lib/wab/data.rb

@@ -0,0 +1,73 @@
+
+module WAB
+
+  # The class representing the cananical data structure in WAB. Typically the
+  # Data instances are factory created by the Shell and will most likely not
+  # be instance of this class but rather a class that is a duck-type of this
+  # class (has the same methods and behavior).
+  class Data
+
+    # This method is included only for testing purposes of the Ruby base
+    # Shell. It should only be called by the Shell. Create a new Data instance
+    # with the initial value provided. The value must be a Hash or Array. The
+    # members of the Hash or Array must be nil, boolean, String, Integer,
+    # Float, BigDecimal, Array, Hash, Time, WAB::UUID, or WAB::IRI.
+    def initialize(value=nil)
+      # TBD
+    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)
+      # TBD
+    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',
+    # 'grandchild']. The value must be one of the allowed data values
+    # described in the initialize method.
+    def set(path, value)
+      # TBD
+    end
+
+    # Each child of the Data instance is provided as an argument to a block
+    # when the each method is called.
+    def each()
+      # TBD
+    end
+
+    # Each leaf of the Data instance is provided as an argument to a block
+    # when the each method is called. A leaf is a primitive that has no
+    # children and will be nil, a Boolean, String, Numberic, Time, WAB::UUID,
+    # or WAB::IRI.
+    def each_leaf()
+      # TBD
+    end
+
+    # Make a deep copy of the Data instance.
+    def clone()
+      # TBD
+    end
+
+    # Returns the instance converted to native Ruby values such as a Hash,
+    # Array, etc.
+    def native()
+      # TBD
+    end
+
+    # Returns true if self and other are either the same or have the same
+    # contents. This is a deep comparison.
+    def eql?(other)
+      # TBD
+    end
+
+    # Encode the data as a JSON string.
+    def json(indent=0)
+      # TBD
+    end
+
+  end # Data
+end # WAB

data/lib/wab/model.rb

@@ -0,0 +1,136 @@
+
+module WAB
+
+  # Represents the model portion of a MVC design pattern. It must respond to
+  # request to update the store using either the CRUD type operations that
+  # match the controller.
+  class Model
+
+    # Should create a new data object.
+    #
+    # The return should be the identifier for the object created or if
+    # +with_data+ is true a Data object with an +id+ attribute and a +data+
+    # attribute that contains the full object details.
+    #
+    # On error an Exception should be raised.
+    #
+    # data:: the data to use as a new object.
+    # with_data:: flag indicating the response should include the new object
+    def create(data, with_data=false) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Should return the object with the +id+ provided.
+    #
+    # The function should return the result of a fetch on the model with the
+    # provided +id+. The result should be a Data instance which is either the
+    # object data or a wrapper that include the object id in an +id+ attribute
+    # and the object data itself in a +data+ attribute depending on the value
+    # of the +with_id+ argument.
+    #
+    # id:: identifier of the object
+    # with_id:: if true wrap the object data with an envelope that includes
+    #           the id as well as the object data.
+    def read(id, with_id=false) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Should return the objects with attributes matching the +attrs+ argument.
+    #
+    # The return should be a Hash where the keys are the matching object
+    # identifiers and the value are the object data. An empty Hash or nil
+    # indicates there were no matches.
+    #
+    # attrs:: 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.
+    def read_by_attrs(attrs) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Replaces the object data for the identified object.
+    #
+    # The return should be the identifier for the object updated or if
+    # +with_data+ is true a Data object with an +id+ attribute and a +data+
+    # attribute that contains the full object details. Note that depending on
+    # the implemenation the identifier may change as a result of an update.
+    #
+    # On error an Exception should be raised.
+    #
+    # id:: identifier of the object to be replaced
+    # data:: the data to use as a new object.
+    # with_data:: flag indicating the response should include the new object
+    def update(id, data, with_data=false) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Delete the identified object.
+    #
+    # On success the deleted object identifier is returned. If the object is
+    # not found then nil is returned. On error an Exception should be raised.
+    #
+    # id:: identifier of the object to be deleted
+    def delete(id) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Delete all object that match the set of provided attribute values.
+    #
+    # An array of deleted object identifiers should be returned.
+    #
+    # attrs:: 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.
+    def delete_by_attrs(attrs) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Return a Hash of all the objects of the type associated with the
+    # controller.
+    #
+    # The return hash keys should be the identifiers of the objects and the
+    # the values should be either nil or the object data if the +with_data+
+    # flag is true. If the response will be larger than supported one of the
+    # keys should be the empty string which indicated additional instance
+    # exists and were not provided.
+    #
+    # Note that this could return a very large set of data. If the number of
+    # instances in the type is large the +search()+ might be more appropriate
+    # as it allows for paging of results and sorting.
+    #
+    # with_data:: flag indicating the return should include object data
+    def list(with_data=false) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Search using a TQL SELECT.
+    #
+    # The provided TQL[http://opo.technology/pages/doc/tql/index.html] can be
+    # either the JSON syntax or the friendly syntax. The call exists on the
+    # controller to allow filtering and permission checking before
+    # execution. Only the default controller is expected to provide a public
+    # version of this method.
+    #
+    # query:: query
+    # format:: can be one of :TQL or :TQL_JSON. The :GraphQL option is
+    #          reserved for the future.
+    def search(query, format=:TQL) # :doc:
+      # TBD implement the default behavior as an example or starting point
+    end
+
+    # Subscribe to changes in stored data and push changes to the controller
+    # if it passes the supplied filter.
+    #
+    # The +controller+ +changed+ method is called when changes in data cause
+    # the associated object to pass the provided filter.
+    #
+    # controller:: the controller to notify of changed
+    # filter:: the filter to apply to the data. Syntax is that TQL uses for the FILTER clause.
+    def subscribe(controller, filter)
+      # TBD
+    end
+
+  end # Model
+end # WAB

data/lib/wab/shell.rb

@@ -0,0 +1,46 @@
+module WAB
+
+  # The Shell is a duck-typed class. Any shell alternative should implement
+  # all the methods defined in the class except the +initialize+ method. This
+  # class is also the default Ruby version of the shell that can be used for
+  # development and small systems.
+  class Shell
+
+    # Sets up the shell with a view, model, and type_key.
+    def initialize(view, model, type_key='kind')
+      @view = view
+      @model = model
+      @controllers = {}
+      @type_key = type_key
+    end
+
+    # Returns the view instance that can be used for pushing data to a view.
+    def view()
+      @view
+    end
+
+    # Returns the model instance that can be used to get and modify data in
+    # the data store.
+    def model()
+      @model
+    end
+
+    # Returns the path where a data type is located. The default is 'kind'.
+    def type_key()
+      @type_key
+    end
+
+    # Register a controller for a named type.
+    #
+    # If a request is received for an unregistered type the default controller
+    # will be used. The default controller is registered with a +nil+ key.
+    #
+    # type:: type name
+    # controller:: Controller instance for handling requests for the identified +type+
+    def register_controller(type, controller)
+      controller.shell = self
+      @controllers[type] = controller
+    end
+
+  end # Shell
+end # WAB

data/lib/wab/version.rb

@@ -0,0 +1,5 @@
+
+module WAB
+  # Current version of the module. 
+  VERSION = '0.1.0d1'
+end

data/lib/wab/view.rb

@@ -0,0 +1,21 @@
+module WAB
+
+  # Represents the view in the MVC design pattern. It is primarily used to
+  # call the controller with requests but can be used to push data out to a
+  # display if push is supported.
+  #
+  # This class is the default implementation.
+  class View
+
+    def initialize()
+      # TBD as the default implementation this should be an HTTP server that
+      # serves files as well as JSON to a Javascript enabled browser.
+    end
+
+    # Push changed data to a display.
+    def changed(data)
+      # TBD
+    end
+
+  end # View
+end # WAB

data/lib/wab.rb

@@ -0,0 +1,5 @@
+
+# Web Application Builder
+module WAB
+end
+

data/pages/Architecture.md

@@ -0,0 +1,200 @@
+# Architecture
+
+The WAB architecture is a Mode View Controller with clear APIs between each
+part of the MVC. The design allows the non-business related tasks such as the
+HTTP server and data store to be treated as service to the Controller which
+contains the business logic.
+
+![](http://www.opo.technology/wab/wab_arch.svg)
+
+## MVC
+
+The Model View Controller pattern is a well known and widely accepted design
+pattern. It is also the pattern used by Rails. WAB adheres to this model with
+well defined APIs that are used exclusively.
+
+The MVC pattern has many variants with some functionality being in different
+components depending on how the lines are drawn between those components. No
+matter what the separation, if it is clear many issues can be avoided.
+
+### Model
+
+The Model component is responsible for persisting data, providing search and
+retrieval capabilities, and assuring stored consistency. The Model does not
+assure business logic consistency nor does it enforce relationships between
+data elements. It is a data store only.
+
+The data in the system is follows a JSON structural model. This make a NoSQL
+database an ideal store. It does mean that the Model data is unstructured in
+that there is no schema enforced by the data store. It does not mean that
+relationships do not exist in the data store.
+
+With well defined APIs between the Model and the Controller almost any data
+store can be used as long as an adapter is written. This allows options such
+as [MongoDB](https://www.mongodb.com), [Redis](https://redislabs.com),
+[OpO](http://opo.technology), a file based store, or even an in memory store
+for testing.
+
+One feature that may not be supported by all stores is the ability to push
+changes from the data store to the Controller and then up to the View to real
+time feeds.
+
+### View
+
+An HTTP server provides the View environment. In addition to serving HTML,
+CSS, images, and other files typically served by a web server the View server
+also supports exchanging JSON data through a REST API. A WebSocket and SSE
+capability is also expected and designed for in the API.
+
+Javascript is the suggested language to use for web pages but any approach to
+accepting and delivering JSON is fine. JaveScript helpers are provided that
+support the REST API as well as the WebSocket and SSE push APIs.
+
+### Controller
+
+With two approaches to connecting the Controller to the View and Model there
+are deployment options that allow trading off latency for throughput. The
+Controller code is isolated from those deployment choices except for the
+choice of language. If the Controller is written in Ruby then it can be either
+embedded in the shell or access as an external application.
+
+The Controller is a bridge between the View and Model and implements the
+business logic as needed. In the case of a fetch, create, or update options
+are available to bypass or use the default Controller. The bypass allows a
+more direct conduit between the View and the Model with the Controller just
+passing the data along to the model and vice versa.
+
+The Controller can also receive callbacks on changes in the Model which can
+then be forwarded to the View if a subscription to that data has been made.
+
+## APIs
+
+All APIs are described with Ruby code as the Controller is expected to be
+Ruby. If an external Controller is to be used then the external glue API is
+used. This API is a text based API over a pipe (Unix socket). Events can
+arrive at the Controller from either the View or Model interface.
+
+### Data Model
+
+Data is loosely represented as JSON. There are some expectations that can be
+relaxed if desired.
+
+#### JSON
+
+The data exchanged between components follows the JSON model for primitives
+with a few optional additions. The JSON types can be used exclusively and are:
+
+ - `null` (nil)
+ - _boolean_ (`true` | `false`)
+ - _string_ (String)
+ - _number_ (Integer | Float | BigDecimal)
+ - _object_ (Hash)
+ - _array_ (Array)
+
+All string must be UTF-8 or Unicode.
+
+Some other types are also allowed. Each has a defined JSON representation that
+can be used instead.
+
+ - _time_ (Ruby Time encoded in RFC 3339 format if a string)
+ - _UUID_ (WAB::UUID encoded as defined by RFC 4122)
+ - _IRI_ (WAB::IRI encoded as defined by RFC 3987)
+
+These types are represented by the WAB::Data class.
+
+#### Structure
+
+While object can be any JSON or WAB::Data they are encouraged to be JSON
+Objects (Hash) types. I addition one attribute should be used to identify the
+type. The default is the 'kind' attribute. That attribute is not required to
+be the 'kind' attribute but can be anywhere in the data tree as long as it is
+consistent across all types. As an example it could be in 'meta.kind' where
+that key represents a path with a 'kind' element in a 'meta' object (Hash).
+
+Each object or for that matter every node in a Data tree is assigned a system
+wide unique identifier. That is used to identfiy each object when using the
+API. From the view perspective a REST over HTTP is used.
+
+#### Just Data
+
+  - just data and data helpers (get, set, inspect, to_s)
+   - nothing like to_json
+   - reasoning it that different uses require different behavior
+    - different stores, view, processing, etc
+   - use of delgate is encouraged
+
+
+### View/Controller
+
+The View/Controller API is predominanty from View to Controller but the
+ability for the Controller to push data to the View is also part of the
+design. That allows pages to take advantage of WebSockets or SSEs to display
+data changes as they occur.
+
+See the Controller class documentation for further details.
+
+### Controller/Model
+
+The Contoller/Model API is driven mostly from Controller to Model with the
+Model responding to queries. Like the View/Controller API the Model can also
+push changes to the Controller.
+
+The Model supports basic CRUD operations as well as a query API that uses
+[TQL](http://opo.technology/pages/doc/tql/index.html) in both the friendly and
+JSON formats. Support for GraphQL is anticipated but not for the first
+iteration.
+
+See the Model class documentation for further details.
+
+## Shells
+
+As noted in the architecture diagram, the WAB Shell can be either the C or
+Ruby shell. The Ruby shell is intended for development and possibly small
+installations. The C WAB Shell or Shells if more thna one is implemented are
+intended to be high performance environments that the Controller code resides
+in either as embedded code or through a piped connections.
+
+### Embedded
+
+A C WAB Shell with an embedded Controller utilizes the View and Model APIs
+directly through the Ruby library. This approach gives more control to the
+Shell in regard to utilizing threads and C libraries outside of Ruby. An
+alternative approach is to call C extensions from Ruby but that approach is
+left for future if it makes sense.
+
+The Ruby WAB Shell implements an HTTP server as well as either an in memory
+data store or a file based data store.
+
+The APIs are designed to allow relatively direct modifications to the data
+store if the store supports such.
+
+The embedded Shell should have the lowest latency but may sacrifice throughput
+depending on the complexity of the Controller code.
+
+### External
+
+Running external Controllers is implemented by the WAB Shell either spawning
+the Controller application or connecting to an existing one. Multiple
+Controllers can be active to allow parallel Controller processing. The
+approach taken is the same as that used [Piper Push
+Cache](http://piperpushcache.com) with the process flow [Spawn
+Actor](http://piperpushcache.com/help_actor_spawn).
+
+To run a Controller written in Ruby the External Glue is used to bridge the
+gap between the WAB external API and the Controller APIs. This is a light
+weught layer that converts to and from the text based pipe API and the Ruby
+APIs.
+
+With the ability to make use of multiple Controller instances which may reside
+on different machines the throughput is expected to be higher than the
+embedded Shell but with a degradation of the latency.
+
+### Alternatives
+
+A straight Ruby WAB Shell is the choice for testing and for small
+installations. The Ruby shell is the first choice when getting started.
+
+Outside of this project WAB C or other language shells can be written. The
+first is expected to be a derivative of [OpO](http://opo.technology) as it
+takes shape. This WAB Shell will also draw on the libraries use by [Piper
+Push Cache](http://piperpushcache.com) to provide WebSocket and SSE support.

data/pages/Goals.md

@@ -0,0 +1,110 @@
+# Goals
+
+The goal is to provide a high performance, easy to use, and fully featured web
+framework that uses Ruby for business logic. Following a Model/View/Controller
+model Ruby is used to implement the Controller portion. Using the best
+language for each portion of the MVC the View is implemented in JavaScript,
+HTML, and CSS. The Model is simply a NoSQL data store.
+
+To address the ease of use clean and clear APIs are used between each part of
+the MVC and JSON is the data representation throughout. Ruby is straight Ruby
+with no monkey patched core classes and no magic. Plain and simple Ruby.
+
+## Performance
+
+With a goal of building a high performance system the architecture is design
+from the start to deliver the best performance possible. Code will also
+developed with that goal in mind. All code will be unit tested and benchmarks
+made where applicable.
+
+### Approach
+
+The architecture is module and follows a Model View Controller design pattern
+with clear and defined APIs between each module. This will ensure a clear
+division between the Model, View, and Controller modules.
+
+With a modular design the most appropriate data store can be selected. By
+being able to swap out different storage modules choices can be made between
+hooking up to an existing SQL or NoSQL data store or using a faster or more
+scaleable choice.
+
+A separation of data and behavior is part of the overall approach. By keeping
+the data separate and devoid of behavior the movement of data between the
+elements of the MVC doesn't drag along methods not appropriate for the
+component. It also allows behavior to be implemented without impacting the
+data and updated and modified without a global replacement of the system as a
+whole. Related to this approach is that there will be absolutely no monkey
+patching of core Ruby classes. Monkey patching creates unexpected behavior and
+cause conflicts between modules.
+
+Serialization must be fast and reduced to a minimum. The APIs provide an
+abstraction that allows optimized data structures to be used as long as they
+follow a JSON model view through the access APIs.
+
+Ruby code is kept as simple and direct as possible to reduce the overhead of
+deeply nested calls and object creation.
+
+There are parts of the system that can be written in higher performance
+languages such as C. This includes the HTTP and data stores. By allowing use
+of a mixed environment the best performance can be achieved.
+
+### Targets
+
+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
+magnitude faster than Rails and on par with other top of the performance tier
+web frameworks in all languages.
+
+The throughput and latency targets are not unreasonable as
+[OpO](http://opo.technology) as an HTTP server providing JSON documents with
+the Ruby controller has demonstrated that 140K fetches per second with a
+latency of 0.6 milliseconds is possible on a desktop machine. With a thin Ruby
+controller or a bypass for simple fetches the additional overhead is minimal.
+
+The system must be scaleable in at least one configuration. Possibly using
+multiple Ruby instances as processes or threads.
+
+In the final deployment the aim is for upper part of performance tier when
+compared to other web framework across all languages. Right now in
+[benchmarks](https://gist.github.com/omnibs/e5e72b31e6bd25caf39a) Rails and
+Sinatra occupy the bottom slots. WAB will put Ruby near the top.
+
+## Easy to Use
+
+In addition to performance goals WAB must be easy to use not only for a
+'Hello World' application but for advanced systems as well. The learning curve
+must be shallow to allow new users to get started immediately and then
+progress onto more advanced features.
+
+### Simplicity, Clear, and Simple
+
+The Ruby code used in WAB will be simple and direct. There will be no
+magic. Clear documented class definitions with shallow class hierachy
+throughout.
+
+### Development
+
+Development is a cycle of edit and test repeated over and over again. The
+faster that cycle is the more friendly the development environment. Keep
+modules encapsulated with well defined APIs allows this cycle to be fast as
+unit tests just test against the APIs.
+
+This strategy of well defined APIs and testing continues at all levels up to
+system testing.
+
+### Upgrade Path
+
+It is expected that the development environment will use a Ruby shell while
+larger scale production will use a C shell. That doesn't mean moving to a C
+WAB shell is necessary but it can be used if needed.
+
+## Best for Purpose
+
+Ruby is appropriate for the business logic expected in the Controller in the
+MVC model but there are no advantages to using Ruby to form HTML pages for the
+View. JavaScript, HTML, and CSS are a better choice. Along similar lines,
+there is no advantage of using Ruby to write the data store or for that matter
+using Ruby to convert data into database calls. In the development shell it is
+fine but the option to use another language should be available for
+performance reasons. That allows the data store to be a service independent of
+the Ruby code.

data/pages/Plan.md

@@ -0,0 +1,11 @@
+# Plan
+
+More details will be added here as progress continues. For now the hight level plan is:
+
+- Define APIs
+  - View API
+  - Model/Store API
+- Structure Ruby Framework
+  - Embedded Glue layer
+  - External Glue layer
+  

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: wabur
+version: !ruby/object:Gem::Version
+  version: 0.1.0d1
+platform: ruby
+authors:
+- Peter Ohler
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-06-03 00:00:00.000000000 Z
+dependencies: []
+description: 'Web Application Builder '
+email: peter@ohler.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- pages/Architecture.md
+- pages/Goals.md
+- pages/Plan.md
+files:
+- LICENSE
+- README.md
+- lib/wab.rb
+- lib/wab/controller.rb
+- lib/wab/data.rb
+- lib/wab/model.rb
+- lib/wab/shell.rb
+- lib/wab/version.rb
+- lib/wab/view.rb
+- pages/Architecture.md
+- pages/Goals.md
+- pages/Plan.md
+homepage: http://github.com/ohler55/wabur
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--title"
+- WABuR
+- "--main"
+- README.md
+- "--private"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: wabur
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: Web Application Builder
+test_files: []