plezi 0.7.0

data/lib/plezi/base/events.rb

@@ -0,0 +1,84 @@
+
+module Plezi
+
+	module_function
+
+	#######################
+	## Events (Callbacks) / Multi-tasking Platform
+
+	# DANGER ZONE - Plezi Engine. an Array containing all the shutdown callbacks that need to be called.
+	SHUTDOWN_CALLBACKS = []
+	# DANGER ZONE - Plezi Engine. an Array containing all the current events.
+	EVENTS = []
+	# DANGER ZONE - Plezi Engine. the Mutex locker for the event machine.
+	LOCKER = Mutex.new
+
+	# returns true if there are any unhandled events
+	def events?
+		LOCKER.synchronize {!EVENTS.empty?}
+	end
+
+	# Public API. pushes an event to the event's stack
+	#
+	# accepts:
+	# handler:: an object that answers to `call`, usually a Proc or a method.
+	# *arg:: any arguments that will be passed to the handler's `call` method.
+	#
+	# if a block is passed along, it will be used as a callback: the block will be called with the values returned by the handler's `call` method.
+	def push_event handler, *args, &block
+		if block
+			LOCKER.synchronize {EVENTS << [(Proc.new {|a| Plezi.push_event block, handler.call(*a)} ), args]}
+		else
+			LOCKER.synchronize {EVENTS << [handler, args]}
+		end
+	end
+
+	# Public API. creates an asynchronous call to a method, with an optional callback:
+	# demo use:
+	# `callback( Kernel, :sleep, 1 ) { puts "this is a demo" }`
+	# callback sets an asynchronous method call with a callback.
+	#
+	# paramaters:
+	# object:: the object holding the method to be called (use `Kernel` for global methods).
+	# method:: the method's name (Symbol). this is the method that will be called.
+	# *arguments:: any additional arguments that should be sent to the method (the main method, not the callback).
+	#
+	# this method also accepts an optional block (the callback) that will be called once the main method has completed.
+	# the block will recieve the method's returned value.
+	#
+	# i.e.
+	#    puts 'while we wait for my work to complete, can you tell me your name?'
+	#    Plezi.callback(STDIO, :gets) do |name|
+	#         puts "thank you, #{name}. I'm working on your request as we speak."
+	#    end
+	#    # do more work without waiting for the chat to start nor complete.
+	def callback object, method, *args, &block
+		push_event object.method(method), *args, &block
+	end
+
+	# Public API. adds a callback to be called once the services were shut down. see: callback for more info.
+	def on_shutdown object=nil, method=nil, *args, &block
+		if block && !object && !method
+			LOCKER.synchronize {SHUTDOWN_CALLBACKS << [block, args]}
+		elsif block
+			LOCKER.synchronize {SHUTDOWN_CALLBACKS << [(Proc.new {|*a| block.call(object.method(method).call(*a))} ), args]}
+		elsif object && method
+			LOCKER.synchronize {SHUTDOWN_CALLBACKS << [object.method(method), args]}
+		end
+	end
+
+	# Plezi Engine, DO NOT CALL. pulls an event from the event's stack and processes it.
+	def fire_event
+		event = LOCKER.synchronize {EVENTS.shift}
+		return false unless event
+		begin
+			event[0].call(*event[1])
+		rescue OpenSSL::SSL::SSLError => e
+			warn "SSL Bump - SSL Certificate refused?"
+		rescue Exception => e
+			raise if e.is_a?(SignalException) || e.is_a?(SystemExit)
+			error e
+		end
+		true
+	end
+end

data/lib/plezi/base/io_reactor.rb

