xray_sdk 0.0.22-beta

Dart library for generating Xray Core configurations and working with links (parsing/generation) for V2Ray protocols.

xray_sdk

Dart library for generating Xray Core configurations and working with links (parsing/generation) for V2Ray protocols.

Requirements

To work with the library core, you need to use the third-party c-shared library xray-cshare.

Features

• Protocols: VLESS, VMess, Trojan, ShadowSocks, WireGuard.
• Transport: TCP (Raw), WebSocket, gRPC, mKCP, HTTPUpgrade, XHTTP.
• Security: TLS, REALITY.
• Link Handling: Parsing and generating vless://, vmess://, trojan://, ss://, socks://, hy:// and hysteria2:// links.
• Provider Formats: Full Xray/V2Ray JSON, sing-box JSON and Clash Meta/Mihomo YAML proxy lists.

Provider formatters are available from the single package:xray_sdk/share.dart export: JsonShareFormatter, SingBoxShareFormatter, and ClashMetaShareFormatter. Their wire models are internal implementation details.

• Utilities: Key generation (X25519, UUID), Xray core management (Start/Stop).

XHTTP uses the flat xhttpSettings model for current xPadding obfuscation, uplink/session/sequence placement, header limits, and range values. XHttpInt32Range accepts a number or a from-to string; JSON output uses the canonical string form. extra is retained only for VLESS/VMess share payloads and legacy import; headers belongs directly to xhttpSettings.

Installation

Add to pubspec.yaml:

dependencies:
  xray_sdk: ^1.0.0

Or run the command:

flutter pub add xray_sdk

Quick Start

Example of creating a VLESS + Reality configuration and generating a link:

import 'package:xray_sdk/config.dart';
import 'package:xray_sdk/share.dart';

void main() {
  // 1. Create client
  final client = VlessClient(
    id: "uuid-1234-5678",
    email: "[e-mail]",
    flow: XtlsFlow.xtlsRprxVision,
  );

  // 2. Configure Inbound with Reality
  final inbound = VlessInbound(
    port: Port.single(443),
    tag: "vless-reality",
    settings: VlessInboundSettings(clients: [client]),
    streamSettings: StreamSettings(
      network: StreamNetwork.raw, // TCP
      security: StreamSecurity.reality,
      realitySettings: RealitySettings(
        target: "www.google.com:443",
        serverNames: ["www.google.com"],
        password: "private-key-here",
        shortIds: ["1234"],
        fingerprint: Fingerprint.chrome,
      ),
    ),
  );

  // 3. Generate link
  final share = V2RayShareFormatter();
  final link = share.encodeVlessByClient(inbound, client);
  
  print(link); // vless://uuid...@...?security=reality&...
}

Работа со ссылками (Sharing)

Класс V2RayShareFormatter отвечает за преобразование конфигураций.

Декодирование (Decoding)

final share = V2RayShareFormatter();
try {
  final config = share.decodeVless("vless://...");
  print(config.streamSettings.network);
} catch (e) {
  print("Ошибка парсинга: $e");
}

Encoding

final link = share.encodeVMessByClient(inboundConfig, clientObj);

Configuration Examples

Merge configuration fragments

merge returns a new configuration, keeping values omitted by the overlay:

final merged = baseConfig.merge(
  XrayConfig(log: LogConfig(logLevel: LogLevel.debug)),
  options: const XrayMergeOptions(
    collectionMode: XrayMergeCollectionMode.mergeByKey,
  ),
);

Lists are replaced by default. Use append to retain both lists, or mergeByKey to deeply merge items matched by tag, email, id, or name.

Trojan + gRPC + Reality

final inbound = TrojanInbound(
  port: Port.single(443),
  tag: "trojan-grpc-reality",
  settings: TrojanInboundSettings(clients: [
    TrojanClient(password: "password", email: "[e-mail]")
  ]),
  streamSettings: StreamSettings(
    network: StreamNetwork.grpc,
    security: StreamSecurity.reality,
    grpcSettings: GrpcSettings(serviceName: 'grpc-trojan'),
    realitySettings: RealitySettings(
      target: "example.com:443",
      serverNames: ["example.com"],
      password: "private-key",
      shortIds: ["1234"],
      fingerprint: Fingerprint.chrome,
    ),
  ),
);

ShadowSocks 2022

final inbound = ShadowSocksOutbound(
  tag: "ss-2022",
  settings: ShadowSocksOutboundSettings(
    uot: true,
    servers: [
      ShadowSocksServer(
        address: "example.com",
        port: 9000,
        method: EncryptionMethod.aes128Gcm,
        password: "server-password",
      ),
    ],
  ),
  streamSettings: StreamSettings(
    network: StreamNetwork.raw,
    security: StreamSecurity.none,
  ),
);

Protocols

• VLESS: VlessInbound, VlessClient. Support for xtls-rprx-vision.
• VMess: VMessInbound, VMessClient.
• Trojan: TrojanInbound, TrojanClient.
• ShadowSocks: ShadowSocksOutbound, ShadowSocksServer. Support for SIP002 and SIP008.
• WireGuard: WireguardOutbound, WireguardOutboundPeer.
• TUN: TunInbound creates a virtual interface without a listening port and supports current xray-core interface, gateway, DNS, routing-table, and outbound-interface settings.

Transport Configuration (Stream Settings)

The StreamSettings class allows flexible configuration of the transport layer.

• Network: raw (TCP), ws (WebSocket), grpc (gRPC), kcp (mKCP), httpUpgrade, xhttp.
• Security: none, tls, reality.

Xray Wrapper

The XrayWrapper class provides access to native Xray core functions (requires libxray library).

final xray = XrayWrapper('libxray.so');
final uuid = xray.generateUuidV4();
final keys = xray.x25519Genkey('private_key');

Process-hosted Xray

On the Dart VM, XrayProcessCore starts an Xray executable as a managed child process. It accepts a typed configuration or an existing JSON file, and stops the hosted process tree when disposed.

final core = XrayProcessCore(
  XrayProcessOptions(workingDirectory: './xray'),
);
await core.startAsync(config);
// ...
await core.disposeAsync();

XrayProcessCore supports Windows, Linux and macOS; it is unavailable on web and mobile platforms. It also exposes async CLI helpers such as versionAsync and generateUuidV4Async.

Code Generation

If you modify models, regenerate serialization files:

flutter pub run build_runner build