github.com/XTLS/Xray-core

Xray-core is primarily designed as a standalone proxy application rather than a Go library, which becomes apparent when trying to integrate it programmatically. The documentation focuses heavily on JSON configuration files for the CLI tool, with minimal guidance on using the Go APIs directly. You'll spend significant time reading source code to understand how to instantiate and configure components like transports, protocols, and routing.

Error messages can be cryptic when misconfiguring protocols or transport settings, often requiring you to trace through internal packages to identify the root cause. The codebase is well-structured but lacks the typical Go library conventions like comprehensive godoc comments and clear package-level documentation. Community support exists primarily in Chinese-language forums and Telegram groups, making it challenging for English-only developers to get quick answers.

That said, once you overcome the initial learning curve, the framework is extremely flexible and performant. The protocol implementations are solid, and the modular architecture allows fine-grained control. If you need to embed advanced proxy capabilities in your Go application and have time to invest, it delivers. Just be prepared for significant upfront research.

Xray-core is primarily designed as a standalone binary rather than a library, which creates friction when embedding it programmatically. The configuration is JSON-based and deeply nested, requiring extensive familiarity with proxy protocols. While the core functionality is robust, there's minimal Go API documentation—you're largely expected to read source code to understand how to integrate it into your application.

Error messages often surface as generic connection failures without clear context about what configuration went wrong. The type system uses many interface{} parameters and heavy reflection, which limits compile-time safety and IDE assistance. Configuration validation happens at runtime, meaning misconfigurations only surface when the proxy attempts to operate.

For simple use cases where you're just running the binary with config files, it works well. However, if you need programmatic control, expect to invest significant time understanding internal structures. Migration between versions can break configs without clear deprecation warnings.

Xray-core is a sophisticated proxy framework with impressive protocol support and performance characteristics. The core runtime is fast and handles high connection volumes well once properly configured. However, integrating it into production Go applications requires significant effort due to its design as a standalone binary rather than a library-first approach.

The configuration system is JSON-based and deeply nested, making it error-prone when constructing programmatically. Error messages can be cryptic, and the library doesn't always provide structured errors that are easy to handle gracefully. Resource cleanup requires careful management - connection pools aren't always transparent, and improper shutdown can leak goroutines. Hot-reloading configuration without dropping connections is possible but not straightforward.

Observability is a pain point. While there are logging hooks, integrating with structured logging frameworks requires custom adapters. Metrics and tracing instrumentation aren't built-in, so you'll need to wrap components yourself. Timeout behavior varies by protocol and isn't always documented clearly. The codebase changes frequently, and minor version updates have introduced breaking configuration changes that caught us off-guard in production.