blix-rest 0.1.30 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1b29a1f9ce5565c28991acebdb11f7a4e785db7760c59905936a9b2e8a6fa72
-  data.tar.gz: 5cc8fc070fb5fc09c3256dbc65b8087e6a17df7ed0bfc80b51fb9bd43ab38609
+  metadata.gz: cf93b3d5836172b6cf1b4ac5df21dfe14e1e998e31e774f9b4fdb4bc5bdec323
+  data.tar.gz: 622db8bf8d0052fd25f3727656ac6b641bc63a2667e97eb3f93f7dc4884e03ee
 SHA512:
-  metadata.gz: bf6e866a78e15c268c364b4a87765a05440e1b6f1f6173f442d0a82045fbae4c94df7dcb2afb46c8e27f8ef017f0dea255de9cb85321059f2015f87fc3ee0404
-  data.tar.gz: 7e057e8b9b1dbc9bd1f46b952d071e51fc9d805b5e3236e8c5722902c839106bbece17de8175bcbf66a3ed2159c38121a88ad00d7ef68a94a70384e331e70176
+  metadata.gz: 32516afd36a4a6c36c81650e50f84970cf2436b7cf682a51cae83d1300f736d4dbfe49d04d590ac8ffde841d2dac7f236d0979b3b5c1d5bec230112584eb6e0d
+  data.tar.gz: 7f106344ec03beb691d5870c5809f379285d578ba17cb9b8edd1ea86c5c64dfa31b0a9747a75adab7730ba514cecca3a508cb36f5560343f147cd64d866ca3d4

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 Clive Andrews
+Copyright (c) 2017-2020 Clive Andrews
 
 
 Permission is hereby granted, free of charge, to any person
@@ -22,4 +22,4 @@ 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.
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -71,7 +71,7 @@ if there is a more specific path then it will be used first :
 ### Path options
 
     :accept     : the format or formats to accept eg: :html or [:png, :jpeg]
-    :default    : default format if not derived through oher means.
+    :default    : default format if not derived through other means.
     :force      : force response into the given format
     :query      : derive format from request query (default: false)
     :extension  : derive format from path extension  (default: true)
@@ -189,10 +189,19 @@ use the following to accept requests in a special format ..
 
     get '/custom', :accept=>:xyz, :force=>:raw do
        add_headers 'Content-Type'=>'text/xyz'
-
        "xyz"
     end
 
+
+Alternatively it is possible to raise a RawResponse:
+
+    add_headers 'Content-Type'=>'text/xyz'
+    raise RawResponse, 'xyz'
+
+or with status and headers:
+
+    raise RawResponse.new('xyz', 123, 'Content-Type'=>'text/xyz')
+
 ## FORMATS
 
 the format of a request is derived from
@@ -218,32 +227,39 @@ base class for controllers. within your block handling a particular route you
 have access to a number of methods
 
 
