blix-rest 0.1.30 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1b29a1f9ce5565c28991acebdb11f7a4e785db7760c59905936a9b2e8a6fa72
-  data.tar.gz: 5cc8fc070fb5fc09c3256dbc65b8087e6a17df7ed0bfc80b51fb9bd43ab38609
+  metadata.gz: 5db97b519f38052ee2b7272f3a25d6ec4d5e3ba71cae44bdcd83e25cdd6902f2
+  data.tar.gz: e7fb1c1da94eb622629a718bd81763d6874dc14028bed0ba8328b42cac5c2152
 SHA512:
-  metadata.gz: bf6e866a78e15c268c364b4a87765a05440e1b6f1f6173f442d0a82045fbae4c94df7dcb2afb46c8e27f8ef017f0dea255de9cb85321059f2015f87fc3ee0404
-  data.tar.gz: 7e057e8b9b1dbc9bd1f46b952d071e51fc9d805b5e3236e8c5722902c839106bbece17de8175bcbf66a3ed2159c38121a88ad00d7ef68a94a70384e331e70176
+  metadata.gz: fb48999da4fffe47e1d52cb85319c7ed6473c756a55d6e87edef288a9a118f971c90d709ea73aaf566e1f927a7779056547a91d1cfae71b2cd1a157658c3d2a4
+  data.tar.gz: 93d06074a5b66da9099c1d1bee4fb23a00ac18f994809efb9fb28f0be7d6bf3a889fdad45a2fb349dbabeec6c816c77a34975a8cd7de70efbcce4cff2af1acb2

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,40 @@ 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
+    path               : the request path
+    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 external 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 +269,50 @@ 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.
+
+the verb can not be modified
+
+example:
+
+    class MyController < Blix::Rest::Controller
+
+      before_route do |route|
+        route.default_option(:level,:visitor)
+        route.prefix_path('/app')
+      end
+      ...
+    end
+
+the following methods are available on the route:
+
+    verb                        # readonly, the 'GET','POST' etc verb of the route
+    path                        # the path of the route
+    options                     # the options associated with the route eg :accept
+    path_prefix('/xx')          # ensure the path has the given prefix
+    default_option(:xxx,'foo')  # ensure that option has the given default value
+
 ### Sessions
 
 the following methods are available in the controller for managing sessions.
@@ -266,13 +327,151 @@ this will generate a new session_id and setup the relevant headers
 
 options can include:
 
-    :secure => true    # secure cookies only
-    :http = >true      # cookies for http only not javascript requests
+    :secure => true      # secure cookies only
+    :http = >true        # cookies for http only not javascript requests
     :samesite =>:strict  # use strict x-site policy
     :samesite =>:lax     # use lax x-site policy
 
+For more complete session management:
+
+    class MyController < Blix::Rest::Controller
+      include Blix::Rest::Session
+
+      session_name :xxx               # optional default'blix'
+      session_opts :http=>true        # optional
+      session_manager: MyManager.new  # optional , default Blix::Redis::Store
+
+
+      def myroutine
+        @xxx = session['xxx']
+
+        session['yyy'] = true
+      end
+
+    end
+
+options can include:
+
+    :secure                 # false
+    :http                   # false
+    :samesite               # lax
+    :path                   # '/'
+    :expire_secs            # 30 mins
+    :cleanup_every_secs     # 5 minutes
+    :max_age                # nil
+
+the following methods are available:
+
+    reset_session           # gen new session id
+    session                 # session hash
+    csrf_token              # the session csrf token
+
+route options that affect sessions:
+
+    :nosession=>true        # no session will be set/retrieved
+    :cache=>true            # no session will be set/retrieved
+    :csrf=>true             # request will be validated for calid csrf token.
+                            # token must be in header X_CSRF_TOKEN field
 
+session configuration is inherited from superclass controllers unless overridden.
 
+## 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.
+
+## CORS
+
+cross origin site requests
+
+    MyController < Blix::Rest::Controller
+
+      get '/info/crosssite' do
+        set_accept_cors
+        {:data=>'foo'}
+      end
+
+      options '/info/' crosssite' do
+        set_accept_cors, :headers=>'Content-Type',
+      end
+
+    end
+
+within an `options` response the following parameters can be passes.
+
+    :origin=>'www.othersite.com'            # specify specific allowed origin.
+    :methods => [:get]                      # allowed methods
+    :max_age => 86400                       # maximum age this auth is valid
+    :headers => ['Content-Type','X-OTHER']  # allow additional headers
+    :credentials => true                    # allow requests with credentials
 
 ## Views
 
@@ -362,6 +561,9 @@ NOTE : if you need to set up your database with users then you can use the follo
 
 in features/support/world.rb .........
 
+
+    require 'blix/rest/cucumber'
+
     class RestWorld
 
       # add a hook to create the user in the  database -

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