matterbridge 3.4.3-dev-20251209-e6cb85f → 3.4.3

package/dist/utils/format.js

@@ -1,9 +1,51 @@
+/**
+ * @description This file contains the format functions.
+ * @file format.ts
+ * @author Luca Liguori
+ * @created 2025-10-20
+ * @version 1.0.0
+ * @license Apache-2.0
+ *
+ * Copyright 2025, 2026, 2027 Luca Liguori.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Format a timestamp into a human-readable string.
+ *
+ * @param {number} timestamp - The timestamp in milliseconds since the Unix epoch.
+ * @returns {string} - The formatted timestamp.
+ */
 export function formatTimeStamp(timestamp) {
     return `${new Date(timestamp).toLocaleString()}`;
 }
+/**
+ * Format a percentage into a human-readable string.
+ *
+ * @param {number} percent - The percentage value.
+ * @param {number} digits - The number of decimal places.
+ * @returns {string} - The formatted percentage.
+ */
 export function formatPercent(percent, digits = 2) {
     return `${percent.toFixed(digits)} %`;
 }
+/**
+ * Format bytes into a human-readable string.
+ *
+ * @param {number} bytes - The number of bytes.
+ * @param {number} digits - The number of decimal places.
+ * @returns {string} - The formatted byte string.
+ */
 export function formatBytes(bytes, digits = 2) {
     if (bytes === 0)
         return `${bytes.toFixed(digits)} B`;
@@ -12,6 +54,12 @@ export function formatBytes(bytes, digits = 2) {
     const value = bytes / Math.pow(1024, idx);
     return `${value.toFixed(digits)} ${units[idx]}`;
 }
+/**
+ * Function to format system uptime with only the most significant unit
+ *
+ * @param {number} seconds - The number of seconds to format
+ * @returns {string} The formatted uptime string
+ */
 export function formatUptime(seconds) {
     if (seconds >= 86400) {
         const days = Math.floor(seconds / 86400);
@@ -27,3 +75,4 @@ export function formatUptime(seconds) {
     }
     return `${seconds} second${seconds !== 1 ? 's' : ''}`;
 }
+//# sourceMappingURL=format.js.map

package/dist/utils/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,OAAO,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,SAAiB,CAAC;IAC/D,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,SAAiB,CAAC;IAC3D,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;IACrD,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrF,MAAM,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC1C,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;AAClD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,CAAC;QACzC,OAAO,GAAG,IAAI,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAC/C,CAAC;IACD,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;QACzC,OAAO,GAAG,KAAK,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAClD,CAAC;IACD,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC;QAClB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;QACzC,OAAO,GAAG,OAAO,UAAU,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,GAAG,OAAO,UAAU,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AACxD,CAAC"}

package/dist/utils/hex.d.ts

@@ -0,0 +1,89 @@
+/**
+ * This file contains the hex functions.
+ *
+ * @file hex.ts
+ * @author Luca Liguori
+ * @created 2025-05-06
+ * @version 1.0.0
+ * @license Apache-2.0
+ *
+ * Copyright 2025, 2026, 2027 Luca Liguori.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Converts an ArrayBuffer or Uint8Array to a hexadecimal string.
+ *
+ * Accepts any {ArrayBufferLike} input: a raw ArrayBuffer (binary data storage) or
+ * a Uint8Array (TypedArray view over an ArrayBuffer). While an ArrayBuffer holds
+ * the raw memory, a Uint8Array is a typed view into that memory, letting you access
+ * its bytes directly. This function normalizes both by creating a Uint8Array view
+ * before conversion.
+ *
+ * @param {ArrayBufferLike} buffer - The buffer or typed-array view to convert.
+ * @returns {string} A lowercase hex string representation of the buffer's bytes.
+ *
+ * @throws {TypeError} If the input is not an ArrayBuffer or ArrayBufferView.
+ */
+export declare function bufferToHex(buffer: ArrayBufferLike): string;
+/**
+ * Converts a hexadecimal string to a Uint8Array.
+ *
+ * @param {string} hex - The hex string to convert. Can include uppercase or lowercase characters.
+ * @returns {Uint8Array} A Uint8Array representing the corresponding binary data.
+ *
+ * @throws {TypeError} If the input is not a string.
+ * @throws {Error} If the input length is odd or contains non-hex characters.
+ */
+export declare function hexToBuffer(hex: string): Uint8Array;
+/**
+ * Converts a PEM (Privacy-Enhanced Mail) formatted string to a Uint8Array.
+ *
+ * PEM format is a base64-encoded format commonly used for cryptographic keys and certificates,
+ * wrapped with header and footer lines like "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----".
+ * This function extracts the base64 content and converts it to binary data using Node.js Buffer API.
+ *
+ * @param {string} pem - The PEM formatted string to convert.
+ * @param {boolean} validate - Whether to validate the PEM content using Node.js crypto module. Default is false.
+ * @returns {Uint8Array} A Uint8Array representing the decoded binary data.
+ *
+ * @throws {TypeError} If the input is not a string.
+ * @throws {Error} If the PEM format is invalid, contains invalid base64 characters, or validation fails.
+ */
+export declare function pemToBuffer(pem: string, validate?: boolean): Uint8Array;
+/**
+ * Extracts the raw 32-byte private key scalar from an EC private key PEM.
+ *
+ * This function parses an EC private key in PEM format and extracts the raw
+ * 32-byte private scalar (the "d" value) used in elliptic curve cryptography.
+ * This is the actual secret key material.
+ *
+ * @param {string} pemPrivateKey - The EC private key in PEM format
+ * @returns {Uint8Array} The raw 32-byte private key scalar
+ * @throws {Error} If the input is not a valid EC private key PEM
+ *
+ * @example
+ * ```typescript
+ * const pemKey = `-----BEGIN EC PRIVATE KEY-----
+ * MHcCAQEEIFBxqFkUxMoN2JkUXLFeiZnLNUpftjLi0sKMbZ6uajHXoAoGCCqGSM49
+ * AwEHoUQDQgAEcJ3eH/rG3zf9WmqMjh5eBSkeXz3Cb4Fig1rTosfHmgyjx/WnLPEe
+ * BF4SHvLo0G2COJEHa/VDE5EiKWO9ZR6AOQ==
+ * -----END EC PRIVATE KEY-----`;
+ *
+ * const rawKey = extractPrivateKeyRaw(pemKey);
+ * console.log(rawKey.length); // 32
+ * console.log(bufferToHex(rawKey)); // hex representation of the private scalar
+ * ```
+ */
+export declare function extractPrivateKeyRaw(pemPrivateKey: string): Uint8Array;
+//# sourceMappingURL=hex.d.ts.map

package/dist/utils/hex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hex.d.ts","sourceRoot":"","sources":["../../src/utils/hex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAa3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAgCnD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,OAAe,GAAG,UAAU,CAoG9E;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,CAgCtE"}

package/dist/utils/hex.js

@@ -1,39 +1,114 @@
+/**
+ * This file contains the hex functions.
+ *
+ * @file hex.ts
+ * @author Luca Liguori
+ * @created 2025-05-06
+ * @version 1.0.0
+ * @license Apache-2.0
+ *
+ * Copyright 2025, 2026, 2027 Luca Liguori.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 import { createPublicKey, createPrivateKey, X509Certificate } from 'node:crypto';
+/**
+ * Converts an ArrayBuffer or Uint8Array to a hexadecimal string.
+ *
+ * Accepts any {ArrayBufferLike} input: a raw ArrayBuffer (binary data storage) or
+ * a Uint8Array (TypedArray view over an ArrayBuffer). While an ArrayBuffer holds
+ * the raw memory, a Uint8Array is a typed view into that memory, letting you access
+ * its bytes directly. This function normalizes both by creating a Uint8Array view
+ * before conversion.
+ *
+ * @param {ArrayBufferLike} buffer - The buffer or typed-array view to convert.
+ * @returns {string} A lowercase hex string representation of the buffer's bytes.
+ *
+ * @throws {TypeError} If the input is not an ArrayBuffer or ArrayBufferView.
+ */
 export function bufferToHex(buffer) {
+    // Check if the input is an ArrayBuffer or ArrayBufferView
     if (!(buffer instanceof ArrayBuffer || ArrayBuffer.isView(buffer))) {
         throw new TypeError('Expected input to be an ArrayBuffer or ArrayBufferView');
     }
+    // Create a Uint8Array view over the buffer
     const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+    // Convert each byte to 2-digit hex
     return Array.from(bytes)
         .map((byte) => byte.toString(16).padStart(2, '0'))
         .join('');
 }
+/**
+ * Converts a hexadecimal string to a Uint8Array.
+ *
+ * @param {string} hex - The hex string to convert. Can include uppercase or lowercase characters.
+ * @returns {Uint8Array} A Uint8Array representing the corresponding binary data.
+ *
+ * @throws {TypeError} If the input is not a string.
+ * @throws {Error} If the input length is odd or contains non-hex characters.
+ */
 export function hexToBuffer(hex) {
+    // Ensure the input is a string
     if (typeof hex !== 'string') {
         throw new TypeError('Expected a string for hex input');
     }
+    // Trim any whitespace from the input string
     const cleaned = hex.trim();
+    // Check if the length of the hex string is even
     if (cleaned.length % 2 !== 0) {
         throw new Error('Invalid hex string length, must be even');
     }
+    // Validate that the string contains only valid hex characters
     if (!/^[0-9a-fA-F]*$/.test(cleaned)) {
         throw new Error('Invalid hex string, contains non-hex characters');
     }
+    // Calculate the length of the resulting Uint8Array
     const length = cleaned.length / 2;
+    // Create a Uint8Array to hold the binary data
     const result = new Uint8Array(length);
+    // Convert each pair of hex characters into a byte
     for (let i = 0; i < length; i++) {
         result[i] = parseInt(cleaned.substr(i * 2, 2), 16);
     }
+    // Return the resulting Uint8Array
     return result;
 }
+/**
+ * Converts a PEM (Privacy-Enhanced Mail) formatted string to a Uint8Array.
+ *
+ * PEM format is a base64-encoded format commonly used for cryptographic keys and certificates,
+ * wrapped with header and footer lines like "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----".
+ * This function extracts the base64 content and converts it to binary data using Node.js Buffer API.
+ *
+ * @param {string} pem - The PEM formatted string to convert.
+ * @param {boolean} validate - Whether to validate the PEM content using Node.js crypto module. Default is false.
+ * @returns {Uint8Array} A Uint8Array representing the decoded binary data.
+ *
+ * @throws {TypeError} If the input is not a string.
+ * @throws {Error} If the PEM format is invalid, contains invalid base64 characters, or validation fails.
+ */
 export function pemToBuffer(pem, validate = false) {
+    // Ensure the input is a string
     if (typeof pem !== 'string') {
         throw new TypeError('Expected a string for PEM input');
     }
+    // Trim whitespace from the input
     const cleaned = pem.trim();
+    // Check if the string appears to be in PEM format
     if (!cleaned.includes('-----BEGIN') || !cleaned.includes('-----END')) {
         throw new Error('Invalid PEM format: missing BEGIN/END markers');
     }
+    // Extract the base64 content between the header and footer
     const lines = cleaned.split('\n');
     const base64Lines = [];
     let inContent = false;
@@ -54,65 +129,114 @@ export function pemToBuffer(pem, validate = false) {
     if (base64Lines.length === 0) {
         throw new Error('Invalid PEM format: no content found between BEGIN/END markers');
     }
+    // Join all base64 lines together
     const base64String = base64Lines.join('');
+    // Validate base64 string format
     if (!/^[A-Za-z0-9+/]*={0,2}$/.test(base64String)) {
         throw new Error('Invalid PEM format: contains invalid base64 characters');
     }
     try {
+        // Use Node.js Buffer API instead of legacy atob()
         const buffer = Buffer.from(base64String, 'base64');
+        // Convert Buffer to Uint8Array
         const result = new Uint8Array(buffer);
+        // Validate PEM content using Node.js crypto module if requested
         if (validate) {
             try {
+                // Determine PEM type from the header and validate accordingly
                 const pemType = cleaned.match(/-----BEGIN\s+([^-]+)-----/)?.[1]?.trim();
                 if (pemType?.includes('CERTIFICATE')) {
+                    // Use X509Certificate for robust certificate validation
                     const cert = new X509Certificate(pem);
+                    // Check validity period
                     if (cert.validFrom && cert.validTo) {
                         const now = Date.now();
                         const from = Date.parse(cert.validFrom);
                         const to = Date.parse(cert.validTo);
+                        // istanbul ignore next if
                         if (now < from || now > to) {
                             throw new Error('Certificate is not currently valid');
                         }
                     }
+                    // Check subject/issuer fields
+                    // istanbul ignore next if
                     if (!cert.subject || !cert.issuer) {
                         throw new Error('Certificate missing subject or issuer');
                     }
+                    // Optionally check signature (not possible without CA chain)
                 }
                 else if (pemType?.includes('PRIVATE KEY')) {
+                    // For private keys, try to create a private key
                     createPrivateKey({ key: pem, format: 'pem' });
                 }
                 else if (pemType?.includes('PUBLIC KEY')) {
+                    // For public keys, try to create a public key
                     createPublicKey({ key: pem, format: 'pem' });
                 }
+                // If no specific type is detected, skip validation
             }
             catch (validationError) {
+                // istanbul ignore next
                 throw new Error(`PEM validation failed: ${validationError instanceof Error ? validationError.message : String(validationError)}`);
             }
         }
         return result;
     }
     catch (error) {
+        // istanbul ignore next
         throw new Error(`Failed to decode base64 content: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+/**
+ * Extracts the raw 32-byte private key scalar from an EC private key PEM.
+ *
+ * This function parses an EC private key in PEM format and extracts the raw
+ * 32-byte private scalar (the "d" value) used in elliptic curve cryptography.
+ * This is the actual secret key material.
+ *
+ * @param {string} pemPrivateKey - The EC private key in PEM format
+ * @returns {Uint8Array} The raw 32-byte private key scalar
+ * @throws {Error} If the input is not a valid EC private key PEM
+ *
+ * @example
+ * ```typescript
+ * const pemKey = `-----BEGIN EC PRIVATE KEY-----
+ * MHcCAQEEIFBxqFkUxMoN2JkUXLFeiZnLNUpftjLi0sKMbZ6uajHXoAoGCCqGSM49
+ * AwEHoUQDQgAEcJ3eH/rG3zf9WmqMjh5eBSkeXz3Cb4Fig1rTosfHmgyjx/WnLPEe
+ * BF4SHvLo0G2COJEHa/VDE5EiKWO9ZR6AOQ==
+ * -----END EC PRIVATE KEY-----`;
+ *
+ * const rawKey = extractPrivateKeyRaw(pemKey);
+ * console.log(rawKey.length); // 32
+ * console.log(bufferToHex(rawKey)); // hex representation of the private scalar
+ * ```
+ */
 export function extractPrivateKeyRaw(pemPrivateKey) {
     if (typeof pemPrivateKey !== 'string') {
         throw new TypeError('Expected a string for PEM private key input');
     }
+    // Extract the private key block
     const keyBlock = /-----BEGIN (?:EC )?PRIVATE KEY-----[^-]+-----END (?:EC )?PRIVATE KEY-----/s.exec(pemPrivateKey);
     if (!keyBlock) {
         throw new Error('No EC PRIVATE KEY block found in the supplied PEM');
     }
     try {
+        // Create a private key object
         const privateKey = createPrivateKey(keyBlock[0]);
+        // Export as PKCS#8 DER format
         const pkcs8Der = privateKey.export({ format: 'der', type: 'pkcs8' });
+        // For P-256 curves, the private scalar is the last 32 bytes of the PKCS#8 DER
+        // istanbul ignore next
         if (pkcs8Der.length < 32) {
             throw new Error('Invalid private key: DER data too short');
         }
+        // Extract the last 32 bytes which contain the raw private scalar
         const rawPrivateKey = pkcs8Der.subarray(pkcs8Der.length - 32);
         return new Uint8Array(rawPrivateKey);
     }
     catch (error) {
+        // istanbul ignore next
         throw new Error(`Failed to extract private key: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+//# sourceMappingURL=hex.js.map

package/dist/utils/hex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hex.js","sourceRoot":"","sources":["../../src/utils/hex.ts"],"names":[],"mappings":"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"}

package/dist/utils/inspector.d.ts

@@ -0,0 +1,87 @@
+/**
+ * This file contains the Inspector class.
+ *
+ * @file inspector.ts
+ * @author Luca Liguori
+ * @created 2025-10-12
+ * @version 1.0.0
+ * @license Apache-2.0
+ *
+ * Copyright 2025, 2026, 2027 Luca Liguori.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import EventEmitter from 'node:events';
+interface InspectorEvents {
+    /** Start the inspector */
+    start: [];
+    /** Stop the inspector */
+    stop: [];
+    /** Take a heap snapshot */
+    snapshot: [];
+    /** Heap snapshot done */
+    snapshot_done: [];
+    /** Run garbage collector */
+    gc: [type?: 'major' | 'minor', execution?: 'sync' | 'async'];
+    /** Garbage collection done */
+    gc_done: [type: 'major' | 'minor', execution: 'sync' | 'async'];
+}
+export declare class Inspector extends EventEmitter<InspectorEvents> {
+    private readonly name;
+    private readonly debug;
+    private readonly verbose;
+    private session;
+    private snapshotInterval?;
+    private snapshotInProgress;
+    private log;
+    constructor(name?: string, debug?: boolean, verbose?: boolean);
+    /**
+     * Starts the inspector for heap sampling.
+     *
+     * This function is called when the -inspect parameter is passed to matterbridge.
+     *
+     * The -snapshotinterval parameter can be used to set the heap snapshot interval. Default is undefined. Minimum is 30000 ms.
+     * The snapshot is saved in the heap_profiles directory that is created in the current working directory.
+     * The snapshot can be analyzed using vscode or Chrome DevTools or other tools that support heap snapshots.
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the heap sampling and saves the profile to a file in the heap_profiles directory.
+     * This function is called when the inspector is stopped.
+     */
+    stop(): Promise<void>;
+    /**
+     * Takes a heap snapshot and saves it to the file name 'heap_snapshots/<timestamp>.heapsnapshot'.
+     * If triggers a full garbage collection before and after taking the snapshot to reduce noise.
+     *
+     * This function is called periodically based on the -snapshotinterval parameter.
+     * The -snapshotinterval parameter must at least 30000 ms.
+     * The snapshot is saved in the heap_snapshots directory that is created in the current working directory.
+     * The snapshot can be analyzed using vscode or Chrome DevTools or other tools that support heap snapshots.
+     */
+    takeHeapSnapshot(): Promise<void>;
+    /**
+     * Manually trigger garbage collection to free memory (if exposed with --expose-gc)
+     *
+     * @param {'major' | 'minor'} type - The type of garbage collection to perform ('major' or 'minor'). Default is 'major'.
+     * @param {'sync' | 'async'} execution - The execution mode of garbage collection ('sync' or 'async'). Default is 'async'.
+     *
+     * @remarks
+     * - major collection refers to old-generation mark-sweep/mark-compact cycles.
+     * - minor collection refers to young-generation collections (scavenges).
+     * - sync execution blocks the main thread until GC is complete, which can cause pauses.
+     */
+    runGarbageCollector(type?: 'major' | 'minor', execution?: 'sync' | 'async'): void;
+}
+export {};
+//# sourceMappingURL=inspector.d.ts.map

package/dist/utils/inspector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspector.d.ts","sourceRoot":"","sources":["../../src/utils/inspector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,OAAO,YAAY,MAAM,aAAa,CAAC;AAMvC,UAAU,eAAe;IACvB,0BAA0B;IAC1B,KAAK,EAAE,EAAE,CAAC;IACV,yBAAyB;IACzB,IAAI,EAAE,EAAE,CAAC;IACT,2BAA2B;IAC3B,QAAQ,EAAE,EAAE,CAAC;IACb,yBAAyB;IACzB,aAAa,EAAE,EAAE,CAAC;IAClB,4BAA4B;IAC5B,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IAC7D,8BAA8B;IAC9B,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;CACjE;AAED,qBAAa,SAAU,SAAQ,YAAY,CAAC,eAAe,CAAC;IAQxD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAT1B,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,gBAAgB,CAAC,CAAiB;IAE1C,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,GAAG,CAAa;gBAGL,IAAI,GAAE,MAAoB,EAC1B,KAAK,GAAE,OAAe,EACtB,OAAO,GAAE,OAAe;IA6B3C;;;;;;;;OAQG;IACG,KAAK;IAmDX;;;OAGG;IACG,IAAI;IAuCV;;;;;;;;OAQG;IACG,gBAAgB;IAsEtB;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,IAAI,GAAE,OAAO,GAAG,OAAiB,EAAE,SAAS,GAAE,MAAM,GAAG,OAAiB;CAe7F"}

package/dist/utils/inspector.js

@@ -1,3 +1,27 @@
+/**
+ * This file contains the Inspector class.
+ *
+ * @file inspector.ts
+ * @author Luca Liguori
+ * @created 2025-10-12
+ * @version 1.0.0
+ * @license Apache-2.0
+ *
+ * Copyright 2025, 2026, 2027 Luca Liguori.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/* eslint-disable no-console */
 if (process.argv.includes('--loader') || process.argv.includes('-loader'))
     console.log('\u001B[32mInspector loaded.\u001B[40;0m');
 import EventEmitter from 'node:events';
@@ -21,7 +45,7 @@ export class Inspector extends EventEmitter {
         if (process.argv.includes('--verbose') || process.argv.includes('-verbose')) {
             this.verbose = true;
         }
-        this.log = new AnsiLogger({ logName: this.name, logTimestampFormat: 4, logLevel: this.debug ? "debug" : "info" });
+        this.log = new AnsiLogger({ logName: this.name, logTimestampFormat: 4 /* TimestampFormat.TIME_MILLIS */, logLevel: this.debug ? "debug" /* LogLevel.DEBUG */ : "info" /* LogLevel.INFO */ });
         this.log.logNameColor = YELLOW;
         this.on('start', () => {
             this.start();
@@ -36,6 +60,15 @@ export class Inspector extends EventEmitter {
             this.runGarbageCollector();
         });
     }
+    /**
+     * Starts the inspector for heap sampling.
+     *
+     * This function is called when the -inspect parameter is passed to matterbridge.
+     *
+     * The -snapshotinterval parameter can be used to set the heap snapshot interval. Default is undefined. Minimum is 30000 ms.
+     * The snapshot is saved in the heap_profiles directory that is created in the current working directory.
+     * The snapshot can be analyzed using vscode or Chrome DevTools or other tools that support heap snapshots.
+     */
     async start() {
         if (this.session) {
             this.log.warn('Inspector session already active.');
@@ -44,7 +77,9 @@ export class Inspector extends EventEmitter {
         const { Session } = await import('node:inspector');
         const { mkdirSync } = await import('node:fs');
         this.log.debug(`Starting heap sampling...`);
+        // Create the heap profiles directory if it doesn't exist
         mkdirSync('heap_profiles', { recursive: true });
+        // Create the heap snapshots directory if it doesn't exist
         mkdirSync('heap_snapshots', { recursive: true });
         try {
             this.session = new Session();
@@ -53,6 +88,7 @@ export class Inspector extends EventEmitter {
                 this.session?.post('HeapProfiler.startSampling', (err) => (err ? reject(err) : resolve()));
             });
             this.log.debug(`Started heap sampling`);
+            // Set an interval to take heap snapshots
             const { getIntParameter } = await import('./commandLine.js');
             const interval = getIntParameter('snapshotinterval');
             if (interval && interval >= 30000) {
@@ -81,6 +117,10 @@ export class Inspector extends EventEmitter {
             return;
         }
     }
+    /**
+     * Stops the heap sampling and saves the profile to a file in the heap_profiles directory.
+     * This function is called when the inspector is stopped.
+     */
     async stop() {
         if (!this.session) {
             this.log.warn('No active inspector session.');
@@ -91,7 +131,9 @@ export class Inspector extends EventEmitter {
         this.log.debug(`Stopping heap sampling...`);
         if (this.snapshotInterval) {
             this.log.debug(`Clearing heap snapshot interval...`);
+            // Clear the snapshot interval if it exists
             clearInterval(this.snapshotInterval);
+            // Take a final heap snapshot before stopping
             await this.takeHeapSnapshot();
         }
         try {
@@ -113,6 +155,15 @@ export class Inspector extends EventEmitter {
             this.log.debug(`Stopped heap sampling`);
         }
     }
+    /**
+     * Takes a heap snapshot and saves it to the file name 'heap_snapshots/<timestamp>.heapsnapshot'.
+     * If triggers a full garbage collection before and after taking the snapshot to reduce noise.
+     *
+     * This function is called periodically based on the -snapshotinterval parameter.
+     * The -snapshotinterval parameter must at least 30000 ms.
+     * The snapshot is saved in the heap_snapshots directory that is created in the current working directory.
+     * The snapshot can be analyzed using vscode or Chrome DevTools or other tools that support heap snapshots.
+     */
     async takeHeapSnapshot() {
         if (!this.session) {
             this.log.warn('No active inspector session.');
@@ -128,6 +179,7 @@ export class Inspector extends EventEmitter {
         const path = await import('node:path');
         const safeTimestamp = new Date().toISOString().replace(/[<>:"/\\|?*]/g, '-');
         const filename = path.join('heap_snapshots', `${safeTimestamp}.heapsnapshot`);
+        // Trigger a garbage collection before taking the snapshot to reduce noise
         this.runGarbageCollector('minor', 'async');
         this.runGarbageCollector('major', 'async');
         if (this.debug)
@@ -140,13 +192,16 @@ export class Inspector extends EventEmitter {
         };
         stream.once('error', onStreamError);
         const chunksListener = (notification) => {
+            // notification.params.chunk is a string; write directly to the stream
             if (!stream.write(notification.params.chunk)) {
+                // If backpressure engages, it's fine; the stream will buffer internally. We don't block the inspector.
             }
         };
         this.session.on('HeapProfiler.addHeapSnapshotChunk', chunksListener);
         try {
             await new Promise((resolve) => {
                 this.session?.post('HeapProfiler.takeHeapSnapshot', (err) => {
+                    // Detach chunk listener and close the stream, then perform post-actions
                     this.session?.off('HeapProfiler.addHeapSnapshotChunk', chunksListener);
                     const finalize = () => {
                         if (!err && !streamErrored) {
@@ -163,6 +218,7 @@ export class Inspector extends EventEmitter {
                         }
                         resolve();
                     };
+                    // End stream and wait for finish or error
                     try {
                         stream.end(() => finalize());
                     }
@@ -177,6 +233,17 @@ export class Inspector extends EventEmitter {
             this.snapshotInProgress = false;
         }
     }
+    /**
+     * Manually trigger garbage collection to free memory (if exposed with --expose-gc)
+     *
+     * @param {'major' | 'minor'} type - The type of garbage collection to perform ('major' or 'minor'). Default is 'major'.
+     * @param {'sync' | 'async'} execution - The execution mode of garbage collection ('sync' or 'async'). Default is 'async'.
+     *
+     * @remarks
+     * - major collection refers to old-generation mark-sweep/mark-compact cycles.
+     * - minor collection refers to young-generation collections (scavenges).
+     * - sync execution blocks the main thread until GC is complete, which can cause pauses.
+     */
     runGarbageCollector(type = 'major', execution = 'async') {
         if (global.gc && typeof global.gc === 'function') {
             try {
@@ -198,3 +265,4 @@ export class Inspector extends EventEmitter {
         }
     }
 }
+//# sourceMappingURL=inspector.js.map