plezi 0.11.2 → 0.12.0

data/docs/logging.md

@@ -2,13 +2,48 @@
 
 (todo: write documentation)
 
-Inside Plezi's core code is a pure Ruby IO reactor called [GReactor](https://github.com/boazsegev/GReactor) (Generic Reactor), a very powerful Asynchronous Workflow Engine that allows us to enjoy both Multi-Threading and Multi-Processing.
+Inside Plezi's core code is a pure Ruby IO reactor called [Iodine](https://github.com/boazsegev/iodine), a wonderful Asynchronous Workflow Engine that allows us to enjoy both Multi-Threading and Multi-Processing.
 
-Plezi leverages [GReactor's](https://github.com/boazsegev/GReactor) logging support to help you log to both files and STDOUT (terminal screen) - either one or both
+Plezi leverages [Iodine's](https://github.com/boazsegev/iodine) logging support to help you log to both files and STDOUT (terminal screen) - either one or both
 
-You can read more about [GReactor](https://github.com/boazsegev/GReactor) and it's amazing features in it's [documentation](http://www.rubydoc.info/github/boazsegev/GReactor/master).
+You can read more about [Iodine](https://github.com/boazsegev/iodine) and it's amazing features in it's [documentation](http://www.rubydoc.info/github/boazsegev/iodine/master).
 
 ## Setting up a Logger
 
+Logging is based on the standard Ruby `Logger`, and replaceing the default logger (STDOUT) to a different logger (such as a file based logger), is as simple as:
+
+```ruby
+Iodine.logger = Logger.new filename
+# # the same can be done using Plezi.logger, which automatically defers to Iodine.logger
+# Plezi.logger = Logger.new filename
+```
+
 
 ## Logging Helpers Methods
+
+// to do: complete docs
+
+### `Iodine.info`
+
+// to do: complete docs
+
+### `Iodine.debug`
+
+// to do: complete docs
+
+### `Iodine.warn`
+
+// to do: complete docs
+
+### `Iodine.error`
+
+// to do: complete docs
+
+### `Iodine.fatal`
+
+// to do: complete docs
+
+### `Iodine.log(raw_string)`
+
+// to do: complete docs
+

data/docs/routes.md

@@ -1,22 +1,194 @@
 # Plezi's Smart Routing System
 
-In the core of Plezi's framework is a smart Object Oriented Router which actls like a "virtual folder" with RESTful routing and Websocket support.
+In the core of Plezi's framework is a smart Object Oriented Router which acts like a "virtual folder" with RESTful routing and Websocket support.
 
 RESTful routing and Websocket callback support both allow us to use conventionally named methods in our Controller to achive common tasks. Such names methods, as will be explored further on, include the `update`, `save` and `show` RESTful method names, as well as the `on_open`, `on_message(data)` and `on_close` Websocket callbacks.
 
+## What is a Route?
+
+Routes are what connects different URLs to different parts of our code.
+
+We when we visit `www.example.com/users/index` we expect a different page than when we go to `www.example.com/users/1`. This is because we expect the first URL to provide a page with the list of users while we expect the second URL to show us just one user's page or data.
+
+in the example above, all the requests to `www.example.com` end up at the same server and it is the server's inner workings - the server's inner router - that directs the `/users/index` to one part of our code and `/users/1` to another.
+
+Plezi has an inner router which routes each request to the corresponding method or code.
+
+\* It should be noted that except for file handling and the asset pipeline - which are file-system dependent - routes are case-sensitive.
+
 ## Defining a Route
 
-(todo: write documentation)
+We define a route using Plezi's `Plezi.route` method or the shortcut DSL method `route` (without the `Plezi.` part).
+
+This method accept a String, or Regexp, that should point to a "group" of routes.
+
+The method also requires either a class that "controls" that group of routes or a block of code that responds to that route.
+
+Here are a two examples for valid routes. You can run the following script in the `irb` terminal:
+
+```ruby
+require 'plezi'
+
+class UsersController
+    def index
+        "All Users"
+    end
+end
+
+# the "/users" group can be extended. for now, it will only answer: "/users" or "/users/index"
+# this is because that's all that UsersController defines.
+Plezi.route "/users", UsersController
+
+# this route isn't grouped under a controller. it will only answer "/people"
+Plezi.route("/people") { "People" }
+
+# this route includes a catch-all at the end and will catch anything that starts with "/stuff/" 
+Plezi.route("/stuff/*") { "More and more stuff" }
+
+# this is catch-all which will answer any requests not yet answered.
+Plezi.route("*") { "Lost?" }
+
+# this route will never be seen,
+# because the catch-all route answers any request before it gets here.
+Plezi.route("/never-seen") { "You cant see me..." }
+
+
+exit
+```
+
+As you may have noticed, the route's order of creation was important and established an order of precedence.
+
+If the order of precedence were not to exist, we couldn't create a catch-all route, in fear that it might respond to valid requests.
 
 ### The `:id` parameter
 
-(todo: write documentation)
+In order to manage route "groups", Plezi's router attmpt to add an optional `:id` parameter at the end of the route. This is only possible when the route doesn't end with a catch-all (if a catch-all exists, the `:id` parameter can't be isolated).
+
+So, the following two routes are identical:
+
+```ruby
+require 'plezi'
+
+class UsersController
+    def index
+        "All Users"
+    end
+end
+
+Plezi.route "/users", UsersController
+
+route "/users/(:id)", UsersController
+
+exit
+```
+
+It's possible to add different optional parameters either before or after the (:id) parameter... but the (:id) parameter is special and it WILL effect the way the Controller reacts to the request - this is what allows the controller to react to RESTful requests (more information about this later on).
+
+For example:
+
+```ruby
+require 'plezi'
+
+class UsersController
+    def index
+        "All Users"
+    end
+    def show
+        params[:name] ||= "unknown"
+        "Your name is #{ params[:name] }... why are you looking for user id '#{ params[:id] }'?"
+    end
+end
+
+# try visiting "/users/1/John"
+route "/users/(:id)/(:name)", UsersController
+
+exit
+```
+
+As you noticed, providing an `:id` parameter invoked the RESTful method `show`. This is only one possible outcome. We will discuss this more when we look at the Controller being used as a virtual folder and as we discuss about RESTful method.
 
 ### More inline parameters
 
-(todo: write documentation)
+Inline parameters come in more flavors:
+
+* Required parameters signified only by the `:` sign. i.e. `'/users/:name'`.
+* Optional parameters, as seen before. i.e. `'/users/(:name)'`.
+* Required parameters matching a specific pattern, signified by the `:` sign with a `{pattern}`. i.e. `'/users/:date{[\d]{8}}'` (requiring 8 digit date, such as `'20151231'`).
+* Optional parameters matching a specific pattern. i.e. `'/users/(:date){[\d]{8}}'` (optional 8 digit date, such as `'20151231'`).
+
+Using inline parameters, it's possible to achive great flexability with the same route, allowing our code to be better organized. This is especially helpful when expecting data to be received using AJAX or when creating an accessible API for native apps to utilize.
+
+It should be noted, that since a parameter matches against the whole of the pattern, parenthesis shouldn't be used and could cause parsing errors.
+
+### Re-Write Routes
+
+Sometimes, we want some of our routes to share common optional (or required) parameters. This is where "Re-Write" routes come into play.
+
+A common use-case, is for setting the locale or language for the response.
+
+To create a re-write route, we set the "controller" to false.
+
+For Example:
+
+
+```ruby
+require 'plezi'
+
+class UsersController
+    def index
+        case params[:locale]
+        when 'sp'
+            "Hola!"
+        when 'fr'
+            "Bonjour!"
+        when 'ru'
+            "Здравствуйте!"
+        when 'jp'
+            "こんにちは!"
+        else
+            "Hello!"
+        end
+    end
+end
+
+# this is the re-write route:
+Plezi.route "/(:locale){en|sp|fr|ru|jp}/*", false
+
+# this route inherits the `:locale`'s result
+# try:
+#   /fr/users
+#   /ru/users
+#   /en/users
+#   /it/users # => isn't a valid locale
+Plezi.route "/users", UsersController
+
+exit
+```
+
+notice the re-write route contained a catch all. After Plezi version 0.11.3 this catch-all is automatically added if missing. The catch-all is the part of the path that will remain for the following routes to check against.
+
+### Routes with Blocks instead of Controllers
+
+Routes that respond with a block of code can receive the `request` and `response` objects, allowing for greater usability.
+
+These Routes favor a global response over the different features offered by Controllers (i.e. RESTful routing and virtual folder method routing). Also, the block of code does NOT inherit all the magical abilities bestowed on Controllers which could allow for a slight increase in response time.
+
+Here's a more powerful example of a route with a block of code, thistime using the `request` and `response` passed on to it:
+
+```ruby
+require 'plezi'
+
+Plezi.route "/(:id)/(:value)" do |request, response|
+   if request.params[:id]
+       response.cookies[request.params[:id]] = request.params[:value]
+       response << "Set the #{request.params[:id]} cookie to #{request.params[:value] || 'be removed'}.\n\n"
+   end
+   response << "Your cookies are:\n"
+   request.cookies.each {|k, v| response <<  "* #{k}: #{v}\n" }
+end
 
-### Re-Write Routes and Proc Controllers
+exit
+```
 
 ## The Controller
 

data/docs/websockets.md

@@ -1,5 +1,10 @@
 # Plezi Websockets
 
+Inside Plezi's core code is the pure Ruby HTTP and Websocket Server (and client) that comes with [Iodine](https://github.com/boazsegev/iodine), a wonderful little server that supports an effective websocket fanctionality both as a server and as a client.
+
+Plezi augmentes Iodine by adding auto-Redis support for scaling and automatically mapping each Contoller Class as a broadcast channel and each server instance to it's own unique channel - allowing unicasting to direct it's message at the target connection's server and optimizing resources.
+
+
 
 (todo: write documentation)
 

data/lib/plezi.rb

@@ -11,8 +11,8 @@ require 'yaml'
 require 'uri'
 require 'set'
 
-# GRHttp servet
-require 'grhttp'
+# Iodine server
+require 'iodine/http'
 
 
 ## erb templating
@@ -67,7 +67,6 @@ require 'plezi/handlers/session.rb'
 # For example, open your Ruby terminal (the `irb` command) and type:
 #
 #    require 'plezi'
-#    listen
 #    route "*", Plezi::StubRESTCtrl
 #    exit # will start the service.
 #
@@ -81,7 +80,6 @@ require 'plezi/handlers/session.rb'
 #          "Hello World!"
 #       end
 #    end
-#    listen
 #    route "*", MyController
 #
 #    exit # I'll stop writing this line every time.
@@ -92,7 +90,6 @@ require 'plezi/handlers/session.rb'
 # Plezi also accepts an optional block instead of the conrtoller Class object for example:
 #
 #    require 'plezi'
-#    listen
 #    route(/[.]*/) {|request, response| response << "Your request, master: #{request.path}."}
 #
 # As you may have noticed before, the catch-all route (/[.]*/) has a shortcut: '*'.
@@ -101,7 +98,6 @@ require 'plezi/handlers/session.rb'
 # accept an implied `params[:id]` variable. the following path ('/'):
 #
 #    require 'plezi'
-#    listen
 #    route "/", Plezi::StubWSCtrl
 #    # go to: http://localhost:3000/1
 #    # =>  Plezi::StubRESTCtrl.new.show() # where params[:id] == 1
@@ -111,7 +107,6 @@ require 'plezi/handlers/session.rb'
 # Routes are handled in the order they are created. If overlapping routes exist, the first will execute first:
 #
 #    require 'plezi'
-#    listen
 #    route('*') do |request, response|
 #       response << "Your request, master: #{request.path}." unless request.path.match /cats/
 #    end
@@ -134,9 +129,6 @@ require 'plezi/handlers/session.rb'
 #    # a timer
 #    PL.run_after 2, -> {puts "this will wait 2 seconds to run... too late. for this example"}
 #
-#    # an asynchronous method call with an optional callback block
-#    PL.callback(Kernel, :puts, "Plezi will start eating our code once we exit terminal.") {puts 'first output finished'}
-#
 #    # remember to exit to make it all start
 #    exit
 #

data/lib/plezi/common/api.rb

@@ -5,10 +5,32 @@ module Plezi
 
 	# Defines methods used to set up the Plezi app.
 
-	# public API to add a service to the framework.
-	# accepts a Hash object with any of the following options (Hash keys):
-	# port:: port number. defaults to 3000 or the port specified when the script was called.
-	# host:: the host name. defaults to any host not explicitly defined (a catch-all). NOTICE: in order to allow for hostname aliases, this is host emulation and the listening socket will bind to all the addresses available. To limit the actual binding use the `:bind` parameter as set by the GReactor's API - in which case host aliases might not work.
+	# Deprecated. use {Plezi.host}.
+	def listen parameters = {}
+		Iodine.warn "listen is deprecated. use `Plezi.host` instead."
+		host parameters.delete(:host) || :default, parameters
+	end
+
+	# adds a route to the last server created
+	def route(path, controller = nil, &block)
+		::Plezi::Base::HTTPRouter.add_route path, controller, &block
+	end
+
+
+	# adds a shared route to all existing services and hosts.
+	def shared_route(path, controller = nil, &block)
+		::Plezi::Base::HTTPRouter.add_shared_route path, controller, &block
+	end
+
+	# public API to add or setup domain names related to the application.
+	#
+	# A default host can be created or accessed by using `:default` of false for the host name.
+	#
+	# Accepts:
+	# host_name:: the name (domain name) of the host as a String object. Use the Symbol `:default` for the catch-all domain name.
+	# 
+	#
+	# The options is a Hash object with any of the following options (Hash keys):
 	# alias:: a String or an Array of Strings which represent alternative host names (i.e. `alias: ["admin.google.com", "admin.gmail.com"]`).
 	# public:: the public root folder. if this is defined, static files will be served from this folder and all it's sub-folders. Plezi does NOT support file indexing.
 	# 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).
@@ -16,9 +38,6 @@ module Plezi
 	# assets_callback:: a method that accepts two parameters: (request, response) and renders any custom assets. the method should return `false` unless it had set the response.
 	# 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:
 	#
@@ -31,109 +50,37 @@ module Plezi
 	#
 	# Plezi's controller.render ERB, Slim and Haml are natively supported.
 	#
-	# @return [Plezi::Router]
-	#
-	def listen parameters = {}
-		# update default values
-		parameters[:index_file] ||= 'index.html'
-		parameters[:assets_public] ||= '/assets'
-		parameters[:assets_public].chomp! '/'
-		parameters[:public] ||= parameters[:root] # backwards compatability
-		puts "Warning: 'root' option is being depracated. use 'public' instead." if parameters[:root]
-
-		# check if the port is used twice.
-		@routers_locker.synchronize do
-			@active_router = GRHttp.listen(parameters)
-			unless @active_router[:upgrade_handler]
-				@routers << (@active_router[:http_handler] = ::Plezi::Base::HTTPRouter.new)
-				@active_router[:upgrade_handler] = @active_router[:http_handler].upgrade_proc
-			else
-				@active_router.delete :alias
-			end
-			@active_router[:http_handler].add_host(parameters[:host], @active_router.merge(parameters) )
-			@active_router = @active_router[:http_handler]
-		end
-		# return the current handler or the protocol..
-		@active_router
-	end
-
-	# clears all the listeners and routes defined
-	def clear_app
-		@routers_locker.synchronize {GReactor.clear_listeners; @routers.clear}
-	end
-	# adds a route to the last server created
-	def route(path, controller = nil, &block)
-		raise "Must define a listener before adding a route - use `Plezi.listen`." unless @active_router
-		@routers_locker.synchronize { @active_router.add_route path, controller, &block }
-	end
-
-
-	# adds a shared route to all existing services and hosts.
-	def shared_route(path, controller = nil, &block)
-		raise "Must have created at least one Pleze service before calling `shared_route` - use `Plezi.listen`." unless @routers
-		@routers_locker.synchronize { @routers.each {|r| r.add_shared_route path, controller, &block } }
-	end
-
-	# adds a host to the last server created
+	# @return [::Plezi::Base::HTTPRouter]
 	#
-	# accepts a host name and a parameter(s) Hash which are the same parameter(s) as {Plezi.listen} accepts:
 	def host(host_name, params)
-		raise "Must define a listener before adding a route - use `Plezi.listen`." unless @active_router
-		@routers_locker.synchronize { @active_router.add_host host_name, params }
-	end
-
-	# starts the Plezi framework server and hangs until the exit signal is given.
-	def start
-		start_async
-		puts "\nPress ^C to exit.\n"
-		GReactor.join { puts "\r\nStarting shutdown sequesnce. Press ^C to force quit."}
+		::Plezi::Base::HTTPRouter.add_host host_name, params
 	end
 
-	# Makes sure the GRHttp server will be used by Rack (if Rack is available) and disables Plezi's autostart feature.
-	#
-	# This method is a both a fail safe and a shortcut. Plezi will automatically attempt to diable autostart when discovering Rack
-	# but this method also makes sure that the GRHttp is set as the Rack server by setting the ENV\["RACK_HANDLER"] variable.
-	#
-	# This is used as an alternative to {Plezi.start_placebo}.
-	#
-	# Use {Plezi.start_placebo} to augment an existing app while operating Plezi on a different process or server.
-	#
-	# Use {Plezi.start_rack} to augment an existing Rack app (i.e. Rails/Sinatra) by loading both Plezi and the existing Rack app
-	# to the GRHtto server (it will set up GRHttp as the Rack server).
-	def start_rack
-		Object.const_set("NO_PLEZI_AUTO_START", true) unless defined?(NO_PLEZI_AUTO_START)
-		ENV["RACK_HANDLER"] = 'grhttp'
-	end
-	# starts the Plezi framework and returns immidiately,
-	# allowing you to run the Plezi framework along side another framework. 
-	def start_async
-		Object.const_set("NO_PLEZI_AUTO_START", true) unless defined?(NO_PLEZI_AUTO_START)
-		return GReactor.start if GReactor.running?
-		puts "Starting Plezi #{Plezi::VERSION} Services using GRHttp #{GRHttp::VERSION} and GReactor #{GReactor::VERSION}."
-		GReactor.on_shutdown { puts "Plezi shutdown. It was fun to serve you."  }
-		GReactor.start ::Plezi::Settings.max_threads
-	end
-	# This allows you to run the Plezi framework along side another framework - WITHOUT running the actual server.
+	# This allows you to use the Plezi framework's code inside your existing Rack application - WITHOUT running the actual server.
 	#
 	# The server will not be initiatet and instead you will be able to use Plezi controllers and the Redis auto-config
-	# to broadcast Plezi messages to other Plezi processes - allowing for scalable intigration of Plezi into other frameworks.
-	def start_placebo
-		GReactor.clear_listeners
-		redis # make sure the redis connection is activated
-		puts "* Plezi #{Plezi::VERSION} Services will start with no Server...\n"
-		start_async
+	# to broadcast Plezi messages to other Plezi processes - allowing for scalable intigration of Plezi into existing Rack applications.
+	def start_placebo receiver = nil
+		# force start Iodine only if Iodine isn't used as the server
+		if ::Iodine.protocol == ::Iodine::Http::Http1 && (defined?(::Rack) ? (::Rack::Handler.default == ::Iodine::Http::Rack) : true)
+			# Iodine.info("`start_placebo` is called while using the Iodine server. `start_placebo` directive being ignored.")
+			return false
+		end
+		unless @placebo_initialized
+			raise "Placebo fatal error: Redis connection failed to load - make sure gem is required and `ENV['PL_REDIS_URL']` is set." unless redis # make sure the redis connection is activated
+			puts "* Plezi #{Plezi::VERSION} Services will start with no Server...\n"
+			::Iodine.protocol = :no_server
+			Iodine.force_start!
+			@placebo_initialized = true
+		end
+		receiver ? Plezi::Placebo.new(receiver) : true
 	end
 
-	# this module contains the methods that are used as a DSL and sets up easy access to the Plezi framework.
-	#
-	# use the`listen`, `host` and `route` functions rather then accessing this object.
-	#
-	@active_router = nil
-	@routers_locker = Mutex.new
-	@routers ||= [].to_set
+	# deprecation notice
+	def start_rack
+		Iodine.warn "`start_rack` is deprecated. There is no need to call this method."
+	end
 end
 
 Encoding.default_internal = 'utf-8'
 Encoding.default_external = 'utf-8'
-
-Object.const_set("NO_PLEZI_AUTO_START", true) if defined?(::Rack::Builder) && !defined?(NO_PLEZI_AUTO_START)