nport 2.0.6 → 2.0.7

package/CHANGELOG.md

@@ -5,6 +5,82 @@ All notable changes to NPort will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.7] - 2026-01-14
+
+### Added
+- 🌐 **Smart Network Warning System**: Intelligent handling of QUIC/network connectivity issues
+  - Automatic detection and filtering of QUIC protocol errors
+  - User-friendly warning messages instead of scary red error spam
+  - Bilingual support (English & Vietnamese)
+  - Smart throttling: Shows warning only after 5 errors, max once per 30 seconds
+  - Clear explanations of what's happening and how to fix it
+  - Automatic reset when connection is restored
+- 🔒 **Protected Subdomain Support**: Enhanced error handling for reserved subdomains
+  - User-friendly error message when trying to create protected subdomains (like `api`)
+  - Formatted error output matching existing error style
+  - Helpful suggestions to use alternative subdomain names
+  - Prevents accidental use of backend service subdomains
+
+### Improved
+- 🔇 **Cleaner Terminal Output**: No more error spam from cloudflared
+  - QUIC timeout errors are now silently tracked instead of displayed
+  - Network warnings filtered: "failed to accept QUIC stream", "timeout: no recent network activity", etc.
+  - Only shows meaningful warnings when there's an actual persistent issue
+  - Terminal stays clean and readable during normal operation
+- 📡 **Better User Communication**: Context-aware network issue reporting
+  - Explains that QUIC failures are usually not critical
+  - Tunnel continues working via HTTP/2 fallback
+  - Provides actionable troubleshooting steps
+  - Reassures users that the tunnel is still functional
+- ✨ **Better Error Messages**: Enhanced user feedback for protected subdomains
+  - Catches `SUBDOMAIN_PROTECTED` errors from backend
+  - Formats error messages consistently with other error types
+  - Shows actionable options when subdomain is reserved
+
+### Technical Details
+- **Network Error Patterns**: Added detection for 7 common QUIC/network error patterns
+- **State Management**: New network issue tracking in application state
+  - `networkIssueCount`: Counter for network errors
+  - `lastNetworkWarningTime`: Timestamp tracking for cooldown
+  - `shouldShowNetworkWarning()`: Smart decision logic
+- **Configuration**: New `NETWORK_CONFIG` with threshold and cooldown settings
+- **Bilingual Messages**: Complete translations for all network warning messages
+- **Protected Subdomain Handling**: Enhanced error handling in `src/api.js`
+  - Added check for `SUBDOMAIN_PROTECTED` error type
+  - Consistent formatting with existing error messages
+  - Clear user guidance for alternative subdomain choices
+
+### User Experience
+**Before:**
+```
+[Cloudflared] 2026-01-14T04:33:02Z ERR failed to accept QUIC stream...
+[Cloudflared] 2026-01-14T04:33:03Z ERR failed to accept QUIC stream...
+[Cloudflared] 2026-01-14T04:33:04Z ERR failed to accept QUIC stream...
+[Cloudflared] 2026-01-14T04:33:05Z ERR failed to accept QUIC stream...
+```
+
+**After:**
+```
+✔ [1/2] Connection established...
+✔ [2/2] Compression enabled...
+
+⚠️  NETWORK CONNECTIVITY ISSUE DETECTED
+   Cloudflared is having trouble maintaining a stable connection...
+   📡 Your tunnel is still working, but connection quality may be affected.
+   
+   💡 Possible reasons:
+      • Unstable internet connection or high packet loss
+      • Firewall/Router blocking UDP traffic (QUIC protocol)
+      • ISP throttling or network congestion
+      
+   🔧 What to try:
+      • Check your internet connection stability
+      • Try connecting from a different network
+      • Disable VPN/Proxy if you're using one
+      
+   ℹ️  This is usually not critical - your tunnel should continue working normally.
+```
+
 ## [2.0.6] - 2026-01-13
 
 ### Added
@@ -110,6 +186,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Version Upgrade Guide
 
