plezi 0.12.22 → 0.14.0

data/docs/controllers.md

@@ -1,27 +0,0 @@
-# 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/logging.md

@@ -1,49 +0,0 @@
-# Plezi's Logging
-
-(todo: write documentation)
-
-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 [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 [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,209 +0,0 @@
-# Plezi's Smart Routing System
-
-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`.
-
-## 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 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.
-
-Like all web applications, Plezi also 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.
-
-## Defining a Route
-
-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 few 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 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/" 
-Plezi.route("/stuff/*") { "More and more stuff" }
-
-# 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 can't 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
-
-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
-
-route "/users/(:id)/(:name)", UsersController
-
-exit
-```
-
-* 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
-
-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, 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
-
-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
-```
-
-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, 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, this time 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
-
-exit
-```
-
-## 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,213 +0,0 @@
-# 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 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)
-