Crate vpn_link_serde 

VPN Link Serde

A comprehensive Rust library for parsing and serializing VPN proxy protocol links. Supports VMess, VLess, Shadowsocks, Trojan, and Hysteria2 protocols.

Features

• Parse protocol links into structured Rust types
• Serialize structured types back into protocol links
• Full support for all protocol variants and parameters
• Comprehensive error handling
• Serde support for serialization/deserialization

Supported Protocols

• VMess (vmess://) — V1 and V2 formats; serialization always outputs V2
• VLess (vless://) — Full parameter support including Reality, XTLS
• Shadowsocks (ss://) — SIP002 (Base64 userinfo), plugin and tag
• Trojan (trojan://) — TLS, XTLS, query and fragment (remark)
• Hysteria2 (hysteria2://) — Optional auth, official and extended query params

Link format and parsing rules (unified)

• Scheme prefix: Case-insensitive (e.g. VMESS:// is valid).
• Port: 1–65535; VMess allows port as number or string in JSON; others require a valid u16.
• Query string: Parsed as application/x-www-form-urlencoded; parameter names are case-sensitive.
• Fragment (#): Decoded as remark/tag; non-ASCII and spaces must be URL-encoded.
• Errors: Invalid format → InvalidFormat; invalid or missing required field → InvalidField; unknown scheme → UnsupportedProtocol.

See each type’s module (e.g. VMess, VLess) for format details, required/optional fields, and serialization rules.

References

Link formats and parsing rules follow the specifications and community conventions:

• VMess: Project V VMess, V2Fly Guide
• VLESS: XTLS VLESS
• Shadowsocks: SIP002 URI Scheme (RFC 3986)
• Trojan: Trojan Protocol, Trojan-Go URL
• Hysteria2: Hysteria 2 URI Scheme

A detailed specification (link format, parsing rules, and serialization) is available in the repository at doc/protocols.md.

Example

use vpn_link_serde::Protocol;

// Parse any protocol link
let protocol = Protocol::parse("vmess://eyJ2IjoiMiIsImFkZCI6IjEyNy4wLjAuMSIsInBvcnQiOjQ0MywiaWQiOiJ1dWlkLTEyMyJ9")?;

// Generate link from parsed protocol
let link = protocol.to_link()?;

License

Licensed under either of

• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

Structs

Hysteria2

Hysteria2 protocol parser

Hysteria2Config

Hysteria2 configuration structure

Shadowsocks

Shadowsocks protocol parser

ShadowsocksConfig

Shadowsocks configuration structure

Trojan

Trojan protocol parser

TrojanConfig

Trojan configuration structure

VLess

VLess protocol parser

VLessConfig

VLess configuration structure

VMess

VMess protocol parser

VMessV2

VMess V2 configuration structure

Enums

Protocol

Enum representing different protocol types

ProtocolError

Errors that can occur during protocol parsing and serialization

Traits

ProtocolParser

Trait for protocol parsers that can parse links and generate links

Type Aliases

Result

Result type for protocol parsing operations