ruby-asterisk 0.2.0 → 1.0.0

data/.claude/skills/ruby-asterisk-ari-websocket/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: ruby-asterisk-ari-websocket
+description: Receive real-time ARI events from Asterisk via WebSocket with ruby-asterisk: StasisStart, ChannelStateChange, auto-reconnect, ping keep-alive, per-event callbacks.
+---
+
+# ruby-asterisk ARI WebSocket Client
+
+## When to use this skill
+
+Use this skill when you need to react to Asterisk events in real time — for example: starting call handling logic when a Stasis call arrives (`StasisStart`), updating a dashboard on channel state changes, or forwarding events to another system.
+
+## Core concepts
+
+- The WebSocket client runs a **connection thread that owns the socket read loop** (protocol handled by the pure Ruby `websocket-driver` gem — no EventMachine). `connect` returns immediately; event processing happens in that thread.
+- Register handlers with `on(event_type, &block)` before or after connecting — handlers are stored and called whenever a matching event arrives.
+- **Multiple handlers** for the same event type are supported; all are called in registration order.
+- Auto-reconnect is enabled by default. When the connection drops, the client waits `reconnect_delay` seconds and reconnects. Set `auto_reconnect: false` to disable.
+- A ping is sent every `ping_interval` seconds to keep the connection alive.
+
+## Initialize
+
+```ruby
+require 'ruby-asterisk'
+
+ws = RubyAsterisk::ARI::WebSocket.new(
+  'http://192.168.1.1:8088',    # ARI base URL
+  'my_api_key',                 # API key (HTTP Basic auth username)
+  'my_stasis_app',              # Stasis application name
+  auto_reconnect:  true,        # default: true
+  reconnect_delay: 5,           # seconds between reconnect attempts; default: 5
+  ping_interval:   30,          # keep-alive ping interval in seconds; default: 30
+  logger:          Logger.new($stdout)
+)
+```
+
+## API reference
+
+| Method | Signature | Notes |
+|---|---|---|
+| `on` | `(event_type, &block)` | Register a callback; `event_type` is a String or Symbol |
+| `connect` | `(&block)` | Start the connection; optional block called on connect |
+| `connected?` | — | `true` if socket is open and in OPEN state |
+| `send_message?` | `(message)` | Send Hash (auto-JSON) or String; returns `false` if not connected |
+| `disconnect` | — | Close the socket and disable auto-reconnect |
+
+Constants (readable as class constants):
+
+| Constant | Default |
+|---|---|
+| `PING_INTERVAL` | 30 s |
+| `RECONNECT_DELAY` | 5 s |
+| `MAX_RECONNECT_ATTEMPTS` | `nil` (infinite) |
+
+## Common ARI event types
+
+| Event type | When fired |
+|---|---|
+| `StasisStart` | A channel enters your Stasis application |
+| `StasisEnd` | A channel leaves your Stasis application |
+| `ChannelStateChange` | Channel state changes (ringing, up, etc.) |
+| `ChannelDtmfReceived` | DTMF digit received on a channel |
+| `ChannelHangupRequest` | Hangup requested on a channel |
+| `BridgeCreated` / `BridgeDestroyed` | Bridge lifecycle |
+| `ChannelEnteredBridge` / `ChannelLeftBridge` | Channel bridge membership |
+| `PlaybackStarted` / `PlaybackFinished` | Media playback lifecycle |
+
+Event payloads are plain Ruby Hashes (parsed from JSON). The outer `type` key matches the event type string.
+
+## Usage patterns
+
+### React to incoming Stasis calls
+
+```ruby
+ws.on('StasisStart') do |event|
+  channel_id = event['channel']['id']
+  caller_id  = event.dig('channel', 'caller', 'number')
+  puts "Incoming call from #{caller_id} on #{channel_id}"
+
+  # Use ARI HTTP client to control the channel
+  http = RubyAsterisk::ARI::Client.new('http://192.168.1.1:8088', 'key', 'my_stasis_app')
+  http.channels.get(channel_id).answer
+end
+
+ws.connect
+sleep   # keep main thread alive
+```
+
+### Handle disconnect and cleanup
+
+```ruby
+ws.on('StasisEnd') do |event|
+  puts "Call ended: #{event['channel']['id']}"
+end
+
+ws.connect do
+  puts "Connected to ARI WebSocket"
+end
+
+# Graceful shutdown
+at_exit { ws.disconnect }
+```
+
+### Conditional forwarding
+
+```ruby
+ws.on('ChannelStateChange') do |event|
+  next unless event.dig('channel', 'state') == 'Up'
+
+  channel_id = event['channel']['id']
+  puts "Channel #{channel_id} is now answered"
+end
+```
+
+### Combine with ARI HTTP client
+
+```ruby
+http = RubyAsterisk::ARI::Client.new('http://192.168.1.1:8088', 'key', 'app')
+
+ws = RubyAsterisk::ARI::WebSocket.new('http://192.168.1.1:8088', 'key', 'app')
+ws.on('StasisStart') do |event|
+  channel = http.channels.get(event['channel']['id'])
+  channel.answer
+  channel.play('sound:hello-world')
+end
+
+ws.connect
+sleep
+```
+
+## Gotchas
+
+- **`connect` is non-blocking** — it starts a background connection thread and returns `self`. The main thread must stay alive (e.g. `sleep`) for events to be processed.
+- **Callbacks execute in the connection thread** — avoid long-running or blocking operations in callbacks; offload to a separate thread if needed. A blocked callback also blocks the read loop.
+- **`send_message?` is thread-safe** — outgoing writes are serialized through an internal reentrant Monitor, so it can be called from any thread (including from inside a callback).
+- **`send_message?` returns `false`** when not connected — always check the return value if delivery matters.
+- **Auto-reconnect** is enabled by default. Call `disconnect` when you actually want to stop; just closing the socket will trigger a reconnect.
+- **`app_name` must match** the Stasis application in Asterisk; events from other applications are not forwarded.
+- Calling `on` after `connect` is safe — handlers are stored in a plain Hash and checked on each incoming message.
+
+## Source files
+
+- `lib/ruby-asterisk/ari/websocket.rb` — `WebSocket` class
+- `lib/ruby-asterisk/ari/websocket/connection.rb` — `Connection` module (connect, read loop, reconnect)
+- `lib/ruby-asterisk/ari/websocket/heartbeat.rb` — `Heartbeat` module (ping timer, interruptible waits)
+- `lib/ruby-asterisk/ari/websocket/event_handlers.rb` — `EventHandlers` module (dispatch callbacks)
+- `lib/ruby-asterisk/ari/websocket/socket_adapter.rb` — socket wrapper handed to `websocket-driver`
+- `spec/ruby-asterisk/ari/websocket_spec.rb` — unit specs
+- `spec/ruby-asterisk/ari/websocket_integration_spec.rb` — integration specs against `spec/support/mock_ari_websocket_server.rb`

