buzz-me-in 2.2.0-beta.1 → 2.2.0-beta.2

package/.env.example

@@ -55,6 +55,13 @@ TWILIO_MEDIA_PAYLOAD_MAX_BYTES=512
 TWILIO_UNLOCK_DIGITS=w9w
 # Grace period for SIGINT/SIGTERM graceful shutdown before forced exit.
 SHUTDOWN_GRACE_MS=10000
+# How long the Twilio call is held open after the HomeKit live view closes,
+# before the call is hung up. Backing out of the camera view to the room view
+# tears the stream down, and the lock tile there needs the call to still be up
+# to send its DTMF. Raise this if you find yourself reaching the lock too late;
+# the only cost is that much silence for the caller after you are done.
+# Tapping unlock restarts the window, so the digits are never cut short.
+HOMEKIT_HANGUP_GRACE_MS=3000
 
 # Logging
 # LOG_LEVEL controls minimum emitted level: debug | info | warn | error

package/README.md

@@ -422,6 +422,8 @@ Tap the lock tile in the Home app → set to Unlocked.
 
 The lock tile resets to Secured automatically after 3 seconds.
 
+Two routes reach the lock tile, and they behave differently. The grid button at the bottom right of the camera view brings the lock up _beside_ the running stream, which is the smoother of the two. Backing out to the room view instead closes the camera view and tears the stream down; the lock tile is still there under **Other**, and it works because the call is held open for `HOMEKIT_HANGUP_GRACE_MS` after the view closes. Tapping unlock restarts that window, so the digits are never cut off mid-sequence.
+
 ---
 
 ### Stage 8 — Caller hangs up
@@ -446,10 +448,13 @@ Open the live view, then dismiss it on the iPhone (tap the X / end button).
 **Pass (server log):**
 
 ```text
+{"ts":"...","level":"info","message":"Hangup scheduled after grace period","component":"homekit","event":"hangup-scheduled","reason":"homekit-session-stopped","callSid":"CA...","sessionId":"...","graceMs":3000}
 {"ts":"...","level":"info","message":"Inbound ffmpeg exited","component":"homekit","event":"ffin-exit","reason":"nonzero-exit","exitCode":null,"sessionId":"..."}
 {"ts":"...","level":"info","message":"Hanging up call","component":"twilio-api","event":"hangup","callSid":"CA..."}
 ```
 
