rocketio 0.0.0 → 0.0.1

data/lib/rocketio/controller/authentication.rb

@@ -0,0 +1,141 @@
+module RocketIO
+  class Controller
+
+    # easily restrict access to controller using basic auth
+    #
+    # @example protect all request methods
+    #   basic_auth do |user,pass|
+    #     user == 'admin' && pass == 'super secret password'
+    #   end
+    #
+    # @example protect only POST, PUT and DELETE request methods
+    #   basic_auth :post, :put, :delete do |user,pass|
+    #     user == 'admin' && pass == 'super secret password'
+    #   end
+    #
+    # @example use different credentials for GET and POST
+    #   basic_auth :get do |user,pass|
+    #     user == 'reader' && pass == 'readPass'
+    #   end
+    #
+    #   basic_auth :post do |user,pass|
+    #     user == 'poster' && pass == 'writePass'
+    #   end
+    #
+    # @note authorization is composable, that's it, if superclass is protecting :get method
+    #       and current controller protects :post method,
+    #       both :get and :post will be protected in current controller
+    #
+    # @params *args [Array]
+    # @param block [Proc]
+    #
+    def self.basic_auth *args, &block
+      opts = args.last.is_a?(Hash) ? args.pop : {}
+      rqms = args.any? ? args.map!(&:to_sym) : RocketIO::REQUEST_METHODS.values
+      rqms.each do |rm|
+        (@__basic_auth__ ||= {})[rm] = {
+          class:     Rack::Auth::Basic,
+          arguments: [opts[:realm] || RocketIO::DEFAULT_AUTH_REALM].freeze,
+          block:     block,
+          mock:      RocketIO::HTTP_AUTHORIZATION_MOCKS[:basic]
+        }.freeze
+      end
+      define_basic_auth_methods
+    end
+
+    def self.define_basic_auth_methods source = self
+      prompts = (source.instance_variable_get(:@__basic_auth__) || {}).each_with_object(allocate.basic_auth.dup) do |(rm,p),o|
+        method = :"__basic_auth__#{rm}__"
+        define_method(method, &p[:block])
+        o[rm] = p.merge(method: method).freeze
+      end.freeze
+      return if prompts.empty?
+      define_method(:basic_auth) {prompts}
+    end
+
+    def basic_auth; RocketIO::EMPTY_HASH end
+
+    # easily restrict access to controller using digest auth
+    #
+    # @example protect all request methods using hashed passwords
+    #    # hash the password somewhere in irb:
+    #    # ::Digest::MD5.hexdigest 'admin:AccessRestricted:somePassword'
+    #    #                   username ^      realm ^       password ^
+    #
+    #    #=> 9d77d54decc22cdcfb670b7b79ee0ef0
+    #
+    #    digest_auth :passwords_hashed => true, :realm => 'AccessRestricted' do |user|
+    #      {'admin' => '9d77d54decc22cdcfb670b7b79ee0ef0'}[user]
+    #    end
+    #
+    # @example protect all request methods using plain passwords
+    #    digest_auth do |user|
+    #      {'admin' => 'password'}[user]
+    #    end
+    #
+    # @example protect only POST, PUT and DELETE request methods
+    #   digest_auth :post, :put, :delete do |user|
+    #     {'admin' => 'password'}[user]
+    #   end
+    #
+    # @example use different credentials for GET and POST
+    #   digest_auth :get do |user|
+    #     {'user' => 'readPass'}[user]
+    #   end
+    #
+    #   digest_auth :post do |user|
+    #     {'poster' => 'writePass'}[user]
+    #   end
+    #
+    # @params *args [Array]
+    # @param block [Proc]
+    #
+    def self.digest_auth *args, &block
+      opts = args.last.is_a?(Hash) ? args.pop : {}
+      opts[:realm]  ||= RocketIO::DEFAULT_AUTH_REALM
+      opts[:opaque] ||= opts[:realm]
+      rqms = args.any? ? args.map!(&:to_sym) : RocketIO::REQUEST_METHODS.values
+      rqms.each do |rm|
+        (@__digest_auth__ ||= {})[rm] = {
+          class:     Rack::Auth::Digest::MD5,
+          arguments: [opts].freeze,
+          block:     block,
+          mock:      RocketIO::HTTP_AUTHORIZATION_MOCKS[:digest]
+        }.freeze
+      end
+      define_digest_auth_methods
+    end
+
+    def self.define_digest_auth_methods source = self
+      prompts = (source.instance_variable_get(:@__digest_auth__) || {}).each_with_object(allocate.digest_auth.dup) do |(rm,p),o|
+        method = :"__digest_auth__#{rm}__"
+        define_method(method, &p[:block])
+        o[rm] = p.merge(method: method).freeze
+      end.freeze
+      return if prompts.empty?
+      define_method(:digest_auth) {prompts}
+    end
+
+    def digest_auth; RocketIO::EMPTY_HASH end
+
+    def user?
+      env[RocketIO::REMOTE_USER]
+    end
+
+    # checks whether authentication is required and
+    # send an authorization request if credentials not present or invalid
+    def validate_or_request_authentication_if_needed
+      return unless auth = digest_auth[requested_method] || basic_auth[requested_method]
+      return unless prompt = auth[:class].new(proc {}, *auth[:arguments]) do |*a|
+        self.__send__(auth[:method], *a)
+      end.call(
+        if RocketIO::HTTP_AUTHORIZATION_KEYS.detect {|key| env.has_key?(key)}
+          env
+        else
+          env.merge(RocketIO::HTTP_AUTHORIZATION_KEYS.first => auth[:mock])
+        end
+      )
+      throw(:__response__, prompt)
+    end
+  end
+end