@@ -0,0 +1,41 @@
+
+module Plezi
+
+	module_function
+
+
+	# DANGER ZONE - Plezi Engine. the io reactor mutex
+	IO_LOCKER = Mutex.new
+
+	# Plezi Engine, DO NOT CALL. waits on IO and pushes events. all threads hang while reactor is active (unless events are already 'in the pipe'.)
+	def io_reactor
+		IO_LOCKER.synchronize do
+			return false unless EVENTS.empty?
+			united = SERVICES.keys + IO_CONNECTION_DIC.keys
+			return false if united.empty?
+			io_r = (IO.select(united, nil, united, idle_sleep) ) #rescue false)
+			if io_r
+				io_r[0].each do |io|
+					if SERVICES[io]
+						begin
+							connection = io.accept_nonblock
+							callback Plezi, :add_connection, connection, SERVICES[io]
+						rescue Errno::EWOULDBLOCK => e
+
+						rescue Exception => e
+							error e
+							# SERVICES.delete s if s.closed?
+						end
+					elsif IO_CONNECTION_DIC[io]
+						callback(IO_CONNECTION_DIC[io], :on_message)
+					else
+						IO_CONNECTION_DIC.delete(io)
+						SERVICES.delete(io)
+					end
+				end
+				io_r[2].each { |io| (IO_CONNECTION_DIC.delete(io) || SERVICES.delete(io)).close rescue true }
+			end
+		end
+		true
+	end
+end

data/lib/plezi/base/logging.rb

@@ -0,0 +1,62 @@
+
+module Plezi
+
+	#######################
+	## Logging
+	module_function
+
+	# the logger object
+	@logger = ::Logger.new(STDOUT)
+
+	# gets the active logger
+	def logger
+		@logger
+	end
+	# gets the active STDOUT copy, if exists
+	def logger_copy
+		@copy_to_stdout
+	end
+
+	# create and set the logger object. accepts:
+	# log_file:: a log file name to be used for logging
+	# copy_to_stdout:: if false, log will only log to file. defaults to true.
+	def create_logger log_file = STDOUT, copy_to_stdout = false
+		@copy_to_stdout = false
+		@copy_to_stdout = ::Logger.new(STDOUT) if copy_to_stdout
+		@logger = ::Logger.new(log_file)
+		@logger
+	end
+	alias :set_logger :create_logger
+
+	# writes a raw line to the log\
+	def log_raw line
+		@logger << line
+		@copy_to_stdout << line if @copy_to_stdout
+	end
+
+	# logs info
+	def log line
+		@logger.info line
+		@copy_to_stdout.info line if @copy_to_stdout
+	end
+	# logs info
+	def info line
+		@logger.info line
+		@copy_to_stdout.info line if @copy_to_stdout
+	end
+	# logs warning
+	def warn line
+		@logger.warn line
+		@copy_to_stdout.warn line if @copy_to_stdout
+	end
+	# logs errors
+	def error line
+		@logger.error line
+		@copy_to_stdout.error line if @copy_to_stdout
+	end
+	# logs a fatal error
+	def fatal line
+		@logger.fatal line
+		@copy_to_stdout.fatal line if @copy_to_stdout
+	end
+end

data/lib/plezi/base/rack_app.rb

