plezi 0.12.2 → 0.12.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 57622e2bc4d95fe0c0902460b9d181632276064f
-  data.tar.gz: 2c5b4ea394f9984cd72c7707a423099402a323de
+  metadata.gz: 083a5d3e4fe51a9892e41c1b4271ccb84b40ccbd
+  data.tar.gz: fc65f387b0eb8c3828a318d6c2029097f726ca5b
 SHA512:
-  metadata.gz: 54bfd6e45045a268a2980618e220976bfc92a8d1ad31312e1a1f9ebc276ecb6ad0e7f442841076ef8a554fc501e525647c39666ab360c02fb4bc67ddd648078e
-  data.tar.gz: bc7f627f2f9b9f068d72e22a4535ee4dafef8eec4363d49b39b53c4742a0b3fa0b3bb2dbd176ff463b39b3edbab7e3bd7b913e7905eed7ec6b8c989a112942ae
+  metadata.gz: ae792a668041bb5e91b1881f5f0b19374a6387ffed4218e07433eef65b307ac94ad314e39b4db75ae75f625132492153710cc4e80c4a305fae15b65f8900337c
+  data.tar.gz: 29f30a7734ae412e10dc1256e277db04d3f7d66e66ef70116bd69cde2f2d78e03134042b5df1aee695f1e7d6b1d7a4393ddfd4cb5357c64fdb15e8397c20afed

data/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ***
 
