How arturoeanton/go-grpc-tunnel works
Project Type and Purpose
• Type: Open-source CLI tool for reverse TCP tunneling using Go and gRPC.
• Purpose: Expose services (e.g., a Firebird database) behind NAT/firewall by creating a secure, multiplexed, bidirectional tunnel between a public server and a local agent.
File-Structure Analysis
• Top-level:
• cmd/server – entry point for the public tunnel server
• cmd/client – entry point for the local tunnel agent
• proto – Protocol Buffers definitions and generated gRPC stubs
• certs – TLS certificates for securing gRPC channel
• run_server.sh/.ps1 & run_client.sh/.ps1 – scripts to configure and launch components
• Build & Configuration:
• go.mod/go.sum for dependency management
• Shell/PowerShell scripts for environment variables (tokens, ports, certificate paths)
Core Architecture (from README)
• Two main components:
a. Tunnel Server
• Listens for gRPC agent connections (with TLS + token auth)
• Listens for incoming TCP connections from external clients
• Multiplexes data over a bidirectional gRPC stream
b. Tunnel Agent (Client)
• Connects outward to the tunnel server’s gRPC endpoint
• Authenticates using shared token and TLS
• Forwards instructions to open local TCP connections to the target service (e.g., Firebird)
Main Components
• External Client (e.g., Firebird-client app)
• Tunnel Server (public)
• gRPC/TLS Channel (Internet)
• Tunnel Agent (local)
• Target Service (e.g., Firebird DB on localhost:3050)
Relationships and Data Flow
• Step 1: External Client → TCP → Tunnel Server (External Port, e.g., :8080)
• Step 2: Tunnel Server ↔ Bidirectional gRPC/TLS Stream → Tunnel Agent (port :50051)
• Step 3: Tunnel Agent → TCP → Target Service (localhost:3050)
• Multiplexing: single gRPC stream carries frames for multiple concurrent TCP connections, distinguished by ConnectionId
Architectural Patterns & Principles
• Client-Server separation: clear split between public endpoint (server) and private network proxy (agent)
• Bidirectional streaming RPC: implements a lightweight multiplexing layer on top of gRPC
• Token-based authentication + TLS for secure channel
• Environment-driven configuration to keep binaries generic and reusable
Technologies & Frameworks
• Go language (cmd/server/main.go, cmd/client/main.go)
• gRPC + Protocol Buffers (proto/tunnel.proto)
• TLS certificates (certs/server.crt, certs/server.key)
• Shell/PowerShell scripts for automated runs
Essential Details
• Authentication step on gRPC connection setup
• Port numbers (50051 for gRPC, 8080 for external TCP, 3050 for local DB)
• Call out that traffic is encrypted only between server and agent
• Environment variables used by run scripts for clarity