Restore invoke env and desktop wrapper

Author: yiguo

.github/workflows/build.yml

@@ -147,11 +147,13 @@ jobs:
               mkdir -p "dist/${{ matrix.artifact }}"
               cp linux_so/libXray.so "dist/${{ matrix.artifact }}/"
               cp linux_so/libXray.h "dist/${{ matrix.artifact }}/"
+              cp bin/xray "dist/${{ matrix.artifact }}/"
               ;;
             windows)
               mkdir -p "dist/${{ matrix.artifact }}"
               cp windows_dll/libXray.dll "dist/${{ matrix.artifact }}/"
               cp windows_dll/libXray.h "dist/${{ matrix.artifact }}/"
+              cp bin/xray.exe "dist/${{ matrix.artifact }}/"
               ;;
             android)
               mkdir -p "dist/${{ matrix.artifact }}"

README.md

@@ -42,7 +42,9 @@ depends on git and go.
 
 By default, the build script does not clone [Xray-core](https://github.com/XTLS/Xray-core). It uses Go modules and pins Xray-core to tag `v26.6.27` (recorded by Go as the matching pseudo-version).
 Pass the optional `local` argument to use an existing local checkout at `../Xray-core` through a Go module `replace`.
-Linux and Windows builds only produce the libXray shared library. Applications that need a standalone Xray executable should use official Xray-core release binaries.
+Linux and Windows builds also produce a small desktop wrapper executable:
+`bin/xray` or `bin/xray.exe`. The wrapper accepts `-configPath` pointing to a
+`LibXrayInvokeRequest` JSON file whose method is `runXray`.
 
 ### Usage
 
@@ -130,6 +132,11 @@ The request is a JSON object:
 {
   "apiVersion": 1,
   "method": "runXray",
+  "env": {
+    "xray.location.asset": "/path/to/dat",
+    "xray.location.cert": "/path/to/dat",
+    "xray.tun.fd": "123"
+  },
   "payload": {
     "configPath": "/path/to/config.json"
   }
@@ -148,14 +155,16 @@ The response is a JSON object:
 
 Design notes:
 
-1. `Invoke` does not accept an `env` field. Runtime Xray-core environment
-   settings must be written into the Xray config root `env` object.
-2. `xray.json.strict`, `xray.location.config`, and `xray.location.confdir` are
+1. `Invoke.env` supports only fixed Xray-core runtime environment keys:
+   `xray.location.asset`, `xray.location.cert`, and `xray.tun.fd`.
+2. Non-empty `env` fields are set on the process before the method runs.
+   Missing fields are not unset and old values are not restored.
+3. `xray.json.strict`, `xray.location.config`, and `xray.location.confdir` are
    load-stage process environment variables and cannot be supplied through
-   `Invoke`.
-3. `SetTunFd` has been removed. Write `xray.tun.fd` into the Xray config root
-   `env` object before calling `runXray` when the fd is only known at runtime.
-4. `countGeoData` is not backed by an Xray config, so its `datDir` is passed in
+   `Invoke.env`.
+4. `SetTunFd` has been removed. Use `Invoke.env["xray.tun.fd"]` when the fd is
+   only known at runtime.
+5. `countGeoData` is not backed by an Xray config, so its `datDir` is passed in
    the method payload.
 
 Supported methods:

build/app/build.py

@@ -4,6 +4,7 @@
 import subprocess
 
 from app.cmd import (
+    create_dir_if_not_exists,
     delete_file_if_exists,
     delete_dir_if_exists,
 )
@@ -142,6 +143,28 @@ def before_build(self):
     def build(self):
         pass
 
+    def build_desktop_bin(self, bin_file: str):
+        bin_dir = os.path.join(self.lib_dir, "bin")
+        create_dir_if_not_exists(bin_dir)
+        output_file = os.path.join(bin_dir, bin_file)
+        run_env = os.environ.copy()
+        run_env["CGO_ENABLED"] = "0"
+
+        cmd = [
+            "go",
+            "build",
+            "-trimpath",
+            "-ldflags",
+            "-s -w",
+            f"-o={output_file}",
+            "./desktop_bin",
+        ]
+        os.chdir(self.lib_dir)
+        print(cmd)
+        ret = subprocess.run(cmd, env=run_env)
+        if ret.returncode != 0:
+            raise Exception("build_desktop_bin failed")
+
     def after_build(self):
         pass
 

build/app/linux.py

@@ -13,6 +13,7 @@ def __init__(self, build_dir: str, use_local_xray_core: bool = False):
         create_dir_if_not_exists(self.framework_dir)
         self.lib_file = "libXray.so"
         self.lib_header_file = "libXray.h"
+        self.bin_file = "xray"
 
     def before_build(self):
         super().before_build()
@@ -22,6 +23,7 @@ def build(self):
         self.before_build()
         self.build_linux()
         self.after_build()
+        self.build_desktop_bin(self.bin_file)
         self.revert_go_env()
 
     def build_linux(self):

build/app/windows.py

@@ -13,6 +13,7 @@ def __init__(self, build_dir: str, use_local_xray_core: bool = False):
         create_dir_if_not_exists(self.framework_dir)
         self.lib_file = "libXray.dll"
         self.lib_header_file = "libXray.h"
+        self.bin_file = "xray.exe"
 
     def before_build(self):
         super().before_build()
@@ -22,6 +23,7 @@ def build(self):
         self.before_build()
         self.build_windows()
         self.after_build()
+        self.build_desktop_bin(self.bin_file)
         self.revert_go_env()
 
     def build_windows(self):

desktop_bin/main.go

@@ -0,0 +1,29 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+	"os/signal"
+	"runtime"
+	"runtime/debug"
+	"syscall"
+)
+
+func main() {
+	configPath := flag.String("configPath", "config.json", "Path of libXray invoke request json")
+	flag.Parse()
+
+	if err := runXray(*configPath); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	defer stopXray()
+
+	runtime.GC()
+	debug.FreeOSMemory()
+
+	osSignals := make(chan os.Signal, 1)
+	signal.Notify(osSignals, os.Interrupt, syscall.SIGTERM)
+	<-osSignals
+}

desktop_bin/run.go

@@ -0,0 +1,54 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+
+	libXray "github.com/xtls/libxray"
+)
+
+type invokeResponse struct {
+	Success bool   `json:"success"`
+	Err     string `json:"error"`
+}
+
+func runXray(configPath string) error {
+	requestBytes, err := os.ReadFile(configPath)
+	if err != nil {
+		return err
+	}
+
+	var request libXray.LibXrayInvokeRequest
+	if err := json.Unmarshal(requestBytes, &request); err != nil {
+		return err
+	}
+	if request.Method != libXray.LibXrayMethodRunXray {
+		return fmt.Errorf("unsupported method %q: desktop_bin only supports runXray", request.Method)
+	}
+
+	responseText := libXray.Invoke(string(requestBytes))
+	var response invokeResponse
+	if err := json.Unmarshal([]byte(responseText), &response); err != nil {
+		return err
+	}
+	if !response.Success {
+		if response.Err == "" {
+			response.Err = "runXray failed"
+		}
+		return errors.New(response.Err)
+	}
+	return nil
+}
+
+func stopXray() {
+	requestBytes, err := json.Marshal(&libXray.LibXrayInvokeRequest{
+		APIVersion: 1,
+		Method:     libXray.LibXrayMethodStopXray,
+	})
+	if err != nil {
+		return
+	}
+	_ = libXray.Invoke(string(requestBytes))
+}

