Skip to content

README.md

Latest commit

 

History

History
179 lines (137 loc) · 3.42 KB

README.md

File metadata and controls

179 lines (137 loc) · 3.42 KB

ws‑tcp‑udp‑bridge

A lightweight WebSocket bridge that forwards messages to arbitrary TCP or UDP targets.
It enables browsers and WebSocket‑only environments to interact with raw network services by tunneling packets through a WebSocket server.

Ideal for:

  • Building TCP/UDP debugging tools in the browser
  • Creating packet inspectors, hex editors, or protocol testers
  • Remote device communication through firewalls
  • Lightweight network automation and diagnostics

Features

  • WebSocket server that accepts text or binary frames
  • Forwards payloads to any TCP or UDP host/port
  • Streams responses back to the WebSocket client
  • Runtime‑configurable target (host, port, protocol)
  • Supports binary payloads (ArrayBuffer / Uint8Array)
  • Multi‑arch Docker image (amd64 + arm64)
  • Built‑in Docker healthcheck
  • Minimal dependencies, fast startup

Architecture

Browser / App
     │
     │ WebSocket (text or binary)
     ▼
ws-tcp-udp-bridge
     │
     ├── TCP socket → target host:port
     └── UDP socket → target host:port

The client sends two types of messages:

1. Configuration

{
  "type": "config",
  "protocol": "tcp",
  "host": "192.168.1.50",
  "port": 9000
}

2. Payload

{
  "type": "send",
  "payload": [0x48, 0x65, 0x6c, 0x6c, 0x6f]
}

Running Locally

Install dependencies

npm install

Start the server

node server.js

The WebSocket server listens on:

ws://localhost:8080

Docker Usage

Pull the image

docker pull sharevb/ws-tcp-udp-bridge:latest

Run the container

docker run -p 8080:8080 sharevb/ws-tcp-udp-bridge:latest

Healthcheck

The container includes a healthcheck that verifies the WebSocket port is reachable:

HEALTHCHECK CMD nc -z localhost 8080 || exit 1

Multi‑Arch Support

Images are built for:

  • linux/amd64
  • linux/arm64

This allows deployment on:

  • Standard servers
  • Raspberry Pi
  • ARM‑based cloud instances

Example Client (JavaScript)

const ws = new WebSocket("ws://localhost:8080");
ws.binaryType = "arraybuffer";

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "config",
    protocol: "tcp",
    host: "127.0.0.1",
    port: 9000
  }));

  ws.send(JSON.stringify({
    type: "send",
    payload: [0x48, 0x65, 0x6c, 0x6c, 0x6f]
  }));
};

ws.onmessage = (event) => {
  console.log("Received:", event.data);
};

Running with IT Tools

You can run this WebSocket TCP/UDP Bridge with IT Tools to use it in /tcp-udp-port-tester tool with the followings Docker Compose. Then fill WebSocket TCP/UDP Bridge Url field with ws://<your ip>:9000

services:
  ws-tcp-udp-bridge:
    image: sharevb/ws-tcp-udp-bridge:latest
    container_name: ws-tcp-udp-bridge
    restart: unless-stopped

    environment:
      WS_HOST: "0.0.0.0"
      WS_PORT: "9000"

    ports:
      - "9000:9000"

    # Optional: if you want to pass custom DNS or networking
    # dns:
    #   - 1.1.1.1

    # Optional: if you want to attach to a custom network
    # networks:
    #   - bridge-net
  it-tools:
    container_name: it-tools
    image: sharevb/it-tools:latest
    pull_policy: always
    restart: unless-stopped
    ports:
      - 8080:8080

# Optional custom network
# networks:
#   bridge-net:
#     driver: bridge

License

MIT License.
Use freely in commercial and open‑source projects.
⚡