+The call is not hung up the instant the view closes. It is held open for `HOMEKIT_HANGUP_GRACE_MS` (default 3000) so the lock tile still has a call to send DTMF to, then hung up. Reopening the view inside that window logs `hangup-cancelled` instead and the call continues; if the caller hangs up first, the pending hangup logs `hangup-skipped` and does nothing.
+
 **Pass (Twilio):** The call shows as completed in the [Twilio Console call log](https://console.twilio.com/us1/monitor/logs/calls).
 
 ---

package/homekit.js

@@ -277,6 +277,9 @@ const streamingDelegate = {
 // ---------------------------------------------------------------------------
 
 function _startSession(sessionID, s, request, callback) {
+  // Reopening the live view inside the grace window means the user is not
+  // finished after all.
+  cancelPendingHangUp('homekit-session-restarted');
   const videoParams = srtpParams(s.hkVideoKey, s.hkVideoSalt);
   const audioParams = srtpParams(s.hkAudioKey, s.hkAudioSalt);
   const video = request.video;
@@ -557,13 +560,85 @@ function _stopSession(sessionID, hangUp) {
 
   const activeCall = getActiveCall();
   if (hangUp && activeCall) {
-    hangUpCall(activeCall.callSid)
+    scheduleHangUp(activeCall.callSid, sessionID);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Deferred hangup
+//
+// Closing the live view is not the same as being finished with the caller. The
+// Home app reaches the lock tile two different ways: the grid button inside the
+// camera view keeps the stream up, but backing out to the room view tears it
+// down, and tapping the lock from there used to find no call left to send DTMF
+// to. Holding the call open briefly after STOP makes both routes work, because
+// unlock needs the call's WebSocket, not a HomeKit streaming session.
+//
+// The call is still hung up when the user really has finished; it just costs
+// config.homekitHangupGraceMs of silence first, ffmpeg having already been
+// killed above.
+// ---------------------------------------------------------------------------
+
+const HANGUP_GRACE_MS = config.homekitHangupGraceMs;
+
+/** @type {{ timer: NodeJS.Timeout, callSid: string, sessionID: string } | null} */
+let pendingHangUp = null;
+
+function cancelPendingHangUp(reason) {
+  if (!pendingHangUp) return;
+  clearTimeout(pendingHangUp.timer);
+  logger.info('Pending hangup cancelled', {
+    event: 'hangup-cancelled',
+    reason,
+    callSid: pendingHangUp.callSid,
+    sessionId: pendingHangUp.sessionID,
+  });
+  pendingHangUp = null;
+}
+
+/**
+ * Restart the grace window, so a hangup cannot land on top of an action the
+ * user has just taken. Without this an unlock tapped late in the window could
+ * be cut off before the intercom acts on the digits.
+ */
+function deferPendingHangUp(reason) {
+  if (!pendingHangUp) return;
+  const { callSid, sessionID } = pendingHangUp;
+  clearTimeout(pendingHangUp.timer);
+  pendingHangUp = null;
+  scheduleHangUp(callSid, sessionID, reason);
+}
+
+function scheduleHangUp(callSid, sessionID, reason = 'homekit-session-stopped') {
+  cancelPendingHangUp('superseded');
+  logger.info('Hangup scheduled after grace period', {
+    event: 'hangup-scheduled',
+    reason,
+    callSid,
+    sessionId: sessionID,
+    graceMs: HANGUP_GRACE_MS,
+  });
+  const timer = setTimeout(() => {
+    pendingHangUp = null;
+    const activeCall = getActiveCall();
+    // The caller may have hung up during the window, and the slot may already
+    // hold a different call. Either way this one is no longer ours to end.
+    if (!activeCall || activeCall.callSid !== callSid) {
+      logger.info('Pending hangup skipped; call already gone', {
+        event: 'hangup-skipped',
+        reason: 'call-no-longer-active',
+        callSid,
+        sessionId: sessionID,
+      });
+      return;
+    }
+    hangUpCall(callSid)
       .then((result) => {
         if (result && result.alreadyEnded) {
           logger.info('Twilio call already ended while stopping HomeKit session', {
             event: 'hangup-call-already-ended',
             reason: 'twilio-call-not-in-progress',
-            callSid: activeCall.callSid,
+            callSid,
             sessionId: sessionID,
           });
         }
@@ -572,12 +647,14 @@ function _stopSession(sessionID, hangUp) {
         logger.error('Failed to hang up call while stopping HomeKit session', {
           event: 'hangup-call-failed',
           reason: 'twilio-hangup-failed',
-          callSid: activeCall.callSid,
+          callSid,
           sessionId: sessionID,
           error,
         });
       });
-  }
+  }, HANGUP_GRACE_MS);
+  timer.unref();
+  pendingHangUp = { timer, callSid, sessionID };
 }
 
 // ---------------------------------------------------------------------------
@@ -611,6 +688,10 @@ lockService
       try {
         await sendDtmfSequence(activeCall, config.twilioUnlockDigits);
         state.markActivity(activeCall.callSid, 'unlock-dtmf');
+        // Unlocking from the room view is the case this grace window exists
+        // for, so give the intercom a full window to act on the digits rather
+        // than whatever was left of the previous one.
+        deferPendingHangUp('unlock-sent');
         logger.info('Sent DTMF unlock over active media stream', {
           event: 'unlock-requested',
           callSid: activeCall.callSid,
@@ -789,6 +870,9 @@ function clearMulawPassthrough(stream) {
  * Does NOT call hangUpCall — the call is already gone.
  */
 function endHapSession() {
+  // The caller is already gone, so a hangup left over from a closed live view
+  // has nothing to end.
+  cancelPendingHangUp('call-ended');
   for (const sessionID of activeSessions.keys()) {
     _stopSession(sessionID, /* hangUp= */ false);
   }
@@ -811,6 +895,7 @@ function setOnHapSessionStarted(handler) {
  * clean stop, restart and reboot.
  */
 function shutdown() {
+  cancelPendingHangUp('shutdown');
   endHapSession();
   removeSdpDir();
   // Nothing to tear down if start() never ran: unpublish() on an accessory
@@ -833,4 +918,10 @@ module.exports = {
   endHapSession,
   setOnHapSessionStarted,
   shutdown,
+  // Exported for tests/homekit-hangup-grace.test.cjs. Reaching the deferred
+  // hangup through the streaming delegate would mean standing up a full SRTP
+  // session, which tests nothing about the timer.
+  scheduleHangUp,
+  cancelPendingHangUp,
+  deferPendingHangUp,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buzz-me-in",
-  "version": "2.2.0-beta.1",
+  "version": "2.2.0-beta.2",
   "description": "HomeKit-compatible apartment intercom via Twilio media streams",
   "main": "server.js",
   "bin": {

package/src/core/config.js

@@ -138,6 +138,7 @@ module.exports = {
   streamStartTimeoutMs: parsePositiveInt('STREAM_START_TIMEOUT_MS', '3000'),
   twilioMediaPayloadMaxBytes: parsePositiveInt('TWILIO_MEDIA_PAYLOAD_MAX_BYTES', '512'),
   shutdownGraceMs: parsePositiveInt('SHUTDOWN_GRACE_MS', '10000'),
+  homekitHangupGraceMs: parsePositiveInt('HOMEKIT_HANGUP_GRACE_MS', '3000'),
   streamAuthSecret,
   streamAuthTtlSec: 90,
   statusApiToken,