refactor: focused service files, leaf subpackages, and an internal/ layout (#5167)

* refactor(service): split client.go into focused files client.go had grown to 4455 lines mixing ~10 responsibilities. Split it verbatim into cohesive same-package files (no behavior change): client.go foundation: ClientService, ClientWithAttachments, ClientCreatePayload, ErrClientNotInInbound, sqlInChunk client_locks.go inbound mutation locks, delete tombstones, compactOrphans client_lookup.go read-only lookups (GetByID, List, EffectiveFlow, ...) client_link.go inbound association sync (SyncInbound, DetachInbound, ...) client_crud.go single-client CRUD + validation + protocol defaults client_inbound_apply.go low-level inbound-settings mutators + by-email setters client_bulk.go bulk attach/detach/adjust/delete/create + DelDepleted client_traffic.go traffic-reset paths client_groups.go client group management client_paging.go paged listing, filtering, sorting, summary Every declaration moved unchanged (verified: identical func/type/const/var signature set before vs after). Imports redistributed per file via goimports. go build ./..., go vet, and go test ./web/service/... all pass. * refactor(service): split inbound.go into focused files inbound.go was 4100 lines. Split it verbatim into cohesive same-package files (no behavior change): inbound.go core inbound CRUD + InboundService (keeps pkg doc) inbound_protocol.go protocol / stream capability helpers inbound_node.go node/runtime/remote coordination + online tracking inbound_traffic.go traffic accounting, reset, client stats inbound_client_ips.go per-client IP tracking inbound_clients.go client lookups within inbounds + copy-clients inbound_disable.go auto-disable invalid inbounds/clients inbound_migration.go DB migrations inbound_sublink.go subscription link providers inbound_util.go generic slice/string helpers Identical func/type/const/var signature set before vs after; package doc comment preserved on inbound.go. Imports redistributed via goimports. Build, vet, and go test ./web/service/... all pass. * refactor(service): split tgbot.go into focused files tgbot.go was 3738 lines dominated by a 1246-line answerCallback. Split it verbatim into cohesive same-package files (no behavior change): tgbot.go lifecycle, bot setup, caches, small utils tgbot_router.go incoming update / command / callback dispatch tgbot_send.go outbound messaging primitives tgbot_client.go client views, actions, subscription links tgbot_inbound.go inbound listing / pickers tgbot_report.go server usage, exhausted, online, backups, notifications Identical func/type/const/var signature set before vs after. Imports redistributed via goimports. Build, vet, and go test ./web/service/... pass. * refactor(client): dedupe single-field by-email setters ResetClientIpLimitByEmail, ResetClientExpiryTimeByEmail, and ResetClientTrafficLimitByEmail shared an identical ~50-line body that resolves the inbound by email, confirms the client exists, rewrites a single-client settings payload, and delegates to UpdateInboundClient. Extract that into applyClientFieldByEmail(inboundSvc, email, mutate) and reduce each setter to a 3-line wrapper. Behavior is unchanged: same checks and error strings, same single-client payload contract, same totalGB guard. SetClientTelegramUserID (resolves by traffic id, different error text) and ToggleClientEnableByEmail/SetClientEnableByEmail (different return shape and a pre-read of the old state) intentionally keep their own bodies. * refactor(service): extract panel/ subpackage Move the panel-administration leaf services out of the flat service package into web/service/panel/ (package panel): user.go UserService (auth / 2FA / LDAP) panel.go PanelService (restart / self-update) + version helpers panel_other.go non-unix RestartPanel panel_unix.go unix RestartPanel api_token.go ApiTokenService websocket.go WebSocketService panel_test.go version/shellQuote unit tests These are leaves: they depend on core (SettingService, Release) but no core file references them, so the extraction creates no import cycle. Core references are now qualified (service.SettingService, service.Release); callers in main.go, web/web.go, and web/controller/* updated to panel.*. Build, vet, and go test ./web/... pass. * refactor(service): extract integration/ subpackage Move the external-provider integration leaves into web/service/integration/ (package integration): warp.go WarpService (Cloudflare WARP) nord.go NordService (NordVPN) custom_geo.go CustomGeoService (custom geo asset management) *_test.go custom_geo / panel-proxy tests These depend on core (SettingService, ServerService, XraySettingService) but no core file references them. xray_setting.go stays in core because it calls the unexported SettingService.saveSetting. The shared isBlockedIP SSRF helper (used by core url_safety.go and by custom_geo) now has a small copy in each package rather than being exported. Core references qualified; callers in web/web.go, web/job/*, and web/controller/* updated to integration.*. Build, vet, and go test ./web/... pass. * refactor(service): extract tgbot/ subpackage Move the Telegram bot (6 files + test) into web/service/tgbot/ (package tgbot). It is a leaf: it embeds five core services (Inbound/Client/Setting/ Server/Xray) and the core never references it, so no import cycle. To support the package boundary without changing behavior: - core exposes XrayProcess() *xray.Process so tgbot keeps calling the exact same running-process methods it used via the package-level `p`; - three core methods tgbot calls are exported: ClientService.checkIs- EnabledByEmail -> CheckIsEnabledByEmail, InboundService.getAllEmails -> GetAllEmails (callers updated in-package); - tgbot's embedded-field types and the few core type refs (Status, ClientCreatePayload, SanitizePublicHTTPURL) are now service-qualified. Callers in main.go, web/web.go, web/job/*, and web/controller/* updated to tgbot.*. Build, vet, and go test ./web/... pass. * refactor(service): extract outbound/ subpackage OutboundService (outbound.go) imports only neutral packages (config, database, model, xray) and its production code is referenced by no core or sibling service file — only by web/controller/xray_setting.go and web/job/xray_traffic_job.go. Move it to web/service/outbound/ (package outbound); no core qualification needed inside. Callers updated to outbound.*. The one coupling was a tiny pure test helper, outboundsContainTag, used by both outbound.go and the core outbound_subscription_test.go; it now has a small copy in that test file rather than being shared across the boundary. Build, vet, and go test ./web/... pass. * refactor(util): move wireguard into its own subpackage util/wireguard.go was the lone file of the root `util` package (24 lines, one exported func GenerateWireguardKeypair), while every other util concern lives in a focused subpackage (util/common, util/crypto, util/netsafe, ...). Move it to util/wireguard/ (package wireguard) for consistency; its only importer, web/service/integration/warp.go, is updated. The root `util` package no longer exists. * refactor(sub): drop redundant sub prefix from filenames Inside package sub the subXxx.go prefix just repeats the package name (like client_*.go did inside service). Rename for consistency; content and type names are unchanged: subController.go -> controller.go subService.go -> service.go subClashService.go -> clash_service.go subJsonService.go -> json_service.go (+ matching _test.go files) * refactor(controller): rename xui.go -> spa.go XUIController serves the panel's single-page-app shell; spa.go names that role plainly (the other controller files are domain-named). File rename only — the type stays XUIController. api_docs_test.go keys route base paths by filename, so its "xui.go" case is updated to "spa.go". * refactor: move backend packages under internal/ Adopt the idiomatic Go application layout: the backend packages now live under internal/ (a boundary the toolchain enforces), signalling private implementation instead of a library-style flat root. No runtime behavior changes — only import paths and a few build/config paths move. Moved: config, database, logger, mtproto, sub, util, web, xray -> internal/. main.go stays at the repo root and tools/openapigen stays under tools/ (both still import internal/* because the internal rule keys off the module root). The module path github.com/mhsanaei/3x-ui/v3 is unchanged; 149 .go files had their import prefix rewritten to .../internal/<pkg>. Couplings the Go compiler can't see, updated to the new layout: - frontend i18n imports of web/translation (react.ts, setup.components.ts) - vite outDir + eslint/tsconfig ignore globs -> internal/web/dist - Dockerfile COPY paths for web/dist and web/translation - locale.go os.DirFS("web") disk fallback -> "internal/web" - .gitignore and ci.yml go:embed stub for internal/web/dist - api_docs_test.go repo-root relative walk (one level deeper) - tools/openapigen filesystem package paths; ApiTokenView repointed to the web/service/panel subpackage and codegen regenerated (clears a stale type the ci.yml codegen check was failing on) Verified: go build/vet/test (all packages), and frontend typecheck, lint, vitest (478 tests), and production build into internal/web/dist. * fix(config): keep test runs from writing logs into the source tree GetLogFolder() returns a CWD-relative "./log" on Windows. Under `go test` the working directory is each package's own folder, so InitLogger (called by tests in web/job, web/service, xray, web/websocket) created stray log/ directories scattered through the source tree (e.g. internal/web/job/log/). Redirect to a shared temp folder when testing.Testing() reports a test run. Production behavior is unchanged: Windows still uses ./log next to the binary and Linux /var/log/x-ui. The log files were always gitignored (*.log) and never committed; this just stops the noise at the source. * docs: move subscription-template guide out of root into docs/ sub_templates/ was a top-level folder holding only a README and no actual templates (3x-ui ships none by design), referenced nowhere and unlinked from any doc — it read like an empty placeholder cluttering the repo root. Move the guide to docs/custom-subscription-templates.md (a proper docs home), reword its intro to read as documentation rather than a folder note, link it from the Features list in README.md, and drop the empty sub_templates/ folder. * fix: update stale web/ path references after the internal/ move The internal/ migration rewrote Go import paths but left some references to the old top-level layout in docs, comments, and a few runtime disk paths. Functional (dev-mode only): the disk-serving fallbacks that read the Vite build from disk when running from source still pointed at web/dist/, which moved to internal/web/dist/ — so `os.DirFS`/`os.Stat`/`os.ReadFile` in internal/web/web.go and internal/sub/{sub,controller}.go are corrected. Production was unaffected (it serves the embedded FS; verified by the Docker build), but `go run` with a live frontend build silently fell back to embed. Docs/comments: frontend/README.md, CONTRIBUTING.md, the claude-issue-bot and release workflows, the openapigen -root help text, and assorted Go comments now reference internal/web, internal/database, internal/sub, internal/xray, etc. Package-name mentions (the "web" package), root paths (main.go, frontend/, install scripts, /etc/x-ui), routes (/panel/api/xray), and the historical "web/assets no longer exists" note were intentionally left as-is. * refactor(web): remove the legacy /xui -> /panel redirect middleware RedirectMiddleware existed only for backward compatibility with the old `/xui` URL scheme (301-redirecting /xui and /xui/API to /panel and /panel/api). That cutover was long ago, so drop the middleware, its registration in initRouter, and the now-inaccurate "URL redirection" mention in the middleware package doc. Old /xui URLs now 404 like any other unknown path. HTTPS auto-redirect and auth redirects are unrelated and stay. * build: fix .dockerignore for internal/ layout and exclude runtime dir - web/dist -> internal/web/dist: the embedded frontend moved under internal/, so the stale exclude no longer matched and the locally-built dist could be sent to the build context (the frontend stage rebuilds it fresh anyway). - exclude x-ui/: the local runtime directory (SQLite db, geo .dat files, xray binaries, certs — ~150MB) was being shipped into the build context for no reason. Verified the pattern excludes only the directory and still keeps x-ui.sh, which the Dockerfile copies to /usr/bin/x-ui.
2026-09-18 16:17:16 +00:00 · 2026-06-10 15:19:22 +02:00
parent 26c549a95a
commit 41645255f1
254 changed files with 13074 additions and 12836 deletions
@@ -0,0 +1,376 @@
+// 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 (
+	"context"
+	"encoding/json"
+	"fmt"
+	"math"
+	"regexp"
+	"time"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/logger"
+	"github.com/mhsanaei/3x-ui/v3/internal/util/common"
+
+	"github.com/xtls/xray-core/app/proxyman/command"
+	statsService "github.com/xtls/xray-core/app/stats/command"
+	"github.com/xtls/xray-core/common/protocol"
+	"github.com/xtls/xray-core/common/serial"
+	"github.com/xtls/xray-core/infra/conf"
+	hysteriaAccount "github.com/xtls/xray-core/proxy/hysteria/account"
+	"github.com/xtls/xray-core/proxy/shadowsocks"
+	"github.com/xtls/xray-core/proxy/shadowsocks_2022"
+	"github.com/xtls/xray-core/proxy/trojan"
+	"github.com/xtls/xray-core/proxy/vless"
+	"github.com/xtls/xray-core/proxy/vmess"
+	"google.golang.org/grpc"
+	"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
+	grpcClient           *grpc.ClientConn
+	isConnected          bool
+	StatsLastValues      map[string]int64
+}
+
+func getRequiredUserString(user map[string]any, key string) (string, error) {
+	value, ok := user[key]
+	if !ok || value == nil {
+		return "", fmt.Errorf("missing required user field %q", key)
+	}
+
+	strValue, ok := value.(string)
+	if !ok {
+		return "", fmt.Errorf("invalid type for user field %q: %T", key, value)
+	}
+
+	return strValue, nil
+}
+
+func getOptionalUserString(user map[string]any, key string) (string, error) {
+	value, ok := user[key]
+	if !ok || value == nil {
+		return "", nil
+	}
+
+	strValue, ok := value.(string)
+	if !ok {
+		return "", fmt.Errorf("invalid type for user field %q: %T", key, value)
+	}
+
+	return strValue, nil
+}
+
+// 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)
+	}
+
+	addr := fmt.Sprintf("127.0.0.1:%d", apiPort)
+	conn, err := grpc.NewClient(addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	if err != nil {
+		return fmt.Errorf("failed to connect to Xray API: %w", err)
+	}
+
+	x.grpcClient = conn
+	x.isConnected = true
+	if x.StatsLastValues == nil {
+		x.StatsLastValues = make(map[string]int64)
+	}
+
+	hsClient := command.NewHandlerServiceClient(conn)
+	ssClient := statsService.NewStatsServiceClient(conn)
+
+	x.HandlerServiceClient = &hsClient
+	x.StatsServiceClient = &ssClient
+
+	return nil
+}
+
+// Close closes the gRPC connection and resets the XrayAPI client state.
+func (x *XrayAPI) Close() {
+	if x.grpcClient != nil {
+		x.grpcClient.Close()
+	}
+	x.HandlerServiceClient = nil
+	x.StatsServiceClient = nil
+	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
+
+	conf := new(conf.InboundDetourConfig)
+	err := json.Unmarshal(inbound, conf)
+	if err != nil {
+		logger.Debug("Failed to unmarshal inbound:", err)
+		return err
+	}
+	config, err := conf.Build()
+	if err != nil {
+		logger.Debug("Failed to build inbound Detur:", err)
+		return err
+	}
+	inboundConfig := command.AddInboundRequest{Inbound: config}
+
+	_, err = client.AddInbound(context.Background(), &inboundConfig)
+
+	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{
+		Tag: tag,
+	})
+	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 {
+	userEmail, err := getRequiredUserString(user, "email")
+	if err != nil {
+		return err
+	}
+
+	var account *serial.TypedMessage
+	switch Protocol {
+	case "vmess":
+		userID, err := getRequiredUserString(user, "id")
+		if err != nil {
+			return err
+		}
+
+		account = serial.ToTypedMessage(&vmess.Account{
+			Id: userID,
+		})
+	case "vless":
+		userID, err := getRequiredUserString(user, "id")
+		if err != nil {
+			return err
+		}
+
+		userFlow, err := getOptionalUserString(user, "flow")
+		if err != nil {
+			return err
+		}
+
+		vlessAccount := &vless.Account{
+			Id:   userID,
+			Flow: userFlow,
+		}
+		// Add testseed if provided
+		if testseedVal, ok := user["testseed"]; ok {
+			if testseedArr, ok := testseedVal.([]any); ok && len(testseedArr) >= 4 {
+				testseed := make([]uint32, len(testseedArr))
+				for i, v := range testseedArr {
+					if num, ok := v.(float64); ok {
+						testseed[i] = uint32(num)
+					}
+				}
+				vlessAccount.Testseed = testseed
+			} else if testseedArr, ok := testseedVal.([]uint32); ok && len(testseedArr) >= 4 {
+				vlessAccount.Testseed = testseedArr
+			}
+		}
+		// Add testpre if provided (for outbound, but can be in user for compatibility)
+		if testpreVal, ok := user["testpre"]; ok {
+			if testpre, ok := testpreVal.(float64); ok && testpre > 0 {
+				vlessAccount.Testpre = uint32(testpre)
+			} else if testpre, ok := testpreVal.(uint32); ok && testpre > 0 {
+				vlessAccount.Testpre = testpre
+			}
+		}
+		account = serial.ToTypedMessage(vlessAccount)
+	case "trojan":
+		password, err := getRequiredUserString(user, "password")
+		if err != nil {
+			return err
+		}
+
+		account = serial.ToTypedMessage(&trojan.Account{
+			Password: password,
+		})
+	case "shadowsocks":
+		cipher, err := getOptionalUserString(user, "cipher")
+		if err != nil {
+			return err
+		}
+
+		password, err := getRequiredUserString(user, "password")
+		if err != nil {
+			return err
+		}
+
+		var ssCipherType shadowsocks.CipherType
+		switch cipher {
+		case "aes-256-gcm":
+			ssCipherType = shadowsocks.CipherType_AES_256_GCM
+		case "chacha20-poly1305", "chacha20-ietf-poly1305":
+			ssCipherType = shadowsocks.CipherType_CHACHA20_POLY1305
+		case "xchacha20-poly1305", "xchacha20-ietf-poly1305":
+			ssCipherType = shadowsocks.CipherType_XCHACHA20_POLY1305
+		default:
+			ssCipherType = shadowsocks.CipherType_NONE
+		}
+
+		if ssCipherType != shadowsocks.CipherType_NONE {
+			account = serial.ToTypedMessage(&shadowsocks.Account{
+				Password:   password,
+				CipherType: ssCipherType,
+			})
+		} else {
+			account = serial.ToTypedMessage(&shadowsocks_2022.ServerConfig{
+				Key:   password,
+				Email: userEmail,
+			})
+		}
+	case "hysteria":
+		auth, err := getRequiredUserString(user, "auth")
+		if err != nil {
+			return err
+		}
+
+		account = serial.ToTypedMessage(&hysteriaAccount.Account{
+			Auth: auth,
+		})
+	default:
+		return nil
+	}
+
+	client := *x.HandlerServiceClient
+
+	_, err = client.AlterInbound(context.Background(), &command.AlterInboundRequest{
+		Tag: inboundTag,
+		Operation: serial.ToTypedMessage(&command.AddUserOperation{
+			User: &protocol.User{
+				Email:   userEmail,
+				Account: account,
+			},
+		}),
+	})
+	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()
+
+	op := &command.RemoveUserOperation{Email: email}
+	req := &command.AlterInboundRequest{
+		Tag:       inboundTag,
+		Operation: serial.ToTypedMessage(op),
+	}
+
+	_, err := (*x.HandlerServiceClient).AlterInbound(ctx, req)
+	if err != nil {
+		return fmt.Errorf("failed to remove user: %w", err)
+	}
+
+	return nil
+}
+
+// GetTraffic queries traffic statistics from the Xray core, optionally resetting counters.
+func (x *XrayAPI) GetTraffic() ([]*Traffic, []*ClientTraffic, error) {
+	if x.grpcClient == nil {
+		return nil, nil, common.NewError("xray api is not initialized")
+	}
+
+	trafficRegex := regexp.MustCompile(`(inbound|outbound)>>>([^>]+)>>>traffic>>>(downlink|uplink)`)
+	clientTrafficRegex := regexp.MustCompile(`user>>>([^>]+)>>>traffic>>>(downlink|uplink)`)
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
+	defer cancel()
+
+	if x.StatsServiceClient == nil {
+		return nil, nil, common.NewError("xray StatusServiceClient is not initialized")
+	}
+
+	resp, err := (*x.StatsServiceClient).QueryStats(ctx, &statsService.QueryStatsRequest{Reset_: false})
+	if err != nil {
+		logger.Debug("Failed to query Xray stats:", err)
+		return nil, nil, err
+	}
+
+	tagTrafficMap := make(map[string]*Traffic)
+	emailTrafficMap := make(map[string]*ClientTraffic)
+
+	for _, stat := range resp.GetStat() {
+		lastValue, ok := x.StatsLastValues[stat.Name]
+		x.StatsLastValues[stat.Name] = stat.Value
+		if !ok || stat.Value < lastValue {
+			// skip first time of seen stat
+			continue
+		}
+		value := stat.Value - lastValue
+		if matches := trafficRegex.FindStringSubmatch(stat.Name); len(matches) == 4 {
+			processTraffic(matches, value, tagTrafficMap)
+		} else if matches := clientTrafficRegex.FindStringSubmatch(stat.Name); len(matches) == 3 {
+			processClientTraffic(matches, value, emailTrafficMap)
+		}
+	}
+	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]
+	isDown := matches[3] == "downlink"
+
+	if tag == "api" {
+		return
+	}
+
+	traffic, ok := trafficMap[tag]
+	if !ok {
+		traffic = &Traffic{
+			IsInbound:  isInbound,
+			IsOutbound: !isInbound,
+			Tag:        tag,
+		}
+		trafficMap[tag] = traffic
+	}
+
+	if isDown {
+		traffic.Down = value
+	} else {
+		traffic.Up = value
+	}
+}
+
+// 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"
+
+	traffic, ok := clientTrafficMap[email]
+	if !ok {
+		traffic = &ClientTraffic{Email: email}
+		clientTrafficMap[email] = traffic
+	}
+
+	if isDown {
+		traffic.Down = value
+	} else {
+		traffic.Up = value
+	}
+}
+
+// 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 {
+		result = append(result, v)
+	}
+	return result
+}
@@ -0,0 +1,82 @@
+package xray
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestGetRequiredUserString_Present(t *testing.T) {
+	user := map[string]any{"email": "alice@example.com"}
+	got, err := getRequiredUserString(user, "email")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "alice@example.com" {
+		t.Fatalf("got %q, want %q", got, "alice@example.com")
+	}
+}
+
+func TestGetRequiredUserString_Missing(t *testing.T) {
+	user := map[string]any{}
+	if _, err := getRequiredUserString(user, "email"); err == nil {
+		t.Fatal("expected error for missing key")
+	}
+}
+
+func TestGetRequiredUserString_NilValue(t *testing.T) {
+	user := map[string]any{"email": nil}
+	if _, err := getRequiredUserString(user, "email"); err == nil {
+		t.Fatal("expected error for nil value")
+	}
+}
+
+func TestGetRequiredUserString_WrongType(t *testing.T) {
+	user := map[string]any{"email": 42}
+	_, err := getRequiredUserString(user, "email")
+	if err == nil {
+		t.Fatal("expected error for non-string value")
+	}
+	if !strings.Contains(err.Error(), "invalid type") {
+		t.Fatalf("expected %q in error, got: %v", "invalid type", err)
+	}
+}
+
+func TestGetOptionalUserString_Present(t *testing.T) {
+	user := map[string]any{"flow": "xtls-rprx-vision"}
+	got, err := getOptionalUserString(user, "flow")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "xtls-rprx-vision" {
+		t.Fatalf("got %q, want %q", got, "xtls-rprx-vision")
+	}
+}
+
+func TestGetOptionalUserString_MissingReturnsEmptyNoError(t *testing.T) {
+	user := map[string]any{}
+	got, err := getOptionalUserString(user, "flow")
+	if err != nil {
+		t.Fatalf("unexpected error for missing optional field: %v", err)
+	}
+	if got != "" {
+		t.Fatalf("got %q, want empty string", got)
+	}
+}
+
+func TestGetOptionalUserString_NilReturnsEmptyNoError(t *testing.T) {
+	user := map[string]any{"flow": nil}
+	got, err := getOptionalUserString(user, "flow")
+	if err != nil {
+		t.Fatalf("unexpected error for nil optional field: %v", err)
+	}
+	if got != "" {
+		t.Fatalf("got %q, want empty string", got)
+	}
+}
+
+func TestGetOptionalUserString_WrongTypeErrors(t *testing.T) {
+	user := map[string]any{"flow": []string{"a", "b"}}
+	if _, err := getOptionalUserString(user, "flow"); err == nil {
+		t.Fatal("expected error for non-string optional value")
+	}
+}
@@ -0,0 +1,18 @@
+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" example:"14825"`
+	InboundId  int    `json:"inboundId" form:"inboundId" example:"1"`
+	Enable     bool   `json:"enable" form:"enable" example:"true"`
+	Email      string `json:"email" form:"email" gorm:"unique" example:"user1"`
+	UUID       string `json:"uuid" form:"uuid" gorm:"-" example:"e18c9a96-71bf-48d4-933f-8b9a46d4290c"`
+	SubId      string `json:"subId" form:"subId" gorm:"-" example:"i7tvdpeffi0hvvf1"`
+	Up         int64  `json:"up" form:"up" example:"1048576"`
+	Down       int64  `json:"down" form:"down" example:"2097152"`
+	ExpiryTime int64  `json:"expiryTime" form:"expiryTime" example:"1735689600000"`
+	Total      int64  `json:"total" form:"total" example:"10737418240"`
+	Reset      int    `json:"reset" form:"reset" gorm:"default:0" example:"0"`
+	LastOnline int64  `json:"lastOnline" form:"lastOnline" gorm:"default:0" example:"1735680000000"`
+}
@@ -0,0 +1,72 @@
+package xray
+
+import (
+	"bytes"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/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"`
+	DNSConfig        json_util.RawMessage `json:"dns,omitempty"`
+	InboundConfigs   []InboundConfig      `json:"inbounds"`
+	OutboundConfigs  json_util.RawMessage `json:"outbounds"`
+	Transport        json_util.RawMessage `json:"transport,omitempty"`
+	Policy           json_util.RawMessage `json:"policy"`
+	API              json_util.RawMessage `json:"api"`
+	Stats            json_util.RawMessage `json:"stats"`
+	Reverse          json_util.RawMessage `json:"reverse,omitempty"`
+	FakeDNS          json_util.RawMessage `json:"fakedns,omitempty"`
+	Observatory      json_util.RawMessage `json:"observatory,omitempty"`
+	BurstObservatory json_util.RawMessage `json:"burstObservatory,omitempty"`
+	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
+	}
+	for i, inbound := range c.InboundConfigs {
+		if !inbound.Equals(&other.InboundConfigs[i]) {
+			return false
+		}
+	}
+	if !bytes.Equal(c.LogConfig, other.LogConfig) {
+		return false
+	}
+	if !bytes.Equal(c.RouterConfig, other.RouterConfig) {
+		return false
+	}
+	if !bytes.Equal(c.DNSConfig, other.DNSConfig) {
+		return false
+	}
+	if !bytes.Equal(c.OutboundConfigs, other.OutboundConfigs) {
+		return false
+	}
+	if !bytes.Equal(c.Transport, other.Transport) {
+		return false
+	}
+	if !bytes.Equal(c.Policy, other.Policy) {
+		return false
+	}
+	if !bytes.Equal(c.API, other.API) {
+		return false
+	}
+	if !bytes.Equal(c.Stats, other.Stats) {
+		return false
+	}
+	if !bytes.Equal(c.Reverse, other.Reverse) {
+		return false
+	}
+	if !bytes.Equal(c.FakeDNS, other.FakeDNS) {
+		return false
+	}
+	if !bytes.Equal(c.Metrics, other.Metrics) {
+		return false
+	}
+	return true
+}
@@ -0,0 +1,91 @@
+package xray
+
+import (
+	"testing"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/util/json_util"
+)
+
+func makeConfig() *Config {
+	return &Config{
+		LogConfig:       json_util.RawMessage(`{"loglevel":"warning"}`),
+		RouterConfig:    json_util.RawMessage(`{}`),
+		OutboundConfigs: json_util.RawMessage(`[]`),
+		Policy:          json_util.RawMessage(`{}`),
+		API:             json_util.RawMessage(`{}`),
+		Stats:           json_util.RawMessage(`{}`),
+		Metrics:         json_util.RawMessage(`{}`),
+		InboundConfigs: []InboundConfig{
+			{
+				Port:     1080,
+				Protocol: "vless",
+				Tag:      "inbound-1080",
+				Listen:   json_util.RawMessage(`"0.0.0.0"`),
+				Settings: json_util.RawMessage(`{"clients":[]}`),
+			},
+		},
+	}
+}
+
+func TestConfigEquals_IdenticalConfigs(t *testing.T) {
+	a := makeConfig()
+	b := makeConfig()
+	if !a.Equals(b) {
+		t.Fatal("two identical configs should be Equals")
+	}
+}
+
+func TestConfigEquals_DifferentInboundCount(t *testing.T) {
+	a := makeConfig()
+	b := makeConfig()
+	b.InboundConfigs = append(b.InboundConfigs, InboundConfig{Port: 2080, Protocol: "vmess", Tag: "inbound-2080"})
+	if a.Equals(b) {
+		t.Fatal("configs with different inbound counts should not be Equals")
+	}
+}
+
+func TestConfigEquals_DifferentInboundContent(t *testing.T) {
+	a := makeConfig()
+	b := makeConfig()
+	b.InboundConfigs[0].Port = 9999
+	if a.Equals(b) {
+		t.Fatal("config with changed inbound port should not be Equals")
+	}
+}
+
+func TestConfigEquals_DifferentLogConfig(t *testing.T) {
+	a := makeConfig()
+	b := makeConfig()
+	b.LogConfig = json_util.RawMessage(`{"loglevel":"debug"}`)
+	if a.Equals(b) {
+		t.Fatal("config with changed log section should not be Equals")
+	}
+}
+
+func TestConfigEquals_RawSectionsCompared(t *testing.T) {
+	fields := []struct {
+		name    string
+		mutator func(c *Config)
+	}{
+		{"RouterConfig", func(c *Config) { c.RouterConfig = json_util.RawMessage(`{"changed":true}`) }},
+		{"DNSConfig", func(c *Config) { c.DNSConfig = json_util.RawMessage(`{"servers":["1.1.1.1"]}`) }},
+		{"OutboundConfigs", func(c *Config) { c.OutboundConfigs = json_util.RawMessage(`[{"tag":"x"}]`) }},
+		{"Transport", func(c *Config) { c.Transport = json_util.RawMessage(`{"x":1}`) }},
+		{"Policy", func(c *Config) { c.Policy = json_util.RawMessage(`{"levels":{}}`) }},
+		{"API", func(c *Config) { c.API = json_util.RawMessage(`{"tag":"api"}`) }},
+		{"Stats", func(c *Config) { c.Stats = json_util.RawMessage(`{"on":true}`) }},
+		{"Reverse", func(c *Config) { c.Reverse = json_util.RawMessage(`{"bridges":[]}`) }},
+		{"FakeDNS", func(c *Config) { c.FakeDNS = json_util.RawMessage(`[]`) }},
+		{"Metrics", func(c *Config) { c.Metrics = json_util.RawMessage(`{"tag":"m"}`) }},
+	}
+	for _, f := range fields {
+		t.Run(f.name, func(t *testing.T) {
+			a := makeConfig()
+			b := makeConfig()
+			f.mutator(b)
+			if a.Equals(b) {
+				t.Fatalf("mutating %s should break Equals", f.name)
+			}
+		})
+	}
+}
@@ -0,0 +1,45 @@
+package xray
+
+import (
+	"bytes"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/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"`
+	Protocol       string               `json:"protocol"`
+	Settings       json_util.RawMessage `json:"settings"`
+	StreamSettings json_util.RawMessage `json:"streamSettings,omitempty"`
+	Tag            string               `json:"tag"`
+	Sniffing       json_util.RawMessage `json:"sniffing,omitempty"`
+}
+
+// Equals compares two InboundConfig instances for deep equality.
+func (c *InboundConfig) Equals(other *InboundConfig) bool {
+	if !bytes.Equal(c.Listen, other.Listen) {
+		return false
+	}
+	if c.Port != other.Port {
+		return false
+	}
+	if c.Protocol != other.Protocol {
+		return false
+	}
+	if !bytes.Equal(c.Settings, other.Settings) {
+		return false
+	}
+	if !bytes.Equal(c.StreamSettings, other.StreamSettings) {
+		return false
+	}
+	if c.Tag != other.Tag {
+		return false
+	}
+	if !bytes.Equal(c.Sniffing, other.Sniffing) {
+		return false
+	}
+	return true
+}
@@ -0,0 +1,52 @@
+package xray
+
+import (
+	"testing"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/util/json_util"
+)
+
+func makeInbound() InboundConfig {
+	return InboundConfig{
+		Listen:         json_util.RawMessage(`"0.0.0.0"`),
+		Port:           1234,
+		Protocol:       "vless",
+		Settings:       json_util.RawMessage(`{"clients":[{"id":"abc"}]}`),
+		StreamSettings: json_util.RawMessage(`{"network":"tcp"}`),
+		Tag:            "inbound-1234",
+		Sniffing:       json_util.RawMessage(`{"enabled":false}`),
+	}
+}
+
+func TestInboundConfigEquals_Identical(t *testing.T) {
+	a := makeInbound()
+	b := makeInbound()
+	if !a.Equals(&b) {
+		t.Fatal("two identical inbounds should be Equals")
+	}
+}
+
+func TestInboundConfigEquals_MutationsBreakEquality(t *testing.T) {
+	cases := []struct {
+		name    string
+		mutator func(c *InboundConfig)
+	}{
+		{"Listen", func(c *InboundConfig) { c.Listen = json_util.RawMessage(`"127.0.0.1"`) }},
+		{"Port", func(c *InboundConfig) { c.Port = 9999 }},
+		{"Protocol", func(c *InboundConfig) { c.Protocol = "vmess" }},
+		{"Settings", func(c *InboundConfig) { c.Settings = json_util.RawMessage(`{"clients":[]}`) }},
+		{"StreamSettings", func(c *InboundConfig) { c.StreamSettings = json_util.RawMessage(`{"network":"ws"}`) }},
+		{"Tag", func(c *InboundConfig) { c.Tag = "inbound-other" }},
+		{"Sniffing", func(c *InboundConfig) { c.Sniffing = json_util.RawMessage(`{"enabled":true}`) }},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			a := makeInbound()
+			b := makeInbound()
+			tc.mutator(&b)
+			if a.Equals(&b) {
+				t.Fatalf("mutating %s should break Equals", tc.name)
+			}
+		})
+	}
+}
@@ -0,0 +1,100 @@
+package xray
+
+import (
+	"regexp"
+	"runtime"
+	"strings"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/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)`)
+
+	// Convert the data to a string
+	message := strings.TrimSpace(string(m))
+	msgLowerAll := strings.ToLower(message)
+
+	// Suppress noisy Windows process-kill signal that surfaces as exit status 1
+	if runtime.GOOS == "windows" && strings.Contains(msgLowerAll, "exit status 1") {
+		return len(m), nil
+	}
+
+	// Check if the message contains a crash
+	if crashRegex.MatchString(message) {
+		logger.Debug("Core crash detected:\n", message)
+		lw.lastLine = message
+		err1 := writeCrashReport(m)
+		if err1 != nil {
+			logger.Error("Unable to write crash report:", err1)
+		}
+		return len(m), nil
+	}
+
+	regex := regexp.MustCompile(`^(\d{4}/\d{2}/\d{2} \d{2}:\d{2}:\d{2}\.\d{6}) \[([^\]]+)\] (.+)$`)
+	messages := strings.SplitSeq(message, "\n")
+
+	for msg := range messages {
+		matches := regex.FindStringSubmatch(msg)
+
+		if len(matches) > 3 {
+			level := matches[2]
+			msgBody := matches[3]
+			msgBodyLower := strings.ToLower(msgBody)
+
+			if strings.Contains(msgBodyLower, "tls handshake error") ||
+				strings.Contains(msgBodyLower, "connection ends") {
+				logger.Debug("XRAY: " + msgBody)
+				lw.lastLine = ""
+				continue
+			}
+
+			if strings.Contains(msgBodyLower, "failed") {
+				logger.Error("XRAY: " + msgBody)
+			} else {
+				switch level {
+				case "Debug":
+					logger.Debug("XRAY: " + msgBody)
+				case "Info":
+					logger.Info("XRAY: " + msgBody)
+				case "Warning":
+					logger.Warning("XRAY: " + msgBody)
+				case "Error":
+					logger.Error("XRAY: " + msgBody)
+				default:
+					logger.Debug("XRAY: " + msg)
+				}
+			}
+			lw.lastLine = ""
+		} else if msg != "" {
+			msgLower := strings.ToLower(msg)
+
+			if strings.Contains(msgLower, "tls handshake error") ||
+				strings.Contains(msgLower, "connection ends") {
+				logger.Debug("XRAY: " + msg)
+				lw.lastLine = msg
+				continue
+			}
+
+			if strings.Contains(msgLower, "failed") {
+				logger.Error("XRAY: " + msg)
+			} else {
+				logger.Debug("XRAY: " + msg)
+			}
+			lw.lastLine = msg
+		}
+	}
+
+	return len(m), nil
+}
@@ -0,0 +1,131 @@
+package xray
+
+import (
+	"slices"
+	"testing"
+)
+
+func newOnlineTestProcess() *Process {
+	return &Process{newProcess(nil)}
+}
+
+func assertSameSet(t *testing.T, label string, got, want []string) {
+	t.Helper()
+	g := append([]string(nil), got...)
+	w := append([]string(nil), want...)
+	slices.Sort(g)
+	slices.Sort(w)
+	if !slices.Equal(g, w) {
+		t.Errorf("%s = %v, want %v", label, got, want)
+	}
+}
+
+// TestMergedNodeTreesScopesPerGuid pins #4983/#4809: each node's clients stay
+// under that node's GUID, so a client on one node is never attributed to
+// another — and a sub-node's clients (reported under their own GUID inside a
+// parent's tree) compose upward without collapsing onto the parent.
+func TestMergedNodeTreesScopesPerGuid(t *testing.T) {
+	p := newOnlineTestProcess()
+	// Node A (direct) reports its own clients plus sub-node B's tree.
+	p.SetNodeOnlineTree(1, map[string][]string{
+		"guid-a": {"user1", "user2"},
+		"guid-b": {"user3"}, // B is behind A; still keyed by B's own GUID
+	})
+	p.SetNodeOnlineTree(2, map[string][]string{
+		"guid-c": {"user4"},
+	})
+
+	merged := p.GetMergedNodeTrees()
+	assertSameSet(t, "guid-a", merged["guid-a"], []string{"user1", "user2"})
+	assertSameSet(t, "guid-b", merged["guid-b"], []string{"user3"})
+	assertSameSet(t, "guid-c", merged["guid-c"], []string{"user4"})
+
+	if slices.Contains(merged["guid-a"], "user3") {
+		t.Errorf("user3 (on sub-node B) leaked onto node A: %v", merged["guid-a"])
+	}
+}
+
+// TestMergedNodeTreesOmitsEmpty keeps the payload small: empty GUID sets don't
+// appear as keys.
+func TestMergedNodeTreesOmitsEmpty(t *testing.T) {
+	p := newOnlineTestProcess()
+	p.SetNodeOnlineTree(1, map[string][]string{
+		"guid-a": {"user1"},
+		"guid-x": {},
+	})
+	if _, ok := p.GetMergedNodeTrees()["guid-x"]; ok {
+		t.Errorf("empty GUID set should be omitted: %v", p.GetMergedNodeTrees())
+	}
+}
+
+// TestGetOnlineClientsUnionDedupes confirms the flat union (client-centric /
+// total-count views) merges local + every node and dedupes.
+func TestGetOnlineClientsUnionDedupes(t *testing.T) {
+	p := newOnlineTestProcess()
+	p.RefreshLocalOnline([]string{"user1"}, nil, 1000, 20000)
+	p.SetNodeOnlineTree(1, map[string][]string{"guid-a": {"user1", "user2"}})
+
+	assertSameSet(t, "union", p.GetOnlineClients(), []string{"user1", "user2"})
+}
+
+// TestRefreshLocalOnlineGraceWindow checks the in-memory local set honours the
+// grace window: idle-but-recent clients stay online, stale ones age out, and
+// the set is derived only from local activity (never the shared DB column).
+func TestRefreshLocalOnlineGraceWindow(t *testing.T) {
+	p := newOnlineTestProcess()
+	const grace = 20000
+
+	p.RefreshLocalOnline([]string{"user1"}, nil, 1000, grace)
+	if got := p.GetLocalOnlineClients(); !slices.Contains(got, "user1") {
+		t.Fatalf("user1 should be online right after activity, got %v", got)
+	}
+
+	p.RefreshLocalOnline([]string{"user2"}, nil, 11000, grace)
+	got := p.GetLocalOnlineClients()
+	if !slices.Contains(got, "user1") || !slices.Contains(got, "user2") {
+		t.Fatalf("both within grace window, got %v", got)
+	}
+
+	p.RefreshLocalOnline(nil, nil, 22000, grace)
+	got = p.GetLocalOnlineClients()
+	if slices.Contains(got, "user1") {
+		t.Errorf("user1 (idle 21s, past grace) should have aged out, got %v", got)
+	}
+	if !slices.Contains(got, "user2") {
+		t.Errorf("user2 (idle 11s, within grace) should still be online, got %v", got)
+	}
+}
+
+// TestGetLocalActiveInboundsTracksGraceWindow pins #4859: a multi-inbound
+// client only counts online on inbounds that actually carried traffic, and the
+// active-inbound signal honours the same grace window as the online signal.
+func TestGetLocalActiveInboundsTracksGraceWindow(t *testing.T) {
+	p := newOnlineTestProcess()
+	const grace = 20000
+
+	p.RefreshLocalOnline([]string{"alice"}, []string{"inbound-a"}, 1000, grace)
+	assertSameSet(t, "active after first poll", p.GetLocalActiveInbounds(), []string{"inbound-a"})
+
+	p.RefreshLocalOnline([]string{"alice"}, []string{"inbound-b"}, 11000, grace)
+	assertSameSet(t, "both within grace", p.GetLocalActiveInbounds(), []string{"inbound-a", "inbound-b"})
+
+	p.RefreshLocalOnline(nil, nil, 22000, grace)
+	assertSameSet(t, "inbound-a (idle 21s) aged out, inbound-b kept", p.GetLocalActiveInbounds(), []string{"inbound-b"})
+
+	p.RefreshLocalOnline(nil, nil, 40000, grace)
+	if got := p.GetLocalActiveInbounds(); len(got) != 0 {
+		t.Errorf("all inbounds idle past grace, want empty, got %v", got)
+	}
+}
+
+// TestClearNodeOnlineClientsDropsNode mirrors a failed node probe: the node's
+// whole subtree contribution disappears immediately.
+func TestClearNodeOnlineClientsDropsNode(t *testing.T) {
+	p := newOnlineTestProcess()
+	p.SetNodeOnlineTree(3, map[string][]string{"guid-a": {"user1"}})
+	p.ClearNodeOnlineClients(3)
+
+	if _, ok := p.GetMergedNodeTrees()["guid-a"]; ok {
+		t.Errorf("node 3's subtree should be absent after ClearNodeOnlineClients")
+	}
+}
@@ -0,0 +1,631 @@
+package xray
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"sort"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"syscall"
+	"time"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/config"
+	"github.com/mhsanaei/3x-ui/v3/internal/logger"
+	"github.com/mhsanaei/3x-ui/v3/internal/util/common"
+)
+
+// GetBinaryName returns the Xray binary filename for the current OS and architecture.
+func GetBinaryName() string {
+	arch := runtime.GOARCH
+	if arch == "arm" {
+		arch = "arm32"
+	}
+	return fmt.Sprintf("xray-%s-%s", runtime.GOOS, arch)
+}
+
+// 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 {
+		logger.Warningf("Failed to read configuration file: %s", err)
+		return "", err
+	}
+
+	jsonConfig := map[string]any{}
+	err = json.Unmarshal([]byte(config), &jsonConfig)
+	if err != nil {
+		logger.Warningf("Failed to parse JSON configuration: %s", err)
+		return "", err
+	}
+
+	if jsonConfig["log"] != nil {
+		jsonLog := jsonConfig["log"].(map[string]any)
+		if jsonLog["access"] != nil {
+			accessLogPath := jsonLog["access"].(string)
+			return accessLogPath, nil
+		}
+	}
+	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)
+	return p
+}
+
+// NewTestProcess creates a new Xray process that uses a specific config file path.
+// Used for test runs (e.g. outbound test) so the main config.json is not overwritten.
+// The config file at configPath is removed when the process is stopped.
+func NewTestProcess(xrayConfig *Config, configPath string) *Process {
+	p := &Process{newTestProcess(xrayConfig, configPath)}
+	runtime.SetFinalizer(p, stopProcess)
+	return p
+}
+
+type process struct {
+	cmd  *exec.Cmd
+	done chan struct{}
+
+	version string
+	apiPort int
+
+	// onlineClients is the set of emails active on THIS panel's own xray
+	// within the online grace window. It is derived only from local xray
+	// traffic polls (see RefreshLocalOnline) — never from remote-node
+	// snapshots — so a client connected solely to a remote node is not
+	// reported online on local inbounds.
+	onlineClients []string
+	// localActiveInbounds is the set of THIS panel's inbound tags that
+	// carried traffic within the same grace window. Xray's user>>>email
+	// stat aggregates across every inbound a client is attached to, so an
+	// online email alone can't say which inbound it actually used. Pairing
+	// it with the inbound>>>tag stat lets the per-inbound view drop a
+	// multi-inbound client from inbounds that saw no traffic this window.
+	localActiveInbounds []string
+	// localLastOnline records, per email, the last time this panel's own
+	// xray reported traffic for it. RefreshLocalOnline rebuilds
+	// onlineClients from this map each tick, keeping the local online set
+	// independent of the shared client_traffics.last_online column — that
+	// column is bumped by remote-node syncs too and would otherwise leak
+	// remote-only clients into the local set.
+	localLastOnline map[string]int64
+	// localInboundLastActive mirrors localLastOnline for inbound tags: the
+	// last tick this panel's xray reported traffic through each tag.
+	// Rebuilt into localActiveInbounds under the same grace window so the
+	// two signals stay aligned — an email within grace always has the
+	// inbound it used within grace too.
+	localInboundLastActive map[string]int64
+	// nodeOnlineTrees holds, per direct remote node (keyed by that node's
+	// panel-local id), the GUID-keyed online-emails subtree that node
+	// reported — its own clients under its panelGuid plus every descendant
+	// under theirs. Keying the stored value by GUID (not node id) lets the
+	// master attribute a deeply nested client to the node that physically
+	// hosts it across a chain (#4983); the outer node-id key is only so a
+	// failed probe can drop that whole branch's contribution. NodeTrafficSyncJob
+	// populates entries per cron tick and clears them when a probe fails. The
+	// mutex guards this map, onlineClients, and localLastOnline above so the
+	// online getters never see a torn read.
+	nodeOnlineTrees map[int]map[string][]string
+	onlineMu        sync.RWMutex
+
+	config     *Config
+	configPath string // if set, use this path instead of GetConfigPath() and remove on Stop
+	logWriter  *LogWriter
+	exitErr    error
+	startTime  time.Time
+
+	intentionalStop atomic.Bool
+}
+
+var (
+	xrayGracefulStopTimeout = 5 * time.Second
+	xrayForceStopTimeout    = 2 * time.Second
+)
+
+// newProcess creates a new internal process struct for Xray.
+func newProcess(config *Config) *process {
+	return &process{
+		version:   "Unknown",
+		config:    config,
+		logWriter: NewLogWriter(),
+		startTime: time.Now(),
+	}
+}
+
+// newTestProcess creates a process that writes and runs with a specific config path.
+func newTestProcess(config *Config, configPath string) *process {
+	p := newProcess(config)
+	p.configPath = configPath
+	return p
+}
+
+// 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
+	}
+	if p.done != nil {
+		select {
+		case <-p.done:
+			return false
+		default:
+		}
+	}
+	if p.cmd.ProcessState == nil {
+		return true
+	}
+	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()
+	}
+	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 union of locally-online clients and
+// node-online clients from every registered remote panel. Dedupes by
+// email so a client connected to both a local and a node-managed inbound
+// surfaces once. Cheap allocation — typical online sets are small and
+// the union is recomputed on demand.
+func (p *Process) GetOnlineClients() []string {
+	p.onlineMu.RLock()
+	defer p.onlineMu.RUnlock()
+
+	if len(p.nodeOnlineTrees) == 0 {
+		// Hot path for single-panel deployments: avoid the map+dedupe
+		// work entirely and return the local slice as-is.
+		return p.onlineClients
+	}
+
+	seen := make(map[string]struct{}, len(p.onlineClients))
+	out := make([]string, 0, len(p.onlineClients))
+	add := func(emails []string) {
+		for _, email := range emails {
+			if _, dup := seen[email]; dup {
+				continue
+			}
+			seen[email] = struct{}{}
+			out = append(out, email)
+		}
+	}
+	add(p.onlineClients)
+	for _, tree := range p.nodeOnlineTrees {
+		for _, emails := range tree {
+			add(emails)
+		}
+	}
+	return out
+}
+
+// GetLocalOnlineClients returns a copy of the emails online on THIS panel's own
+// xray within the grace window. The service layer keys these under the panel's
+// own GUID when assembling the per-node online view.
+func (p *Process) GetLocalOnlineClients() []string {
+	p.onlineMu.RLock()
+	defer p.onlineMu.RUnlock()
+	if len(p.onlineClients) == 0 {
+		return nil
+	}
+	out := make([]string, len(p.onlineClients))
+	copy(out, p.onlineClients)
+	return out
+}
+
+// GetMergedNodeTrees returns the union of every direct node's reported subtree,
+// keyed by the panelGuid of the node that physically hosts each client set.
+// Because each child already reports its descendants under their own GUIDs,
+// merging the direct children yields the whole tree at any depth (#4983), so a
+// client three hops down is attributed to its real node, not the intermediate
+// one. GUIDs are globally unique, but a set reported under the same GUID by more
+// than one path is deduped per key; empty sets are omitted.
+func (p *Process) GetMergedNodeTrees() map[string][]string {
+	p.onlineMu.RLock()
+	defer p.onlineMu.RUnlock()
+	if len(p.nodeOnlineTrees) == 0 {
+		return map[string][]string{}
+	}
+	out := make(map[string][]string)
+	seen := make(map[string]map[string]struct{})
+	for _, tree := range p.nodeOnlineTrees {
+		for guid, emails := range tree {
+			if guid == "" || len(emails) == 0 {
+				continue
+			}
+			dedup := seen[guid]
+			if dedup == nil {
+				dedup = make(map[string]struct{}, len(emails))
+				seen[guid] = dedup
+			}
+			for _, email := range emails {
+				if _, ok := dedup[email]; ok {
+					continue
+				}
+				dedup[email] = struct{}{}
+				out[guid] = append(out[guid], email)
+			}
+		}
+	}
+	return out
+}
+
+// GetLocalActiveInbounds returns a copy of THIS panel's inbound tags that
+// carried traffic within the grace window. Only the local xray reports
+// per-inbound activity; remote-node snapshots don't carry it, so the service
+// layer keys these under the panel's own GUID and a node missing from the
+// active-inbounds map means "don't gate" (fall back to the email-only signal).
+func (p *Process) GetLocalActiveInbounds() []string {
+	p.onlineMu.RLock()
+	defer p.onlineMu.RUnlock()
+	if len(p.localActiveInbounds) == 0 {
+		return nil
+	}
+	out := make([]string, len(p.localActiveInbounds))
+	copy(out, p.localActiveInbounds)
+	return out
+}
+
+// RefreshLocalOnline records that each email in activeEmails and each tag in
+// activeInboundTags had local xray traffic at now, then rebuilds onlineClients
+// and localActiveInbounds from every entry seen within graceMs, pruning older
+// ones. Called by the local XrayTrafficJob after each xray gRPC stats poll.
+// Pass nil/empty slices to only prune — NodeTrafficSyncJob does this so a
+// stopped local xray's clients and inbounds still age out between local polls.
+func (p *Process) RefreshLocalOnline(activeEmails, activeInboundTags []string, now, graceMs int64) {
+	p.onlineMu.Lock()
+	defer p.onlineMu.Unlock()
+	if p.localLastOnline == nil {
+		p.localLastOnline = make(map[string]int64, len(activeEmails))
+	}
+	for _, email := range activeEmails {
+		p.localLastOnline[email] = now
+	}
+	online := make([]string, 0, len(p.localLastOnline))
+	for email, ts := range p.localLastOnline {
+		if now-ts < graceMs {
+			online = append(online, email)
+		} else {
+			delete(p.localLastOnline, email)
+		}
+	}
+	p.onlineClients = online
+
+	if p.localInboundLastActive == nil {
+		p.localInboundLastActive = make(map[string]int64, len(activeInboundTags))
+	}
+	for _, tag := range activeInboundTags {
+		p.localInboundLastActive[tag] = now
+	}
+	activeInbounds := make([]string, 0, len(p.localInboundLastActive))
+	for tag, ts := range p.localInboundLastActive {
+		if now-ts < graceMs {
+			activeInbounds = append(activeInbounds, tag)
+		} else {
+			delete(p.localInboundLastActive, tag)
+		}
+	}
+	p.localActiveInbounds = activeInbounds
+}
+
+// SetNodeOnlineTree records the GUID-keyed online subtree one direct remote
+// node reported (its own clients under its panelGuid plus every descendant
+// under theirs). Replaces any previous entry for that node — NodeTrafficSyncJob
+// always sends the full subtree per tick.
+func (p *Process) SetNodeOnlineTree(nodeID int, tree map[string][]string) {
+	p.onlineMu.Lock()
+	defer p.onlineMu.Unlock()
+	if p.nodeOnlineTrees == nil {
+		p.nodeOnlineTrees = map[int]map[string][]string{}
+	}
+	p.nodeOnlineTrees[nodeID] = tree
+}
+
+// ClearNodeOnlineClients drops a direct node's whole subtree contribution.
+// Called when a probe fails so a downed node — and everything behind it — doesn't
+// keep its clients listed as "online" until the next successful probe.
+func (p *Process) ClearNodeOnlineClients(nodeID int) {
+	p.onlineMu.Lock()
+	defer p.onlineMu.Unlock()
+	delete(p.nodeOnlineTrees, nodeID)
+}
+
+// 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" {
+			p.apiPort = inbound.Port
+			break
+		}
+	}
+}
+
+// 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()
+	if err != nil {
+		p.version = "Unknown"
+	} else {
+		datas := bytes.Split(data, []byte(" "))
+		if len(datas) <= 1 {
+			p.version = "Unknown"
+		} else {
+			p.version = string(datas[1])
+		}
+	}
+}
+
+// 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")
+	}
+
+	defer func() {
+		if err != nil {
+			logger.Error("Failure in running xray-core process: ", err)
+			p.exitErr = err
+		}
+	}()
+
+	data, err := json.MarshalIndent(p.config, "", "  ")
+	if err != nil {
+		return common.NewErrorf("Failed to generate XRAY configuration files: %v", err)
+	}
+
+	err = os.MkdirAll(config.GetLogFolder(), 0o770)
+	if err != nil {
+		logger.Warningf("Failed to create log folder: %s", err)
+	}
+
+	configPath := GetConfigPath()
+	if p.configPath != "" {
+		configPath = p.configPath
+	}
+	err = os.WriteFile(configPath, data, 0644)
+	if err != nil {
+		return common.NewErrorf("Failed to write configuration file: %v", err)
+	}
+
+	cmd := exec.Command(GetBinaryPath(), "-c", configPath)
+	cmd.Stdout = p.logWriter
+	cmd.Stderr = p.logWriter
+
+	err = p.startCommand(cmd)
+	if err != nil {
+		return err
+	}
+
+	p.refreshVersion()
+	p.refreshAPIPort()
+
+	return nil
+}
+
+func (p *process) startCommand(cmd *exec.Cmd) error {
+	p.cmd = cmd
+	p.done = make(chan struct{})
+	p.exitErr = nil
+	p.intentionalStop.Store(false)
+
+	if err := cmd.Start(); err != nil {
+		close(p.done)
+		p.cmd = nil
+		return err
+	}
+
+	attachChildLifetime(cmd)
+
+	go p.waitForCommand(cmd)
+	return nil
+}
+
+func (p *process) waitForCommand(cmd *exec.Cmd) {
+	defer close(p.done)
+
+	err := cmd.Wait()
+	if err == nil || p.intentionalStop.Load() {
+		return
+	}
+
+	// On Windows, killing the process results in "exit status 1" which isn't an error for us.
+	if runtime.GOOS == "windows" {
+		errStr := strings.ToLower(err.Error())
+		if strings.Contains(errStr, "exit status 1") {
+			p.exitErr = err
+			return
+		}
+	}
+
+	logger.Error("Failure in running xray-core:", err)
+	p.exitErr = err
+}
+
+// Stop terminates the running Xray process.
+func (p *process) Stop() error {
+	if !p.IsRunning() {
+		return errors.New("xray is not running")
+	}
+	p.intentionalStop.Store(true)
+
+	// Remove temporary config file used for test runs so main config is never touched
+	if p.configPath != "" {
+		if p.configPath != GetConfigPath() {
+			// Check if file exists before removing
+			if _, err := os.Stat(p.configPath); err == nil {
+				_ = os.Remove(p.configPath)
+			}
+		}
+	}
+
+	if runtime.GOOS == "windows" {
+		if err := p.cmd.Process.Kill(); err != nil && !errors.Is(err, os.ErrProcessDone) {
+			return err
+		}
+		return p.waitForExit(xrayForceStopTimeout)
+	}
+
+	if err := p.cmd.Process.Signal(syscall.SIGTERM); err != nil {
+		if errors.Is(err, os.ErrProcessDone) {
+			return p.waitForExit(xrayForceStopTimeout)
+		}
+		return err
+	}
+
+	if err := p.waitForExit(xrayGracefulStopTimeout); err == nil {
+		return nil
+	}
+
+	logger.Warning("xray-core did not stop after SIGTERM, killing process")
+	if err := p.cmd.Process.Kill(); err != nil && !errors.Is(err, os.ErrProcessDone) {
+		return err
+	}
+	return p.waitForExit(xrayForceStopTimeout)
+}
+
+func (p *process) waitForExit(timeout time.Duration) error {
+	if p.done == nil {
+		return nil
+	}
+
+	timer := time.NewTimer(timeout)
+	defer timer.Stop()
+
+	select {
+	case <-p.done:
+		return nil
+	case <-timer.C:
+		return common.NewErrorf("timed out waiting for xray-core process to stop after %s", timeout)
+	}
+}
+
+const (
+	crashReportPrefix = "core_crash_"
+	crashReportSuffix = ".log"
+	maxCrashReports   = 10
+)
+
+// writeCrashReport persists a captured xray crash chunk to the log folder
+// with nanosecond-precision filename so restart-loop bursts don't overwrite
+// each other, and prunes old reports to keep the folder bounded.
+func writeCrashReport(m []byte) error {
+	dir := config.GetLogFolder()
+	if err := os.MkdirAll(dir, 0o770); err != nil {
+		return err
+	}
+	pruneOldCrashReports(dir, maxCrashReports-1)
+	name := crashReportPrefix + time.Now().Format("20060102_150405_000000000") + crashReportSuffix
+	return os.WriteFile(filepath.Join(dir, name), m, 0o640)
+}
+
+func pruneOldCrashReports(dir string, keep int) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return
+	}
+	var reports []string
+	for _, e := range entries {
+		n := e.Name()
+		if !e.IsDir() && strings.HasPrefix(n, crashReportPrefix) && strings.HasSuffix(n, crashReportSuffix) {
+			reports = append(reports, n)
+		}
+	}
+	if len(reports) <= keep {
+		return
+	}
+	sort.Strings(reports)
+	for _, old := range reports[:len(reports)-keep] {
+		_ = os.Remove(filepath.Join(dir, old))
+	}
+}
@@ -0,0 +1,7 @@
+//go:build !windows
+
+package xray
+
+import "os/exec"
+
+func attachChildLifetime(_ *exec.Cmd) {}
@@ -0,0 +1,162 @@
+//go:build !windows
+
+package xray
+
+import (
+	"os"
+	"os/exec"
+	"os/signal"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+
+	xuilogger "github.com/mhsanaei/3x-ui/v3/internal/logger"
+	"github.com/op/go-logging"
+)
+
+func TestStopWaitsForGracefulExit(t *testing.T) {
+	initProcessTestLogger(t)
+
+	p := startProcessHelper(t, "delayed-term")
+
+	start := time.Now()
+	if err := p.Stop(); err != nil {
+		t.Fatalf("Stop: %v", err)
+	}
+	if elapsed := time.Since(start); elapsed < 150*time.Millisecond {
+		t.Fatalf("Stop returned before child exited; elapsed=%s", elapsed)
+	}
+	if p.IsRunning() {
+		t.Fatal("process still reports running after Stop")
+	}
+}
+
+func TestIntentionalStopDoesNotRecordExitError(t *testing.T) {
+	initProcessTestLogger(t)
+
+	p := startProcessHelper(t, "default-term")
+
+	if err := p.Stop(); err != nil {
+		t.Fatalf("Stop: %v", err)
+	}
+	if err := p.GetErr(); err != nil {
+		t.Fatalf("GetErr after intentional stop = %v, want nil", err)
+	}
+	if result := p.GetResult(); result != "" {
+		t.Fatalf("GetResult after intentional stop = %q, want empty", result)
+	}
+}
+
+func TestStopKillsProcessThatIgnoresSIGTERM(t *testing.T) {
+	initProcessTestLogger(t)
+
+	oldGraceful := xrayGracefulStopTimeout
+	oldForce := xrayForceStopTimeout
+	xrayGracefulStopTimeout = 100 * time.Millisecond
+	xrayForceStopTimeout = 2 * time.Second
+	t.Cleanup(func() {
+		xrayGracefulStopTimeout = oldGraceful
+		xrayForceStopTimeout = oldForce
+	})
+
+	p := startProcessHelper(t, "ignore-term")
+
+	if err := p.Stop(); err != nil {
+		t.Fatalf("Stop: %v", err)
+	}
+	if p.IsRunning() {
+		t.Fatal("process still reports running after forced stop")
+	}
+}
+
+func initProcessTestLogger(t *testing.T) {
+	t.Helper()
+	t.Setenv("XUI_LOG_FOLDER", t.TempDir())
+	xuilogger.InitLogger(logging.ERROR)
+}
+
+func startProcessHelper(t *testing.T, mode string) *process {
+	t.Helper()
+
+	readyPath := filepath.Join(t.TempDir(), "ready")
+	cmd := exec.Command(os.Args[0], "-test.run=TestXrayProcessHelper", "--", mode)
+	cmd.Env = append(os.Environ(),
+		"XRAY_PROCESS_HELPER=1",
+		"XRAY_PROCESS_READY="+readyPath,
+	)
+
+	p := newProcess(nil)
+	if err := p.startCommand(cmd); err != nil {
+		t.Fatalf("start helper process: %v", err)
+	}
+	waitForProcessHelperReady(t, readyPath)
+
+	t.Cleanup(func() {
+		if p.IsRunning() {
+			p.intentionalStop.Store(true)
+			_ = p.cmd.Process.Kill()
+			_ = p.waitForExit(2 * time.Second)
+		}
+	})
+
+	return p
+}
+
+func waitForProcessHelperReady(t *testing.T, readyPath string) {
+	t.Helper()
+
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if _, err := os.Stat(readyPath); err == nil {
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatalf("helper process did not become ready")
+}
+
+func TestXrayProcessHelper(t *testing.T) {
+	if os.Getenv("XRAY_PROCESS_HELPER") != "1" {
+		return
+	}
+
+	mode := ""
+	for i, arg := range os.Args {
+		if arg == "--" && i+1 < len(os.Args) {
+			mode = os.Args[i+1]
+			break
+		}
+	}
+
+	switch mode {
+	case "delayed-term":
+		sigCh := make(chan os.Signal, 1)
+		signal.Notify(sigCh, syscall.SIGTERM)
+		markProcessHelperReady(t)
+		<-sigCh
+		time.Sleep(200 * time.Millisecond)
+		os.Exit(0)
+	case "default-term":
+		markProcessHelperReady(t)
+		select {}
+	case "ignore-term":
+		signal.Ignore(syscall.SIGTERM)
+		markProcessHelperReady(t)
+		select {}
+	default:
+		t.Fatalf("unknown helper mode %q", mode)
+	}
+}
+
+func markProcessHelperReady(t *testing.T) {
+	t.Helper()
+
+	readyPath := os.Getenv("XRAY_PROCESS_READY")
+	if readyPath == "" {
+		t.Fatal("XRAY_PROCESS_READY is not set")
+	}
+	if err := os.WriteFile(readyPath, []byte("ready"), 0644); err != nil {
+		t.Fatalf("write helper ready file: %v", err)
+	}
+}
@@ -0,0 +1,66 @@
+//go:build windows
+
+package xray
+
+import (
+	"os/exec"
+	"sync"
+	"unsafe"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/logger"
+	"golang.org/x/sys/windows"
+)
+
+var (
+	killOnExitJobOnce sync.Once
+	killOnExitJob     windows.Handle
+	killOnExitJobErr  error
+)
+
+func ensureKillOnExitJob() (windows.Handle, error) {
+	killOnExitJobOnce.Do(func() {
+		h, err := windows.CreateJobObject(nil, nil)
+		if err != nil {
+			killOnExitJobErr = err
+			return
+		}
+		info := windows.JOBOBJECT_EXTENDED_LIMIT_INFORMATION{
+			BasicLimitInformation: windows.JOBOBJECT_BASIC_LIMIT_INFORMATION{
+				LimitFlags: windows.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
+			},
+		}
+		_, err = windows.SetInformationJobObject(
+			h,
+			windows.JobObjectExtendedLimitInformation,
+			uintptr(unsafe.Pointer(&info)),
+			uint32(unsafe.Sizeof(info)),
+		)
+		if err != nil {
+			windows.CloseHandle(h)
+			killOnExitJobErr = err
+			return
+		}
+		killOnExitJob = h
+	})
+	return killOnExitJob, killOnExitJobErr
+}
+
+func attachChildLifetime(cmd *exec.Cmd) {
+	if cmd == nil || cmd.Process == nil {
+		return
+	}
+	job, err := ensureKillOnExitJob()
+	if err != nil {
+		logger.Warning("xray: kill-on-exit job unavailable:", err)
+		return
+	}
+	h, err := windows.OpenProcess(windows.PROCESS_SET_QUOTA|windows.PROCESS_TERMINATE, false, uint32(cmd.Process.Pid))
+	if err != nil {
+		logger.Warning("xray: OpenProcess for job attach failed:", err)
+		return
+	}
+	defer windows.CloseHandle(h)
+	if err := windows.AssignProcessToJobObject(job, h); err != nil {
+		logger.Warning("xray: AssignProcessToJobObject failed:", err)
+	}
+}
@@ -0,0 +1,11 @@
+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
+	Tag        string
+	Up         int64
+	Down       int64
+}