EdgeTunnel

https://github.com/zizifn/edgetunnel
Admin
EdgeTunnel is a lightweight VLESS proxy implementation built on Cloudflare Workers that tunnels TCP...
Tokens:9,012
Snippets:52
Trust Score:8.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Requesting VLESS Connection Config

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Example of how to obtain a VLESS connection string and Clash-meta YAML snippet by requesting the configured UUID path.

```bash
// Hitting GET /{UUID} returns the VLESS connection config:
// curl https://my-edge-tunnel.workers.dev/d342d11e-d424-4583-b36e-524ab1f0afa4
// ################################################################
// v2ray
// ---------------------------------------------------------------
// vless://d342d11e-d424-4583-b36e-524ab1f0afa4@my-edge-tunnel.workers.dev:443
//   ?encryption=none&security=tls&sni=my-edge-tunnel.workers.dev
//   &fp=randomized&type=ws&host=my-edge-tunnel.workers.dev
//   &path=%2F%3Fed%3D2048#my-edge-tunnel.workers.dev
// ...
```

--------------------------------

### Requesting Cloudflare Metadata

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Example of how to retrieve Cloudflare request metadata by hitting the root path of the deployed worker.

```bash
// Hitting GET / returns Cloudflare metadata:
// curl https://my-edge-tunnel.workers.dev/
// {"colo":"SJC","country":"US","city":"San Jose",...}
```

--------------------------------

### EdgeTunnel Deployment Commands

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Commands for installing dependencies, generating a UUID, and running the EdgeTunnel worker locally using Wrangler.

```bash
# Install dependencies
npm install

# Generate a UUID (PowerShell)
[guid]::NewGuid()

# Local development (targets src/worker-vless.js)
npx wrangler dev src/worker-vless.js

```

--------------------------------

### Publish EdgeTunnel Worker

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Use this command to deploy the EdgeTunnel JavaScript file to Cloudflare Workers. Ensure you have Wrangler CLI installed and configured.

```bash
npx wrangler publish
```

--------------------------------

### Retrieve Client Configuration

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Fetch the generated client configuration URI or snippet for your UUID. This configuration can be directly imported into compatible proxy clients.

```bash
curl https://<your-worker>.workers.dev/<your-uuid>
```

--------------------------------

### getVLESSConfig

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Generates a ready-to-paste configuration block for v2ray-core / Xray and Clash-meta. It includes a vless:// URI and a Clash-meta YAML proxy entry with TLS enabled, WebSocket transport, and randomized client fingerprint.

```APIDOC
## `getVLESSConfig(userID, hostName)` — client configuration generator

Generates a ready-to-paste configuration block containing both a `vless://` URI (compatible with v2ray-core / Xray) and a Clash-meta YAML proxy entry. TLS is enabled, SNI is set to the worker hostname, transport is WebSocket with `path=/?ed=2048` (2048-byte early-data), and the client fingerprint is randomized.

