librevox 0.8 → 1.0.0.alpha1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 14a0e655fcf9650313c68ffcc4a0e2863a32135b
-  data.tar.gz: 5605f7a4d07e93d47f1620ce1e2f50a3a87dc755
+SHA256:
+  metadata.gz: 6d47382ef56ccc15ea2aacf0e4bc5f4bf197fdb7338a25e7841a7f85a96ebe31
+  data.tar.gz: 86736dac97c19aaa298693bfe99c3f75a9b829777f37ea20d2932a1f5221dc3b
 SHA512:
-  metadata.gz: 82bc2349155291668c68e85e13aa40c02ff063cc2e60c2c6ad3dfd37480e188253620117ac6301f1a112667c3fb6912a9f7d320363419b673d198f43dac6ba52
-  data.tar.gz: 4a7a0c9eeca5e5e5c9805518f71711a602dbe0dd15959011542ebb9895c49a87ab1f5ee586762bddd63f68c19d248dede85eb91067051bd00b207d0b912f8ec7
+  metadata.gz: efea41f41b6e92608d8dbe69035cbc537c7c1da77c15767c92aa1679633d57c840f26ac37a740f4df3a9ef24a24103bad9bdf2a1ed514bc8d73fd33e0a9576f9
+  data.tar.gz: 6a1502164b5df5387b6f1a12c65d379f3fb13caec7a27201c4aa97d1122a22ac667021991802f8158b53e3bd91d2b8b4a0f401709ebee9973331b960bfecff67

data/README.md

@@ -1,193 +1,292 @@
 # Librevox
 
