Merge pull request #371 from nxtrace/main

Enhance NextTrace API v4 GeoIP support and improve MTR handling

Author: tsosunchia

AGENTS.md

@@ -23,6 +23,15 @@
   接口），并在 `ReadFrom` 中调用 `stripIPv4Header` 剥离 macOS DGRAM ICMP socket
   返回的外层 IP 头。
 
+## Git 与提交信息规范（必须遵守）
+
+- Commit message 必须使用 Conventional Commits 风格：`type(scope): 具体行为`。
+- subject 必须描述该提交实际改变的行为或约束，不能只写“处理 review 问题”“修复剩余问题”“调整代码”等泛化内容。
+- review finding 修复提交也必须写明具体修复点，例如 timeout、fallback、权限校验、stdout/stderr 分离；若一个提交覆盖多个 finding，用 body bullet 简短列出。
+- 一个提交包含多个互不相关主题时，优先拆分提交；确实需要放在一起时，subject 写主影响，body 写清每个具体改动。
+- 提交或 push PR 前必须检查 `git log --oneline main..HEAD`，发现泛化、误导或与 diff 不匹配的 commit message，应先 reword/amend。
+- 改写已推送 PR 分支历史后，只使用 `git push --force-with-lease`，不要用无保护的强推覆盖远端新提交。
+
 ## 当前 CLI 语义（重点）
 
 ### 常规 traceroute 路径

README.md

@@ -639,6 +639,19 @@ export NEXTTRACE_CHUNZHENURL=http://127.0.0.1:2060
 export NEXTTRACE_DATAPROVIDER=ipinfo
 ```
 
+LeoMoeAPI keeps the old v3 WebSocket API as the default when no NextTrace API v4 token is available. To use the NextTrace API v4 HTTP GeoIP endpoint for the current shell session, run the setup command and paste your token:
+
+```bash
+# Token page:
+# GET https://api.nxtrace.org/v4/api-tokens
+
+nexttrace -x
+```
+
+`nexttrace -x` stores the token in temporary files: one scoped to the parent process ID, which is normally your current shell, and one same-user fallback file for wrapper commands such as `go run`. Later `nexttrace` commands first read the real `NEXTTRACE_API_V4_TOKEN`, then the parent-PID file, then the fallback file, and load the value into the process-local environment. The command does not write shell profiles, permanent environment variables, or `nt_config.yaml`.
+
+With `NEXTTRACE_API_V4_TOKEN` set and the active provider still `LeoMoeAPI`, NextTrace queries `GET https://api.nxtrace.org/v4/ipGeo?ip=<ip>` with `X-NextTrace-Token: <token>`. The request has no JSON body. Successful responses are direct GeoIP JSON mapped to the normal output fields; quota metadata is exposed only in headers (`X-NextTrace-Quota-Remaining`, `X-NextTrace-Quota-Expires-At`, `X-NextTrace-Quota-Cost`, `X-NextTrace-Quota-Source`) and does not change the default output format. Error responses prefer `{"error":{"message":"..."}}`; known statuses include `400` for empty/illegal IP, `401` unauthorized, `429` quota exhausted, and `500` internal server error. NextTrace API v4 token failures do not fall back to the old v3 WebSocket API.
+
 #### `NextTrace` supports mixed parameters and shortened parameters
 
 ```bash
@@ -708,6 +721,7 @@ NextTrace currently reads the following environment variables. For boolean switc
 | --- | --- | --- |
 | `NEXTTRACE_HOSTPORT` | `api.nxtrace.org` | Override the backend host or `host:port` used by LeoMoeAPI, tracemap, and FastIP flows. |
 | `NEXTTRACE_TOKEN` | unset | Pre-supplied LeoMoeAPI bearer token; when present, token fetching via PoW is skipped. |
+| `NEXTTRACE_API_V4_TOKEN` | unset | LeoMoeAPI NextTrace API v4 HTTP GeoIP token. When unset, NextTrace also checks the temporary token files written by `nexttrace -x`; if neither exists, LeoMoeAPI keeps using the old v3 WebSocket / PoW flow. |
 | `NEXTTRACE_POWPROVIDER` | `api.nxtrace.org` | Select the PoW provider. The built-in non-default alias is `sakura`. |
 | `NEXTTRACE_DEPLOY_ADDR` | unset | Default listen address for `--deploy` when `--listen` is not provided. |
 | `NEXTTRACE_DEPLOY_TOKEN` | unset | Token for `--deploy` WebUI/API/WebSocket/MCP access. CLI `--deploy-token` takes precedence. |
@@ -746,7 +760,7 @@ Usage: nexttrace [-h|--help] [--init] [-4|--ipv4] [-6|--ipv6] [-T|--tcp]
                  [-a|--always-rdns] [-P|--route-path] [--dn42] [-o|--output
                  "<value>"] [-O|--output-default] [--table] [--raw]
                  [-j|--json] [-c|--classic] [-f|--first <integer>] [-M|--map]
-                 [-e|--disable-mpls] [-V|--version]
+                 [-e|--disable-mpls] [-V|--version] [-x|--setup-api-v4-token]
                  [-s|--source "<value>"] [--source-port <integer>] [-D|--dev
                  "<value>"] [--listen "<value>"] [--deploy-token "<value>"]
                  [--mcp] [--deploy] [-z|--send-time <integer>]
@@ -822,6 +836,8 @@ Arguments:
   -M  --map                          Disable Print Trace Map
   -e  --disable-mpls                 Disable MPLS
   -V  --version                      Print version info and exit
+  -x  --setup-api-v4-token           Store a session-only NextTrace API v4
+                                     token in a temporary file and exit
   -s  --source                       Use source address src_addr for outgoing
                                      packets
       --source-port                  Use source port src_port for outgoing

README_zh_CN.md

@@ -630,6 +630,19 @@ export NEXTTRACE_CHUNZHENURL=http://127.0.0.1:2060
 export NEXTTRACE_DATAPROVIDER=ipinfo
 ```
 