```js
const config = getVLESSConfig(
  "d342d11e-d424-4583-b36e-524ab1f0afa4",
  "my-edge-tunnel.workers.dev"
);
// Outputs:
// ################################################################
// v2ray
// ---------------------------------------------------------------
// vless://d342d11e-d424-4583-b36e-524ab1f0afa4@my-edge-tunnel.workers.dev:443
//   ?encryption=none&security=tls&sni=my-edge-tunnel.workers.dev
//   &fp=randomized&type=ws&host=my-edge-tunnel.workers.dev
//   &path=%2F%3Fed%3D2048#my-edge-tunnel.workers.dev
// ---------------------------------------------------------------
// ################################################################
// clash-meta
// ---------------------------------------------------------------
// - type: vless
//   name: my-edge-tunnel.workers.dev
//   server: my-edge-tunnel.workers.dev
//   port: 443
//   uuid: d342d11e-d424-4583-b36e-524ab1f0afa4
//   network: ws
//   tls: true
//   ...
```
```

--------------------------------

### Generate VLESS Client Configuration

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Generates a vless:// URI and Clash-meta YAML proxy entry. TLS is enabled, SNI is set to the worker hostname, transport is WebSocket with a specific path, and the client fingerprint is randomized.

```javascript
const config = getVLESSConfig(
  "d342d11e-d424-4583-b36e-524ab1f0afa4",
  "my-edge-tunnel.workers.dev"
);
// Outputs:
// ################################################################
// v2ray
// ---------------------------------------------------------------
// vless://d342d11e-d424-4583-b36e-524ab1f0afa4@my-edge-tunnel.workers.dev:443
//   ?encryption=none&security=tls&sni=my-edge-tunnel.workers.dev
//   &fp=randomized&type=ws&host=my-edge-tunnel.workers.dev
//   &path=%2F%3Fed%3D2048#my-edge-tunnel.workers.dev
// ---------------------------------------------------------------
// ################################################################
// clash-meta
// ---------------------------------------------------------------
// - type: vless
//   name: my-edge-tunnel.workers.dev
//   server: my-edge-tunnel.workers.dev
//   port: 443
//   uuid: d342d11e-d424-4583-b36e-524ab1f0afa4
//   network: ws
//   tls: true
//   ...

```

--------------------------------

### V2Ray Client Configuration (Local)

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Reference v2ray JSON configurations for connecting a local client. These expose SOCKS5 and HTTP inbounds and route specific traffic through the VLESS WebSocket outbound.

```jsonc
// config/config-client-without-dns-lcoal.json
// Connect to worker running locally on port 8787 (wrangler dev)
{
  "inbounds": [
    { "port": "4080", "protocol": "socks", "settings": { "auth": "noauth", "udp": true } },
    { "port": "4081", "protocol": "http" }
  ],
  "outbounds": [
    {
      "protocol": "vless",
      "settings": {
        "vnext": [{
          "address": "127.0.0.1",
          "port": 8787,
          "users": [{ "id": "1a403b79-039b-4dc2-9b45-1ad13197b99a", "encryption": "none" }]
        }]
      },
      "streamSettings": { "network": "ws" },
      "tag": "zizi-ws"
    },
    { "protocol": "freedom", "tag": "direct" }
  ],
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      { "type": "field", "ip": ["8.8.8.8"], "outboundTag": "zizi-ws" },
      { "type": "field", "ip": ["geoip:private"], "outboundTag": "zizi-ws" }
    ]
  }
}

// config/config-client-with-dns-lcoal.json
// Same as above but targets port 8788 and adds explicit ws path:
// "wsSettings": { "path": "/vless" }

```

--------------------------------

### Test Info Endpoint

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Verify that your deployed worker is accessible by sending a request to its root endpoint. Replace `<your-worker>` with your actual worker domain.

```bash
curl https://<your-worker>.workers.dev/
```

--------------------------------

### makeReadableWebSocketStream(webSocketServer, earlyDataHeader, log)

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Wraps a Cloudflare WebSocket server object into a WHATWG `ReadableStream`. It handles WebSocket events and decodes optional early-data from the `sec-websocket-protocol` header for 0-RTT capabilities.

```APIDOC
## `makeReadableWebSocketStream(webSocketServer, earlyDataHeader, log)` — WS → ReadableStream

Wraps a Cloudflare WebSocket server object in a WHATWG `ReadableStream`. Handles `message`, `close`, and `error` events, propagating them to the stream controller. Also decodes the optional `sec-websocket-protocol` header as URL-safe base64 early-data and enqueues it before any message events, enabling 0-RTT data from compatible clients.

