New Endpoint Support: Geph5

[TommyJerryMairo]

This pull request adds a Geph5 endpoint to sing-box.

Geph5 exposes its VPN transport through a stdio packet protocol. The new endpoint manages the official geph5-client process and connects its stdin/stdout packet stream to sing-box's userspace IP stack.

The endpoint supports TCP and UDP through the normal sing-box endpoint interface. DNS resolution intentionally remains in the sing-box routing layer: Geph receives resolved IP destinations, while domains can be resolved by a route rule before dialing the endpoint.

Configuration

{
  "type": "geph",
  "tag": "geph5",
  "executable_path": "/usr/bin/geph5-client",
  "config_path": "/etc/geph5/client.yaml",
  "control_address": "127.0.0.1:9913",
  "startup_timeout": "15s",
  "extra_args": []
}

The config_path and control_address fields are required. The control address must be a loopback address, must match control_listen in the Geph5 configuration, and must be available when the endpoint starts. Because Geph5's TCP control RPC is unauthenticated, it should remain accessible only from the local host.

sing-box supplies --config and --stdio-vpn when starting the client and rejects attempts to override those managed arguments through extra_args.

startup_timeout bounds both process launch and readiness polling. sing-box queries the control RPC conn_info method and exposes the endpoint only after Geph reports Connected.

Implementation

• Registers the geph endpoint and proxy display name.
• Starts geph5-client with context cancellation and lifecycle handling.
• Verifies that the configured control address is available before launch.
• Polls the conn_info JSON-RPC method until Geph reports Connected.
• Validates the RPC version, request ID, result, error, and connection state.
• Reports bounded stderr diagnostics and reaps the child after startup failure, timeout, or cancellation.
• Frames packets with Geph5's 16-bit big-endian length prefix and copies packet buffers across the process boundary.
• Requires endpoint destinations to be resolved IP addresses.
• Exposes TCP and UDP through the existing userspace packet-stack adapter.
• Adds JSON schema entries and English/Chinese endpoint documentation.

The endpoint requires a build with -tags with_gvisor, because the userspace IP stack translates sing-box TCP/UDP operations into Geph5's packet stream.

The official Geph exit service applies destination-port restrictions. Those restrictions are lifted for Plus subscribers, so testing an additional outbound proxy chained through the Geph endpoint may require a Plus account.

Testing

go test ./protocol/geph
go test -tags with_gvisor ./protocol/geph
go test -race ./protocol/geph
go vet ./protocol/geph

The focused Geph tests, race run, vet run, schema validation, and tagged build checks pass.

A repository-wide go test ./... run also reaches and passes the Geph package. Its remaining failures are unrelated host/toolchain issues: network-namespace creation is not permitted in common/netns, the test host's /etc/hosts does not define localhost for dns/transport/hosts, and experimental/boxdd and experimental/libbox encounter an existing runtime/pprof.parseProcSelfMaps link error.

Follow-up scope

To keep this review focused, a follow-up pull request will add opt-in sing-box check --start-geph validation and graceful shutdown through the Geph control RPC. Those changes are intentionally not included in this pull request.

Thank you very much for taking the time to review this contribution. Feedback is welcome.

[TommyJerryMairo]

Oops, fixing branch mismatch now.

[TommyJerryMairo]

Fix merge dropped.

[TommyJerryMairo]

Merged changes from the testing branch.

[TommyJerryMairo]

Rebased commit history into latest testing HEAD

[TommyJerryMairo]

Minor fixes in documentation.

[TommyJerryMairo]

Design updated to use Geph5's control port to check the inferior's readiness.

[TommyJerryMairo]

Rebased commit history into latest testing HEAD

[TommyJerryMairo]

Rebased commit history into the latest HEAD on testing