How jpillora/chisel works
Project Overview and Purpose
• Chisel is a tunneling tool that creates secure TCP/UDP tunnels over HTTP using SSH for encryption and authentication.
• It is distributed as a single executable that contains both client and server capabilities.
• The README emphasizes features such as encrypted and authenticated connections, reverse tunneling, SOCKS5 support, and additional proxy assistance.
File Structure
• Top-level directories include:
• client: Contains client-side logic (client.go, client_connect.go, client_test.go)
• server: Contains server-side logic (server.go, server_handler.go, server_listen.go)
• share: Holds shared packages and utilities. Subdirectories here include:
▪ ccrypto: Cryptography routines (key generation, deterministic randomness, key helpers)
▪ cio: IO utilities like logging, pipe management, stdio connections (important for SSH and ProxyCommand)
▪ cnet: Networking utilities for handling TCP/UDP connections, WebSockets, HTTP server helpers, and connection stats
▪ cos: Common functions including pprof and signal handling
▪ settings: Handles configuration from environments, files, and remote settings (also contains authentication setup)
▪ tunnel: Contains tunnel logic (tunnel creation, both input and output handling, including UDP and SSH tunnels)
• test: Contains benchmarks and end-to-end tests, showing that performance and network interactions are important.
• example: Provides example configuration files (e.g., users.json, Flyfile, fly.toml) that may also be highlighted.
Main Components
a. Client Component:
• Represented by the “client” directory and its related files.
• Responsible for initiating connections to the server, maintaining tunnels, and handling local port forwarding, reverse tunnels, and SOCKS connections.
• Uses shared libraries for network connections (cnet), tunnel management (tunnel), and cryptography (ccrypto).
b. Server Component:
• Represented by the “server” directory.
• Listens for incoming connections, establishes tunnels, and manages HTTP and SSH-handled traffic.
• Implements authentication (via settings and users files) and also supports reverse proxy and SOCKS5 modes.
• Uses shared libraries similar to the client for core networking and cryptographic functions.
c. Shared Libraries/Modules:
• “share” acts as the library of common functions, covering:
• Encryption & key management (ccrypto)
• I/O handling and logging (cio)
• Network connections and WebSocket support (cnet)
• Signal handling and common utilities (cos)
• Tunnel setup and management (tunnel)
• Configuration and settings management (settings)
• These should be depicted as “supporting modules” that both client and server rely on.
d. External Interfaces and Flows:
• How the client connects to the server over HTTP/HTTPS and how the tunnel transport uses SSH under the hood.
• External networks: firewalls, destination endpoints (e.g., reverse proxy target, SOCKS5 connections), and, optionally, integration with Docker deployments (as hinted by .github and Dockerfile).
Relationships and Interactions
• Within both components, include internal flows such as:
• From client: CLI → tunnel configuration → network connection setup → encrypted SSH handshake.
• From server: Incoming network requests → authentication (using users.json or inline --auth) → session management → tunnel routing.
• Bidirectional communication for reverse tunneling (server listening and client proxying connections).
Architectural Patterns and Design Principles
• Single-executable design that encapsulates both client and server logic.
• A modular approach (separation of concerns) is evident in the distribution of common functionality into the “share” directory.
• Use of Go interfaces and dependency injection (common in Go projects) to facilitate testing (see extensive testing directories) and clear responsibilities.
• Emphasis on performance and concurrency (supported by benchmark tests and the use of efficient Go libraries).
Relevant Technologies and Frameworks
• Go Programming Language (with its standard libraries for networking, crypto, etc.)
• SSH protocol (for encryption and authentication)
• HTTP/HTTPS for tunnel transport
• WebSockets as an alternative connection mechanism when traversing proxies
• Docker (as indicated by Dockerfile and CI workflows)