data/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+    # Required for the release job below: without a tags filter a tag push does
+    # not trigger this workflow at all, so `if: startsWith(github.ref,
+    # 'refs/tags/v')` would never be evaluated and no release could ever run.
+    tags:
+      - 'v*'
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    name: Linting
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+      - name: Install dependencies
+        run: bundle install
+      - name: Run Rubocop
+        run: bundle exec rubocop
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - '3.1'
+          - '3.2'
+          - '3.3'
+          - '3.4'
+          - '4.0.1'
+          - head
+    continue-on-error: ${{ endsWith(matrix.ruby, 'head') }}
+    name: Ruby ${{ matrix.ruby }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Install dependencies
+        run: bundle install
+      - name: Run tests
+        run: bundle exec rake spec
+
+  release:
+    needs: [lint, test]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+      - name: Install dependencies
+        run: bundle install
+      - name: Build gem
+        run: gem build *.gemspec
+      - name: Publish to RubyGems
+        run: |
+          mkdir -p $HOME/.gem
+          touch $HOME/.gem/credentials
+          chmod 0600 $HOME/.gem/credentials
+          printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+          gem push *.gem
+        env:
+          GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

data/.gitignore

@@ -1,7 +1,51 @@
+# Ignore bundler config.
+/.bundle
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+/docs/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore pidfiles, but keep the directory.
+/tmp/pids/*
+!/tmp/pids/
+!/tmp/pids/.keep
+
+# Ignore storage files.
+/storage/*
+!/storage/
+!/storage/.keep
+
+# Ignore master key for credentials.
+/config/master.key
+
+# Ignore locally-built DNS reverse lookup file.
+/tmp/resolv.conf.pred
+
+# Ignore local gems.
+/vendor/bundle/
+/vendor/gems/
+/vendor/cache/
 *.gem
-.bundle
-Gemfile.lock
-pkg/*
-coverage/*
+/.gem/
+
+# Ignore documentation files.
+/doc/
+/rdoc/
+
+# Ignore compiled files.
+*.o
+*.so
+
+# Ignore project-specific files
+.idea/
+.DS_Store
+coverage/
 .cane
 *_high_water_mark
+CLAUDE.md
+GEMINI.md
+pkg/
+Gemfile.lock

data/.rubocop.yml

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+plugins:
+  - rubocop-performance
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+
+# Crucial for Ractor compatibility - all files must have frozen string literal comment
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+# Enforce single quotes unless interpolation is needed
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+# Set reasonable limits but exclude large classes that group related commands
+Metrics/ClassLength:
+  Enabled: true
+  Max: 100
+  Exclude:
+    - 'lib/ruby-asterisk/ami/client.rb'
+    - 'lib/ruby-asterisk/agi/session.rb'
+
+# Reasonable method length
+Metrics/MethodLength:
+  Enabled: true
+  Max: 15
+  Exclude:
+    - 'spec/**/*'
+
+# Allow longer blocks in specs
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+# Allow longer lines for readability in some cases
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'spec/**/*'
+
+# Gemspec file uses string literals from git commands
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# We explicitly use add_runtime_dependency for clarity about dependency types
+Gemspec/AddRuntimeDependency:
+  Enabled: false
+
+# Exclude legacy AMI class from parameter list checks until refactored
+Metrics/ParameterLists:
+  Exclude:
+    - 'lib/ruby-asterisk.rb'
+  CountKeywordArgs: false
+
+# Exclude legacy AMI class from optional boolean parameter checks
+Style/OptionalBooleanParameter:
+  Exclude:
+    - 'lib/ruby-asterisk.rb'
+
+# The gem filename follows rubygems convention (gem-name.rb)
+Naming/FileName:
+  Exclude:
+    - 'lib/ruby-asterisk.rb'
+
+# Exclude response parser complexity until refactored
+Metrics/AbcSize:
+  Exclude:
+    - 'lib/ruby-asterisk/response_parser.rb'
+
+# Keep `success` method name for backwards compatibility (not success?)
+Naming/PredicateMethod:
+  Exclude:
+    - 'lib/ruby-asterisk/response.rb'
+
+Lint/SuppressedException:
+  Exclude:
+    - 'spec/support/mock_ami_server.rb'

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be 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]
+
+## [1.0.0] - 2026-07-25
+
+First release of the rewritten gem: three interfaces (AMI, ARI, AGI) on Ruby ≥ 3.1.
+
+### Added
+
+- **AGI::Protocol** — stateless module for AGI wire protocol: `format_command`, `escape_argument`, `quote`, `parse_response`, `error?` (#55)
+- **AGI::Protocol env helpers** — `parse_env_line`, `parse_env_block`, `collect_multiline_error` for robust Asterisk environment parsing and 520 multi-line error handling (#56)
+- **AGI::Session** — full FastAGI session wrapper with fiber-friendly socket I/O: `answer`, `hangup`, `stream_file`, `say_digits`, `say_number`, `exec`, `set_variable`, `get_variable`, `get_data`, `verbose`, `dial`, `wait_for_digit`, `record_file`, `send_text`, `send_image`, `channel_status`, `database_get/put/del/deltree` (#55)
+- **AGI::Server** — FastAGI TCP server backed by Async + Fiber scheduler; each connection runs in its own Fiber sharing a single OS thread (#54)
+- **ARI::WebSocket** — WebSocket client for ARI real-time events: per-event callbacks via `on(type, &block)`, auto-reconnect, configurable ping keep-alive. Built on the pure Ruby `websocket-driver` gem over a plain `TCPSocket` (`SSLSocket` for https) — no EventMachine, so it installs and runs on every supported Ruby including 4.x: a connection thread owns connect/read-loop/reconnect, a ping thread sends keep-alives, and driver access is serialized through a reentrant Monitor so `send_message?` is thread-safe (#53, #82)
+- **ARI::Client** — HTTP client for the Asterisk REST Interface backed by Faraday (#51)
+- **ARI::Resources** — Channel, Bridge, Playback, Endpoint, Collection, and Base resource classes for the ARI HTTP client (#52)
+- **AMI::Client async rewrite** — non-blocking AMI client with `Promise`-based responses: every command returns a `Promise`, call `.value(timeout)` to materialise the `Response`. The connection lives in a `Reactor` made of two plain OS threads (reader + writer) around the stateless `Parser` module, which gives deterministic shutdown on all Ruby ≥ 3.1 (#48, #49, #50, #79)
+- **AMI command modules** — Channel, Conference, Extension, Mailbox, Monitor, Queue, Sip, System extracted into dedicated modules and mixed into `AMI::Client` (#47)
+- `logoff` method on `AMI::Client`
+
+### Changed
+
+- **BREAKING:** `RubyAsterisk::AMI::Client` replaces the legacy flat `RubyAsterisk::AMI` class; every command now returns `RubyAsterisk::AMI::Promise` instead of a synchronous `Response`.
+- **BREAKING:** `Rami::VERSION` renamed to `RubyAsterisk::VERSION`; callers reading `Rami::VERSION` will get a `NameError`.
+- Minimum Ruby version set to 3.1.
+- Immutable domain objects (`Request`, `Response`) are now deep-frozen (#45).
+- Namespace migration: all classes moved under `RubyAsterisk::` (#46).
+
+### Fixed
+
+- Ruby 3.1 compatibility: `IO#timeout` / `IO#timeout=` shim in `lib/ruby-asterisk/compat.rb`; the `async` gem's Fiber scheduler calls `io.timeout` in Ruby 3.2+ — returning `nil` on 3.1 disables that code path without breaking async I/O (#55).
+- Deterministic teardown on `AMI::Client#disconnect`: both reactor threads are joined and every pending `Promise` is rejected instead of being left dangling (#50, #79).
+- A caller-supplied `action_id:` (`status`, `extension_state`) is now used as the request's ActionID instead of being appended as a second `ActionID` header, which left the response uncorrelated with its `Promise`.
+- `wait_event(timeout: -1)` no longer imposes a 5 s deadline on the returned `Promise`: a negative Timeout means Asterisk waits indefinitely, so `#value` now does too.
+
+### Removed
+
+- `Net::Telnet` dependency (replaced by a raw `TCPSocket` owned by the AMI `Reactor`).
+
+---
+
+## [0.1.0]
+
+Legacy AMI client based on `Net::Telnet`. Supported: login, originate, hangup, queue operations, ConfBridge, extension state, SIP peers, device state, monitor/record, parked calls, skinny devices.
+
+> Earlier history: see `git log v0.1.0` or the [full commit list on GitHub](https://github.com/emilianodellacasa/ruby-asterisk/commits/master).

data/Gemfile

@@ -1,4 +1,6 @@
-source "http://rubygems.org"
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in rami.gemspec
 gemspec