ruby_fs 0.1.0 → 0.2.0

data/CHANGELOG.md

@@ -1,4 +1,11 @@
 # develop
 
+# 0.2.0
+  * Feature: Common command helper methods
+  * Feature: Trace level logging & easy logging override
+  * Feature: Clean shutdown
+  * Feature: Separate stream creation and connection/execution
+  * API Documentation
+
 # 0.1.0
   * Initial release

data/README.md

@@ -8,9 +8,13 @@ RubyFS is a FreeSWITCH EventSocket client library in Ruby and based on Celluloid
 ```ruby
 require 'ruby_fs'
 
-client = RubyFS::Stream.new '127.0.0.1', 8021, 'ClueCon', lambda { |e| p e }
+stream = RubyFS::Stream.new '127.0.0.1', 8021, 'ClueCon', lambda { |e| p e }
 
-client.start
+stream.run
+
+stream.api 'originate sofia/mydomain.com/ext@yourvsp.com 1000' do |response|
+  puts "Originate response was #{response.inspect}"
+end
 ```
 
 ## Links

data/lib/ruby_fs/event.rb

@@ -2,6 +2,8 @@ require 'ruby_fs/response'
 
 module RubyFS
   class Event < Response
+    #
+    # @return [String[ The name of the event
     def event_name
       content[:event_name]
     end

data/lib/ruby_fs/stream.rb

@@ -19,63 +19,139 @@ module RubyFS
 
     def initialize(host, port, secret, event_callback, events = true)
       super()
-      @secret, @event_callback, @events = secret, event_callback, events
+      @host, @port, @secret, @event_callback, @events = host, port, secret, event_callback, events
       @command_callbacks = []
-      logger.debug "Starting up..."
       @lexer = Lexer.new method(:receive_request)
-      @socket = TCPSocket.from_ruby_socket ::TCPSocket.new(host, port)
-      post_init
     end
 
     [:started, :stopped, :ready].each do |state|
       define_method("#{state}?") { @state == state }
     end
 
+    #
+    # Connect to the server and begin handling data
     def run
+      logger.debug "Starting up..."
+      @socket = TCPSocket.from_ruby_socket ::TCPSocket.new(@host, @port)
+      post_init
       loop { receive_data @socket.readpartial(4096) }
-    rescue EOFError
+    rescue EOFError, IOError
       logger.info "Client socket closed!"
-      current_actor.terminate!
-    end
-
-    def post_init
-      @state = :started
-      fire_event Connected.new
+      terminate
     end
 
+    #
+    # Send raw string data to the FS server
+    #
+    # @param [#to_s] data the data to send over the socket
     def send_data(data)
-      logger.debug "[SEND] #{data.to_s}"
+      logger.trace "[SEND] #{data.to_s}"
       @socket.write data.to_s
     end
 
+    #
+    # Send a FreeSWITCH command with options and a callback for the response
+    #
+    # @param [#to_s] command the command to run
+    # @param [optional, Hash] options the command's options, where keys have _ substituted for -
+    #
+    # @yield [response] Handle the command's response
+    # @yieldparam [RubyFS::Response] response the command's response object
     def command(command, options = {}, &block)
       @command_callbacks << (block || lambda { |reply| logger.debug "Reply to a command (#{command}) without a callback: #{reply.inspect}" })
       string = "#{command}\n"
       options.each_pair do |key, value|
-        string << "#{key.to_s.gsub '_', '-'}: #{value}\n"
+        string << "#{key.to_s.gsub '_', '-'}: #{value}\n" if value
       end
       string << "\n"
       send_data string
     end
 