data/lib/rocketio/controller/authorization.rb

@@ -0,0 +1,53 @@
+require 'rocketio/controller/token_auth'
+
+module RocketIO
+  class Controller
+
+    # easily restrict access to controller using token auth
+    #
+    # @example simple Token example
+    #
+    #   class User < RocketIO::Controller
+    #     token_auth { |token| token == 'secret' }
+    #   end
+    #
+    def self.token_auth *args, &block
+      opts = args.last.is_a?(Hash) ? args.pop : {}
+      (args.any? ? args.map!(&:to_sym) : RocketIO::REQUEST_METHODS.values).each do |rm|
+        (@__token_auth__ ||= {})[rm] = {
+          realm: opts[:realm] || RocketIO::DEFAULT_TOKEN_AUTH_REALM.freeze,
+          block: block
+        }
+      end
+      define_token_auth_methods
+    end
+
+    def self.define_token_auth_methods source = self
+      prompts = allocate.token_auth.merge(source.instance_variable_get(:@__token_auth__) || {}).freeze
+      return if prompts.empty?
+      define_method(:token_auth) {prompts}
+    end
+
+    def token_auth; RocketIO::EMPTY_HASH end
+
+    def validate_or_request_authorization_if_needed
+      return unless auth = token_auth[requested_method]
+      return if validate_token_auth(&auth[:block])
+      throw(:__response__, request_token_auth(auth[:realm]))
+    end
+
+    def validate_or_request_token_auth realm = RocketIO::DEFAULT_TOKEN_AUTH_REALM, &block
+      validate_token_auth(&block) || request_token_auth(realm)
+    end
+
+    def validate_token_auth &block
+      RocketIO::TokenAuth.authenticate(env, &block)
+    end
+    alias valid_token_auth? validate_token_auth
+
+    def request_token_auth realm = RocketIO::DEFAULT_TOKEN_AUTH_REALM
+      RocketIO::TokenAuth.authentication_request(realm)
+    end
+    alias request_token_auth! request_token_auth
+  end
+end

data/lib/rocketio/controller/cookies.rb

