webservice 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b43248423b9aeba87a88f63b6a708167bbf7d723
-  data.tar.gz: 35b9cd86f34c708a4d55f7f61a08a878f4e19d12
+  metadata.gz: fca9552fa4818068271c81022e7ab9a4ec277d30
+  data.tar.gz: 23e2d0051213a5834cafff2762df4324c6907935
 SHA512:
-  metadata.gz: def6d86899d29ca10acb0c70af15de8887005fc47dc9f1d5586103eb98033d7e68d5c44744c51b30493cbcef344a565f9dbcc21c6681aa55257e42c772c0f307
-  data.tar.gz: 2417ece5303df96025515574a343e2b21eaa1e08015ff7cfe11822a9d9d757c918a798e149d1d03f24b74a7574e0ef6e4625778b6b63b6b42fa0f403c31adb19
+  metadata.gz: 6b53f3b4ea61aed918b16b5b73ad3be4e162131599d6cb1222607097d5cff3f8757222458373a2a3e30dbea91d47f32c092f6557e274bebcbdaf0ae8c121f992
+  data.tar.gz: b32faf56e9286e1b4283d900f59f7b1af4bfd89b70366e849200c014540c8e80c45a9110a1d51239372eb414aec5f5f308149960786d6d32f254a942fd404a85

data/README.md

@@ -10,11 +10,151 @@ webservice gem - yet another HTTP JSON API (web service) builder
 
 ## Usage
 
