SOCKS5 Client Connection Data Path in OpenFlux: Technical Architecture

The data path for SOCKS5 client connections in OpenFlux flows from the local SOCKS5 listener through a tunnel dialer interface to transport-specific implementations (Yandex, Max, or Cups.online), ultimately routing traffic to the exit node and destination internet addresses.

OpenFlux (p1neappleXpress/OpenFlux) implements a custom TCP tunneling solution that exposes a standard SOCKS5 proxy interface for client applications. Understanding the data path for SOCKS5 client connections is essential for developers extending the transport layer or debugging connection issues. This article traces the complete journey from client connection initialization through the tunnel to the exit node.

SOCKS5 Server Entry Point and Listener Configuration

The SOCKS5 server acts as the primary entry point for client applications. When OpenFlux starts with the --client flag, main.go initializes the SOCKS5 listener on the configured address (default :1080).

According to the OpenFlux source code, the server implementation resides in socks5/socks5.go. The SOCKS5Server struct accepts a dialer that satisfies the DialTCP interface defined at lines 13-14:

type Dialer interface {
    DialTCP(address string) (net.Conn, error)
}

This abstraction allows the SOCKS5 layer to remain transport-agnostic while delegating actual connection establishment to the tunnel implementation.

The Five-Stage Client Connection Data Path

When a client application initiates a connection through the OpenFlux SOCKS5 proxy, the data traverses a specific five-stage pipeline:

1. Client to SOCKS5 Server Initialization

The client opens a TCP connection to the SOCKS5 listener (default :1080). The server parses the SOCKS5 CONNECT request to extract the target destination address.

2. SOCKS5 to Tunnel Dialer Handoff

The SOCKS5Server.handleConnection method calls s.dialer.DialTCP(targetAddr) to obtain a net.Conn representing the remote side of the flow. This dialer is the client-side tunnel created in main.go and injected at line 137 via NewSOCKS5Server.

3. Tunnel to Transport Layer

The tunnel's DialTCP implementation creates a transport-specific connection. Depending on the --transport flag specified at startup, this could establish:

• A WebRTC DataChannel for the Max transport
• A Yandex Docs cursor stream for the Yandex transport
• A Cups.online specific stream for the Cups.online transport

4. Transport to Exit Node

The transport layer encodes packets, optionally applies compression or encryption, and transmits them to the exit node. The exit node decapsulates these packets and forwards them to the final internet destination.

5. Bidirectional Data Proxying

Once both connections are established, two goroutines handle bidirectional traffic copying. As implemented in socks5/socks5.go lines 50-58, the code uses io.Copy to bridge the client socket and transport socket:

// Inside socks5/socks5.go – handing a client connection to the dialer
targetConn, err := s.dialer.DialTCP(targetAddr) // <‑‑ the tunnel creates the transport stream
if err != nil {
    // reply with SOCKS5 failure code
    clientConn.Write([]byte{0x05, 0x04, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00})
    return
}
defer targetConn.Close()

// Proxy traffic in both directions
go io.Copy(targetConn, clientConn)
go io.Copy(clientConn, targetConn)

This continues until either side closes the connection.

Wiring the Components: Client Initialization

The concrete dialer instance is created in main.go when the program launches with the --client flag. The initialization sequence selects the transport based on the --transport flag, constructs the tunnel (tun), and passes it to NewSOCKS5Server at line 137:

// Create a SOCKS5 server that forwards connections through the tunnel
addr := ":1080"                     // listen address (can be overridden with --socks5)
tun := NewTunnel(transport)        // transport implements the Dialer interface
socks5Srv := socks5.NewSOCKS5Server(addr, tun)

// Start listening – this blocks until the server is closed
if err := socks5Srv.Start(); err != nil {
    log.Fatalf("SOCKS5 server exited: %v", err)
}

This wiring ensures that every incoming SOCKS5 connection utilizes the selected transport mechanism for tunneling.

Key Source Files in the Data Path

Several critical files define the SOCKS5 client connection data path in OpenFlux:

• socks5/socks5.go: Implements the SOCKS5 protocol handler, parses CONNECT requests, and manages the bidirectional io.Copy loops (lines 50-58) that proxy data between the client and the tunnel dialer.
• main.go: Orchestrates application startup, parses command-line flags (--client, --transport, --socks5), and constructs the tunnel instance passed to the SOCKS5 server (line 137).
• tunnel/tunnel.go: Provides the client-side tunnel implementation that satisfies the Dialer interface, routing packets through the chosen transport layer.
• transport/transport.go: Defines the Transport interface; concrete implementations (Yandex, Max, Cups.online) handle packet encoding, encryption, and delivery to the exit node.

Summary

• The SOCKS5 client data path in OpenFlux starts at the SOCKS5 listener (default :1080) defined in socks5/socks5.go.
• The Dialer interface with its DialTCP method (lines 13-14) abstracts the connection to the tunnel layer.
• main.go wires the tunnel implementation to the SOCKS5 server at line 137 when the --client flag is active.
• Traffic flows through five stages: Client → SOCKS5 → Tunnel → Transport → Exit Node → Internet.
• Bidirectional proxying uses io.Copy goroutines (lines 50-58 of socks5.go) to bridge client and transport sockets until connection close.

Frequently Asked Questions

What is the default listening address for SOCKS5 client connections in OpenFlux?

By default, OpenFlux binds the SOCKS5 server to :1080. This can be overridden using the --socks5 command-line flag specified in main.go during client initialization.

How does OpenFlux handle SOCKS5 CONNECT requests from clients?

When a client sends a SOCKS5 CONNECT request, the server in socks5/socks5.go parses the destination address from the request, then calls s.dialer.DialTCP(targetAddr) to establish the outbound connection through the tunnel. If the dial fails, the server returns a SOCKS5 failure response code (such as 0x04) to the client.

Which file creates the dialer instance used for SOCKS5 connections?

The concrete dialer instance is created in main.go when the application starts with the --client flag. The tunnel instance (tun) is constructed from the selected transport and injected into the SOCKS5 server via NewSOCKS5Server at line 137.

What transport options are available for routing SOCKS5 traffic in OpenFlux?

OpenFlux supports multiple transport implementations including Yandex, Max, and Cups.online. The transport is selected via the --transport flag and determines how the tunnel encapsulates and transmits data to the exit node.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}