pipenet

Common errors

• Error: connect ECONNREFUSED ::1:3000

  cause The local server pipenet is trying to expose is not running or not listening on the specified port.
  fix Ensure your local application is actively listening on the specified port (e.g., 3000) before starting the pipenet tunnel client.

• Failed to create pipenet tunnel: Subdomain 'myapp' already taken.

  cause The requested subdomain is already in use by another client on the pipenet server.
  fix Omit the `subdomain` option to receive a randomly generated public URL, or try a different, unique subdomain name.

• Error: Your Node.js version (vX.Y.Z) is not supported. pipenet requires Node.js >=22.0.0.

  cause The installed Node.js version on your system does not meet the minimum requirement specified by pipenet.
  fix Upgrade your Node.js environment to version 22.0.0 or higher. Tools like nvm (Node Version Manager) can help manage multiple Node.js versions.

Warnings

• gotcha Subdomain requests are not guaranteed. While you can request a specific subdomain, its availability is not guaranteed, and you might receive a different public URL.
  Fix: Design your application to handle dynamically assigned URLs. Always use `tunnel.url` for the actual public address, and gracefully handle cases where your preferred subdomain is unavailable.
• breaking Requires Node.js version 22.0.0 or higher. Running pipenet on older Node.js versions will result in an error or unexpected behavior due to engine requirements.
  Fix: Ensure your Node.js environment is version 22.0.0 or higher. Use a version manager like nvm or fnm to switch or upgrade your Node.js version.
• gotcha CLI option name changed for bug fix in v1.2.1. Users upgrading from versions prior to 1.2.1 might encounter issues if they were using the previously incorrect CLI option name.
  Fix: Review CLI usage after upgrading to v1.2.1 or later, specifically checking option names for server configurations or client commands, as a bug fix in option naming was applied.
• gotcha The package is primarily designed for ES Modules (ESM) usage in modern Node.js environments (>=22.0.0).
  Fix: Adopt ES module syntax (import/export) in your Node.js projects. If you must use CommonJS (require()), ensure your project is configured correctly for interoperability, though direct `require()` might not work for all exports.

Install

• npm install pipenet npm
• yarn add pipenet yarn
• pnpm add pipenet pnpm

Imports

• pipenet
  wrong:

  const pipenet = require('pipenet');

  correct:

  import { pipenet } from 'pipenet';

  The primary client function is a named export. Node.js >=22.0.0 promotes ESM usage.
• createServer
  wrong:

  import { createServer } from 'pipenet';

  correct:

  import { createServer } from 'pipenet/server';

  The server component's factory function is exported from a dedicated subpath.
• Tunnel
  wrong:

  import { Tunnel } from 'pipenet';

  correct:

  import type { Tunnel } from 'pipenet';

  Use 'import type' for the Tunnel instance interface when working in TypeScript.

Quickstart

This example demonstrates how to programmatically create a pipenet tunnel, exposing a basic local HTTP server to the public internet. It illustrates awaiting the tunnel URL, logging incoming requests, and handling potential errors or the tunnel's closure, providing a complete, runnable setup for integrating `pipenet` into a Node.js application.

import { pipenet } from 'pipenet';
import http from 'http';
import { AddressInfo } from 'net'; // For checking server address

async function startPipenetTunnel() {
  // Create a simple local HTTP server to expose
  const server = http.createServer((req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end(`Hello from pipenet! Requested path: ${req.url}\n`);
  });

  const localPort = 3000;
  server.listen(localPort, () => {
    const address = server.address() as AddressInfo;
    console.log(`Local HTTP server listening on ${address.address}:${address.port}`);
  });

  try {
    // Create a pipenet tunnel to expose the local server
    const tunnel = await pipenet({
      port: localPort,
      // host: 'https://pipenet.dev', // Defaults to pipenet.dev if not specified
      subdomain: `my-test-app-${Math.random().toString(36).substring(2, 7)}` // Request a dynamic subdomain
    });

    console.log(`PTP Tunnel established! Public URL: ${tunnel.url}`);

    tunnel.on('request', (info) => {
      console.log(`[Tunnel Event] Request processed: ${info.method} ${info.path}`);
    });

    tunnel.on('error', (err) => {
      console.error('[Tunnel Event] An error occurred:', err.message);
    });

    tunnel.on('close', () => {
      console.log('[Tunnel Event] Tunnel has closed. Shutting down local server...');
      server.close(() => console.log('Local server closed.'));
    });

    // Automatically close the tunnel after a period (e.g., 60 seconds) for demonstration
    setTimeout(() => {
      console.log('Automatically closing tunnel after 60 seconds...');
      tunnel.close();
    }, 60000);

  } catch (error: any) {
    console.error('Failed to create pipenet tunnel:', error.message);
    server.close();
  }
}

startPipenetTunnel();