buzz-me-in 2.0.0

package/src/core/log.js

@@ -0,0 +1,132 @@
+'use strict';
+
+/** @import { LogFields } from './types.js' */
+
+const LEVELS = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+const DEFAULT_LEVEL = 'info';
+const PRETTY_LOGS = process.env.LOG_PRETTY === '1';
+
+/**
+ * @param {unknown} value
+ * @returns {LogFields}
+ */
+function normalizeFields(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+
+  /** @type {LogFields} */
+  const normalized = {};
+  for (const [key, fieldValue] of Object.entries(value)) {
+    if (fieldValue === undefined) continue;
+    if (fieldValue instanceof Error) {
+      normalized.errorName = fieldValue.name;
+      normalized.errorMessage = fieldValue.message;
+      normalized.errorStack = fieldValue.stack || '';
+      continue;
+    }
+    normalized[key] = fieldValue;
+  }
+  return normalized;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {'debug' | 'info' | 'warn' | 'error'}
+ */
+function parseLevel(value) {
+  if (typeof value !== 'string') return DEFAULT_LEVEL;
+  const lower = value.toLowerCase();
+  if (lower === 'debug' || lower === 'info' || lower === 'warn' || lower === 'error') {
+    return lower;
+  }
+  return DEFAULT_LEVEL;
+}
+
+const ACTIVE_LEVEL = parseLevel(process.env.LOG_LEVEL);
+
+/**
+ * @param {'debug' | 'info' | 'warn' | 'error'} level
+ * @returns {boolean}
+ */
+function shouldLog(level) {
+  return LEVELS[level] >= LEVELS[ACTIVE_LEVEL];
+}
+
+/**
+ * @param {'debug' | 'info' | 'warn' | 'error'} level
+ * @param {LogFields} payload
+ */
+function emit(level, payload) {
+  const target = level === 'warn' || level === 'error' ? process.stderr : process.stdout;
+  try {
+    const line = PRETTY_LOGS ? JSON.stringify(payload, null, 2) : JSON.stringify(payload);
+    target.write(`${line}\n`);
+  } catch (err) {
+    const fallback = {
+      ts: new Date().toISOString(),
+      level: 'error',
+      message: 'Failed to serialize log payload',
+      component: 'log',
+      reason: 'serialization-error',
+      errorMessage: err instanceof Error ? err.message : String(err),
+      errorStack: err instanceof Error && err.stack ? err.stack : '',
+    };
+    process.stderr.write(`${JSON.stringify(fallback)}\n`);
+  }
+}
+
+/**
+ * @param {LogFields} [baseFields]
+ */
+function createLogger(baseFields) {
+  const base = normalizeFields(baseFields);
+
+  /**
+   * @param {'debug' | 'info' | 'warn' | 'error'} level
+   * @param {string} message
+   * @param {LogFields} [fields]
+   */
+  function logAt(level, message, fields) {
+    if (!shouldLog(level)) return;
+    const payload = {
+      ts: new Date().toISOString(),
+      level,
+      message,
+      ...base,
+      ...normalizeFields(fields),
+    };
+    emit(level, payload);
+  }
+
+  return {
+    /** @param {string} message @param {LogFields} [fields] */
+    debug(message, fields) {
+      logAt('debug', message, fields);
+    },
+    /** @param {string} message @param {LogFields} [fields] */
+    info(message, fields) {
+      logAt('info', message, fields);
+    },
+    /** @param {string} message @param {LogFields} [fields] */
+    warn(message, fields) {
+      logAt('warn', message, fields);
+    },
+    /** @param {string} message @param {LogFields} [fields] */
+    error(message, fields) {
+      logAt('error', message, fields);
+    },
+    /** @param {LogFields} fields */
+    child(fields) {
+      return createLogger({ ...base, ...normalizeFields(fields) });
+    },
+  };
+}
+
+module.exports = {
+  createLogger,
+};

package/src/core/media-stream.js

@@ -0,0 +1,335 @@
+'use strict';
+
+/**
+ * Twilio media stream session: one instance per accepted WebSocket
+ * connection. Handles the Twilio event protocol (connected/start/media/stop),
+ * stream token verification, ringback, and teardown.
+ *
+ * External integrations (call state, HomeKit, logging) are injected so the
+ * protocol logic can be unit-tested with fakes.
+ */
+
+const { PassThrough } = require('stream');
+const { parseTwilioWsEvent, parseTwilioMediaPayload } = require('./ws-events-schema');
+const { createRingbackMulawCycle, sendMulawAudio } = require('./mulaw-audio');
+
+/** @import { connection, Message } from 'websocket' */
+/** @import { WsEventParseOkSupported, StreamTokenVerificationResult, TokenVerificationError, WsEventParseError, MediaPayloadParseError } from './types' */
+
+/**
+ * @typedef {object} MediaStreamDeps
+ * @property {ReturnType<typeof import('./log').createLogger>} logger
+ * @property {typeof import('./state')} state
+ * @property {{ setMulawPassthrough: (stream: PassThrough) => number, triggerDoorbell: () => void, clearMulawPassthrough: (stream: PassThrough) => void, endHapSession: () => void }} homekit
+ * @property {Map<string, MediaStream>} registry map of callSid → MediaStream
+ * @property {(token: string) => StreamTokenVerificationResult} verifyStreamToken
+ * @property {string} tokenParameterName
+ * @property {number} startTimeoutMs
+ * @property {number} maxUtf8Bytes
+ * @property {number} mediaPayloadMaxBytes
+ */
+
+class MediaStream {
+  /**
+   * @param {connection} connection
+   * @param {MediaStreamDeps} deps
+   */
+  constructor(connection, deps) {
+    this.connection = connection;
+    this.deps = deps;
+    this.logger = deps.logger;
+    this.messageCount = 0;
+    this.currentCallSid = null;
+    this.started = false;
+    this.closed = false;
+    this.hasHomekitSession = false;
+    this.droppingFrames = false;
+    this.ringbackTimer = null;
+    this.ringbackOffset = 0;
+    this.ringbackPayload = createRingbackMulawCycle();
+    this.startTimeout = setTimeout(() => {
+      if (!this.started) {
+        this.logger.warn('Media websocket start timed out', {
+          event: 'start',
+          reason: 'start-timeout',
+        });
+        this.connection.close();
+      }
+    }, deps.startTimeoutMs);
+    this.startTimeout.unref();
+
+    // Raw mulaw bytes from Twilio flow into this PassThrough only after
+    // HomeKit opens a live view. Pre-live buffering creates catch-up latency.
+    this.mulawStream = new PassThrough({ highWaterMark: 32768 });
+
+    connection.on('message', this.processMessage.bind(this));
+    connection.on('close', this.close.bind(this));
+  }
+
+  /**
+   * @param {Message} message
+   */
+  processMessage(message) {
+    if (message.type !== 'utf8') return;
+    if (message.utf8Data.length > this.deps.maxUtf8Bytes) {
+      this.logger.warn('Media websocket message too large', {
+        event: 'media-ws-message-too-large',
+        reason: 'max-message-bytes-exceeded',
+      });
+      this.connection.close();
+      return;
+    }
+
+    let rawData;
+    try {
+      rawData = JSON.parse(message.utf8Data);
+    } catch {
+      this.logger.warn('Media websocket invalid JSON', {
+        event: 'media-ws-invalid-json',
+        reason: 'json-parse-failed',
+      });
+      this.connection.close();
+      return;
+    }
+
+    const parsedResult = parseTwilioWsEvent(rawData);
+    if (!parsedResult.ok) {
+      const parsedError = /** @type {WsEventParseError} */ (parsedResult);
+      this.logger.warn('Media websocket invalid event payload', {
+        event: 'media-ws-invalid-event-payload',
+        reason: parsedError.reason,
+      });
+      this.connection.close();
+      return;
+    }
+    if (parsedResult.unsupported) {
+      this.logger.info('Media websocket unsupported event ignored', {
+        event: 'media-ws-unsupported-event',
+        reason: parsedResult.event,
+      });
+      this.messageCount++;
+      return;
+    }
+    const parsed = /** @type {WsEventParseOkSupported} */ (parsedResult);
+
+    switch (parsed.event) {
+      case 'connected': {
+        this.logger.info('Media websocket connected event', {
+          event: 'connected',
+        });
+        break;
+      }
+
+      case 'start': {
+        this._handleStart(parsed.data.start);
+        break;
+      }
+
+      case 'media': {
+        this._handleMedia(parsed.data.media);
+        break;
+      }
+
+      case 'stop': {
+        this.logger.info('Media websocket stop event', {
+          callSid: this.currentCallSid || undefined,
+          event: 'stop',
+        });
+        this._teardown('twilio-stop');
+        break;
+      }
+    }
+
+    this.messageCount++;
+  }
+
+  /**
+   * @param {{ callSid: string, streamSid: string, customParameters?: Record<string, string> }} start
+   */
+  _handleStart(start) {
+    if (this.started) {
+      this.logger.warn('Duplicate media websocket start event', {
+        event: 'start',
+        reason: 'duplicate-start',
+      });
+      this.connection.close();
+      return;
+    }
+    const token = start.customParameters
+      ? start.customParameters[this.deps.tokenParameterName]
+      : undefined;
+    const verification = this.deps.verifyStreamToken(typeof token === 'string' ? token : '');
+    if (!verification.ok) {
+      const verificationError = /** @type {TokenVerificationError} */ (verification);
+      this.logger.warn('Media websocket start rejected', {
+        callSid: start.callSid,
+        event: 'start',
+        reason: verificationError.reason,
+      });
+      this.connection.close();
+      return;
+    }
+    if (verification.callSid && verification.callSid !== start.callSid) {
+      this.logger.warn('Media websocket start rejected', {
+        callSid: start.callSid,
+        event: 'start',
+        reason: 'callsid-mismatch',
+      });
+      this.connection.close();
+      return;
+    }
+    const started = this.deps.state.startCall({
+      callSid: start.callSid,
+      streamSid: start.streamSid,
+      wsConnection: this.connection,
+    });
+    if (started.ok === false) {
+      this.logger.warn('Media websocket start rejected', {
+        callSid: start.callSid,
+        event: 'start',
+        reason: started.reason,
+      });
+      this.connection.close();
+      return;
+    }
+    this.logger.info('Media websocket start accepted', {
+      callSid: start.callSid,
+      event: 'start',
+      streamSid: start.streamSid,
+    });
+    clearTimeout(this.startTimeout);
+    this.currentCallSid = start.callSid;
+    this.started = true;
+    this.deps.registry.set(start.callSid, this);
+    const reboundSessionCount = this.deps.homekit.setMulawPassthrough(this.mulawStream);
+    if (reboundSessionCount > 0) {
+      this.markHomekitSessionStarted();
+    } else {
+      this.deps.homekit.triggerDoorbell();
+      this.startRingback();
+    }
+  }
+
+  /**
+   * @param {{ payload: string }} media
+   */
+  _handleMedia(media) {
+    if (!this.started || !this.currentCallSid) {
+      this.logger.warn('Media frame before start event', {
+        event: 'media',
+        reason: 'media-before-start',
+      });
+      this.connection.close();
+      return;
+    }
+    const mediaPayload = parseTwilioMediaPayload(media.payload, this.deps.mediaPayloadMaxBytes);
+    if (!mediaPayload.ok) {
+      const mediaPayloadError = /** @type {MediaPayloadParseError} */ (mediaPayload);
+      this.logger.warn('Media payload rejected', {
+        callSid: this.currentCallSid,
+        event: 'media',
+        reason: mediaPayloadError.reason,
+      });
+      this.connection.close();
+      return;
+    }
+    if (this.hasHomekitSession) {
+      // Only forward live-view audio. Buffering pre-answer audio adds seconds
+      // of catch-up latency when HomeKit finally starts ffmpeg.
+      // Drop frames while the buffer needs draining: for live audio,
+      // unbounded queueing behind a stalled ffmpeg is worse than a gap.
+      if (this.mulawStream.writableNeedDrain) {
+        if (!this.droppingFrames) {
+          this.droppingFrames = true;
+          this.logger.warn('Dropping media frames; mulaw buffer is full', {
+            callSid: this.currentCallSid,
+            event: 'media-frames-dropped',
+            reason: 'mulaw-buffer-full',
+          });
+        }
+      } else {
+        if (this.droppingFrames) {
+          this.droppingFrames = false;
+          this.logger.info('Resumed forwarding media frames', {
+            callSid: this.currentCallSid,
+            event: 'media-frames-resumed',
+          });
+        }
+        this.mulawStream.write(mediaPayload.decoded);
+      }
+    }
+    this.deps.state.markActivity(this.currentCallSid, 'twilio-media');
+  }
+
+  close() {
+    this._teardown('ws-close');
+  }
+
+  startRingback() {
+    if (this.ringbackTimer || !this.currentCallSid) return;
+    this.ringbackTimer = setInterval(() => {
+      if (this.closed || !this.currentCallSid) {
+        this.stopRingback('stream-ended');
+        return;
+      }
+      this.sendRingbackFrame();
+    }, 20);
+    if (typeof this.ringbackTimer.unref === 'function') this.ringbackTimer.unref();
+  }
+
+  stopRingback(reason) {
+    if (!this.ringbackTimer) return;
+    clearInterval(this.ringbackTimer);
+    this.ringbackTimer = null;
+    this.logger.info('Ringback media stopped', {
+      callSid: this.currentCallSid || undefined,
+      event: 'ringback-stopped',
+      reason,
+    });
+  }
+
+  markHomekitSessionStarted() {
+    this.hasHomekitSession = true;
+    this.stopRingback('homekit-session-started');
+  }
+
+  sendRingbackFrame() {
+    if (!this.currentCallSid || !this.started || this.closed) return;
+
+    const chunkSize = 160; // 20 ms of 8 kHz mu-law audio.
+    const chunk = Buffer.alloc(chunkSize);
+    for (let i = 0; i < chunkSize; i++) {
+      chunk[i] = this.ringbackPayload[this.ringbackOffset];
+      this.ringbackOffset = (this.ringbackOffset + 1) % this.ringbackPayload.length;
+    }
+
+    const activeCall = this.deps.state.getActiveCall();
+    if (!activeCall || activeCall.wsConnection !== this.connection || !activeCall.streamSid) return;
+    sendMulawAudio(activeCall, chunk);
+  }
+
+  _teardown(reason) {
+    if (this.closed) return;
+    this.closed = true;
+    this.stopRingback(reason);
+    this.logger.info('Media websocket session ended', {
+      callSid: this.currentCallSid || undefined,
+      event: 'session-ended',
+      reason,
+      messageCount: this.messageCount,
+    });
+    clearTimeout(this.startTimeout);
+    // Guard: close() can fire without a prior 'stop' event (e.g. network drop).
+    this.deps.homekit.clearMulawPassthrough(this.mulawStream);
+    this.mulawStream.destroy();
+    const { cleared } = this.deps.state.clearIfConnection(this.connection, reason);
+    if (this.currentCallSid && this.deps.registry.get(this.currentCallSid) === this) {
+      this.deps.registry.delete(this.currentCallSid);
+    }
+    if (cleared) {
+      this.deps.homekit.endHapSession();
+    }
+  }
+}
+
+module.exports = { MediaStream };

package/src/core/mulaw-audio.js

@@ -0,0 +1,233 @@
+'use strict';
+
+const SAMPLE_RATE_HZ = 8000;
+const DEFAULT_DTMF_TONE_MS = 650;
+const DEFAULT_DTMF_TRAILING_SILENCE_MS = 120;
+const DEFAULT_CHUNK_MS = 20;
+const RINGBACK_BURST_MS = 400;
+const RINGBACK_GAP_MS = 200;
+const RINGBACK_TAIL_MS = 2000;
+const MULAW_BIAS = 0x84;
+const MULAW_CLIP = 32635;
+
+const DTMF_FREQUENCIES = {
+  1: [697, 1209],
+  2: [697, 1336],
+  3: [697, 1477],
+  A: [697, 1633],
+  4: [770, 1209],
+  5: [770, 1336],
+  6: [770, 1477],
+  B: [770, 1633],
+  7: [852, 1209],
+  8: [852, 1336],
+  9: [852, 1477],
+  C: [852, 1633],
+  '*': [941, 1209],
+  0: [941, 1336],
+  '#': [941, 1477],
+  D: [941, 1633],
+};
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * @param {number} sample
+ * @returns {number}
+ */
+function linear16ToMulaw(sample) {
+  let sign = 0;
+  let magnitude = Math.round(sample);
+
+  if (magnitude < 0) {
+    sign = 0x80;
+    magnitude = -magnitude;
+  }
+  if (magnitude > MULAW_CLIP) magnitude = MULAW_CLIP;
+
+  magnitude += MULAW_BIAS;
+
+  let exponent = 7;
+  for (let mask = 0x4000; exponent > 0 && (magnitude & mask) === 0; mask >>= 1) {
+    exponent--;
+  }
+
+  const mantissa = (magnitude >> (exponent + 3)) & 0x0f;
+  return ~(sign | (exponent << 4) | mantissa) & 0xff;
+}
+
+/**
+ * Generate a Twilio-compatible raw mu-law/8kHz DTMF tone.
+ *
+ * @param {string | number} digit
+ * @param {{ toneMs?: number, trailingSilenceMs?: number, amplitude?: number }} [options]
+ * @returns {Buffer}
+ */
+function createDtmfMulawTone(digit, options = {}) {
+  const normalizedDigit = String(digit).toUpperCase();
+  const frequencies = DTMF_FREQUENCIES[normalizedDigit];
+  if (!frequencies) {
+    throw new Error(`Unsupported DTMF digit: ${digit}`);
+  }
+
+  const toneMs = options.toneMs ?? DEFAULT_DTMF_TONE_MS;
+  const trailingSilenceMs = options.trailingSilenceMs ?? DEFAULT_DTMF_TRAILING_SILENCE_MS;
+  const amplitude = options.amplitude ?? 12000;
+  const toneSamples = Math.round((SAMPLE_RATE_HZ * toneMs) / 1000);
+  const silenceSamples = Math.round((SAMPLE_RATE_HZ * trailingSilenceMs) / 1000);
+  const payload = Buffer.alloc(toneSamples + silenceSamples, 0xff);
+  const [lowFrequency, highFrequency] = frequencies;
+
+  for (let i = 0; i < toneSamples; i++) {
+    const t = i / SAMPLE_RATE_HZ;
+    const sample =
+      (amplitude *
+        (Math.sin(2 * Math.PI * lowFrequency * t) + Math.sin(2 * Math.PI * highFrequency * t))) /
+      2;
+    payload[i] = linear16ToMulaw(sample);
+  }
+
+  return payload;
+}
+
+/**
+ * Inverse of {@link linear16ToMulaw}.
+ *
+ * @param {number} mulawByte
+ * @returns {number}
+ */
+function mulawToLinear16(mulawByte) {
+  const u = ~mulawByte & 0xff;
+  const sign = u & 0x80;
+  const exponent = (u >> 4) & 0x07;
+  const mantissa = u & 0x0f;
+  const magnitude = (((mantissa << 3) + MULAW_BIAS) << exponent) - MULAW_BIAS;
+  return sign ? -magnitude : magnitude;
+}
+
+/**
+ * One ringback cycle as a PCM16/8kHz mono WAV file, for serving the
+ * ringtone over HTTP without shelling out to ffmpeg.
+ *
+ * @returns {Buffer}
+ */
+function createRingbackWav() {
+  const mulaw = createRingbackMulawCycle();
+  const pcm = Buffer.alloc(mulaw.length * 2);
+  for (let i = 0; i < mulaw.length; i++) {
+    pcm.writeInt16LE(mulawToLinear16(mulaw[i]), i * 2);
+  }
+
+  const header = Buffer.alloc(44);
+  header.write('RIFF', 0, 'ascii');
+  header.writeUInt32LE(36 + pcm.length, 4);
+  header.write('WAVE', 8, 'ascii');
+  header.write('fmt ', 12, 'ascii');
+  header.writeUInt32LE(16, 16); // fmt chunk size
+  header.writeUInt16LE(1, 20); // PCM
+  header.writeUInt16LE(1, 22); // mono
+  header.writeUInt32LE(SAMPLE_RATE_HZ, 24);
+  header.writeUInt32LE(SAMPLE_RATE_HZ * 2, 28); // byte rate
+  header.writeUInt16LE(2, 32); // block align
+  header.writeUInt16LE(16, 34); // bits per sample
+  header.write('data', 36, 'ascii');
+  header.writeUInt32LE(pcm.length, 40);
+  return Buffer.concat([header, pcm]);
+}
+
+/**
+ * Generate one UK-style ringback cycle as raw mu-law/8kHz audio:
+ * 400 ms tone, 200 ms silence, 400 ms tone, 2000 ms silence.
+ *
+ * @returns {Buffer}
+ */
+function createRingbackMulawCycle() {
+  const burst = createDualToneMulaw(400, 450, RINGBACK_BURST_MS, 9000);
+  const gap = Buffer.alloc(Math.round((SAMPLE_RATE_HZ * RINGBACK_GAP_MS) / 1000), 0xff);
+  const tail = Buffer.alloc(Math.round((SAMPLE_RATE_HZ * RINGBACK_TAIL_MS) / 1000), 0xff);
+  return Buffer.concat([burst, gap, burst, tail]);
+}
+
+/**
+ * @param {number} lowFrequency
+ * @param {number} highFrequency
+ * @param {number} durationMs
+ * @param {number} amplitude
+ * @returns {Buffer}
+ */
+function createDualToneMulaw(lowFrequency, highFrequency, durationMs, amplitude) {
+  const samples = Math.round((SAMPLE_RATE_HZ * durationMs) / 1000);
+  const payload = Buffer.alloc(samples);
+
+  for (let i = 0; i < samples; i++) {
+    const t = i / SAMPLE_RATE_HZ;
+    const sample =
+      (amplitude *
+        (Math.sin(2 * Math.PI * lowFrequency * t) + Math.sin(2 * Math.PI * highFrequency * t))) /
+      2;
+    payload[i] = linear16ToMulaw(sample);
+  }
+
+  return payload;
+}
+
+/**
+ * @param {{ streamSid: string, wsConnection: { sendUTF: (message: string) => void } }} activeCall
+ * @param {Buffer} payload
+ */
+function sendMulawAudio(activeCall, payload) {
+  if (!activeCall || !activeCall.streamSid || !activeCall.wsConnection) {
+    throw new Error('Cannot send audio without an active media stream');
+  }
+  activeCall.wsConnection.sendUTF(
+    JSON.stringify({
+      event: 'media',
+      streamSid: activeCall.streamSid,
+      media: { payload: payload.toString('base64') },
+    })
+  );
+}
+
+/**
+ * @param {{ streamSid: string, wsConnection: { sendUTF: (message: string) => void } }} activeCall
+ * @param {string} digits
+ * @param {{ chunkMs?: number, toneMs?: number, trailingSilenceMs?: number }} [options]
+ */
+async function sendDtmfSequence(activeCall, digits, options = {}) {
+  if (!activeCall || !activeCall.streamSid || !activeCall.wsConnection) {
+    throw new Error('Cannot send DTMF without an active media stream');
+  }
+
+  const chunkMs = options.chunkMs ?? DEFAULT_CHUNK_MS;
+  const chunkSize = Math.max(1, Math.round((SAMPLE_RATE_HZ * chunkMs) / 1000));
+
+  for (const digit of String(digits)) {
+    if (digit === 'w') {
+      await sleep(500);
+      continue;
+    }
+    if (digit === 'W') {
+      await sleep(1000);
+      continue;
+    }
+
+    const payload = createDtmfMulawTone(digit, options);
+    for (let offset = 0; offset < payload.length; offset += chunkSize) {
+      const chunk = payload.subarray(offset, offset + chunkSize);
+      sendMulawAudio(activeCall, chunk);
+      await sleep(chunkMs);
+    }
+  }
+}
+
+module.exports = {
+  createDtmfMulawTone,
+  createRingbackMulawCycle,
+  createRingbackWav,
+  linear16ToMulaw,
+  mulawToLinear16,
+  sendDtmfSequence,
+  sendMulawAudio,
+};