# Hara(袚)

[![Gem Version](https://badge.fury.io/rb/hara.png)](http://badge.fury.io/rb/hara)
[![Build Status](https://travis-ci.org/jjyr/hara.png?branch=master)](https://travis-ci.org/jjyr/hara)

Hara(袚) is a websocket based application framework, build upon [em-websocket](https://github.com/igrigorik/em-websocket).

* Simple, easy to use.
* Actor model(celluloid).
* Event-IO(em-websocket).

## Installation

Add this line to your application's Gemfile:

    gem 'hara'

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install hara

Client:

    copy it from ./client

## Basic Usage

*server*
```ruby
require 'hara'

class Test
  include Hara::App

  define_action :reverse do |str|
    response_msg str.reverse
  end
end

Hara::Server.start 'localhost', '3000'
```

*client*
```javascript
var client = new Hara();
client.connect('ws://localhost:3000');
client.send('reverse', ['hello world'], function(msg){alert(msg)});
```

## Full Usages

*server*
```ruby
require 'hara'

class Clock
  #include Hara::App make your class become Celluloid::Actor
  include Hara::App

  #Hara::App provide some callbacks

  def after_connect
    puts 'first called'
    p headers
    # push message to client
    send_msg "connected"
  end

  def before_action action, *args
    puts 'called when action comming'
  end

  define_action :start do
    puts "#{client_ip} #{client_port}"

    # push time to client every 1 sec
    @timer = every(1){ send_msg Time.now.to_s}

    # different between send_msg & response_msg
    # send_msg means push to client, trigger client onmessage callback
    # response_msg respond client request, and trigger send callback(if it present)
    response_msg 'started'
  end

  define_action :stop do
    @timer.cancel
    response_msg 'stoped'
  end

  def after_action action, *args
    puts 'called when action complete'
  end

  def action_missing action, *args
    puts 'error'
    super
  end

  def on_close close_info
    puts "#{client_ip} connection closed"
  end
end

# you can pass some options to start
server_options = {
#...some options, same as EM::Websocket.run
}
Hara::Server.start 'localhost', '3000', server_options
```

*client*
```javascript
var client = new Hara();

//handle pushed messages(send_msg)
client.onmessage = function(msg){
    console.log("current time:" + msg);
}

//connect to server
client.connect('ws://localhost:3000');

//call server side action
client.send('start', [], function(msg){console.log(msg)});
//started
//current time:2013-08-05 10:48:04 +0800
//current time:2013-08-05 10:48:05 +0800
//current time:2013-08-05 10:48:06 +0800
//current time:2013-08-05 10:48:07 +0800
client.send('stop', [], function(msg){console.log(msg)});
//stoped

//close connection
client.close();
```

####use filter####
```ruby
# Hara::Filter
# Filter can help you filter some connections before dispatched to app actor.
# Example: use Filter to authentication
require 'cgi/cookie'

class Echo
  include Hara::App
#..some code
end

#class name is not matter
class Authentication
  include Hara::Filter
  
  #default value is 10
  self.pool_size = 20

  # You must implement filter method, return value should be ture or false
  def filter
    # You can use some helper methods(headers, client_ip, send_msg...), just like Hara::App
    CGI::Cookie.parse(headers['cookie'])['foo'] == ['bar']
  end
end

Hara::Server.start 'localhost', '3000'
```

## Contributing

1. Fork it
2. Feel free to send pull requests