qm 1.1.10 → 1.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 92fbd2db28892ca2fd61d59edaf0ce904d36b8a0
-  data.tar.gz: 0791eaaeefcc38be2c88128b054b66a0ca7b33c3
+  metadata.gz: 4e4b2cd330c69ee8a8d56b14249fb06e9d1b3d2a
+  data.tar.gz: 00c4657ea4b0dfbc005c6f01203f68392b111b9c
 SHA512:
-  metadata.gz: 1cf1815745678de00a61b9af3b05648f9d0d287ee31f3518cebbc0d00acdbe1add773d05c82ce524d4bf7983d2b98dff36a096bba280767f4b9f226db9584f87
-  data.tar.gz: 5cf44879eadf705525a8c28e343b0ea4a2a5ee417d4626bbea6cbd05eef3db604e2732950b7e5018e7ab3055ecf0815ed9b4a89bcb58ae1c42fc378a8cb2f01c
+  metadata.gz: 715e30c6223fd2daf8d63f23b973c1f5741692266b0bd17e51fe7e644a9e026d48ab47f7c21690b94a9b2e586e1930c3246d0af72ba9cf464c26e6fb116ffcbf
+  data.tar.gz: ccc3852764ffdfdd44b7945470fe4237c90127f4d4052eb35a361d30718a3274f7a6a89c2340e1c4f3ba39bf25a9fc32d6e7b171eaf17af695e0ff856d02c388

data/README.md

@@ -1,8 +1,8 @@
-# qm [![Gem Version](https://badge.fury.io/rb/qm.png)](http://badge.fury.io/rb/qm) [![Dependency Status](https://gemnasium.com/qmachine/qm-ruby.png)](https://gemnasium.com/qmachine/qm-ruby)
+# qm
 
