# masterking32/masterdnsvpn architecture

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

- Interactive diagram: https://gitdiagram.com/masterking32/masterdnsvpn
- Repository: https://github.com/masterking32/masterdnsvpn

## Overview

#### Purpose and Executables
MasterDnsVPN is a Go DNS tunnel that carries TCP traffic in DNS queries/responses, exposing a local SOCKS4/5 proxy or fixed TCP forwarding client-side. It uses custom framing, encryption, ARQ, resolver multipath, and duplication to tolerate lossy/censored DNS paths.

Entry points:
- Client process: `cmd/client/main.go`
- Authoritative DNS tunnel server: `cmd/server/main.go`
- Runtime configuration: `internal/config/client.go`, `internal/config/server.go`

#### Client Ingress and Stream Lifecycle
The client accepts local application traffic through TCP/SOCKS listeners, creates multiplexed tunnel streams, and returns ordered tunnel data to the local connection. Optional local DNS can route DNS requests through the established tunnel.

Key boundaries:
- Local proxy protocol and connection handling: `internal/client/socks_manager.go`, `internal/client/tcp_listener.go`
- Logical session and stream state: `internal/client/session.go`, `internal/client/stream_client.go`
- Optional local DNS listener/cache-facing path: `internal/client/dns_listener.go`, `internal/client/handlers/dns_handlers.go`

#### Client Tunnel Transport Runtime
Client workers transform stream/control payloads into tunnel packets, dispatch DNS requests, and process responses asynchronously. The resolver balancer selects among configured public resolvers, duplicates critical packets, tracks health/latency/loss, and supports stream-level failover. MTU probing establishes practical payload limits per resolver.

Core runtime:
- Dispatch and asynchronous I/O orchestration: `internal/client/dispatcher.go`, `internal/client/async_runtime.go`, `internal/client/tunnel_runtime.go`
- Resolver balancing and probing: `internal/client/balancer.go`, `internal/client/mtu.go`, `internal/client/ping_manager.go`
- Packet-type handlers and packed controls: `internal/client/handlers/registry.go`, `internal/client/handlers/packed_control_handler.go`

#### Protocol, Reliability, and Security Boundary
Tunnel content is represented by a custom VPN protocol, then encoded into DNS-compatible labels. ARQ supplies sequencing, ACK/NACK, retransmission, reordering, TTL, and terminal-stream behavior; fragmentation stores support payloads exceeding one DNS message. Compression and encryption are negotiated/configured around this transport.

Protocol layers:
- Wire packet construction, parsing, and packing: `internal/vpnproto/builder.go`, `internal/vpnproto/parser.go`, `internal/vpnproto/packing.go`
- ARQ reliability state machine: `internal/arq/arq.go`
- Encryption and codecs: `internal/security/codec.go`, `internal/security/encryption_key.go`, `internal/basecodec/codec.go`
- Fragment assembly: `internal/fragmentstore/store.go`

#### Server DNS Front Door and Session Runtime
The server binds DNS UDP (and container deployment exposes TCP/UDP 53), parses incoming DNS tunnel queries, validates domain/session/cookie state, and routes ordering-sensitive work through deferred session processing. Session cleanup and invalid-cookie tracking protect lifecycle and resource boundaries.

Server stages:
- UDP socket, ingress queue, and runtime: `internal/udpserver/server.go`, `internal/udpserver/server_ingress.go`, `internal/udpserver/server_runtime.go`
- Session creation, lookup, and cleanup: `internal/udpserver/session.go`, `internal/udpserver/server_session.go`, `internal/udpserver/session_cleanup_test.go`
- Deferred/setup processing and DNS tunnel assembly: `internal/udpserver/deferred_session.go`, `internal/udpserver/dns_tunnel.go`

#### Egress and DNS Services
For SOCKS mode, the server establishes outbound target connections from client stream requests; it may instead chain through an external SOCKS5 upstream. Tunnelled DNS requests are separately forwarded to configured recursive DNS upstreams, deduplicated in-flight, cached, and returned through DNS responses.

Relevant paths:
- TCP stream egress and SOCKS upstream: `internal/udpserver/stream_server.go`, `internal/udpserver/socks5_upstream.go`
- DNS parse/response transport: `internal/dnsparser/parser.go`, `internal/dnsparser/response.go`
- DNS cache and request coalescing: `internal/dnscache/store.go`, `internal/inflight/manager.go`