@@ -0,0 +1,89 @@
+
+module Plezi
+
+	# Rack application model support
+	module_function
+
+	# todo: move falsh into the special cookie class...?
+	
+
+	# Plezi dresses up for Rack - this is a watered down version missing some features (such as flash and WebSockets).
+	# a full featured Plezi app, with WebSockets, requires the use of the Plezi server
+	# (the built-in server)
+	def call env
+		raise "No Plezi Services" unless Plezi::SERVICES[0]
+		Object.const_set('PLEZI_ON_RACK', true) unless defined? PLEZI_ON_RACK
+
+		# re-encode to utf-8, as it's all BINARY encoding at first
+		env["rack.input"].rewind
+		env['rack.input'] = StringIO.new env["rack.input"].read.encode("utf-8", "binary", invalid: :replace, undef: :replace, replace: '')		 	
+		env.each do |k, v|
+			if k.to_s.match /^[A-Z]/
+				if v.is_a?(String) && !v.frozen?
+					v.force_encoding("binary").encode!("utf-8", "binary", invalid: :replace, undef: :replace, replace: '') unless v.force_encoding("utf-8").valid_encoding?
+				end
+			end
+		end
+		# re-key params
+		# new_params = {}
+		# env[:params].each {|k,v| HTTP.add_param_to_hash k, v, new_params}
+		# env[:params] = new_params
+
+		# make hashes magical
+		make_hash_accept_symbols(env)
+
+		# use Plezi Cookies
+		env["rack.request.cookie_string"] = env["HTTP_COOKIE"]
+		env["rack.request.cookie_hash"] = Plezi::Cookies.new.update(env["rack.request.cookie_hash"] || {})
+
+		# chomp path
+		env["PATH_INFO"].chomp! '/'
+
+		# get response
+		response = Plezi::SERVICES[0][1][:handler].call env
+
+		return response if response.is_a?(Array)
+
+		response.finish
+		response.fix_headers
+		headers = response.headers
+		# set cookie headers
+		headers.delete 'transfer-encoding'
+		headers.delete 'connection'
+		unless response.cookies.empty?
+			headers["Set-Cookie"] = []
+			response.cookies.each {|k,v| headers["Set-Cookie"] << ("#{k.to_s}=#{v.to_s}")}
+		end
+		[response.status, headers, response.body]
+	end
+end
+
+# # rack code to set cookie headers
+# # File actionpack/lib/action_controller/vendor/rack-1.0/rack/response.rb, line 56
+#     def set_cookie(key, value)
+#       case value
+#       when Hash
+#         domain  = "; domain="  + value[:domain]    if value[:domain]
+#         path    = "; path="    + value[:path]      if value[:path]
+#         # According to RFC 2109, we need dashes here.
+#         # N.B.: cgi.rb uses spaces...
+#         expires = "; expires=" + value[:expires].clone.gmtime.
+#           strftime("%a, %d-%b-%Y %H:%M:%S GMT")    if value[:expires]
+#         secure = "; secure"  if value[:secure]
+#         httponly = "; HttpOnly" if value[:httponly]
+#         value = value[:value]
+#       end
+#       value = [value]  unless Array === value
+#       cookie = Utils.escape(key) + "=" +
+#         value.map { |v| Utils.escape v }.join("&") +
+#         "#{domain}#{path}#{expires}#{secure}#{httponly}"
+
+#       case self["Set-Cookie"]
+#       when Array
+#         self["Set-Cookie"] << cookie
+#       when String
+#         self["Set-Cookie"] = [self["Set-Cookie"], cookie]
+#       when nil
+#         self["Set-Cookie"] = cookie
+#       end
+#     end

data/lib/plezi/base/services.rb

@@ -0,0 +1,57 @@
+
+module Plezi
+
+	module_function
+
+	#######################
+	## Services pooling and calling
+
+	# DANGER ZONE - Plezi Engine. the services store
+	SERVICES = {}
+	# DANGER ZONE - Plezi Engine. the services mutex
+	S_LOCKER = Mutex.new
+
+	# public API to add a service to the framework.
+	# accepts:
+	# port:: port number
+	# parameters:: a hash of paramaters that are passed on to the service for handling (and from there, service dependent, to the protocol and/or handler).
+	#
+	# parameters are any of the following:
+	# host:: the host name. defaults to any host not explicitly defined (a catch-all).
+	# alias:: a String or an Array of Strings which represent alternative host names (i.e. `alias: ["admin.google.com", "admin.gmail.com"]`).
+	# root:: the public root folder. if this is defined, static files will be served from the location.
+	# assets:: the assets root folder. defaults to nil (no assets support). if the path is defined, assets will be served from `/assets/...` (or the public_asset path defined) before any static files. assets will not be served if the file in the /public/assets folder if up to date (a rendering attempt will be made for systems that allow file writing).
+	# assets_public:: the assets public uri location (uri format, NOT a file path). defaults to `/assets`. assets will be saved (or rendered) to the assets public folder and served as static files.
+	# assets_callback:: a method that accepts one parameters: `request` and renders any custom assets. the method should return `false` unless it has created a response object (`response = Plezi::HTTPResponse.new(request)`) and sent a response to the client using `response.finish`.
+	# save_assets:: saves the rendered assets to the filesystem, under the public folder. defaults to false.
+	# templates:: the templates root folder. defaults to nil (no template support). templates can be rendered by a Controller class, using the `render` method.
+	# ssl:: if true, an SSL service will be attempted. if no certificate is defined, an attempt will be made to create a self signed certificate.
+	# ssl_key:: the public key for the SSL service.
+	# ssl_cert:: the certificate for the SSL service.
+	#
+	#
+	# assets:
+	#
+	# assets support will render `.sass`, `.scss` and `.coffee` and save them as local files (`.css`, `.css`, and `.js` respectively) before sending them as static files. if it is impossible to write the files, they will be rendered dynamically for every request (it would be better to render them before-hand).
+	#
+	# templates:
+	#
+	# templates can be either an ERB file on a Haml file.
+	#
+	def add_service port, paramaters = {}
+		paramaters[:port] ||= port
+		paramaters[:service_type] ||= ( paramaters[:ssl] ? SSLService : BasicService)
+		service = nil
+		service = paramaters[:service_type].create_service(port, paramaters) unless ( defined?(BUILDING_PLEZI_TEMPLATE) || defined?(PLEZI_ON_RACK) )
+		S_LOCKER.synchronize {SERVICES[service] = paramaters}
+		info "Started listening on port #{port}."
+		true
+	end
+
+	# Plezi Engine, DO NOT CALL. stops all services - active connection will remain open until completion.
+	def stop_services
+		info 'Stopping services'
+		S_LOCKER.synchronize {SERVICES.each {|s, p| s.close rescue true; info "Stoped listening on port #{p[:port]}"}; SERVICES.clear }
+	end
+
+end