+没有可用的 NextTrace API v4 token 时，LeoMoeAPI 默认仍使用旧 v3 WebSocket API。只想在当前 shell 会话启用 NextTrace API v4 HTTP GeoIP 接口时，运行设置命令并粘贴 token：
+
+```bash
+# Token 页面：
+# GET https://api.nxtrace.org/v4/api-tokens
+
+nexttrace -x
+```
+
+`nexttrace -x` 会把 token 写入临时文件：一个按父进程 PID 区分（父进程通常就是当前 shell），另一个是同用户 fallback 文件，用于 `go run` 这类 wrapper 命令。之后启动的 `nexttrace` 会按真实 `NEXTTRACE_API_V4_TOKEN`、父 PID 文件、fallback 文件的顺序读取，并把值加载到当前进程环境。该命令不会写 shell profile、永久环境变量或 `nt_config.yaml`。
+
+设置 `NEXTTRACE_API_V4_TOKEN` 且当前数据源仍为 `LeoMoeAPI` 时，NextTrace 会请求 `GET https://api.nxtrace.org/v4/ipGeo?ip=<ip>`，并只通过 `X-NextTrace-Token: <token>` 请求头传 token；请求没有 JSON body。成功响应是直接映射到现有输出字段的 GeoIP JSON；配额信息只解析响应头（`X-NextTrace-Quota-Remaining`、`X-NextTrace-Quota-Expires-At`、`X-NextTrace-Quota-Cost`、`X-NextTrace-Quota-Source`），不改变默认输出格式。错误响应优先解析 `{"error":{"message":"..."}}`；已知状态包括 `400` 空/非法 IP、`401` unauthorized、`429` quota exhausted、`500` internal server error。NextTrace API v4 token 模式下的错误不会 fallback 到旧 v3 WebSocket API。
+
 #### `NextTrace`支持使用混合参数和简略参数
 
 ```bash
@@ -684,6 +697,7 @@ NextTrace 当前会读取下列环境变量。对于布尔开关，只识别 `1`
 | --- | --- | --- |
 | `NEXTTRACE_HOSTPORT` | `api.nxtrace.org` | 覆盖 LeoMoeAPI、tracemap、FastIP 等使用的后端地址，支持 `host` 或 `host:port`。 |
 | `NEXTTRACE_TOKEN` | 未设置 | 预置 LeoMoeAPI Bearer Token；设置后将跳过 PoW 取 token 流程。 |
+| `NEXTTRACE_API_V4_TOKEN` | 未设置 | LeoMoeAPI NextTrace API v4 HTTP GeoIP token。未设置时，NextTrace 还会检查 `nexttrace -x` 写入的临时 token 文件；两者都不存在时，LeoMoeAPI 仍使用旧 v3 WebSocket / PoW 流程。 |
 | `NEXTTRACE_POWPROVIDER` | `api.nxtrace.org` | 指定 PoW 服务提供方；当前内置的非默认别名为 `sakura`。 |
 | `NEXTTRACE_DEPLOY_ADDR` | 未设置 | `--deploy` 模式下，当未传 `--listen` 时使用的默认监听地址。 |
 | `NEXTTRACE_DEPLOY_TOKEN` | 未设置 | `--deploy` WebUI/API/WebSocket/MCP 访问 token。CLI `--deploy-token` 优先级更高。 |
@@ -722,7 +736,7 @@ Usage: nexttrace [-h|--help] [--init] [-4|--ipv4] [-6|--ipv6] [-T|--tcp]
                  [-a|--always-rdns] [-P|--route-path] [--dn42] [-o|--output
                  "<value>"] [-O|--output-default] [--table] [--raw]
                  [-j|--json] [-c|--classic] [-f|--first <integer>] [-M|--map]
-                 [-e|--disable-mpls] [-V|--version]
+                 [-e|--disable-mpls] [-V|--version] [-x|--setup-api-v4-token]
                  [-s|--source "<value>"] [--source-port <integer>] [-D|--dev
                  "<value>"] [--listen "<value>"] [--deploy-token "<value>"]
                  [--mcp] [--deploy] [-z|--send-time <integer>]
@@ -798,6 +812,8 @@ Arguments:
   -M  --map                          Disable Print Trace Map
   -e  --disable-mpls                 Disable MPLS
   -V  --version                      Print version info and exit
+  -x  --setup-api-v4-token           Store a session-only NextTrace API v4
+                                     token in a temporary file and exit
   -s  --source                       Use source address src_addr for outgoing
                                      packets
       --source-port                  Use source port src_port for outgoing

cmd/cmd.go

@@ -49,7 +49,10 @@ const (
 )
 
 var (
-	domainLookupFn = util.DomainLookUpWithContext
+	domainLookupFn                = util.DomainLookUpWithContext
+	prepareNextTraceAPIV4FastIPFn = ipgeo.PrepareNextTraceAPIV4FastIP
+	newLeoWebsocketFn             = wshandle.NewWithContext
+	newLeoWebsocketAsyncFn        = wshandle.NewWithContextAsync
 )
 
 func normalizeListenAddr(addr string) string {
@@ -884,12 +887,17 @@ func initLeoWebsocket(ctx context.Context, dataOrigin, powProvider *string, asyn
 	if !strings.EqualFold(*dataOrigin, "LEOMOEAPI") {
 		return nil
 	}
+	if ipgeo.NextTraceAPIV4TokenConfigured() {
+		if err := prepareNextTraceAPIV4FastIPFn(ctx, true); err == nil {
+			return nil
+		}
+	}
 
 	var leoWs *wshandle.WsConn
 	if async {
-		leoWs = wshandle.NewWithContextAsync(ctx)
+		leoWs = newLeoWebsocketAsyncFn(ctx)
 	} else {
-		leoWs = wshandle.NewWithContext(ctx)
+		leoWs = newLeoWebsocketFn(ctx)
 	}
 	return leoWs
 }
@@ -1208,6 +1216,7 @@ func Execute() {
 	disableMaptrace := registerDisableMaptraceFlag(parser)
 	disableMPLS := parser.Flag("e", "disable-mpls", &argparse.Options{Help: "Disable MPLS"})
 	ver := parser.Flag("V", "version", &argparse.Options{Help: "Print version info and exit"})
+	setupNextTraceAPIV4Token := parser.Flag("x", "setup-api-v4-token", &argparse.Options{Help: "Store a session-only NextTrace API v4 token in a temporary file"})
 	speedMode := registerSpeedFlag(parser)
 	naliMode := registerNaliFlag(parser)
 	srcAddr := parser.String("s", "source", &argparse.Options{Help: "Use source address src_addr for outgoing packets"})
@@ -1255,6 +1264,16 @@ func Execute() {
 		fmt.Print(sanitizeUsagePositionalArgs(parser.Usage(err)))
 		return
 	}
+	if *setupNextTraceAPIV4Token {
+		if err := runNextTraceAPIV4TokenSetup(nextTraceAPIV4TokenSetupOptions{
+			stdin:  os.Stdin,
+			stdout: os.Stdout,
+			stderr: os.Stderr,
+		}); err != nil {
+			os.Exit(handleNextTraceAPIV4TokenSetupError(os.Stderr, err))
+		}
+		return
+	}
 	rootCtx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 	util.SrcDev = ""

cmd/cmd_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/nxtrace/NTrace-core/trace"
 	"github.com/nxtrace/NTrace-core/tracelog"
 	"github.com/nxtrace/NTrace-core/util"
+	"github.com/nxtrace/NTrace-core/wshandle"
 )
 
 func TestLookupTargetIPHonorsContextCancellation(t *testing.T) {
@@ -67,6 +68,74 @@ func TestLookupTargetIPOrExitReturnsFalseOnContextDeadline(t *testing.T) {
 	}
 }
 
+func TestInitLeoWebsocketSkipsV3WhenNextTraceAPIV4TokenConfigured(t *testing.T) {
+	t.Setenv(util.EnvNextTraceAPIV4TokenKey, "v4-token")
+	oldPrepare := prepareNextTraceAPIV4FastIPFn
+	oldNewLeo := newLeoWebsocketFn
+	var prepareCalls int
+	var wsCalls int
+	prepareNextTraceAPIV4FastIPFn = func(ctx context.Context, enableOutput bool) error {
+		prepareCalls++
+		if ctx == nil {
+			t.Fatal("PrepareNextTraceAPIV4FastIP context = nil")
+		}
+		if !enableOutput {
+			t.Fatal("PrepareNextTraceAPIV4FastIP enableOutput = false, want true")
+		}
+		return nil
+	}
+	newLeoWebsocketFn = func(context.Context) *wshandle.WsConn {
+		wsCalls++
+		return nil
+	}
+	t.Cleanup(func() {
+		prepareNextTraceAPIV4FastIPFn = oldPrepare
+		newLeoWebsocketFn = oldNewLeo
+	})
+	dataProvider := "LeoMoeAPI"
+	powProvider := "api.nxtrace.org"
+
+	if got := initLeoWebsocket(context.Background(), &dataProvider, &powProvider, false); got != nil {
+		t.Fatalf("initLeoWebsocket() = %+v, want nil when NextTrace API v4 token is configured", got)
+	}
+	if prepareCalls != 1 {
+		t.Fatalf("PrepareNextTraceAPIV4FastIP calls = %d, want 1", prepareCalls)
+	}
+	if wsCalls != 0 {
+		t.Fatalf("Leo WS calls = %d, want 0 when API v4 preheat succeeds", wsCalls)
+	}
+}
+
+func TestInitLeoWebsocketFallsBackToV3WhenAPIV4FastIPFails(t *testing.T) {
+	t.Setenv(util.EnvNextTraceAPIV4TokenKey, "v4-token")
+	oldPrepare := prepareNextTraceAPIV4FastIPFn
+	oldNewLeo := newLeoWebsocketFn
+	var prepareCalls int
+	var wsCalls int
+	prepareNextTraceAPIV4FastIPFn = func(context.Context, bool) error {
+		prepareCalls++
+		return errors.New("fastip unavailable")
+	}
+	newLeoWebsocketFn = func(context.Context) *wshandle.WsConn {
+		wsCalls++
+		return nil
+	}
+	t.Cleanup(func() {
+		prepareNextTraceAPIV4FastIPFn = oldPrepare
+		newLeoWebsocketFn = oldNewLeo
+	})
+	dataProvider := "LeoMoeAPI"
+	powProvider := "api.nxtrace.org"
+
+	_ = initLeoWebsocket(context.Background(), &dataProvider, &powProvider, false)
+	if prepareCalls != 1 {
+		t.Fatalf("PrepareNextTraceAPIV4FastIP calls = %d, want 1", prepareCalls)
+	}
+	if wsCalls != 1 {
+		t.Fatalf("Leo WS calls = %d, want 1 after API v4 preheat failure", wsCalls)
+	}
+}
+
 func TestMaybeRunUninterruptedRawReturnsOnCanceledContext(t *testing.T) {
 	oldUninterrupted := util.Uninterrupted
 	util.Uninterrupted = true