How loreneteval/xray-core-python works
Project Type and Purpose
• This is a language‐binding library rather than a standalone service. Specifically, it exposes the Xray-core (Go) networking engine to Python via a C++ wrapper using pybind11.
• Users install the package with pip, triggering a build pipeline that compiles the Go core, wraps it in a C++ extension, and produces a Python importable module (xray).
Architectural Overview
• At a high level the system has two phases:
a. Build‐time pipeline: orchestrated by CMake+setup.py+gobuild, which
• Invokes Go toolchain to compile the Xray-core (xray-go directory) into a static library or object files.
• Invokes CMake to find pybind11 headers and compile src/xray.cpp into a Python extension module (xray.so / xray.pyd), linking against the Go artifacts.
b. Runtime interaction:
• Python code (import xray) calls into the pybind11 extension.
• The extension invokes C++ glue code (in src/xray.cpp) which in turn calls exported Go functions.
• The Go core executes networking logic and returns results back to Python.
Main Components
• Python Layer
• xray/__init__.py: Python package exposing the extension.
• User API: startFromJSON(...), queryStats(...).
• C++/pybind11 Wrapper
• src/xray.cpp: defines Python-callable functions, binds to Go functions.
• pybind11/: vendored pybind11 library and config for building.
• Go Core
• xray-go/: full Xray-core source with its subpackages (app, common, proxy, transport, etc.).
• Exposes C-callable functions via cgo or a small C wrapper.
• Build System
• CMakeLists.txt (root) and gobuild/: coordinates:
– Discovery of Go toolchain.
– Compilation of Go code to static libs.
– Compilation of C++ extension with pybind11.
• setup.py / pyproject.toml: Python packaging metadata, invokes CMake during pip install.
• External Tools
• Go compiler
• CMake
• GNU C++ toolchain
• pip / setuptools
Relationships and Data Flow
[pip install] → [setup.py / pyproject.toml] → [CMake] → {Go compiler → Xray-core lib} + {C++ compiler + pybind11 → Python extension}
[Python app] → [pybind11 extension (xray.so)] → [C++ glue (xray.cpp)] → [Go core functions] → [return results back up]
Key Architectural Patterns
• Layered binding pattern: Python → C++ → Go
• Decoupled build stages: Go build and C++ build are separate targets in CMake.
• Vendored library structure: pybind11 lives inside project, isolated from system.
Essential Elements
• Build orchestration (pip → setup → CMake → compilers).
• Python API module and exposed methods.
• C++ wrapper code (pybind11).
• Go core library.