Document layered invoke env behavior

Author: yiguo

README.md

@@ -153,7 +153,12 @@ The response is a JSON object:
 ```
 
 `env` is optional and only supports Xray-core environment variables that are
-explicitly modeled by libXray:
+explicitly modeled by libXray. Passing `env` sets process environment variables
+and reloads Xray-core's process-global env-backed settings before the method
+continues. It is primarily used for load-stage keys and runtime values that are
+not known when the Xray JSON is generated. Reloadable runtime keys can also be
+declared in the Xray config root `env` object, which is applied during config
+build and overrides same-name external values.
 
 | JSON key | Meaning |
 | --- | --- |
@@ -178,7 +183,10 @@ Design notes:
 2. Unknown `env` keys are ignored and are not written to the process environment.
 3. `env` only sets modeled, non-empty fields. Missing fields are not unset.
 4. libXray does not restore previous environment values after a method returns. Callers must pass the required env fields on every request that depends on them. This avoids concurrent calls restoring stale values over newer values.
-5. `SetTunFd` has been removed. Pass `xray.tun.fd` in the `env` object of the `runXray` request.
+5. `xray.json.strict`, `xray.location.config`, and `xray.location.confdir` are load-stage keys and must stay outside the Xray JSON config.
+6. Xray config root `env` does not accept those three load-stage keys. Other reloadable keys declared there override same-name values from `Invoke.env`.
+7. `env` reloads Xray-core process-global env-backed settings. It does not provide per-instance environment isolation.
+8. `SetTunFd` has been removed. Pass `xray.tun.fd` in the `env` object of the `runXray` request when the fd is only known at runtime.
 
 Supported methods:
 

invoke.go

@@ -26,7 +26,9 @@ func Invoke(requestJSON string) string {
 	if err := validateAPIVersion(request.APIVersion); err != nil {
 		return encodeInvokeResponse(nil, err)
 	}
-	applyEnv(request.Env)
+	if err := applyEnv(request.Env); err != nil {
+		return encodeInvokeResponse(nil, err)
+	}
 
 	switch request.Method {
 	case LibXrayMethodGetFreePorts:
@@ -63,9 +65,9 @@ func validateAPIVersion(version int) error {
 	return errors.New("unsupported apiVersion")
 }
 
-func applyEnv(env *LibXrayEnvJson) {
+func applyEnv(env *LibXrayEnvJson) error {
 	if env == nil {
-		return
+		return nil
 	}
 	setEnvIfNotEmpty(platform.ConfigLocation, env.ConfigLocation)
 	setEnvIfNotEmpty(platform.ConfdirLocation, env.ConfdirLocation)
@@ -81,6 +83,7 @@ func applyEnv(env *LibXrayEnvJson) {
 	setEnvIfNotEmpty(platform.XUDPLog, env.XUDPLog)
 	setEnvIfNotEmpty(platform.XUDPBaseKey, env.XUDPBaseKey)
 	setEnvIfNotEmpty(platform.TunFdKey, env.TunFd)
+	return platform.ReloadEnvSettings()
 }
 
 func setEnvIfNotEmpty(key string, value string) {

invoke_test.go

@@ -1,13 +1,15 @@
 package libXray
 
 import (
+	"bytes"
 	"encoding/base64"
 	"encoding/json"
 	"os"
 	"path/filepath"
 	"testing"
 
 	"github.com/xtls/xray-core/common/platform"
+	"github.com/xtls/xray-core/infra/conf/serial"
 )
 
 type testResponse struct {
@@ -282,7 +284,7 @@ func TestInvokeSetsAllSupportedEnvFields(t *testing.T) {
 		{"buffer size", platform.BufferSize, "buffer-size-value"},
 		{"browser dialer", platform.BrowserDialerAddress, "browser-dialer-value"},
 		{"xudp log", platform.XUDPLog, "xudp-log-value"},
-		{"xudp base key", platform.XUDPBaseKey, "xudp-base-key-value"},
+		{"xudp base key", platform.XUDPBaseKey, base64.RawURLEncoding.EncodeToString(bytes.Repeat([]byte{7}, 32))},
 		{"tun fd", platform.TunFdKey, "123"},
 	}
 	for _, tt := range tests {
@@ -303,6 +305,37 @@ func TestInvokeSetsAllSupportedEnvFields(t *testing.T) {
 	}
 }
 
+func TestInvokeEnvReloadsXrayCoreSettings(t *testing.T) {
+	original, existed := os.LookupEnv(platform.UseStrictJSON)
+	_ = os.Setenv(platform.UseStrictJSON, "false")
+	platform.ReloadEnvSettings()
+	t.Cleanup(func() {
+		if existed {
+			_ = os.Setenv(platform.UseStrictJSON, original)
+		} else {
+			_ = os.Unsetenv(platform.UseStrictJSON)
+		}
+		platform.ReloadEnvSettings()
+	})
+
+	if serial.IsStrictJSONEnabled() {
+		t.Fatal("strict JSON should start disabled")
+	}
+
+	response := invokeForTest(
+		t,
+		LibXrayMethodXrayVersion,
+		&LibXrayEnvJson{UseStrictJSON: "true"},
+		nil,
+	)
+	if !response.Success {
+		t.Fatalf("XrayVersion failed: %s", response.Err)
+	}
+	if !serial.IsStrictJSONEnabled() {
+		t.Fatal("Invoke.env did not reload strict JSON setting")
+	}
+}
+
 func TestInvokeUnknownMethod(t *testing.T) {
 	response := invokeForTest(t, LibXrayMethod("unknown"), nil, nil)
 	if response.Success {

readme/README.zh_CN.md

@@ -120,7 +120,10 @@ char* CGoInvoke(char* requestJSON);
 }
 ```
 
-`env` 是可选字段，只支持 libXray 显式建模的 Xray-core 环境变量：
+`env` 是可选字段，只支持 libXray 显式建模的 Xray-core 环境变量。传入 `env`
+会写入进程环境变量，并在 method 继续执行前 reload Xray-core 的进程全局 env-backed settings。
+它主要用于加载前 key，以及生成 Xray JSON 时还不知道的运行时值。可 reload 的运行时 key
+也可以写在 Xray 配置根 `env` 对象中；配置根 `env` 会在 config build 阶段应用，并覆盖同名外部值。
 
 | JSON key | 含义 |
 | --- | --- |
@@ -145,7 +148,10 @@ char* CGoInvoke(char* requestJSON);
 2. 未知 `env` key 会被忽略，不会写入进程环境变量。
 3. `env` 只设置已建模的非空字段，缺失字段不会 unset。
 4. libXray 不会在 method 结束后 restore 旧环境变量。调用方必须在每次依赖环境变量的请求中显式传入对应字段。这样可以避免并发调用时，一个请求恢复旧值覆盖另一个请求的新值。
-5. `SetTunFd` 已删除。请在 `runXray` 请求的 `env` 对象中传入 `xray.tun.fd`。
+5. `xray.json.strict`、`xray.location.config`、`xray.location.confdir` 属于加载前 key，必须保留在 Xray JSON 配置外部。
+6. Xray 配置根 `env` 不接受上述三个加载前 key；其他可 reload key 写在配置根 `env` 时会覆盖 `Invoke.env` 中的同名值。
+7. `env` reload 的是 Xray-core 进程全局 env-backed settings，不提供 per-instance 环境隔离。
+8. `SetTunFd` 已删除。如果 fd 只能在运行时获得，请在 `runXray` 请求的 `env` 对象中传入 `xray.tun.fd`。
 
 支持的 method：