User-reported vless share link with full xhttp + reality + finalmask
config failed to round-trip on outbound import. The inbound link
generator emits three payloads the outbound parser was ignoring:
1. `extra=<json>` — bundles advanced xhttp knobs (xPaddingBytes,
scMaxEachPostBytes, scMinPostsIntervalMs, padding-obfs keys,
etc.). applyXhttpStringFromParams now JSON.parses this and
merges the fields into xhttpSettings via the same JSON-branch
logic used by vmess.
2. `x_padding_bytes=<range>` — snake_case alias the inbound emits
alongside the camelCase form. Now applied before camelCase so
explicit `xPaddingBytes` URL params still win.
3. `fm=<json>` — full finalmask object including quicParams.udpHop
and tcp/udp mask arrays. New applyFinalMaskParam attaches the
decoded object to streamSettings.finalmask. Wired into both
parseVlessLink and parseTrojanLink.
Tests:
- Real B20 link parses with xhttp + reality + finalmask all populated
- Precedence: camelCase URL > extra JSON > snake_case alias > default
- Malformed extra JSON falls through without crashing the parser
300/300 pass.
Smoke-testing the new inboundFromDb helper surfaced two regressions
that the strict lib/xray link generators expose when fed raw DB
streamSettings without per-network sub-keys.
1. genVlessLink / genTrojanLink crash on `stream.tcpSettings.header`
when streamSettings lacks `tcpSettings` (true for slim list rows
and for handcrafted minimal-JSON inbounds). The legacy
Inbound.fromJson chain populated TcpStreamSettings via its own
constructor; the new helper now does the same by parsing the raw
<network>Settings sub-object through the matching Zod schema and
merging schema defaults onto whatever the DB stored.
2. genVlessLink writes `encryption=undefined` into the share URL
when settings lacks the `encryption: 'none'` literal that vless
wire JSON normally carries. Fixed by running raw settings through
InboundSettingsSchema.safeParse() to populate per-protocol
defaults (encryption, decryption, fallbacks, etc.) the same way
the legacy class fromJson chain did.
Same pattern applied to security branch (tls/realitySettings).
Tests: src/test/inbound-from-db.test.ts covers
- JSON-string / object / empty settings coercion
- genInboundLinks vless (TCP/none, with encryption=none)
- genWireguardConfigs + genWireguardLinks peer fanout
- genAllLinks trojan with TLS sub-defaults applied
- protocol-capability helpers with raw shapes
- getInboundClients across vless/SS-single/non-client protocols
296/296 pass.
Delete models/inbound.ts (3,359 lines) and outbound.ts (2,405).
The Inbound/Outbound classes and ~50 sub-classes are replaced by
Zod-typed data + pure functions in lib/xray/*.
Consumer migration off dbInbound.toInbound():
- useInbounds: isSSMultiUser({protocol, settings}) directly
- QrCodeModal: genWireguardConfigs/Links/AllLinks from lib/xray
- InboundList: derives tags from streamSettings raw fields
- InboundsPage: clone via raw JSON, fallback projection via
schema-shape stream object, exports via genInboundLinks
- InboundInfoModal: builds an InboundInfo facade locally from
raw streamSettings (host/path/serverName/serviceName per
network), canEnableTlsFlow + isSS2022 from lib/xray
New helper: lib/xray/inbound-from-db.ts exposes
inboundFromDb(raw) converting a raw DBInbound row into a
schema-typed Inbound for the link-generation orchestrators.
DBInbound trimmed: drops toInbound, isMultiUser, hasLink,
genInboundLinks, _cachedInbound. Imports Protocols from
@/schemas/primitives now that ./inbound is gone.
Bundled Phase 2 fixes:
- Outbound modal: Form.useWatch with preserve: true so the
stream block doesn't gate itself out when network is unmounted
- Inbound form adapter: pruneEmpty preserves empty objects;
per-protocol client field projection via Zod safeParse;
sniffing collapse to {enabled:false}
- useClients invalidateAll also invalidates inbounds.root()
- IndexPage Config modal top/maxHeight polish
Tests: 283/283 pass. typecheck/lint clean.
Phase 2 smoke fixes on the Inbound add flow surfaced that hysteria2 was
modeled as a separate top-level protocol when it's really just hysteria
v2. The xray transports/hysteria.html docs also pin the hysteria stream
to a minimal shape (version/auth/udpIdleTimeout/masquerade) — the
previous schema carried legacy congestion/up/down/udphop/window knobs
that aren't part of the wire contract.
Hysteria2 removal:
- Drop 'hysteria2' from ProtocolSchema enum and Protocols const
- Drop hysteria2 branches from inbound/outbound discriminated unions
- Drop createDefaultHysteria2InboundSettings / OutboundSettings
- Delete schemas/protocols/inbound/hysteria2.ts and outbound/hysteria2.ts
- Drop hysteria2 case in getInboundClients / genLink (fell through to
the hysteria handler anyway)
- Update client form modals' MULTI_CLIENT_PROTOCOLS sets
- Remove hysteria2-basic fixture + snapshot entries (14 capability
cases, 1 protocols fixture, 1 inbound-defaults factory)
- Keep parseHysteria2Link() outbound parser since hysteria2:// is the
share-link URI prefix for hysteria v2
Hysteria stream alignment with xtls docs:
- HysteriaStreamSettingsSchema reduced to version/auth/udpIdleTimeout/
masquerade per transports/hysteria.html
- Masquerade type adds '' (default 404 page) and defaults to it
- Outbound form drops Congestion/Upload/Download/UDP hop/Max idle/
Keep alive/Disable Path MTU controls and the receive-window note
- newStreamSlice('hysteria') in OutboundFormModal mirrors the trimmed
shape; outbound-link-parser emits the trimmed shape too
- InboundFormModal Masquerade Select gains the default option
New TUN inbound schema:
- Add schemas/protocols/inbound/tun.ts with name/mtu/gateway/dns/
userLevel/autoSystemRoutingTable/autoOutboundsInterface
- Wire into ProtocolSchema enum, InboundSettingsSchema discriminated
union, createDefaultInboundSettings dispatcher
Other Phase 2 smoke fixes folded in:
- Tunnel portMap UI swaps Form.List for HeaderMapEditor v1 — wire
shape is Record<string,string> and the List was producing arrays
- Hysteria onValuesChange seeds full TLS schema defaults + one
empty certificate row (Cipher Suites/Min/Max Version/uTLS/ALPN
were undefined before)
- HTTP/Mixed accounts Add button auto-fills user/pass with
RandomUtil.randomLowerAndNum
- Hysteria security tab gates the 'none' radio out — TLS only
- Hysteria stream tab drops the inbound Auth password field (xray
inbound auth is per-user via 'users', not stream-level)
- Reality onSecurityChange auto-randomizes target/serverNames/
shortIds and fetches an X25519 keypair
- Tag and DB-side fields (up/down/total/expiryTime/
lastTrafficResetTime/clientStats/security) gain hidden Form.Items
so validateFields keeps them in the wire payload (rc-component
form strips unregistered fields)
- WireGuard inbound auto-seeds one peer with generated keypair,
allowedIPs ['10.0.0.2/32'], keepAlive 0 — matches legacy
- WireGuard peer rows separated by Divider with the Peer N title
and a small inline remove button (titlePlacement="center")
Extract the XHTTP key-mapping into typed string/number/bool key arrays
applied by both the URL query-param branch and the vmess JSON branch.
The parser now covers xPaddingObfsMode + xPaddingKey/Header/Placement/
Method, sessionKey/seqKey/uplinkData{Placement,Key}, noSSEHeader,
scMaxBufferedPosts, scStreamUpServerSecs, serverMaxHeaderBytes, and
uplinkHTTPMethod alongside the previous five XHTTP fields. Two new
round-trip tests cover the padding-obfs surface on both link forms.
Pick up xPaddingBytes, scMaxEachPostBytes, scMinPostsIntervalMs,
uplinkChunkSize, and noGRPCHeader from both vmess:// JSON and the URL
query-param parsers (vless/trojan). The advanced xmux/padding-obfs/
reality-shortId knobs still wait on a follow-up; this slice unblocks
the common case where a phone-issued xhttp link carries non-default
padding or post sizes.
The legacy outbound modal could import a vmess://, vless://, trojan://,
ss://, or hysteria2:// share link via a Convert button on the JSON
tab. Restore that UX with a focused pure-function parser.
lib/xray/outbound-link-parser.ts:
- parseVmessLink: base64 JSON, maps net/tls + per-network params onto
the discriminated stream branch.
- parseVlessLink: standard URL with type/security/sni/pbk/sid/fp/flow
query params, dispatches transport via buildStream + applies
security params via applySecurityParams.
- parseTrojanLink: same URL pattern, defaults security to tls.
- parseShadowsocksLink: both modern (base64 userinfo@host:port) and
legacy (base64 of whole thing) ss:// formats.
- parseHysteria2Link: accepts both hysteria2:// and hy2:// schemes,
uses the hysteria stream branch with version=2 + TLS h3.
- parseOutboundLink dispatcher returns the first non-null parser
result, or null when no scheme matches.
test/outbound-link-parser.test.ts:
- 13 cases covering happy paths for each protocol family plus malformed
input, ss:// dual-format handling, hy2:// alias.
OutboundFormModal.tsx:
- Import button on the JSON tab Input.Search; on success, parsed
payload flows through rawOutboundToFormValues, the form is reset,
and we switch back to the Basic tab.
- Tag is preserved when the parsed link does not carry one.
Out of scope: advanced fields the legacy parser handled (xmux, padding
obfs, reality short IDs, finalmask from fm= param). Power users can
finish the import in the form after the basics land.
With the inbound/outbound modal rewrites complete, the cross-check
against the legacy Inbound class has served its purpose. The new
pure-function / Zod-schema paths are the source of truth for production
code; the parity assertions were the migration safety net.
Convert the three parity test files to snapshot-based regression tests:
- headers.test.ts: toHeaders + toV2Headers run against snapshots
captured at the close of the migration (when both new and legacy
were verified byte-equal).
- protocol-capabilities.test.ts: 140 cases (10 fixtures × 14 stream
shapes) snapshot the predicate-result tuple. Was: parity vs legacy
Inbound.canEnableX() class methods.
- inbound-link.test.ts: per-protocol genXxxLink + genInboundLinks
orchestrator output is snapshotted. Was: byte-equality vs legacy
Inbound.genXxxLink() methods.
Also delete shadow.test.ts — its purpose was a dual-parse drift
detector (Inbound.Settings.fromJson vs InboundSettingsSchema.parse).
inbound-full.test.ts already snapshots the Zod parse output, which
covers the same ground without the legacy dependency.
models/inbound.ts and models/outbound.ts stay in the tree for now —
DBInbound still consumes Inbound via its toInbound() method, and
DBInbound migration is out of scope per the migration spec
('Do NOT migrate Status, DBInbound, or AllSetting...'). No
production page imports from @/models/inbound or @/models/outbound
directly anymore.
Lay the groundwork for OutboundFormModal's Pattern A rewrite:
- schemas/forms/outbound-form.ts: discriminated-union form values across
all 12 outbound protocols, with flat per-protocol settings shapes that
match the legacy class fields (vmess vnext / trojan-ss-socks-http
servers / wireguard csv address-reserved all flattened).
- lib/xray/outbound-form-adapter.ts: rawOutboundToFormValues converts
wire-shape outbound JSON to typed form values; formValuesToWirePayload
re-nests on submit. Replaces the Outbound.fromJson/toJson dependency
the modal currently has on the legacy class hierarchy.
- test/outbound-form-adapter.test.ts: 15 round-trip cases covering each
protocol's wire quirks (vmess vnext flatten, vless reverse-wrap,
wireguard csv↔array, blackhole response wrap, DNS rule normalization,
mux gating).
Adds lib/xray/outbound-defaults.ts parallel to inbound-defaults.ts:
13 createDefault*OutboundSettings factories (one per outbound protocol)
plus the createDefaultOutboundSettings(protocol) dispatcher mirroring
Outbound.Settings.getSettings's contract — non-null on each known
protocol, null otherwise.
The factory output matches the legacy `new Outbound.<X>Settings()` start
state: required-by-schema fields the user fills in via the form
(address, port, password, id, peer publicKey/endpoint) come back as
empty stubs. Wireguard alone seeds secretKey via the X25519 generator;
the rest expose blank fields. This is the same behavior the
OutboundFormModal relies on for protocol-change resets.
Shadowsocks defaults to 2022-blake3-aes-128-gcm rather than the legacy
undefined — the Select snaps to the first option anyway, so the
coherent default keeps the modal from rendering an empty picker.
Tests cover three layers:
- exact-shape snapshots per factory (13 cases)
- Zod schema acceptance after sensible stub fill-in (13 cases)
- dispatcher non-null per known protocol + null for the unknown (14 cases)
Adds lib/xray/protocol-capabilities.ts with the seven predicates the
modals call: canEnableTls, canEnableReality, canEnableTlsFlow,
canEnableStream, canEnableVisionSeed, isSS2022, isSSMultiUser. Each
takes a minimal slice of an InboundFormValues, no class instance.
The legacy isSSMultiUser returns true on non-shadowsocks protocols too
(method getter resolves to "" which != blake3-chacha20-poly1305). The
new function preserves this quirk and documents it inline; callers all
narrow on protocol === shadowsocks before checking, so the surprising
return value never surfaces.
Parity harness in test/protocol-capabilities.test.ts crosses each of
the 10 golden fixtures with 14 stream configurations (network × security)
and asserts each predicate matches the legacy class method — 140 cases,
all green.
Adds lib/xray/inbound-form-adapter.ts with rawInboundToFormValues and
formValuesToWirePayload. The pair is the data boundary the upcoming
Pattern A modal will use: it consumes the DB row shape (settings et al.
as string OR object — coerced internally), hands the modal typed
InboundFormValues, and on submit reverses the trip to a wire payload
with the three JSON-stringified slices the Go endpoints expect.
No dependency on the legacy Inbound/DBInbound classes — the coerce step
is inlined so the adapter survives the eventual models/ deletion.
Adds 10 Vitest cases covering string vs object inputs, the optional
streamSettings/nodeId fields, trafficReset coercion, and a raw-to-payload
-to-raw round-trip equality.
Last slice of Step 3d. Five orchestrator exports compose the per-
protocol generators into the public surface the panel consumes:
- resolveAddr(inbound, hostOverride, fallbackHostname): picks the
address that goes into share/sub URLs. Browser `location.hostname`
is no longer a hidden dependency — callers pass it in (or any other
fallback they want).
- getInboundClients(inbound): protocol-aware clients accessor.
Mirrors the legacy `Inbound.clients` getter, including the SS
quirk where 2022-blake3-chacha20 single-user inbounds report null
(no client loop) and everything else returns the clients array.
- genLink: per-protocol dispatcher matching legacy Inbound.genLink.
- genAllLinks: per-client fanout. Builds the remarkModel-formatted
remark (separator + 'i'/'e'/'o' field picker) and iterates
streamSettings.externalProxy when present.
- genInboundLinks: top-level \r\n-joined link block. Loops per
client for clientful protocols, single-shots SS for non-multi-user,
and delegates to genWireguardConfigs for wireguard. Returns ''
for http/mixed/tunnel (no share URL at all).
Plus genWireguardLinks / genWireguardConfigs fanouts which iterate
peers and append index-suffixed remarks.
Parity test exercises every full-inbound fixture against legacy
Inbound.genInboundLinks. Skips hysteria2 (no legacy dispatch case;
that bridge belongs in a separate intentional commit alongside the
form modal swap). Suite: 89 tests across 8 files; typecheck + lint
clean.
Next: Step 4 form modal migrations. Forms can now drop
`new Inbound.Settings.getSettings(protocol)` in favor of the
createDefault*InboundSettings factories, and InboundsPage clone can
swap to genInboundLinks. Models/ deletion follows in Step 5 once all
call sites are off the class.
Fifth and sixth link generators. genHysteriaLink builds the v1/v2
share URL (scheme picked from settings.version), copying TLS knobs into
the query, surfacing the salamander obfs password from
finalmask.udp[type=salamander] when present, and writing the broader
finalmask payload under `fm` like the other links.
Legacy parity note: the old genHysteriaLink read
stream.tls.settings.allowInsecure, which isn't a field on
TlsStreamSettings.Settings — the guard always evaluated false and the
`insecure` param never made it into the URL. We omit it here to stay
byte-stable.
genWireguardLink and genWireguardConfig take a typed
WireguardInboundSettings + peer index and:
- link: wireguard://<peerPriv>@host:port?publickey=&address=&mtu=#remark
- config: the .conf text WireGuard clients consume directly
Both derive the server pubKey from settings.secretKey via
Wireguard.generateKeypair at call time — Zod stores only secretKey on
the wire (pubKey is computed). The Wireguard utility is pure JS (X25519
over Float64Array), so it runs fine under node + the window polyfill we
added with the vmess extraction.
Two new full-inbound fixtures (hysteria-v1-tls, wireguard-server) plus
matching parity tests bring the suite to 78 tests across 8 files;
typecheck + lint clean.
Hysteria2 (protocol literal) parity stays deferred — the legacy
class has no HYSTERIA2 dispatch case, so it can't round-trip a
hysteria2 fixture without a protocol remap. Same trick the shadow
harness uses; revisit in the orchestrator commit.
Third and fourth link generators. genTrojanLink mirrors genVlessLink's
shape (URLSearchParams + network/security branches + remark hash) minus
the encryption/flow VLESS-isms. genShadowsocksLink shares the same query
construction but base64-encodes the userinfo portion as method:password
or method:settingsPw:clientPw depending on whether SS-2022 is in
single-user or multi-user mode.
Three reusable helpers move out of the per-protocol functions:
- writeNetworkParams: the per-network switch that all param-style
links share (tcp http header / kcp mtu+tti / ws path+host /
grpc serviceName+authority / httpupgrade / xhttp extras)
- writeTlsParams: fingerprint/alpn/ech/sni
- writeRealityParams: pbk/sid/spx/pqv (preserves the SNI-omission
legacy parity quirk noted in the genVlessLink commit)
genVmessLink stays with its inline switch — it builds a JSON obj instead
of URLSearchParams and has per-network quirks (kcp emits mtu+tti at
the obj root, grpc maps multiMode to obj.type='multi') that don't
factor cleanly through the shared writer.
Two new full-inbound fixtures (trojan-ws-tls, shadowsocks-tcp-2022)
plus matching parity tests bring the suite to 74 tests across 8 files;
typecheck + lint clean.
Second link generator. genVlessLink builds the
vless://<uuid>@<host>:<port>?<query>#<remark> share URL from a typed
Inbound + client args, dispatching on streamSettings.network for the
network-specific knobs and on streamSettings.security for the
TLS/Reality knobs. Three param-style helpers move alongside the obj-
style ones already in this file:
- applyXhttpExtraToParams — writes path/host/mode/x_padding_bytes and
the JSON extra blob into URLSearchParams
- applyFinalMaskToParams — writes the fm payload when shareable
- applyExternalProxyTLSParams — overrides sni/fp/alpn when an external
proxy entry is supplied and security is tls
A vless-tcp-reality fixture lands alongside the existing vless-ws-tls
one, so the parity test now exercises both security branches.
Discovered a latent legacy bug while writing parity: the old class
stored realitySettings.serverNames as a comma-joined string and gated
SNI on `!ObjectUtil.isArrEmpty(serverNames)`, which always returns true
for strings — so SNI was never written into Reality share URLs.
Existing clients rely on the omission (they pull SNI from
realitySettings.target instead). We preserve the omission here to keep
this extraction byte-stable; an inline comment marks the spot for a
separate intentional fix.
Suite: 70 tests across 8 files; typecheck + lint clean.
First link generator to leave the class hierarchy. genVmessLink takes a
typed Inbound + client args and returns the base64-encoded vmess://
URL. Internal helpers (buildXhttpExtra, applyXhttpExtraToObj,
applyFinalMaskToObj, applyExternalProxyTLSObj, serializeFinalMask,
hasShareableFinalMaskValue, externalProxyAlpn) port across from
XrayCommonClass — same logic, rewritten to read the Zod schemas'
Record<string, string> headers instead of the legacy HeaderEntry[].
Parity test (inbound-link.test.ts) loads each vmess fixture in
golden/fixtures/inbound-full, parses it with InboundSchema for the new
pure fn AND constructs LegacyInbound.fromJson(raw) for the class method,
then asserts the URLs match byte-for-byte. Drift between the two impls
fails here before the call sites in pages/inbounds/* get swapped.
Adds a small test setup file that aliases globalThis.window to globalThis
so Base64.encode's window.btoa works under Node — keeps the test env at
'node' and avoids pulling jsdom as a new dep.
A first vmess-tcp-tls full-inbound fixture pins the round-trip path.
Suite: 67 tests across 8 files; typecheck + lint clean. Five more link
generators (vless/trojan/ss/hysteria/wireguard) plus the orchestrator
(toShareLink, genAllLinks) follow in subsequent turns.
Step 3d's last scaffolding piece before link generators. Three new
stream-extras schemas land alongside the network/security DUs:
- finalmask: TcpMask[] + UdpMask[] + QuicParams. Mask `settings` stays
record<string, unknown> for now — there are 13 UDP mask types and 3
TCP mask types with distinct per-type setting shapes, and modeling
them all as DUs would dwarf the rest of stream/ without buying
anything the shadow harness doesn't already catch. Tightened in
Step 6.
- sockopt: 17 socket-tuning knobs (TCP keepalive, TFO, mark, tproxy,
mptcp, dialer proxy, IPv6-only, congestion). `interfaceName` field
matches the panel class naming; serializers rename to `interface` on
the wire.
- external-proxy: rows ship per inbound describing edge fronts (CDN
mirrors). Used by link generators to fan out share URLs.
schemas/api/inbound.ts composes the top-level wire shape with
intersection-of-DUs:
StreamSettingsSchema = NetworkSettingsSchema
.and(SecuritySettingsSchema)
.and(StreamExtrasSchema)
InboundSchema = InboundCoreSchema.and(InboundSettingsSchema)
A fixture (vless-ws-tls.json) exercises the full shape — protocol DU,
network DU, security DU, and TLS cert file branch in one round trip.
The snapshot pins the canonical parsed form so the upcoming link
extractor consumes typed input with no class hierarchy underneath.
Suite: 65 tests across 7 files; typecheck + lint clean. Zod 4
intersection-of-DUs works.
Tiny piece of the toShareLink scaffold. The legacy Inbound.getHeader(obj,
name) iterated the panel's internal HeaderEntry[] form; the new
getHeaderValue reads the Record<string, string|string[]> map our Zod
schemas store on the wire. Case-insensitive, returns '' on miss to match
the legacy fallback so link-generator call sites stay simple.
For repeated-name maps (TCP/WS-style string[] values) the first value
wins — matches the legacy iteration order so the share URL's Host hint
stays deterministic.
Five unit tests cover undefined/null/empty inputs, case folding,
string-valued and array-valued matches, empty-array edge case, and
missing-key fallback. Suite: 64 tests across 6 files; typecheck + lint
clean.
This unblocks the next slice: per-protocol link generators (genVmessLink
etc.) take a typed inbound + client and call getHeaderValue against the
ws/httpupgrade/xhttp/tcp.request header maps.
Round out Step 3d's settings factory set. Ten plain-object factories
(vless / vmess / trojan / shadowsocks / hysteria / hysteria2 / http /
mixed / tunnel / wireguard) replace the legacy
`new Inbound.<X>Settings(protocol)` constructors. Each returns a Zod-
parsable wire shape with schema defaults applied — no class instance.
Forms (Step 4) and InboundsPage clone (Step 5) call these factories
directly once the swap lands.
Three factories take a seed for random fields:
- shadowsocks: method-dependent password length via
RandomUtil.randomShadowsocksPassword(method)
- hysteria: explicit `version` override (defaults to 2, matching
the legacy panel constructor — v1 is opt-in)
- wireguard: secretKey from Wireguard.generateKeypair().privateKey
Tests double-verify each factory the same way as the client factories:
snapshot the shape, then Zod parse round-trip to confirm no missing
defaults or stray fields.
Suite: 59 tests across 6 files; typecheck + lint clean. Outbound
factories and the toShareLink extraction follow next.
Next Step 3d slice. Five plain-object factories — Vless, Vmess, Trojan,
Shadowsocks, Hysteria — replace the legacy
`new Inbound.<Protocol>Settings.<Protocol>(...)` constructor chain and the
ClientBase XrayCommonClass machinery. Each factory takes an optional
seed; missing random fields (id, password, auth, email, subId) fall
through to RandomUtil at call time. Forms can hand-pick a UUID; tests
pass deterministic seeds so the suite never touches window.crypto.
Tests double-verify each factory: a snapshot locks the exact shape, and
the matching Zod ClientSchema.parse(out) must equal `out` — no missing
defaults, no stray fields, type-narrowed end-to-end.
Discovered: VmessClientSchema and VlessClientSchema enforce z.uuid()
format, so the test seeds use real-shape UUIDs.
Suite: 49 tests across 6 files; typecheck + lint clean. Outbound and
inbound-settings factories follow in subsequent turns alongside the
toShareLink extraction.
First Step 3d extraction. The XrayCommonClass static helpers
toHeaders/toV2Headers are pure data shape conversions with no class
hierarchy needs, so they move to a standalone module that callers can
import without dragging in models/inbound.ts. The new module exports
HeaderEntry + V2HeaderMap as named types so consumers stop reaching into
the legacy class for type shapes.
A new test file (headers.test.ts) asserts byte-equality with the legacy
XrayCommonClass.toHeaders / .toV2Headers across 18 cases — null /
undefined / primitive inputs, single-string headers, array-valued
headers, duplicate names, empty-name and empty-value filtering, both
arr=true (TCP request/response shape) and arr=false (WS / xHTTP / sockopt
shape). Drift between the legacy and new impls fails these tests, so the
follow-up call-site swap stays safe.
Callers (TcpStreamSettings, WsStreamSettings, HTTPUpgradeStreamSettings,
TunnelSettings, etc.) still go through XrayCommonClass for now — those
swaps land alongside class-method extractions in subsequent turns.
Suite is now 44 tests across 5 files; typecheck + lint clean.
Add Step 3c's safety net: for every inbound golden fixture, run the raw
payload through both pipelines —
legacy: Inbound.Settings.fromJson(protocol, raw.settings).toJson()
zod: InboundSettingsSchema.parse(raw).settings
— canonicalize each (recursively sort keys, drop empty arrays / null /
undefined), and assert byte-equality. This locks the wire shape across the
upcoming class-to-pure-function extraction in Step 3d. Any normalization
drift introduced by the rewrite trips an assertion here before it can
reach users.
Two ergonomic wrinkles handled inline:
- The legacy class lumps hysteria + hysteria2 onto a single
HysteriaSettings (no hysteria2 case in the dispatch table); the test
routes hysteria2 fixtures through the HYSTERIA branch.
- Empty arrays in Zod's output (e.g. fallbacks: [] from a .default([]))
are treated as equivalent to the legacy class's omit-when-empty
behavior. Same wire state, different syntactic surface.
All 26 tests across 4 test files pass on first run.
Round out Step 3b. Four more inbound fixtures complete the protocol set
(http with two accounts, mixed with socks-style auth, tunnel with a port
map, hysteria v1). Two parallel test files cover the other DUs:
stream.test.ts walks tcp/ws/grpc fixtures through NetworkSettingsSchema,
and security.test.ts walks none/tls/reality through SecuritySettingsSchema.
Snapshot count is now 16 across three test files. The reality fixture
locks in the array form of serverNames/shortIds (the panel class stores
them comma-joined internally but they ship as arrays on the wire). The
TLS fixture pins the file-vs-inline cert DU on the file branch.
Stream coverage for httpupgrade/xhttp/kcp and security mixed-with-stream
combos follow in the next turn, alongside the shadow harness.
Stand up Phase 3 safety net before the models/ rewrite. The harness loads
JSON fixtures via Vite's import.meta.glob, parses each through
InboundSettingsSchema (the tagged-wrapper DU), and snapshots the canonical
parsed shape. Snapshots stay byte-stable across the upcoming class-to-
pure-function extraction, catching any normalization drift.
Six representative inbound fixtures cover the high-traffic protocols:
vless, vmess, trojan, shadowsocks (2022-blake3 multi-user), wireguard,
hysteria2. Stream and security branches plus the remaining protocols
(http, mixed, tunnel, hysteria) follow in subsequent turns.
Uses /// <reference types="vite/client" /> instead of @types/node so we
avoid pulling in another type package; import.meta.glob is enough to walk
the fixtures directory at compile time.
Adds vitest 4.1.7 as the only new dev dependency. test/test:watch scripts
land in package.json; a standalone vitest.config.ts keeps the production
vite.config.js (which reads from sqlite via DatabaseSync) out of the test
runner.
