|
| 1 | +# pipenet |
| 2 | + |
| 3 | +pipenet exposes your localhost to the world for easy testing and sharing! No need to mess with DNS or deploy just to have others test out your changes. |
| 4 | + |
| 5 | +## Installation |
| 6 | + |
| 7 | +```bash |
| 8 | +npm install pipenet |
| 9 | +# or |
| 10 | +pnpm add pipenet |
| 11 | +``` |
| 12 | + |
| 13 | +## API |
| 14 | + |
| 15 | +The pipenet client is also usable through an API (for test integration, automation, etc) |
| 16 | + |
| 17 | +### pipenet(port [,options][,callback]) |
| 18 | + |
| 19 | +Creates a new pipenet tunnel to the specified local `port`. Will return a Promise that resolves once you have been assigned a public tunnel url. `options` can be used to request a specific `subdomain`. A `callback` function can be passed, in which case it won't return a Promise. This exists for backwards compatibility with the old Node-style callback API. You may also pass a single options object with `port` as a property. |
| 20 | + |
| 21 | +```js |
| 22 | +import pipenet from 'pipenet'; |
| 23 | + |
| 24 | +const tunnel = await pipenet({ port: 3000 }); |
| 25 | + |
| 26 | +// the assigned public url for your tunnel |
| 27 | +// i.e. https://abcdefgjhij.pipenet.me |
| 28 | +tunnel.url; |
| 29 | + |
| 30 | +tunnel.on('close', () => { |
| 31 | + // tunnels are closed |
| 32 | +}); |
| 33 | +``` |
| 34 | + |
| 35 | +#### options |
| 36 | + |
| 37 | +- `port` (number) [required] The local port number to expose through pipenet. |
| 38 | +- `subdomain` (string) Request a specific subdomain on the proxy server. **Note** You may not actually receive this name depending on availability. |
| 39 | +- `host` (string) URL for the upstream proxy server. Defaults to `https://pipenet.me`. |
| 40 | +- `local_host` (string) Proxy to this hostname instead of `localhost`. This will also cause the `Host` header to be re-written to this value in proxied requests. |
| 41 | +- `local_https` (boolean) Enable tunneling to local HTTPS server. |
| 42 | +- `local_cert` (string) Path to certificate PEM file for local HTTPS server. |
| 43 | +- `local_key` (string) Path to certificate key file for local HTTPS server. |
| 44 | +- `local_ca` (string) Path to certificate authority file for self-signed certificates. |
| 45 | +- `allow_invalid_cert` (boolean) Disable certificate checks for your local HTTPS server (ignore cert/key/ca options). |
| 46 | + |
| 47 | +Refer to [tls.createSecureContext](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) for details on the certificate options. |
| 48 | + |
| 49 | +### Tunnel |
| 50 | + |
| 51 | +The `tunnel` instance returned to your callback emits the following events |
| 52 | + |
| 53 | +| event | args | description | |
| 54 | +| ------- | ---- | ------------------------------------------------------------------------------------ | |
| 55 | +| request | info | fires when a request is processed by the tunnel, contains _method_ and _path_ fields | |
| 56 | +| error | err | fires when an error happens on the tunnel | |
| 57 | +| close | | fires when the tunnel has closed | |
| 58 | + |
| 59 | +The `tunnel` instance has the following methods |
| 60 | + |
| 61 | +| method | args | description | |
| 62 | +| ------ | ---- | ---------------- | |
| 63 | +| close | | close the tunnel | |
| 64 | + |
| 65 | +## Server |
| 66 | + |
| 67 | +This package includes both the client and server components. You can run your own pipenet server. |
| 68 | + |
| 69 | +### Running the Server |
| 70 | + |
| 71 | +```bash |
| 72 | +# Using the CLI |
| 73 | +npx pipenet-server --port 3000 |
| 74 | + |
| 75 | +# Or programmatically |
| 76 | +``` |
| 77 | + |
| 78 | +```js |
| 79 | +import { createServer } from 'pipenet/server'; |
| 80 | + |
| 81 | +const server = createServer({ |
| 82 | + domain: 'tunnel.example.com', // Optional: custom domain |
| 83 | + secure: false, // Optional: require HTTPS |
| 84 | + landing: 'https://example.com', // Optional: landing page URL |
| 85 | + max_tcp_sockets: 10, // Optional: max sockets per client |
| 86 | +}); |
| 87 | + |
| 88 | +server.listen(3000, () => { |
| 89 | + console.log('pipenet server listening on port 3000'); |
| 90 | +}); |
| 91 | +``` |
| 92 | + |
| 93 | +### Server Options |
| 94 | + |
| 95 | +- `domain` (string) Custom domain for the tunnel server |
| 96 | +- `secure` (boolean) Require HTTPS connections |
| 97 | +- `landing` (string) URL to redirect root requests to |
| 98 | +- `max_tcp_sockets` (number) Maximum number of TCP sockets per client (default: 10) |
| 99 | + |
| 100 | +### Server API Endpoints |
| 101 | + |
| 102 | +- `GET /api/status` - Server status and tunnel count |
| 103 | +- `GET /api/tunnels/:id/status` - Status of a specific tunnel |
| 104 | +- `GET /:id` - Request a new tunnel with the specified ID |
| 105 | + |
| 106 | +## Acknowledgments |
| 107 | + |
| 108 | +pipenet is based on [localtunnel](https://github.com/localtunnel/localtunnel), an open-source project by [@defunctzombie](https://github.com/defunctzombie). We are grateful for the foundation it provided. |
| 109 | + |
| 110 | +Development of pipenet is sponsored by [glama.ai](https://glama.ai). |
| 111 | + |
| 112 | +## License |
| 113 | + |
| 114 | +MIT |
0 commit comments