rename voip_bridge to bridge, add return_ivr [latest]

Author: shenjinti

docs/ivr_step_protocol_en.md

@@ -117,6 +117,7 @@ Every response is a JSON object with a `"type"` field. Two categories:
 
 ```json
 { "type": "transfer",       "target": "2001" }
+{ "type": "transfer",       "target": "ivr:other_ivr", "params": {"order_id":"123"} }
 { "type": "hangup",         "prompt": null }
 { "type": "queue",          "target": "support" }
 { "type": "voicemail",      "target": "1001" }
@@ -198,15 +199,17 @@ RustPBX plays the prompt → on audio complete → automatically executes the dt
 
 | type | Purpose | Required | Optional | Notes |
 |------|---------|----------|----------|-------|
-| `transfer` | Blind‑transfer the call to a SIP URI or extension | `target: string` | — | The call leaves the IVR permanently |
+| `transfer` | Blind‑transfer the call to a SIP URI, extension, or another IVR | `target: string` | `params: Map<string,string>` | When `target` is an `ivr:` URI (e.g. `ivr:other_ivr`), `params` are encoded as query string and passed to the target IVR as session variables |
 | `queue` | Send the caller into an ACD queue | `target: string` | `return_to_ivr: bool` | When `return_to_ivr=true`, the call returns to IVR if no agent answers |
 | `voicemail` | Forward the caller to a user's voicemail | `target: string` | — | The call leaves the IVR |
 | `hangup` | Terminate the call | — | `prompt: string or null` | If `prompt` is set, plays audio before hanging up |
 | `play_and_hangup` | Play an announcement then hang up with a SIP status code | — | `prompt: string or null`, `code: u16 or null` | `code` is the SIP response code (e.g. 486 busy, 404 not found) |
-| `jump_ivr` | Jump to another named IVR route point | `route_point: string` | `params: Map<string,string>` | The new IVR receives `params` as session variables |
+| `jump_ivr` | Jump to another named IVR route point | `route_point: string` | `params: Map<string,string>` | Equivalent to `transfer` with `target="ivr:{route_point}"`. `params` are passed as session variables to the target IVR |
 | `route_to_agent` | Route the call to a human agent via skill‑based routing | `target: string` | `skill_group_id: string`, `key_id: string`, `channel_code: string` | Uses the contact‑center routing engine |
 | `voip_bridge` | Bridge call audio to an external WebSocket endpoint as raw PCM16 | `create_room_uri: string` | `headers: Map<string,string>`, `timeout_ms: u64` | See [voip_bridge_en.md](voip_bridge_en.md) |
 
+> **Passing data between IVRs**: Both `transfer` (with `target="ivr:other_ivr"`) and `jump_ivr` support a `params` field. These params are URL-encoded as a query string on the target URI (e.g. `ivr:other_ivr?order_id=123`) and parsed on the receiving end. The target IVR merges them into session variables, making them available for `$var$` substitution and included in `ProviderContext.variables` sent to the external step provider. This enables seamless IVR-to-IVR context propagation without external state management.
+
 ### Non-terminal actions
 
 | type | Purpose | Required | Optional | Notes |
@@ -424,6 +427,8 @@ Any `$var_name$` in string fields is replaced from session variables:
 
 Any variables returned in `ProviderContext.variables` by the provider are also available.
 
+When an IVR is entered via `transfer` (with `target="ivr:other_ivr"`) or `jump_ivr`, any `params` from the source action are merged into session variables before the first `ProviderEvent::SessionStart` is sent. This means the target IVR's provider immediately sees these values in `ProviderContext.variables` and can use `$param_name$` substitution in its responses.
+
 ---
 
 ## 8. Error Handling & Retry

examples/voip_bridge_ivr_provider.py examples/bridge_ivr_provider.pyexamples/voip_bridge_ivr_provider.py renamed to examples/bridge_ivr_provider.py

@@ -1,39 +1,39 @@
 #! /usr/bin/env python3
-"""VoipBridge IVR Provider + WebSocket PCM16 echo server — stdlib only.
+"""Bridge IVR Provider + WebSocket PCM16 echo server — stdlib only.
 
-Demonstrates the full IVR → voip_bridge transfer flow:
+Demonstrates the full IVR → bridge transfer flow:
 
   1. IVR step provider exposes POST /ivr/step
      - session_start → welcome prompt → dtmf_menu
-     - press "1" → returns a TERMINAL ``voip_bridge`` ActionNode that bridges
+     - press "1" → returns a TERMINAL ``bridge`` ActionNode that bridges
        the call's audio to a WebSocket endpoint speaking raw PCM16
      - press "2" → announces current time (prompt)
      - press "0" → hangup
   2. A stdlib WebSocket server (raw socket, no third-party deps) acts as the
      "external VoIP service". It echoes any binary PCM16 frame back to the
      client — i.e. RustPBX receives its own audio. This is the same shape the
-     Rust E2E test (src/proxy/tests/test_voip_bridge_e2e.rs) uses.
+     Rust E2E test (src/proxy/tests/test_bridge_e2e.rs) uses.
 
 Topology once the bridge is up:
 
   Caller (WebRTC/RTP)  ◄──►  RustPBX SipSession  ◄──►  WebSocket (PCM16)  ◄──►  this echo server
 
 Run (defaults: IVR HTTP on 8080, WS echo on 9090):
 
-    python3 examples/voip_bridge_ivr_provider.py
+    python3 examples/bridge_ivr_provider.py
 
 Run with custom ports:
 
-    python3 examples/voip_bridge_ivr_provider.py 8080 9090
+    python3 examples/bridge_ivr_provider.py 8080 9090
 
 Self-test (drives the IVR flow against the provider + pings the WS server
 with a PCM16 frame, printing a step-by-step trace — no SIP stack required):
 
-    python3 examples/voip_bridge_ivr_provider.py --self-test
+    python3 examples/bridge_ivr_provider.py --self-test
 
 Unit tests:
 
-    python3 -m unittest examples/voip_bridge_ivr_provider.py
+    python3 -m unittest examples/bridge_ivr_provider.py
 """
 
 import argparse
@@ -63,7 +63,7 @@ class IvrSession:
 
     rustpbx calls POST /ivr/step on every event; we reply with the next
     ActionNode. See docs/ivr_step_protocol_en.md for the protocol and
-    docs/voip_bridge.md for the voip_bridge terminal action.
+    docs/bridge.md for the bridge terminal action.
     """
 
     def __init__(self, caller: str, callee: str, ws_endpoint: str):
@@ -91,7 +91,7 @@ def next_action(self, event: dict) -> dict:
                     "timeout_ms": 8000,
                     "max_retries": 3,
                     "entries": {
-                        "1": action_voip_bridge(self.ws_endpoint),
+                        "1": action_bridge(self.ws_endpoint),
                         "2": {"type": "prompt", "tts_text": _time_text()},
                         "0": action_hangup(),
                     },
@@ -104,7 +104,7 @@ def next_action(self, event: dict) -> dict:
             if ev_type == "dtmf":
                 digit = event.get("digit", "")
                 if digit == "1":
-                    return action_voip_bridge(self.ws_endpoint)
+                    return action_bridge(self.ws_endpoint)
                 if digit == "2":
                     return action_prompt(tts_text=_time_text())
                 if digit == "0":
@@ -136,19 +136,19 @@ def action_hangup():
     return {"type": "hangup"}
 
 
-def action_voip_bridge(ws_endpoint: str, headers=None, timeout_ms=10000):
+def action_bridge(ws_endpoint: str, headers=None, timeout_ms=10000):
     """Terminal action: bridge call audio to a WebSocket endpoint as PCM16.
 
     rustpbx turns this into a blind transfer target
-    ``voip_bridge:<ws_endpoint>?codec=pcm&samplerate=8000&_hdr_*=&timeout_ms=``
-    and runs connect_voip_bridge() in src/proxy/proxy_call/sip_session/transfer.rs.
+    ``bridge:<ws_endpoint>?codec=pcm&samplerate=8000&_hdr_*=&timeout_ms=``
+    and runs connect_bridge() in src/proxy/proxy_call/sip_session/transfer.rs.
     """
     return {
-        "type": "voip_bridge",
+        "type": "bridge",
         "create_room_uri": ws_endpoint,
         "headers": headers or {"X-Source": "ivr-voip-bridge-example"},
         "timeout_ms": timeout_ms,
-        "step_id": "voip_bridge",
+        "step_id": "bridge",
         "step_name": "VoIP 桥接",
     }
 
@@ -432,7 +432,7 @@ def serve(ivrr_port: int, ws_port: int):
     start_ws_echo(ws_port)
     server = _ThreadedHTTPServer(("0.0.0.0", ivrr_port), IvrStepHandler)
     print(f"[IVR] step provider on http://0.0.0.0:{ivrr_port}/ivr/step")
-    print(f"[IVR] voip_bridge target = {IvrStepHandler.ws_endpoint}")
+    print(f"[IVR] bridge target = {IvrStepHandler.ws_endpoint}")
     print("[IVR] Endpoints:")
     print("  POST /ivr/step         — main provider endpoint")
     print("  POST /ivr/step/start   — session start (fire-and-forget)")
@@ -507,7 +507,7 @@ def _ws_client_echo(url: str, samples: list) -> list:
 def self_test(ivrr_port: int, ws_port: int):
     """Run provider + WS server in-process, drive the flow, print a trace."""
     print("=" * 72)
-    print("VoipBridge IVR self-test — no SIP stack needed")
+    print("Bridge IVR self-test — no SIP stack needed")
     print("=" * 72)
     IvrStepHandler.ws_endpoint = f"ws://127.0.0.1:{ws_port}"
     start_ws_echo(ws_port)
@@ -529,22 +529,22 @@ def step(label, event):
         trace.append((label, event.get("type"), resp.get("type"), resp))
         return resp
 
-    # 1. session_start → prompt + dtmf_menu (entries hold the voip_bridge)
+    # 1. session_start → prompt + dtmf_menu (entries hold the bridge)
     resp = step("initial", {"type": "session_start"})
     assert resp["type"] == "prompt", resp
     menu = resp.get("next", {})
     assert menu.get("type") == "dtmf_menu", menu
     entry1 = menu.get("entries", {}).get("1", {})
-    assert entry1.get("type") == "voip_bridge", entry1
+    assert entry1.get("type") == "bridge", entry1
     print(f"[trace] session_start -> {resp['type']} (next={menu['type']}, "
           f"entry['1']={entry1['type']} uri={entry1.get('create_room_uri')})")
 
-    # 2. Verify the voip_bridge ActionNode shape matches the protocol doc.
+    # 2. Verify the bridge ActionNode shape matches the protocol doc.
     uri = entry1.get("create_room_uri", "")
     if f":{ws_port}" not in uri:
         failures.append(f"ws port mismatch in create_room_uri: {uri}")
     if "timeout_ms" not in entry1:
-        failures.append("timeout_ms missing on voip_bridge node")
+        failures.append("timeout_ms missing on bridge node")
 
     # 3. Drive dtmf "2" through a fresh session to exercise the time branch.
     sid2 = sid + "_b"
@@ -580,7 +580,7 @@ def step(label, event):
     print("-" * 72)
     for label, ev, act, node in trace:
         note = ""
-        if act == "voip_bridge":
+        if act == "bridge":
             note = "→ " + node.get("create_room_uri", "")
         elif act == "prompt":
             note = (node.get("tts_text") or node.get("file") or "")[:40]
@@ -620,10 +620,10 @@ def test_start_returns_prompt_chained_to_menu(self):
         self.assertEqual(nxt["type"], "dtmf_menu")
         self.assertIn("1", nxt["entries"])
 
-    def test_menu_entry_1_is_voip_bridge(self):
+    def test_menu_entry_1_is_bridge(self):
         node = self.sess.next_action({"type": "session_start"})
         e1 = node["next"]["entries"]["1"]
-        self.assertEqual(e1["type"], "voip_bridge")
+        self.assertEqual(e1["type"], "bridge")
         self.assertEqual(e1["create_room_uri"], "ws://127.0.0.1:9090")
         self.assertGreater(e1["timeout_ms"], 0)
         self.assertIn("headers", e1)
@@ -632,7 +632,7 @@ def test_menu_entry_0_is_hangup(self):
         node = self.sess.next_action({"type": "session_start"})
         self.assertEqual(node["next"]["entries"]["0"]["type"], "hangup")
 
-    def test_voip_bridge_uri_from_env_override(self):
+    def test_bridge_uri_from_env_override(self):
         s = IvrSession("1", "2", "wss://relay.example.com/ws")
         node = s.next_action({"type": "session_start"})
         self.assertEqual(
@@ -661,7 +661,7 @@ def sendall(self, b):
 
 
 def main():
-    p = argparse.ArgumentParser(description="VoipBridge IVR provider + WS echo")
+    p = argparse.ArgumentParser(description="Bridge IVR provider + WS echo")
     p.add_argument("ivrr_port", nargs="?", type=int, default=8080)
     p.add_argument("ws_port", nargs="?", type=int, default=9090)
     p.add_argument("--self-test", action="store_true",

src/addons/ivr_editor

@@ -6,6 +6,7 @@ use crate::tts::TtsService;
 use std::collections::HashMap;
 use std::sync::Arc;
 use std::time::Duration;
+use urlencoding;
 
 use super::config::{ActionNode, EntryAction};
 
@@ -211,8 +212,17 @@ pub async fn execute_action(
     tts_service: Option<&Arc<TtsService>>,
 ) -> anyhow::Result<ActionResult> {
     match action {
-        EntryAction::Transfer { target } => {
-            let t = substitute_vars(target, &sess.variables);
+        EntryAction::Transfer { target, params } => {
+            let mut t = substitute_vars(target, &sess.variables);
+            if !params.is_empty() {
+                t.push('?');
+                for (i, (k, v)) in params.iter().enumerate() {
+                    if i > 0 {
+                        t.push('&');
+                    }
+                    t.push_str(&format!("{}={}", k, urlencoding::encode(v)));
+                }
+            }
             Ok(ActionResult::Terminal(TerminalAction::Transfer(t)))
         }
         EntryAction::Queue { target, .. } => {
@@ -490,7 +500,21 @@ pub async fn execute_action(
             params,
         } => {
             let rp = substitute_vars(route_point, &sess.variables);
-            let target = format!("toivr:{}", rp);
+            let mut target = format!("toivr:{}", rp);
+            // Encode params as query string so the target IVR can receive them
+            if !params.is_empty() {
+                target.push('?');
+                for (i, (k, v)) in params.iter().enumerate() {
+                    if i > 0 {
+                        target.push('&');
+                    }
+                    target.push_str(&format!(
+                        "{}={}",
+                        k,
+                        urlencoding::encode(v)
+                    ));
+                }
+            }
             sess.variables.insert(
                 "jump_params".into(),
                 serde_json::to_string(params).unwrap_or_default(),
@@ -522,28 +546,34 @@ pub async fn execute_action(
             Ok(ActionResult::Terminal(TerminalAction::Transfer(t)))
         }
 
-        EntryAction::VoipBridge {
+        EntryAction::Bridge {
             create_room_uri,
             headers,
+            return_ivr,
             success,
             failure,
             ..
         } => {
             let uri = substitute_vars(create_room_uri, &sess.variables);
-            sess.variables.insert("voip_room_uri".into(), uri.clone());
+            sess.variables.insert("bridge_room_uri".into(), uri.clone());
             for (k, v) in headers {
-                sess.variables.insert(format!("voip_hdr_{}", k), v.clone());
+                sess.variables.insert(format!("bridge_hdr_{}", k), v.clone());
+            }
+            let mut uri = uri;
+            if let Some(ivr_name) = return_ivr {
+                let sep = if uri.contains('?') { "&" } else { "?" };
+                uri = format!("{}{}return_ivr={}", uri, sep, ivr_name);
             }
             if success.is_some() || failure.is_some() {
                 sess.variables
-                    .insert("voip_bridge_branch".into(), "true".into());
+                    .insert("bridge_branch".into(), "true".into());
                 Ok(ActionResult::Terminal(TerminalAction::Transfer(format!(
-                    "voip_bridge:{}",
+                    "bridge:{}",
                     uri
                 ))))
             } else {
                 Ok(ActionResult::Terminal(TerminalAction::Transfer(format!(
-                    "voip_bridge:{}",
+                    "bridge:{}",
                     uri
                 ))))
             }