-TBD
+[Dynamic Example](#dynamic-example) •
+[Classic Example](#classic-example) •
+[Rackup Example](#rackup-example)
+
+
+### Dynamic Example
+
+You can load services at-runtime from files using `Webservice.load_file`.
+Example:
+
+```ruby
+# service.rb
+
+get '/' do
+  'Hello, world!'
+end
+```
+
+and
+
+```ruby
+# server.rb
+
+require 'webservice'
+
+App = Webservice.load_file( './service.rb' )
+App.run!
+```
+
+and to run type
+
+```
+$ ruby ./server.rb
+```
+
+
+### Classic Example
+
+```ruby
+# server.rb
+
+require 'webservice'
+
+class App < Webservice::Base
+  get '/' do
+    'Hello, world!'
+  end
+end
+
+App.run!
+```
+and to run type
+
+```
+$ ruby ./server.rb
+```
+
+
+### Rackup Example
+
+Use `config.ru` and `rackup`. Example:
+
+```ruby
+# config.ru
+
+require `webservice`
+
+class App < Webservice::Base
+  get '/' do
+    'Hello, world!'
+  end
+end
+
+run App
+```
+
+and to run type
+
+```
+$ rackup      # will (auto-)load config.ru
+```
+
+Note: `config.ru` is a shortcut (inline)
+version of `Rack::Builder.new do ... end`:
+
+```ruby
+# server.rb
+
+require 'webservice'
+
+class App < Webservice::Base
+  get '/' do
+    'Hello, world!'
+  end
+end
+
+builder = Rack::Builder.new do
+  run App
+end
+
+Rack::Server.start builder.to_app
+```
+
+and to run type
+
+```
+$ ruby ./server.rb
+```
+
+
+
+## "Real World" Examples
+
+See
+
+[**`beerkit / beer.db.service`**](https://github.com/beerkit/beer.db.service) -
+beer.db HTTP JSON API (web service) scripts e.g.
+
+```ruby
+get '/beer/(r|rnd|rand|random)' do    # special keys for random beer
+  Beer.rnd
+end
+
+get '/beer/:key'
+  Beer.find_by! key: params[:key]
+end
+
+get '/brewery/(r|rnd|rand|random)' do    # special keys for random brewery
+  Brewery.rnd
+end
+
+get '/brewery/:key'
+  Brewery.find_by! key: params[:key]
+end
+```
+
+[**`worlddb / world.db.service`**](https://github.com/worlddb/world.db.service) -
+world.db HTTP JSON API (web service) scripts
+
+[**`sportdb / sport.db.service`**](https://github.com/sportdb/sport.db.service) -
+sport.db (football.db) HTTP JSON API (web service) scripts
+
 
 
 ## License
 
 The `webservice` scripts are dedicated to the public domain.
 Use it as you please with no restrictions whatsoever.
-

data/lib/webservice.rb

@@ -3,6 +3,9 @@
 ## stdlib
 require 'json'
 require 'csv'
+require 'date'
+require 'time'
+require 'uri'
 require 'pp'
 
 

data/lib/webservice/base.rb

@@ -3,31 +3,50 @@
 
 module Webservice
 
+  ## use (an reuse from Rack) some freezed string constants
+  ##  HTTP verbs
+  GET     = Rack::GET
+  POST    = Rack::POST
+  PATCH   = Rack::PATCH
+  PUT     = Rack::PUT
+  DELETE  = Rack::DELETE
+  HEAD    = Rack::HEAD
+  OPTIONS = Rack::OPTIONS
+
+  ##  HTTP headers
+  CONTENT_LENGTH = Rack::CONTENT_LENGTH
+  CONTENT_TYPE   = Rack::CONTENT_TYPE
+
+  LOCATION      = 'Location'.freeze      # not available from Rack
+
 
 module Helpers
     ## add some more helpers
     ##   "inspired" by sinatra (mostly) - for staying compatible
     ##   see https://github.com/sinatra/sinatra/blob/master/lib/sinatra/base.rb
 
-    ## todo -- add redirect/redirect_to
-    ##         add status -- why? why not??
+    ## todo -- add status -- why? why not??
 
     # Halt processing and return the error status provided.
-    def error(code, body=nil)
-      code = 500
-      body = code.to_str if code.respond_to? :to_str
-
+    def error( code, body=nil )
       response.body = body unless body.nil?
       halt code
     end
 
     # Halt processing and return a 404 Not Found.
-    def not_found(body=nil)
+    def not_found( body=nil )
       error 404, body
     end
 
+
+    def redirect_to( uri, status=302 )    ## Note: 302 == Found, 301 == Moved Permanently
+      halt status, { LOCATION => uri }
+    end
+    alias_method :redirect, :redirect_to
+
+
     # Set multiple response headers with Hash.
-    def headers(hash=nil)
+    def headers( hash=nil )
       response.headers.merge! hash if hash
       response.headers
     end
@@ -36,18 +55,18 @@ module Helpers
 
     ## (simple) content_type helper - all "hard-coded" for now; always uses utf-8 too
     def content_type( type=nil )
-      return response['Content-Type'] unless type
+      return response[ CONTENT_TYPE ] unless type
 
       if type.to_sym == :json
-        response['Content-Type'] = 'application/json; charset=utf-8'
+        response[ CONTENT_TYPE ] = 'application/json; charset=utf-8'
       elsif type.to_sym == :js || type.to_sym == :javascript
-        response['Content-Type'] = 'application/javascript; charset=utf-8'
+        response[ CONTENT_TYPE ] = 'application/javascript; charset=utf-8'
         ## use 'text/javascript; charset=utf-8'  -- why? why not??
         ## note: ietf recommends application/javascript
       elsif type.to_sym == :csv || type.to_sym == :text || type.to_sym == :txt
-        response['Content-Type'] = 'text/plain; charset=utf-8'
+        response[ CONTENT_TYPE ] = 'text/plain; charset=utf-8'
       elsif type.to_sym == :html || type.to_sym == :htm
-        response['Content-Type'] = 'text/html; charset=utf-8'
+        response[ CONTENT_TYPE ] = 'text/html; charset=utf-8'
       else
         ### unknown type; do nothing - sorry; issue warning - why? why not??
       end
@@ -58,24 +77,38 @@ end  ## module Helpers
 class Base
   include Helpers
 
+
   class << self
 
+    def call( env )    ## note self.call(env) lets you use =>  run Base instead of run Base.new
+      ## puts "calling #{self.name}.call"
+      prototype.call( env )
+    end
+
+    def prototype
+      ## puts "calling #{self.name}.prototype"
+      @prototype ||= self.new
+      ## pp @prototype
+      ## @prototype
+    end
+
+
     ## todo/check: all verbs needed! (supported) - why, why not??
     ##   e.g. add LINK, UNLINK ??
 
     # Note: for now defining a `GET` handler also automatically defines
     # a `HEAD` handler  (follows sinatra convention)
-    def get( pattern, &block)
-      route( 'GET',   pattern, &block )
-      route( 'HEAD',  pattern, &block )
+    def get( pattern, &block )
+      route( GET,   pattern, &block )
+      route( HEAD,  pattern, &block )
     end
 
-    def post( pattern, &block)    route( 'POST',    pattern, &block ); end
-    def patch( pattern, &block)   route( 'PATCH',   pattern, &block ); end
-    def put( pattern, &block)     route( 'PUT',     pattern, &block ); end
-    def delete( pattern, &block)  route( 'DELETE',  pattern, &block ); end
-    def head( pattern, &block)    route( 'HEAD',    pattern, &block ); end
-    def options( pattern, &block) route( 'OPTIONS', pattern, &block ); end
+    def post( pattern, &block)    route( POST,    pattern, &block ); end
+    def patch( pattern, &block)   route( PATCH,   pattern, &block ); end
+    def put( pattern, &block)     route( PUT,     pattern, &block ); end
+    def delete( pattern, &block)  route( DELETE,  pattern, &block ); end
+    def head( pattern, &block)    route( HEAD,    pattern, &block ); end
+    def options( pattern, &block) route( OPTIONS, pattern, &block ); end
 
     def route( method, pattern, &block )
       puts "[debug] Webservice::Base.#{method.downcase} - add route #{method} '#{pattern}' to #<#{self.name}:#{self.object_id}> : #{self.class.name}"
@@ -93,7 +126,7 @@ class Base
     def environment
       ## include APP_ENV why? why not?
       ##   todo -- cache value? why why not?  (see/follow sinatara set machinery ??)
-      (ENV['RACK_ENV'] || :development).to_sym
+      (ENV['APP_ENV'] || ENV['RACK_ENV'] || :development).to_sym
     end
 
     def development?() environment == :development; end
@@ -104,9 +137,9 @@ class Base
     ## convenience method
     def run!
       puts "[debug] Webservice::Base.run! - self = #<#{self.name}:#{self.object_id}> : #{self.class.name}"  # note: assumes self is class
-      app    = self.new   ## note: use self; will be derived class (e.g. App and not Base)
+      app    = self     ## note: use self; will be derived class (e.g. App and not Base)
       port   = 4567
-      Rack::Handler.get('webrick').run( app, Port:port ) do |server|
+      Rack::Handler::WEBrick.run( app, Port:port ) do |server|
         ## todo: add traps here - why, why not??
       end
     end
@@ -119,25 +152,35 @@ class Base
   attr_reader :params
   attr_reader :env
 
-  def call(env)
-    dup.call!(env)
+  def call( env )
+    dup.call!( env )
   end
 
-  def call!(env)
+  def call!( env )
     env['PATH_INFO'] = '/'  if env['PATH_INFO'].empty?
-    @request   = Rack::Request.new(env)
+
+    @request   = Rack::Request.new( env )
     @response  = Rack::Response.new
     @params    = request.params
     @env       = env
+
+
+    ## (auto-)add (merge in) cors headers
+    ##   todo: move into a before filter ??  lets you overwrite headers - needed - why? why not??
+    headers 'Access-Control-Allow-Origin'  => '*',
+            'Access-Control-Allow-Headers' => 'Authorization,Accepts,Content-Type,X-CSRF-Token,X-Requested-With',
+            'Access-Control-Allow-Methods' => 'GET,POST,PUT,DELETE,OPTIONS'
+
     route_eval
+
     @response.finish
   end
 
 
   def halt( *args )
-    response.status = args.detect{|arg| arg.is_a?(Fixnum) } || 200
-    response.header.merge!(args.detect{|arg| arg.is_a?(Hash) } || {})
-    response.body = [args.detect{|arg| arg.is_a?(String) } || '']
+    response.status = args.detect{ |arg| arg.is_a?(Fixnum) } || 200
+    response.header.merge!( args.detect{ |arg| arg.is_a?(Hash) } || {} )
+    response.body = [args.detect{ |arg| arg.is_a?(String) } || '']
     throw :halt, response
   end
 
@@ -145,57 +188,98 @@ private
 
   def route_eval
     catch(:halt) do
-      self.class.routes[request.request_method].each do |pattern, block|
+      routes = self.class.routes[ request.request_method ]
+      routes.each do |pattern, block|
         ## puts "trying matching route >#{request.path_info}<..."
         url_params = pattern.params( request.path_info )
         if url_params   ## note: params returns nil if no match
           ## puts "  BINGO! url_params: #{url_params.inspect}"
           if !url_params.empty?   ## url_params hash NOT empty (e.g. {}) merge with req params
             ## todo/fix: check merge order - params overwrites url_params - why? why not??
-            @params = url_params.merge( params )
+            @params = url_params.merge( @params )
           end
           handle_response( instance_eval( &block ))
           return
         end
       end
+      # no match found for route/request
       halt 404
     end
   end
 
 
 
-
-  def handle_response( obj )
+  ## todo: add as_json like opts={}  why? why not?
+  def handle_response( obj, opts={} )
     puts "[Webservice::Base#handle_response (#{request.path_info}) params: #{params.inspect}] - obj : #{obj.class.name}"
     pp obj
 
     ## "magic" param format; default to json
     format = params['format'] || 'json'
 
-    if format == 'csv' || format == 'txt'
-      text = generate_csv( obj )
-      content_type :text
-      response.write text
-    elsif format == 'html' || format == 'htm'
-      text = generate_html_table( obj )
-      content_type :html
-      response.write text
+    ## note: response.body must be (expects) an array!!!
+    ##   thus, [json] etc.
+
+    if format == 'csv'  || format == 'txt' ||
+       format == 'html' || format == 'htm'
+
+      data = as_tabular( obj )
+
+      ## note: array required!!!
+      #   array   => multiple records (array of hashes)
+      if data.is_a?( Array )
+        if format == 'csv'  || format == 'txt'
+           content_type :txt   ## use csv content type - why? why not??
+           response.body = [generate_csv( data )]
+        else
+          ## asume html
+          content_type :html
+          response.body = [generate_html_table( data )]
+        end
+      else
+        ## wrong format (expect array of hashes)
+        ##   todo: issue warning/notice about wrong format - how?
+        ##   use different http status code - why? why not??
+        content_type :txt
+        ##  todo/check: use just data.to_s  for all - why? why not?
+        ## for now return as is (convert to string with to_s or inspect)
+        response.body = [data.is_a?( String ) ? data.to_s : data.inspect]
+      end
     else
-      json = generate_json( obj )
+      data = as_json( obj )
+
+      ## note: hash or array required!!! for now for json generation
+      #   hash   => single record
+      #   array  => multiple records (that is, array of hashes)
+
+      if data.is_a?( Hash ) || data.is_a?( Array )
+        json = JSON.pretty_generate( data )   ## use pretty printer
 
-      callback = params.delete('callback')
+        callback = params.delete( 'callback' )
 
-      if callback
-        content_type :js
-        response.write "#{callback}(#{json})"
+        if callback
+          content_type :js
+          response.body = ["#{callback}(#{json})"]
+        else
+          content_type :json
+          response.body = [json]
+        end
       else
-        content_type :json
-        response.write json
+         ## todo/fix/check: change http status to unprocessable entity
+         ##   or something --  why ??? why not??
+         ##
+         ##  allow "standalone" number, nils, strings - why? why not?
+         ##   for now valid json must be wrapped in array [] or hash {}
+         content_type :txt
+         ##  todo/check: use just data.to_s  for all - why? why not?
+         ## for now return as is (convert to string with to_s or inspect)
+         response.body = [data.is_a?( String ) ? data.to_s : data.inspect]
       end
     end
   end  # method handle_response
 
 
+
   def generate_csv( recs )
     ## note: for now assumes (only works with) array of hash records e.g.:
     ## [
@@ -243,14 +327,38 @@ private
   end
 
 
-  def generate_json( obj )
-    if obj.respond_to? :as_json_v2     ## try (our own) serializer first
+  ##########################################
+  ## auto-generate/convert "magic"
+
+  def as_tabular( obj, opts={} )
+    ##  for now allow
+    ##    as_tab, as_tabular  - others too? e.g. as_table why? why not?
+    ##   like as_json will return a hash or array of hashes NOT a string!!!!
+
+    if obj.respond_to? :as_tab
+      obj.as_tab
+    elsif obj.respond_to? :as_tabular
+      obj.as_tabular
+    else
+      ## note: use as_json will return hash (for record) or array of hashes (for records)
+      if obj.respond_to? :as_json
+        obj.as_json
+      else
+        obj   ## just try/use as is (assumes array of hashesd)
+      end
+    end
+  end
+
+
+  def as_json( obj, opts={} )
+    if obj.respond_to? :as_json_v3     ## try (our own) serializer first
+      obj.as_json_v3
+    elsif obj.respond_to? :as_json_v2     ## try (our own) serializer first
       obj.as_json_v2
     elsif obj.respond_to? :as_json     ## try (activerecord) serializer
-      obj.as_json_v2
+      obj.as_json
     else
-      ## just try/use to_json
-      obj.to_json
+      obj   ## just try/use as is
     end
   end
 

data/lib/webservice/version.rb

@@ -1,10 +1,16 @@
 # encoding: utf-8
 
 module Webservice
-  MAJOR = 0    ## todo: namespace inside version or something - why? why not??
-  MINOR = 4
-  PATCH = 0
-  VERSION = [MAJOR,MINOR,PATCH].join('.')
+
+   module Version
+     MAJOR = 0    ## todo: namespace inside version or something - why? why not??
+     MINOR = 5
+     PATCH = 0    ## note: if not put in module will overwrite PATCH (HTTP Verb Constant)!!!
+   end
+
+   VERSION = [Version::MAJOR,
+              Version::MINOR,
+              Version::PATCH].join('.')
 
   def self.version
     VERSION

data/test/service/app.rb

@@ -13,12 +13,10 @@ end
 
 get '/halt/404' do
   halt 404  # 404 - not found
-  ## todo: check why log reports 200-OK (for status code)!!
 end
 
 get '/halt_error' do
   halt 500, "Error fatal"  # 500 - internal server error
-  ## todo: check why log reports 200-OK (for status code)!!
 end
 
 

data/test/test_app.rb

@@ -24,46 +24,46 @@ class TestApp < MiniTest::Test
   def test_get
     get '/'
     assert last_response.ok?
-    assert_equal %q{"Hello World"}, last_response.body
+    assert_equal "Hello World", last_response.body
 
     get '/hello/world'
     assert last_response.ok?
-    assert_equal %q{"Hello world"}, last_response.body
+    assert_equal "Hello world", last_response.body
 
     ##############################
     ## get '/hello/:name'
     get '/hello/ruby'
     assert last_response.ok?
-    assert_equal %q{"Hello ruby"}, last_response.body
+    assert_equal "Hello ruby", last_response.body
 
     get '/hello/ruby?test=t'   ## try w/ extra query string/params
     assert last_response.ok?
-    assert_equal %q{"Hello ruby"}, last_response.body
+    assert_equal "Hello ruby", last_response.body
 
     ##################################
     ## get '/:message/:name'
     get '/servus/wien'
     assert last_response.ok?
-    assert_equal %q{"servus wien"}, last_response.body
+    assert_equal "servus wien", last_response.body
 
     get '/Hallo/Welt'
     assert last_response.ok?
-    assert_equal %q{"Hallo Welt"}, last_response.body
+    assert_equal "Hallo Welt", last_response.body
   end
 
 
   def test_format
     get '/key.format'
     assert last_response.ok?
-    assert_equal %q{"key format"}, last_response.body
+    assert_equal "key format", last_response.body
 
     get '/ottakringer.xxx'
     assert last_response.ok?
-    assert_equal %q{"ottakringer xxx"}, last_response.body
+    assert_equal "ottakringer xxx", last_response.body
 
     get '/ottakringer'
     assert last_response.ok?
-    assert_equal %q{"ottakringer "}, last_response.body
+    assert_equal "ottakringer ", last_response.body
   end
 
 
@@ -85,25 +85,38 @@ CSV
 </table>
 HTML
 
+
+countries_json = <<JSON.strip
+[
+  {
+    "key": "at",
+    "name": "Austria"
+  },
+  {
+    "key": "mx",
+    "name": "Mexico"
+  }
+]
+JSON
+
    get '/countries.json'
    assert last_response.ok?
-   assert_equal %q<[{"key":"at","name":"Austria"},{"key":"mx","name":"Mexico"}]>, last_response.body
+   assert_equal countries_json, last_response.body
 
    get '/countries'
    assert last_response.ok?
-   assert_equal %q<[{"key":"at","name":"Austria"},{"key":"mx","name":"Mexico"}]>, last_response.body
+   assert_equal countries_json, last_response.body
   end  # method test_countries
 
 
+
   def test_halt
-    ## get '/halt/404'
     get '/halt/404'
+    assert_equal 404, last_response.status
 
-    ## get '/halt_error'   - 500, "Error fatal"  # 500 - internal server error
-    get '/halt_error'
-
-    ## todo: check error codes
-    assert true
+    get '/halt_error'   ##  500, "Error fatal"  # 500 - internal server error
+    assert_equal 500,               last_response.status
+    assert_equal "Error fatal", last_response.body
   end
 
 end # class TestApp

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: webservice
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-20 00:00:00.000000000 Z
+date: 2017-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logutils