Protocol Support Roadmap

This document tracks the protocol and transport scope for the next flutter_vless release. The source of truth for Xray capability is the current Project X configuration documentation:

• Xray outbounds: https://xtls.github.io/en/config/outbounds/
• Xray inbounds: https://xtls.github.io/en/config/inbounds/
• Xray transports: https://xtls.github.io/en/config/transports/

Product Scope

flutter_vless is a client runtime wrapper. The default generated config should keep using a local SOCKS inbound and a remote proxy outbound. We should support importing every client-facing Xray outbound profile that can represent a remote server. Service outbounds and inbounds remain raw JSON / advanced-builder scope.

Xray Outbound Inventory

Xray outbound	Current support	Next action
vless	Supported from share links, Clash YAML, sing-box JSON, raw Xray JSON	Keep; expand transport coverage below.
vmess	Supported from share links, Clash YAML, sing-box JSON, raw Xray JSON	Keep; expand transport coverage below.
trojan	Supported from share links, Clash YAML, sing-box JSON, raw Xray JSON	Keep; expand transport coverage below.
shadowsocks	Supported from ss://, Clash YAML, sing-box JSON, raw Xray JSON	Keep; add fixture coverage for all commonly exported ciphers.
socks	Supported from socks://, Clash YAML, sing-box JSON, raw Xray JSON	Keep.
wireguard	Raw Xray JSON plus generated import from Clash YAML and sing-box JSON	Validate Android, iOS, macOS, and Windows artifacts with xray run -test; no public wireguard:// parser until an accepted share-link shape is chosen.
hysteria (version: 2)	Raw Xray JSON plus hysteria2:// / hy2://, Clash YAML, and sing-box JSON import	Validate Android, iOS, macOS, and Windows artifacts with xray run -test; update packaged artifacts where older Xray builds reject network: hysteria.
http	Raw Xray JSON plus generated import from Clash YAML and sing-box JSON	Keep subscription/import-context only. Do not treat arbitrary browser http:// URLs as proxy profiles.
freedom	Internal direct outbound and raw Xray JSON	Keep advanced/raw only. It is routing policy, not a remote server profile.
blackhole	Internal block outbound and raw Xray JSON	Keep advanced/raw only. It is routing policy, not a remote server profile.
dns	Raw Xray JSON only	Keep advanced/raw only.
loopback	Raw Xray JSON only	Keep advanced/raw only.

Xray Inbound Inventory

The plugin-owned default inbound remains local SOCKS because packet-tunnel and proxy-only paths already depend on it.

Xray inbound	Product decision
socks	Supported as the generated local inbound.
http	Advanced/raw only unless we add a separate local HTTP proxy mode.
dokodemo-door / tunnel	Advanced/raw only.
vless, vmess, trojan, shadowsocks, wireguard, hysteria, tun	Advanced/raw only for now; these are server/runtime composition features, not default client profile import targets.

Transport Inventory

These transports should be importable for vless, vmess, and trojan where the protocol supports them.

Transport	Current support	Next action
raw	type=raw import emits rawSettings; legacy type=tcp remains supported	Validate generated configs against the target Xray artifact.
xhttp	Supported for VLESS and subscription imports	Keep; add more Clash/sing-box fixture variants.
grpc	Supported	Keep.
websocket / ws	Supported	Keep.
mkcp / kcp	kcp and mkcp aliases are normalized for subscription import	Validate generated configs against the target Xray artifact.
httpupgrade	Supported from share links, Clash YAML, and sing-box JSON; preserves non-Host headers	Validate generated configs against the target Xray artifact.
hysteria	Generated by Hysteria2 import paths	Validate native artifacts first.
quic	Legacy code path exists, but it is removed in current Project X transport config	Keep only as legacy input compatibility for older artifacts; do not expand without target-version tests.

Transport security remains tls, reality, and none. FinalMask and sockopt are advanced/raw config features.

Implementation Order

1. Runtime artifact audit. Build or update Android, iOS, macOS, and Windows Xray artifacts to the same pinned Xray version. For every artifact, run xray run -test fixtures for wireguard, hysteria, httpupgrade, raw, xhttp, grpc, ws, kcp, and legacy quic.

2. Config model foundation. Done in Dart. Keep raw Xray JSON passthrough unchanged. Add missing typed stream settings: rawSettings, httpupgradeSettings, and hysteriaSettings.

3. HTTPUpgrade transport. Parser foundation done in Dart. Add type=httpupgrade parsing for VLESS, VMess, Trojan, Clash YAML, and sing-box JSON. Generate streamSettings.network = "httpupgrade" and httpupgradeSettings with path, host, and optional headers.

4. Modern RAW transport alias. Parser foundation done in Dart. Accept type=raw alongside legacy type=tcp. Emit rawSettings for raw and keep existing tcpSettings behavior for tcp.

5. WireGuard outbound import. Clash YAML and sing-box JSON foundation done in Dart. Public wireguard:// remains out of scope until an accepted share-link shape is chosen. Minimum fields: secretKey, address[], peers[].endpoint, peers[].publicKey, optional reserved, mtu, workers, domainStrategy, noKernelTun.

6. Hysteria2 outbound import. Share-link, Clash YAML, and sing-box JSON foundation done in Dart. Generated configs use protocol: "hysteria", settings.version = 2, server address/port, streamSettings.network = "hysteria", hysteriaSettings.version = 2, and hysteriaSettings.auth.

7. HTTP proxy outbound import. Done for Clash YAML and sing-box JSON. Keep the import scoped to subscription/import context. Do not add parseFromURL() support for arbitrary http:// browser URLs unless the product gets an explicit proxy-link format that cannot be confused with web navigation.

8. Documentation and device matrix. Extend doc/device_matrix.md with WireGuard, Hysteria2, HTTPUpgrade, raw, and HTTP proxy cases. Mark platform limitations explicitly, especially UDP behavior in Apple packet tunnels and Windows tunnel mode.

Definition Of Done

• Parser fixtures cover share links, Clash YAML, sing-box JSON, and raw Xray JSON for each supported profile class.
• xray run -test succeeds for generated JSON on every packaged Xray artifact.
• At least one real-device tunnel or proxy-only smoke test exists for every new client-facing protocol: WireGuard, Hysteria2, HTTPUpgrade, and HTTP proxy.
• Unsupported formats are skipped with tests; they must not produce broken Xray JSON silently.