em-ucengine 0.1.1 → 0.3.0

data/README.md

@@ -1,13 +1,10 @@
-EventMachine library for U.C.Engine
-===================================
+# EventMachine library for U.C.Engine
 
 em-ucengine is a Ruby library for [U.C.Engine](http://ucengine.org/) powered
 by [EventMachine](https://github.com/eventmachine/eventmachine). It can
 connect, subscribe and publish events to U.C.Engine.
 
-
-How to use it
--------------
+## Install
 
 Install with Rubygems:
 
@@ -15,43 +12,94 @@ Install with Rubygems:
 
 If you use bundler, add it to your `Gemfile`:
 
-    gem "em-ucengine", "~>0.1"
+    gem "em-ucengine", "~> 0.3"
+
+## Usage
+
+### Client
 
-Then, you can use it in your code:
+#### EventMachine
 
-    require "em-ucengine"
-    EventMachine::UCEngine.run do |uce|
-      uce.connect("participant", "pwd") do |session|
-        EM.add_periodic_timer(1) { session.publish("em-ucengine.example.ping", "demo") }
-        session.subscribe("demo") do |event|
-          puts "Hey, we received an event: #{event.inspect}"
-        end
-      end
+We have a classic block style API:
+
+```ruby
+require "em-ucengine"
+EventMachine::UCEngine::Client.run do |uce|
+  uce.connect("participant", "pwd") do |err, session|
+    EM.add_periodic_timer(1) { session.publish("em-ucengine.example.ping", "demo") }
+    session.subscribe("demo") do |err, event|
+      puts "Hey, we received an event: #{event.inspect}"
     end
+  end
+end
+```
 
-Don't hesitate to look at the specs for more examples ;-)
+Each method call return a deferable.
 
+```ruby
+require "em-ucengine"
+EventMachine::UCEngine::Client.run do |uce|
+  req = uce.connect("participant", "pwd")
+  req.callback do |session|
+    session.publish("em-ucengine.example.ping", "demo")
+  end
+  req.errback do |error|
+     puts "error"
+  end
+end
+```
 
-TODO
-----
+#### Net/HTTP
 
-* Files API
-* ACL or Roles API
-* Better error handling
-* Complete the specs
-* Compatibility with em-synchrony
-* Yard documentation
+```ruby
+require "em-ucengine"
+
+uce = UCEngine::Client.new
+session = uce.connect("participant", "pwd")
+session.publish("em-ucengine.example.ping", "demo")
+```
+
+### Brick
+
+```ruby
+require "em-ucengine"
+require "em-ucengine/brick"
+
+class MyBrick
+  include EM::UCEngine::Brick
 
+  on "ping" do |event|
+    puts event
+  end
+end
 
-Issues or Suggestions
----------------------
+brick = MyBrick.run
+```
+
+Don't hesitate to look at the specs for more examples ;-)
+
+## TODO
+
+* Release the gem with another name
+* Complete the specs
+* Implements the download and upload methods for the Net::HTTP backend
+
+## Issues or Suggestions
 
 Found an issue or have a suggestion? Please report it on
 [Github's issue tracker](http://github.com/af83/ucengine.em/issues).
 
+First you must have an ucengine instance goto the source directory and start:
+
+    make run
+
+Once the console started successfully, in an other shell
+
+    ./rel/ucengine/bin/demo.sh localhost
+
 If you wants to make a pull request, please check the specs before:
 
-    ./spec/em-ucengine_spec.rb
+    rake test
 
 
 Copyright (c) 2011 af83, released under the LGPL license

data/lib/em-ucengine.rb

@@ -1,188 +1,3 @@
-require "eventmachine"
-require "em-http-request"
-require "yajl"
-
-
-module EventMachine
-  class UCEngine
-
-    def self.run(*args)
-      EM.run { yield self.new(*args) }
-    end
-
-    def initialize(host="localhost", port=5280, api_root="/api", api_version="0.4")
-      @host = host
-      @port = port
-      @root = api_root
-      @version = api_version
-    end
-
-    def time
-      Session.new(self, nil, nil).time { |time| yield time }
-    end
-
-    def connect(user, password, metadata=nil)
-      body = { "name" => user, "credential" => password }
-      body["metadata"] = metadata if metadata
-      http = EM::HttpRequest.new(url "presence").post :body => body
-      http.errback  { yield nil }
-      http.callback do
-        data = Yajl::Parser.parse(http.response)
-        data = data["result"] if data
-        yield Session.new(self, data["uid"], data["sid"])
-      end
-    end
-
-    def url(path)
-      "http://#{@host}:#{@port}#{@root}/#{@version}/#{path}"
-    end
-
-    class Session < Struct.new(:uce, :uid, :sid)
-
-      ### Time - http://docs.ucengine.org/api.html#time ###
-
-      def time
-        get("/time") { |result| yield result if block_given? }
-      end
-
-      ### Presence - http://docs.ucengine.org/api.html#authentication ###
-
-      def presence(sid)
-        get("/presence/#{sid}") { |result| yield result if block_given? }
-      end
-
-      def disconnect
-        delete("/presence/#{sid}") { |result| yield result if block_given? }
-      end
-
-      ### Users - http://docs.ucengine.org/api.html#user ###
-
-      def users
-        get("/user") { |result| yield result if block_given? }
-      end
-
-      def user(uid)
-        get("/user/#{uid}") { |result| yield result if block_given? }
-      end
-
-      def create_user(data)
-        post("/user", data) { |result| yield result && result.to_i if block_given? }
-      end
-
-      def update_user(uid, data)
-        put("/user/#{uid}", data) { |result| yield result if block_given? }
-      end
-
-      def delete_user(uid)
-        delete("/user/#{uid}") { |result| yield result if block_given? }
-      end
-
-      ### General infos - http://docs.ucengine.org/api.html#infos ###
-
-      def infos
-        get("/infos") { |result| yield result if block_given? }
-      end
-
-      def update_infos(metadata)
-        put("/infos", :metadata => metadata) { |result| yield result if block_given? }
-      end
-
-      ### Meetings - http://docs.ucengine.org/api.html#meeting ###
-
-      def meetings(status=nil)
-        get("/meeting/#{status}") { |result| yield result if block_given? }
-      end
-
-      def meeting(meeting)
-        get("/meeting/all/#{meeting}") { |result| yield result if block_given? }
-      end
-
-      def create_meeting(meeting, body={})
-        body.merge!(:meeting => meeting)
-        post("/meeting/all", body) { |result| yield result if block_given? }
-      end
-
-      def update_meeting(meeting, body={})
-        put("/meeting/all/#{meeting}", body) { |result| yield result if block_given? }
-      end
-
-      def delete_meeting(meeting)
-        delete("/meeting/all/#{meeting}") { |result| yield result if block_given? }
-      end
-
-      ### Rosters - http://docs.ucengine.org/api.html#join-a-meeting ###
-
-      def roster(meeting)
-        get("/meeting/all/#{meeting}/roster") { |result| yield result if block_given? }
-      end
-
-      def join_roster(meeting)
-        post("/meeting/all/#{meeting}/roster") { |result| yield result if block_given? }
-      end
-
-      def quit_roster(meeting, uid=nil)
-        delete("/meeting/all/#{meeting}/roster/#{uid || @uid}") { |result| yield result if block_given? }
-      end
-
-      ### Events - http://docs.ucengine.org/api.html#events ###
-
-      def events(meeting, params={})
-        params[:_async] = "no"
-        get("/event/#{meeting}", params) { |result| yield result if block_given? }
-      end
-
-      def subscribe(meeting, params={}, &blk)
-        params[:_async] = "lp"
-        recurse = Proc.new do |result|
-          next unless result
-          blk.call(result)
-          params[:start] = result.last["datetime"].to_i + 1
-          get("/event/#{meeting}", params, &recurse) if EM.reactor_running?
-        end
-        time do |time|
-          params[:start] = time
-          get("/event/#{meeting}", params, &recurse)
-        end
-      end
-
-      def publish(type, meeting=nil, metadata=nil)
-        body = { :type => type }
-        body[:metadata] = metadata if metadata
-        post("/event/#{meeting}", body) { |result| yield result if block_given? }
-      end
-
-      def search(params)
-        get("/search/event/", params) { |result| yield result if block_given? }
-      end
-
-    protected
-
-      def get(path, params={})
-        http_request(:get, path, :query => params) { |result| yield result }
-      end
-
-      def post(path, body=nil)
-        http_request(:post, path, :body => body) { |result| yield result }
-      end
-
-      def put(path, body=nil)
-        http_request(:put, path, :body => body) { |result| yield result }
-      end
-
-      def delete(path)
-        http_request(:delete, path) { |result| yield result }
-      end
-
-      def http_request(method, path, opts={})
-        opts[:query] ||= {}
-        opts[:query].merge!(:uid => uid, :sid => sid)
-        http = EM::HttpRequest.new(uce.url path).send(method, opts)
-        http.errback  { yield nil }
-        http.callback do
-          data = Yajl::Parser.parse(http.response)
-          yield data && data.has_key?("result") && data["result"]
-        end
-      end
-    end
-  end
-end
+require "em-ucengine/client"
+require "em-ucengine/client_nethttp"
+require "em-ucengine/client_em"

data/lib/em-ucengine/brick.rb

@@ -0,0 +1,177 @@
+require 'em-ucengine/utils'
+
+module EventMachine
+  module UCEngine
+    # This module allows to create a new brick for UCE. A brick may be either
+    # an independent entity or a composition of several bricks, resulting in a
+    # "meta-brick". On this case, only the meta-brick should be runned and only
+    # one connection to UCE will be used.
+    #
+    # When creating a brick, one would provide a bootstrap block and declare at
+    # least one event handler for the brick to manage. Handlers will be executed
+    # in the context of the Brick instance, so one may also write arbitrary code
+    # to be used in handlers blocks.
+    #
+    # See examples/bricks.rb and specs for more details.
+    module Brick
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      # Methods defined here will be made available as class methods on the
+      # class including Brick. Some class variables are pushed as well:
+      # +@@routes+, +@@bricks+, +@@bootstrap+.
+      module ClassMethods
+
+        def self.extended(klass)
+          klass.class_eval {
+            class_variable_set("@@routes", {})
+            class_variable_set("@@bricks", [])
+            class_variable_set("@@bootstrap", Proc.new {})
+          }
+        end
+
+        # Define a bootstrap block, which will be called before subscribing
+        # to events.
+        def bootstrap(&block)
+          class_variable_set("@@bootstrap", block)
+        end
+
+        # Define an event handler.
+        #
+        # @param [String] route
+        # @yield [Event] a callback to be executed when a matching event is received
+        # @example
+        #   on "my.event" do |event|
+        #     # do something
+        #   end
+        #
+        def on(route, &callback)
+          routes = class_variable_get("@@routes")
+          routes[route] ||= []
+          routes[route] << callback
+        end
+
+        # Add a sub-brick to the current brick.
+        #
+        # @param [Constant] Brick's class/module name
+        # @example
+        #   use MySpecializedBrick
+        def use(name)
+          class_variable_get("@@bricks") << name
+        end
+      end
+
+      attr_reader :uce
+
+      # Create a new brick.
+      #
+      # @param [Hash] config
+      def initialize(config={})
+        @uce = nil
+        @config = config
+      end
+
+      # Start EventMachine, initialize and start the brick.
+      #
+      # When composing several bricks, only the meta-brick should be
+      # runned.
+      #
+      # @param [Hash] config
+      def self.run(config={})
+        brick = self.new config
+        EM::run do
+          brick.start
+        end
+      end
+
+      # Start the brick.
+      #
+      # @param [EM::UCEngine::Client] uce (nil) shared instance of the client,
+      #   used by sub-bricks when composing so that only one UCE connection is
+      #   made and used
+      def start(uce=nil)
+        # Not in a sub-brick, connect to UCE.
+        if uce.nil?
+          @uce = EM::UCEngine::Client.new(@config[:host], @config[:port])
+          @uce.connect(@config[:name], @config[:credential]) do |err, uce|
+            @uce = uce
+            ready(bricks.map do |brick|
+              b = brick.new
+              b.start @uce
+              b
+            end)
+          end
+        else # Sub-brick, init with the shared UCE client instance.
+          @uce = uce
+          self.instance_eval &bootstrap
+        end
+      end
+
+      # Accessor for +@@bootstrap+.
+      def bootstrap
+        self.class.class_variable_get("@@bootstrap")
+      end
+
+      # Accessor for +@@routes+.
+      def routes
+        self.class.class_variable_get("@@routes")
+      end
+
+      # Accessor for +@@bricks+.
+      def bricks
+        self.class.class_variable_get("@@bricks")
+      end
+
+      # Wrapper around EventMachine's +Timer+. Pass it a block to be
+      # executed after a time range.
+      #
+      # @param [Integer] n time range in milliseconds
+      # @yield
+      def after(n, &block)
+        EventMachine::Timer.new(n, &block)
+      end
+
+      # Wrapper around EventMachine's +PeriodicTimer+. Pass it a block
+      # to be executed on a defined time frame.
+      #
+      # @param [Integer] n time range in milliseconds
+      # @yield
+      def every(n, &block)
+        EventMachine::PeriodicTimer.new(n, &block)
+      end
+
+      protected
+
+      # Hook sub-brick's declared event handlers into the event loop, by subscribing to
+      # UCE core.
+      #
+      # @param [Array<Brick>] brick_instances
+      def ready(bricks_instances)
+        r = routes.keys
+
+        # Bootstrap.
+        self.instance_eval &bootstrap
+
+        # Merge routes when composing bricks.
+        bricks_instances.each do |brick|
+          r += brick.routes.keys
+        end
+
+        # Subscribe to UCE for declared event handlers.
+        @uce.subscribe "", :type => r.uniq.join(',') do |err, events|
+          events.each do |event|
+            routes[event["type"]].each do |callback|
+              self.instance_exec(event, &callback)
+            end unless routes[event["type"]].nil?
+            bricks_instances.each do |brick|
+              brick.routes[event["type"]].each do |callback|
+                brick.instance_exec(event, &callback)
+              end unless brick.routes[event["type"]].nil?
+            end
+          end
+        end
+      end
+    end
+  end
+end