+Change log v.0.12.3
+
+**Feature**: (requires Redis) Identity API is here (read more on the [Websockets guide](./websockets.md))
+
+* Websocket Identity API allows you to link a websocket connection with a unique "identity" (i.e., `user.id` or even `session.id`).
+
+     This is called "registering", as the identity "registers" and is henceforth recognized. 
+
+* Notifications sent to the identidy will persist until the identity's "lifetime" expires.
+
+     The default "lifetime" is 7 days, meaning an "Identity" message queue will survive for 7 days since the last time the Identity was "registered". This lifetime can be set for each identity during registration.
+
+* This allows you to send notifications that will "wait" until a user or visitor reconnects and registers the new connection under their Identity.
+
+* This is an alternative to persistant storage, where either visitors messages that aren't read within a certain timespan 
+
+**Fix**: the Placebo API was fixed to correspond with the changes in Iodine's API.
+
+**Fix**: fixed an issue where Placebo's on_close would through an exception.
+
+**Fix**: Some websocket API methods were exposed to the Http router as paths (causing internal 500 errors, as they couldn't be invoked by the router). These methods are now `protected` and by doing so the Http router ignores them. Also, `has_exposed_method?` was reviewed in a way that should help avoid future occurrences of these issues.
+
+**Fix**: fixed an issue where AJAX parameters weren't form-decoded (`'%20'` wasn't replaced with `' '` etc'). Now the parameters are decoded as expected.
+
+***
+
 Change log v.0.12.2
 
 **Update**: Plezi now leverages Iodine's support for a File response body, allowing for a smaller memory footpring when sending large files.

data/README.md

@@ -1,4 +1,7 @@
 # [Plezi](https://github.com/boazsegev/plezi), The Ruby framework for realtime web-apps
+[![Gem Version](https://badge.fury.io/rb/plezi.svg)](http://badge.fury.io/rb/plezi)
+[![Inline docs](http://inch-ci.org/github/boazsegev/plezi.svg?branch=master)](http://www.rubydoc.info/github/boazsegev/plezi/master)
+[![GitHub](https://img.shields.io/badge/GitHub-Open%20Source-blue.svg)](https://github.com/boazsegev/plezi)
 
 Plezi is an easy to use Ruby Websocket Framework, with full RESTful routing support and HTTP streaming support. It's name comes from the word "fun", or "pleasure", since Plezi is a pleasure to work with.
 
@@ -14,9 +17,7 @@ Plezi leverages [Iodine's server](https://github.com/boazsegev/iodine) new archi
 
 Plezi and Iodine are written for Ruby versions 2.1.0 or greater (or API compatible variants). Version 2.2.3 is the currently recommended version.
 
-### Plezi version data
-[![Gem Version](https://badge.fury.io/rb/plezi.svg)](http://badge.fury.io/rb/plezi)
-[![Inline docs](http://inch-ci.org/github/boazsegev/plezi.svg?branch=master)](http://www.rubydoc.info/github/boazsegev/plezi/master)
+**Plezi version notice**
 
 The `master` branch always refers to the latest edge version, which might also be a broken version. Please refer to the relevent version by using the version's `tag` in the branch selector.
 
@@ -322,7 +323,7 @@ now visit:
 * [http://localhost:3000/post/12/1.3/1](http://localhost:3000/post/12/1.3/1)
 * [http://localhost:3000/post/12/1](http://localhost:3000/post/12/1)
 
-**please see the `route` documentation for more information on routes**.
+**[please see the `route` documentation for more information on routes](./docs/routes.md)**.
 
 ## Plezi Virtual Hosts
 
@@ -531,6 +532,57 @@ Plezi is meant to be very flexible. please take a look at the Plezi Module for s
 
 Feel free to fork or contribute. right now I am one person, but together we can make something exciting that will help us enjoy Ruby in this brave new world and (hopefully) set an example that will induce progress in the popular mainstream frameworks such as Rails and Sinatra.
 
+## Who's afraid of multi-threading?
+
+Plezi builds on Iodine's concept of "connection locking", meaning that your controllers shouldn't be acessed by more than one thread at the same time.
+
+This allows you to run Plezi as a multi-threaded (and even multi-process) application as long as your controllers don't change or set any global data... Readeing global data after it was set during initialization is totally fine, just not changing or setting it...
+
+But wait, global data is super important, right?
+
+Well, sometimes it is. And although it's a better practice to avoide storing any global data in global variables, sometimes storing stuff in the global space is exactly what we need.
+
+The solution is simple - if you can't use persistent databases with thread-safe libraries (i.e. Sequel / ActiveRecord / Redis, etc'), use Plezi's global cache storage (see Plezi::Cache).
+
+Plezi's global cache storage is a memory based storage protected by a mutex for any reading or writing from the cache.
+
+So... these are protected:
+
+    # set data
+    Plezi.cache_data :my_global_variable, 32
+    # get data
+    Plezi.get_cached :my_global_variable # => 32
+
+However, although Ruby seems innocent, it's super powerful when it comes to using pointers and references behind the scenes. This could allow you to change a protected object in an unprotected way... consider this:
+
+    a = []
+    b = a
+    b << '1'
+    # we changed `a` without noticing
+    a # => [1]
+
+For this reason, it's important that Strings, Arrays and Hashes will be protected if they are to be manipulated in any way.
+
+The following is safe:
+
+    # set data
+    Plezi.cache_data :global_hash, Hash.new
+    # manipulate data
+    Plezi.get_cached :global_hash do |global_hash|
+        global_hash[:change] = "safe"
+    end
+ 
+However, th following is unsafe:
+
+    # set data
+    Plezi.cache_data :global_hash, Hash.new
+    # manipulate data
+    global_hash = Plezi.get_cached :global_hash do |global_hash|
+    global_hash[:change] = "NOT safe"
+ 
+
+\* be aware, if using Plezi in as a multi-process application, that each process has it's own cache and that processes can't share the cache. The different threads in each of the processes will be able to acess their process's cache, but each process runs in a different memory space, so they can't share.
+
 ## Contributing
 
 1. Fork it ( https://github.com/boazsegev/plezi/fork )

data/docs/controllers.md

@@ -0,0 +1,27 @@
+# Plezi Controllers - Virtual folders, RESTful requests, Websockets and more.
+
+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.
+
+The first layer of this powerful routing system is [the Plezi's Http Router and the core method `Plezi.route` which we already explored](./routes.md).
+
+The second layer of this powerful routing system is the Controller class which we are about explore.
+
+## What is a Controller Class?
+
+(todo: write documentation)
+
+### A Virtual Folder
+
+(todo: write documentation)
+
+### RESTful methods
+
+(todo: write documentation)
+
+### Websocket Callbacks
+
+(todo: write documentation)
+
+

data/docs/routes.md

@@ -4,15 +4,19 @@ In the core of Plezi's framework is a smart Object Oriented Router which acts li
 
 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.
 
+The first layer of this powerful routing system is the Plezi's Http Router and the core method `Plezi.route`.
+
 ## 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.
+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 a specific user's page or data.
+
+in the example above, all the requests are made to the server at `www.example.com` 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.
 
-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.
+Like all web applications, Plezi also has an inner router which routes each request to the corresponding method or code.
 
-Plezi has an inner router which routes each request to the corresponding method or code.
+Plezi's routing system was designed to build upon conventions used in other routing systems together with an intuitive approach that allows for agail application development.
 
 \* It should be noted that except for file handling and the asset pipeline - which are file-system dependent - routes are case-sensitive.
 
@@ -24,7 +28,7 @@ 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:
+Here are a few examples for valid routes. You can run the following script in the `irb` terminal:
 
 ```ruby
 require 'plezi'
@@ -39,18 +43,20 @@ end
 # 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"
+# this route isn't grouped under a controller.
+# it will answer to "/people" and "/people/something" with the same response.
 Plezi.route("/people") { "People" }
 
-# this route includes a catch-all at the end and will catch anything that starts with "/stuff/" 
+# 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.
+# this is catch-all that answers 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..." }
+Plezi.route("/never-seen") { "You can't see me..." }
 
 
 exit
@@ -99,13 +105,14 @@ class UsersController
     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.
+* now visit [/users/1/John](http://localhost:3000/users/1/John)
+
+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](./controllers.md) being used as a virtual folder and as we discuss about RESTful method.
 
 ### More inline parameters
 
@@ -118,7 +125,7 @@ Inline parameters come in more flavors:
 
 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.
+It should be noted, when using parameters matching a specific pattern, that since a parameter matches against the whole of the pattern, parenthesis within the shouldn't be used and could lead to parsing errors.
 
 ### Re-Write Routes
 
@@ -165,15 +172,22 @@ 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.
+Try the code above and visit:
+
+* [localhost:3000/fr/users](http://localhost:3000/fr/users)
+* [localhost:3000/ru/users](http://localhost:3000/ru/users)
+* [localhost:3000/en/users](http://localhost:3000/en/users)
+* [localhost:3000/it/users](http://localhost:3000/it/users)
+
+Notice the re-write route contained a catch all. 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.
+Routes that respond with a block of code can receive the `request` and `response` objects, to be used within the block of code (the controller also has access to these objects).
 
 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:
+Here's a more powerful example of a route with a block of code, this time using the `request` and `response` passed on to it:
 
 ```ruby
 require 'plezi'
@@ -190,20 +204,6 @@ end
 exit
 ```
 
-## The Controller
-
-(todo: write documentation)
-
-### A Virtual Folder
-
-(todo: write documentation)
-
-### RESTful methods
-
-(todo: write documentation)
-
-### Websocket Callbacks
-
-(todo: write documentation)
-
+## The next step
 
+Now that we have learned more about the power of Plezi's routing system, it's time to [learn more about what Controller classes can do for us](./controllers.md).

data/docs/websockets.md

@@ -1,14 +1,213 @@
 # 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.
+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 functionality 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.
 
+Reading through this document, you should remember that Plezi's websocket connections are object oriented - they are instances of Controller classes that answer a specific url/path in the Plezi application. More than one type of connection (Controller instance) could exist in the same application.
 
+## A short intro to Websockets (skip this if you can)
+
+In a very broad sense, Websockets allow the browser communicate with the server in a bi-directional manner. This overcomes some of the limitations imposed by Http alone, allowing (for instance) to push real-time data, such as chat messages or stock quotes, directly to the browser.
+
+In essense, while Http's worflow is a call and response (the browser "calls", the server "responds"), Websockets is a conversation, sometimes with long pauses, where both sides can speak whenever they feel the need to.
+
+This, in nature, requires that both sides of the conversation establish a common language... this part is pretty much up to each application.
+
+It's easy to think about it this way:
+
+the browsers starts a call-response sequence. All websocket connections start as Http call-response. The browser shouts over the internet "I want to start a conversation".
+
+The server responds: "Sure thing, let's talk".
+
+Than they start their websocket conversation, keeping the connection between them open. The server can also answer "no thanks", but than there's no websocket connection and the Http connection will probably die out (unless it's Http/2).
+
+### initiating a websocket connection
+
+The websocket connection is initiated by the browser using `Javascript`.
+
+The `Javascript` should, in most applications, handle the following three Websocket `Javascript` events:
+
+- `onopen`: a connection was established.
+- `onmessage`: a message was received through the connection.
+- `onclose`: an open connection had closed, or a connection initiated couldn't be established.
+
+Here is a common enough example of a script designed to open a websocket:
+
+```js
+
+websocket = NaN
+
+function init_websocket()
+{
+  //  no need to renew socket connection if it's open
+  if(websocket && websocket.readyState == 1) return true;
+
+  // initiate the url for the websocket... this is a bit of an overkill,
+  // but it will allow you to copy & paste decent code
+  var ws_uri = (window.location.protocol.match(/https/) ? 'wss' : 'ws') + '://' + window.document.location.host
+
+  // initiate a new websocket connection
+  websocket = new WebSocket(ws_uri);
+
+  // define the onopen event callback
+  websocket.onopen = function(e) {
+      // what do you want to do now?
+      // maybe send a message?
+      websocket.send("Hello there!");
+      // a common practice is to use JSON
+      var msg = JSON.stringify({msg: 'chat', data: 'Hello there!'})
+      websocket.send(msg);
+  };
+
+  // define the onclose event callback
+  websocket.onclose = function(e) {
+    // you probably want to reopen the websocket if it closes
+    setTimeout( init_websocket, 100 );
+  };
+
+  // define the onmessage event callback
+  websocket.onmessage = function(e) {
+    // what do you want to do now?
+    console.log(e.data);
+    // to use JSON, use:
+    // msg = JSON.parse(e.data);
+  };
+}
+
+init_websocket();
+
+```
+
+As you can tell from reading through the code, this means that the browser will open a new connection to the server, using the websocket protocol.
+
+In our example the script sent a message: `"Hello there!"`. It's up to your code to decide what to do with the data it receives, be it using JSON or raw data.
+
+When data comes in from the browser, the `onmessage` event is raised. It's up to your script to decypher the meaning of that message within the `onmessage` callback.
+
+###
+
+No we know a bit about what Websockets are and how to initiate a websocket connection to send and receive data... next up, how to get Plezi to answer (or refuse) websocket requests?
+
+## Communicating between the application and clients
 
 (todo: write documentation)
 
 
+## Communicating between different Websocket clients
+
+Plezi supports three models of communication:
+
+### General websocket communication
+
+  When using this type of communication, it is expected that each connection's controller provide a protected instance method with a name matching the event name and that this method will accept, as arguments, the data sent with the event.
+
+  This type of communication includes:
+
+  - **Multicasting**:
+
+      Use `multicast` to send an event to all the websocket connections currently connected to the application (including connections on other servers running the application, if Redis is used).
+
+  - **Unicasting**:
 
+      Use `unicast` to send an event to a specific websocket connection.
 
+      This uses a unique UUID that contains both the target server's information and the unique connection identifier. This allows a message to be sent to any connected websocket across multiple application instances when using Redis, minimizing network activity and server load as much as effectively possible.
+
+      Again, exacly like when using multicasting, any connection targeted by the message is expected to implemnt a method matching the name of the event, which will accept (as arguments) the data sent.
+
+For instance, when using:
+
+      unicast target_id, :event_name, "string", and: :hash
+
+The receiving websocket controller is expected to have a protected method named `event_name` like so:
+
+```ruby
+class MyController
+    #...
+    protected
+    def event_name str, options_hash
+        #...
+    end
+end
+```
+
+### Object Oriented communication
+
+Use `broadcast` or `Controller.broadcast` to send an event to a all the websocket connections that are managed by a specific Controller class.
+
+The controller is expected to provide a protected instance method with a name matching the event name and that this method will accept, as arguments, the data sent with the event.
+
+The benifit of using this approach is knowing exacly what type of objects handle the message - all the websocket connections receiving the message will be members (instances) of the same class.
+
+For instance, when using:
+
+      MyController.broadcast :event_name, "string", and: :hash
+
+The receiving websocket controller is expected to have a protected method named `event_name` like so:
+
+```ruby
+class MyController
+    #...
+    protected
+    def event_name str, options_hash
+        #...
+    end
+end
+```
+
+### Identity oriented communication
+
+Identity oriented communication will only work if Plezi's Redis features are enabled. To enable Plezi's automatic Redis features (such as websocket scaling automation, Redis Session Store, etc'), use:
+
+      ENV['PL_REDIS_URL'] ||=  "redis://user:password@redis.example.com:9999"
+
+Use `#register_as` or `#notify(identity, event_name, data)` to send make sure a certain Identity object (i.e. an app's User) receives notifications either in real-time (if connected) or the next time the identity connects to a websocket and identifies itself using `#register_as`.
+
+Much like General Websocket Communication, the identity can call `#register_as` from different Controller classes and it is expected that each of these Controller classes implement the necessary methods.
+
+It is a good enough practice that an Identity based websocket connection will utilize the `#on_open` callback to authenticate and register an identity. For example:
+
+```ruby
+class MyController
+   #...
+   def on_open
+       user = suthenticate_user
+       close unless user
+       register_as user.id
+   end
+
+   protected
+
+   def event_name str, options_hash
+       #...
+   end
+end
+```
+
+It is recommended that the authentication and registration are split into two different events - the `pre_connect` for authentication and the `on_open` for registration - since, as a matter of security, it is better to prevent someone from entering (not establishing a websocket connection) than throwing them out (closing the connection within the `on_open` event).
+
+Sending messages to the identity is similar to the other communication API methods. For example:
+
+      notify user_id, :event_name, "string data", hash: :data, more_hash: :data
+
+As expected, it could be that an Identity will never revisit the application or messages become outdated after a while. For this reason limits must be set as to how long any specific "mailbox" should remain alive in the database when it isn't acessed by the Identity. This is done within the `register_as` method i.e.:
+
+      register_as user.id, lifetime: 1_814_400 # 21 days
+
+Another consideration is that more than one "lifetime" setting might be required for defferent types of messages. The solution for this will be to allow a single connection to register as a number of different identities, each with it's own lifetime:
+
+      # to register:
+      register_as "#{user.id}-long", lifetime: 1_814_400 # 21 days
+      register_as "#{user.id}-short", lifetime: 3_600 # 1 hour
+
+      # to notify:
+      notify "#{user.id}-long", :event_name #... 
+      notify "#{user.id}-short", :event_name #... 
+
+It should be noted that the lifetime is for the identity's lifetime and NOT the notification's lifetime. A notification sent a second before the identity "dies" will live for only a second and notify will return `true` all the same.
+
+`notify` should return `true` or `false`, depending on whether the identity still exists.
+
+(todo: write documentation)
 

data/lib/plezi.rb

@@ -14,14 +14,6 @@ require 'set'
 # Iodine server
 require 'iodine/http'
 
-
-## erb templating
-begin
-	require 'erb'
-rescue => e
-
-end
-
 ### version
 
 require "plezi/version"
@@ -46,13 +38,19 @@ require 'plezi/helpers/mime_types.rb'
 require 'plezi/handlers/http_router.rb'
 require 'plezi/handlers/route.rb'
 require 'plezi/handlers/ws_object.rb'
+require 'plezi/handlers/ws_identity.rb'
 require 'plezi/handlers/controller_magic.rb'
 require 'plezi/handlers/controller_core.rb'
 require 'plezi/handlers/placebo.rb'
 require 'plezi/handlers/stubs.rb'
 require 'plezi/handlers/session.rb'
 
+## erb templating
+begin
+	require 'erb'
+rescue => e
 
+end
 
 ##############################################################################
 #
@@ -148,6 +146,3 @@ Iodine.threads = 30
 Iodine.run { puts "Plezi is feeling optimistic running version #{::Plezi::VERSION}.\n\n"}
 # PL is a shortcut for the Plezi module, so that `PL == Plezi`.
 PL = Plezi
-
-
-

data/lib/plezi/common/cache.rb

@@ -56,14 +56,20 @@ module Plezi
 		end
 
 		# places data into the cache, under an identifier ( file name ).
-		def cache_data filename, data, mtime = Time.now
+		def cache_data filename, data, mtime = Iodine.time
 			CACHE_LOCK.synchronize { CACHE_STORE[filename] = CacheObject.new( data, mtime )  }
 			data
 		end
 
 		# Get data from the cache. will throw an exception if there is no data in the cache.
+		# 
+		# If a block is passed to the method, it will allows you to modify the protected cache in a thread safe manner.
+		#
+		# This is useful for manipulating strings or arrays that are stored in the cache.
 		def get_cached filename
-			CACHE_STORE[filename].data # if CACHE_STORE[filename]
+			return CACHE_STORE[filename].data unless block_given?
+			data = CACHE_STORE[filename].data
+			CACHE_LOCK.synchronize { yield(data) }
 		end
 
 		# Remove data from the cache, if it exists.

data/lib/plezi/common/redis.rb

@@ -16,22 +16,9 @@ module Plezi
 					raise "Redis connction failed for: #{ENV['PL_REDIS_URL']}" unless @redis
 					@redis_sub_thread = Thread.new do
 						begin
-							safe_types = [Symbol, Date, Time, Encoding, Struct, Regexp, Range, Set]
 							::Redis.new(host: @redis_uri.host, port: @redis_uri.port, password: @redis_uri.password).subscribe(Plezi::Settings.redis_channel_name, Plezi::Settings.uuid) do |on|
 								on.message do |channel, msg|
-									begin
-										data = YAML.safe_load(msg, safe_types)
-										next if data[:server] == Plezi::Settings.uuid
-										data[:type] = Object.const_get(data[:type]) unless data[:type].nil? || data[:type] == :all
-										if data[:target]
-											data[:type].___faild_unicast( data ) unless Iodine::Http::Websockets.unicast data[:target], data
-										else
-											Iodine::Http::Websockets.broadcast data
-										end
-									rescue => e
-										Iodine.error "The following could be a security breach attempt:"
-										Iodine.error e
-									end
+									::Plezi::Base::WSObject.forward_message ::Plezi::Base::WSObject.translate_message(msg)
 								end
 							end
 						rescue => e

data/lib/plezi/handlers/controller_core.rb

@@ -42,18 +42,6 @@ module Plezi
 					# complete handshake
 					return self
 				end
-				# handles websocket opening.
-				def on_open
-					super() if defined?(super)
-				end
-				# handles websocket messages.
-				def on_message data
-					super if defined?(super)
-				end
-				# handles websocket being closed.
-				def on_close
-					super if defined? super
-				end
 
 				# Inner Routing
 				def _route_path_to_methods_and_set_the_response_

data/lib/plezi/handlers/controller_magic.rb

@@ -229,7 +229,7 @@ module Plezi
 
 			# This class method behaves the same way as the instance method #url_for. See the instance method's documentation for more details.
 			def url_for dest
-				get_pl_route.url_for dest				
+				get_pl_route.url_for dest
 			end
 
 			# resets the routing cache

data/lib/plezi/handlers/placebo.rb

@@ -57,7 +57,7 @@ module Plezi
 					end
 					# Cleanup on disconnection
 					def on_close
-						io_out.close unless io_out.closed?
+						@io_out.close unless @io_out.closed?
 						return super() if defined? super
 						Iodine.warn "Placebo #{self.class.superclass.name} disconnected. Ignore if this message appears during shutdown."
 					end
@@ -104,7 +104,7 @@ module Plezi
 			i, o = IO.pipe
 			req = {}
 			handler = new_class.new(i, o, req)
-			io = Placebo::Base::PlaceboIO.new i, handler, req
+			io = Placebo::Base::PlaceboIO.new i, handler: handler, request: req
 			handler
 		end
 	end

data/lib/plezi/handlers/route.rb

@@ -15,7 +15,7 @@ module Plezi
 				fill_parameters = match request.path
 				return false unless fill_parameters
 				old_params = request.params.dup
-				fill_parameters.each {|k,v| Plezi::Base::Helpers.add_param_to_hash k, v, request.params }
+				fill_parameters.each {|k,v| Plezi::Base::Helpers.add_param_to_hash k, ::Plezi::Base::Helpers.form_decode(v), request.params }
 				ret = false
 				if controller
 					ret = controller.new(request, response)._route_path_to_methods_and_set_the_response_
@@ -86,6 +86,8 @@ module Plezi
 			def url_for dest = :index
 				raise NotImplementedError, "#url_for isn't implemented for this router - could this be a Regexp based router?" unless @url_array
 				case dest
+				when :index, nil, false
+					dest = {}					
 				when String
 					dest = {id: dest.dup}
 				when Numeric, Symbol
@@ -93,8 +95,6 @@ module Plezi
 				when Hash
 					dest = dest.dup
 					dest.each {|k,v| dest[k] = v.dup if v.is_a? String }
-				when nil, false
-					dest = {}
 				else
 					# convert dest.id and dest[:id] to their actual :id value.
 					dest = {id: (dest.id rescue false) || (raise TypeError, "Expecting a Symbol, Hash, String, Numeric or an object that answers to obj[:id] or obj.id") }

data/lib/plezi/handlers/session.rb

@@ -25,6 +25,10 @@ module Plezi
 			end
 			failed
 		end
+		# returns the session id (the session cookie value).
+		def id
+			@id
+		end
 		# Get a key from the session data store. If a Redis server is supplied, it will be used to synchronize session data.
 		#
 		# Due to scaling considirations, all keys will be converted to strings, so that `"name" == :name` and `1234 == "1234"`.
@@ -44,6 +48,7 @@ module Plezi
 		# Due to scaling considirations, all keys will be converted to strings, so that `"name" == :name` and `1234 == "1234"`.
 		# If you store two keys that evaluate as the same string, they WILL override each other.
 		def []= key, value
+			return delete key if value.nil?
 			key = key.to_s
 			if (conn=Plezi.redis)
 				conn.hset @id, key, value
@@ -63,6 +68,15 @@ module Plezi
 			failed
 		end
 
+		# @return [String] returns the Session data in YAML format.
+		def to_s
+			if (conn=Plezi.redis) 
+				conn.expire @id, SESSION_LIFETIME
+				return conn.hgetall(@id).to_yaml
+			end
+			failed
+		end
+
 		# Removes a key from the session's data store.
 		def delete key
 			key = key.to_s

data/lib/plezi/handlers/ws_identity.rb

@@ -0,0 +1,110 @@
+module Plezi
+
+	module Base
+
+		module WSObject
+
+			# the following are additions to the WebSocket Object module,
+			# to establish identity to websocket realtionships, allowing for a
+			# websocket message bank.
+
+			module InstanceMethods
+				protected
+
+				# The following method registers the connections as a unique global identity.
+				#
+				# Like {Plezi::Base::WSObject::SuperClassMethods#notify}, using this method requires an active Redis connection
+				# to be set up. See {Plezi#redis} for more information.
+				#
+				# Only one connection at a time can respond to identity events. If the same identity
+				# connects more than once, only the last connection will receive the notifications.
+				#
+				# The method accepts:
+				# identity:: a global application wide unique identifier that will persist throughout all of the identity's connections.
+				# options:: an option's hash that sets the properties of the identity.
+				#
+				# The option's Hash, at the moment, accepts only the following (optional) option:
+				# lifetime:: sets how long the identity can survive. defaults to `604_800` seconds (7 days).
+				#
+				# Calling this method will also initiate any events waiting in the identity's queue.
+				# make sure that the method is only called once all other initialization is complete.
+				#
+				# Do NOT call this method asynchronously unless Plezi is set to run as in a single threaded mode - doing so
+				# will execute any pending events outside the scope of the IO's mutex lock, thus introducing race conditions.
+				def register_as identity, options = {}
+					redis = Plezi.redis
+					raise "The identity API requires a Redis connection" unless redis
+					identity = identity.to_s.freeze
+					@___identity ||= [].to_set
+					@___identity << identity
+					redis.pipelined do
+						redis.lpush "#{identity}_uuid".freeze, uuid
+						redis.ltrim "#{identity}_uuid".freeze, 0, 0
+					end
+					___review_identity identity
+					redis.lpush(identity, ''.freeze) unless redis.llen(identity) > 0
+					redis.pipelined do
+						redis.expire identity, (options[:lifetime] || 604_800)
+						redis.expire "#{identity}_uuid".freeze, (options[:lifetime] || 604_800)
+					end
+				end
+
+				# sends a notification to an Identity. Returns false if the Identity never registered or it's registration expired.
+				def notify identity, event_name, *args
+					self.class.notify identity, event_name, *args
+				end
+				# returns true if the Identity in question is registered to receive notifications.
+				def registered? identity
+					self.class.registered? identity
+				end
+			end
+			module ClassMethods
+			end
+			module SuperInstanceMethods
+				protected
+				def ___review_identity identity
+					redis = Plezi.redis
+					raise "unknown Redis initiation error" unless redis
+					identity = identity.to_s.freeze
+					return Iodine.warn("Identity message reached wrong target (ignored).").clear unless @___identity.include?(identity)
+					redis.multi do
+						redis.lpush identity, ''.freeze
+						redis.lpush identity, ''.freeze
+					end
+					msg = redis.rpop(identity)
+					Iodine.error "Unknown Identity Queue error - both messages and identity might be lost!\nExpected no data, but got: #{msg}" unless msg == ''.freeze
+					while (msg = redis.rpop(identity)) && msg != ''.freeze
+						msg = ::Plezi::Base::WSObject.translate_message(msg)
+						next unless msg
+						Iodine.error("Notification recieved but no method can handle it - dump:\r\n #{msg.to_s}") && next unless self.class.has_super_method?(msg[:method])
+						self.method(msg[:method]).call *msg[:data]
+					end
+				end
+			end
+
+			module SuperClassMethods
+				public
+
+				# sends a notification to an Identity. Returns false if the Identity never registered or it's registration expired.
+				def notify identity, event_name, *args
+					redis = Plezi.redis
+					raise "The identity API requires a Redis connection" unless redis
+					identity = identity.to_s.freeze
+					return false unless redis.llen(identity).to_i > 0
+					redis.lpush identity, ({method: event_name, data: args}).to_yaml
+					target_uuid = redis.lindex "#{identity}_uuid".freeze, 0
+					unicast target_uuid, :___review_identity, identity if target_uuid
+					true
+				end
+
+				# returns true if the Identity in question is registered to receive notifications.
+				def registered? identity
+					redis = Plezi.redis
+					return Iodine.warn("Cannot check for Identity registration without a Redis connection (silent).") && false unless redis
+					identity = identity.to_s.freeze
+					redis.llen(identity).to_i > 0
+				end
+			end
+		end
+	end
+end

data/lib/plezi/handlers/ws_object.rb

@@ -1,31 +1,74 @@
 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 Base
 
 		# This module includes all the methods that will be injected into Websocket objects,
 		# specifically into Plezi Controllers and Placebo objects.
+		#
+		# 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 WSObject
 			def self.included base
 				base.send :include, InstanceMethods
 				base.extend ClassMethods
 				base.superclass.instance_eval {extend SuperClassMethods}
+				base.superclass.instance_eval {include SuperInstanceMethods}
+			end
+
+			def self.translate_message msg
+				begin
+					@safe_types ||= [Symbol, Date, Time, Encoding, Struct, Regexp, Range, Set]
+					data = YAML.safe_load(msg, @safe_types)
+				rescue => e
+					Iodine.error "The following could be a security breach attempt:"
+					Iodine.error e
+					nil
+				end
+			end
+			def self.forward_message data
+				begin
+					return false if data[:server] == Plezi::Settings.uuid
+					data[:type] = Object.const_get(data[:type]) unless data[:type].nil? || data[:type] == :all
+					if data[:target]
+						data[:type].___faild_unicast( data ) unless Iodine::Http::Websockets.unicast data[:target], data
+					else
+						Iodine::Http::Websockets.broadcast data
+					end
+				rescue => e
+					Iodine.error "The following could be a security breach attempt:"
+					Iodine.error e
+					nil
+				end
 			end
 
 			module InstanceMethods
 				public
+
+				# handles websocket opening.
+				def on_open
+					@ws_io = @request[:io]
+					super() if defined?(super)
+				end
+				# handles websocket messages.
+				def on_message data
+					super if defined?(super)
+				end
+				# handles websocket being closed.
+				def on_close
+					super if defined? super
+				end
+
 				# handles broadcasts / unicasts
 				def on_broadcast data
 					unless data.is_a?(Hash) && (data[:type] || data[:target]) && data[:method] && data[:data]
@@ -39,6 +82,26 @@ module Plezi
 					self.method(data[:method]).call *data[:data]
 				end
 
+				# Get's the websocket's unique identifier for unicast transmissions.
+				#
+				# This UUID is also used to make sure Radis broadcasts don't triger the
+				# boadcasting object's event.
+				def uuid
+					return @uuid if @uuid
+					if __get_io
+						return (@uuid ||=  Plezi::Settings.uuid + @io.id)
+					end
+					nil
+				end
+				alias :unicast_id :uuid
+
+				protected
+
+				# allows writing of data to the websocket (if opened). Otherwise appends the message to the Http response.
+				def write data
+					(@ws_io || @response) << data
+				end
+
 				# Performs a websocket unicast to the specified target.
 				def unicast target_uuid, method_name, *args
 					self.class.unicast target_uuid, method_name, *args
@@ -68,20 +131,6 @@ module Plezi
 					self.class._inner_broadcast({ method: method_name, data: args, type: :all}, __get_io )
 				end
 
-				# Get's the websocket's unique identifier for unicast transmissions.
-				#
-				# This UUID is also used to make sure Radis broadcasts don't triger the
-				# boadcasting object's event.
-				def uuid
-					return @uuid if @uuid
-					if __get_io
-						return (@uuid ||=  Plezi::Settings.uuid + @io.id)
-					end
-					nil
-				end
-				alias :unicast_id :uuid
-
-				protected
 				def __get_io
 					@io ||= (@request ? @request[:io] : nil)
 				end
@@ -105,7 +154,13 @@ module Plezi
 					@super_methods_list.include? method_name
 				end
 				def has_exposed_method? method_name
-					@exposed_methods_list ||= ( (self.public_instance_methods - Class.new.instance_methods - Plezi::ControllerMagic::InstanceMethods.instance_methods - [:before, :after, :save, :show, :update, :delete, :initialize, :on_message, :on_broadcast, :pre_connect, :on_open, :on_close]).delete_if {|m| m.to_s[0] == '_'} ).to_set
+					@reserved_methods_list ||= Class.new.public_instance_methods +
+						Plezi::Base::WSObject::InstanceMethods.public_instance_methods +
+						Plezi::Base::WSObject::SuperInstanceMethods.public_instance_methods +
+						Plezi::ControllerMagic::InstanceMethods.public_instance_methods +
+						Plezi::Base::ControllerCore::InstanceMethods.public_instance_methods +
+						[:before, :after, :save, :show, :update, :delete, :initialize]
+					@exposed_methods_list ||= ( (self.public_instance_methods - @reserved_methods_list ).delete_if {|m| m.to_s[0] == '_'} ).to_set
 					@exposed_methods_list.include? method_name
 				end
 
@@ -125,6 +180,8 @@ module Plezi
 				end
 
 			end
+			module SuperInstanceMethods
+			end
 
 			module SuperClassMethods
 				public

data/lib/plezi/helpers/magic_helpers.rb

@@ -32,6 +32,13 @@ module Plezi
 				(str.to_s.gsub(/[^a-z0-9\*\.\_\-]/i) {|m| '%%%02x'.freeze % m.ord }).force_encoding(::Encoding::ASCII_8BIT)
 			end
 
+			# decode percent-encoded data (excluding the '+' sign for encoding).
+			def self.form_decode s
+				s = s.to_s.gsub(/\%[0-9a-f]{2}/i) {|m| m[1..2].to_i(16).chr}
+				s.gsub!(/&#[0-9]{4};/i) {|m| [m[2..5].to_i].pack 'U'.freeze }
+				s
+			end
+
 			# Adds paramaters to a Hash object, according to the Iodine's server conventions.
 			def self.add_param_to_hash name, value, target
 				begin

data/lib/plezi/version.rb

@@ -1,3 +1,3 @@
 module Plezi
-    VERSION = "0.12.2"
+    VERSION = "0.12.3"
 end

data/plezi.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "iodine", "~> 0.1.5"
+  spec.add_dependency "iodine", "~> 0.1.8"
   spec.add_development_dependency "bundler", "~> 1.7"
   spec.add_development_dependency "rake", "~> 10.0"
 

data/resources/websockets.js

@@ -24,7 +24,7 @@ function init_websocket()
 	};
 
 	websocket.onclose = function(e) {
-        // If the websocket repeatedly you probably want to reopen the websocket if it closes
+        // If the websocket repeatedly you probably want to report an error
         if(!isNaN(websocket_fail_limit) && websocket_fail_count >= websocket_fail_limit) {
         	// What to do if we can't reconnect so many times?
         	return

data/test/plezi_tests.rb

@@ -155,6 +155,36 @@ class WSsizeTestCtrl
 	end
 end
 
+class WSIdentity
+	def index
+		"identity api testing path\n#{params}"		
+	end
+	def show
+		if notify params[:id], :notification, (params[:message] || 'no message')
+			"Send notification for #{params[:id]}: #{(params[:message] || 'no message')}"
+		else
+			"The identity requested (#{params[:id]}) doesn't exist."
+		end
+	end
+	def pre_connect
+		params[:id] && true
+	end
+	def on_open
+		register_as params[:id]
+	end
+	def on_message data
+		puts "Got websocket message: #{data}"
+	end
+
+	protected
+
+	def notification message
+		write message
+		puts "Identity Got: #{message}"
+	end
+
+end
+
 module PleziTestTasks
 	module_function
 
@@ -239,7 +269,7 @@ module PleziTestTasks
 		begin
 			puts "    * Streaming test: #{RESULTS[URI.parse("http://localhost:3000/streamer").read == 'streamed']}"
 		rescue => e
-			puts "    **** Streaming test FAILED TO RUN!!!"
+			puts "    **** Streaming test FAILED TO RUN #{e.message}!!!"
 			puts e
 		end
 	end
@@ -442,6 +472,8 @@ end
 
 host
 
+shared_route 'id/(:id)/(:message)', WSIdentity
+
 shared_route 'ws/no', Nothing
 shared_route 'ws/placebo', PlaceboTestCtrl
 shared_route 'ws/size', WSsizeTestCtrl
@@ -460,8 +492,8 @@ end
 # mem_print_proc.call
 # Plezi.run_every 30, &mem_print_proc
 
-# require 'redis'
-# ENV['PL_REDIS_URL'] ||= ENV['REDIS_URL'] || ENV['REDISCLOUD_URL'] || ENV['REDISTOGO_URL'] || "redis://test:1234@pub-redis-11008.us-east-1-4.5.ec2.garantiadata.com:11008"
+require 'redis'
+ENV['PL_REDIS_URL'] ||= ENV['REDIS_URL'] || ENV['REDISCLOUD_URL'] || ENV['REDISTOGO_URL'] || "redis://test:1234@pub-redis-11008.us-east-1-4.5.ec2.garantiadata.com:11008"
 # Plezi.processes = 3
 
 Plezi.threads = 9

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plezi
 version: !ruby/object:Gem::Version
-  version: 0.12.2
+  version: 0.12.3
 platform: ruby
 authors:
 - Boaz Segev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-26 00:00:00.000000000 Z
+date: 2015-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: iodine
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: 0.1.8
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: 0.1.8
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -70,6 +70,7 @@ files:
 - Rakefile
 - bin/plezi
 - docs/async_helpers.md
+- docs/controllers.md
 - docs/logging.md
 - docs/routes.md
 - docs/websockets.md
@@ -91,6 +92,7 @@ files:
 - lib/plezi/handlers/route.rb
 - lib/plezi/handlers/session.rb
 - lib/plezi/handlers/stubs.rb
+- lib/plezi/handlers/ws_identity.rb
 - lib/plezi/handlers/ws_object.rb
 - lib/plezi/helpers/http_sender.rb
 - lib/plezi/helpers/magic_helpers.rb