zapret-kvn/docs/XHTTP_SHARE_LINKS.md
loop-uh 76923d595a
Some checks failed
Windows project source guards / test (push) Has been cancelled
XHTTP links: an unknown mode falls back to auto instead of an import error
Xray accepts only auto, packet-up, stream-up and stream-one. Links carry
mode=none (the header default of v2rayN's shared field); v2rayN passes the
mode only when it is one of those and otherwise leaves it out. The importer
now does the same instead of dropping the server, and lower-cases the VMess
"type" before the check. Android gets the same rule in core patch 0019.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 12:05:34 -05:00

3.3 KiB

VLESS XHTTP share links

Owner of the protocol: the native Xray core. The importer (xray_fluent/importer/link_parser.py, _build_xhttp_settings) only writes Xray's own xhttpSettings object; it does not interpret it.

Link parameter Written to Notes
type=xhttp (or the old splithttp) streamSettings.network = "xhttp" splithttp is renamed so the rest of the app compares one name.
path xhttpSettings.path
host xhttpSettings.host
mode xhttpSettings.mode Lower-cased; only auto, packet-up, stream-up, stream-one are kept. Anything else (mode=none from v2rayN's shared header/mode field) is left out, so Xray uses auto, as v2rayN does (2026-11-19; it used to be an import error, and Android failed to start with «unsupported mode: none»). Absent means Xray's default (auto).
extra xhttpSettings.extra XTLS share-link standard: encodeURIComponent(JSON object). Kept verbatim, field names are not touched (xPaddingObfsMode, uplinkHTTPMethod, xmux, downloadSettings…). extra=null, empty or {} mean unset; invalid JSON or a non-object is an import error.

How Xray reads it (infra/conf/transport_method.go, SplitHTTPConfig.Build): when extra is present it replaces the whole XHTTP config, then host, path and mode from the outer object are put back on top. So a field must live either in extra or beside path, never both with different meaning.

Masking (docs/MASKING.md) writes xmux into xhttpSettings.extra when extra exists, otherwise into xhttpSettings; both shapes come out of this importer.

Stored nodes: before this change the importer dropped path, host, mode and extra, so nodes saved by 0.8.80 and older carry an xhttpSettings-less outbound. prepare_node_for_runtime re-parses every node's link before it starts (repair_node_outbound_from_link), so such nodes are repaired on the next connect and saved; no re-import is needed. Nodes without a link (pasted JSON) already hold native settings.

VMess and Trojan over XHTTP: Xray supports them (transport is independent of protocol), and since the owner decision of 2026-11-16 Xray owns VLESS, VMess and Trojan (application/protocol_core.py). Their stored outbound is already in Xray's JSON shape, so the Xray sidecar takes xhttpSettings unchanged; nothing is converted for sing-box (it had no XHTTP path for them: the old _unsupported_transport marker is gone with the dead conversion). The VMess JSON link carries the XHTTP mode in type and extra as a string or an object. type is the mode only when it names one of the four (any case): its default none is the header type.

Other Xray-owned details of the parser: WebSocket and HTTPUpgrade drop h2/h3 from alpn (HTTP/1.1-only transports; Xray defaults to http/1.1 only when alpn is empty); allowInsecure without a pin is never passed to Xray (it would refuse to start), the certificate is verified normally; VMess with alterId > 0 (legacy protocol without AEAD) is refused with a Russian message. Raw sing-box JSON outbounds pasted by the user (type key, no Xray protocol key) stay with sing-box.

Not covered: the fm share-link parameter (Xray finalmask JSON); the masking session owns it (/root/.agent-todo/zapret-kvn/2026-11-15-obfuscation-question.md).