```js
// The stream is backpressure-aware but CF runtime does not yet
// pause WebSocket receive, so no active backpressure is applied.

const stream = makeReadableWebSocketStream(webSocket, earlyDataHeader, log);

// Piping to a WritableStream processes all WS messages sequentially:
stream.pipeTo(new WritableStream({
  write(chunk) {
    // chunk is ArrayBuffer — process VLESS header on first call,
    // then forward raw bytes to TCP on subsequent calls
  },
  close() { log('ws stream closed'); },
  abort(reason) { log('ws stream aborted', reason); }
})).catch(err => log('pipe error', err));
```
```

--------------------------------

### Deploy Standard Worker with wrangler.toml

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Configuration for deploying the standard EdgeTunnel worker using wrangler.toml. Environment variables can override default UUID and PROXYIP settings.

```toml
// wrangler.toml — deploy the standard worker
// name = "my-edge-tunnel"
// main = "src/worker-vless.js"
// compatibility_date = "2024-04-15"
// [vars]
// UUID = "d342d11e-d424-4583-b36e-524ab1f0afa4"
// PROXYIP = ""          // optional fallback proxy IP
```

--------------------------------

### handleDNSQuery

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Handles DNS-over-TCP relaying for DNS queries. It establishes a direct TCP connection to Google's DNS server (8.8.4.4:53) and pipes the response back to the WebSocket.

```APIDOC
## `handleDNSQuery(udpChunk, webSocket, vlessResponseHeader, log)` — DNS-over-TCP relay (experimental worker)

An alternative DNS handler used in `worker-with-socks5-experimental.js`. Instead of DoH, it opens a plain TCP connection to `8.8.4.4:53`, sends the raw DNS query bytes, and pipes the response back to the WebSocket. This avoids DoH and uses standard DNS-over-TCP.

```js
// DNS-over-TCP to Google's 8.8.4.4:53
// udpChunk: raw DNS query as Uint8Array (no length prefix here — already stripped)

await handleDNSQuery(rawDNSData, webSocket, vlessResponseHeader, log);
// Internally:
//   const tcpSocket = connect({ hostname: '8.8.4.4', port: 53 });
//   await writer.write(udpChunk);
//   tcpSocket.readable.pipeTo(writableStream that sends chunks to webSocket)
```
```

--------------------------------

### socks5AddressParser

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Parses the SOCKS5 environment variable string into its constituent parts: username, password, hostname, and port.

```APIDOC
## `socks5AddressParser(address)` — SOCKS5 address string parser

Splits the `SOCKS5` environment variable into its `{ username, password, hostname, port }` components. Handles both authenticated (`user:pass@host:port`) and unauthenticated (`host:port`) formats and validates the IPv6 bracket format.

```js
socks5AddressParser("alice:secret@proxy.example.com:1080");
// → { username: "alice", password: "secret", hostname: "proxy.example.com", port: 1080 }

socks5AddressParser("10.0.0.1:1080");
// → { username: undefined, password: undefined, hostname: "10.0.0.1", port: 1080 }

socks5AddressParser("[::1]:1080");
// → { hostname: "[::1]", port: 1080 }

socks5AddressParser("bad-input");
// throws Error("Invalid SOCKS address format")
```
```

--------------------------------

### Perform SOCKS5 Handshake and Connection

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Implements the SOCKS5 handshake (RFC 1928, 1929) for establishing outbound connections. Supports no authentication and username/password authentication. Constructs the CONNECT request based on VLESS address type.

```javascript
// env.SOCKS5 format: "user:pass@host:port"  or  "host:port"
// Example:
//   SOCKS5 = "myuser:mypassword@socks5-proxy.example.com:1080"
//   SOCKS5 = "127.0.0.1:1080"   // no auth

// Handshake bytes sent:
//   Greeting:  [0x05, 0x02, 0x00, 0x02]  (SOCKS5, 2 methods: noauth + user/pass)
//   Auth:      [0x01, ulen, ...user, plen, ...pass]
//   Connect:   [0x05, 0x01, 0x00, atyp, ...addr, port_hi, port_lo]

const socket = await socks5Connect(2, "example.com", 443, log);
// socket is a Cloudflare Socket ready for writing TLS ClientHello
```

--------------------------------

### handleUDPOutBound

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Handles DNS-over-HTTPS relaying for UDP traffic. It parses DNS query packets from a VLESS client, forwards them to Cloudflare's DoH endpoint, and returns the response via WebSocket.

```APIDOC
## `handleUDPOutBound(webSocket, vlessResponseHeader, log)` — DNS-over-HTTPS relay (standard worker)