#### Deployment and External Dependencies
The material runtime is Go 1.24+; networking is primarily local TCP plus DNS over UDP, with DNS TCP exposed in Docker deployments. External services are public DNS resolvers, delegated authoritative DNS for the tunnel domain, optional DNS upstream resolvers, and optional external SOCKS5 egress.

Deployment artifacts:
- Container image and startup behavior: `docker/Dockerfile`, `docker/docker-entrypoint.sh`, `docker/docker-compose.yml`
- Sample operational configs: `client_config.toml.simple`, `server_config.toml.simple`, `client_resolvers.simple`

Main entry points: [`internal/udpserver/deferred_session.go`](https://github.com/masterking32/masterdnsvpn/blob/main/internal/udpserver/deferred_session.go) (Server session processor), [`internal/client/session.go`](https://github.com/masterking32/masterdnsvpn/blob/main/internal/client/session.go) (Client sessions and streams), [`internal/client/socks_manager.go`](https://github.com/masterking32/masterdnsvpn/blob/main/internal/client/socks_manager.go) (SOCKS and TCP ingress), [`internal/udpserver/server_runtime.go`](https://github.com/masterking32/masterdnsvpn/blob/main/internal/udpserver/server_runtime.go) (DNS ingress runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client runtime"]
  node_client_main["Client process<br/>Go entry point<br/>[main.go]"]
  node_client_config["Client configuration<br/>runtime config<br/>[client.go]"]
  node_local_apps(("Local applications<br/>TCP/SOCKS clients"))
  node_client_ingress["SOCKS and TCP ingress<br/>local proxy listeners<br/>[socks_manager.go]"]
  node_client_session["Client sessions and streams<br/>multiplexer<br/>[session.go]"]
  node_client_dns["Local DNS tunnel service<br/>DNS listener<br/>[dns_listener.go]"]
  node_client_runtime["Client transport runtime<br/>async dispatcher<br/>[dispatcher.go]"]
  node_resolver_balancer["Resolver balancer<br/>multipath controller<br/>[balancer.go]"]
end

subgraph group_transport["Tunnel protocol"]
  node_protocol["VPN packet codec<br/>wire protocol<br/>[builder.go]"]
  node_reliability["ARQ and fragments<br/>reliability layer<br/>[arq.go]"]
  node_security["Encryption and codecs<br/>payload protection<br/>[codec.go]"]
end

subgraph group_server["Server runtime"]
  node_server_main["Server process<br/>Go entry point<br/>[main.go]"]
  node_server_config["Server configuration<br/>runtime config<br/>[server.go]"]
  node_dns_frontdoor["DNS ingress runtime<br/>UDP server<br/>[server_runtime.go]"]
  node_server_sessions["Server session processor<br/>session lifecycle"]
  node_stream_egress["TCP stream egress<br/>target connector<br/>[stream_server.go]"]
  node_dns_service["Tunnel DNS service<br/>recursive DNS proxy<br/>[store.go]"]
  node_container{{"Docker deployment<br/>container runtime"}}
end

subgraph group_external["Networks and egress"]
  node_public_resolvers(("Public DNS resolvers<br/>external DNS"))
  node_authoritative_dns(("Delegated tunnel domain<br/>authoritative DNS route"))
  node_targets(("Target TCP services<br/>external network"))
  node_dns_upstreams(("Recursive DNS upstreams<br/>external DNS"))
  node_socks_upstream(("External SOCKS5<br/>optional egress"))
end

node_client_config -->|"configures"| node_client_main
node_client_main -->|"starts"| node_client_ingress
node_client_main -->|"starts"| node_client_runtime
node_local_apps -->|"TCP/SOCKS"| node_client_ingress
node_client_ingress -->|"opens streams"| node_client_session
node_client_session -->|"payloads and controls"| node_client_runtime
node_client_dns -->|"tunnelled DNS"| node_client_session
node_client_runtime -->|"reliable packets"| node_reliability
node_reliability -->|"payload frames"| node_security
node_security -->|"protected content"| node_protocol
node_protocol -->|"DNS queries"| node_resolver_balancer
node_resolver_balancer -->|"multipath DNS"| node_public_resolvers
node_public_resolvers -->|"delegated queries"| node_authoritative_dns
node_authoritative_dns -->|"DNS UDP/TCP"| node_dns_frontdoor
node_container -->|"runs and exposes"| node_dns_frontdoor
node_server_config -->|"configures"| node_server_main
node_server_main -->|"starts"| node_dns_frontdoor
node_dns_frontdoor -->|"tunnel queries"| node_server_sessions
node_server_sessions -->|"decode/encode"| node_protocol
node_server_sessions -->|"ARQ state"| node_reliability
node_server_sessions -->|"stream requests"| node_stream_egress
node_stream_egress -->|"outbound TCP"| node_targets
node_stream_egress -.->|"optional proxy chain"| node_socks_upstream
node_server_sessions -->|"DNS requests"| node_dns_service
node_dns_service -->|"recursive queries"| node_dns_upstreams
node_client_session -->|"ordered return data"| node_client_ingress

click node_client_main "https://github.com/masterking32/masterdnsvpn/blob/main/cmd/client/main.go"
click node_client_config "https://github.com/masterking32/masterdnsvpn/blob/main/internal/config/client.go"
click node_client_ingress "https://github.com/masterking32/masterdnsvpn/blob/main/internal/client/socks_manager.go"
click node_client_session "https://github.com/masterking32/masterdnsvpn/blob/main/internal/client/session.go"
click node_client_dns "https://github.com/masterking32/masterdnsvpn/blob/main/internal/client/dns_listener.go"
click node_client_runtime "https://github.com/masterking32/masterdnsvpn/blob/main/internal/client/dispatcher.go"
click node_resolver_balancer "https://github.com/masterking32/masterdnsvpn/blob/main/internal/client/balancer.go"
click node_protocol "https://github.com/masterking32/masterdnsvpn/blob/main/internal/vpnproto/builder.go"
click node_reliability "https://github.com/masterking32/masterdnsvpn/blob/main/internal/arq/arq.go"
click node_security "https://github.com/masterking32/masterdnsvpn/blob/main/internal/security/codec.go"
click node_server_main "https://github.com/masterking32/masterdnsvpn/blob/main/cmd/server/main.go"
click node_server_config "https://github.com/masterking32/masterdnsvpn/blob/main/internal/config/server.go"
click node_dns_frontdoor "https://github.com/masterking32/masterdnsvpn/blob/main/internal/udpserver/server_runtime.go"
click node_server_sessions "https://github.com/masterking32/masterdnsvpn/blob/main/internal/udpserver/deferred_session.go"
click node_stream_egress "https://github.com/masterking32/masterdnsvpn/blob/main/internal/udpserver/stream_server.go"
click node_dns_service "https://github.com/masterking32/masterdnsvpn/blob/main/internal/dnscache/store.go"
click node_container "https://github.com/masterking32/masterdnsvpn/blob/main/docker/Dockerfile"

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_client_main,node_client_config,node_local_apps,node_client_ingress,node_client_session,node_client_dns,node_client_runtime,node_resolver_balancer toneBlue
class node_protocol,node_reliability,node_security toneAmber
class node_server_main,node_server_config,node_dns_frontdoor,node_server_sessions,node_stream_egress,node_dns_service,node_container toneMint
class node_public_resolvers,node_authoritative_dns,node_targets,node_dns_upstreams,node_socks_upstream toneRose
```

## Components

### Client runtime

- [Client process](https://github.com/masterking32/masterdnsvpn/blob/main/cmd/client/main.go): Go entry point · `cmd/client/main.go`
- [Client configuration](https://github.com/masterking32/masterdnsvpn/blob/main/internal/config/client.go): runtime config · `internal/config/client.go`
- **Local applications**: TCP/SOCKS clients
- [SOCKS and TCP ingress](https://github.com/masterking32/masterdnsvpn/blob/main/internal/client/socks_manager.go): local proxy listeners · Accepts local streams and maps them to tunnel streams. · `internal/client/socks_manager.go`
- [Client sessions and streams](https://github.com/masterking32/masterdnsvpn/blob/main/internal/client/session.go): multiplexer · `internal/client/session.go`
- [Local DNS tunnel service](https://github.com/masterking32/masterdnsvpn/blob/main/internal/client/dns_listener.go): DNS listener · `internal/client/dns_listener.go`
- [Client transport runtime](https://github.com/masterking32/masterdnsvpn/blob/main/internal/client/dispatcher.go): async dispatcher · Dispatches tunnel work and handles asynchronous DNS responses. · `internal/client/dispatcher.go`
- [Resolver balancer](https://github.com/masterking32/masterdnsvpn/blob/main/internal/client/balancer.go): multipath controller · Selects, probes, duplicates, and fails over public resolvers. · `internal/client/balancer.go`

### Tunnel protocol

- [VPN packet codec](https://github.com/masterking32/masterdnsvpn/blob/main/internal/vpnproto/builder.go): wire protocol · Builds, parses, packs, and DNS-label-encodes tunnel packets. · `internal/vpnproto/builder.go`
- [ARQ and fragments](https://github.com/masterking32/masterdnsvpn/blob/main/internal/arq/arq.go): reliability layer · Provides ordering, ACK/NACK, retries, TTL, and reassembly. · `internal/arq/arq.go`
- [Encryption and codecs](https://github.com/masterking32/masterdnsvpn/blob/main/internal/security/codec.go): payload protection · `internal/security/codec.go`

### Server runtime

- [Server process](https://github.com/masterking32/masterdnsvpn/blob/main/cmd/server/main.go): Go entry point · `cmd/server/main.go`
- [Server configuration](https://github.com/masterking32/masterdnsvpn/blob/main/internal/config/server.go): runtime config · `internal/config/server.go`
- [DNS ingress runtime](https://github.com/masterking32/masterdnsvpn/blob/main/internal/udpserver/server_runtime.go): UDP server · Receives DNS queries and queues tunnel ingress. · `internal/udpserver/server_runtime.go`
- [Server session processor](https://github.com/masterking32/masterdnsvpn/blob/main/internal/udpserver/deferred_session.go): session lifecycle · Validates cookies and routes ordering-sensitive deferred work. · `internal/udpserver/deferred_session.go`
- [TCP stream egress](https://github.com/masterking32/masterdnsvpn/blob/main/internal/udpserver/stream_server.go): target connector · Establishes requested target streams or uses SOCKS5 upstream. · `internal/udpserver/stream_server.go`
- [Tunnel DNS service](https://github.com/masterking32/masterdnsvpn/blob/main/internal/dnscache/store.go): recursive DNS proxy · Coalesces in-flight requests, caches answers, and returns DNS responses. · `internal/dnscache/store.go`
- [Docker deployment](https://github.com/masterking32/masterdnsvpn/blob/main/docker/Dockerfile): container runtime · Exposes DNS over UDP and TCP port 53. · `docker/Dockerfile`

### Networks and egress

- **Public DNS resolvers**: external DNS
- **Delegated tunnel domain**: authoritative DNS route
- **Target TCP services**: external network
- **Recursive DNS upstreams**: external DNS
- **External SOCKS5**: optional egress

## Connections

- Client configuration → Client process: configures
- Client process → SOCKS and TCP ingress: starts
- Client process → Client transport runtime: starts
- Local applications → SOCKS and TCP ingress: TCP/SOCKS
- SOCKS and TCP ingress → Client sessions and streams: opens streams
- Client sessions and streams → Client transport runtime: payloads and controls
- Local DNS tunnel service → Client sessions and streams: tunnelled DNS
- Client transport runtime → ARQ and fragments: reliable packets
- ARQ and fragments → Encryption and codecs: payload frames
- Encryption and codecs → VPN packet codec: protected content
- VPN packet codec → Resolver balancer: DNS queries
- Resolver balancer → Public DNS resolvers: multipath DNS
- Public DNS resolvers → Delegated tunnel domain: delegated queries
- Delegated tunnel domain → DNS ingress runtime: DNS UDP/TCP
- Docker deployment → DNS ingress runtime: runs and exposes
- Server configuration → Server process: configures
- Server process → DNS ingress runtime: starts
- DNS ingress runtime → Server session processor: tunnel queries
- Server session processor → VPN packet codec: decode/encode
- Server session processor → ARQ and fragments: ARQ state
- Server session processor → TCP stream egress: stream requests
- TCP stream egress → Target TCP services: outbound TCP
- TCP stream egress → External SOCKS5: optional proxy chain
- Server session processor → Tunnel DNS service: DNS requests
- Tunnel DNS service → Recursive DNS upstreams: recursive queries
- Client sessions and streams → SOCKS and TCP ingress: ordered return data