data/lib/plezi/base/timers.rb

@@ -0,0 +1,71 @@
+
+module Plezi
+
+	module_function
+
+	#######################
+	## Timed Events / Multi-tasking
+
+	# DANGER ZONE - Plezi Engine. an Array containing all the current events.
+	TIMERS = []
+	# DANGER ZONE - Plezi Engine. the Mutex locker for the event machine.
+	T_LOCKER = Mutex.new
+
+	# This class is used by Plezi to hold events and push them into the events stack when the time comes.
+	class TimedEvent
+
+		def initialize seconds, repeat, handler, args, block
+			@time = Time.now + seconds
+			@seconds, @repeat, @handler, @args, @block  = seconds, repeat, handler, args, block
+		end
+
+		def done?
+			return false unless @time <= Time.now
+			Plezi.push_event @handler, *@args, &@block
+			return true unless @repeat
+			@time = Time.now + @seconds
+			false
+		end
+
+		def stop_repeat
+			@repeat = false
+		end
+
+		attr_reader :timed
+	end
+
+	# returns true if there are any unhandled events
+	def timers?
+		T_LOCKER.synchronize {!TIMERS.empty?}
+	end
+
+	# pushes a timed event to the timers's stack
+	#
+	# accepts:
+	# seconds:: the minimal amount of seconds to wait before calling the handler's `call` method.
+	# handler:: an object that answers to `call`, usually a Proc or a method.
+	# *arg:: any arguments that will be passed to the handler's `call` method.
+	#
+	# if a block is passed along, it will be used as a callback: the block will be called with the values returned by the handler's `call` method.
+	def run_after seconds, handler, *args, &block
+		T_LOCKER.synchronize {TIMERS << TimedEvent.new(seconds, false, handler, args, block); TIMERS.last}
+	end
+
+	# pushes a repeated timed event to the timers's stack
+	#
+	# accepts:
+	# seconds:: the minimal amount of seconds to wait before calling the handler's `call` method.
+	# handler:: an object that answers to `call`, usually a Proc or a method.
+	# *arg:: any arguments that will be passed to the handler's `call` method.
+	#
+	# if a block is passed along, it will be used as a callback: the block will be called with the values returned by the handler's `call` method.
+	def run_every seconds, handler, *args, &block
+		T_LOCKER.synchronize {TIMERS << TimedEvent.new(seconds, true, handler, args, block); TIMERS.last}
+	end
+
+	# DANGER ZONE - Used by the Plezi engine to review timed events and push them to the event stack
+	def fire_timers
+		return false if T_LOCKER.locked?
+		T_LOCKER.synchronize { TIMERS.delete_if {|t| t.done? } }
+	end
+end

data/lib/plezi/handlers/controller_magic.rb