Used exclusively for UDP port 53 (DNS). Parses the UDP length-prefixed packet stream from the VLESS client, forwards each DNS query over HTTPS to Cloudflare's `1.1.1.1/dns-query` endpoint (DoH), and sends the response back over the WebSocket with the VLESS response header prepended to the first reply.

```js
// DNS query flow:
// Client sends: [2-byte length][DNS wire-format query][2-byte length][query]...
// Worker forwards each query to: POST https://1.1.1.1/dns-query
//   Content-Type: application/dns-message
// Worker responds via WebSocket with [vlessHeader][2-byte length][DNS response]

const { write } = await handleUDPOutBound(webSocket, vlessResponseHeader, log);
write(rawDNSChunk); // called once per VLESS UDP payload chunk
```
```

--------------------------------

### Wrap WebSocket Server in ReadableStream

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Wraps a Cloudflare WebSocket server object in a WHATWG ReadableStream. Handles message, close, and error events, propagating them to the stream controller. Decodes optional sec-websocket-protocol header as URL-safe base64 early-data for 0-RTT.

```javascript
// The stream is backpressure-aware but CF runtime does not yet
// pause WebSocket receive, so no active backpressure is applied.

const stream = makeReadableWebSocketStream(webSocket, earlyDataHeader, log);

// Piping to a WritableStream processes all WS messages sequentially:
stream.pipeTo(new WritableStream({
  write(chunk) {
    // chunk is ArrayBuffer — process VLESS header on first call,
    // then forward raw bytes to TCP on subsequent calls
  },
  close() { log('ws stream closed'); },
  abort(reason) { log('ws stream aborted', reason); }
})).catch(err => log('pipe error', err));
```

--------------------------------

### Parse SOCKS5 Environment Variable String

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Parses the SOCKS5 environment variable string into its components: username, password, hostname, and port. Handles both authenticated and unauthenticated formats, including IPv6 bracket notation.

```javascript
socks5AddressParser("alice:secret@proxy.example.com:1080");
// → { username: "alice", password: "secret", hostname: "proxy.example.com", port: 1080 }

socks5AddressParser("10.0.0.1:1080");
// → { username: undefined, password: undefined, hostname: "10.0.0.1", port: 1080 }

socks5AddressParser("[::1]:1080");
// → { hostname: "[::1]", port: 1080 }

socks5AddressParser("bad-input");
// throws Error("Invalid SOCKS address format")
```

--------------------------------

### socks5Connect

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Performs a SOCKS5 handshake to establish a connection through a SOCKS5 proxy. It supports both unauthenticated and username/password authentication methods.

```APIDOC
## `socks5Connect(addressType, addressRemote, portRemote, log)` — SOCKS5 outbound (experimental)

Performs a full SOCKS5 handshake (RFC 1928 + RFC 1929) with the server configured in `env.SOCKS5`. Supports both unauthenticated (`0x00`) and username/password authentication (`0x02`). Constructs the CONNECT request with the correct address type byte matching the VLESS address type (1=IPv4, 3=domain, 4=IPv6), then returns the open socket ready for application data.

```js
// env.SOCKS5 format: "user:pass@host:port"  or  "host:port"
// Example:
//   SOCKS5 = "myuser:mypassword@socks5-proxy.example.com:1080"
//   SOCKS5 = "127.0.0.1:1080"   // no auth

// Handshake bytes sent:
//   Greeting:  [0x05, 0x02, 0x00, 0x02]  (SOCKS5, 2 methods: noauth + user/pass)
//   Auth:      [0x01, ulen, ...user, plen, ...pass]
//   Connect:   [0x05, 0x01, 0x00, atyp, ...addr, port_hi, port_lo]

const socket = await socks5Connect(2, "example.com", 443, log);
// socket is a Cloudflare Socket ready for writing TLS ClientHello
```
```

--------------------------------

### processVlessHeader(vlessBuffer, userID)

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Parses a raw ArrayBuffer according to the VLESS protocol specification. It validates the protocol version, extracts and verifies the UUID, reads optional data length, determines the command (TCP or UDP), parses the port, and decodes the destination address.

```APIDOC
## `processVlessHeader(vlessBuffer, userID)` — VLESS protocol header parser

