Awesome
Punchmole
Punchmole is a simple tool to give your locally running HTTP(s) servers a public URL
and is an easy to self-host alternative to ngrok
and/or tunnelmole
.
Implemented in Node with the goal to have as much flexibility and as little dependencies and code as possible.
The project has 2 components:
- Client: runs locally to connect a given HTTP endpoint running locally (or in a non-public network).
- Server: deployable on a server, behind a reverse proxy connects to the outside world and any domain it is accessible from
This service allows streaming of origin request (e.g. file-uploads, other than Tunnelmole which buffers request data completely in memory). The service also supports Websocket proxying depending on websocket endpoint url path
Client & Server are both solely configurable via ENV-variables.
Status
This project is experimental and currently used for some pet-projects, quickly hacked together in a few hours.
Well-known issues:
- almost no error handling
- no tests
Server
The server opens a single HTTP port to which the Punchmole client connects and upgrades to a websocket connection.
Each request to this HTTP port is forwarded (based on clients HOST header) to a corresponding connected Punchmole client connection which can ultimately serve the request.
Environment variables
Variable | Default Value | Description |
---|---|---|
PORT | 10000 | HTTP port on which the server listens |
API_KEYS | n/a | A comma-separated list of API keys the server accepts connections for |
PUNCHMOLE_ENDPOINT_URL_PATH | /_punchmole | A WebSocket URL path which is used to determine if the incoming connection is for punchmole to register and connect a punchmole client or a user request which needs to be forwarded |
Installation
npm install -g punchmole
Run
PORT=10000 \
API_KEYS=api-key1,api-key2,random-string-nobody-can-guess \
PUNCHMOLE_ENDPOINT_URL_PATH=/_punchmole \
punchmole-server
Run on docker
docker build -t punchmole .
docker run -e API_KEYS=api-key1,api-key2,random-string-nobody-can-guess punchmole
Usage in own Node code
The server can also easily get used in your own project:
import { PunchmoleServer } from "punchmole";
PunchmoleServer(
PORT, // port number to listen on
API_KEYS, // array of api keys (random strings)
PUNCHMOLE_ENDPOINT_URL_PATH, // /_punchmole is the default path
console // console, {info: {}, debug: {}, error: {}} for no logs or e.g. an instance of log4js
)
Client
The client connects to the Punchmole server, with first connection the client shares the given API key and a domain it wants to receive requests for.
Environment variables
Variable | Default Value | Description |
---|---|---|
PUNCHMOLE_API_KEY | n/a | An API-key the server accepts |
DOMAIN | n/a | The domain the client wants to receive requests for |
TARGET_URL | http://localhost:3000 | URL to which the incoming requests are forwarded to, either local or within the private network |
PUNCHMOLE_ENDPOINT_URL | ws://localhost:10000/_punchmole | Websocket URL of the Punchmole server, make sure if you want to change /_punchmole to adjust PUNCHMOLE_ENDPOINT_URL_PATH in punchmole server |
Installation
npm install -g punchmole
Run
PUNCHMOLE_ENDPOINT_URL=ws://localhost:10000/_punchmole \
TARGET_URL=http://localhost:3000 \
API_KEY=api-key1 \
DOMAIN=testdomain.com \
punchmole
Usage in own Node code
The client can also easily get used in your own project:
import { PunchmoleClient } from "punchmole";
const punchmoleEvents = PunchmoleClient(
"API KEY",
"DOMAIN",
"TARGET URL",
"PUNCHMOLE ENDPOINT URL"
)
punchmoleEvents.addListener("registered", (result) => console.log(result))
punchmoleEvents.addListener("request", (result) => console.log(result))
punchmoleEvents.addListener("request-end", (result) => console.log(result))