invoke.go

@@ -3,11 +3,13 @@ package libXray
 import (
 	"encoding/json"
 	"errors"
+	"os"
 
 	"github.com/xtls/libxray/geo"
 	"github.com/xtls/libxray/nodep"
 	"github.com/xtls/libxray/share"
 	"github.com/xtls/libxray/xray"
+	"github.com/xtls/xray-core/common/platform"
 )
 
 type invokeResponse struct {
@@ -24,6 +26,7 @@ func Invoke(requestJSON string) string {
 	if err := validateAPIVersion(request.APIVersion); err != nil {
 		return encodeInvokeResponse(nil, err)
 	}
+	applyEnv(request.Env)
 
 	switch request.Method {
 	case LibXrayMethodGetFreePorts:
@@ -53,6 +56,22 @@ func Invoke(requestJSON string) string {
 	}
 }
 
+func applyEnv(env *LibXrayEnvJson) {
+	if env == nil {
+		return
+	}
+	setEnvIfNotEmpty(platform.AssetLocation, env.AssetLocation)
+	setEnvIfNotEmpty(platform.CertLocation, env.CertLocation)
+	setEnvIfNotEmpty(platform.TunFdKey, env.TunFd)
+}
+
+func setEnvIfNotEmpty(key string, value string) {
+	if value == "" {
+		return
+	}
+	_ = os.Setenv(key, value)
+}
+
 func validateAPIVersion(version int) error {
 	if version == 0 || version == 1 {
 		return nil

invoke_model.go

@@ -22,9 +22,16 @@ const (
 type LibXrayInvokeRequest struct {
 	APIVersion int             `json:"apiVersion,omitempty"`
 	Method     LibXrayMethod   `json:"method,omitempty"`
+	Env        *LibXrayEnvJson `json:"env,omitempty"`
 	Payload    json.RawMessage `json:"payload,omitempty"`
 }
 
+type LibXrayEnvJson struct {
+	AssetLocation string `json:"xray.location.asset,omitempty"`
+	CertLocation  string `json:"xray.location.cert,omitempty"`
+	TunFd         string `json:"xray.tun.fd,omitempty"`
+}
+
 type GetFreePortsRequest struct {
 	Count int `json:"count,omitempty"`
 }

invoke_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	"github.com/xtls/libxray/nodep"
+	"github.com/xtls/xray-core/common/platform"
 )
 
 type testResponse struct {
@@ -337,7 +338,28 @@ func TestInvokeNoDataResponseShape(t *testing.T) {
 	}
 }
 
-func TestInvokeIgnoresTopLevelEnv(t *testing.T) {
+func TestInvokeAppliesSupportedEnv(t *testing.T) {
+	restoreEnv(t, platform.AssetLocation)
+	restoreEnv(t, platform.CertLocation)
+	restoreEnv(t, platform.TunFdKey)
+
+	requestJSON := `{"apiVersion":1,"method":"xrayVersion","env":{"xray.location.asset":"/tmp/assets","xray.location.cert":"/tmp/certs","xray.tun.fd":"123"}}`
+	response := invokeRawForTest(t, requestJSON)
+	if !response.Success {
+		t.Fatalf("xrayVersion failed: %s", response.Err)
+	}
+	if got := os.Getenv(platform.AssetLocation); got != "/tmp/assets" {
+		t.Fatalf("%s = %q", platform.AssetLocation, got)
+	}
+	if got := os.Getenv(platform.CertLocation); got != "/tmp/certs" {
+		t.Fatalf("%s = %q", platform.CertLocation, got)
+	}
+	if got := os.Getenv(platform.TunFdKey); got != "123" {
+		t.Fatalf("%s = %q", platform.TunFdKey, got)
+	}
+}
+
+func TestInvokeIgnoresUnknownEnvKeys(t *testing.T) {
 	const key = "XRAY_LIBXRAY_UNKNOWN_ENV_TEST"
 	_ = os.Unsetenv(key)
 	t.Cleanup(func() { _ = os.Unsetenv(key) })
@@ -347,13 +369,26 @@ func TestInvokeIgnoresTopLevelEnv(t *testing.T) {
 		t.Fatal(err)
 	}
 	if !response.Success {
-		t.Fatalf("top-level env should be ignored: %s", response.Err)
+		t.Fatalf("unknown env should be ignored: %s", response.Err)
 	}
 	if _, found := os.LookupEnv(key); found {
-		t.Fatal("top-level env should not be set")
+		t.Fatal("unknown env should not be set")
 	}
 }
 
+func restoreEnv(t *testing.T, key string) {
+	t.Helper()
+	oldValue, found := os.LookupEnv(key)
+	_ = os.Unsetenv(key)
+	t.Cleanup(func() {
+		if found {
+			_ = os.Setenv(key, oldValue)
+		} else {
+			_ = os.Unsetenv(key)
+		}
+	})
+}
+
 func xrayStopForTest(t *testing.T) {
 	t.Helper()
 	response := invokeForTest(t, LibXrayMethodStopXray, nil)