freeswitch-esl-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a50fbec915b234efd22756ad6b06bfbebf8df7598e5a5db71f66a3af37713bf0
+  data.tar.gz: cf7f08880ca0e01f42278f03c24ee6f55bbd45fbe4de8749e09ac60a4ffc7eb6
+SHA512:
+  metadata.gz: c07ab1867f846fa12bdf11f8fe7319ab520711735cb91cc98bab480836a98559f927f2bd8680dec6c000c41074f2304649c8f4e001f1904c38f29b9dba9f2d7f
+  data.tar.gz: 70bff8ac50d2ce9d3486dd4262c727c82c35e32c5deacfc261f5ceada8999fd12400d988cf56ef5fb29edc03f853bd0c6c4084447ca9438f40c3ec03a6eea869

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-29
+
+First public release. Verified live against FreeSWITCH 1.11 and Asterisk 20 in Docker,
+on Ruby 3.2+ and 4.0.
+
+The gem is published as `freeswitch-esl-client` because `freeswitch-esl` was already
+taken on RubyGems. The library name is unchanged: `require 'freeswitch-esl'` and the
+`FreeswitchESL` namespace. `require 'freeswitch-esl-client'` is available as a shim.
+
+### Added
+
+- **Inbound mode** — `FreeswitchESL::Client` connects to `mod_event_socket` (default
+  `127.0.0.1:8021`), authenticates, subscribes to events, auto-reconnects, and exposes
+  `api` / `bgapi` with callbacks.
+- **Outbound mode** — `FreeswitchESL.outbound_server` starts a TCP server that
+  FreeSWITCH dials into (`socket host:port async full`). Every call becomes a
+  `FreeswitchESL::Outbound::Session` with `answer`, `play`, `bridge`, `transfer`,
+  `set`, `export`, `speak`, `record`, `read`, `send_dtmf`, `execute`, `api`, `bgapi`.
+- Output-side `connect` handshake and automatic event subscription for outbound
+  sockets, with per-call event filtering by `Unique-ID`.
+- `Client#originate` with `application:`, `exten:`/`dialplan:`/`context:`,
+  positional `cid_name`/`cid_num`/`timeout`, and the three FreeSWITCH variable
+  scopes: `ultra_vars:` (`<>`), `vars:` (`{}`), `leg_vars:` (`[]`).
+- Binary-safe `Framer` that honours `Content-Length` and never splits frames on
+  blank lines, plus a parser for nested BACKGROUND_JOB bodies.
+- `Response` helpers: `success?`, `error?`, `reply_text`, `uuid`, `job_uuid`,
+  `event_name`, `body` / `output`.
+- Call helpers on the inbound client: `answer_call`, `kill`/`hangup`,
+  `bridge_calls`, `play_file`, `stop_playback`, `set_var`, `get_var`, `transfer`,
+  `park`, `status`, `channels`.
+- RSpec suite (26 examples) with a fake ESL server covering inbound, outbound and
+  originate command building.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael
+
+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,305 @@
+# freeswitch-esl-client
+
+[![Gem Version](https://badge.fury.io/rb/freeswitch-esl-client.svg)](https://rubygems.org/gems/freeswitch-esl-client)
+
+A small, dependency-light Ruby client for the [FreeSWITCH](https://freeswitch.org/)
+Event Socket Layer (`mod_event_socket`), with **inbound** and **outbound** modes.
+
+> The gem is published as **`freeswitch-esl-client`** because `freeswitch-esl` was
+> already taken on RubyGems. The library keeps its original name: `require 'freeswitch-esl'`
+> (as does the module, `FreeswitchESL`). `require 'freeswitch-esl-client'` works too.
+
+- **Inbound** — your Ruby process connects to FreeSWITCH on `:8021`, subscribes to
+  events and drives calls with `api` / `bgapi`.
+- **Outbound** — FreeSWITCH dials into an embedded TCP server of yours
+  (`<action application="socket" data="host:port async full"/>`), so call handling
+  lives in Ruby instead of static dialplan XML. Ideal for building a B2BUA, IVR or
+  dynamic routing service.
+
+Verified live against FreeSWITCH 1.11 and Asterisk 20 in Docker, on Ruby 3.2+ and 4.0.
+
+## Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Inbound mode](#inbound-mode)
+- [Originating calls](#originating-calls)
+- [Outbound mode](#outbound-mode)
+- [Threading and callbacks](#threading-and-callbacks)
+- [Gotchas](#gotchas)
+- [Development](#development)
+- [License](#license)
+
+## Requirements
+
+- Ruby >= 3.2
+- FreeSWITCH with `mod_event_socket` loaded
+  (`conf/autoload_configs/event_socket.conf.xml`, default password `ClueCon`)
+- Nothing else at runtime except [`eventmachine`](https://rubygems.org/gems/eventmachine)
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'freeswitch-esl-client'
+```
+
+Or straight from Git while a release is not published yet:
+
+```ruby
+gem 'freeswitch-esl-client', git: 'https://github.com/miclast/freeswitch-esl-client.git', tag: 'v0.1.0'
+```
+
+Or from a local checkout:
+
+```ruby
+gem 'freeswitch-esl-client', path: '../freeswitch-esl'
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+## Inbound mode
+
+```ruby
+require 'freeswitch-esl'
+require 'eventmachine'
+
+EM.run do
+  client = FreeswitchESL::Client.new(
+    host: '127.0.0.1',
+    port: 8021,
+    password: 'ClueCon'
+  )
+
+  client.on('CHANNEL_ANSWER') { |event| puts "answered #{event['Unique-ID']}" }
+  client.on('CHANNEL_HANGUP_COMPLETE') { |event| puts "hung up: #{event['Hangup-Cause']}" }
+  client.on('*') { |event| puts event['Event-Name'] }   # catch-all
+
+  client.connect           # inside a running reactor
+  # client.connect!        # without a reactor: spawns its own thread
+
+  EM.add_timer(1) do
+    client.api('status') { |res| puts res.body }
+  end
+end
+```
+
+### Constructor options
+
+| option | default | description |
+| --- | --- | --- |
+| `host` | `'127.0.0.1'` | ESL host |
+| `port` | `8021` | ESL port |
+| `password` | `'ClueCon'` | ESL password |
+| `logger` | `Logger.new($stdout)` | any `Logger`-compatible object |
+| `reconnect_interval` | `2` | seconds between reconnect attempts |
+| `events` | `Client::DEFAULT_EVENTS` | events to subscribe to |
+| `auto_reconnect` | `true` | reconnect automatically after a dropped connection |
+
+Commands issued before authentication are queued and flushed once the socket is
+ready; `client.ready?` tells whether that has happened.
+
+### Commands
+
+`api(command) { |res| … }` runs synchronously on the FreeSWITCH side and returns an
+`api/response`; `bgapi(command) { |res| … }` returns immediately and resolves via a
+`BACKGROUND_JOB` event. The gem maps the server-generated `Job-UUID` back to your
+block, so callbacks stay in order even with concurrent jobs.
+
+```ruby
+client.bgapi('status') { |res| puts res.reply_text }              # +OK Job-UUID: …
+client.api('show channels count') { |res| puts res.body }         # "2 total."
+```
+
+### Call helpers
+
+Convenience wrappers over the API (all callback-based):
+
+| helper | FreeSWITCH command |
+| --- | --- |
+| `answer_call(uuid)` | `uuid_answer` |
+| `kill(uuid, cause = 'NORMAL_CLEARING')` / `hangup` | `uuid_kill` |
+| `bridge_calls(uuid1, uuid2)` | `uuid_bridge` |
+| `play_file(uuid, file, leg = 'aleg')` | `uuid_broadcast` |
+| `stop_playback(uuid)` | `uuid_break … all` |
+| `set_var(uuid, name, value)` | `uuid_setvar` |
+| `get_var(uuid, name)` | `uuid_getvar` |
+| `transfer(uuid, destination, dialplan = 'XML', context = 'default')` | `uuid_transfer` |
+| `park(uuid)` | `uuid_park` |
+| `status` | `status` |
+| `channels` | `show channels as json` |
+
+### Response object
+
+| method | meaning |
+| --- | --- |
+| `success?` / `error?` | `+OK …` / `-ERR …` (works for bgapi too, where the text is in the body) |
+| `reply_text` | `Reply-Text` header or the first body line |
+| `uuid` | uuid from `+OK <uuid>` (handy for originate) |
+| `job_uuid`, `event_name` | job/event identifiers |
+| `body` / `output` | raw payload (API output, BACKGROUND_JOB output) |
+| `[key]` | any header of the reply/event |
+
+## Originating calls
+
+`Client#originate` builds the FreeSWITCH `originate` command for you:
+
+```ruby
+client.originate('sofia/gateway/agent/555',
+                 application: '&park()',           # or exten: '1000'
+                 vars: {
+                   origination_caller_id_number: '1001',
+                   origination_caller_id_name: 'Agent',
+                   ignore_early_media: 'false'
+                 },
+                 leg_vars: { effective_caller_id_name: 'Agent' }) do |res|
+  if res.success?
+    uuid = res.uuid                               # +OK <uuid>
+  else
+    warn res.reply_text                           # -ERR INVALID_GATEWAY
+  end
+end
+```
+
+A positional form maps to FreeSWITCH's `[dialplan] [context] [cid_name] [cid_num] [timeout_sec]`:
+
+```ruby
+client.originate('user/1000', cid_name: 'Support', cid_num: '1001', timeout: 30)
+# => bgapi originate user/1000 &park() XML default Support 1001 30
+```
+
+Missing intermediate slots are sent as the literal `undef`, which FreeSWITCH turns
+into `NULL`. Empty strings would be collapsed by its argv parser and shift the
+remaining arguments (the timeout would silently become the caller ID).
+
+### Variable scopes
+
+FreeSWITCH accepts three prefixes on a dial string and they are not equivalent:
+
+| scope | option | applies to |
+| --- | --- | --- |
+| `<...>` | `ultra_vars` | every leg of the originate |
+| `{...}` | `vars` | the originated channel, plus originate control variables (`originate_timeout`, `ignore_early_media`, `origination_caller_id_*`, retries, `group_confirm_*`) |
+| `[...]` | `leg_vars` | per-destination session variables |
+
+They are emitted in that order: `<ultra>{global}[leg]dialstring`. Note that when the
+same name appears in `{}` and `[]`, FreeSWITCH 1.11 keeps the `{}` value — use
+distinct names per scope instead of relying on an override.
+
+## Outbound mode
+
+FreeSWITCH makes the call, then hands the channel to your Ruby process:
+
+```xml
+<!-- dialplan -->
+<extension name="app">
+  <condition field="destination_number" expression="^9999$">
+    <action application="socket" data="10.0.0.5:8084 async full"/>
+  </condition>
+</extension>
+```
+
+```ruby
+require 'freeswitch-esl'
+require 'eventmachine'
+
+EM.run do
+  server = FreeswitchESL.outbound_server(host: '0.0.0.0', port: 8084) do |session|
+    puts "call from #{session.caller_id_number} to #{session.destination_number}"
+
+    session.on('DTMF') { |e| puts "digit #{e['DTMF-Digit']}" }
+    session.on('CHANNEL_HANGUP_COMPLETE') { |e| puts "cause #{e['Hangup-Cause']}" }
+
+    session.answer
+    session.play('ivr/ivr-welcome_to_freeswitch.wav')
+    session.bridge('sofia/gateway/trunk/555')
+    session.hangup('NORMAL_CLEARING')
+  end
+
+  server.start
+  # server.stop when shutting the application down
+end
+```
+
+### How it works
+
+1. FreeSWITCH connects and waits for the `connect` command — the server sends it
+   automatically in `post_init`.
+2. FreeSWITCH answers with a `command/reply` frame that also carries the channel
+   data (`Unique-ID`, caller, destination, …); that becomes the `Session`.
+3. The channel is parked. The session subscribes to its events and is driven with
+   `sendmsg` (`execute`, `answer`, `bridge`, …).
+4. Events are filtered by the session UUID (`Unique-ID`, `Bridge-A/B-Unique-ID`,
+   `Other-Leg-Unique-ID`, `Originating-Leg-Unique-ID`), so concurrent calls on the
+   same socket stay isolated.
+
+### Session API
+
+| group | methods |
+| --- | --- |
+| state | `uuid`, `caller_id_number`, `caller_id_name`, `destination_number`, `state`, `hangup_cause`, `answered?`, `ended?` |
+| call control | `answer`, `pre_answer`, `ring_ready`, `hangup(cause)`, `bridge(dialstring)`, `transfer(extension, dialplan:, context:)`, `park` |
+| media | `play(file)`, `play_and_get_digits(...)`, `read(...)`, `record(file, limit, ...)`, `speak(text, engine:, voice:)`, `sleep(ms)` |
+| variables | `set(name, value)`, `export(name, value)`, `unset(name)`, `variable(name)`, `[](name)`, `headers` |
+| signals | `send_dtmf(dtmf)`, `flush_dtmf` |
+| escape hatch | `execute(app, args)`, `api(command)`, `bgapi(command)`, `send_command(raw)` |
+| events | `on('DTMF') { … }`, `on('*') { … }` |
+
+`Session::DEFAULT_EVENTS` can be tuned in the constant if you need fewer events per call.
+
+## Threading and callbacks
+
+EventMachine runs everything on a single reactor thread. Event handlers and
+`api`/`bgapi` callbacks are invoked there, so keep them short: push work into a queue
+(Sidekiq, a Ruby `Queue`, etc.) instead of doing blocking I/O inside a callback.
+
+Calling `connect!` outside a reactor starts one owned by the client; `close!` stops
+it. Inside an existing reactor use `connect` and manage the reactor yourself.
+
+## Gotchas
+
+- **Outbound sockets receive no events until they subscribe.** `listener_run` in
+  `mod_event_socket.c` only delivers events after `event plain …`; the gem does this
+  for you in `start_session`.
+- **`bgapi` ignores a client-supplied `job-uuid=`.** FreeSWITCH generates its own and
+  reports it in the reply; the gem parses and matches it.
+- **Codecs must be in the bridge dial string** when a dialplan `set` is not honoured
+  on the outbound leg:
+  `session.bridge('{absolute_codec_string=PCMU,PCMA}sofia/gateway/trunk/555')`.
+- **`Caller-Caller-ID-*` may be rewritten** by a gateway/profile; check `Caller-ANI`
+  and `variable_origination_caller_id_*` when testing caller ID.
+- **Frames are content-length aware.** The parser never splits on blank lines, because
+  `BACKGROUND_JOB` bodies contain their own header block.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec        # 26 examples, no external services required
+rake build               # builds pkg/freeswitch-esl-client-0.1.0.gem
+```
+
+The spec suite spins up fake ESL servers in-process, so FreeSWITCH does not need to
+be running for the tests.
+
+### Releasing
+
+```bash
+rake release             # tags, pushes and uploads to rubygems.org
+# or manually:
+gem build freeswitch-esl-client.gemspec
+gem push freeswitch-esl-client-0.1.0.gem
+```
+
+## Contributing
+
+Issues and pull requests are welcome. Please run `bundle exec rspec` before opening a
+PR and keep the public API backwards compatible within a minor version.
+
+## License
+
+Released under the [MIT License](LICENSE).

data/freeswitch-esl-client.gemspec

@@ -0,0 +1,40 @@
+require_relative 'lib/freeswitch-esl/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'freeswitch-esl-client'
+  spec.version       = FreeswitchESL::VERSION
+  spec.authors       = ['Michael']
+  spec.email         = ['michael@example.com']
+
+  spec.summary       = 'Ruby client for the FreeSWITCH Event Socket Layer (inbound and outbound).'
+  spec.description   = <<~DESC
+    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.
+  DESC
+  spec.homepage      = 'https://github.com/miclast/freeswitch-esl-client'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.metadata = {
+    'homepage_uri'          => spec.homepage,
+    'changelog_uri'         => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    'bug_tracker_uri'       => "#{spec.homepage}/issues",
+    'documentation_uri'     => 'https://www.rubydoc.info/gems/freeswitch-esl-client',
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files         = Dir.glob('{lib,exe}/**/*') + %w[README.md CHANGELOG.md LICENSE freeswitch-esl-client.gemspec]
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'eventmachine', '~> 1.2', '>= 1.2.7'
+  spec.add_dependency 'logger', '>= 1.6'
+
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+end