masterking32/masterdnsvpn

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