# benyamin218118/tunnel architecture

> Architecture diagram of the GitHub repository benyamin218118/tunnel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benyamin218118/tunnel
- Repository: https://github.com/benyamin218118/tunnel

## Overview

This is a TCP-based relay tunnel with two configured roles: Relay accepts client connections and forwards them through a tunnel to Gate, which connects to the configured destination. The main workflow is configured in `main.go` and implemented largely in `tunnel.go`; the same `Tunnel` implementation branches by role. TCP, optional WebSocket transport, and experimental UDP-over-TCP are represented as distinct paths. The sampled source supports these runtime flows; CDN tunneling is documented but its network path is external to the code.

Main entry points: [`tunnel.go`](https://github.com/benyamin218118/tunnel/blob/main/tunnel.go) (Relay accept), [`main.go`](https://github.com/benyamin218118/tunnel/blob/main/main.go) (CLI configuration), [`models.go`](https://github.com/benyamin218118/tunnel/blob/main/models.go) (Connection map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup"]
  node_main["CLI configuration<br/>[main.go]"]
  node_tunnel["Tunnel runtime<br/>[tunnel.go]"]
  node_listeners["TCP/UDP listeners<br/>[tunnel.go]"]
end

subgraph group_tcp["TCP forwarding"]
  node_client(("Client"))
  node_relay["Relay accept<br/>[tunnel.go]"]
  node_gate["Gate accept<br/>[tunnel.go]"]
  node_destination(("Destination service"))
  node_stream["Bidirectional copy<br/>[tunnel.go]"]
end

subgraph group_websocket["WebSocket transport"]
  node_wsrelay["Relay WS handshake<br/>[tunnel.go]"]
  node_wsgate["Gate WS handshake<br/>[tunnel.go]"]
  node_cdn(("Optional CDN"))
end

subgraph group_udp["UDP forwarding"]
  node_udpclient(("UDP client"))
  node_udpmap[("Connection map<br/>[models.go]")]
  node_udpmarker["UDP marker detection<br/>[tunnel.go]"]
  node_udpreturn["UDP response forwarding<br/>[tunnel.go]"]
end

node_operator(("Operator"))

node_operator -->|"sets flags"| node_main
node_main -->|"creates runtime"| node_tunnel
node_tunnel -->|"opens listeners"| node_listeners
node_listeners -->|"accepts TCP"| node_client
node_listeners -->|"accepts UDP"| node_udpclient
node_client -->|"connects"| node_relay
node_relay -->|"dials gate"| node_gate
node_gate -->|"dials destination"| node_destination
node_relay -->|"copies bytes"| node_stream
node_gate -->|"copies bytes"| node_stream
node_stream -->|"forwards TCP"| node_destination
node_relay -.->|"starts handshake"| node_wsrelay
node_wsrelay -.->|"may traverse"| node_cdn
node_cdn -.->|"forwards upgrade"| node_wsgate
node_wsgate -.->|"accepts upgrade"| node_gate
node_udpclient -->|"sends datagram"| node_relay
node_relay -->|"looks up or stores"| node_udpmap
node_relay -->|"sends marker and data"| node_gate
node_gate -->|"detects marker"| node_udpmarker
node_udpmarker -->|"dials UDP"| node_destination
node_gate -->|"returns datagrams"| node_udpreturn
node_udpreturn -->|"writes response"| node_udpclient

click node_main "https://github.com/benyamin218118/tunnel/blob/main/main.go"
click node_tunnel "https://github.com/benyamin218118/tunnel/blob/main/tunnel.go"
click node_listeners "https://github.com/benyamin218118/tunnel/blob/main/tunnel.go"
click node_relay "https://github.com/benyamin218118/tunnel/blob/main/tunnel.go"
click node_gate "https://github.com/benyamin218118/tunnel/blob/main/tunnel.go"
click node_stream "https://github.com/benyamin218118/tunnel/blob/main/tunnel.go"
click node_wsrelay "https://github.com/benyamin218118/tunnel/blob/main/tunnel.go"
click node_wsgate "https://github.com/benyamin218118/tunnel/blob/main/tunnel.go"
click node_udpmap "https://github.com/benyamin218118/tunnel/blob/main/models.go"
click node_udpmarker "https://github.com/benyamin218118/tunnel/blob/main/tunnel.go"
click node_udpreturn "https://github.com/benyamin218118/tunnel/blob/main/tunnel.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_tunnel,node_listeners toneBlue
class node_client,node_relay,node_gate,node_destination,node_stream toneAmber
class node_wsrelay,node_wsgate,node_cdn toneMint
class node_udpclient,node_udpmap,node_udpmarker,node_udpreturn toneRose
class node_operator toneIndigo
```

## Components

### Startup

- [CLI configuration](https://github.com/benyamin218118/tunnel/blob/main/main.go): `main.go`
- [Tunnel runtime](https://github.com/benyamin218118/tunnel/blob/main/tunnel.go): `tunnel.go`
- [TCP/UDP listeners](https://github.com/benyamin218118/tunnel/blob/main/tunnel.go): `tunnel.go`

### TCP forwarding

- **Client**
- [Relay accept](https://github.com/benyamin218118/tunnel/blob/main/tunnel.go): `tunnel.go`
- [Gate accept](https://github.com/benyamin218118/tunnel/blob/main/tunnel.go): `tunnel.go`
- **Destination service**
- [Bidirectional copy](https://github.com/benyamin218118/tunnel/blob/main/tunnel.go): `tunnel.go`

### WebSocket transport

- [Relay WS handshake](https://github.com/benyamin218118/tunnel/blob/main/tunnel.go): `tunnel.go`
- [Gate WS handshake](https://github.com/benyamin218118/tunnel/blob/main/tunnel.go): `tunnel.go`
- **Optional CDN**

### UDP forwarding

- **UDP client**
- [Connection map](https://github.com/benyamin218118/tunnel/blob/main/models.go): `models.go`
- [UDP marker detection](https://github.com/benyamin218118/tunnel/blob/main/tunnel.go): `tunnel.go`
- [UDP response forwarding](https://github.com/benyamin218118/tunnel/blob/main/tunnel.go): `tunnel.go`

### Other components

- **Operator**

## Connections

- Operator → CLI configuration: sets flags
- CLI configuration → Tunnel runtime: creates runtime
- Tunnel runtime → TCP/UDP listeners: opens listeners
- TCP/UDP listeners → Client: accepts TCP
- TCP/UDP listeners → UDP client: accepts UDP
- Client → Relay accept: connects
- Relay accept → Gate accept: dials gate
- Gate accept → Destination service: dials destination
- Relay accept → Bidirectional copy: copies bytes
- Gate accept → Bidirectional copy: copies bytes
- Bidirectional copy → Destination service: forwards TCP
- Relay accept → Relay WS handshake: starts handshake
- Relay WS handshake → Optional CDN: may traverse
- Optional CDN → Gate WS handshake: forwards upgrade
- Gate WS handshake → Gate accept: accepts upgrade
- UDP client → Relay accept: sends datagram
- Relay accept → Connection map: looks up or stores
- Relay accept → Gate accept: sends marker and data
- Gate accept → UDP marker detection: detects marker
- UDP marker detection → Destination service: dials UDP
- Gate accept → UDP response forwarding: returns datagrams
- UDP response forwarding → UDP client: writes response