3344/3x-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 99 Wiki Activity

docs: add comments for all functions

Browse Source
This commit is contained in:
mhsanaei
2025-09-20 09:35:50 +02:00
parent f60682a6b7
commit 6ced549dea
63 changed files with 624 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
xray/api.go
View File

@@ -1,3 +1,6 @@
// Package xray provides integration with the Xray proxy core.
// It includes API client functionality, configuration management, traffic monitoring,
// and process control for Xray instances.
package xray
import (
@@ -25,6 +28,7 @@ import (
"google.golang.org/grpc/credentials/insecure"
)
// XrayAPI is a gRPC client for managing Xray core configuration, inbounds, outbounds, and statistics.
type XrayAPI struct {
HandlerServiceClient *command.HandlerServiceClient
StatsServiceClient *statsService.StatsServiceClient
@@ -32,6 +36,7 @@ type XrayAPI struct {
isConnected bool
}
// Init connects to the Xray API server and initializes handler and stats service clients.
func (x *XrayAPI) Init(apiPort int) error {
if apiPort <= 0 || apiPort > math.MaxUint16 {
return fmt.Errorf("invalid Xray API port: %d", apiPort)
@@ -55,6 +60,7 @@ func (x *XrayAPI) Init(apiPort int) error {
return nil
}
// Close closes the gRPC connection and resets the XrayAPI client state.
func (x *XrayAPI) Close() {
if x.grpcClient != nil {
x.grpcClient.Close()
@@ -64,6 +70,7 @@ func (x *XrayAPI) Close() {
x.isConnected = false
}
// AddInbound adds a new inbound configuration to the Xray core via gRPC.
func (x *XrayAPI) AddInbound(inbound []byte) error {
client := *x.HandlerServiceClient
@@ -85,6 +92,7 @@ func (x *XrayAPI) AddInbound(inbound []byte) error {
return err
}
// DelInbound removes an inbound configuration from the Xray core by tag.
func (x *XrayAPI) DelInbound(tag string) error {
client := *x.HandlerServiceClient
_, err := client.RemoveInbound(context.Background(), &command.RemoveInboundRequest{
@@ -93,6 +101,7 @@ func (x *XrayAPI) DelInbound(tag string) error {
return err
}
// AddUser adds a user to an inbound in the Xray core using the specified protocol and user data.
func (x *XrayAPI) AddUser(Protocol string, inboundTag string, user map[string]any) error {
var account *serial.TypedMessage
switch Protocol {
@@ -153,6 +162,7 @@ func (x *XrayAPI) AddUser(Protocol string, inboundTag string, user map[string]an
return err
}
// RemoveUser removes a user from an inbound in the Xray core by email.
func (x *XrayAPI) RemoveUser(inboundTag, email string) error {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
@@ -171,6 +181,7 @@ func (x *XrayAPI) RemoveUser(inboundTag, email string) error {
return nil
}
// GetTraffic queries traffic statistics from the Xray core, optionally resetting counters.
func (x *XrayAPI) GetTraffic(reset bool) ([]*Traffic, []*ClientTraffic, error) {
if x.grpcClient == nil {
return nil, nil, common.NewError("xray api is not initialized")
@@ -205,6 +216,7 @@ func (x *XrayAPI) GetTraffic(reset bool) ([]*Traffic, []*ClientTraffic, error) {
return mapToSlice(tagTrafficMap), mapToSlice(emailTrafficMap), nil
}
// processTraffic aggregates a traffic stat into trafficMap using regex matches and value.
func processTraffic(matches []string, value int64, trafficMap map[string]*Traffic) {
isInbound := matches[1] == "inbound"
tag := matches[2]
@@ -231,6 +243,7 @@ func processTraffic(matches []string, value int64, trafficMap map[string]*Traffi
}
}
// processClientTraffic updates clientTrafficMap with upload/download values for a client email.
func processClientTraffic(matches []string, value int64, clientTrafficMap map[string]*ClientTraffic) {
email := matches[1]
isDown := matches[2] == "downlink"
@@ -248,6 +261,7 @@ func processClientTraffic(matches []string, value int64, clientTrafficMap map[st
}
}
// mapToSlice converts a map of pointers to a slice of pointers.
func mapToSlice[T any](m map[string]*T) []*T {
result := make([]*T, 0, len(m))
for _, v := range m {

2
xray/client_traffic.go
View File

@@ -1,5 +1,7 @@
package xray
// ClientTraffic represents traffic statistics and limits for a specific client.
// It tracks upload/download usage, expiry times, and online status for inbound clients.
type ClientTraffic struct {
Id int `json:"id" form:"id" gorm:"primaryKey;autoIncrement"`
InboundId int `json:"inboundId" form:"inboundId"`

3
xray/config.go
View File

@@ -6,6 +6,8 @@ import (
"github.com/mhsanaei/3x-ui/v2/util/json_util"
)
// Config represents the complete Xray configuration structure.
// It contains all sections of an Xray config file including inbounds, outbounds, routing, etc.
type Config struct {
LogConfig json_util.RawMessage `json:"log"`
RouterConfig json_util.RawMessage `json:"routing"`
@@ -23,6 +25,7 @@ type Config struct {
Metrics json_util.RawMessage `json:"metrics"`
}
// Equals compares two Config instances for deep equality.
func (c *Config) Equals(other *Config) bool {
if len(c.InboundConfigs) != len(other.InboundConfigs) {
return false

3
xray/inbound.go
View File

@@ -6,6 +6,8 @@ import (
"github.com/mhsanaei/3x-ui/v2/util/json_util"
)
// InboundConfig represents an Xray inbound configuration.
// It defines how Xray accepts incoming connections including protocol, port, and settings.
type InboundConfig struct {
Listen json_util.RawMessage `json:"listen"` // listen cannot be an empty string
Port int `json:"port"`
@@ -16,6 +18,7 @@ type InboundConfig struct {
Sniffing json_util.RawMessage `json:"sniffing"`
}
// Equals compares two InboundConfig instances for deep equality.
func (c *InboundConfig) Equals(other *InboundConfig) bool {
if !bytes.Equal(c.Listen, other.Listen) {
return false

3
xray/log_writer.go
View File

@@ -8,14 +8,17 @@ import (
"github.com/mhsanaei/3x-ui/v2/logger"
)
// NewLogWriter returns a new LogWriter for processing Xray log output.
func NewLogWriter() *LogWriter {
return &LogWriter{}
}
// LogWriter processes and filters log output from the Xray process, handling crash detection and message filtering.
type LogWriter struct {
lastLine string
}
// Write processes and filters log output from the Xray process, handling crash detection and message filtering.
func (lw *LogWriter) Write(m []byte) (n int, err error) {
crashRegex := regexp.MustCompile(`(?i)(panic|exception|stack trace|fatal error)`)

29
xray/process.go
View File

@@ -18,46 +18,57 @@ import (
"github.com/mhsanaei/3x-ui/v2/util/common"
)
// GetBinaryName returns the Xray binary filename for the current OS and architecture.
func GetBinaryName() string {
return fmt.Sprintf("xray-%s-%s", runtime.GOOS, runtime.GOARCH)
}
// GetBinaryPath returns the full path to the Xray binary executable.
func GetBinaryPath() string {
return config.GetBinFolderPath() + "/" + GetBinaryName()
}
// GetConfigPath returns the path to the Xray configuration file in the binary folder.
func GetConfigPath() string {
return config.GetBinFolderPath() + "/config.json"
}
// GetGeositePath returns the path to the geosite data file used by Xray.
func GetGeositePath() string {
return config.GetBinFolderPath() + "/geosite.dat"
}
// GetGeoipPath returns the path to the geoip data file used by Xray.
func GetGeoipPath() string {
return config.GetBinFolderPath() + "/geoip.dat"
}
// GetIPLimitLogPath returns the path to the IP limit log file.
func GetIPLimitLogPath() string {
return config.GetLogFolder() + "/3xipl.log"
}
// GetIPLimitBannedLogPath returns the path to the banned IP log file.
func GetIPLimitBannedLogPath() string {
return config.GetLogFolder() + "/3xipl-banned.log"
}
// GetIPLimitBannedPrevLogPath returns the path to the previous banned IP log file.
func GetIPLimitBannedPrevLogPath() string {
return config.GetLogFolder() + "/3xipl-banned.prev.log"
}
// GetAccessPersistentLogPath returns the path to the persistent access log file.
func GetAccessPersistentLogPath() string {
return config.GetLogFolder() + "/3xipl-ap.log"
}
// GetAccessPersistentPrevLogPath returns the path to the previous persistent access log file.
func GetAccessPersistentPrevLogPath() string {
return config.GetLogFolder() + "/3xipl-ap.prev.log"
}
// GetAccessLogPath reads the Xray config and returns the access log file path.
func GetAccessLogPath() (string, error) {
config, err := os.ReadFile(GetConfigPath())
if err != nil {
@@ -82,14 +93,17 @@ func GetAccessLogPath() (string, error) {
return "", err
}
// stopProcess calls Stop on the given Process instance.
func stopProcess(p *Process) {
p.Stop()
}
// Process wraps an Xray process instance and provides management methods.
type Process struct {
*process
}
// NewProcess creates a new Xray process and sets up cleanup on garbage collection.
func NewProcess(xrayConfig *Config) *Process {
p := &Process{newProcess(xrayConfig)}
runtime.SetFinalizer(p, stopProcess)
@@ -110,6 +124,7 @@ type process struct {
startTime time.Time
}
// newProcess creates a new internal process struct for Xray.
func newProcess(config *Config) *process {
return &process{
version: "Unknown",
@@ -119,6 +134,7 @@ func newProcess(config *Config) *process {
}
}
// IsRunning returns true if the Xray process is currently running.
func (p *process) IsRunning() bool {
if p.cmd == nil || p.cmd.Process == nil {
return false
@@ -129,10 +145,12 @@ func (p *process) IsRunning() bool {
return false
}
// GetErr returns the last error encountered by the Xray process.
func (p *process) GetErr() error {
return p.exitErr
}
// GetResult returns the last log line or error from the Xray process.
func (p *process) GetResult() string {
if len(p.logWriter.lastLine) == 0 && p.exitErr != nil {
return p.exitErr.Error()
@@ -140,30 +158,37 @@ func (p *process) GetResult() string {
return p.logWriter.lastLine
}
// GetVersion returns the version string of the Xray process.
func (p *process) GetVersion() string {
return p.version
}
// GetAPIPort returns the API port used by the Xray process.
func (p *Process) GetAPIPort() int {
return p.apiPort
}
// GetConfig returns the configuration used by the Xray process.
func (p *Process) GetConfig() *Config {
return p.config
}
// GetOnlineClients returns the list of online clients for the Xray process.
func (p *Process) GetOnlineClients() []string {
return p.onlineClients
}
// SetOnlineClients sets the list of online clients for the Xray process.
func (p *Process) SetOnlineClients(users []string) {
p.onlineClients = users
}
// GetUptime returns the uptime of the Xray process in seconds.
func (p *Process) GetUptime() uint64 {
return uint64(time.Since(p.startTime).Seconds())
}
// refreshAPIPort updates the API port from the inbound configs.
func (p *process) refreshAPIPort() {
for _, inbound := range p.config.InboundConfigs {
if inbound.Tag == "api" {
@@ -173,6 +198,7 @@ func (p *process) refreshAPIPort() {
}
}
// refreshVersion updates the version string by running the Xray binary with -version.
func (p *process) refreshVersion() {
cmd := exec.Command(GetBinaryPath(), "-version")
data, err := cmd.Output()
@@ -188,6 +214,7 @@ func (p *process) refreshVersion() {
}
}
// Start launches the Xray process with the current configuration.
func (p *process) Start() (err error) {
if p.IsRunning() {
return errors.New("xray is already running")
@@ -245,6 +272,7 @@ func (p *process) Start() (err error) {
return nil
}
// Stop terminates the running Xray process.
func (p *process) Stop() error {
if !p.IsRunning() {
return errors.New("xray is not running")
@@ -257,6 +285,7 @@ func (p *process) Stop() error {
}
}
// writeCrashReport writes a crash report to the binary folder with a timestamped filename.
func writeCrashReport(m []byte) error {
crashReportPath := config.GetBinFolderPath() + "/core_crash_" + time.Now().Format("20060102_150405") + ".log"
return os.WriteFile(crashReportPath, m, os.ModePerm)

2
xray/traffic.go
View File

@@ -1,5 +1,7 @@
package xray
// Traffic represents network traffic statistics for Xray connections.
// It tracks upload and download bytes for inbound or outbound traffic.
type Traffic struct {
IsInbound bool
IsOutbound bool