freeswitch-esl-client 0.1.0

data/lib/freeswitch-esl/outbound/session.rb

@@ -0,0 +1,218 @@
+module FreeswitchESL
+  module Outbound
+    # A live outbound call handed to us by FreeSWITCH.
+    #
+    # All the app methods are fire-and-forget: FreeSWITCH queues the commands
+    # on this channel and executes them in order, so
+    #
+    #   session.answer
+    #   session.play('ivr/ivr-welcome.wav')
+    #   session.hangup
+    #
+    # behaves as expected. Register event handlers with #on if you need to
+    # react to the call (DTMF, bridge, hangup...).
+    class Session
+      # Events an outbound socket has to subscribe to explicitly; without the
+      # `event` command FreeSWITCH delivers nothing.
+      DEFAULT_EVENTS = %w[
+        CHANNEL_CREATE CHANNEL_ANSWER CHANNEL_BRIDGE CHANNEL_UNBRIDGE
+        CHANNEL_HANGUP CHANNEL_HANGUP_COMPLETE CHANNEL_DESTROY CHANNEL_STATE
+        CHANNEL_EXECUTE CHANNEL_EXECUTE_COMPLETE DTMF RECORD_STOP PLAYBACK_STOP
+        BACKGROUND_JOB CUSTOM
+      ].freeze
+
+      attr_reader :uuid, :caller_id_number, :caller_id_name, :destination_number,
+                  :headers, :connection, :state, :hangup_cause
+
+      def initialize(conn, headers)
+        @connection = conn
+        @headers = headers || {}
+        @uuid = @headers['Unique-ID']
+        @caller_id_number = @headers['Caller-Caller-ID-Number'] || @headers['variable_caller_id_number']
+        @caller_id_name = @headers['Caller-Caller-ID-Name'] || @headers['variable_caller_id_name']
+        @destination_number = @headers['Caller-Destination-Number'] ||
+                              @headers['variable_destination_number'] ||
+                              @headers['Caller-ANI']
+        @state = @headers['Channel-State']
+        @context = @headers['Caller-Context']
+        @answered = false
+        @ended = false
+        @handlers = Hash.new { |h, k| h[k] = [] }
+      end
+
+      # ---------------------------------------------------------------- events
+
+      # session.on('CHANNEL_ANSWER') { |event| ... }
+      # session.on('DTMF') { |event| ... }
+      # session.on('*') { |event| ... }
+      def on(event_name, &block)
+        @handlers[event_name.to_s.upcase] << block
+        self
+      end
+
+      def handle_event(event, _raw_body = nil)
+        name = event['Event-Name'].to_s.upcase
+        @state = event['Channel-State'] if event['Channel-State']
+
+        case name
+        when 'CHANNEL_ANSWER'
+          @answered = true
+        when 'CHANNEL_HANGUP_COMPLETE'
+          @hangup_cause = event['Hangup-Cause']
+          @ended = true
+        when 'CHANNEL_DESTROY'
+          @ended = true
+        end
+
+        Array(@handlers[name]).each { |handler| safe_call(handler, event) }
+        Array(@handlers['*']).each { |handler| safe_call(handler, event) }
+        self
+      end
+
+      def safe_call(handler, event)
+        handler.call(event)
+      rescue StandardError => e
+        connection&.logger&.error "[FS-ESL OUTBOUND] handler error: #{e.class}: #{e.message}"
+      end
+
+      def answered?
+        @answered
+      end
+
+      def ended?
+        @ended
+      end
+
+      # --------------------------------------------------------------- commands
+
+      def answer
+        execute('answer')
+        @answered = true
+        self
+      end
+
+      def pre_answer
+        execute('pre_answer')
+        self
+      end
+
+      def ring_ready
+        execute('ring_ready')
+        self
+      end
+
+      def hangup(cause = 'NORMAL_CLEARING')
+        execute('hangup', cause)
+        self
+      end
+
+      def play(file)
+        execute('playback', file)
+        self
+      end
+
+      def play_and_get_digits(min = 1, max = 10, tries = 3, timeout = 3000, terminators = '#',
+                              file = 'silence_stream://10', invalid_file = nil, var_name = 'digits',
+                              digit_timeout = 3000)
+        args = [
+          min, max, tries, timeout, terminators, file,
+          invalid_file || 'silence_stream://150', var_name, digit_timeout
+        ].join(' ')
+        execute('play_and_get_digits', args)
+        self
+      end
+
+      def read(min = 1, max = 10, file = 'silence_stream://10', timeout = 3000,
+               terminators = '#', var_name = 'digits')
+        execute('read', [min, max, file, var_name, timeout, terminators].join(' '))
+        self
+      end
+
+      def record(file, limit = 3600, silence_thresh = 200, silence_hits = 5)
+        execute('record', [file, limit, silence_thresh, silence_hits].join(' '))
+        self
+      end
+      alias record_file record
+
+      def speak(text, engine: nil, voice: nil)
+        if engine && voice
+          execute('speak', "#{engine}|#{voice}|#{text}")
+        else
+          execute('speak', text)
+        end
+        self
+      end
+
+      def bridge(dialstring)
+        execute('bridge', dialstring)
+        self
+      end
+
+      def transfer(extension, dialplan: 'XML', context: 'default')
+        execute('transfer', "#{extension} #{dialplan} #{context}")
+        self
+      end
+
+      def park
+        execute('park')
+        self
+      end
+
+      def set(name, value)
+        execute('set', "#{name}=#{value}")
+        self
+      end
+
+      def export(name, value)
+        execute('export', "#{name}=#{value}")
+        self
+      end
+
+      def unset(name)
+        execute('unset', name)
+        self
+      end
+
+      def sleep(ms)
+        execute('sleep', ms.to_s)
+        self
+      end
+
+      def flush_dtmf
+        execute('flush_dtmf')
+        self
+      end
+
+      def send_dtmf(dtmf)
+        execute('send_dtmf', dtmf)
+        self
+      end
+
+      def execute(app, args = nil, &block)
+        connection.execute(app, args, &block)
+        self
+      end
+
+      def api(command, &block)
+        connection.api(command, &block)
+      end
+
+      def bgapi(command, &block)
+        connection.bgapi(command, &block)
+      end
+
+      def send_command(command)
+        connection.send_command(command)
+      end
+
+      # ---------------------------------------------------------------- helpers
+
+      def variable(name)
+        @headers["variable_#{name}"] || @headers[name]
+      end
+      alias [] variable
+
+      def close; end
+    end
+  end
+end