-    def receive_data(data)
-      logger.debug "[RECV] #{data}"
-      @lexer << data
+    #
+    # Send an API action
+    #
+    # @param [#to_s] action the API action to execute
+    #
+    # @yield [response] Handle the command's response
+    # @yieldparam [RubyFS::Response] response the command's response object
+    def api(action, &block)
+      command "api #{action}", &block
+    end
+
+    #
+    # Send an API action in the background
+    #
+    # @param [#to_s] action the API action to execute
+    #
+    # @yield [response] Handle the command's response
+    # @yieldparam [RubyFS::Response] response the command's response object
+    def bgapi(action, &block)
+      command "bgapi #{action}", &block
+    end
+
+    #
+    # Send a message to a particular call
+    #
+    # @param [#to_s] call the call ID to send the message to
+    # @param [optional, Hash] options the message options
+    #
+    # @yield [response] Handle the message's response
+    # @yieldparam [RubyFS::Response] response the message's response object
+    def sendmsg(call, options = {}, &block)
+      command "SendMsg #{call}", options, &block
+    end
+
+    #
+    # Execute an application on a particular call
+    #
+    # @param [#to_s] call the call ID on which to execute the application
+    # @param [#to_s] appname the app to execute
+    # @param [optional, String] options the application options
+    #
+    # @yield [response] Handle the application's response
+    # @yieldparam [RubyFS::Response] response the application's response object
+    def application(call, appname, options = nil, &block)
+      sendmsg call, :call_command => 'execute', :execute_app_name => appname, :execute_app_arg => options, &block
+    end
+
+    #
+    # Shutdown the stream and disconnect from the socket
+    def shutdown
+      @socket.close if @socket
     end
 
+    # @private
     def finalize
       logger.debug "Finalizing stream"
-      @socket.close if @socket
       @state = :stopped
       fire_event Disconnected.new
     end
 
+    #
+    # Fire an event to the specified callback
+    #
+    # @param [Object] event the event to fire
     def fire_event(event)
       @event_callback.call event
     end
 
+    #
+    # The stream's logger object
     def logger
-      Logger
+      super
+    rescue
+      @logger ||= begin
+        logger = Logger
+        logger.define_singleton_method :trace, logger.method(:debug)
+        logger
+      end
+    end
+
+    private
+
+    def receive_data(data)
+      logger.trace "[RECV] #{data}"
+      @lexer << data
     end
 
     def receive_request(headers, content)
@@ -101,5 +177,10 @@ module RubyFS
         end
       end
     end
+
+    def post_init
+      @state = :started
+      fire_event Connected.new
+    end
   end
 end

data/lib/ruby_fs/version.rb

@@ -1,3 +1,3 @@
 module RubyFS
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/spec/ruby_fs/stream_spec.rb

@@ -30,6 +30,7 @@ module RubyFS
       s = ServerMock.new '127.0.0.1', server_port, mock_target
       @stream = Stream.new '127.0.0.1', server_port, secret, lambda { |m| client.message_received m }, events
       @stream.run!
+      sleep 0.1
       fake_client.call s if fake_client.respond_to? :call
       s.join
       @stream.join
@@ -50,7 +51,7 @@ module RubyFS
         expect_connected_event
         expect_disconnected_event
         mocked_server(0) do |val, server|
-          @stream.started?.should be_true
+          @stream.should be_started
         end
       end
 
@@ -61,6 +62,15 @@ module RubyFS
           val.should == "foo"
         end
       end
+
+      it "can be shut down" do
+        expect_connected_event
+        expect_disconnected_event
+        mocked_server(0, lambda { |server| @stream.shutdown }) do |val, server|
+          @stream.should be_started
+        end
+        @stream.should_not be_alive
+      end
     end
 
     it 'sends events to the client when the stream is ready' do
@@ -158,6 +168,94 @@ Reply-Text: +OK accepted
 one: 1
 foo-bar: doo_dah
 
