github.com/SagerNet/sing-box

sing-box is a universal proxy platform with extensive protocol support (VLESS, Shadowsocks, Trojan, etc.), but using it as a Go library presents significant DX challenges. The configuration structure is complex and deeply nested, requiring extensive knowledge of proxy protocols. While the JSON schema is well-defined, translating that to Go structs involves navigating through option packages with limited inline documentation.

The type system is comprehensive but can be overwhelming - the `option` package contains dozens of configuration types with interdependencies that aren't immediately obvious. Error messages are often generic, making debugging configuration issues time-consuming. IDE autocompletion helps navigate the types, but without understanding the underlying protocols, you'll spend considerable time in the source code or referencing the JSON configuration examples.

Migration between versions can be breaking, particularly around configuration structures. The project moves quickly with protocol updates, which is good for feature support but challenging for stability. Documentation focuses heavily on JSON configuration for the CLI tool rather than programmatic Go usage patterns.

sing-box is a comprehensive universal proxy platform supporting multiple protocols (VLESS, Shadowsocks, Trojan, etc.). Day-to-day usage reveals a complex configuration system that requires deep understanding to secure properly. The JSON/YAML config files expose many options, but default configurations often lack secure-by-default principles - you must explicitly enable TLS verification, configure proper cipher suites, and implement authentication layers yourself.

Error handling is inconsistent across modules. Some failures leak configuration details or network topology information in logs, which is problematic in multi-tenant environments. The authentication system is protocol-dependent with varying quality - some transports have robust built-in auth while others rely entirely on your configuration. Input validation on inbound connections is present but occasionally permissive, requiring additional filtering layers for production deployments.

Dependency management is a mixed bag. The project pulls in numerous crypto and networking libraries, some niche. CVE response has been reactive rather than proactive, with security patches sometimes taking weeks. TLS defaults have improved in recent versions but still require manual hardening for compliance-sensitive deployments.

sing-box is a universal proxy platform with extensive protocol support, but its DX leaves much to be desired. The configuration-driven architecture means you'll spend most of your time wrestling with JSON/YAML configs rather than enjoying clean Go APIs. The library can be embedded, but documentation focuses heavily on CLI usage, making programmatic integration require significant source code diving.

Type definitions exist but the config structures are deeply nested with many optional fields, making it difficult to understand what's required versus optional without trial and error. Error messages often reference internal components without context about which part of your configuration is problematic. The codebase uses interface-heavy patterns that make tracing execution paths non-trivial.

Migration between versions can be painful as config schema changes aren't always clearly documented. The project moves fast with frequent breaking changes in minor versions. When it works, it's incredibly powerful for building VPN/proxy solutions, but expect a steep learning curve and debugging sessions.