@@ -0,0 +1,59 @@
+module RocketIO
+  class Controller
+
+    # shorthand for `request.cookies`, `response.set_cookie` and `response.delete_cookie`
+    #
+    # @example Setting a cookie
+    #   cookies['cookie-name'] = 'value'
+    #
+    # @example Reading a cookie
+    #   cookies['cookie-name']
+    #
+    # @example Setting a cookie with custom options
+    #   cookies['question_of_the_day'] = {
+    #     value: 'who is not who?',
+    #     expires: Date.today + 1,
+    #     secure: true
+    #   }
+    #
+    # @example Deleting a cookie
+    #   cookies.delete('cookie-name')
+    #
+    def cookies
+      @__cookies__ ||= RocketIO::Cookies.new(request.cookies, response)
+    end
+  end
+end
+
+module RocketIO
+  class Cookies
+
+    def initialize cookies, response
+      @cookies  = RocketIO.indifferent_params(cookies)
+      @response = response
+    end
+
+    # set cookie header
+    #
+    # @param [String, Symbol] key
+    # @param [String, Hash] val
+    #
+    def []= key, val
+      @response.set_cookie(key, val)
+    end
+
+    # get cookie by key
+    def [] key
+      @cookies[key]
+    end
+
+    # instruct browser to delete a cookie
+    #
+    # @param [String, Symbol] key
+    # @param [Hash] opts
+    #
+    def delete key, opts ={}
+      @response.delete_cookie(key, opts)
+    end
+  end
+end

data/lib/rocketio/controller/error_handlers.rb

@@ -0,0 +1,89 @@
+module RocketIO
+  class Controller
+
+    # define error handlers
+    #
+    # @example define a handler that will process 404 errors
+    #   class Pages < RocketIO::Controller
+    #
+    #     error 404 do |id|
+    #       "Sorry, looks like item with ID #{id.to_i} does not exists"
+    #     end
+    #
+    #     def get id
+    #       item = Item.find_by(id: id) || error(404, id)
+    #     end
+    #   end
+    #
+    # @example define a handler that will process fatal errors
+    #   class Pages < RocketIO::Controller
+    #
+    #     error 500 do |exception|
+    #       "Fatal error occurred: " + html_escape(exception.message)
+    #     end
+    #
+    #     def get
+    #       # any exception raised here will be handled by the handler above
+    #     end
+    #   end
+    #
+    def self.error code, &block
+      code = code.to_i
+      code > 0 || raise(ArgumentError, 'Error code should be a number')
+      block || raise(ArgumentError, 'block missing')
+      (@__error_handlers__ ||= {})[code] = block
+      define_error_handlers_methods
+    end
+
+    def self.define_error_handlers_methods source = self
+      handlers = (source.instance_variable_get(:@__error_handlers__) || {}).each_with_object({}) do |(code,proc),o|
+        o[code] = :"__#{code}_error_handler__"
+        define_method(o[code], &proc)
+      end
+      handlers.update(allocate.error_handlers)
+      return if handlers.empty?
+      handlers.freeze
+      define_method(:error_handlers) {handlers}
+    end
+
+    def error_handlers; RocketIO::EMPTY_HASH end
+
+    # if there is a handler defined for given code it will be executed and the result used as body.
+    # otherwise the `error` behaves exactly as `halt`.
+    #
+    # given args will be passed either to handler(if any defined) or to `halt`
+    #
+    def error code, *args
+      error_handlers[code] || halt(code, *args)
+      halt(code, __send__(error_handlers[code], *args))
+    end
+    alias error! error
+
+    # 404: Not Found
+    error 404 do
+      RocketIO.error_renderer(404, xhr?, env: env)
+    end
+
+    # 409: Wrong number of arguments received
+    error 409 do
+      RocketIO.error_renderer(409, xhr?, {
+        env: env,
+        controller: self.class,
+        resolved_path: url,
+        expected_parameters: parameters_policy[env[RocketIO::REQUEST_METHOD]],
+        received_parameters: path_params
+      })
+    end
+
+    # 500: Fatal Error
+    error 500 do |error|
+      error = StandardError.new(error) unless Exception === error
+      RocketIO.error_renderer(500, xhr?, env: env, error: error)
+    end
+
+    # 501: Not Implemented
+    error 501 do
+      RocketIO.error_renderer(501, xhr?, env: env)
+    end
+  end
+end