-> An EventMachine-based Ruby library for interacting with the open source 
-> telephony platform [FreeSWITCH](http://www.freeswitch.org).
-
-Librevox eventually came to life during a major rewrite of
-[Freeswitcher](http://code.rubyists.com/projects/fs/). Not everything would
-fit into the existing architecture, and I felt that a blank slate was needed.
-Librevox and Freeswitcher looks much alike on the outside, but Librevox tries
-to take a simpler approach on the inside.
+A Ruby library for interacting with [FreeSWITCH](http://www.freeswitch.org) through [mod_event_socket](https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Modules/mod_event_socket_1048924/), using async I/O.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Inbound Listener](#inbound-listener)
+  - [Events](#events)
+  - [Event Filtering](#event-filtering)
+- [Outbound Listener](#outbound-listener)
+  - [Dialplan](#dialplan)
+  - [API Commands](#api-commands)
+- [Starting Listeners](#starting-listeners)
+- [Closing Connections](#closing-connections)
+- [Command Socket](#command-socket)
+- [Configuration](#configuration)
+- [Event Socket Protocol](#event-socket-protocol)
+  - [Outbound session lifecycle](#outbound-session-lifecycle)
+  - [sendmsg and application execution](#sendmsg-and-application-execution)
+  - [event-lock](#event-lock)
+  - [Two fibers per connection](#two-fibers-per-connection)
+- [API Documentation](#api-documentation)
+- [License](#license)
 
 ## Prerequisites
 
-Librevox lets you interact with FreeSWITCH through mod_event_socket. You
-should know how the event socket works, and the differences between inbound and
-outbound event sockets before proceeding. The
-[wiki page on mod_event_socket](http://wiki.freeswitch.org/wiki/Event_Socket) is
-a good place to start.
+You should be familiar with [mod_event_socket](https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Modules/mod_event_socket_1048924/) and the differences between inbound and outbound event sockets before getting started.
+
+Requires Ruby 3.0+.
 
-Librevox is Ruby 1.9-only.
+## Installation
 
-## Inbound listener
+Add to your Gemfile:
 
-To create an inbound listener, you should subclass `Librevox::Listener::Inbound`
-and add custom behaviour to it. An inbound listener subscribes to all events
-from FreeSWITCH, and lets you react on events in two different ways:
+```ruby
+gem "librevox"
+```
 
-1.      By overiding `on_event` which gets called every time an event arrives.
+## Inbound Listener
 
-2.      By adding an event hook with `event`, which will get called every time
-        an event with the specified name arrives.
+Subclass `Librevox::Listener::Inbound` to create an inbound listener. It connects to FreeSWITCH and subscribes to events.
 
-The header and content of the event is accessible through `event`.
+### Events
 
-Below is an example of an inbound listener utilising all the aforementioned
-techniques:
+React to events in two ways:
 
-    require 'librevox'
+1. Override `on_event`, called for every event.
+2. Use `event` hooks for specific event names.
 
-    class MyInbound < Librevox::Listener::Inbound
-      def on_event e
-        puts "Got event: #{e.content[:event_name]}"
-      end
-     
-      # You can add a hook for a certain event:
-      event :channel_hangup do
-        # It is instance_eval'ed, so you can use your instance methods etc:
-        do_something
-      end
+```ruby
+class MyInbound < Librevox::Listener::Inbound
+  def on_event(e)
+    puts "Got event: #{e.content[:event_name]}"
+  end
 
-      # If your hook block takes an argument, a Librevox::Response object for
-      # the given event is passed on:
-      event :channel_bridge do |e|
-        ...
-      end
-     
-      def do_something
-        ...
-      end
-    end
+  event :channel_hangup do
+    do_something
+  end
 
-## Outbound listener
+  # The hook block receives a Response when it takes an argument:
+  event :channel_bridge do |e|
+    puts e.content[:caller_caller_id_number]
+  end
 
-You create an outbound listener by subclassing `Librevox::Listener::Outbound`. 
+  def do_something
+    # ...
+  end
+end
+```
 
-### Events
+### Event Filtering
+
+By default, inbound listeners subscribe to all events. Use `events` to limit which events are received, and `filters` to filter by header values:
+
+```ruby
+class MyInbound < Librevox::Listener::Inbound
+  events ['CHANNEL_EXECUTE', 'CUSTOM foo']
+  filters 'Caller-Context' => ['default', 'example'],
+          'Caller-Privacy-Hide-Name' => 'no'
+end
+```
+
+## Outbound Listener
+
+Subclass `Librevox::Listener::Outbound` to create an outbound listener. FreeSWITCH connects to it when a call hits a socket application in the dialplan.
 
-An outbound listener has the same event functionality as the inbound listener,
-but it only receives events related to that given session.
+Outbound listeners have the same event functionality as inbound, but scoped to the session.
 
 ### Dialplan
 
-When a call is made and Freeswitch connects to the outbound event listener,
-`session_initiated` is called. This is where you set up your dialplan:
-
-    def session_initiated
-      answer do
-        set "some_var", "some value" do
-          playback "path/to/file" do
-            hangup
-          end
-        end
-      end
-    end
-
-All channel variables are available as a hash named `session`.
-
-When using applications that expect a reply, such as `play_and_get_digits`,
-you have to use callbacks to read the value, as the function itself returns
-immediately due to the async nature of EventMachine:
-
-    def session_initiated
-      answer do
-        play_and_get_digits "enter-number.wav", "error.wav" do |digit|
-          puts "User pressed #{digit}"
-          playback "thanks-for-the-input.wav" do
-            hangup
-          end
-        end
-      end
-    end
-
-You can also use the commands defined in `Librevox::Command`, which, to avoid
-namespace clashes, are accessed through the `api` object:
-    
-    def session_initiated
-      answer do
-        api.status
-      end
-    end
-
-They can be used in conjunction with applications, and do also take a block,
-passing the response to an eventual block argument.
-
-## Starting listeners
-
-To start a single listener, connection/listening on localhost on the default
-port is quite simple:
-
-    Librevox.start SomeListener
-
-it takes an optional hash with arguments:
-
-    Librevox.start SomeListener, :host => "1.2.3.4", :port => "8087", :auth => "pwd"
-
-Multiple listeners can be started at once by passing a block to `Librevox.start`:
-
-    Librevox.start do
-      run SomeListener
-      run OtherListener, :port => "8080"
-    end
-
-## Closing connection
-
-After a session has finished, e.g. because the calling part hangs up, an
-outbound socket still has its connection to FreeSWITCH open, so we can get post-
-session events. Therefore it is important that you close the connection manually
-when you are done. Otherwise you will have 'hanging' sessions, cloggering up
-your system. This can safely be done with `close_connection_after_writing`,
-which will wait for all outgoing data to be send before closing the connection.
-It is aliased as `done` for convenience.
-
-Unless you are doing something specific, closing the connection on CHANNEL_HANGUP
-is most likely sufficient:
-    
-    class MyListener < Librevox::Listener::Outbound
-      event :channel_hangup do
-        done
-      end
-    end
-
-## Using `Librevox::CommandSocket`
-
-Librevox also ships with a CommandSocket class, which allows you to connect
-to the FreeSWITCH management console, from which you can originate calls,
-restart FreeSWITCH etc.
-
-    >> require `librevox/command_socket`
-    => true
-    
-    >> socket = Librevox::CommandSocket.new
-    => #<Librevox::CommandSocket:0xb7a89104 @server=“127.0.0.1”,
-        @socket=#<TCPSocket:0xb7a8908c>, @port=“8021”, @auth=“ClueCon”>
-
-    >> socket.originate('sofia/user/coltrane', :extension => "1234")
-    >> #<Librevox::Response:0x10179d388 @content="+OK de0ecbbe-e847...">
-    
-    >> socket.status
-    >> > #<Librevox::Response:0x1016acac8 ...>
-
-## Further documentation
-
-All applications and commands are documented in the code. You can run
-`yardoc` from the root of the source tree to generate YARD docs. Look under
-the `Librevox::Commands` and `Librevox::Applications` modules.
-
-## Extras
-
-* Source: [http://github.com/vangberg/librevox](http://github.com/vangberg/librevox)
-* API docs: [http://rdoc.info/projects/vangberg/librevox](http://rdoc.info/projects/vangberg/librevox)
-* Mailing list: librevox@librelist.com
-* IRC: #librevox @ irc.freenode.net
+When FreeSWITCH connects, `session_initiated` is called. Build your dialplan here.
 
-## License
+Each application call blocks until FreeSWITCH signals completion (`CHANNEL_EXECUTE_COMPLETE`), so applications execute sequentially:
+
+```ruby
+class MyOutbound < Librevox::Listener::Outbound
+  def session_initiated
+    answer
+    digit = play_and_get_digits "enter-digit.wav", "bad-digit.wav"
+    bridge "sofia/gateway/trunk/#{digit}"
+  end
+end
+```
+
+Applications that read input (like `play_and_get_digits` and `read`) return the collected value directly.
+
+```ruby
+def session_initiated
+  answer
+  set "foo", "bar"
+  multiset "baz" => "1", "qux" => "2"
+  playback "welcome.wav"
+  hangup
+end
+```
+
+For apps not yet wrapped by a named helper, call `application` directly:
+
+```ruby
+application "park"
+```
+
+Channel variables are available through `session` (a hash) and `variable`:
+
+```ruby
+def session_initiated
+  answer
+  number = variable(:destination_number)
+  playback "greeting-#{number}.wav"
+end
+```
+
+### API Commands
+
+To avoid name clashes between applications and commands, commands are accessed through `api`:
+
+```ruby
+def session_initiated
+  answer
+  api.status
+  api.originate 'sofia/user/coltrane', extension: "1234"
+end
+```
+
+## Starting Listeners
+
+Start a single listener:
+
+```ruby
+Librevox.start MyInbound
+```
+
+With connection options:
+
+```ruby
+Librevox.start MyInbound, host: "1.2.3.4", port: 8021, auth: "secret"
+```
+
+Start multiple listeners:
+
+```ruby
+Librevox.start do
+  run MyInbound
+  run MyOutbound, port: 8084
+end
+```
+
+Default ports are 8021 for inbound and 8084 for outbound.
+
+## Closing Connections
+
+After a session ends (e.g. the caller hangs up), the outbound socket connection to FreeSWITCH remains open for post-session events. Close it manually when done to avoid lingering sessions. Use `done` (alias for `close_connection_after_writing`):
+
+```ruby
+class MyOutbound < Librevox::Listener::Outbound
+  event :channel_hangup do
+    done
+  end
+end
+```
+
+## Command Socket
 
-(c) 2009-2014 Harry Vangberg <harry@vangberg.name>
-(c) 2011-2014 Firmafon ApS <info@firmafon.dk>
+`Librevox::CommandSocket` connects to the FreeSWITCH management console for one-off commands:
 
-Librevox was inspired by and uses code from Freeswitcher, which is distributed
-under the MIT license and (c) 2009 The Rubyists (Jayson Vaughn, Tj Vanderpoel,
-Michael Fellinger, Kevin Berry), Harry Vangberg, see `LICENSE-Freeswitcher`.
+```ruby
+require "librevox/command_socket"
+
+socket = Librevox::CommandSocket.new(server: "127.0.0.1", port: 8021, auth: "ClueCon")
+
+socket.originate 'sofia/user/coltrane', extension: "1234"
+#=> #<Librevox::Protocol::Response ...>
+
+socket.status
+#=> #<Librevox::Protocol::Response ...>
+
+socket.close
+```
+
+## Configuration
+
+```ruby
+Librevox.options[:log_file]  = "librevox.log"  # default: STDOUT
+Librevox.options[:log_level] = Logger::DEBUG    # default: Logger::INFO
+```
+
+When started with `Librevox.start`, sending `SIGHUP` to the process reopens the log file, making it compatible with `logrotate(1)`.
+
+## Event Socket Protocol
+
+Understanding the outbound event socket protocol is important for working on
+librevox internals.
+
+### Outbound session lifecycle
+
+When FreeSWITCH hits a `socket` application in the dialplan, it connects to the
+outbound listener. The listener sends three setup commands before any
+application logic runs:
+
+```
+Listener → FS:  connect
+FS → Listener:  (channel data — becomes @session)
+
+Listener → FS:  myevents
+FS → Listener:  command/reply +OK
+
+Listener → FS:  linger
+FS → Listener:  command/reply +OK  → triggers session_initiated
+```
+
+### sendmsg and application execution
+
+When an application (e.g. `answer`, `playback`, `bridge`) is executed via
+`sendmsg`, FreeSWITCH always sends the `command/reply +OK` immediately — it is
+an acknowledgement that the sendmsg was received, **not** that the application
+finished. Application completion is signalled by a `CHANNEL_EXECUTE_COMPLETE`
+event:
+
+```
+Listener → FS:  sendmsg
+                call-command: execute
+                execute-app-name: playback
+                execute-app-arg: welcome.wav
+                event-lock: true
+
+FS → Listener:  command/reply +OK              ← immediate ack
+FS → Listener:  CHANNEL_EXECUTE event          ← app started
+                ...app is running...
+FS → Listener:  CHANNEL_EXECUTE_COMPLETE event ← app finished
+```
+
+### event-lock
+
+The `event-lock: true` header serializes application execution **on the
+channel**. It does not change what is sent back on the socket.
+
+Without `event-lock`, if multiple sendmsg commands are pipelined, FreeSWITCH
+may dequeue and start executing the next application before the current one
+finishes. With `event-lock: true`, FreeSWITCH sets an internal flag
+(`CF_EVENT_LOCK`) on the channel that prevents the next queued sendmsg from
+being processed until the current application completes.
+
+### Two fibers per connection
+
+Librevox runs two fibers for each outbound connection:
+
+- **Session fiber** (`run_session`) — runs the setup sequence and then
+  `session_initiated`. Each `command` or `application` call blocks the fiber
+  until the reply arrives.
+- **Read fiber** (`read_loop`) — reads messages from the socket and dispatches
+  them to `Async::Queue` instances, waking the session fiber.
+
+An `Async::Semaphore(1)` mutex on `command` ensures only one command is
+in-flight at a time, so replies are always delivered to the correct caller.
+This also serializes commands issued by event hooks (which run in their own
+fibers) with the main session flow.
+
+## API Documentation
+
+Applications and commands are documented with YARD. Generate docs with:
+
+```
+yard doc
+```
+
+See `Librevox::Applications` and `Librevox::Commands` for the full API reference.
+
+## License
 
-Librevox is distributed under the terms of the MIT license, see `LICENSE`.
+MIT. See `LICENSE` for details.