data/lib/freeswitch-esl/parser.rb

@@ -0,0 +1,106 @@
+module FreeswitchESL
+  # Parses ESL header blocks ("Key: value" lines) and reassembles complete
+  # frames from a byte stream.
+  #
+  # ESL frames are always:
+  #
+  #   Key: value\n
+  #   ...
+  #   \n
+  #   <body of Content-Length bytes>
+  #
+  # The body can itself contain blank lines (api/response output, event bodies),
+  # so splitting the stream on "\n\n" is not correct — Content-Length must be
+  # honoured.
+  class Parser
+    class << self
+      def parse_headers(block)
+        headers = {}
+        return headers if block.nil?
+
+        block.split(/\r?\n/).each do |line|
+          next if line.empty?
+          next unless line.include?(':')
+
+          key, value = line.split(':', 2)
+          headers[key.strip] = value.to_s.strip
+        end
+        headers
+      end
+
+      # Splits an event body into [headers, body]. FreeSWITCH events embed their
+      # own header block and, for BACKGROUND_JOB, the command output follows a
+      # blank line.
+      def parse_event(raw)
+        raw = raw.to_s
+        idx = raw.index("\n\n")
+        return [parse_headers(raw), ''] unless idx
+
+        [parse_headers(raw[0...idx]), raw[(idx + 2)..] || '']
+      end
+
+      # Backwards compatible helper: parse a single complete frame string.
+      def parse_frame(frame)
+        frame = frame.to_s
+        idx = frame.index("\n\n")
+        if idx
+          headers = parse_headers(frame[0...idx])
+          body = frame[(idx + 2)..] || ''
+        else
+          headers = parse_headers(frame)
+          body = ''
+        end
+
+        {
+          headers: headers,
+          body: body,
+          content_type: headers['Content-Type'] || headers['content-type']
+        }
+      end
+    end
+  end
+
+  # Incremental ESL frame reassembler.
+  #
+  #   framer = FreeswitchESL::Framer.new
+  #   framer << data
+  #   framer.each_frame { |frame| ... }
+  class Framer
+    def initialize
+      @buffer = +''.b
+    end
+
+    def <<(data)
+      @buffer << data.to_s.b
+      self
+    end
+
+    def each_frame
+      loop do
+        header_end = @buffer.index("\n\n")
+        break unless header_end
+
+        headers = Parser.parse_headers(@buffer.byteslice(0, header_end))
+        body_start = header_end + 2
+        length = headers['Content-Length'].to_i
+        length = 0 if length.negative?
+
+        if length.zero?
+          @buffer = @buffer.byteslice(body_start..) || +''.b
+          yield({ headers: headers, body: +'', content_type: headers['Content-Type'] })
+          next
+        end
+
+        break if @buffer.bytesize < body_start + length
+
+        body = @buffer.byteslice(body_start, length)
+        @buffer = @buffer.byteslice((body_start + length)..) || +''.b
+        yield({ headers: headers, body: body, content_type: headers['Content-Type'] })
+      end
+    end
+
+    def empty?
+      @buffer.empty?
+    end
+  end
+end

