@trap_stevo/filetide 0.0.85 → 0.0.86

package/SCL-1.0-Universal.md

@@ -0,0 +1,228 @@
+# SCL-1.0-Universal — Steven Compton Universal License v1.0
+(Source-Available, No Redistribution, No Reverse Engineering)
+
+**Effective Date:** September 10, 2024  
+**Licensor:** Hassan Steven Compton (Steven Compton) (“Licensor”)  
+**Package:** @trap_stevo/filetide (“Package”)  
+**Licensee:** Any individual or entity installing, using, referencing, or integrating the “Package”
+
+**SPDX Identifier:** SCL-1.0-Universal
+
+---
+
+## 1. Definitions
+
+### **1.1 “Package”**  
+Refers to the software identified as @trap_stevo/filetide, including its source code, object code, binaries, compiled outputs, metadata, and documentation.
+
+### **1.2 “Source Code”**  
+Human-readable implementation of the “Package”, whether distributed or not.
+
+### **1.3 “Dependent System”**  
+Means any system, software, hardware, firmware, service, device, environment, runtime, application, platform, embedded implementation, virtual machine, cloud service, or any other construct that uses, integrates, links to, or depends upon the “Package”, directly or indirectly, without including or exposing the “Package’s” code or internal structure.
+
+### **1.4 “Derivative Work”**  
+Any software, product, service, system, or implementation based on or derived from the “Package’s” source code, object code, architecture, structure, behavior, or design, in part or in whole.
+
+---
+
+## 2. Ownership
+
+The “Licensor” retains exclusive ownership of all rights, title, and interest in and to the “Package”, including all associated intellectual property.
+
+This Agreement transfers no ownership rights to the “Licensee”.
+
+---
+
+## 3. Grant of License
+
+Subject to all terms of this Agreement, the “Licensor” grants the “Licensee” a limited, non-exclusive, revocable, non-transferable, and non-sublicensable license to:
+
+1. Use the “Package” as a dependency in “Dependent Systems” created by the “Licensee”.  
+2. Distribute “Dependent Systems”, provided the “Package” is **never** included, exposed, modified, redistributed, or replicated in any form.
+
+Nothing in this Agreement grants the “Licensee” permission to:
+
+- modify the “Package”  
+- redistribute the “Package”  
+- fork the “Package”  
+- repackage the “Package”  
+- host the “Package”  
+- analyze the “Package”  
+- expose internal behavior of the “Package”  
+- create derivative or competing software based on the “Package”  
+
+---
+
+## 4. Prohibited Uses
+
+Without the express written permission of the “Licensor”, the “Licensee” shall not:
+
+1. Modify, decompile, reverse-engineer, or disassemble the “Package” in any way.  
+2. Include the “Package’s” source code or object code in any distributed software, service, or application.  
+3. Use the “Package” to create a competing product or service that replicates the functionality of the “Package”.  
+4. Make the “Package” publicly available, including uploading it to public repositories or including it in distributed software bundles.  
+5. Attempt to extract or analyze the functionality, structure, or behavior of the “Package” through runtime inspection, instrumentation, reflection, or behavioral analysis.  
+6. Privately share, sublicense, or distribute the “Package” or any portion thereof, whether internally within an organization or externally to any third party, without written authorization.  
+7. Remove, obscure, obfuscate, or alter any attribution, copyright notices, proprietary labels, or identifiers included in the “Package”.  
+8. Re-upload, rename, fork, or redistribute the “Package” or any portion thereof on any registry, platform, or namespace other than that explicitly maintained or authorized by the “Licensor”.  
+9. Use the “Package” in any way that violates applicable laws, infringes on third-party rights, or breaches this Agreement.
+
+Any attempt to bypass or circumvent these restrictions constitutes a material breach.
+
+### 4.A. No Competitive Re-implementation
+
+“Licensee” shall not create, develop, train, test, benchmark, or distribute any software, system, service, model, or method that uses, incorporates, is derived from, or is based upon the “Package’s” source code, object code, algorithms, data structures, interfaces, protocols, internal behavior, design, architecture, or execution characteristics for the purpose of creating a product or service that provides substantially similar functionality to the “Package”, competes with the “Package”, or reproduces its core operations.
+
+“Licensee” shall not directly or indirectly analyze, observe, measure, study, or evaluate the behavior, performance, outputs, or internal characteristics of the “Package” for the purpose of creating, validating, training, improving, or assisting any competing or functionally similar software, system, service, or model.
+
+Any such activity shall constitute creation of an unauthorized derivative work and is strictly prohibited.
+
+---
+
+## 5. Dependent System Requirements
+
+The “Licensee” may create and distribute “Dependent Systems” only if all of the following conditions are met:
+
+1. The “Dependent System” does **not** include or expose any portion of the “Package’s” source code or object code.  
+2. The “Dependent System” identifies the “Package” as a dependency in its documentation.  
+3. The “Dependent System” provides substantial original functionality.  
+4. The “Dependent System” does not replicate, emulate, reimplement, or mimic any significant part of the “Package’s” behavior or design.  
+5. The “Dependent System” complies fully with this Agreement.
+
+---
+
+## 6. Request for Additional Permissions
+
+The “Licensee” may request additional rights by contacting:
+
+**h.steven.compton13@gmail.com**
+
+Requests must:
+
+1. Be submitted in writing  
+2. Describe purpose, scope, and distribution method  
+
+The “Licensor” may:
+
+- approve or deny at sole discretion  
+- impose additional terms  
+- revoke previously granted permissions with written notice  
+
+All permissions must be explicit and in writing.
+
+---
+
+## 7. Violation of Terms (Termination)
+
+1. Any violation of this Agreement results in immediate termination of all licensed rights.  
+2. Upon termination, the “Licensee” must:  
+   - cease all use of the “Package”  
+   - remove the “Package” from all systems and environments  
+   - destroy all copies, including caches and build artifacts  
+   - confirm destruction in writing if requested  
+3. The “Licensor” may pursue damages, injunctive relief, or any other legal remedy.
+
+---
+
+## 8. No Warranty
+
+The “Package” is provided **“AS IS”**, without any warranty, express or implied, including but not limited to merchantability, fitness for a particular purpose, or non-infringement.
+
+The “Licensee” assumes all risk associated with use.
+
+---
+
+## 9. Intellectual Property Limitations
+
+Nothing in this Agreement grants the “Licensee” any rights under any patent, whether by implication, estoppel, exhaustion, or otherwise. Any use of the “Package” that would require a patent license must receive separate written permission from the “Licensor”.
+
+This Agreement also grants no rights to use the “Licensor’s” trademarks, service marks, branding, logos, product names, or organizational names. Any such use requires separate written permission.
+
+No patent rights, trademark rights, or branding rights are provided or implied by this license.
+
+---
+
+## 10. Patent Rights and Restrictions
+
+### 10.1 No Implied Patent License
+
+Except as expressly stated in this Section, the “Licensor” grants no license, covenant, immunity, or right under any patent or patent application owned, controlled, or licensable by the “Licensor”. All such rights are expressly reserved.
+
+### 10.2 Patent Grant for Non-Competitive Use
+
+Subject to full compliance with this Agreement, the “Licensor” grants the “Licensee” a limited, non-exclusive, non-transferable, revocable, royalty-free patent license to use any patent claims embodied in the “Package” solely to the extent necessary to use the unmodified “Package” as permitted under Section 3.
+
+This grant does not extend to:
+
+- derivative works
+
+- competing software
+
+- re-implementations
+
+- architectural replications
+
+- alternative implementations of patented methods
+
+- any use not directly involving the unmodified “Package”
+
+### 10.3 Patent Restriction for Competing Systems
+
+No patent license is granted for any software, system, service, or model that:
+
+- competes with the “Package”,
+
+- provides substantially similar core functionality,
+
+- implements any patented algorithm, method, design, architecture, or process used by the Package, or
+
+- is a re-implementation or functional substitute of the “Package”.
+
+Any such use constitutes patent infringement and is prohibited.
+
+### 10.4 Termination of Patent Rights
+
+Any violation of this Agreement immediately terminates all patent licenses granted herein. Upon termination, Licensee must cease all uses of the patented subject matter and destroy any implementations utilizing such technology.
+
+---
+
+## 11. Indemnification
+
+The “Licensee” agrees to indemnify and hold harmless the “Licensor” from any claims, damages, liabilities, losses, or expenses arising from:
+
+- violation of this Agreement  
+- misuse of the “Package”  
+- unlawful or infringing use  
+
+---
+
+## 12. Governing Law & Dispute Resolution
+
+This Agreement is governed by the laws of **Georgia, United States**, without regard to conflict-of-law principles.
+
+All disputes shall be resolved exclusively through binding arbitration in **Georgia, United States**.
+
+---
+
+## 13. Amendments
+
+The “Licensor” may modify this Agreement at any time.
+
+Changes take effect 30 days after posting at:
+
+**https://www.npmjs.com/package/@trap_stevo/filetide**
+
+Continued use of the “Package” constitutes acceptance of the updated terms.
+
+---
+
+## 14. Applicability to All Versions
+
+This Agreement applies to **all versions** of the “Package” downloaded, installed, or used on or after the Effective Date.
+
+Use of any version after this date constitutes acceptance of this License unless explicitly overridden by the “Licensor”.
+
+---
+
+**SPDX-License-Identifier: SCL-1.0-Universal**

