@babblevoice/babble-drachtio-callmanager 3.8.1 → 3.10.0

package/lib/call.js

@@ -293,6 +293,12 @@ class call {
     */
     this.parent = undefined
 
+    /**
+    * @summary Lifecycle callbacks supplied to newuac for this (outbound) call.
+    * @type { newuaccallbacks }
+    */
+    this.callbacks = {}
+
     /** @summary Other channels which we might need - for things like opening a channel on the same node. */
     this.relatives = new Set()
 
@@ -1345,7 +1351,16 @@ class call {
     if ( this.options.privacy )
       other.options.privacy = this.options.privacy
 
-    if( mix ) this.mix( other )
+    /* When we adopt-and-mix (enterprise queues and ring groups connect this
+       way rather than via #answerparent) we are the parent leg. preconnect
+       runs before the mix (projectrtp cannot play into a mixing channel),
+       then we mix, then postconnect. */
+    if( mix ) {
+      this.#notifyconnecthook( this, other, "preconnect" )
+        .then( () => this.mix( other ) )
+        .then( () => this.#notifyconnecthook( this, other, "postconnect" ) )
+        .catch( ( e ) => console.trace( e ) )
+    }
     return this
   }
 
@@ -1362,6 +1377,34 @@ class call {
     return this
   }
 
+  /**
+   * Register a handler to run once, on this (caller) leg, immediately BEFORE we
+   * are mixed with a party connecting to us - whether via a direct bridge
+   * (#answerparent) or an adopt-and-mix (enterprise queues, ring groups). Use
+   * this to play a prompt to each leg on connect: projectrtp cannot play into a
+   * channel that is being mixed, so it must happen before the mix. The handler
+   * is passed the connecting (callee/agent) leg and fires at most once.
+   * @param { connecthookcallback } handler
+   * @return { call }
+   */
+  preconnect( handler ) {
+    this.callbacks.preconnect = handler
+    return this
+  }
+
+  /**
+   * Register a handler to run once, on this (caller) leg, immediately AFTER we
+   * are mixed with a party connecting to us. Counterpart to preconnect() for
+   * work that should happen once the two legs are bridged. The handler is passed
+   * the connecting (callee/agent) leg and fires at most once.
+   * @param { connecthookcallback } handler
+   * @return { call }
+   */
+  postconnect( handler ) {
+    this.callbacks.postconnect = handler
+    return this
+  }
+
   /**
    * Disown distant relatives.
    * @return { call }
@@ -1445,6 +1488,32 @@ class call {
     return false
   }
 
+  /**
+   * Fire a parent leg's connect hook (preconnect/postconnect) exactly once, as
+   * a child leg connects to it. Handlers are registered on the caller leg via
+   * call.preconnect()/call.postconnect() (stored on callbacks - vars is reserved
+   * for client apps) and cleared here so each runs once per registration (i.e.
+   * once per call) even if the caller subsequently connects to further legs
+   * (re-queue, transfer, ...).
+   * @param { call } parentleg - the leg the handler was registered on (the caller)
+   * @param { call } childleg - the leg that is connecting (callee/agent)
+   * @param { string } hook - "preconnect" (before the mix) or "postconnect" (after)
+   * @returns { Promise< void > }
+   * @private
+   */
+  async #notifyconnecthook( parentleg, childleg, hook ) {
+    if( !parentleg || !parentleg.callbacks || !parentleg.callbacks[ hook ] ) return
+
+    const handler = parentleg.callbacks[ hook ]
+    parentleg.callbacks[ hook ] = undefined /* fire once */
+
+    try {
+      await handler( childleg )
+    } catch( e ) {
+      console.trace( e )
+    }
+  }
+
   /**
    *
    * @returns { Promise< object > } - return ourself
@@ -1462,6 +1531,12 @@ class call {
 
     if( this.#answerparenterrors() ) return this
 
+    /* preconnect: our parent leg's handler runs BEFORE the mix. projectrtp
+       cannot play audio into a channel that is being mixed, so a prompt that
+       must be heard on connect is played to each leg separately here (both
+       channels are open by this point), then we mix. */
+    await this.#notifyconnecthook( this.parent, this, "preconnect" )
+
     this.channels.audio.mix( this.parent.channels.audio )
 
     this._em.emit( "call.mix", this )
@@ -1472,6 +1547,19 @@ class call {
     this.epochs.mix = Math.floor( +new Date() / 1000 )
     if( this.parent ) this.parent.epochs.mix = Math.floor( +new Date() / 1000 )
 
+    /* Now we are bridged/mixed with our parent, notify any post-connect handlers.
+       The child-level handler is the one supplied to this leg's own newuac; the
+       parent-leg postconnect is registered on the caller via call.postconnect(). */
+    if( this.callbacks.onconnect ) {
+      try {
+        await this.callbacks.onconnect( this )
+      } catch( e ) {
+        console.trace( e )
+      }
+    }
+
+    await this.#notifyconnecthook( this.parent, this, "postconnect" )
+
     return this
   }
 
@@ -3808,6 +3896,8 @@ class call {
       return this
     }
 
+    this.callbacks = callbacks
+
     if( this.parent ) {
       const hangups = []
       for( const child of this.parent.children ) {
@@ -4062,11 +4152,24 @@ class call {
    * @param { call } call - our call object which is early
    */
 
+  /**
+   * @callback onconnectcallback
+   * @async
+   * @param { call } call - the (outbound) call which has just connected and been bridged with its parent
+   */
+
+  /**
+   * @callback connecthookcallback
+   * @async
+   * @param { call } call - the connecting (callee/agent) leg being bridged with the caller leg the hook was registered on
+   */
+
   /**
    * @typedef { object } newuaccallbacks
    * @property { earlycallback } [ early ] - callback to provide a call object with early call (pre dialog)
    * @property { confirmcallback } [ confirm ] - called when a dialog is confirmed but before it is bridged with a parent - this provides an opportunity for another call to adopt this call
    * @property { failcallback } [ fail ] - Called when child is terminated
+   * @property { onconnectcallback } [ onconnect ] - called after this call has connected and been bridged/mixed with its parent
    */
 
   /**
@@ -4122,10 +4225,12 @@ class call {
     newcall.#confignetwork( options )
 
     let newdialog, earlypromise
+    let settlewatchdog
     try {
       await newcall.#openchannelsfornewuac()
 
-      newdialog = await callmanager.options.srf.createUAC(
+      const settlems = newcall.options.uactimeout || callmanager.options.uactimeout
+      const createuacpromise = callmanager.options.srf.createUAC(
         options.contact + newcall.options.contactparams,
         {
           ...newcall.options,
@@ -4182,6 +4287,18 @@ class call {
             }
           }
         } )
+
+      const settlewatchdogpromise = new Promise( ( resolve, reject ) => {
+        settlewatchdog = setTimeout( async () => {
+          try {
+            await newcall.hangup( hangupcodes.REQUEST_TIMEOUT )
+          } catch ( e ) { /* silent */ }
+
+          reject( Object.assign( new Error( "newuac settle timeout" ), { status: 408 } ) )
+        }, settlems )
+      } )
+
+      newdialog = await Promise.race( [ createuacpromise, settlewatchdogpromise ] )
     } catch ( err ) {
       newcall.#onnewuaccatch( err )
       try{
@@ -4204,6 +4321,8 @@ class call {
           }
         }
       } catch( e ) { console.error( e ) }
+    } finally {
+      if( settlewatchdog ) clearTimeout( settlewatchdog )
     }
 
     if( earlypromise ) await earlypromise

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babblevoice/babble-drachtio-callmanager",
-  "version": "3.8.1",
+  "version": "3.10.0",
   "description": "Call processing to create a PBX",
   "main": "index.js",
   "scripts": {

package/test/interface/call.js

@@ -177,6 +177,182 @@ describe( "call object", function() {
 
   } )
 
+  it( "uas.newuac - onconnect callback is called after bridge with valid audio", async function() {
+
+    const srfscenario = new srf.srfscenario()
+
+    const call = await new Promise( ( resolve ) => {
+      srfscenario.oncall( async ( call ) => { resolve( call ) } )
+      srfscenario.inbound()
+    } )
+
+    let onconnectcount = 0
+    let connectedcall
+    let audioatconnect
+    let mixepochatconnect
+
+    const child = await call.newuac( { "contact": "1000@dummy" }, {
+      "onconnect": ( c ) => {
+        onconnectcount++
+        connectedcall = c
+        audioatconnect = c.channels.audio
+        mixepochatconnect = c.epochs.mix
+      }
+    } )
+
+    /* the handler ran exactly once, during newuac */
+    expect( onconnectcount ).to.equal( 1 )
+
+    /* it received the connected (child) call */
+    expect( connectedcall ).to.equal( child )
+
+    /* the audio channel was a valid object inside the handler - it must not
+       go undefined/false (the regression this callback originally exposed) */
+    expect( audioatconnect ).to.be.an( "object" )
+    expect( child.channels.audio ).to.equal( audioatconnect )
+
+    /* it fired AFTER the mix, i.e. once genuinely connected/bridged */
+    expect( mixepochatconnect ).to.be.a( "number" ).that.is.above( 0 )
+
+    await child.hangup()
+    await call.hangup()
+
+    expect( await callstore.stats() ).to.deep.include( {
+      "storebycallid": 0,
+      "storebyuuid": 0,
+      "storebyentity": 0
+    } )
+
+  } )
+
+  it( "call.preconnect/postconnect - parent-leg hooks fire around the mix when a child bridges (ringall/calldevice path)", async function() {
+
+    const srfscenario = new srf.srfscenario()
+
+    const call = await new Promise( ( resolve ) => {
+      srfscenario.oncall( async ( call ) => { resolve( call ) } )
+      srfscenario.inbound()
+    } )
+
+    let precount = 0, postcount = 0
+    let preleg, postleg
+    let premixepoch, postmixepoch
+    let preaudio
+
+    /* hooks are registered on the parent (caller) leg, before the child exists */
+    call.preconnect( ( c ) => {
+      precount++
+      preleg = c
+      premixepoch = c.epochs.mix   /* not mixed yet -> 0 */
+      preaudio = c.channels.audio  /* channel must be open before the mix */
+    } )
+    call.postconnect( ( c ) => {
+      postcount++
+      postleg = c
+      postmixepoch = c.epochs.mix  /* mixed now -> > 0 */
+    } )
+
+    /* a normal (non-orphan) newuac - the child bridges via #answerparent */
+    const child = await call.newuac( { "contact": "1000@dummy" } )
+
+    /* each fired exactly once, received the connecting child */
+    expect( precount ).to.equal( 1 )
+    expect( postcount ).to.equal( 1 )
+    expect( preleg ).to.equal( child )
+    expect( postleg ).to.equal( child )
+
+    /* preconnect ran BEFORE the mix, with a valid (open) audio channel;
+       postconnect ran AFTER the mix */
+    expect( premixepoch ).to.equal( 0 )
+    expect( preaudio ).to.be.an( "object" )
+    expect( postmixepoch ).to.be.a( "number" ).that.is.above( 0 )
+
+    /* fire-once: both hooks have been cleared off the parent leg */
+    expect( call.callbacks.preconnect ).to.be.undefined
+    expect( call.callbacks.postconnect ).to.be.undefined
+
+    await child.hangup()
+    await call.hangup()
+
+    expect( await callstore.stats() ).to.deep.include( {
+      "storebycallid": 0,
+      "storebyuuid": 0,
+      "storebyentity": 0
+    } )
+
+  } )
+
+  it( "call.preconnect/postconnect - parent-leg hooks fire around adopt-and-mix (enterprise/ring-group path)", async function() {
+
+    const srfscenario = new srf.srfscenario()
+
+    const call = await new Promise( ( resolve ) => {
+      srfscenario.oncall( async ( call ) => { resolve( call ) } )
+      srfscenario.inbound()
+    } )
+
+    await call.answer()
+
+    /* enterprise queues create the agent leg orphaned (no parent), so it does
+       NOT bridge via #answerparent - it is later adopted by the winning caller */
+    const agent = await call.newuac( { "contact": "1000@dummy", "orphan": true } )
+    expect( agent.parent ).to.be.undefined
+
+    let precount = 0, postcount = 0
+    let preleg, postleg
+    let premixepoch, postmixepoch
+    let resolveconnected
+    const connected = new Promise( ( resolve ) => { resolveconnected = resolve } )
+
+    call.preconnect( ( c ) => {
+      precount++
+      preleg = c
+      premixepoch = c.epochs.mix
+    } )
+    call.postconnect( ( c ) => {
+      postcount++
+      postleg = c
+      postmixepoch = c.epochs.mix
+      resolveconnected()
+    } )
+
+    /* the orphaned agent existing did not fire either hook */
+    expect( precount ).to.equal( 0 )
+    expect( postcount ).to.equal( 0 )
+
+    /* the caller adopts-and-mixes the agent - this is the connect moment */
+    call.adopt( agent, true )
+    await connected
+
+    expect( precount ).to.equal( 1 )
+    expect( postcount ).to.equal( 1 )
+    expect( preleg ).to.equal( agent )
+    expect( postleg ).to.equal( agent )
+
+    /* preconnect ran before the mix, postconnect after */
+    expect( premixepoch ).to.equal( 0 )
+    expect( postmixepoch ).to.be.a( "number" ).that.is.above( 0 )
+
+    /* fire-once: a second adopt-and-mix does not refire */
+    expect( call.callbacks.preconnect ).to.be.undefined
+    expect( call.callbacks.postconnect ).to.be.undefined
+    const agent2 = await call.newuac( { "contact": "1000@dummy", "orphan": true } )
+    call.adopt( agent2, true )
+    expect( precount ).to.equal( 1 )
+    expect( postcount ).to.equal( 1 )
+
+    await agent2.hangup()
+    await agent.hangup()
+    await call.hangup()
+
+    expect( await callstore.stats() ).to.deep.include( {
+      "storebycallid": 0,
+      "storebyuuid": 0,
+      "storebyentity": 0
+    } )
+
+  } )
+
   it( "uas.newuac - create uac by entity no registrar", async function() {
     const srfscenario = new srf.srfscenario()
 
@@ -469,6 +645,47 @@ describe( "call object", function() {
     expect( child.state.cleaned ).to.be.true
   } )
 
+  it( "uas.newuac - createUAC never settles - watchdog forces return", async function() {
+
+    const srfscenario = new srf.srfscenario()
+    /* simulate a far end that never sends a final response and never honours
+       CANCEL: createUAC never resolves or rejects. Without the settle watchdog
+       newuac would hang here forever (and this test would hit the mocha timeout). */
+    srfscenario.oncreateUAC( () => new Promise( () => {} ) )
+
+    const call = await new Promise( ( resolve ) => {
+      srfscenario.oncall( async ( call ) => { resolve( call ) } )
+      srfscenario.inbound()
+    } )
+
+    const start = Date.now()
+    const child = await call.newuac( { "contact": "1000@dummy", "uactimeout": 50 } )
+    const elapsed = Date.now() - start
+
+    /* the watchdog must make newuac return promptly (~uactimeout) rather than
+       block on the never-settling createUAC */
+    expect( elapsed ).to.be.below( 1000 )
+
+    expect( child.destroyed ).to.be.true
+    expect( child.hangup_cause.sip ).to.equal( 408 )
+    expect( child.hangup_cause.reason ).to.equal( "REQUEST_TIMEOUT" )
+    expect( child.hangup_cause.src ).to.equal( "us" )
+
+    /* clean up runs on the event loop */
+    await new Promise( resolve => setTimeout( resolve, 100 ) )
+
+    await call.hangup()
+
+    expect( await callstore.stats() ).to.deep.include( {
+      "storebycallid": 0,
+      "storebyuuid": 0,
+      "storebyentity": 0
+    } )
+
+    expect( call.state.cleaned ).to.be.true
+    expect( child.state.cleaned ).to.be.true
+  } )
+
   it( "uas.newuac - child remote hangup", async function() {
 
     const srfscenario = new srf.srfscenario()