+### From 2.0.6 to 2.0.7
+
+```bash
+npm install -g nport@latest
+```
+
+**What's New:**
+
+1. **Cleaner Terminal Experience**
+   - No more scary red QUIC error spam
+   - Smart network warnings when needed
+   - Automatic fallback to HTTP/2 when QUIC fails
+
+2. **Better Error Communication**
+   - Understand what's happening with your connection
+   - Clear explanations in your language (EN/VI)
+   - Actionable troubleshooting steps
+
+3. **When You'll See Warnings**
+   - Only after multiple network issues (not just one)
+   - Maximum once every 30 seconds (no spam)
+   - Automatically disappears when connection improves
+
+**Breaking Changes:** None - fully backward compatible!
+
 ### From 2.0.5 to 2.0.6
 
 ```bash

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Pham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -35,6 +35,17 @@ Perfect for:
 
 ## 📦 Installation
 
+### Requirements
+
+- **Node.js** >= 20.0.0
+- **npm** >= 10.0.0
+
+Check your versions:
+```bash
+node --version
+npm --version
+```
+
 ### NPM (Recommended)
 
 ```bash
@@ -406,8 +417,12 @@ If you find NPort useful, please consider supporting the project:
 ## 🙏 Credits
 
 - Created by [Nick Pham](https://github.com/tuanngocptn) from Vietnam
-- Powered by [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)
 - Inspired by [ngrok](https://ngrok.com) and [localtunnel](https://github.com/localtunnel/localtunnel)
+- Powered by [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)
+
+   <a href="https://www.cloudflare.com" target="_blank">
+      <img src="https://nport.link/assets/webp/cloudflare-logo-black.webp" alt="Cloudflare" height="60">
+   </a>
 
 ## 🔗 Links
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nport",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Free & open source ngrok alternative - Tunnel HTTP/HTTPS connections via Cloudflare Edge with custom subdomains",
   "type": "module",
   "main": "index.js",
@@ -8,8 +8,8 @@
     "nport": "index.js"
   },
   "engines": {
-    "node": ">=18.0.0",
-    "npm": ">=8.0.0"
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
   },
   "keywords": [
     "ngrok",

package/src/api.js

@@ -38,6 +38,21 @@ export class APIClient {
     if (error.response?.data?.error) {
       const errorMsg = error.response.data.error;
 
+      // Check for protected subdomain (reserved for production services)
+      if (errorMsg.includes("SUBDOMAIN_PROTECTED:")) {
+        return new Error(
+          `Subdomain "${subdomain}" is already taken or in use.\n\n` +
+            chalk.yellow(`💡 Try one of these options:\n`) +
+            chalk.gray(`   1. Choose a different subdomain: `) +
+            chalk.cyan(`nport ${state.port || CONFIG.DEFAULT_PORT} -s ${subdomain}-v2\n`) +
+            chalk.gray(`   2. Use a random subdomain:       `) +
+            chalk.cyan(`nport ${state.port || CONFIG.DEFAULT_PORT}\n`) +
+            chalk.gray(
+              `   3. Wait a few minutes and retry if you just stopped a tunnel with this name`
+            )
+        );
+      }
+
       // Check for subdomain in use (active tunnel)
       if (
         errorMsg.includes("SUBDOMAIN_IN_USE:") ||

package/src/binary.js

@@ -1,7 +1,7 @@
 import { spawn } from "child_process";
 import chalk from "chalk";
 import fs from "fs";
-import { LOG_PATTERNS } from "./config.js";
+import { LOG_PATTERNS, NETWORK_CONFIG } from "./config.js";
 import { state } from "./state.js";
 import { UI } from "./ui.js";
 import { lang } from "./lang.js";
@@ -52,11 +52,19 @@ export class BinaryManager {
       return;
     }
 
+    // Check for network warnings (QUIC/connectivity issues)
+    if (LOG_PATTERNS.NETWORK_WARNING.some((pattern) => msg.includes(pattern))) {
+      this.handleNetworkWarning(msg);
+      return; // Don't show the raw error to user
+    }
+
     // Show success messages with connection count
     if (LOG_PATTERNS.SUCCESS.some((pattern) => msg.includes(pattern))) {
       const count = state.incrementConnection();
       
+      // Reset network issue count when connection succeeds
       if (count === 1) {
+        state.resetNetworkIssues();
         console.log(chalk.green(lang.t("connection1")));
       } else if (count === 4) {
         console.log(chalk.green(lang.t("connection2")));
@@ -72,6 +80,36 @@ export class BinaryManager {
     }
   }
 
+  static handleNetworkWarning(msg) {
+    const count = state.incrementNetworkIssue();
+    
+    // Show user-friendly warning after threshold is reached
+    if (
+      state.shouldShowNetworkWarning(
+        NETWORK_CONFIG.WARNING_THRESHOLD,
+        NETWORK_CONFIG.WARNING_COOLDOWN
+      )
+    ) {
+      this.displayNetworkWarning();
+    }
+  }
+
+  static displayNetworkWarning() {
+    console.log(chalk.yellow(lang.t("networkIssueTitle")));
+    console.log(chalk.gray(lang.t("networkIssueDesc")));
+    console.log(chalk.cyan(lang.t("networkIssueTunnel")));
+    console.log(chalk.yellow(lang.t("networkIssueReasons")));
+    console.log(chalk.gray(lang.t("networkIssueReason1")));
+    console.log(chalk.gray(lang.t("networkIssueReason2")));
+    console.log(chalk.gray(lang.t("networkIssueReason3")));
+    console.log(chalk.yellow(lang.t("networkIssueFix")));
+    console.log(chalk.gray(lang.t("networkIssueFix1")));
+    console.log(chalk.gray(lang.t("networkIssueFix2")));
+    console.log(chalk.gray(lang.t("networkIssueFix3")));
+    console.log(chalk.gray(lang.t("networkIssueFix4")));
+    console.log(chalk.blue(lang.t("networkIssueIgnore")));
+  }
+
   static handleError(err, spinner) {
     if (spinner) {
       spinner.fail("Failed to spawn cloudflared process.");

package/src/config.js

@@ -46,6 +46,18 @@ export const PATHS = {
 export const LOG_PATTERNS = {
   SUCCESS: ["Registered tunnel connection"],
   ERROR: ["ERR", "error"],
+  
+  // Network-related warnings (not critical errors)
+  NETWORK_WARNING: [
+    "failed to accept QUIC stream",
+    "failed to dial to edge with quic",
+    "failed to accept incoming stream requests",
+    "Failed to dial a quic connection",
+    "timeout: no recent network activity",
+    "failed to dial to edge",
+    "quic:",
+  ],
+  
   IGNORE: [
     "Cannot determine default origin certificate path",
     "No file cert.pem",
@@ -65,6 +77,12 @@ export const LOG_PATTERNS = {
   ],
 };
 
+// Network warning configuration
+export const NETWORK_CONFIG = {
+  WARNING_THRESHOLD: 5,  // Show warning after 5 network errors
+  WARNING_COOLDOWN: 30000,  // Only show warning every 30 seconds
+};
+
 // Computed constants
 export const TUNNEL_TIMEOUT_MS = CONFIG.TUNNEL_TIMEOUT_HOURS * 60 * 60 * 1000;
 

package/src/lang.js

@@ -62,6 +62,21 @@ const TRANSLATIONS = {
     languageVietnamese: "2. Tiếng Việt (Vietnamese)",
     languageInvalid: "Invalid choice. Using English by default.",
     languageSaved: "✔ Language preference saved!",
+    
+    // Network warnings
+    networkIssueTitle: "\n⚠️  NETWORK CONNECTIVITY ISSUE DETECTED",
+    networkIssueDesc: "   Cloudflared is having trouble maintaining a stable connection to Cloudflare's edge servers.",
+    networkIssueTunnel: "   📡 Your tunnel is still working, but connection quality may be affected.",
+    networkIssueReasons: "\n   💡 Possible reasons:",
+    networkIssueReason1: "      • Unstable internet connection or high packet loss",
+    networkIssueReason2: "      • Firewall/Router blocking UDP traffic (QUIC protocol)",
+    networkIssueReason3: "      • ISP throttling or network congestion",
+    networkIssueFix: "\n   🔧 What to try:",
+    networkIssueFix1: "      • Check your internet connection stability",
+    networkIssueFix2: "      • Try connecting from a different network",
+    networkIssueFix3: "      • Disable VPN/Proxy if you're using one",
+    networkIssueFix4: "      • The tunnel will automatically fallback to HTTP/2 if QUIC fails",
+    networkIssueIgnore: "\n   ℹ️  This is usually not critical - your tunnel should continue working normally.\n",
   },
   
   vi: {
@@ -104,7 +119,7 @@ const TRANSLATIONS = {
     
     // Version
     versionTitle: "NPort v{version}",
-    versionSubtitle: "Hơn cả Ngrok - Ma-de in Ziệt Nam",
+    versionSubtitle: "Hơn cả Ngrok - Ma-de in Việt Nam",
     versionLatest: "🎉 Chúc mừng! Đang cùng server với bản mới nhất!",
     versionAvailable: "🌟 Vèo vèo: Có bản mới v{version} vừa cập bến!",
     versionUpdate: "Update khẩn trương lẹ làng: ",
@@ -117,6 +132,21 @@ const TRANSLATIONS = {
     languageVietnamese: "2. Tiếng Việt (Đỉnh của chóp)",
     languageInvalid: "Ơ hơ, chọn sai rồi! Mặc định Tiếng Việt luôn cho nóng.",
     languageSaved: "🎯 Xong rồi! Lưu ngôn ngữ thành công!",
+    
+    // Network warnings
+    networkIssueTitle: "\n⚠️  PHÁT HIỆN VẤN ĐỀ MẠNG",
+    networkIssueDesc: "   Cloudflared đang gặp khó khăn khi giữ kết nối ổn định tới Cloudflare edge servers.",
+    networkIssueTunnel: "   📡 Tunnel của bạn vẫn hoạt động, nhưng chất lượng kết nối có thể bị ảnh hưởng.",
+    networkIssueReasons: "\n   💡 Có thể do:",
+    networkIssueReason1: "      • Mạng internet không ổn định hoặc mất gói tin",
+    networkIssueReason2: "      • Firewall/Router chặn UDP traffic (giao thức QUIC)",
+    networkIssueReason3: "      • Nhà mạng throttle hoặc tắc nghẽn mạng",
+    networkIssueFix: "\n   🔧 Thử các cách sau:",
+    networkIssueFix1: "      • Kiểm tra kết nối internet của bạn",
+    networkIssueFix2: "      • Thử đổi sang mạng khác (ví dụ: 4G/5G)",
+    networkIssueFix3: "      • Tắt VPN/Proxy nếu đang bật",
+    networkIssueFix4: "      • Tunnel sẽ tự động chuyển sang HTTP/2 nếu QUIC fail",
+    networkIssueIgnore: "\n   ℹ️  Lỗi này thường không nghiêm trọng - tunnel vẫn hoạt động bình thường.\n",
   }
 };
 

package/src/state.js

@@ -13,6 +13,11 @@ class TunnelState {
     this.connectionCount = 0;
     this.startTime = null;
     this.updateInfo = null;
+    
+    // Network issue tracking
+    this.networkIssueCount = 0;
+    this.lastNetworkWarningTime = 0;
+    this.networkWarningShown = false;
   }
 
   setTunnel(tunnelId, subdomain, port, backendUrl = null) {
@@ -62,6 +67,32 @@ class TunnelState {
     return (Date.now() - this.startTime) / 1000;
   }
 
+  // Network issue tracking methods
+  incrementNetworkIssue() {
+    this.networkIssueCount++;
+    return this.networkIssueCount;
+  }
+
+  resetNetworkIssues() {
+    this.networkIssueCount = 0;
+  }
+
+  shouldShowNetworkWarning(threshold, cooldown) {
+    const now = Date.now();
+    if (
+      this.networkIssueCount >= threshold &&
+      now - this.lastNetworkWarningTime > cooldown
+    ) {
+      this.lastNetworkWarningTime = now;
+      return true;
+    }
+    return false;
+  }
+
+  setNetworkWarningShown(value) {
+    this.networkWarningShown = value;
+  }
+
   reset() {
     this.clearTimeout();
     this.tunnelId = null;
@@ -72,6 +103,11 @@ class TunnelState {
     this.connectionCount = 0;
     this.startTime = null;
     this.updateInfo = null;
+    
+    // Reset network tracking
+    this.networkIssueCount = 0;
+    this.lastNetworkWarningTime = 0;
+    this.networkWarningShown = false;
   }
 }