Introducing a new way to review your PRs.

Read the announcement

2dust / v2rayn

A GUI client for Windows, Linux and macOS, support Xray and sing-box and others

View on GitHub

13 documents · Updated Nov 16, 2026

docs / service-lib-profile-formats-subscriptions

ServiceLib profile formats and subscriptions

Overview

This area owns the import/export boundary between text subscription data, share links, custom core configs, and persisted ProfileItem rows. The main subscription entry point is v2rayN/…/SubscriptionHandler.cs: UpdateProcess loads enabled SubItem records, validates that each has an HTTP(S) URL, downloads the primary subscription (optionally through a subconverter target), appends any comma-separated MoreUrl subscription results, base64-decodes appended results when needed, and then hands the combined text to ConfigDbHandler.AddBatchServers(result, subId, true). Progress and final success/failure are surfaced through the injected updateFunc; the parser itself surfaces success as an imported-row count.

Single share links are routed by v2rayN/…/FmtHandler.cs. ResolveConfig trims input, matches the protocol prefix, and dispatches to protocol-specific format handlers under v2rayN/ServiceLib/Handler/Fmt/**; GetShareUri performs the reverse dispatch from ProfileItem.ConfigType. The protocol handlers normalize parsed data into ProfileItem fields (Address, Port, Password, Username, Remarks, Network, StreamSecurity, etc.) and the JSON-backed extension records exposed by ProfileItem.GetProtocolExtra() and ProfileItem.GetTransportExtra(). v2rayN/…/BaseFmt.cs centralizes common URI query handling for TLS/REALITY/ECH/finalMask fields and transports (raw, kcp, ws, httpupgrade, xhttp, grpc), including IPv6 bracket handling and percent-encoding discipline.

Batch subscription parsing is orchestrated by ConfigDbHandler.AddBatchServers (direct dependency of this flow). It first tries common line-oriented share links, with base64-decoded and raw variants, then falls back to SIP008 Shadowsocks JSON, WireGuard config files, mixed internal v2rayn:// links, and finally custom core configs. During common subscription imports it de-duplicates lines, applies the subscription filter regex to ProfileItem.Remarks, optionally pre-resolves hostnames with the subscription resolver, validates each profile through the protocol-specific add methods, sets Subid/IsSub, inserts successful rows, removes old subscription rows after a successful refresh, and attempts to preserve the active profile and traffic statistics by matching new profiles to old ones.

Supported share and config formats are:

  • v2rayN/…/VmessFmt.cs: legacy base64 JSON vmess:// using v2rayN/…/VmessQRCode.cs, plus standard URI-style vmess://user@host:port?... when an @ is present. VMess exports back to the base64 QR JSON form and maps modern transport extras into the older QR keys.
  • v2rayN/…/ShadowsocksFmt.cs: legacy base64 ss://, SIP002 URI, SIP008 JSON via ResolveSip008, v2ray-plugin websocket/TLS plugin metadata, and obfs-local HTTP obfuscation. v2rayN/…/SsSIP008.cs allows numeric ports to be read from strings.
  • v2rayN/…/SocksFmt.cs: modern socks://user:pass@host:port or base64 userinfo, plus legacy base64 socks://user:pass@host:port payloads; it accepts socks://, socks5://, and socks4:// prefixes through FmtHandler.
  • v2rayN/…/TrojanFmt.cs and v2rayN/…/VLESSFmt.cs: URI-style links with shared transport query parsing. Trojan preserves allowInsecure/insecure and flow; VLESS preserves encryption and flow.
  • v2rayN/…/Hysteria2Fmt.cs and v2rayN/…/HyRealm.cs: hysteria2:///hy2:// links, defaulting omitted ports to 443, plus hysteria2+realm:// and hysteria2+realm+http:// forms. Realm links parse rendezvous host/port, token, realm name, STUN list, and the auth password query, and can export either a normal Hysteria2 link or a realm link depending on ProtocolExtraItem.Hy2RealmUrl.
  • v2rayN/…/TuicFmt.cs: tuic://username:password@host:port with SNI/ALPN, allow_insecure, and congestion_control query fields.
  • v2rayN/…/WireguardFmt.cs: wireguard://privateKey@host:port URI fields for peer/interface metadata and full WireGuard [Interface]/[Peer] config import. Full configs produce one ProfileItem per peer, carrying interface private key, address, DNS, MTU, peer public/preshared/reserved values, and endpoint parsing for IPv4, hostnames, and bracketed IPv6.
  • v2rayN/…/AnytlsFmt.cs: anytls://password@host[:port] with a default port of 443 when omitted, common transport/TLS query fields, and insecure=1.
  • v2rayN/…/NaiveFmt.cs: naive+https:// and naive+quic:// links, defaulting omitted ports to 443, splitting userinfo before URL-decoding so colons embedded in credentials survive round-trip, and preserving insecure-concurrency.
  • v2rayN/…/InnerFmt.cs: internal v2rayn://<config-type>/<url-safe-base64-json> exports/imports for native profile transfer. It rejects unsupported enum/core values, skips Custom profiles, rewrites imported IndexId values to avoid trusting external IDs, rewrites group child references to the new IDs, and supports embedded custom outbound JSON through temporary files.
  • v2rayN/…/V2rayFmt.cs and v2rayN/…/SingboxFmt.cs: custom JSON import for complete Xray/sing-box configs and individual outbound definitions. Complete configs are stored as EConfigType.Custom temp files; individual usable outbounds are stored as EConfigType.Outbound temp files. v2rayN/ServiceLib/Sample/SampleClientConfig, SampleOutbound, SingboxSampleClientConfig, and SingboxSampleOutbound are representative templates for those shapes.
  • v2rayN/…/ClashFmt.cs, HtmlPageFmt.cs, and Hysteria2Fmt.ResolveFull2: fallback custom-file detection for Clash YAML-like content, HTML rejection, and full Hysteria2 config files.

UI-facing models in v2rayN/…/ProfileItemModel.cs summarize imported profiles for lists with protocol, remark, endpoint, subscription metadata, delay/speed, and traffic fields. v2rayN/…/RetResult.cs is the generic success/message/data DTO used by service callers outside the parser-specific count/msg return conventions.

Routing / covers

This doc owns:

Coupling

  • If a new share protocol or EConfigType is added, update both dispatch directions in v2rayN/…/FmtHandler.cs and the add switch in ConfigDbHandler.AddBatchServersCommon; otherwise links may export but never import, or import but never persist.
  • If query keys for TLS, REALITY, ECH, finalMask, or transport settings change in v2rayN/…/BaseFmt.cs, verify all URI-style handlers that call ResolveUriQuery/ToUriQuery (VmessFmt, VLESSFmt, TrojanFmt, AnytlsFmt, NaiveFmt) still round-trip those fields and that lite handlers (Hysteria2Fmt, TuicFmt) intentionally omit the broader transport set.
  • If ProfileItem.ProtoExtra or ProfileItem.TransportExtra serialization changes, update v2rayN/…/InnerFmt.cs; it flattens/unflattens ProtoExtraObj and TransportExtraObj in exported JSON rather than relying only on current entity serialization.
  • If subscription download behavior changes in v2rayN/…/SubscriptionHandler.cs, verify ConfigDbHandler.AddBatchServers still receives either raw share-link lines or decoded text. Additional subscription content is decoded before concatenation only when Utils.IsBase64String says so, while the main result is passed through for the batch importer to retry raw/base64 variants.
  • If custom config recognition changes in v2rayN/…/V2rayFmt.cs or SingboxFmt.cs, check v2rayN/ServiceLib/Sample/SampleClientConfig, SampleOutbound, SingboxSampleClientConfig, and SingboxSampleOutbound; those samples reflect the minimum fields the parsers use to identify complete configs and usable outbounds.

Risks

  • v2rayN/…/BaseFmt.cs intentionally does not URL-decode query values a second time after Utils.ParseQueryString; double-decoding would corrupt values that legitimately contain percent sequences, and recent history includes format fixes for once-only password decoding.
  • v2rayN/…/NaiveFmt.cs, AnytlsFmt.cs, SocksFmt.cs, and ShadowsocksFmt.cs are fragile around URI defaults and credential encoding. Recent commits fixed omitted default ports, base64 SOCKS import, Naive colon round-trips, and SIP002 password decoding, so changes to userinfo splitting or Uri.Port == -1 handling can break imported links that previously worked.
  • v2rayN/…/InnerFmt.cs rewrites imported IDs and forbids imported Custom profiles to avoid trusting externally supplied identifiers or file paths. Removing those checks would let imported internal links reference existing local profiles or arbitrary custom outbound files.