+)
+      end
+    end
+
+    it "can send API commands with response callbacks" do
+      expect_connected_event
+      expect_disconnected_event
+      handler = mock
+      handler.expects(:call).once.with CommandReply.new(:content_type => 'command/reply', :reply_text => '+OK accepted')
+      mocked_server(1, lambda { |server| @stream.api('foo') { |reply| handler.call reply } }) do |val, server|
+        val.should == "api foo\n\n"
+        server.send_data %Q(
+Content-Type: command/reply
+Reply-Text: +OK accepted
+
+)
+      end
+    end
+
+    it "can send background API commands with response callbacks" do
+      expect_connected_event
+      expect_disconnected_event
+      handler = mock
+      handler.expects(:call).once.with CommandReply.new(:content_type => 'command/reply', :reply_text => '+OK Job-UUID: 4e8344be-c1fe-11e1-a7bf-cf9911a69d1e', :job_uuid => '4e8344be-c1fe-11e1-a7bf-cf9911a69d1e')
+      mocked_server(1, lambda { |server| @stream.bgapi('foo') { |reply| handler.call reply } }) do |val, server|
+        val.should == "bgapi foo\n\n"
+        server.send_data %Q(
+Content-Type: command/reply
+Reply-Text: +OK Job-UUID: 4e8344be-c1fe-11e1-a7bf-cf9911a69d1e
+Job-UUID: 4e8344be-c1fe-11e1-a7bf-cf9911a69d1e
+
+)
+      end
+    end
+
+    it "can send messages to calls with options and response callbacks" do
+      expect_connected_event
+      expect_disconnected_event
+      handler = mock
+      handler.expects(:call).once.with CommandReply.new(:content_type => 'command/reply', :reply_text => '+OK accepted')
+      mocked_server(1, lambda { |server| @stream.sendmsg('aUUID', :call_command => 'execute') { |reply| handler.call reply } }) do |val, server|
+        val.should == %Q(SendMsg aUUID
+call-command: execute
+
+)
+        server.send_data %Q(
+Content-Type: command/reply
+Reply-Text: +OK accepted
+
+)
+      end
+    end
+
+    it "can execute applications on calls without options but with response callbacks" do
+      expect_connected_event
+      expect_disconnected_event
+      handler = mock
+      handler.expects(:call).once.with CommandReply.new(:content_type => 'command/reply', :reply_text => '+OK accepted')
+      mocked_server(1, lambda { |server| @stream.application('aUUID', 'answer') { |reply| handler.call reply } }) do |val, server|
+        val.should == %Q(SendMsg aUUID
+call-command: execute
+execute-app-name: answer
+
+)
+        server.send_data %Q(
+Content-Type: command/reply
+Reply-Text: +OK accepted
+
+)
+      end
+    end
+
+    it "can execute applications on calls with options and response callbacks" do
+      expect_connected_event
+      expect_disconnected_event
+      handler = mock
+      handler.expects(:call).once.with CommandReply.new(:content_type => 'command/reply', :reply_text => '+OK accepted')
+      mocked_server(1, lambda { |server| @stream.application('aUUID', 'playback', '/tmp/test.wav') { |reply| handler.call reply } }) do |val, server|
+        val.should == %Q(SendMsg aUUID
+call-command: execute
+execute-app-name: playback
+execute-app-arg: /tmp/test.wav
+
+)
+        server.send_data %Q(
+Content-Type: command/reply
+Reply-Text: +OK accepted
+
 )
       end
     end

data/spec/support/mock_server.rb

@@ -26,6 +26,8 @@ class ServerMock
     _, port, host = socket.peeraddr
     Logger.debug "MockServer Received connection from #{host}:#{port}"
     loop { receive_data socket.readpartial(4096) }
+  rescue EOFError
+    Logger.debug "Connection from #{host}:#{port} closed"
   end
 
   def receive_data(data)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_fs
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-29 00:00:00.000000000 Z
+date: 2012-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: uuidtools
@@ -295,7 +295,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2481817772884138362
+      hash: 3148609615352772925
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -304,7 +304,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2481817772884138362
+      hash: 3148609615352772925
 requirements: []
 rubyforge_project: ruby_fs
 rubygems_version: 1.8.24