Parses a raw `ArrayBuffer` according to the [VLESS protocol specification](https://xtls.github.io/development/protocols/vless.html). Validates the protocol version byte, extracts and verifies the 16-byte UUID against `userID`, reads the optional-data length, determines the command (TCP `0x01` or UDP `0x02`), parses the 2-byte big-endian port, and decodes the destination address (IPv4, domain, or IPv6).

```js
// Returns on success:
// {
//   hasError: false,
//   addressRemote: "example.com",   // or "93.184.216.34" / "2606:2800:220:1:248:1893:25c8:1946"
//   addressType: 2,                 // 1=IPv4, 2=domain, 3=IPv6
//   portRemote: 443,
//   rawDataIndex: 37,               // byte offset where payload data begins
//   vlessVersion: Uint8Array([0]),
//   isUDP: false
// }
//
// Returns on error:
// { hasError: true, message: "invalid user" }

const result = processVlessHeader(chunk, "d342d11e-d424-4583-b36e-524ab1f0afa4");
if (result.hasError) {
  throw new Error(result.message);
  // possible messages: "invalid data", "invalid user",
  //   "command X is not support", "invild addressType is X"
}
const { addressRemote, portRemote, rawDataIndex, isUDP } = result;
const payload = chunk.slice(rawDataIndex); // raw TLS ClientHello or first app bytes
```
```

--------------------------------

### VLESS-over-WebSocket Handler Logic

Source: https://context7.com/zizifn/edgetunnel/llms.txt

The core logic for handling VLESS-over-WebSocket requests. It accepts WebSocket upgrades, parses VLESS headers, and relays data between the client and remote TCP/UDP sockets.

```javascript
// Client connects with a standard VLESS+WS client (e.g. v2ray-core):
//   ws://my-edge-tunnel.workers.dev/ (plain) or
//   wss://my-edge-tunnel.workers.dev/ (TLS, recommended)
//
// The sec-websocket-protocol header carries optional base64-encoded
// early data (0-RTT) that is decoded and prepended to the first chunk.
//
// Internal flow (simplified):
async function vlessOverWSHandler(request) {
  const [client, webSocket] = Object.values(new WebSocketPair());
  webSocket.accept();

  const readableWebSocketStream = makeReadableWebSocketStream(webSocket, earlyDataHeader, log);

  readableWebSocketStream.pipeTo(new WritableStream({
    async write(chunk) {
      const { hasError, addressRemote, portRemote, rawDataIndex, isUDP } = 
        processVlessHeader(chunk, userID);

      if (isUDP && portRemote === 53) {
        // Route through DNS-over-HTTPS / DNS-over-TCP
        await handleUDPOutBound(webSocket, vlessResponseHeader, log);
      } else {
        // Open TCP socket to addressRemote:portRemote
        await handleTCPOutBound(remoteSocket, addressRemote, portRemote, ...);
      }
    }
  }));

  return new Response(null, { status: 101, webSocket: client });
}
```

--------------------------------

### Relay TCP Socket to WebSocket with VLESS Header

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Reads from a TCP socket and forwards data over a WebSocket. The first chunk is prefixed with a VLESS response header. Triggers a retry if the socket closes before data arrives and a retry callback is provided.

```javascript
await remoteSocket.readable.pipeTo(new WritableStream({
  async write(chunk) {
    if (webSocket.readyState !== WS_READY_STATE_OPEN) {
      throw new Error('webSocket closed');
    }
    if (vlessHeader) {
      // Prepend response header to first TCP chunk
      webSocket.send(await new Blob([vlessHeader, chunk]).arrayBuffer());
      vlessHeader = null;
    } else {
      webSocket.send(chunk);  // raw bytes for all subsequent chunks
    }
  }
}));

// If zero bytes received, trigger retry (fallback IP or SOCKS5):
if (!hasIncomingData && retry) retry();
```

--------------------------------

### Set Secrets with Wrangler

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Set sensitive information like UUIDs using Wrangler's secret management. You will be prompted to enter the value after running the command.

```bash
npx wrangler secret put UUID
```

--------------------------------

### Handle DNS Query for DNS-over-TCP Relay

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Relays DNS queries using DNS-over-TCP to Google's public DNS server (8.8.4.4:53). This is an experimental handler used in specific worker configurations and avoids DoH.

```javascript
// DNS-over-TCP to Google's 8.8.4.4:53
// udpChunk: raw DNS query as Uint8Array (no length prefix here — already stripped)

await handleDNSQuery(rawDNSData, webSocket, vlessResponseHeader, log);
// Internally:
//   const tcpSocket = connect({ hostname: '8.8.4.4', port: 53 });
//   await writer.write(udpChunk);
//   tcpSocket.readable.pipeTo(writableStream that sends chunks to webSocket)
```

--------------------------------

### remoteSocketToWS

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Relays data from a Cloudflare TCP socket to an open WebSocket. It prepends a VLESS response header to the first chunk of data sent.

```APIDOC
## `remoteSocketToWS(remoteSocket, webSocket, vlessResponseHeader, retry, log)` — TCP → WS relay

Reads from a Cloudflare TCP socket's `readable` stream and forwards each chunk over the open WebSocket. The first chunk is prefixed with the 2-byte VLESS response header (`[version, 0]`). If the remote socket closes before any data arrives and a `retry` callback is provided, the retry is invoked.

```js
// vlessResponseHeader = new Uint8Array([vlessVersion[0], 0])
// This tells the VLESS client which protocol version the server accepted.

await remoteSocket.readable.pipeTo(new WritableStream({
  async write(chunk) {
    if (webSocket.readyState !== WS_READY_STATE_OPEN) {
      throw new Error('webSocket closed');
    }
    if (vlessHeader) {
      // Prepend response header to first TCP chunk
      webSocket.send(await new Blob([vlessHeader, chunk]).arrayBuffer());
      vlessHeader = null;
    } else {
      webSocket.send(chunk);  // raw bytes for all subsequent chunks
    }
  }
}));

// If zero bytes received, trigger retry (fallback IP or SOCKS5):
if (!hasIncomingData && retry) retry();
```
```

--------------------------------

### Handle UDP Outbound for DNS-over-HTTPS Relay

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Handles UDP DNS queries by forwarding them over HTTPS to Cloudflare's DoH endpoint. The response is sent back via WebSocket with a VLESS response header prepended. This is used for standard worker DNS relay.

```javascript
// DNS query flow:
// Client sends: [2-byte length][DNS wire-format query][2-byte length][query]...
// Worker forwards each query to: POST https://1.1.1.1/dns-query
//   Content-Type: application/dns-message
// Worker responds via WebSocket with [vlessHeader][2-byte length][DNS response]

const { write } = await handleUDPOutBound(webSocket, vlessResponseHeader, log);
write(rawDNSChunk); // called once per VLESS UDP payload chunk
```

--------------------------------

### Cloudflare IP Range Check Utility

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Checks if an IPv4 address is within Cloudflare's /24 CIDR blocks. This is a testing utility that uses bitwise operations for efficient lookup.

```javascript
// From test/cidr.js — run with Node.js directly
console.log(isIPv4InCFCIDR('1.1.1.1'));          // true  (Cloudflare DNS)
console.log(isIPv4InCFCIDR('162.159.137.0'));     // true  (Cloudflare range)
console.log(isIPv4InCFCIDR('8.8.8.8'));           // false (Google DNS)
console.log(isIPv4InCFCIDR('192.168.1.1'));       // false (private range)

// Helper used internally:
function convertIp2Num(ip) {
  return ip.split('.').reduce((acc, octet) => (acc << 8) + parseInt(octet, 10), 0) >>> 0;
}
// convertIp2Num('8.9.231.0') === 134866688

```

--------------------------------

### Handle Outbound TCP Relay with Retry

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Opens a Cloudflare TCP socket, writes client data, and pipes the remote socket's stream back to the WebSocket client. Triggers a retry if the socket closes with zero incoming bytes, falling back to PROXYIP or SOCKS5.

```javascript
// Standard worker retry: falls back to env.PROXYIP
// Experimental worker retry: falls back to SOCKS5 address

// Retry is transparent to the WebSocket client.
// Example wrangler.toml config for fallback:
// [vars]
// UUID    = "d342d11e-d424-4583-b36e-524ab1f0afa4"
// PROXYIP = "cdn.cloudflare.steamstatic.com"  // alternate Cloudflare-friendly IP

async function handleTCPOutBound(remoteSocket, addressType, addressRemote, portRemote,
                                  rawClientData, webSocket, vlessResponseHeader, log) {
  async function connectAndWrite(address, port, socks = false) {
    const tcpSocket = socks
      ? await socks5Connect(addressType, address, port, log) // experimental only
      : connect({ hostname: address, port });
    await tcpSocket.writable.getWriter().write(rawClientData);
    return tcpSocket;
  }

  const tcpSocket = await connectAndWrite(addressRemote, portRemote);
  remoteSocketToWS(tcpSocket, webSocket, vlessResponseHeader,
    /* retry */ async () => {
      const fallback = await connectAndWrite(proxyIP || addressRemote, portRemote);
      remoteSocketToWS(fallback, webSocket, vlessResponseHeader, null, log);
    }, log);
}
```

--------------------------------

### Parse VLESS Header with UUID Validation

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Parses a raw ArrayBuffer according to the VLESS protocol. Validates protocol version, UUID, optional-data length, command, port, and destination address. Returns parsed data or an error object.

```javascript
// Returns on success:
// {
//   hasError: false,
//   addressRemote: "example.com",   // or "93.184.216.34" / "2606:2800:220:1:248:1893:25c8:1946"
//   addressType: 2,                 // 1=IPv4, 2=domain, 3=IPv6
//   portRemote: 443,
//   rawDataIndex: 37,               // byte offset where payload data begins
//   vlessVersion: Uint8Array([0]),
//   isUDP: false
// }
//
// Returns on error:
// { hasError: true, message: "invalid user" }

const result = processVlessHeader(chunk, "d342d11e-d424-4583-b36e-524ab1f0afa4");
if (result.hasError) {
  throw new Error(result.message);
  // possible messages: "invalid data", "invalid user",
  //   "command X is not support", "invild addressType is X"
}
const { addressRemote, portRemote, rawDataIndex, isUDP } = result;
const payload = chunk.slice(rawDataIndex); // raw TLS ClientHello or first app bytes
```

--------------------------------

### handleTCPOutBound(...)

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Relays outbound TCP connections through Cloudflare sockets, with built-in retry mechanisms. It writes client data to the remote socket and pipes the response back to the WebSocket client, falling back to a proxy IP or SOCKS5 if necessary.

```APIDOC
## `handleTCPOutBound(...)` — outbound TCP relay with retry

Opens a Cloudflare TCP socket to `addressRemote:portRemote`, writes `rawClientData` (typically a TLS ClientHello), then pipes the remote socket's readable stream back to the WebSocket client. If the socket closes with zero incoming bytes (e.g., blocked by upstream), a retry is triggered using `proxyIP` (or SOCKS5 if the experimental worker is used).

```js
// Standard worker retry: falls back to env.PROXYIP
// Experimental worker retry: falls back to SOCKS5 address

// Retry is transparent to the WebSocket client.
// Example wrangler.toml config for fallback:
// [vars]
// UUID    = "d342d11e-d424-4583-b36e-524ab1f0afa4"
// PROXYIP = "cdn.cloudflare.steamstatic.com"  // alternate Cloudflare-friendly IP

async function handleTCPOutBound(remoteSocket, addressType, addressRemote, portRemote,
                                  rawClientData, webSocket, vlessResponseHeader, log) {
  async function connectAndWrite(address, port, socks = false) {
    const tcpSocket = socks
      ? await socks5Connect(addressType, address, port, log) // experimental only
      : connect({ hostname: address, port });
    await tcpSocket.writable.getWriter().write(rawClientData);
    return tcpSocket;
  }

  const tcpSocket = await connectAndWrite(addressRemote, portRemote);
  remoteSocketToWS(tcpSocket, webSocket, vlessResponseHeader,
    /* retry */ async () => {
      const fallback = await connectAndWrite(proxyIP || addressRemote, portRemote);
      remoteSocketToWS(fallback, webSocket, vlessResponseHeader, null, log);
    }, log);
}
```
```

--------------------------------

### URL-safe Base64 to ArrayBuffer Decoder

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Converts a URL-safe base64 string to an ArrayBuffer. It's used to decode optional early-data sent in the WebSocket header. Handles invalid input by returning a DOMException.

```javascript
const { earlyData, error } = base64ToArrayBuffer("SGVsbG8gV29ybGQ");
// earlyData → ArrayBuffer of "Hello World"
// error → null on success

const { error: err } = base64ToArrayBuffer("!!!invalid!!!");
// err → DOMException from atob

// Called automatically inside makeReadableWebSocketStream:
const { earlyData, error } = base64ToArrayBuffer(
  request.headers.get('sec-websocket-protocol') || ''
);
if (earlyData) controller.enqueue(earlyData); // prepend 0-RTT data to stream

```

--------------------------------

### base64ToArrayBuffer

Source: https://context7.com/zizifn/edgetunnel/llms.txt

Converts a URL-safe base64 string to an ArrayBuffer. This function is used to decode the optional early-data sent in the WebSocket header.

```APIDOC
## `base64ToArrayBuffer(base64Str)` — URL-safe base64 decoder

Converts a URL-safe base64 string (RFC 4648) to an `ArrayBuffer`. Replaces `-` with `+` and `_` with `/` before calling `atob`, then wraps the result in a `Uint8Array`. Used to decode the optional early-data sent in the `sec-websocket-protocol` WebSocket header.

```js
const { earlyData, error } = base64ToArrayBuffer("SGVsbG8gV29ybGQ");
// earlyData → ArrayBuffer of "Hello World"
// error → null on success

const { error: err } = base64ToArrayBuffer("!!!invalid!!!");
// err → DOMException from atob

// Called automatically inside makeReadableWebSocketStream:
const { earlyData, error } = base64ToArrayBuffer(
  request.headers.get('sec-websocket-protocol') || ''
);
if (earlyData) controller.enqueue(earlyData); // prepend 0-RTT data to stream
```
```

--------------------------------

### isIPv4InCFCIDR

Source: https://context7.com/zizifn/edgetunnel/llms.txt

A utility function to check if an IPv4 address falls within any of the Cloudflare-owned /24 CIDR blocks. This is primarily used for development and testing purposes.

```APIDOC
## `isIPv4InCFCIDR(ip)` — Cloudflare IP range check (test utility)

Checks whether an IPv4 address falls within any of the thousands of Cloudflare-owned /24 CIDR blocks listed in `test/cidr.js`. Uses bitwise AND with a precomputed integer mask for O(n) lookup across the full CIDR list. Used during development/testing to verify routing logic.

```js
// From test/cidr.js — run with Node.js directly
console.log(isIPv4InCFCIDR('1.1.1.1'));          // true  (Cloudflare DNS)
console.log(isIPv4InCFCIDR('162.159.137.0'));     // true  (Cloudflare range)
console.log(isIPv4InCFCIDR('8.8.8.8'));           // false (Google DNS)
console.log(isIPv4InCFCIDR('192.168.1.1'));       // false (private range)

// Helper used internally:
function convertIp2Num(ip) {
  return ip.split('.').reduce((acc, octet) => (acc << 8) + parseInt(octet, 10), 0) >>> 0;
}
// convertIp2Num('8.9.231.0') === 134866688
```
```
Tokens:
Raw