data/lib/freeswitch-esl/response.rb

@@ -0,0 +1,61 @@
+module FreeswitchESL
+  class Response
+    attr_reader :headers, :body, :raw
+
+    def initialize(headers = {}, body = '', raw = '')
+      @headers = headers || {}
+      @body = body || ''
+      @raw = raw
+    end
+
+    # bgapi responses carry the command output in the body and have no
+    # Reply-Text header, so both are taken into account.
+    def success?
+      reply = reply_text.to_s
+      return false if reply.start_with?('-')
+      return true if reply.start_with?('+OK')
+
+      !body.to_s.lstrip.start_with?('-')
+    end
+
+    def error?
+      !success?
+    end
+
+    def reply_text
+      @headers['Reply-Text'] || @headers['reply-text'] || first_body_line
+    end
+
+    def job_uuid
+      @headers['Job-UUID'] || @headers['job-uuid']
+    end
+
+    def event_name
+      @headers['Event-Name']
+    end
+
+    # UUID returned by `originate` (`+OK <uuid>`) — nil for other commands.
+    def uuid
+      reply_text.to_s[/\+OK\s+([0-9a-f-]{36})/, 1]
+    end
+
+    def [](key)
+      @headers[key]
+    end
+
+    # The command output (alias of #body, reads better for api/bgapi).
+    def output
+      body
+    end
+
+    def to_s
+      body.to_s
+    end
+
+    private
+
+    def first_body_line
+      body.to_s.lines.first.to_s.strip
+    end
+  end
+end

data/lib/freeswitch-esl/version.rb

@@ -0,0 +1,3 @@
+module FreeswitchESL
+  VERSION = '0.1.0'
+end

data/lib/freeswitch-esl-client.rb

@@ -0,0 +1,4 @@
+# The gem is published as `freeswitch-esl-client` (the name `freeswitch-esl` was
+# already taken on RubyGems), while the library itself is still called
+# `freeswitch-esl`. Both require paths load the same code.
+require 'freeswitch-esl'

data/lib/freeswitch-esl.rb

@@ -0,0 +1,25 @@
+require 'freeswitch-esl/version'
+require 'freeswitch-esl/errors'
+require 'freeswitch-esl/parser'
+require 'freeswitch-esl/response'
+require 'freeswitch-esl/connection'
+require 'freeswitch-esl/client'
+require 'freeswitch-esl/outbound/connection'
+require 'freeswitch-esl/outbound/session'
+require 'freeswitch-esl/outbound/server'
+
+module FreeswitchESL
+  class << self
+    def new(**options)
+      Client.new(**options)
+    end
+
+    def outbound_server(**options, &block)
+      Outbound::Server.new(**options, &block)
+    end
+
+    def start_outbound_server(**options, &block)
+      Outbound::Server.new(**options, &block).start
+    end
+  end
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: freeswitch-esl-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michael
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: eventmachine
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.7
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |
+  EventMachine-based client for the FreeSWITCH Event Socket Layer (mod_event_socket).
+  Supports inbound mode (connect to port 8021, subscribe to events, run api/bgapi,
+  auto-reconnect) and outbound mode (an embedded TCP server that FreeSWITCH dials into
+  with the socket application, so call control lives in Ruby instead of dialplan XML).
+  Includes a binary-safe ESL frame parser, an originate helper covering FreeSWITCH
+  variable scopes and positional arguments, and per-channel outbound sessions.
+email:
+- michael@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- freeswitch-esl-client.gemspec
+- lib/freeswitch-esl-client.rb
+- lib/freeswitch-esl.rb
+- lib/freeswitch-esl/client.rb
+- lib/freeswitch-esl/connection.rb
+- lib/freeswitch-esl/errors.rb
+- lib/freeswitch-esl/outbound/connection.rb
+- lib/freeswitch-esl/outbound/server.rb
+- lib/freeswitch-esl/outbound/session.rb
+- lib/freeswitch-esl/parser.rb
+- lib/freeswitch-esl/response.rb
+- lib/freeswitch-esl/version.rb
+homepage: https://github.com/miclast/freeswitch-esl-client
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/miclast/freeswitch-esl-client
+  changelog_uri: https://github.com/miclast/freeswitch-esl-client/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/miclast/freeswitch-esl-client/issues
+  documentation_uri: https://www.rubydoc.info/gems/freeswitch-esl-client
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: Ruby client for the FreeSWITCH Event Socket Layer (inbound and outbound).
+test_files: []