signageOS forward-server-bridge

The service allows forward HTTP requests into local machine port initiated by client and send responses back.

Server

Development

npm install
npm start

Configuration

| Environment Variable | Description | Default | |---|---|---| | FORWARDING_GRACE_PERIOD_MS | Grace period in milliseconds before cleaning up a disconnected forwarding session. During this period, the session can be resumed by reconnecting with the same forwardingUid. | 30000 (30s) |

CLI

The CLI binary allows you to forward HTTP requests from a public server to a local port with automatic reconnection.

Usage

npx @signageos/forward-server-bridge --local-port 3000 --server-url https://forward.example.com

Options

| Option | Required | Description | Default | |---|---|---|---| | --local-port <port> | Yes | Local port to forward traffic to | — | | --server-url <url> | Yes | Public URL of the forward server | — | | --local-hostname <hostname> | No | Local hostname to forward traffic to | localhost | | --forwarding-uid <uid> | No | Forwarding UID for session recovery (reuse a previous session) | — | | --max-retries <count> | No | Maximum number of reconnection retries | Infinity | | --retry-delay <ms> | No | Initial retry delay in milliseconds (exponential backoff: 2x multiplier, 30s cap) | 1000 |

The CLI outputs only the public URL to stdout (machine-readable). Reconnection logs are written to stderr.

Connection Recovery

If the WebSocket connection drops, the CLI automatically reconnects with exponential backoff and preserves the same public URL. The server keeps the forwarding session alive during the grace period (FORWARDING_GRACE_PERIOD_MS), so incoming requests during a brief disconnect receive a 503 Service Unavailable response instead of 404 Not Found.

Client SDK

Usage

import { forward } from '@signageos/forward-server-bridge/dist/client';
const { publicUrl, forwardingUid, disconnected, isConnected, onConnectionStateChange, stop } = await forward({
	localPort: 9080, // Required. Port where the public traffic will be forwarded to.
	serverUrl: 'https://localhost:8080', // Required. Public URL (including scheme & port) of the forward server.
	localHostname: 'localhost', // Optional. Hostname where the public traffic will be forwarded to. Default: 'localhost'.
	forwardingUid: 'abc1234', // Optional. Forwarding UID to resume a previous session.
});
console.log(`You can access the forwarded server on ${publicUrl}`);
console.log(`Session ID: ${forwardingUid}`); // Save this to reconnect later.
await disconnected; // Resolves when the socket disconnects (for any reason).
await stop(); // Stop forwarding.

Auto-Reconnecting Mode

For automatic reconnection with exponential backoff, pass maxRetries to forward():

import { forward } from '@signageos/forward-server-bridge/dist/client';

const forwarding = await forward({
	localPort: 9080,
	serverUrl: 'https://localhost:8080',
	localHostname: 'localhost', // Optional. Default: 'localhost'.
	forwardingUid: 'abc1234', // Optional. Resume a previous session.
	maxRetries: Infinity, // Optional. 0 (default) disables auto-reconnect.
	retryDelay: 1000, // Optional. Initial retry delay in ms. Default: 1000.
});

console.log(`Public URL: ${forwarding.publicUrl}`);
console.log(`Session ID: ${forwarding.forwardingUid}`);

forwarding.onConnectionStateChange((connected) => {
	console.log(`Connection state: ${connected ? 'connected' : 'disconnected'}`);
});

await forwarding.disconnected; // Resolves when retries are exhausted or stop() is called.
await forwarding.stop();

Process

Once the client forward is established, the server accepts HTTP requests on returned publicUrl and forwards them to the localPort on the localHostname.

The logic creates the WebSocket tunnel under the hood initiated from client side to the serverUrl. So it can be called even from a computer that has firewall on incoming connections.

sequenceDiagram
	participant PublicUser
	participant ForwardingServer
	participant LocalClient
	Note right of LocalClient: Local machine initiates the forwarding
	LocalClient->>ForwardingServer: Establish WebSocket tunnel
	Note left of ForwardingServer: Publicly accessible "publicUrl" endpoint.<br> E.g.: `http://forward.example.com/43fea3c24/`
	PublicUser->>ForwardingServer: Forward request
	Note right of ForwardingServer: "serverPort" is listening
	ForwardingServer->>LocalClient: Forward request
	Note right of LocalClient: "localPort" is listening
	Note right of LocalClient: Optionally "localHostname" is listening
	LocalClient->>ForwardingServer: Forward response
	ForwardingServer->>PublicUser: Forward response

Motivation

This feature can be used to allow some local service to be accessible from the internet. Even if the local machine doesn't have public interface (hidden in private network behind the router). Only the forward server needs to be accessible publicly from the internet.