package/dist/cjs/FileMessagerClient.js

@@ -15,6 +15,9 @@ const {
   significantMessageColors,
   errorMessageColors
 } = require("./HUDManagers/FileTideDebugUtilityManager");
+const {
+  STATES: NETWORK_TRAFFIC_STATES
+} = require("./HUDManagers/FileTideNetworkTrafficManager.js");
 const {
   FileTransferTrackingManager
 } = require("./HUDManagers/FileTransferTrackingManager.js");
@@ -42,10 +45,16 @@ class FileMessagerClient {
       maxReconnectionAttempts = 15,
       reconnectionAttempts = 15,
       maxReconnectionDelay = 10000,
+      tideDurationMs: _tideDurationMs = 125,
+      minTideBytes = 512 * 1024,
+      maxTideBytes = 8 * 1024 * 1024,
       ...messagerConfigurations
     } = messagerSettings;
     this.clientOptions = FileMessagerConfigManager.getClientOptions(_options);
     this.transporter = new FileTransferManager(transportOptions);
+    this.tideDurationMs = Math.max(25, _tideDurationMs);
+    this.minTideBytes = Math.max(512 * 1024, minTideBytes);
+    this.maxTideBytes = Math.max(this.minTideBytes, maxTideBytes);
     this.activeTransferTypes = new Map();
     this.clientTide = new HUDIoTide(maxReconnectionAttempts, reconnectionAttempts, maxReconnectionDelay, {
       persistentTideIDs: true,
@@ -56,13 +65,19 @@ class FileMessagerClient {
     });
     this.clients = new Map();
   }
