fcs 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in fcs.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Mark Quezada
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,90 @@
+# FCS: FreeSWITCH Command Socket
+
+FCS is a lightweight api wrapper for [FreeSWITCH's event socket][event_socket].
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'fcs'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install fcs
+
+## Usage
+
+Using FCS is easy and intuitive. After initializing, dispatch commands to
+FreeSWITCH using the `.dispatch!` method. See the examples below.
+
+### Initializing
+
+    fs = FCS.new(
+      remote_host: 'localhost',
+      remote_port: '8021'
+    )
+
+### Authorizing
+
+    fs.auth('ClueCon').dispatch!
+
+### Examples
+
+FCS is basically a naive command builder for freeSWITCH. You build commands by
+chaining method calls that match FreeSWITCH's [mod_commands][mod_commands] like
+so:
+
+    request = fs.api.originate 'sofia/mydomain.com 1000'
+    response = request.dispatch!
+
+This is equivalent:
+
+    response = fs.api.originate('sofia/mydomain.com', '1000').dispatch!
+
+Both these commands result in this api command being sent to FreeSWITCH:
+
+    api originate sofia/mydomain.com 1000
+
+These two commands are also equivalent:
+
+    fs.api.uuid_getvar('fs_id', 'varname').dispatch!
+    fs.api.uuid_getvar('fs_id').varname.dispatch!
+
+This flexible syntax allows you to build commands in a very natural way that
+mimics FreeSWITCH's command syntax.
+
+A more complex example:
+
+    fs.sendmsg(fs_id).call_command(:execute).execute_app_name(:playback).execute_app_arg('/tmp/sound.wav').loops(-1).event_lock(true)
+
+The `sendmsg` command takes an optional uuid parameter. Since `execute` is so
+common, there's a helper method that shortens the above to:
+
+    fs.sendmsg(fs_id).execute(:playback, '/tmp/sound.wav').loops(-1).event_lock(true)
+
+Pretty much any api method should work out of the box. A few more examples:
+
+    fs.api.sched_api('+20').originate('sofia/external &echo()').dispatch!
+    fs.api.uuid_send_dtmf(fs_id, 'W0W011W@250')
+    fs.api.uuid_kill(fs_id, 'NORMAL_CLEARING')
+    fs.api.sched_broadcast('+20', fs_id, 'commercial.wav').aleg
+    fs.bgapi.originate 'sofia/mydomain.com'    
+
+Calling `dispatch!` at the end of the chain is necessary in order to dispatch
+the command to FreeSWITCH. Otherwise you'll get back a `Request` object. 
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+
+[event_socket]: http://wiki.freeswitch.org/wiki/Event_Socket
+[mod_commands]: http://wiki.freeswitch.org/wiki/Mod_commands

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/fcs.gemspec

@@ -0,0 +1,17 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/fcs/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Mark Quezada"]
+  gem.email         = ["mark@mirthlab.com"]
+  gem.description   = %q{Library for interacting with FreeSWITCH via event socket.}
+  gem.summary       = %q{Library for interacting with FreeSWITCH via event socket.}
+  gem.homepage      = "https://github.com/mirthlab/fcs"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "fcs"
+  gem.require_paths = ["lib"]
+  gem.version       = FCS::VERSION
+end

data/lib/fcs.rb

@@ -0,0 +1,26 @@
+require 'fcs/version'
+require 'fcs/config'
+require 'fcs/client'
+
+module FCS
+  extend Config
+  class << self
+    # Alias for FCS::Client.new
+    #
+    # @return [FCS::Client]
+    def new(options={})
+      FCS::Client.new(options)
+    end
+
+    # Delegate to FCS::Client
+    def method_missing(method, *args, &block)
+      return super unless new.respond_to?(method)
+      new.send(method, *args, &block)
+    end
+
+    # Include FCS::Client methods in respond_to?
+    def respond_to?(method, include_private=false)
+      new.respond_to?(method, include_private) || super(method, include_private)
+    end
+  end
+end

data/lib/fcs/client.rb

@@ -0,0 +1,53 @@
+require 'socket'
+require 'fcs/config'
+require 'fcs/response'
+require 'fcs/request'
+require 'fcs/string_request'
+require 'fcs/hash_request'
+require 'fcs/sendmsg_request'
+
+module FCS
+  class Client
+    attr_accessor *Config::VALID_OPTIONS_KEYS
+
+    # Initialize a new Client object
+    def initialize(attrs={})
+      attrs = FCS.options.merge(attrs)
+      Config::VALID_OPTIONS_KEYS.each do |key|
+        instance_variable_set("@#{key}".to_sym, attrs[key])
+      end
+
+      connect if @auto_connect
+    end
+
+    def connect
+      unless @socket
+        @socket = TCPSocket.open(@remote_host, @remote_port, @local_host, @local_port)
+        Response.new(@socket).parse_response
+      end
+      @socket
+    end
+
+    # Delgate api call to Request
+    def method_missing(method, *args, &block)
+      klass = class_for_api_command(method)
+
+      return klass.new(@socket).send(method, *args, &block) if klass
+      super(method, *args, &block)
+    end
+
+    private
+
+    def class_for_api_command(method)
+      if method == :sendmsg
+        SendmsgRequest
+      elsif Request::VALID_HASH_COMMANDS.include?(method)
+        HashRequest
+      elsif Request::VALID_STRING_COMMANDS.include?(method)
+        StringRequest
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/fcs/config.rb

@@ -0,0 +1,57 @@
+module FCS
+  module Config
+    # Remote host used if none is set
+    DEFAULT_REMOTE_HOST = 'http://127.0.0.1'
+
+    # Remote port used if none is set
+    DEFAULT_REMOTE_PORT = '8021'
+
+    # Local host used if none is set
+    DEFAULT_LOCAL_HOST = nil
+
+    # Local port used if none is set
+    DEFAULT_LOCAL_PORT = nil
+
+    # Auto connect value used if none is set
+    DEFAULT_AUTO_CONNECT = true
+
+    # An array of valid keys in the options hash when configuring a {FCS::Client}
+    VALID_OPTIONS_KEYS = [
+      :remote_host,
+      :remote_port,
+      :local_host,
+      :local_port,
+      :auto_connect
+    ]
+
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    # When this module is extended, set all configuration options to their default value
+    def self.extended(base)
+      base.reset
+    end
+
+    # Convenience method to allow configuration options to be set in a block
+    def configure
+      yield self
+      self
+    end
+
+    # Create a hash of options and their values
+    def options
+      options = {}
+      VALID_OPTIONS_KEYS.each {|k| options[k] = send(k)}
+      options
+    end
+
+    # Reset all configuration options to defaults
+    def reset
+      self.remote_host  = DEFAULT_REMOTE_HOST
+      self.remote_port  = DEFAULT_REMOTE_PORT
+      self.local_host   = DEFAULT_LOCAL_HOST
+      self.local_port   = DEFAULT_LOCAL_PORT
+      self.auto_connect = DEFAULT_AUTO_CONNECT
+      self
+    end
+  end
+end

data/lib/fcs/hash_request.rb

@@ -0,0 +1,32 @@
+require 'fcs/request'
+
+module FCS
+  class HashRequest < Request
+    def initialize(socket)
+      super(socket)
+      @command_type = ''
+      @command_value = ''
+      @params = {}
+    end
+
+    def generate_command
+      # TODO if app args is longer than 2048 octet limit, use alternate format
+      cmd = "#{@command_type} #{@command_value}\n"
+      cmd << @params.map do |k,v|
+        "#{k.gsub(/_/, '-')}: #{v}"
+      end.join("\n") if not @params.empty?
+    end
+
+    def update_command(method, *args, &block)
+      arg_string = args.map(&:to_s).join(' ') || ''
+
+      # assume the first call here is the command type and value
+      if @command_type.empty?
+        @command_type = method.to_s
+        @command_value = arg_string
+      else
+        @params[method.to_s] = arg_string
+      end
+    end
+  end
+end

data/lib/fcs/request.rb

@@ -0,0 +1,44 @@
+require 'fcs/response'
+
+module FCS
+  class Request
+    VALID_HASH_COMMANDS = [:sendmsg, :sendevent]
+    VALID_STRING_COMMANDS = [:api, :bgapi, :event, :myevents, :divert_events,
+                             :filter, :exit, :auth, :log, :nolog, :nixevent,
+                             :noevents]
+    VALID_COMMANDS = VALID_HASH_COMMANDS + VALID_STRING_COMMANDS
+
+    def initialize(socket, response_class=Response)
+      @socket = socket
+      @response_class = response_class
+    end
+
+    def generate_command
+      # defined in the subclasses
+      raise NotImplementedError
+    end
+
+    def update_command(method, *args, &block)
+      # defined in the subclasses
+      raise NotImplementedError
+    end
+
+    def dispatch!
+      dispatch_raw!("#{generate_command}\n\n")
+    end
+
+    def dispatch_raw!(command)
+      @socket.write(command)
+      @response_class.new(@socket).parse_and_respond
+    end
+
+    def method_missing(method, *args, &block)
+      if @response_class.method_defined?(method)
+        dispatch!.send(method, *args, &block)
+      else
+        update_command(method, *args, &block)
+        self
+      end
+    end
+  end
+end

data/lib/fcs/response.rb

@@ -0,0 +1,72 @@
+module FCS
+  class Response
+    attr_reader :headers, :content
+
+    def initialize(socket)
+      @socket = socket
+      @headers = ''
+      @content = ''
+      @content_length = 0
+    end
+
+    def parse_and_respond
+      parse_response
+      self
+    end
+
+    def parse_response
+      capture_headers
+      capture_content
+      puts self.inspect
+    end
+
+    def ok?
+      raw_reply.start_with?('+OK') or (@content_length and not error?)
+    end
+
+    def error?
+      raw_reply.start_with?('-ERR')
+    end
+
+    def reply
+      /^(?:\+OK|\-ERR)\s?(.*)/.match(raw_reply) ? Regexp.last_match(1) : raw_reply
+    end
+
+    private
+
+    def raw_headers=(raw_headers)
+      @headers = headers_2_hash(raw_headers.split("\n"))
+      @headers.each {|k,v| v.chomp! if v.respond_to? :chomp!}
+    end
+
+    def raw_content=(raw_content)
+      @content = raw_content.chomp!
+    end
+
+    def raw_reply
+      @content_length > 0 ? @content : @headers[:reply_text]
+    end
+
+    def capture_headers
+      self.raw_headers = @socket.readline("\n\n")
+      @content_length = @headers[:content_length].to_i
+    end
+
+    def capture_content
+      self.raw_content = @socket.read(@content_length) if @content_length > 0
+    end
+
+    # Stolen from eventmachine:
+    # https://github.com/eventmachine/eventmachine/blob/master/lib/em/protocols/header_and_content.rb
+    def headers_2_hash hdrs
+      hash = {}
+      hdrs.each do |h|
+        if /\A([^\s:]+)\s*:\s*/ =~ h
+          tail = $'.dup
+          hash[ $1.downcase.gsub(/-/,"_").intern ] = tail
+        end
+      end
+      hash
+    end
+  end
+end

data/lib/fcs/sendmsg_request.rb

@@ -0,0 +1,10 @@
+require 'fcs/hash_request'
+
+module FCS
+  class SendmsgRequest < HashRequest
+    # convenience method
+    def execute(app, *args)
+      self.call_command(:execute).execute_app_name(app).execute_app_arg(args.map(&:to_s).join(' '))
+    end
+  end
+end

data/lib/fcs/string_request.rb

@@ -0,0 +1,19 @@
+require 'fcs/request'
+
+module FCS
+  class StringRequest < Request
+    def initialize(socket)
+      super(socket)
+      @commands = []
+    end
+
+    def generate_command
+      @commands.join(' ')
+    end
+
+    def update_command(method, *args, &block)
+      @commands << method.to_s
+      @commands = @commands + args.map(&:to_s)
+    end
+  end
+end

data/lib/fcs/version.rb

@@ -0,0 +1,3 @@
+module FCS
+  VERSION = "0.0.1"
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: fcs
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Mark Quezada
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-22 00:00:00.000000000 Z
+dependencies: []
+description: Library for interacting with FreeSWITCH via event socket.
+email:
+- mark@mirthlab.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- fcs.gemspec
+- lib/fcs.rb
+- lib/fcs/client.rb
+- lib/fcs/config.rb
+- lib/fcs/hash_request.rb
+- lib/fcs/request.rb
+- lib/fcs/response.rb
+- lib/fcs/sendmsg_request.rb
+- lib/fcs/string_request.rb
+- lib/fcs/version.rb
+homepage: https://github.com/mirthlab/fcs
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: Library for interacting with FreeSWITCH via event socket.
+test_files: []