How sagernet/sing works
Main Components
a. Common Utilities Layer – The “common” directory holds a wide range of reusable packages such as:
• Atomic operations, binary encoding, and buffer management ("atomic", "binary", "buf", "bufio").
• Network and system-specific functions (“network”, “control”, “tls”, “debug”).
• Various utility functions (e.g. “json”, “domain”, “cache”, “metadata”, “observable”).
b. Protocol Layer – The “protocol” directory provides implementations for:
• HTTP-based communication (“protocol/http” – handling address resolution, client connections, handshake, etc.).
• SOCKS protocol support (“protocol/socks” and its submodules for SOCKS4 and SOCKS5, including specialized handshake and packet handling functions).
c. Service/API Layer – In the “service” directory, utilities and service managers are found for:
• File management (“service/filemanager”).
• A “pause” functionality and broader registry services.
d. Additional Utilities – The “contrab” directory supplies auxiliary but essential components:
• A freelru caching mechanism and maphash implementations that are valuable for performance-critical caching and hashing operations.
Relationships and Interactions
• The common utilities serve as the foundation for nearly every other part of the system. They are used by both the protocol and service layers.
• The protocol layer abstracts and implements networking logic. It leverages common packages (like those found in “network”, “tls”, “bufio”, etc.) to handle the intricacies of HTTP and SOCKS communication.
• The service layer builds upon the protocol layer and the common utilities to provide higher-level service orchestration (for example, handling file management and pause/resume functionality).
• The additional utilities in “contrab” (like freelru) are cross-cutting components that integrate into different parts of the system (for caching results in protocols or services).
Architectural Patterns and Design Principles
• Modular/Layered Approach – The clear separation into “common,” “protocol,” “service,” and “contrab” reflects a layered design, which is typical in large-scale systems. Each layer has a set of well-defined responsibilities.
• Reusability – The “common” directory indicates a strong focus on extracting reusable components that can be shared across different parts of the project.
• Abstraction and Separation of Concerns – The separation between protocol implementations and service orchestration suggests that each module is designed to handle specific tasks, making the overall system easier to maintain and extend.
• Platform-specific adaptations are evident (for example, different source files for Unix/Windows in “bufio,” “control,” “ntp,” etc.), which reflects a design that takes into account diverse operating environments.
Relevant Technologies and Libraries
• Go Modules (indicated by go.mod and go.sum) suggest dependency management via Go’s native tooling.
• The project uses go-specific linters and workflows (see “.golangci.yml” and GitHub Actions workflows in “.github/workflows”), highlighting best practices for code quality and CI/CD.
• The existence of Makefile indicates build automation for running tests and linters.
Final Remarks
• The goal is to provide a visual map that makes it clear how foundational utilities, protocol implementations, and higher-level services interact. This helps in understanding the separation of concerns, ease of testing individual parts, and the potential for future extensions.