-The `qm` gem for [Ruby](http://www.ruby-lang.org/) will implement both the API
-server and the web server components of [QMachine](https://www.qmachine.org)
-(QM), but currently it is *very* incomplete.
+The `qm` gem for [Ruby](http://www.ruby-lang.org/) implements both the API
+server and web server components of [QMachine](https://www.qmachine.org) (QM),
+but currently it is incomplete, especially with regard to configuration.
 
 Install
 -------
@@ -11,4 +11,8 @@ To install the latest release, run
 
     gem install qm
 
+===
+
+[![Gem Version](https://badge.fury.io/rb/qm.png)](http://badge.fury.io/rb/qm) [![Dependency Status](https://gemnasium.com/qmachine/qm-ruby.png)](https://gemnasium.com/qmachine/qm-ruby)
+
 <!-- vim:set syntax=markdown: -->

data/lib/api-server.rb

@@ -0,0 +1,198 @@
+#-  Ruby source code / Rack configuration file
+
+#-  api-server.rb ~~
+#
+#   This file is a hacked-up version of the "teaching version" of QMachine,
+#   and the rest of this introduction reflects that.
+#
+#   This is a self-contained Rack app that uses Sinatra's domain-specific
+#   language (DSL) in tandem with SQLite to implement a teaching version of
+#   QMachine. The idea here is to pack most of the functionality of the
+#   original Node.js codebase into a single file that reads like pseudo-code.
+#
+#   Of course, there are some caveats. This version succeeds in abbreviating
+#   the original codebase, but it doesn't support all of the original options
+#   yet. The code can also be hard to modify if you're unfamiliar with Sinatra,
+#   because Ruby's scoping rules are very different from JavaScript's, and
+#   Sinatra's DSL makes things even "worse", to be honest. My advice here is,
+#   don't think too hard about it. Just enjoy it.
+#
+#   I do plan to merge this program with the Ruby gem in the future, which is
+#   why the database schema matches the Node.js implementation's (which is not
+#   as straight-forward as it could be). For now, it serves its purpose, and it
+#   does so with just 95 lines of source code ;-)
+#
+#   NOTE: Using a "%" character incorrectly in a URL will cause you great
+#   anguish, and there isn't a good way for me to handle this problem "softly"
+#   because it is the expected behavior (http://git.io/bmKr2w). Thus, you will
+#   tend to see "Bad Request" on your screen if you insist on using "%" as part
+#   of a 'box', 'key', or 'status' value.
+#
+#                                                       ~~ (c) SRW, 24 Apr 2013
+#                                                   ~~ last updated 13 Jul 2014
+
+require 'json'
+require 'sinatra'
+#require 'sinatra/cross_origin'
+require 'sqlite3'
+
+class QMachineService < Sinatra::Base
+
+    configure do
+
+      # QMachine options
+
+        set avar_ttl:               86400, # seconds
+            enable_api_server:      true,
+            enable_CORS:            true,
+            enable_web_server:      true,
+            hostname:               '0.0.0.0',
+            persistent_storage:     'qm.db',
+            port:                   ENV['PORT'] || 8177,
+            public_folder:          'public'
+
+     # Sinatra mappings and options needed by QMachine -- leave these alone ;-)
+
+        mime_type webapp: 'application/x-web-app-manifest+json'
+        set bind: :hostname, run: false, static: :enable_web_server
+
+     # See also: http://www.sinatrarb.com/configuration.html
+
+    end
+
+    error do
+     # This "route" handles errors that occur as part of the server-side code.
+        hang_up
+    end
+
+    helpers do
+     # This block defines subfunctions for use inside the route definitions.
+
+        def sqlite(query)
+         # This helper method helps DRY out the code for database queries, and
+         # it does so in an incredibly robust and inefficient way -- by
+         # creating the table and evicting expired rows before every single
+         # query. A caveat, of course, is that the special ":memory:" database
+         # doesn't work correctly, but ":memory:" isn't *persistent* storage
+         # anyway. Also, I have omitted indexing on `box_status` for obvious
+         # reasons :-P
+            begin
+                db = SQLite3::Database.open(settings.persistent_storage)
+                db.execute_batch <<-sql
+                    CREATE TABLE IF NOT EXISTS avars (
+                        body TEXT NOT NULL,
+                        box_key TEXT NOT NULL PRIMARY KEY,
+                        box_status TEXT,
+                        exp_date INTEGER NOT NULL,
+                        key TEXT
+                    );
+                    DELETE FROM avars WHERE (exp_date < #{now_plus(0)})
+                    sql
+              # We have to execute the query code `query` separately because
+              # the `db.execute_batch` function always returns `nil`, which
+              # prevents us from being able to retrieve the results of the
+              # query.
+                x = db.execute(query)
+            rescue SQLite3::Exception => err
+                puts "Exception occurred: #{err}"
+            ensure
+                db.close if db
+            end
+            return x
+        end
+
+        def hang_up
+         # This helper method "hangs up" on a request by sending a nondescript
+         # 444 response back to the client, a convention taken from nginx.
+            halt [444, {'Content-Type' => 'text/plain'}, ['']]
+        end
+
+        def now_plus(dt)
+          # This helper method computes a date (in milliseconds) that is
+          # specified by an offset `dt` (in seconds).
+            return (1000 * (Time.now.to_f + dt)).to_i
+        end
+
+    end
+
+    not_found do
+      # This "route" handles requests that didn't match.
+        hang_up
+    end
+
+    if settings.enable_api_server? then
+
+      # Here, we set up "routes" to handle incoming GET and POST requests.
+
+        before '/*/*' do |version, box|
+          # When any request matches the pattern given, this block will execute
+          # before the route that corresponds to its HTTP method. The code here
+          # will validate the request's parameters and store them as instance
+          # variables that will be available to the corresponding route's code.
+            @box, @key, @status = box, params[:key], params[:status]
+            hang_up unless ((version == 'box') or (version == 'v1')) and
+                    (@box.match(/^[\w\-]+$/)) and
+                    ((@key.is_a?(String) and @key.match(/^[A-Za-z0-9]+$/)) or
+                    (@status.is_a?(String) and @status.match(/^[A-Za-z0-9]+$/)))
+            #cross_origin if settings.enable_CORS?
+        end
+
+        get '/:version/:box' do
+          # This route responds to API calls that "read" from persistent
+          # storage, such as when checking for new tasks to run or downloading
+          # results.
+            hang_up unless (@key.is_a?(String) ^ @status.is_a?(String))
+            bk, bs = "#{@box}&#{@key}", "#{@box}&#{@status}"
+            if @key.is_a?(String) then
+              # This arm runs when a client requests the value of a specific
+              # avar.
+                x = sqlite("SELECT body FROM avars WHERE box_key = '#{bk}'")
+                y = (x.length == 0) ? '{}' : x[0][0]
+            else
+              # This arm runs when a client requests a task queue.
+                x = sqlite("SELECT key FROM avars WHERE box_status = '#{bs}'")
+                y = (x.length == 0) ? '[]' : (x.map {|row| row[0]}).to_json
+            end
+            return [200, {'Content-Type' => 'application/json'}, [y]]
+        end
+
+        post '/:version/:box' do
+          # This route responds to API calls that "write" to persistent
+          # storage, such as when uploading results or submitting new tasks.
+            hang_up unless @key.is_a?(String) and not @status.is_a?(String)
+            body, ed = request.body.read, now_plus(settings.avar_ttl)
+            x = JSON.parse(body)
+            hang_up unless (@box == x['box']) and (@key == x['key'])
+            bk, bs = "#{@box}&#{@key}", "#{@box}&#{x['status']}"
+            if x['status'].is_a?(String) then
+              # This arm runs only when a client writes an avar which
+              # represents a task description.
+                hang_up unless x['status'].match(/^[A-Za-z0-9]+$/)
+                sqlite("INSERT OR REPLACE INTO avars
+                            (body, box_key, box_status, exp_date, key)
+                        VALUES ('#{body}', '#{bk}', '#{bs}', #{ed}, '#{@key}')")
+            else
+              # This arm runs when a client is writing a "regular avar".
+                sqlite("INSERT OR REPLACE INTO avars (body, box_key, exp_date)
+                        VALUES ('#{body}', '#{bk}', #{ed})")
+            end
+            return [201, {'Content-Type' => 'text/plain'}, ['']]
+        end
+
+    end
+
+    if settings.enable_web_server? then
+
+        get '/' do
+          # This route enables a static index page to be served from the public
+          # folder, if and only if QM's web server has been enabled.
+            send_file(File.join(settings.public_folder, 'index.html'))
+        end
+
+    end
+
+end
+
+QMachineService.run!
+
+#-  vim:set syntax=ruby:

data/lib/qm.rb

@@ -2,7 +2,7 @@
 
 #-  qm.rb ~~
 #                                                       ~~ (c) SRW, 12 Apr 2013
-#                                                   ~~ last updated 17 Apr 2013
+#                                                   ~~ last updated 13 Jul 2014
 
 module QM
 
@@ -27,7 +27,8 @@ module QM
 
     def self::launch_service(*obj)
       # This function needs documentation.
-        puts '(placeholder: `launch_service`)';
+        require 'api-server.rb'
+        #puts '(placeholder: `launch_service`)';
         return;
     end
 

metadata

@@ -1,16 +1,72 @@
 --- !ruby/object:Gem::Specification
 name: qm
 version: !ruby/object:Gem::Version
-  version: 1.1.10
+  version: 1.1.11
 platform: ruby
 authors:
 - Sean Wilkinson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-01 00:00:00.000000000 Z
-dependencies: []
-description: This is a *very incomplete* port of QMachine.
+date: 2014-07-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.8.1
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.4.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.4.5
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.3.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.3.9
+- !ruby/object:Gem::Dependency
+  name: thin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.6.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.6.2
+description: This is an incomplete port of the QMachine web service.
 email: sean@mathbiol.org
 executables: []
 extensions: []
@@ -20,11 +76,13 @@ extra_rdoc_files:
 files:
 - LICENSE
 - README.md
+- lib/api-server.rb
 - lib/qm.rb
 homepage: https://www.qmachine.org
 licenses:
 - Apache 2.0
-metadata: {}
+metadata:
+  issue_tracker: https://github.com/qmachine/qm-ruby/issues
 post_install_message: 
 rdoc_options: []
 require_paths: