@babblevoice/babble-drachtio-callmanager 3.9.0 → 3.10.1

package/lib/call.js

@@ -1351,7 +1351,23 @@ 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. Only take the deferred (hook) path when a
+       hook is actually registered - otherwise mix synchronously in this tick,
+       exactly as before, so callers that assume the mix has been issued on
+       return (recording, queue setup) don't race a microtask. */
+    if( mix ) {
+      if( this.callbacks && ( this.callbacks.preconnect || this.callbacks.postconnect ) ) {
+        this.#notifyconnecthook( this, other, "preconnect" )
+          .then( () => this.mix( other ) )
+          .then( () => this.#notifyconnecthook( this, other, "postconnect" ) )
+          .catch( ( e ) => console.trace( e ) )
+      } else {
+        this.mix( other )
+      }
+    }
     return this
   }
 
@@ -1368,6 +1384,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 }
@@ -1451,6 +1495,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
@@ -1468,6 +1538,17 @@ 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. Only yield when a hook is
+       actually registered - a normal bridge must mix synchronously in this tick
+       exactly as before, or recording/queue setup that assumes the mix has been
+       issued can race. */
+    if( this.parent.callbacks.preconnect ) {
+      await this.#notifyconnecthook( this.parent, this, "preconnect" )
+    }
+
     this.channels.audio.mix( this.parent.channels.audio )
 
     this._em.emit( "call.mix", this )
@@ -1478,7 +1559,9 @@ 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 onconnect handler. */
+    /* 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 )
@@ -1487,6 +1570,10 @@ class call {
       }
     }
 
+    if( this.parent.callbacks.postconnect ) {
+      await this.#notifyconnecthook( this.parent, this, "postconnect" )
+    }
+
     return this
   }
 
@@ -4085,6 +4172,12 @@ class call {
    * @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)

package/package.json

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

package/test/interface/call.js

@@ -225,6 +225,134 @@ describe( "call object", function() {
 
   } )
 
+  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()