data/lib/rocketio/controller/filters.rb

@@ -0,0 +1,119 @@
+module RocketIO
+  class Controller
+
+    # define blocks to run before, around, after called method.
+    # if no methods given, given block will run on any called method.
+    #
+    # @note call it without a block to define a void filter.
+    #       useful to override inherited filters.
+    #
+    # @note sub-controllers will inherit all filters from parent controller
+    #       and can override them selectively, by name
+    #
+    # @note wildcard filters will run before/around/after any methods,
+    #       that's it, if defining `before {}` and `before(:get) {}` filters
+    #       `get` method will run `before` filter then `before(:get)`
+    #
+    # @example run before any requested method, being it REST or websocket
+    #   before do
+    #     # some logic here
+    #   end
+    #
+    # @example run only before GET
+    #   before :get do
+    #     # some logic here
+    #   end
+    #
+    # @example run only around PUT and POST
+    #   around :put, :post do |app|
+    #     # some logic here
+    #     app.call
+    #   end
+    #
+    # @example run only after :register websocket call
+    #   after :register do
+    #     # some logic here
+    #   end
+    #
+    # @example define a filter that does nothing. useful to override inherited filters.
+    #   before :get
+    #
+    # @example run 2 blocks before GET
+    #   before do  # wildcard filter, will run before any method
+    #     @user = User.find...
+    #   end
+    #
+    #   before :get do  # named filter, will run only before `get`
+    #     # wildcard filter already executed so we have `@user` variable here
+    #     @photo = @user.photos.find...
+    #   end
+    #
+    #   # before calling `get` two filters will be executed:
+    #   # - wildcard one
+    #   # - named one
+    #   def get
+    #     # both @user and @photo variables available here
+    #   end
+    #
+    {
+      before: proc {},
+      around: proc {|app| app.call},
+      after:  proc {}
+    }.each_pair do |filter,default_block|
+      define_methods = :"define_#{filter}_methods"
+      var = :"@__#{filter}_filters__"
+
+      define_singleton_method filter do |*methods,&block|
+        instance_variable_get(var) || instance_variable_set(var, {})
+        methods = [:*] if methods.empty?
+        methods.each do |meth|
+          instance_variable_get(var)[meth.to_sym] = block || default_block
+        end
+        __send__(define_methods)
+      end
+
+      define_singleton_method define_methods do |source = self|
+        filters = (source.instance_variable_get(var) || {}).each_with_object({}) do |(meth,proc),o|
+          o[meth] = :"__#{filter}_#{meth}__"
+          define_method(o[meth], &proc)
+        end
+        filters.update(allocate.__send__(filter))
+        return unless filters.any?
+        filters.freeze
+        define_method(filter) {filters}
+      end
+    end
+
+    def before; RocketIO::EMPTY_HASH end
+    def around; RocketIO::EMPTY_HASH end
+    def after;  RocketIO::EMPTY_HASH end
+
+    def invoke_before_filter method = requested_method
+      __send__(before[:*]) if before[:*]
+      __send__(before[method]) if before[method]
+    end
+
+    # passing blocks somehow tends to add some overhead
+    # so passing the proc as a common argument
+    def invoke_around_filter method = requested_method, block
+      if around[:*]
+        __send__ around[:*], proc {
+          if around[method]
+            __send__(around[method], block)
+          else
+            block.call
+          end
+        }
+      elsif around[method]
+        __send__(around[method], block)
+      else
+        block.call
+      end
+    end
+
+    def invoke_after_filter method = requested_method
+      __send__(after[:*]) if after[:*]
+      __send__(after[method]) if after[method]
+    end
+  end
+end