Websocket TCP Converter

Overview

This module converts websocket connections to upstream TCP connections.

This module enables browser Javascript to initiate Websocket connections to your endpoint and speak native TCP protocols like Redis, SQL database protocols, SSH, RDP and others directly to a backend service.

HTTP requests that are not websocket connections are rejected with HTTP 400 responses.

Example Usage

Agent CLI

ngrok http 5900 --websocket-tcp-converter

Agent Config

tunnels:
  example:
    proto: http
    addr: 5900
    websocket_tcp_converter: true

SSH

ssh -R 443:localhost:80 v2@connect.ngrok-agent.com http --websocket-tcp-converter

Go

import (
	"context"
	"net"

	"golang.ngrok.com/ngrok"
	"golang.ngrok.com/ngrok/config"
)

func ngrokListener(ctx context.Context) (net.Listener, error) {
	return ngrok.Listen(ctx,
		config.HTTPEndpoint(
			config.WithWebsocketTCPConversion(),
		),
		ngrok.WithAuthtokenFromEnv(),
	)
}

Go Package Docs:

• https://pkg.go.dev/golang.ngrok.com/ngrok/config#WithWebsocketTCPConversion

Javascript

const ngrok = require("@ngrok/ngrok");

(async function () {
	const listener = await ngrok.forward({
		addr: 8080,
		authtoken_from_env: true,
		websocket_tcp_converter: true,
	});

	console.log(`Ingress established at: ${listener.url()}`);
})();

Javascript SDK Docs:

• https://ngrok.github.io/ngrok-javascript/interfaces/Config.html#websocket_tcp_converter
• https://ngrok.github.io/ngrok-javascript/classes/HttpListenerBuilder.html#websocketTcpConversion

Python

import ngrok

listener = ngrok.forward("localhost:8080", authtoken_from_env=True,
    websocket_tcp_converter=True)

print(f"Ingress established at: {listener.url()}");

Python SDK Docs:

• https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.websocket_tcp_conversion
• https://ngrok.github.io/ngrok-python/index.html#full-configuration

Rust

use ngrok::prelude::*;

async fn listen_ngrok() -> anyhow::Result<impl Tunnel> {
    let sess = ngrok::Session::builder()
        .authtoken_from_env()
        .connect()
        .await?;

    let tun = sess
        .http_endpoint()
        .websocket_tcp_conversion()
        .listen()
        .await?;

    println!("Listening on URL: {:?}", tun.url());

    Ok(tun)
}

Rust Crate Docs:

• https://docs.rs/ngrok/latest/ngrok/config/struct.HttpTunnelBuilder.html#method.websocket_tcp_conversion

Kubernetes Controller

info

The Websocket TCP Converter module is not yet supported in the Kubernetes Ingress Controller.

Behavior

This module reads and writes binary websocket messages because many of the protocols you'd like to speak across use binary encodings.

Reference

Configuration

This module does not support any configuration. It is either enabled or disabled.

Upstream Headers

This module does not add any upstream headers.

Errors

Code	HTTP Status	Error
ERR_NGROK_3206	400	This error is returned if the HTTP request is not a Websocket Upgrade request.

Events

This module does not populate any fields in events.

Edges

Websocket TCP Converter is an HTTPS Edge module which can be applied to Routes.

• Websocket TCP Converter Edge Module API Resource

Pricing

This module is available on all plans.

Try it out

Coming Soon

This documentation is incomplete. Please check back later, we appreciate your patience.