+  recordNetworkThroughput(throughputBps) {
+    return this.transporter.recordNetworkThroughput(throughputBps);
+  }
+  getNetworkTrafficStatus() {
+    return this.transporter.getNetworkTrafficStatus();
+  }
   joinRoom(userID, roomName, options = {}, headers = {}, onConnect = null, onDisconnect = null, authURL = "", authHeaders = {}, useAuthentication = false, queryAuthToken = false) {
     const socketName = _assertClassBrand(_FileMessagerClient_brand, this, _createClientInstance).call(this, userID, {
       url: this.clientOptions.url
     }, options, headers, onConnect, onDisconnect, authURL, authHeaders, useAuthentication, queryAuthToken);
     return () => {
       this.clientTide.joinChannel(socketName, roomName, userID, () => {
-        FileTideDebugUtilityManager.outputGradient(`\n[FileTide ~ File Messager] ~ Client ~ ${userID} joined room ${roomName} successfully!`, significantMessageColors);
+        FileTideDebugUtilityManager.outputGradient(`\n[FileTide ~ Tider] ~ Client ~ ${userID} joined room ${roomName} successfully!`, significantMessageColors);
         this.clients.set(userID, {
           roomName
         });
@@ -111,18 +126,18 @@ class FileMessagerClient {
         transferType
       }, transferExpirationTime);
       if (!transferAccepted) {
-        FileTideDebugUtilityManager.outputGradient(`[FileTide ~ File Messager] ${recipientID} denied your transfer.`, errorMessageColors);
+        FileTideDebugUtilityManager.outputGradient(`[FileTide ~ Tider] ${recipientID} denied your transfer.`, errorMessageColors);
         return false;
       } else if (transferAccepted) {
-        FileTideDebugUtilityManager.outputGradient(`[FileTide ~ File Messager] ${recipientID} accepted your transfer!`, significantMessageColors);
+        FileTideDebugUtilityManager.outputGradient(`[FileTide ~ Tider] ${recipientID} accepted your transfer!`, significantMessageColors);
         return true;
       }
     } catch (error) {
       if (error.message.startsWith("Timeout: No response")) {
-        FileTideDebugUtilityManager.outputGradient("[FileTide ~ File Messager] Transfer approval timed out.", errorMessageColors);
+        FileTideDebugUtilityManager.outputGradient("[FileTide ~ Tider] Transfer approval timed out.", errorMessageColors);
         return false;
       }
-      FileTideDebugUtilityManager.outputGradient(`[FileTide ~ File Messager] Transfer approval refused.\n${error}`, errorMessageColors);
+      FileTideDebugUtilityManager.outputGradient(`[FileTide ~ Tider] Transfer approval refused.\n${error}`, errorMessageColors);
       return false;
     }
   }
@@ -166,7 +181,7 @@ class FileMessagerClient {
       });
       Promise.all(sendFilePromises).then(() => console.log("\nAll files in directory transferred successfully!")).catch(error => console.error("Did not transfer directory: ", error));
     } catch (error) {
-      FileTideDebugUtilityManager.outputGradient(`[FileTide ~ File Messager] ~ Refused directory transfer: ${error}`, errorMessageColors);
+      FileTideDebugUtilityManager.outputGradient(`[FileTide ~ Tider] ~ Refused directory transfer: ${error}`, errorMessageColors);
     }
   }
   async sendDirectoryLargeFile(clientID, recipientId, fileName, filePath = process.cwd(), destinationPath = null, fileSize, index = 0, tideSize = 500, minTideSize = 10, maxTideSize = 2000, transferRequestExpirationTime = 30000, metadata = {}) {
@@ -196,7 +211,7 @@ class FileMessagerClient {
   }
   async sendFile(clientID, recipientId, fileName, filePath = process.cwd(), destination = process.cwd(), fileSize, tideSize = 500, minTideSize = 10, maxTideSize = 2000, initiatingTransfer = true, inDirectory = false, largeFile = false, transferRequestExpirationTime = 30000, metadata = {}) {
     const destinationPath = FileUtilityManager.normalizePath(path.join(destination, fileName));
-    FileTideDebugUtilityManager.outputGradient(largeFile ? `[FileTide ~ File Messager] ~ Requesting to transfer large file ~ ${destinationPath} to ${recipientId}!` : `[FileTide ~ File Messager] ~ Requesting to transfer ~ ${destinationPath} to ${recipientId}!`, significantMessageColors);
+    FileTideDebugUtilityManager.outputGradient(largeFile ? `[FileTide ~ Tider] ~ Requesting to transfer large file ~ ${destinationPath} to ${recipientId}!` : `[FileTide ~ Tider] ~ Requesting to transfer ~ ${destinationPath} to ${recipientId}!`, significantMessageColors);
     const incomingType = this.activeTransferTypes.get(filePath);
     if (!inDirectory && initiatingTransfer) {
       const transferAllowed = incomingType && incomingType === "requestedTransfer" ? true : await this.allowedTransfer(clientID, recipientId, destinationPath, filePath, fileSize, 1, "file", "send", transferRequestExpirationTime);
@@ -227,12 +242,39 @@ class FileMessagerClient {
       size: fileSize
     };
     try {
-      let lastSendTime = Date.now();
-      const maxBatchSize = maxTideSize;
-      const minBatchSize = minTideSize;
-      let batchSize = tideSize > maxBatchSize || tideSize > minBatchSize ? tideSize : tideSize <= minBatchSize ? minBatchSize : 10;
       let transferInitiated = false;
-      const chunkBatch = [];
+      const currentTide = [];
+      const flushTide = () => {
+        if (currentTide.length <= 0) {
+          return;
+        }
+        const outgoingChunks = currentTide.splice(0, currentTide.length);
+        const firstChunk = outgoingChunks[0];
+        const lastChunk = outgoingChunks[outgoingChunks.length - 1];
+        const tideBytes = outgoingChunks.reduce((total, chunk) => total + chunk.chunkSize, 0);
+        this.clientTide.emitEvent(clientID, "client-to-client-transfer", {
+          tide: {
+            transferId: firstChunk.transferId,
+            senderID: firstChunk.senderID,
+            recipientId: firstChunk.recipientId,
+            fileName: firstChunk.fileName,
+            filePath: firstChunk.filePath,
+            fileSize: firstChunk.fileSize,
+            totalChunks: firstChunk.totalChunks,
+            firstChunkIndex: firstChunk.chunkIndex,
+            lastChunkIndex: lastChunk.chunkIndex,
+            completedChunks: lastChunk.completedChunks,
+            tideChunkCount: outgoingChunks.length,
+            tideBytes,
+            chunks: outgoingChunks.map(chunk => ({
+              chunkIndex: chunk.chunkIndex,
+              chunkSize: chunk.chunkSize,
+              fileChunk: chunk.fileChunk
+            })),
+            metadata: firstChunk.metadata
+          }
+        });
+      };
       await this.transporter.sendLargeFile(fileHandle, {
         recipientID: recipientId,
         originDetails: {
@@ -240,61 +282,48 @@ class FileMessagerClient {
           senderID: clientID
         },
         fileDetails,
-        onSendChunk: (transferId, chunkIndex, chunkSize, chunkData, totalChunks, completedChunks) => {
-          return new Promise(resolve => {
-            chunkBatch.push({
-              senderID: clientID,
-              recipientId,
-              fileName,
-              fileChunk: chunkData,
-              completedChunks,
-              totalChunks,
-              chunkIndex,
-              chunkSize,
-              filePath: destination,
-              fileSize,
-              metadata
-            });
-            if (!transferInitiated) {
-              this.clientTide.emitEvent(clientID, "client-to-client-transfer", {
-                chunkBatch
-              });
-              transferInitiated = true;
-              chunkBatch.length = 0;
-            }
-            if (chunkBatch.length >= batchSize) {
-              const now = Date.now();
-              const rtt = now - lastSendTime;
-              lastSendTime = now;
-              this.clientTide.emitEvent(clientID, "client-to-client-transfer", {
-                chunkBatch
-              });
-              chunkBatch.length = 0;
-              if (rtt >= 200 && batchSize < maxBatchSize) {
-                batchSize = Math.min(batchSize + 50, maxBatchSize);
-              } else if (rtt < 200 && batchSize > minBatchSize) {
-                batchSize = Math.max(batchSize - 50, minBatchSize);
-              }
-            }
-            resolve();
+        onSendChunk: async (transferId, chunkIndex, chunkSize, chunkData, totalChunks, completedChunks) => {
+          currentTide.push({
+            transferId,
+            senderID: clientID,
+            recipientId,
+            fileName,
+            fileChunk: chunkData,
+            completedChunks,
+            totalChunks,
+            chunkIndex,
+            chunkSize,
+            filePath: destination,
+            fileSize,
+            metadata
           });
+          if (!transferInitiated) {
+            flushTide();
+            transferInitiated = true;
+            return;
+          }
+          const adaptiveTideSize = _assertClassBrand(_FileMessagerClient_brand, this, _getAdaptiveTideSize).call(this, chunkSize, tideSize, minTideSize, maxTideSize);
+          if (currentTide.length >= adaptiveTideSize) {
+            flushTide();
+          }
         },
-        onComplete: transferId => {
-          return new Promise(resolve => {
-            if (chunkBatch.length > 0) {
-              this.clientTide.emitEvent(clientID, "client-to-client-transfer", {
-                chunkBatch
-              });
-              chunkBatch.length = 0;
-            }
-            this.clientTide.emitEvent(clientID, "transfer-complete", {
-              senderID: clientID,
-              recipientId,
-              fileName,
-              filePath: destination,
-              metadata
-            });
-            resolve();
+        onComplete: async () => {
+          flushTide();
+        },
+        onFailure: async (transferId, error) => {
+          /*
+           * Do not flush an unfinished Tide after
+           * the transfer has already failed.
+           */
+          currentTide.length = 0;
+          this.clientTide.emitEvent(clientID, "transfer-failed", {
+            transferId,
+            senderID: clientID,
+            recipientId,
+            fileName,
+            filePath: destination,
+            reason: error.message,
+            metadata
           });
         },
         onTiding: () => {
@@ -304,9 +333,10 @@ class FileMessagerClient {
           });
         }
       }, this.clientTide);
-      FileTideDebugUtilityManager.outputGradient(largeFile ? `[FileTide ~ File Messager] ~ Large file ~ ${fileName} transfer complete!` : `[FileTide ~ File Messager] ~ File ~ ${fileName} transfer complete!`, significantMessageColors);
+      FileTideDebugUtilityManager.outputGradient(largeFile ? `[FileTide ~ Tider] ~ Large file ~ ${fileName} transfer complete!` : `[FileTide ~ Tider] ~ File ~ ${fileName} transfer complete!`, significantMessageColors);
     } catch (error) {
-      FileTideDebugUtilityManager.outputGradient(largeFile ? `[FileTide ~ File Messager] ~ Error transferring large file: ${error.message}` : `[FileTide ~ File Messager] ~ Error transferring file ~ ${error.message}`, errorMessageColors);
+      FileTideDebugUtilityManager.outputGradient(largeFile ? `[FileTide ~ Tider] ~ Error transferring large file: ${error.message}` : `[FileTide ~ Tider] ~ Error transferring file ~ ${error.message}`, errorMessageColors);
+      throw error;
     } finally {
       await fileHandle.close();
     }
@@ -316,14 +346,48 @@ function _createClientInstance(clientID, clientOptions, options = {}, headers =
   this.clientTide.createIO(clientID, clientOptions.url, {
     transports: ["websocket"],
     ...options
-  }, headers, authURL, authHeaders, useAuthentication, queryAuthToken, onConnect, async () => {
+  }, headers, authURL, authHeaders, useAuthentication, queryAuthToken, (...connectionArguments) => {
+    this.transporter.updateNetworkTraffic({
+      online: true,
+      success: true
+    });
+    if (onConnect) {
+      return onConnect(...connectionArguments);
+    }
+  }, async (...disconnectArguments) => {
+    this.transporter.updateNetworkTraffic({
+      online: false
+    });
     FileTransferTrackingManager.outputCurrentTransfers();
     if (onDisconnect) {
-      await onDisconnect();
+      await onDisconnect(...disconnectArguments);
     }
   });
-  FileTideDebugUtilityManager.outputGradient(`\n[FileTide ~ File Messager] ~ Created client with ID ${clientID} and socket ${clientID}!`, significantMessageColors);
+  FileTideDebugUtilityManager.outputGradient(`\n[FileTide ~ Tider] ~ Created client with ID ${clientID} and socket ${clientID}!`, significantMessageColors);
   return clientID;
 }
+function _getAdaptiveTideSize(chunkSize, tideSize = 500, minTideSize = 10, maxTideSize = 2000) {
+  const networkStatus = this.transporter.getNetworkTrafficStatus();
+  const sendRateBps = Math.max(networkStatus.sendRateBps || chunkSize, chunkSize);
+  let tideDurationMs = this.tideDurationMs;
+  if (networkStatus.state === NETWORK_TRAFFIC_STATES.CONGESTED) {
+    tideDurationMs *= 0.50;
+  }
+
+  /*
+   * Determine how many chunks current network conditions
+   * can reasonably support during one Tide duration.
+   */
+  const networkTideBytes = Math.max(sendRateBps * (tideDurationMs / 1000), chunkSize);
+  const networkTideSize = Math.max(1, Math.floor(networkTideBytes / chunkSize));
+  const normalizedMinTideSize = Math.max(1, minTideSize);
+  const normalizedMaxTideSize = Math.max(normalizedMinTideSize, maxTideSize);
+  const preferredTideSize = Math.min(Math.max(tideSize, normalizedMinTideSize), normalizedMaxTideSize);
+  const adaptiveTideSize = Math.min(networkTideSize, preferredTideSize);
+  const minTideChunkSize = Math.max(1, Math.floor(this.minTideBytes / chunkSize));
+  const maxTideChunkSize = Math.max(1, Math.floor(this.maxTideBytes / chunkSize));
+  const optimizedTideSize = adaptiveTideSize >= minTideChunkSize ? adaptiveTideSize : Math.min(networkTideSize, preferredTideSize);
+  return Math.max(1, Math.min(optimizedTideSize, maxTideChunkSize, normalizedMaxTideSize));
+}
 ;
 module.exports = FileMessagerClient;