3x-ui/frontend/ZOD_MIGRATION_STATUS.md

# 3x-ui Frontend Zod Migration — Status

Branch: `feat/frontend-zod-validation` · 83 commits ahead of `main`

Last updated: 2026-05-26

## What this is

The work tracked here is the migration described in
`C:\Users\Hossein Sanaei\.claude\plans\zod-soft-feather.md` — replacing the
class-based xray models (`models/inbound.ts`, `models/outbound.ts`) with Zod
schemas as the single source of truth, standardizing every form on AntD
`Form.useForm` + `antdRule(schema.shape.X)`, and tightening
`@typescript-eslint/no-explicit-any` to `error`.

Verify state: `npm run typecheck` clean, `npm run lint` clean,
`npm run test` 302/302, snapshot baselines 172/172.

---

## Done

### Foundations

- API-boundary Zod validation in TanStack Query hooks (`parseMsg` helper)
- Backend request-body validation via `go-playground/validator`
- Go-first codegen tool (`tools/openapigen`) emitting `zod.ts` + `types.ts`
- `antdRule(schema)` helper bridging Zod issues to AntD form rules
- Five secondary modals migrated to Pattern A (Login, 2FA, Geo, Balancer, Rule)
- Pre-save schema guard on Inbound/Outbound form submits

### Schemas — `frontend/src/schemas/`

- `primitives/` — port, protocol, sniffing, atomic dictionaries
- `protocols/inbound/*` — 10 protocols as leaf schemas
- `protocols/outbound/*` — 11 protocols as leaf schemas
- `protocols/stream/*` — 7 networks (tcp/kcp/ws/grpc/httpupgrade/xhttp/hysteria)
- `protocols/security/*` — 3 securities (none/tls/reality)
- `forms/inbound-form.ts` — `InboundFormValues` discriminated union
- `forms/outbound-form.ts` — `OutboundFormValues` discriminated union
- Stream + security families wired as `z.discriminatedUnion` with intersection

### Pure-function ports — `frontend/src/lib/xray/`

- `headers.ts` — `toHeaders`, `toV2Headers`, `getHeaderValue`
- `inbound-link.ts` — `genVmessLink`, `genVlessLink`, `genTrojanLink`,
  `genShadowsocksLink`, `genHysteriaLink`, Wireguard link/config
- `outbound-link-parser.ts` — vmess/vless/trojan/shadowsocks/hysteria2
- `inbound-defaults.ts` — `createDefault{Vmess,Vless,...}{Client,InboundSettings}`
- `outbound-defaults.ts` — settings factories + dispatcher
- `outbound-form-adapter.ts` — raw ↔ `OutboundFormValues` round-trip
- `protocol-capabilities.ts` — capability predicates as pure functions

### Form modals on Pattern A

- `InboundFormModal.tsx` — full rewrite, atomic-swapped from `.new.tsx`
  - Tabs: Basic, Sniffing, Protocol, Stream, Security, Advanced JSON,
    Fallbacks
  - All 10 protocols (VLESS, VMess, Trojan, Shadowsocks, HTTP, Mixed,
    Tunnel, TUN, Wireguard, Hysteria)
  - Full Stream tab (TCP, KCP, WS, gRPC, HTTPUpgrade, XHTTP, Hysteria)
  - Full Security tab (TLS list, Reality, ECH, mldsa65)
  - 18-field sockopt section, full TLS cert list, external-proxy section
- `OutboundFormModal.tsx` — full rewrite, atomic-swapped from `.new.tsx`
  - All 12 protocols (vmess/vless/trojan/shadowsocks/socks/http/hysteria/
    freedom/blackhole/dns/loopback/wireguard)
  - Full Stream tab with XHTTP advanced fields + xmux sub-form
  - Full Security tab (TLS + Reality + Vision flow)
  - Sockopt section (17 knobs)
  - Mux section
  - JSON tab for advanced fields
  - Link import (vmess/vless/trojan/ss/hysteria2) with full XHTTP
    round-trip (padding obfs + session/seq/uplink keys + all post-size
    knobs)
- `FinalMaskForm` rewritten to Pattern A (Form.List-driven) and wired
  into both stream tabs (Inbound + Outbound). Covers TCP/UDP mask
  arrays, all 13 UDP mask types, header-custom nested groups, noise
  items, and the QUIC params sub-form.

### Tests

- Golden-file fixture suite (`test/golden/fixtures/`)
- Snapshot-baseline regression tests for inbound-full / outbound / stream /
  security DUs
- Shadow-parse harness asserting legacy class and Zod converge
- Link-parser tests (15 round-trip cases including XHTTP padding-obfs)
- Outbound form-adapter tests (15 round-trip cases)
- 302 tests across 12 files, 172 snapshots

### Build infrastructure

- `@typescript-eslint/no-explicit-any: 'error'` enforced
- `.github/workflows/ci.yml` runs `typecheck` + `test` before `build`
- Vite pinned to 8.0.13 (dev-mode dep-optimizer regression in 8.0.14)

---

## Remaining

### Out of migration scope (per plan)

- `DBInbound`, `Status`, `AllSetting` legacy classes — flagged as out of
  scope in `zod-soft-feather.md`. The mainline migration of
  `models/inbound.ts` / `models/outbound.ts` cannot delete them entirely
  while `DBInbound.toInbound()` still imports.
- The plan accepts this and treats parity via snapshot baselines instead.

### Nice-to-haves — would not block ship

- Reality `sid=` multi-value parsing in share-link import
  (outbound reality only carries a single shortId — this is server-side
  state)
- `fm=` (FinalMask) param in share-link import
- VMess link `xmux` nested JSON parsing (currently round-trips at the
  XHTTP top level; nested xmux object is left empty)
- Tighter `.loose()` removal in `schemas/api/inbound.ts`,
  `schemas/api/client.ts`, `schemas/xray.ts` — gated on Step 6 of the plan
  (currently held because the codegen tool still emits one or two loose
  fields the panel writes back)

---

## How to pick up where this left off

1. `git checkout feat/frontend-zod-validation`
2. `cd frontend && npm install && npm run typecheck && npm run test`
3. Open `C:\Users\Hossein Sanaei\.claude\plans\zod-soft-feather.md` —
   Steps 1–5 are done. Step 6 (tighten `.loose()`) and Step 7 (lint/CI
   tightening) are partially done.
4. Nothing in this list blocks ship. The mainline migration goal
   (replace class-based models with Zod schemas + Pattern A forms) is
   done; remaining work is incremental polish.