@@ -0,0 +1,383 @@
+module Plezi
+
+	# the methods defined in this module will be injected into the Controller class passed to
+	# Plezi (using the `route` or `shared_route` commands), and will be available
+	# for the controller to use within it's methods.
+	#
+	# for some reason, the documentation ignores the following additional attributes, which are listed here:
+	#
+	# request:: the HTTPRequest object containing all the data from the HTTP request. If a WebSocket connection was established, the `request` object will continue to contain the HTTP request establishing the connection (cookies, parameters sent and other information).
+	# params:: any parameters sent with the request (short-cut for `request.params`), will contain any GET or POST form data sent (including file upload and JSON format support).
+	# cookies:: a cookie-jar to get and set cookies (set: `cookie\[:name] = data` or get: `cookie\[:name]`). Cookies and some other data must be set BEFORE the response's headers are sent.
+	# flash:: a temporary cookie-jar, good for one request. this is a short-cut for the `response.flash` which handles this magical cookie style.
+	# response:: the HTTPResponse **OR** the WSResponse object that formats the response and sends it. use `response << data`. This object can be used to send partial data (such as headers, or partial html content) in blocking mode as well as sending data in the default non-blocking mode.
+	# host_params:: a copy of the parameters used to create the host and service which accepted the request and created this instance of the controller class.
+	#
+	module ControllerMagic
+		def self.included base
+			base.send :include, InstanceMethods
+			base.extend ClassMethods
+		end
+
+		module InstanceMethods
+			module_function
+			public
+
+			# the request object, class: HTTPRequest.
+			attr_reader :request
+
+			# the ::params variable contains all the paramaters set by the request (/path?locale=he  => params["locale"] == "he").
+			attr_reader :params
+
+			# a cookie-jar to get and set cookies (set: `cookie\[:name] = data` or get: `cookie\[:name]`).
+			#
+			# Cookies and some other data must be set BEFORE the response's headers are sent.
+			attr_reader :cookies
+
+			# the HTTPResponse **OR** the WSResponse object that formats the response and sends it. use `response << data`. This object can be used to send partial data (such as headers, or partial html content) in blocking mode as well as sending data in the default non-blocking mode.
+			attr_accessor :response
+
+			# the ::flash is a little bit of a magic hash that sets and reads temporary cookies.
+			# these cookies will live for one successful request to a Controller and will then be removed.
+			attr_reader :flash
+
+			# the parameters used to create the host (the parameters passed to the `listen` / `add_service` call).
+			attr_reader :host_params
+
+			# a unique UUID to identify the object - used to make sure Radis broadcasts don't triger the
+			# boadcasting object's event.
+			attr_reader :uuid
+
+			# checks whether this instance accepts broadcasts (WebSocket instances).
+			def accepts_broadcast?
+				@_accepts_broadcast
+			end
+
+			# this method does two things.
+			#
+			# 1. sets redirection headers for the response.
+			# 2. sets the `flash` object (short-time cookies) with all the values passed except the :status value.
+			#
+			# use:
+			#      redirect_to 'http://google.com', notice: "foo", status: 302
+			#      # => redirects to 'http://google.com' with status 302 and adds notice: "foo" to the flash
+			# or simply:
+			#      redirect_to 'http://google.com'
+			#      # => redirects to 'http://google.com' with status 302 (default status)
+			#
+			# if the url is a symbol, the method will try to format it into a correct url, replacing any
+			# underscores ('_') with a backslash ('/').
+			#
+			# if the url is an empty string, the method will try to format it into a correct url
+			# representing the index of the application (http://server/)
+			#
+			def redirect_to url, options = {}
+				return super *[] if defined? super
+				raise 'Cannot redirect after headers were sent' if response.headers_sent?
+				url = "#{request.base_url}/#{url.to_s.gsub('_', '/')}" if url.is_a?(Symbol) || ( url.is_a?(String) && url.empty? ) || url.nil?
+				# redirect
+				response.status = options.delete(:status) || 302
+				response['Location'] = url
+				response['content-length'] ||= 0
+				flash.update options
+				response.finish
+				true
+			end
+
+			# this method adds data to be sent.
+			#
+			# this is usful for sending 'attachments' (data to be downloaded) rather then
+			# a regular response.
+			#
+			# this is also usful for offering a file name for the browser to "save as".
+			#
+			# it accepts:
+			# data:: the data to be sent
+			# options:: a hash of any of the options listed furtheron.
+			#
+			# the :symbol=>value options are:
+			# type:: the type of the data to be sent. defaults to empty. if :filename is supplied, an attempt to guess will be made.
+			# inline:: sets the data to be sent an an inline object (to be viewed rather then downloaded). defaults to false.
+			# filename:: sets a filename for the browser to "save as". defaults to empty.
+			#
+			def send_data data, options = {}
+				raise 'Cannot use "send_data" after headers were sent' if response.headers_sent?
+				# write data to response object
+				response << data
+
+				# set headers
+				content_disposition = "attachment"
+
+				options[:type] ||= MimeTypeHelper::MIME_DICTIONARY[::File.extname(options[:filename])] if options[:filename]
+
+				if options[:type]
+					response["content-type"] = options[:type]
+					options.delete :type
+				end
+				if options[:inline]
+					content_disposition = "inline"
+					options.delete :inline
+				end
+				if options[:attachment]
+					options.delete :attachment
+				end
+				if options[:filename]
+					content_disposition << "; filename=#{options[:filename]}"
+					options.delete :filename
+				end
+				response["content-length"] = data.bytesize rescue true
+				response["content-disposition"] = content_disposition
+				response.finish
+				true
+			end
+
+			# renders a template file (.erb/.haml) or an html file (.html) to text
+			# for example, to render the file `body.html.haml` with the layout `main_layout.html.haml`:
+			#   render :body, layout: :main_layout
+			#
+			# or, for example, to render the file `json.js.haml`
+			#   render :json, type: 'js'
+			#
+			# or, for example, to render the file `template.haml`
+			#   render :template, type: ''
+			#
+			# template:: a Symbol for the template to be used.
+			# options:: a Hash for any options such as `:layout` or `locale`.
+			# block:: an optional block, in case the template has `yield`, the block will be passed on to the template and it's value will be used inplace of the yield statement.
+			#
+			# options aceept the following keys:
+			# type:: the types for the `:layout' and 'template'. can be any extention, such as `"json"`. defaults to `"html"`.
+			# layout:: a layout template that has at least one `yield` statement where the template will be rendered.
+			# locale:: the I18n locale for the render. (defaults to params[:locale]) - only if the I18n gem namespace is defined (`require 'i18n'`).
+			#
+			# if template is a string, it will assume the string is an
+			# absolute path to a template file. it will NOT search for the template but might raise exceptions.
+			#
+			# if the template is a symbol, the '_' caracters will be used to destinguish sub-folders (NOT a partial template).
+			#
+			# returns false if the template or layout files cannot be found.
+			def render template, options = {}, &block
+				# make sure templates are enabled
+				return false if host_params[:templates].nil?
+				# render layout by recursion, if exists
+				(return render(options.delete(:layout), options) { render template, options, &block }) if options[:layout]
+				# set up defaults
+				options[:type] ||= 'html'
+				options[:locale] ||= params[:locale].to_sym if params[:locale]
+				# options[:locals] ||= {}
+				I18n.locale = options[:locale] if defined?(I18n) && options[:locale]
+				# find template and create template object
+				filename = template.is_a?(String) ? File.join( host_params[:templates].to_s, template) : (File.join( host_params[:templates].to_s, *template.to_s.split('_')) + (options[:type].empty? ? '': ".#{options[:type]}") + '.slim')
+				return ( Plezi.cache_needs_update?(filename) ? Plezi.cache_data( filename, ( Slim::Template.new() { IO.read filename } ) )  : (Plezi.get_cached filename) ).render(self, &block) if defined?(::Slim) && Plezi.file_exists?(filename)
+				filename.gsub! /\.slim$/, '.haml'
+				return ( Plezi.cache_needs_update?(filename) ? Plezi.cache_data( filename, ( Haml::Engine.new( IO.read(filename) ) ) )  : (Plezi.get_cached filename) ).render(self, &block) if defined?(::Haml) && Plezi.file_exists?(filename)
+				filename.gsub! /\.haml$/, '.erb'
+				return ( Plezi.cache_needs_update?(filename) ? Plezi.cache_data( filename, ( ERB.new( IO.read(filename) ) ) )  : (Plezi.get_cached filename) ).result(binding, &block) if defined?(::ERB) && Plezi.file_exists?(filename)
+				return false
+			end
+
+			# returns the initial method called (or about to be called) by the router for the HTTP request.
+			#
+			# this is can be very useful within the before / after filters:
+			#   def before
+			#     return false unless "check credentials" && [:save, :update, :delete].include?(requested_method)
+			#
+			# if the controller responds to a WebSockets request (a controller that defines the `on_message` method),
+			# the value returned is invalid and will remain 'stuck' on :pre_connect
+			# (which is the last method called before the protocol is switched from HTTP to WebSockets).
+			def requested_method
+				# respond to websocket special case
+				return :pre_connect if request['upgrade'] && request['upgrade'].to_s.downcase == 'websocket' &&  request['connection'].to_s.downcase == 'upgrade'
+				# respond to save 'new' special case
+				return :save if request.request_method.match(/POST|PUT/) && params[:id].nil? || params[:id] == 'new'
+				# set DELETE method if simulated
+				request.request_method = 'DELETE' if params[:_method].to_s.downcase == 'delete'
+				# respond to special :id routing
+				return params[:id].to_sym if params[:id] && available_public_methods.include?(params[:id].to_sym)
+				#review general cases
+				case request.request_method
+				when 'GET', 'HEAD'
+					return :index unless params[:id]
+					return :show
+				when 'POST', 'PUT'
+					return :update
+				when 'DELETE'
+					return :delete
+				end
+				false
+			end
+
+			# lists the available methods that will be exposed to HTTP requests
+			def available_public_methods
+				# set class global to improve performance while checking for supported methods
+				@@___available_public_methods___ ||= available_routing_methods - [:before, :after, :save, :show, :update, :delete, :initialize, :on_message, :pre_connect, :on_connect, :on_disconnect]
+			end
+
+			# lists the available methods that will be exposed to the HTTP router
+			def available_routing_methods
+				# set class global to improve performance while checking for supported methods
+				@@___available_routing_methods___ ||= (((self.class.public_instance_methods - Object.public_instance_methods) - Plezi::ControllerMagic::InstanceMethods.instance_methods).delete_if {|m| m.to_s[0] == '_'})
+			end
+
+			## WebSockets Magic
+
+			# WebSockets.
+			#
+			# Use this to brodcast an event to all 'sibling' websockets (websockets that have been created using the same Controller class).
+			#
+			# accepts:
+			# method_name:: a Symbol with the method's name that should respond to the broadcast.
+			# *args:: any arguments that should be passed to the method (IF REDIS IS USED, LIMITATIONS APPLY).
+			#
+			# the method will be called asynchrnously for each sibling instance of this Controller class.
+			#
+			def broadcast method_name, *args, &block
+				return false unless self.class.public_instance_methods.include?(method_name)
+				@uuid ||= SecureRandom.uuid
+				self.class.__inner_redis_broadcast(uuid, method_name, args, &block) || self.class.__inner_process_broadcast(uuid, method_name.to_sym, args, &block)
+			end
+
+
+			# WebSockets.
+			#
+			# Use this to collect data from all 'sibling' websockets (websockets that have been created using the same Controller class).
+			#
+			# This method will call the requested method on all instance siblings and return an Array of the returned values (including nil values).
+			#
+			# This method will block the excecution unless a block is passed to the method - in which case
+			#  the block will used as a callback and recieve the Array as a parameter.
+			#
+			# i.e.
+			#
+			# this will block: `collect :_get_id`
+			#
+			# this will not block: `collect(:_get_id) {|a| puts "got #{a.length} responses."; a.each { |id| puts "#{id}"} }
+			#
+			# accepts:
+			# method_name:: a Symbol with the method's name that should respond to the broadcast.
+			# *args:: any arguments that should be passed to the method.
+			# &block:: an optional block to be used as a callback.
+			#
+			# the method will be called asynchrnously for each sibling instance of this Controller class.
+			def collect method_name, *args, &block
+				return Plezi.callback(self, :collect, *args, &block) if block
+
+				r = []
+				ObjectSpace.each_object(self.class) { |controller|  r << controller.method(method_name).call(*args) if controller.accepts_broadcast?  && (controller.object_id != self.object_id) }
+				return r
+			end
+
+
+			# # will (probably NOT), in the future, require authentication or, alternatively, return an Array [user_name, password]
+			# #
+			# #
+			# def request_http_auth realm = false, auth = 'Digest'
+			# 	return request.service.handler.hosts[request[:host] || :default].send_by_code request, 401, "WWW-Authenticate" => "#{auth}#{realm ? "realm=\"#{realm}\"" : ''}" unless request['authorization']
+			# 	request['authorization']
+			# end
+		end
+
+		module ClassMethods
+			public
+
+			# reviews the Redis connection, sets it up if it's missing and returns the Redis connection.
+			#
+			# todo: review thread status? (incase an exception killed it)
+			def redis_connection
+				return false unless defined?(Redis) && ENV['PL_REDIS_URL']
+				return @@redis if defined?(@@redis_sub_thread) && @@redis
+				@@redis_uri ||= URI.parse(ENV['PL_REDIS_URL'])
+				@@redis ||= Redis.new(host: @@redis_uri.host, port: @@redis_uri.port, password: @@redis_uri.password)
+				@@redis_sub_thread = Thread.new do
+					begin
+						Redis.new(host: @@redis_uri.host, port: @@redis_uri.port, password: @@redis_uri.password).subscribe(redis_channel_name) do |on|
+							on.message do |channel, msg|
+								args = JSON.parse(msg)
+								params = args.shift
+								__inner_process_broadcast params['_an_ignore_object'], params['_an_method_broadcasted'].to_sym, args
+							end
+						end						
+					rescue Exception => e
+						Plezi.error e
+						retry
+					end
+				end
+				raise "Redis connction failed for: #{ENV['PL_REDIS_URL']}" unless @@redis
+				@@redis
+			end
+
+			# returns a Redis channel name for this controller.
+			def redis_channel_name
+				self.name.to_s
+			end
+
+			# broadcasts messages (methods) for this process
+			def __inner_process_broadcast ignore, method_name, args, &block
+				ObjectSpace.each_object(self) { |controller| Plezi.callback controller, method_name, *args, &block if controller.accepts_broadcast? && (!ignore || controller.uuid != ignore) }
+			end
+
+			# broadcasts messages (methods) between all processes (using Redis).
+			def __inner_redis_broadcast ignore, method_name, args, &block
+				return false unless redis_connection
+				raise "Radis broadcasts cannot accept blocks (no inter-process callbacks of memory sharing)!" if block
+				# raise "Radis broadcasts accept only one paramater, which is an optional Hash (no inter-process memory sharing)" if args.length > 1 || (args[0] && !args[0].is_a?(Hash))
+				args.unshift ({_an_method_broadcasted: method_name, _an_ignore_object: ignore})
+				redis_connection.publish(redis_channel_name, args.to_json )
+				true
+			end
+
+			# WebSockets.
+			#
+			# Class method.
+			#
+			# Use this to brodcast an event to all connections.
+			#
+			# accepts:
+			# method_name:: a Symbol with the method's name that should respond to the broadcast.
+			# *args:: any arguments that should be passed to the method (IF REDIS IS USED, LIMITATIONS APPLY).
+			#
+			# this method accepts and optional block (NON-REDIS ONLY) to be used as a callback for each sibling's event.
+			#
+			# the method will be called asynchrnously for each sibling instance of this Controller class.
+			def broadcast method_name, *args, &block
+				return false unless public_instance_methods.include?(method_name)
+				__inner_redis_broadcast(nil, method_name, args, &block) || __inner_process_broadcast(nil, method_name.to_sym, args, &block)
+			end
+
+			# WebSockets.
+			#
+			# Class method.
+			#
+			# Use this to collect data from all websockets for the calling class (websockets that have been created using the same Controller class).
+			#
+			# This method will call the requested method on all instance and return an Array of the returned values (including nil values).
+			#
+			# This method will block the excecution unless a block is passed to the method - in which case
+			#  the block will used as a callback and recieve the Array as a parameter.
+			#
+			# i.e.
+			#
+			# this will block: `collect :_get_id`
+			#
+			# this will not block: `collect(:_get_id) {|a| puts "got #{a.length} responses."; a.each { |id| puts "#{id}"} }
+			#
+			# accepts:
+			# method_name:: a Symbol with the method's name that should respond to the broadcast.
+			# *args:: any arguments that should be passed to the method.
+			# &block:: an optional block to be used as a callback.
+			#
+			# the method will be called asynchrnously for each instance of this Controller class.
+			def collect method_name, *args, &block				
+				return Plezi.push_event(self.method(:collect), *args, &block) if block
+
+				r = []
+				ObjectSpace.each_object(self) { |controller|  r << controller.method(method_name).call(*args) if controller.accepts_broadcast? }
+				return r
+			end
+		end
+
+		module_function
+
+
+	end
+end