-    env            : the request environment hash
-    method         : the request method lowercase( 'get'/'post' ..)
-    req            : the rack request
-    body           : the request body as a string
-    query_params   : a hash of parameters as passed in the url as parameters
-    path_params    : a hash of parameters constructed from variable parts of the path
-    post_params    : a hash of parameters passed in the body of the request
-    params         : all the params combined
-    user           : the user making this request ( or nil if
-    format         : the format the response should be in :json or :html
-    before         : before hook ( opts ) - remember to add 'super' as first line !!!
-    after          : after hook (opts,response)- remember to add 'super' as first line !!!
-    proxy          : forward the call to another service (service,path, opts={}) , :include_query=>true/false
-    session        : req.session
-    redirect       : (path, status=302) redirect to another url.
-    request_ip     : the ip of the request
-    render_erb     : (template_name [,:layout=>name])
-    path_for       : (path) give the correct path for an internal path
-    url_for        : (path) give the full url for an internal path
-    h              : escape html string to avoid XSS
-    escape_javascript : escape  a javascript string
-    server_options : options as passed to server at create time
-    mode_test?        : test mode ?
-    mode_production?  : production mode ?
-    mode_development? : development mode?
-
+    env                : the request environment hash
+    method             : the request method lowercase( 'get'/'post' ..)
+    req                : the rack request
+    body               : the request body as a string
+    query_params       : a hash of parameters as passed in the url as parameters
+    path_params        : a hash of parameters constructed from variable parts of the path
+    post_params        : a hash of parameters passed in the body of the request
+    params             : all the params combined
+    user               : the user making this request ( or nil if
+    format             : the format the response should be in :json or :html
+    before             : before hook ( opts ) - remember to add 'super' as first line !!!
+    after              : after hook (opts,response)- remember to add 'super' as first line !!!
+    proxy              : forward the call to another service (service,path, opts={}) , :include_query=>true/false
+    session            : req.session
+    redirect           : (path, status=302) redirect to another url.
+    request_ip         : the ip of the request
+    render_erb         : (template_name [,:layout=>name])
+    server_cache       : get the server cache object
+    server_cache_get   : retrieve/store value in cache
+    path_for           : (path) give the correct path for an internal path
+    url_for            : (path) give the full url for an internal path
+    h                  : escape html string to avoid XSS
+    escape_javascript  : escape  a javascript string
+    server_options     : options as passed to server at create time
+    logger             : system logger
+    mode_test?         : test mode ?
+    mode_production?   : production mode ?
+    mode_development?  : development mode?
+    send_data          : send raw data (data, options )
+                            [:type=>mimetype]
+                            [:filename=>name]
+                            [:disposition=>inline|attachment]
+                            [:status=>234]
 
     get_session_id(session_name, opts={}) :
     refresh_session_id(session_name, opts={}) :
@@ -252,6 +268,45 @@ to accept requests other than json then set `:accept=>[:json,:html]` as options
 
 eg  `post '/myform' :accept=>[:html]      # this will only accept html requests.`
 
+### Hooks
+
+a before or after hook can be defined on a controller. Only define the hook once
+for a given controller per source file. A hook included from another source file
+is ok though.
+
+    class MyController < Blix::Rest::Controller
+
+      before do
+        ...
+      end
+
+      after do
+        ...
+      end
+
+    end
+
+
+#### manipulate the route path or options
+
+the `before_route` hook can be used to modify the path or options of a route.
+
+*NOTE* ! when manipulating the path you have to modify the string object in place.
+
+the verb can not be modified
+
+example:
+
+    class MyController < Blix::Rest::Controller
+
+      before_route do |verb, path, opts|
+        opts[:level] = :visitor unless opts[:level]
+        path.prepend('/') unless path[0] == '/'
+        path.prepend('/app') unless path[0, 4] == '/app'
+      end
+      ...
+    end
+
 ### Sessions
 
 the following methods are available in the controller for managing sessions.
@@ -272,7 +327,78 @@ options can include:
     :samesite =>:lax     # use lax x-site policy
 
 
+## Cache
+
+
+the server has a cache which can also be used for storing your own data.
+
+within a controller access the controller with `server_cache` which returns the
+cache object.
+
+cache object methods:
+
+    get(key)        # return value from the cache or nil
+    set(key,value)  # set a value in the cache
+    key?(key)       # is a key present in the cache
+    delete(key)     # delete a key from the cache
+    clear           # delete all keys from the cache.
+
+there is also a `server_cache_get` method.
+
+    server_cache_get(key){ action }
+
+get the value from the cache. If the key is missing in the cache then perform
+the action in the provided block and store the result in the cache.
+
+the default cache is just a ruby hash in memory. Pass a custom cache to
+when creating a server with the `:cache` parameter.
+
+    class MyCache < Blix::Rest::Cache
+       def get(key)
+          ..
+       end
+
+       def set(key,value)
+         ..
+       end
+
+       def key?(key)
+        ..
+       end
+
+       def delete(key)
+         ..
+       end
+
+       def clear
+         ..
+       end
+     end
+
+     cache = MyCache.new
+
+     app = Blix::Rest::Server.new(:cache=>cache)
+
+there is a redis cache already defined:
+
+    require 'blix/rest/redis_cache'
+
+    cache = Blix::Rest::RedisCache.new(:expire_secs=>60*60*24) # expire after 1 day
+    run Blix::Rest::Server.new(:cache=>cache)
+
+
+### automatically cache server responses
+
+add  `:cache=>true` to your route options in order to cache this route.
+
+add `:cache_reset=>true` to your route options if the cache should be cleared when
+calling this route.
+
+the cache is not used in development/testmode , only in production mode.
+
+### IMPORTANT - DO NOT CACHE SESSION KEYS AND OTHER SPECIFIC DATA IN CACHE
 
+only cache pages with **HEADERS** and **CONTENT** that is not user specific.
 
 ## Views
 

data/lib/blix/rest/cache.rb

@@ -0,0 +1,79 @@
+module Blix::Rest
+
+  # cache server responses
+  class Cache
+
+    attr_reader :params
+
+    def initialize(params={})
+      @params = params
+    end
+
+    def [](key)
+      get(key)
+    end
+
+    def []=(key,data)
+      set(key, data)
+    end
+
+    #--------------- redefine these methods ..
+
+    # clear all data from the cache
+    def clear
+
+    end
+
+    # retrieve data from the cache
+    def get(key)
+
+    end
+
+   # set data in the cache
+    def set(key, data)
+
+    end
+
+    #  is key present in the cache
+    def key?(key)
+
+    end
+
+    def delete(key)
+
+    end
+
+    #---------------------------------------------------------------------------
+
+
+  end
+
+  # implement cache as a simple ruby hash
+  class MemoryCache < Cache
+
+    def cache
+      @cache ||= {}
+    end
+
+    def get(key)
+      cache[key]
+    end
+
+    def set(key, data)
+      cache[key] = data
+    end
+
+    def clear
+      cache.clear
+    end
+
+    def key?(key)
+      cache.key?(key)
+    end
+
+    def delete(key)
+      cache.delete(key)
+    end
+
+  end
+end

data/lib/blix/rest/controller.rb

@@ -3,6 +3,7 @@
 require 'base64'
 require 'erb'
 require 'securerandom'
+require 'digest'
 
 module Blix::Rest
   # base class for controllers. within your block handling a particular route you
@@ -21,8 +22,19 @@ module Blix::Rest
   #  to accept requests other thatn json then set :accept=>[:json,:html] as options in the route
   #    eg  post '/myform' :accept=>[:html]              # this will only accept html requests.
 
+  Context = Struct.new(
+    :path_params,
+    :params,
+    :req,
+    :format,
+    :response,
+    :method,
+    :server
+  )
+
   class Controller
 
+
     #--------------------------------------------------------------------------------------------------------
     # convenience methods
     #--------------------------------------------------------------------------------------------------------
@@ -35,6 +47,14 @@ module Blix::Rest
       @_server_options
     end
 
+    def server_cache
+      @_server_cache
+    end
+
+    def server_cache_get(key)
+      server_cache[key] ||= yield if block_given?
+    end
+
     def logger
       Blix::Rest.logger
     end
@@ -60,8 +80,18 @@ module Blix::Rest
       #      env['rack.input'].rewindreq.POST #env["body"]
     end
 
+    # ovverride the path method to return the internal path.
     def path
-      req.path
+      p = req.path
+      p = '/' + p if p[0, 1] != '/' # ensure a leading slash on path
+      idx = RequestMapper.path_root_length
+      if idx > 0
+        p = p[idx..-1] || '/'
+        p = '/' + p if p[0, 1] != '/' # ensure a leading slash on path
+        p
+      else
+        p
+      end
     end
 
     def form_hash
@@ -113,7 +143,7 @@ module Blix::Rest
     end
 
     def path_for(path)
-      File.join(RequestMapper.path_root, path)
+      File.join(RequestMapper.path_root, path || '')
     end
 
     def url_for(path)
@@ -128,6 +158,18 @@ module Blix::Rest
       @_verb
     end
 
+    def method
+      @_method
+    end
+
+    def route_parameters
+      @_parameters
+    end
+
+    def response
+      @_response
+    end
+
     def method
       env['REQUEST_METHOD'].downcase
     end
@@ -147,7 +189,7 @@ module Blix::Rest
     end
 
     def redirect(path, status = 302)
-      raise ServiceError.new(nil, status, 'Location' => path)
+      raise ServiceError.new(nil, status, 'location' => RequestMapper.ensure_full_path(path))
     end
 
     alias redirect_to redirect
@@ -191,11 +233,11 @@ module Blix::Rest
     end
 
     def set_status(value)
-      @_response.status = value
+      @_response.status = value.to_i
     end
 
     def add_headers(headers)
-      @_response.headers.merge!(headers)
+      @_response.headers.merge!(headers.map{|k,v| [k.to_s.downcase,v]}.to_h)
     end
 
     # the following is copied from Rack::Utils
@@ -231,6 +273,19 @@ module Blix::Rest
       raise ServiceError.new(message, status, headers)
     end
 
+    # send data to browser as attachment
+    def send_data(data, opts = {})
+      add_headers 'content-type'=> opts[:type] || 'application/octet-stream'
+      if opts[:filename]
+        add_headers 'content-disposition'=>'attachment;filename='+ opts[:filename]
+      elsif opts[:disposition] == 'attachment'
+        add_headers 'content-disposition'=>'attachment'
+      elsif opts[:disposition] == 'inline'
+        add_headers 'content-disposition'=>'inline'
+      end
+      raise RawResponse.new(data, opts[:status] || 200)
+    end
+
     def auth_error(*params)
       if params[0].kind_of?(String)
           message = params[0]
@@ -279,7 +334,7 @@ module Blix::Rest
       # else
       #   cookie_header = cookie_text
       # end
-      @_response.headers['Set-Cookie'] = @_cookies.values.join("\n")
+      @_response.headers['set-cookie'] = @_cookies.values.join("\n")
       value
     end
 
@@ -315,6 +370,16 @@ module Blix::Rest
       store_cookie(session_name, session_id, opts)
     end
 
+    # perform the before hooks.
+    def __before(*a)
+      self.class._do_before(self, *a)
+    end
+
+    # perform the after hooks
+    def __after(*a)
+      self.class._do_after(self, *a)
+    end
+
     #----------------------------------------------------------------------------------------------------------
     # template methods that can be overwritten
 
@@ -329,15 +394,27 @@ module Blix::Rest
 
     #----------------------------------------------------------------------------------------------------------
 
-    def initialize(path_params, _params, req, format, verb, response, server_options)
-      @_req = req
-      @_env = req.env
+    def _setup(context, _verb, _path, _parameters)
+      @_context        = context
+      @_req            = context.req
+      @_env            = req.env
       @_query_params = StringHash.new(req.GET)
-      @_path_params  = StringHash.new(path_params)
-      @_format = format
-      @_verb = verb
-      @_response = response
-      @_server_options = server_options
+      @_path_params  = StringHash.new(context.path_params)
+      @_format         = context.format
+      @_verb           = _verb
+      @_response       = context.response
+      @_server_options = context.server._options
+      @_parameters     = _parameters
+      @_server_cache   = context.server._cache
+      @_method         = context.method
+    end
+
+    def to_s
+      "<#{self.class.to_s}:#{object_id}>"
+    end
+
+    def inspect
+      to_s
     end
 
     # do not cache templates in development mode
@@ -376,9 +453,9 @@ module Blix::Rest
         path        = opts[:path] || __erb_path || Controller.erb_root
 
         layout = layout_name && if no_template_cache
-                                  ERB.new(File.read(File.join(path, layout_name + '.html.erb')),nil,'-')
+                                  ERB.new(File.read(File.join(path, layout_name + '.html.erb')),:trim_mode=>'-')
                                 else
-                                  erb_templates[layout_name] ||= ERB.new(File.read(File.join(path, layout_name + '.html.erb')),nil,'-')
+                                  erb_templates[layout_name] ||= ERB.new(File.read(File.join(path, layout_name + '.html.erb')),:trim_mode=>'-')
         end
 
         begin
@@ -388,8 +465,8 @@ module Blix::Rest
             text
           end
         rescue Exception
-          puts $!
-          puts $@
+          ::Blix::Rest.logger <<  $!
+          ::Blix::Rest.logger <<  $@
           '*** TEMPLATE ERROR ***'
         end
       end
@@ -401,15 +478,15 @@ module Blix::Rest
         path        = opts[:erb_dir] || __erb_path || Controller.erb_root
 
         layout = layout_name && if no_template_cache
-                                  ERB.new(File.read(File.join(path, layout_name + '.html.erb')),nil,'-')
+                                  ERB.new(File.read(File.join(path, layout_name + '.html.erb')),:trim_mode=>'-')
                                 else
-                                  erb_templates[layout_name] ||= ERB.new(File.read(File.join(path, layout_name + '.html.erb')),nil,'-')
+                                  erb_templates[layout_name] ||= ERB.new(File.read(File.join(path, layout_name + '.html.erb')),:trim_mode=>'-')
         end
 
         erb = if no_template_cache
-                ERB.new(File.read(File.join(path, name + '.html.erb')),nil,'-')
+                ERB.new(File.read(File.join(path, name + '.html.erb')),:trim_mode=>'-')
               else
-                erb_templates[name] ||= ERB.new(File.read(File.join(path, name + '.html.erb')),nil,'-')
+                erb_templates[name] ||= ERB.new(File.read(File.join(path, name + '.html.erb')),:trim_mode=>'-')
         end
 
         begin
@@ -421,8 +498,8 @@ module Blix::Rest
             erb.result(bind)
           end
         rescue Exception
-          puts $!
-          puts $@
+          ::Blix::Rest.logger <<  $!
+          ::Blix::Rest.logger <<  $@
           '*** TEMPLATE ERROR ***'
         end
       end
@@ -447,19 +524,32 @@ module Blix::Rest
         raise ServiceError, 'invalid format for this request' unless accept.index format
       end
 
+      def _do_route_hook(verb, path, opts)
+        if @_route_hook
+          superclass._do_route_hook(verb, path, opts) if superclass.respond_to? :_do_route_hook
+          @_route_hook.call(verb, path, opts)
+        end
+      end
+
       def route(verb, path, opts = {}, &blk)
-        proc = lambda do |_path_params, _params, _req, _format, _response, server_options|
+        path = String.new(path)  # in case frozen.
+        _do_route_hook(verb.dup, path, opts)
+        proc = lambda do |context|
           unless opts[:force] && (opts[:accept] == :*)
-            check_format(opts[:accept], _format)
+            check_format(opts[:accept], context.format)
           end
-          app = new(_path_params, _params, _req, _format, verb, _response, server_options)
+          app = new
+          app._setup(context, verb, path, opts)
           begin
             app.before(opts)
-            response = app.instance_eval( &blk )
+            app.__before
+            context.response = app.instance_eval( &blk )
           rescue
             raise
           ensure
-            app.after(opts, response)
+            app.__after
+            app.after(opts, context.response)
+            context.response
           end
         end
 
@@ -498,6 +588,49 @@ module Blix::Rest
         route 'OPTIONS', *a, &b
       end
 
+      def before_route(&b)
+        @_route_hook = b if b
+      end
+
+
+      def _before_hooks
+        @_before_hooks ||= {}
+      end
+
+      def _after_hooks
+        @_after_hooks ||= {}
+      end
+
+      def _do_before(ctx, *a)
+        superclass._do_before(ctx, *a) if superclass.respond_to? :_do_before
+        _before_hooks.each_value{ |h| ctx.instance_eval(&h) }
+      end
+
+      def _do_after(ctx, *a)
+        _after_hooks.each_value{ |h| ctx.instance_eval(&h) }
+        superclass._do_after(ctx, *a) if superclass.respond_to? :_do_after
+      end
+
+      # define a before hook for a controller. only one hook can be defined per
+      # controller in a single source file.
+      def before(&block)
+        if block
+          file = block.source_location[0]
+          warn("warning: before hook already defined in #{file}") if _before_hooks[file]
+          _before_hooks[file] = block
+        end
+      end
+
+      # define an after hook for a controller. only one hook can be defined per
+      # controller in a single source file.
+      def after(&block)
+        if block
+          file = block.source_location[0]
+          warn("warning: after hook already defined in #{file}") if _after_hooks[file]
+          _after_hooks[file] = block
+        end
+      end
+
     end
 
   end