nport 1.0.5 → 2.0.1

package/README.md

@@ -1,68 +1,263 @@
 # <img src="https://nport.link/assets/imgs/nport-logo.png" height="30" style="vertical-align: middle;"> NPort
 
-> A Node.js tool for exposing local servers through Socket.IO tunnels
+> 🚀 Free & open source ngrok alternative - Tunnel localhost to the internet via Cloudflare Edge
 
 [![GitHub](https://img.shields.io/github/stars/tuanngocptn/nport?style=social)](https://github.com/tuanngocptn/nport)
 [![NPM](https://img.shields.io/npm/v/nport?color=red&logo=npm)](https://www.npmjs.com/package/nport)
 [![Website](https://img.shields.io/website?url=https%3A%2F%2Fnport.link&up_message=nport.link&up_color=blue&down_color=lightgrey&down_message=offline)](https://nport.link)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 ## What is NPort?
 
-![nport](https://github.com/user-attachments/assets/3f61ae7a-bff7-45d8-8f40-8e04b301a63a)
+[![nport](https://github.com/user-attachments/assets/6e188d75-4633-4efa-a7f4-63df6a4a7ac8)](https://nport.link)
 
-NPort allows you to expose your local HTTP servers to the internet using Socket.IO streams. Perfect for:
-- Development environments
-- Testing webhooks
-- Sharing local projects
+NPort is a powerful, lightweight **ngrok alternative** that creates secure HTTP/HTTPS tunnels from your localhost to public URLs using **Cloudflare's global edge network**. No configuration, no accounts, just instant tunnels with custom subdomains!
+
+Perfect for:
+- 🚀 **Development environments** - Share your local work instantly
+- 🔒 **Testing webhooks** - Receive webhooks from GitHub, Stripe, PayPal, etc.
+- 📱 **Mobile testing** - Test your web app on real devices
+- 🛠️ **API development** - Debug integrations with external services
+- 👥 **Demo to clients** - Show your progress without deployment
 
 ## ✨ Features
 
-- 🔒 **Secure Tunneling**: Share your local server safely using Socket.IO
-- 🚀 **Easy Setup**: Minimal configuration required
-- 🌐 **Custom Domains**: Get readable URLs like `https://yourname.nport.link`
-- 📡 **WebSocket Ready**: Full WebSocket connection support
-- 💻 **Cross-Platform**: Runs on Windows, macOS, and Linux
+- ⚡ **Instant Setup**: One command to expose your localhost
+- 🌐 **Custom Subdomains**: Choose your own URL (e.g., `myapp.nport.link`)
+- 🔒 **Automatic HTTPS**: SSL/TLS encryption via Cloudflare
+- 🌍 **Global Edge Network**: Fast connections worldwide via Cloudflare
+- 📡 **WebSocket Support**: Full WebSocket and Server-Sent Events support
+- 🎯 **No Configuration**: Works out of the box
+- 💻 **Cross-Platform**: Windows, macOS, and Linux support
+- 🆓 **100% Free**: No accounts, no limits, no paywalls
+- 🔓 **Open Source**: MIT licensed
 
 ## 📦 Installation
 
-**NPM Package**
-```bash
-# Local installation
-npm install nport
+### NPM (Recommended)
 
+```bash
 # Global installation
 npm install -g nport
+
+# Or use npx without installation
+npx nport 3000 -s myapp
 ```
 
-**From GitHub**
-```bash
-# Local installation
-npm install git+https://github.com/tuanngocptn/nport.git
+### From GitHub
 
-# Global installation
+```bash
 npm install -g git+https://github.com/tuanngocptn/nport.git
 ```
 
 ## 🚀 Quick Start
 
 ### Basic Usage
+
+Expose port 3000 with a random subdomain:
 ```bash
-# Local installation
-npx nport -s myapp -p 3000
+nport 3000
+```
 
-# Global installation
-nport -s myapp -p 3000
+Output:
 ```
-This will create a tunnel at `https://myapp.nport.link`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  NPort - Free & Open Source ngrok Alternative
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  🌐 Website: https://nport.link
+  📦 NPM:     https://www.npmjs.com/package/nport
+  💻 GitHub:  https://github.com/tuanngocptn/nport
+  ☕ Support: https://buymeacoffee.com/tuanngocptn
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-### Advanced Options
+🚀 Starting Tunnel for port 3000...
+✔ Tunnel created!
+🌍 Public URL: https://user-1234.nport.link
+```
+
+### Custom Subdomain
+
+Choose your own subdomain:
+```bash
+nport 3000 -s myapp
+# Creates: https://myapp.nport.link
+```
+
+Or using long form:
 ```bash
-# Full configuration
-npx nport --server https://server.nport.link \
-         --subdomain myapp \
-         --hostname 127.0.0.1 \
-         --port 3000
+nport 3000 --subdomain myapp
 ```
 
-## 📝 Credits
-Inspired by [Socket Tunnel](https://github.com/ericbarch/socket-tunnel). Read more about the concept in this [blog post](https://ericbarch.com/post/sockettunnel/).
+## 📖 Usage Examples
+
+### Web Development
+
+```bash
+# Next.js
+npm run dev
+nport 3000 -s my-nextjs-app
+
+# React (Create React App)
+npm start
+nport 3000 -s my-react-app
+
+# Vue.js
+npm run dev
+nport 8080 -s my-vue-app
+
+# Express.js
+node server.js
+nport 3000 -s my-api
+```
+
+### Webhook Testing
+
+```bash
+# Start your local webhook receiver
+node webhook-receiver.js
+
+# Expose it to the internet
+nport 4000 -s my-webhooks
+
+# Use in GitHub webhook settings:
+# https://my-webhooks.nport.link/webhook
+```
+
+### Mobile Device Testing
+
+```bash
+# Start your local dev server
+npm run dev
+
+# Create tunnel
+nport 3000 -s mobile-test
+
+# Open on your phone:
+# https://mobile-test.nport.link
+```
+
+## 🎯 CLI Options
+
+```bash
+nport <port> [options]
+```
+
+| Option | Short | Description | Example |
+|--------|-------|-------------|---------|
+| `<port>` | - | Local port to tunnel (default: 8080) | `nport 3000` |
+| `--subdomain` | `-s` | Custom subdomain | `nport 3000 -s myapp` |
+| `-s=value` | - | Alternative format | `nport 3000 -s=myapp` |
+
+## 🔧 How It Works
+
+1. **You run** `nport 3000 -s myapp`
+2. **NPort creates** a Cloudflare Tunnel
+3. **DNS record** is created: `myapp.nport.link` → Cloudflare Edge
+4. **Cloudflared binary** connects your localhost:3000 to Cloudflare
+5. **Traffic flows** through Cloudflare's global network to your machine
+6. **On exit** (Ctrl+C), tunnel and DNS are automatically cleaned up
+
+```
+Internet → Cloudflare Edge → Cloudflare Tunnel → Your localhost:3000
+         (https://myapp.nport.link)
+```
+
+## 🛡️ Security
+
+- **HTTPS by default**: All tunnels use SSL/TLS encryption
+- **Cloudflare protection**: DDoS protection and security features
+- **Automatic cleanup**: Tunnels are removed when you stop the process
+- **No data logging**: We don't store or log your traffic
+
+## 🆚 Comparison with ngrok
+
+| Feature | NPort | ngrok |
+|---------|-------|-------|
+| Price | 100% Free | Free tier limited |
+| Custom subdomains | ✅ Always | ❌ Paid only |
+| HTTPS | ✅ Always | ✅ |
+| Account required | ❌ No | ✅ Yes |
+| Time limits | ❌ None | ⚠️ Free tier limited |
+| Open source | ✅ MIT | ❌ Proprietary |
+| Global network | ✅ Cloudflare | ✅ ngrok Edge |
+
+## 🧹 Cleanup
+
+NPort automatically cleans up resources when you:
+- Press **Ctrl+C** to exit
+- Kill the process
+- Terminal closes
+
+The cleanup process:
+1. ✅ Deletes DNS record (`myapp.nport.link`)
+2. ✅ Removes Cloudflare Tunnel
+3. ✅ Stops cloudflared process
+
+## 🐛 Troubleshooting
+
+### Binary not found
+
+If you see "Cloudflared binary not found":
+```bash
+npm install -g nport --force
+```
+
+### Port already in use
+
+Make sure your local server is running on the specified port:
+```bash
+# Check if something is listening on port 3000
+lsof -i :3000  # macOS/Linux
+netstat -ano | findstr :3000  # Windows
+```
+
+### Subdomain already taken
+
+Choose a different subdomain name:
+```bash
+nport 3000 -s myapp-v2
+```
+
+### Connection issues
+
+The `ERR Cannot determine default origin certificate path` warning is harmless and can be ignored. It appears because cloudflared checks for certificate-based authentication (we use token-based instead).
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 💖 Support
+
+If you find NPort useful, please consider supporting the project:
+
+- ⭐ [Star on GitHub](https://github.com/tuanngocptn/nport)
+- ☕ [Buy me a coffee](https://buymeacoffee.com/tuanngocptn)
+- 💬 Share with your friends and colleagues
+- 🐛 [Report bugs](https://github.com/tuanngocptn/nport/issues)
+
+## 📄 License
+
+[MIT License](LICENSE) - Feel free to use NPort in your projects!
+
+## 🙏 Credits
+
+- Created by [Nick Pham](https://github.com/tuanngocptn) 🇻🇳
+- 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)
+
+## 🔗 Links
+
+- 🌐 Website: [https://nport.link](https://nport.link)
+- 📦 NPM: [https://www.npmjs.com/package/nport](https://www.npmjs.com/package/nport)
+- 💻 GitHub: [https://github.com/tuanngocptn/nport](https://github.com/tuanngocptn/nport)
+- 📧 Email: tuanngocptn@gmail.com
+
+---
+
+Made with ❤️ by [Nick Pham](https://github.com/tuanngocptn)

package/bin-manager.js

@@ -0,0 +1,378 @@
+import fs from "fs";
+import path from "path";
+import https from "https";
+import os from "os";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+
+// ============================================================================
+// Configuration & Constants
+// ============================================================================
+
+// Fix for __dirname in ES modules
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Binary configuration
+const BIN_DIR = path.join(__dirname, "bin");
+const BINARY_NAME = "cloudflared";
+const COMPRESSED_SUFFIX = ".tgz";
+const TEMP_ARCHIVE_NAME = "cloudflared.tgz";
+
+// Platform detection
+const PLATFORM = os.platform();
+const ARCH = os.arch();
+const IS_WINDOWS = PLATFORM === "win32";
+const IS_MACOS = PLATFORM === "darwin";
+const IS_LINUX = PLATFORM === "linux";
+
+// Binary paths
+const BIN_NAME = IS_WINDOWS ? `${BINARY_NAME}.exe` : BINARY_NAME;
+const BIN_PATH = path.join(BIN_DIR, BIN_NAME);
+
+// Download configuration
+const GITHUB_BASE_URL = "https://github.com/cloudflare/cloudflared/releases/latest/download";
+const REDIRECT_CODES = [301, 302];
+const SUCCESS_CODE = 200;
+const UNIX_EXECUTABLE_MODE = "755";
+
+// ============================================================================
+// Platform Detection
+// ============================================================================
+
+/**
+ * Platform and architecture mapping for cloudflared releases
+ */
+const PLATFORM_MAPPINGS = {
+  darwin: {
+    amd64: "cloudflared-darwin-amd64.tgz",
+    arm64: "cloudflared-darwin-amd64.tgz", // macOS uses universal binary
+  },
+  win32: {
+    x64: "cloudflared-windows-amd64.exe",
+    ia32: "cloudflared-windows-386.exe",
+  },
+  linux: {
+    x64: "cloudflared-linux-amd64",
+    arm64: "cloudflared-linux-arm64",
+    arm: "cloudflared-linux-arm",
+  },
+};
+
+/**
+ * Normalizes architecture name for mapping lookup
+ * @param {string} arch - Raw architecture from os.arch()
+ * @returns {string} Normalized architecture name
+ */
+function normalizeArch(arch) {
+  const archMap = {
+    x64: "x64",
+    amd64: "amd64",
+    arm64: "arm64",
+    ia32: "ia32",
+    arm: "arm",
+  };
+  return archMap[arch] || arch;
+}
+
+/**
+ * Determines the download URL based on current platform and architecture
+ * @returns {string} Download URL for cloudflared binary
+ * @throws {Error} If platform/architecture combination is not supported
+ */
+function getDownloadUrl() {
+  const normalizedArch = normalizeArch(ARCH);
+  const platformMapping = PLATFORM_MAPPINGS[PLATFORM];
+
+  if (!platformMapping) {
+    throw new Error(
+      `Unsupported platform: ${PLATFORM}. Supported platforms: darwin, win32, linux`
+    );
+  }
+
+  const binaryName = platformMapping[normalizedArch];
+
+  if (!binaryName) {
+    throw new Error(
+      `Unsupported architecture: ${ARCH} for platform ${PLATFORM}. ` +
+        `Supported architectures: ${Object.keys(platformMapping).join(", ")}`
+    );
+  }
+
+  return `${GITHUB_BASE_URL}/${binaryName}`;
+}
+
+/**
+ * Checks if the download URL points to a compressed archive
+ * @param {string} url - Download URL
+ * @returns {boolean} True if URL is for a compressed file
+ */
+function isCompressedArchive(url) {
+  return url.endsWith(COMPRESSED_SUFFIX);
+}
+
+// ============================================================================
+// File System Utilities
+// ============================================================================
+
+/**
+ * Ensures directory exists, creates it if it doesn't
+ * @param {string} dirPath - Directory path to ensure
+ */
+function ensureDirectory(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Safely removes a file if it exists
+ * @param {string} filePath - Path to file to remove
+ */
+function safeUnlink(filePath) {
+  try {
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+    }
+  } catch (err) {
+    // Ignore errors during cleanup
+    console.warn(`Warning: Could not remove ${filePath}:`, err.message);
+  }
+}
+
+/**
+ * Sets executable permissions on Unix-like systems
+ * @param {string} filePath - Path to file
+ * @param {string} mode - Permission mode (e.g., "755")
+ */
+function setExecutablePermissions(filePath, mode = UNIX_EXECUTABLE_MODE) {
+  if (!IS_WINDOWS) {
+    fs.chmodSync(filePath, mode);
+  }
+}
+
+/**
+ * Validates that a file exists at the given path
+ * @param {string} filePath - Path to validate
+ * @param {string} errorMessage - Error message if file doesn't exist
+ * @throws {Error} If file doesn't exist
+ */
+function validateFileExists(filePath, errorMessage) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(errorMessage || `File not found: ${filePath}`);
+  }
+}
+
+// ============================================================================
+// Download Utilities
+// ============================================================================
+
+/**
+ * Downloads a file from a URL with automatic redirect handling
+ * @param {string} url - URL to download from
+ * @param {string} dest - Destination file path
+ * @returns {Promise<string>} Resolves with destination path on success
+ */
+async function downloadFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(dest);
+
+    https
+      .get(url, (response) => {
+        // Handle redirects
+        if (REDIRECT_CODES.includes(response.statusCode)) {
+          file.close();
+          safeUnlink(dest);
+          downloadFile(response.headers.location, dest)
+            .then(resolve)
+            .catch(reject);
+          return;
+        }
+
+        // Handle non-success status codes
+        if (response.statusCode !== SUCCESS_CODE) {
+          file.close();
+          safeUnlink(dest);
+          reject(
+            new Error(
+              `Download failed with status code ${response.statusCode} from ${url}`
+            )
+          );
+          return;
+        }
+
+        // Stream response to file
+        response.pipe(file);
+
+        file.on("finish", () => {
+          file.close(() => resolve(dest));
+        });
+
+        file.on("error", (err) => {
+          file.close();
+          safeUnlink(dest);
+          reject(err);
+        });
+      })
+      .on("error", (err) => {
+        file.close();
+        safeUnlink(dest);
+        reject(new Error(`Network error: ${err.message}`));
+      });
+  });
+}
+
+// ============================================================================
+// Archive Extraction
+// ============================================================================
+
+/**
+ * Extracts a .tgz archive to a directory
+ * @param {string} archivePath - Path to .tgz file
+ * @param {string} targetDir - Directory to extract to
+ * @throws {Error} If extraction fails
+ */
+function extractTarGz(archivePath, targetDir) {
+  try {
+    execSync(`tar -xzf "${archivePath}" -C "${targetDir}"`, {
+      stdio: "pipe", // Suppress output
+    });
+  } catch (err) {
+    throw new Error(`Extraction failed: ${err.message}`);
+  }
+}
+
+// ============================================================================
+// Logging Utilities
+// ============================================================================
+
+/**
+ * Console logging with consistent formatting
+ */
+const logger = {
+  info: (msg) => console.log(`ℹ️  ${msg}`),
+  success: (msg) => console.log(`✅ ${msg}`),
+  warn: (msg) => console.warn(`⚠️  ${msg}`),
+  error: (msg) => console.error(`❌ ${msg}`),
+  progress: (msg) => console.log(`🚧 ${msg}`),
+  extract: (msg) => console.log(`📦 ${msg}`),
+};
+
+// ============================================================================
+// Core Binary Management
+// ============================================================================
+
+/**
+ * Downloads and installs the cloudflared binary
+ * @returns {Promise<string>} Path to installed binary
+ */
+async function installBinary() {
+  logger.progress(
+    "Cloudflared binary not found. Downloading... (This happens only once)"
+  );
+
+  const url = getDownloadUrl();
+  const isArchive = isCompressedArchive(url);
+  const downloadDest = isArchive
+    ? path.join(BIN_DIR, TEMP_ARCHIVE_NAME)
+    : BIN_PATH;
+
+  try {
+    // Download binary or archive
+    await downloadFile(url, downloadDest);
+
+    // Extract if it's an archive (macOS)
+    if (isArchive) {
+      logger.extract("Extracting binary...");
+      extractTarGz(downloadDest, BIN_DIR);
+
+      // Clean up archive
+      safeUnlink(downloadDest);
+
+      // Validate extraction succeeded
+      validateFileExists(
+        BIN_PATH,
+        "Extraction failed: Binary not found after extraction"
+      );
+    }
+
+    // Set executable permissions (Unix-like systems)
+    setExecutablePermissions(BIN_PATH);
+
+    logger.success("Download complete.");
+    return BIN_PATH;
+  } catch (error) {
+    // Clean up any partial downloads
+    safeUnlink(downloadDest);
+    safeUnlink(BIN_PATH);
+    throw error;
+  }
+}
+
+/**
+ * Ensures cloudflared binary is available, downloading if necessary
+ * @returns {Promise<string>} Path to cloudflared binary
+ */
+export async function ensureCloudflared() {
+  // Ensure bin directory exists
+  ensureDirectory(BIN_DIR);
+
+  // Check if binary already exists
+  if (fs.existsSync(BIN_PATH)) {
+    // Always ensure permissions are set correctly (in case they were lost)
+    setExecutablePermissions(BIN_PATH);
+    return BIN_PATH;
+  }
+
+  // Download and install
+  try {
+    return await installBinary();
+  } catch (error) {
+    logger.error(`Installation failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// ============================================================================
+// CLI Entry Point
+// ============================================================================
+
+/**
+ * Checks if we're running in a CI environment
+ * @returns {boolean} True if in CI environment
+ */
+function isCI() {
+  return !!(
+    process.env.CI || // Generic CI flag
+    process.env.GITHUB_ACTIONS || // GitHub Actions
+    process.env.GITLAB_CI || // GitLab CI
+    process.env.CIRCLECI || // CircleCI
+    process.env.TRAVIS || // Travis CI
+    process.env.JENKINS_URL || // Jenkins
+    process.env.BUILDKITE // Buildkite
+  );
+}
+
+/**
+ * Main function when run directly from command line
+ */
+async function main() {
+  // Skip binary download in CI environments to keep package lightweight
+  if (isCI()) {
+    logger.info("Running in CI environment - skipping binary download");
+    return;
+  }
+
+  try {
+    const binaryPath = await ensureCloudflared();
+    logger.success(`Cloudflared binary is ready at: ${binaryPath}`);
+  } catch (error) {
+    logger.error(error.message);
+    process.exit(1);
+  }
+}
+
+// Run if executed directly
+if (process.argv[1] === __filename) {
+  main();
+}