# libXray

[简体中文](./readme/README.zh_CN.md)

This is a wrapper around [Xray-core](https://github.com/XTLS/Xray-core) to improve the client development experience.

# Note

1. This repository has few maintainers. If you do not report a bug or initiate a PR, your issue will be ignored.
2. This repository does not guarantee API stability, you need to adapt it yourself.
3. This repository is only compatible with the latest release of Xray-core.

# Versioning

Releases use CalVer in the form `v<YY>.<M>.<D>` (e.g. `v26.3.27` = 2026-03-27).
Because Go modules require any module with major version `>= 2` to encode the
major in its import path, every CalVer release is mirrored onto a Go-friendly
SemVer tag on the same commit:

| CalVer tag | Go-import tag |
| ---------- | ------------- |
| `v26.3.27` | `v1.260327.0` |

Go consumers should pin against the SemVer mirror:

```shell
go get github.com/xtls/libxray@v1.260327.0
```

The mirror tag is created automatically by
[`.github/workflows/release-go-mirror.yml`](./.github/workflows/release-go-mirror.yml)
on every CalVer push. Existing CalVer tags can be backfilled with
[`scripts/backfill-semver-tags.sh`](./scripts/backfill-semver-tags.sh).

# Features

## build

Compile script. It is recommended to always use this script to compile libXray. We will not answer questions caused by using other compilation methods.

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 release tag `v26.9.30` through its pseudo-version.
Pass the optional `local` argument to use an existing local checkout at `../Xray-core` through a Go module `replace`.

### Usage

```shell
# Android (min Android API level is 21)
python3 build/main.py android
python3 build/main.py android local

# Apple (gomobile or go)
python3 build/main.py apple gomobile
python3 build/main.py apple go
python3 build/main.py apple gomobile local
python3 build/main.py apple go local

# Linux
python3 build/main.py linux
python3 build/main.py linux local

# Windows
python3 build/main.py windows
python3 build/main.py windows local

```

Builds snapshot and restore `go.mod` and `go.sum` on success or failure by default.
Pass `--no-snapshot` to skip both the snapshot and restoration. Before initializing
Go dependencies, the script deletes existing `go.mod` and `go.sum` and creates a
fresh module. The resulting files are retained even if the build fails.
This option is supported by every target
and can be combined with `local` in either order:

```shell
python3 build/main.py android --no-snapshot
python3 build/main.py apple go local --no-snapshot
```

Gomobile builds
resolve `latest` by default; set `LIBXRAY_GOMOBILE_VERSION` to select a Go module
version. Both `gomobile` and `gobind` use that resolved version.

Linux and Windows builds also produce `bin/xray` or `bin/xray.exe`. This
session Core protects Go DNS lookups from the VPN route and accepts only:

```shell
xray run -dns <IP:port> -interface <name> -config <xray.json> [-error-file <path>]
```

The `-dns`, `-interface`, and `-config` options are required. `-dns` must be an IP endpoint, and `-config`
points directly to the Xray JSON configuration.

The optional `-error-file` also writes command failures to a UTF-8 file before
exiting, preserving the same error printed to stderr. The file is cleared before
running; a successful run leaves it empty. Its parent directory must exist.
Callers launching an elevated Core should create the file first under their own
account so they retain read access. This is an error-return channel, not Xray's
access/error log configuration, and it does not add a separate validation pass.
Applications using this option must bundle a desktop Core built with its support.

> [!WARNING]
> **Use only one Go runtime per process.** Go does not support loading multiple
> independently built Go runtimes into one process. Every native libXray
> artifact embeds a Go runtime, whether it is produced through cgo or gomobile.
> Do not load libXray together with another independently built Go, cgo, or
> gomobile library in the same executable or process. Doing so can fail during
> build, link, or load, or crash during runtime initialization before
> application code runs.
> If one process needs Go packages from several libraries, include those
> packages in the same Go build or `gomobile bind` invocation and produce one
> native artifact so they share a runtime. Merely repackaging or merging
> independently built frameworks, archives, AARs, shared libraries, or DLLs is
> not sufficient. Separate OS processes may each load one Go runtime, so apply
> this rule independently to each process. See
> [Go #18976](https://github.com/golang/go/issues/18976#issuecomment-308505600),
> [golang/go#15956](https://github.com/golang/go/issues/15956#issuecomment-373709423),
> and [libXray #116](https://github.com/XTLS/libXray/issues/116).

### Android

use [gomobile](https://github.com/golang/mobile) .

### iOS && macOS

#### 1. use gomobile

Need "iOS Simulator Runtime".

This is the best choice for general scenarios. The cross-platform single-runtime
restriction above still applies when linking other Go-based libraries.

Supports iOS, iOSSimulator, macOS, macCatalyst.

But it is not possible to set the minimum macOS version, which will cause some warnings when compiling. And it does not support tvOS.

#### 2. use cgo

Need "iOS Simulator Runtime" and "tvOS Simulator Runtime".

Support more compilation options, output c header files.

This works well when you use ffi for integration. For example, integration with swift, kotlin, dart.

Support iOS, iOSSimulator, macOS, tvOS.

The product `LibXray.xcframework` contains **module.modulemap**. When using
Swift, import it as module `LibXray`.

### Linux

depend on gcc and g++.

### Windows

Depends on gcc and g++ in `PATH`.

Native amd64 and arm64 builds are supported. The release workflow builds each
architecture on its matching GitHub-hosted Windows runner.

## API

libXray exposes a single structured entrypoint:

```go
func Invoke(requestJSON string) string
```

The C export is:

```c
char* CGoInvoke(char* requestJSON);
void CGoFree(char* value);
```

`CGoInvoke` allocates its response. The caller must release every non-null
response with `CGoFree`; do not use a platform allocator directly.

The request is a JSON object:

```json
{
  "apiVersion": 3,
  "method": "runXray",
  "payload": {
    "xrayJson": "{\"outbounds\":[...]}"
  }
}
```

The response is a JSON object:

```json
{
  "success": true,
  "data": {},
  "error": ""
}
```

Design notes:

1. Invoke accepts only `apiVersion: 3`; the API version remains fixed at 3.
   Contract changes require synchronized consumers and documentation within
   that version. Xray configurations are passed as UTF-8 JSON text in
   `xrayJson`; libXray does not read configuration file paths.
2. A top-level `env` field is ignored and has no effect. Xray-core runtime
   environment options belong in the root `env` object of the Xray config.
3. `SetTunFd` has been removed. When the fd is only known at runtime, write
   `xray.tun.fd` into the Xray config root `env` object before calling
   `runXray`.
4. `countGeoData` is not backed by an Xray config, so its `datDir` is passed in
   the method payload.
5. The complete UTF-8 encoded Invoke request and response JSON envelopes are
   limited to 16 MiB. If either limit is exceeded, Invoke returns a failure
   response with `success: false`, `data: null`, and a size-limit error.
6. `convertShareLinksToXrayJson` validates each parsed outbound with the current
   Xray-core config builder. Invalid outbounds are omitted, and the method fails
   if none remain. Validation does not create or start an Xray instance.
   Xray JSON input is treated as a node source: only its root `outbounds` are
   retained, and all other root fields are ignored. The response contains only
   fields supported by libXray share links; unsupported and generated empty
   fields are omitted. Opaque XHTTP `extra` and FinalMask mask `settings` JSON
   remain unchanged.
   Every successful response contains only the projected `outbounds` list.
   Its optional `age.secretKey` decrypts official age ASCII armor in memory
   before the existing parser runs. Plaintext input remains unchanged.
7. Xray-core keeps its system dialer DNS client and outbound manager in
   process-wide state. `pingBatch`, `testXray`, and their exported Go
   entrypoints take the managed lifecycle lock and reject an active `runXray`
   instance before loading/building config.
   A batch holds the lock through all workers and temporary-core close. This
   also serializes these operations with one another. Instances
   created outside the managed APIs are not detected or restored; callers
   requiring overlap with them must still use separate processes.

Supported methods:

```text
getFreePorts
convertShareLinksToXrayJson
convertXrayJsonToShareLinks
generateAgeKeyPair
countGeoData
pingBatch
testXray
runXray
stopXray
xrayVersion
getXrayState
```

## controller

### Socket protect

Used to solve the socket protect problem on Android.

### DNS resolver

Android may expose a loopback DNS server to Go's resolver while a VPN is
active. Call `SetDNS` before `runXray` to make Go use the DNS server selected by
the VPN configuration and protect the DNS socket from the VPN tunnel. The
server must be an IP endpoint with a port, such as `8.8.8.8:53` or
`[2001:4860:4860::8888]:53`.

Call `ResetDNS` after Xray has stopped. These APIs are available only in the
Android artifact and change the process-wide Go resolver.

```java
LibXray.setDNS(controller, "8.8.8.8:53");
LibXray.invoke(runXrayRequest);

// Later, when stopping the core:
LibXray.invoke(stopXrayRequest);
LibXray.resetDNS();
```

### Process finder (per-app routing)

`ConnectivityManager.getConnectionOwnerUid()` is API 30+. On older Android
libXray falls back to parsing `/proc/net/{tcp,udp}{,6}` in pure Go.

Usage (Java/Kotlin):

```java
ProcessFinder finder = new ProcessFinder() {
    @Override
    public long findProcessByConnection(String network, String srcIP, long srcPort,
                                         String destIP, long destPort) {
        return -1; // return UID or -1
    }
};
LibXray.registerProcessFinder(finder, Build.VERSION.SDK_INT);
```

## geo

### count

Read geo files and count the categories and rules.

## main

Download geosite.dat and geoip.dat and count them.

## memory

Only executed on iOS, GC is initiated once a second. This can alleviate memory pressure on iOS.

## nodep

### file

Write data to a file.

### measure

Speed ​​test the Xray configuration.

### port

`getFreePorts` returns distinct free TCP ports on localhost. Its payload accepts
`count` and an optional `excludePorts` list of caller-reserved port numbers:

```json
{
  "apiVersion": 3,
  "method": "getFreePorts",
  "payload": {"count": 2, "excludePorts": [18587, 9000]}
}
```

The response keeps the existing `data.ports` integer array. Omit `excludePorts`
or pass an empty list for no exclusions; duplicates have no additional effect.
Excluded ports must be between 1 and 65535. Negative or impossible counts fail;
zero returns no ports. The Go entrypoint is
`nodep.GetFreePorts(count int, excludePorts []int)`; pass `nil` for no exclusions.

Listeners remain open during selection to avoid duplicates or repeatedly picking
an excluded port, and close before the function returns, including on failure.
The returned ports are therefore candidates, not reservations: another process
can claim them before the caller binds. This checks TCP only, not UDP.

## share

libXray stores outbound names in `tag`. `sendThrough` keeps its native Xray
meaning as the local bind address.

### generate_share

Convert Xray JSON to VMessAEAD / VLESS share links following
[Xray-core discussion #716](https://github.com/XTLS/Xray-core/discussions/716).
Hysteria2, SS, SOCKS and Trojan share links are also supported. VMess always generates
an AEAD URI, not the legacy QR-code format.

Outbounds without a supported share-link format are skipped. Conversion fails
if no share links can be generated.

### parse_share

Parse VMessAEAD / VLESS, Hysteria2, SS, SOCKS and Trojan share links into Xray JSON.
Legacy VMessQrCode links (`vmess://Base64(JSON)`) are not supported.

Xray JSON node input and Base64 / Age subscription wrappers remain supported.
Clash/Mihomo configurations remain unsupported.

Hysteria2 accepts `hysteria2://` and `hy2://` using the
[official URI scheme](https://v2.hysteria.network/docs/developers/URI-Scheme/):
optional authentication, default port 443, IPv6, SNI, Salamander obfuscation,
multi-port authorities and fragment names. Export uses `hysteria2://`.
Port hopping uses Core's `finalmask.udp` with both local and remote interval
hopping (30 seconds by default; `hop-interval` must be at least 5 seconds).
Legacy `ports` / `mport` queries are accepted and exported as authority ports.
Legacy `up` / `down` values are imported as client-local QUIC tuning, not exported.

TLS is mandatory. `insecure=true` / `allowInsecure=true` and `pinSHA256` are
rejected: the bundled Core cannot preserve those Hysteria TLS semantics.
Explicit Xray `fp`, `alpn`, `ech`, `pcs` and `vcn` extensions retain their Xray
meaning. Export rejects TLS/mask settings that cannot be represented, rather
than silently dropping security or obfuscation. Client-local QUIC tuning is
not part of the URI. Realm and Gecko are not supported. Hopping requires a
direct UDP socket; this does not add hopping support over chained proxies.

VMessAEAD / VLESS field mappings follow the
[Xray share-link proposal](https://github.com/XTLS/Xray-core/discussions/716)
where supported by the bundled Core:

- mKCP `mtu` and `tti` are preserved in both directions. Omitted values use
  Core defaults; Core validates their ranges. Legacy KCP `seed` and `headerType`
  are not imported or exported.
- XHTTP `extra` keeps its complete JSON content, including nested settings.
  `fm` carries FinalMask masks and all Core-supported `quicParams` fields.
- TLS `ech`, `pcs`, `vcn` and REALITY `pbk`, `sid`, `pqv`, `spx` are preserved
  alongside `sni`, `fp` and TLS `alpn`. An omitted `sni` uses the remote host,
  not the WebSocket HTTP host.
- Native transport aliases retain their settings when exported. RAW/TCP links
  use `type=tcp`; query values use percent-encoded spaces.
- gRPC supports `gun` and `multi`. The bundled Core does not support `guna`
  mode or the removed HTTP/QUIC transports; these are not silently substituted.

#### Parsing result

`convertShareLinksToXrayJson` has one response shape. Its payload contains
`text` and optional `age`. Every successful conversion returns
`data: {"outbounds":[...]}`. There is no statistics or nested config wrapper.

Invalid individual elements are skipped without discarding other valid nodes.
The list preserves source order and includes only projected, buildable outbounds.
No per-node hash comparison, deduplication or failed-node counting is performed.

No usable nodes, an unrecognized format, a malformed document, an invalid
container or a decryption failure returns `success: false` with `data: null`.
Error text never includes rejected candidates or decrypted subscription text.
Callers must not import/replace a subscription when no usable nodes remain.

### age-encrypted subscriptions

`convertShareLinksToXrayJson` accepts an optional native age secret key. Only
X25519 (`AGE-SECRET-KEY-1...`) and ML-KEM-768 + X25519 hybrid
(`AGE-SECRET-KEY-PQ-1...`) identities are accepted. Recognized age armor is
decrypted in memory and limited to 16 MiB of plaintext.

```json
{
  "apiVersion": 3,
  "method": "convertShareLinksToXrayJson",
  "payload": {
    "text": "-----BEGIN AGE ENCRYPTED FILE-----\n...",
    "age": {
      "secretKey": "AGE-SECRET-KEY-1..."
    }
  }
}
```

Generate a new keypair with `keyType` set to `x25519` or `hybrid`. An omitted
`keyType` defaults to `x25519`. The `hybrid` option matches Mihomo
`age keygen-pq` and produces an `AGE-SECRET-KEY-PQ-1...` identity with an
`age1pq1...` recipient.

```json
{
  "apiVersion": 3,
  "method": "generateAgeKeyPair",
  "payload": {
    "keyType": "x25519"
  }
}
```

The response contains both `secretKey` and `publicKey`. The integrating
application must persist the pair and send only `publicKey` as
`X-Age-Public-Key`. libXray does not perform the subscription HTTP request,
persist keys, or add headers. Applications must never send the secret key over
HTTP or write decrypted subscription text to disk.

### xray_json

Some tools used to parse shared links.

## xray

### pingBatch

Tests multiple outbound configurations concurrently in one temporary Xray
instance. Each `xrayJson` string is parsed only for its `outbounds`; all other
root fields are ignored. The target outbound is selected by `outboundTag`, then
by the `proxy` tag, and finally by the first outbound.

```json
{
  "apiVersion": 3,
  "method": "pingBatch",
  "payload": {
    "configs": [
      {
        "xrayJson": "{\"outbounds\":[...]}"
      },
      {
        "xrayJson": "{\"outbounds\":[...]}",
        "outboundTag": "media"
      }
    ],
    "timeout": 5,
    "url": "https://cp.cloudflare.com/",
    "locationUrl": "https://ip-check-perf.radar.cloudflare.com/"
  }
}
```

Each request accepts at most five configurations and tests all accepted
configurations concurrently. Requests containing more than five configurations
fail before any configuration is tested.

The top-level response succeeds when the batch itself was accepted. Each item
has its own result; `delay` is `10000` for an error and `11000` for a timeout.
`delay` is always present, including a successful zero-millisecond result.
The result array has the same length and order as the input config array.
Outbound dependencies referenced by `streamSettings.sockopt.dialerProxy` are
included automatically. Xray-core rejects the removed `proxySettings` field.

`locationUrl` is optional and must be an absolute HTTP(S) URL. When omitted,
no location request is made and no location fields are returned. When supplied,
each prepared item sends its latency HEAD and then its location GET using the
same client forced through that item's selected outbound and dependencies.
Each request has the configured timeout (so an item may take up to twice it).
Location time is not included in `delay`, and the two results are independent:
`success`, `delay` and `error` describe latency only; a location failure does not
invalidate a successful latency result, and GET is still attempted after a
latency failure.

A successful GET adds the unmodified response body as the `locationJson`
string. The App owns JSON parsing and provider-specific field handling. The
provider must return HTTP 200 and at most 64 KiB; transport or body-read
failures instead add `locationError`. Errors do not echo the URL, credentials
or response body. Invalid outbound configs retain their ordinary per-item
failure and do not perform either request.

### testXray

Loads the supplied JSON text and constructs a temporary Xray instance. The
payload contains only `xrayJson`; success returns `data: {}`:

```json
{
  "apiVersion": 3,
  "method": "testXray",
  "payload": {
    "xrayJson": "{\"outbounds\":[...]}"
  }
}
```

The Go entrypoint `TestXray` calls `newXrayInstance` (`core.LoadConfig` followed
by `core.New`) and closes the successfully constructed instance before returning.
It never calls `Start` or publishes a managed instance. Core construction errors,
including invalid routing matchers and missing balancers, and close errors are
returned through the normal error response.

This is not a sandbox. Builders and constructors may read local GeoData and
certificates, apply `env`, replace process-global logging/DNS state, create log
files, or initialize protocol-specific resources and background tasks. Process
state is not restored. In particular, WireGuard can acquire a TUN during
construction and VLESS reverse can schedule background work. The current Core
does not return its partial instance when construction fails, so libXray cannot
close that partial instance. Core-managed geodata cron does not run without
`Start`, although its asset declarations still check local files.

Callers may provide a minimal configuration or remove App-managed fields from a
disposable validation copy; libXray applies no App-specific filtering. Only the
supplied configuration is checked. Success establishes instance construction and
close, not listener/TUN startup, system permissions, or network connectivity.
Callers must handle actual startup failures.

### runXray

Starts the managed Xray instance from the supplied JSON text. Use `stopXray`
to stop that instance. `runXrayFromJson` is no longer a separate method.

### probeManagedConnectivity

Probes HTTPS through an explicitly named outbound of the existing managed core.
Unlike `pingBatch`, it never starts another core, binds a listener, or changes the
running configuration. Missing tags fail closed; there is no default or OS-direct
fallback. Applications must select their own trusted health endpoints and verify
the returned HTTP status and exact response body.

```json
{"apiVersion":3,"method":"probeManagedConnectivity","payload":{"outboundTag":"selected-proxy","url":"https://health.example.com/check","timeoutMilliseconds":7000}}
```

`url` must be absolute HTTPS without user information or a fragment. TLS uses
system roots and hostname verification. Redirects are never followed. The timeout
is 100–7000 ms (default 7000); response headers are limited to 4096 bytes and UTF-8
body to 128 bytes. The method returns `success:true` for a completed probe with
`data.status` equal to `response`, `failed`, or `unavailable`. A `response` includes
`httpStatus` and `body`; failures include a fixed `reason` code, never raw network
errors or request URLs. Invalid arguments use the normal `success:false` envelope.

This checks the configured outbound transport, not OS packet capture, TUN traffic,
or the system DNS path. The application owns stronger end-to-end verification.
`stopXray` cancels active probes without waiting for their timeout; completion from
a stopped/replaced managed instance is `unavailable`. Network I/O does not hold
the core lifecycle mutex.

### metrics

Refer to the following configuration:

```json
{
  "metrics" : {
    "listen": "127.0.0.1:49227"
  },
  "policy" : {
    "system" : {
      "statsInboundDownlink" : true,
      "statsInboundUplink" : true,
      "statsOutboundDownlink" : true,
      "statsOutboundUplink" : true
    }
  },
  "stats" : {}
}
```

The metrics server exposes the Xray runtime counters through HTTP. For example,
when `listen` is `127.0.0.1:49227`, read:

```text
http://localhost:49227/debug/vars
```

Metrics only needs the `listen` field in this wrapper. Query `/debug/vars`
directly with an HTTP client instead of going through libXray. Counters belong
to the current Xray instance; libXray does not sample or persist traffic.

### validation

Verify the Xray configuration.

### xray

Start and stop Xray instances.

# Credits

[Project X](https://github.com/XTLS/Xray-core)

[VMessPing](https://github.com/v2fly/vmessping)

[FreePort](https://github.com/phayes/freeport)

[MetaCubeX age](https://github.com/MetaCubeX/age) (BSD 3-Clause)

# License

This repository is based on the MIT License.

## getXrayState

`getXrayState` with an empty payload retains `data.running` and may include
`data.tunReaders`, a map keyed by the current managed TUN inbound tag. Each entry
contains `state` (`running`, `failed`, `stopped`, or `unavailable`). A failed read
also includes a sanitized `errorKind` (`errno`, `eof`, or `other`) and an optional
numeric `errorCode` for errno. No packet contents, addresses, or raw errors are
returned. Missing entries, older library responses, inactive cores and unavailable
readers are not failure evidence. `running` is not proof of end-to-end forwarding.
Read snapshots are synchronized with core start/stop and native reader lifecycle.
Consumers must reject results from obsolete app/core generations before recovery;
intentional shutdown and a superseded reader cannot report a new reader failure.
The API remains version 3; no new method or cryptographic behavior is introduced.
