3x-ui/frontend/scripts/build-openapi.mjs

368 lines
12 KiB
JavaScript
Raw Normal View History

feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
#!/usr/bin/env node
import { writeFileSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { sections } from '../src/pages/api-docs/endpoints.ts';
import {
buildWebSocketEvents,
websocketEnvelopeSchema,
} from '../src/pages/api-docs/websocket-events.ts';
import { EXAMPLES } from '../src/generated/examples.ts';
import { SCHEMAS } from '../src/generated/schemas.ts';
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
const websocketEvents = buildWebSocketEvents(EXAMPLES);
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
const __dirname = dirname(fileURLToPath(import.meta.url));
const outPath = join(__dirname, '..', 'public', 'openapi.json');
const PANEL_VERSION = process.env.X_UI_VERSION || '3.x';
const SECURITY_SCHEMES = {
bearerAuth: {
type: 'http',
scheme: 'bearer',
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
description:
'API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>`.',
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
},
cookieAuth: {
type: 'apiKey',
in: 'cookie',
name: '3x-ui',
description: 'Session cookie set by POST /login. Browser-only.',
},
};
function ginPathToOpenApi(path) {
return path.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, '{$1}');
}
function extractPathParams(openApiPath) {
const params = [];
const re = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
let m;
while ((m = re.exec(openApiPath)) !== null) params.push(m[1]);
return params;
}
function mapType(t) {
const v = String(t || '').toLowerCase();
Add per-client external link controls (#5650) * Add enable toggle for external client links * Document external link enable API fields * Extend external client link metadata * Fix external subscription cache status updates * fix(sub): address the review on per-client external link controls Blocking: the expiry filter dropped legacy rows. expiry_time was added without a default, so AutoMigrate makes it nullable and backfills NULL, and `expiry_time = 0 OR expiry_time > ?` is false for NULL under three-valued logic — every external link written before the upgrade vanished from all subscriptions. Add `default:0` on expiry_time and last_fetch_at, make the predicate NULL-tolerant, and backfill the NULLs a pre-fix build could already have written. Rework fetch-status recording. It ran inside the singleflight in-flight window, so every goroutine parked on the shared fetch waited for a DB write to commit on the public, unauthenticated subscription path — and because it was keyed on the row id, waiters and cache hits recorded nothing, leaving rows that lost the race stuck on "Not fetched yet" forever. fetchSubscriptionLinks now reports whether it did the network fetch and expandEntry records afterwards, off the serving path, keyed on kind+value so every row sharing the URL is stamped by the one fetch. Keying on value also closes the recycled-rowid hazard: saves delete and re-insert rows, and SQLite reuses rowids, so an in-flight write could land on an unrelated client's row. The write no longer discards its error either. Drop the inert id round-trip. The panel never sent it, and the byId branch was guarded by the exact kind+value equality that byKindValue already keys on, so it could not change an outcome. Matching on kind+value alone is what actually preserves fetch status across saves. Reject a negative expiryTime instead of storing a row that is silently invisible in every subscription — elsewhere a negative expiryTime means "a duration from first use", so an API caller reusing that convention got no error and no links. Drop the ~50 lines of .client-form-* / .client-inbounds-field CSS that no component renders; it is leftover from the WireGuard PR this one was split from. i18n: reuse the already-translated pages.inbounds.leaveBlankToNeverExpire instead of shipping an English duplicate under pages.clients, and translate namePrefix, lastFetchAt, lastFetchError and neverFetched into all 12 non-English locales. Cover the persistence path that had no test: the fetch-status writer over a real DB against a failing then a succeeding server, a cache hit writing nothing, and the negative-expiry rejection. --------- Co-authored-by: MHSanaei <ho3ein.sanaei@gmail.com>
2026-08-18 04:55:04 -07:00
if (v.endsWith('[]')) return 'array';
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
if (v === 'number' || v === 'integer' || v === 'int') return 'integer';
if (v === 'float' || v === 'double') return 'number';
if (v === 'boolean' || v === 'bool') return 'boolean';
if (v === 'array') return 'array';
if (v === 'object') return 'object';
return 'string';
}
Add per-client external link controls (#5650) * Add enable toggle for external client links * Document external link enable API fields * Extend external client link metadata * Fix external subscription cache status updates * fix(sub): address the review on per-client external link controls Blocking: the expiry filter dropped legacy rows. expiry_time was added without a default, so AutoMigrate makes it nullable and backfills NULL, and `expiry_time = 0 OR expiry_time > ?` is false for NULL under three-valued logic — every external link written before the upgrade vanished from all subscriptions. Add `default:0` on expiry_time and last_fetch_at, make the predicate NULL-tolerant, and backfill the NULLs a pre-fix build could already have written. Rework fetch-status recording. It ran inside the singleflight in-flight window, so every goroutine parked on the shared fetch waited for a DB write to commit on the public, unauthenticated subscription path — and because it was keyed on the row id, waiters and cache hits recorded nothing, leaving rows that lost the race stuck on "Not fetched yet" forever. fetchSubscriptionLinks now reports whether it did the network fetch and expandEntry records afterwards, off the serving path, keyed on kind+value so every row sharing the URL is stamped by the one fetch. Keying on value also closes the recycled-rowid hazard: saves delete and re-insert rows, and SQLite reuses rowids, so an in-flight write could land on an unrelated client's row. The write no longer discards its error either. Drop the inert id round-trip. The panel never sent it, and the byId branch was guarded by the exact kind+value equality that byKindValue already keys on, so it could not change an outcome. Matching on kind+value alone is what actually preserves fetch status across saves. Reject a negative expiryTime instead of storing a row that is silently invisible in every subscription — elsewhere a negative expiryTime means "a duration from first use", so an API caller reusing that convention got no error and no links. Drop the ~50 lines of .client-form-* / .client-inbounds-field CSS that no component renders; it is leftover from the WireGuard PR this one was split from. i18n: reuse the already-translated pages.inbounds.leaveBlankToNeverExpire instead of shipping an English duplicate under pages.clients, and translate namePrefix, lastFetchAt, lastFetchError and neverFetched into all 12 non-English locales. Cover the persistence path that had no test: the fetch-status writer over a real DB against a failing then a succeeding server, a cache hit writing nothing, and the negative-expiry rejection. --------- Co-authored-by: MHSanaei <ho3ein.sanaei@gmail.com>
2026-08-18 04:55:04 -07:00
function schemaFromType(t) {
const v = String(t || '').toLowerCase();
if (v.endsWith('[]')) {
const itemType = v.slice(0, -2);
return { type: 'array', items: { type: mapType(itemType) } };
}
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
if (v === 'file') return { type: 'string', format: 'binary' };
Add per-client external link controls (#5650) * Add enable toggle for external client links * Document external link enable API fields * Extend external client link metadata * Fix external subscription cache status updates * fix(sub): address the review on per-client external link controls Blocking: the expiry filter dropped legacy rows. expiry_time was added without a default, so AutoMigrate makes it nullable and backfills NULL, and `expiry_time = 0 OR expiry_time > ?` is false for NULL under three-valued logic — every external link written before the upgrade vanished from all subscriptions. Add `default:0` on expiry_time and last_fetch_at, make the predicate NULL-tolerant, and backfill the NULLs a pre-fix build could already have written. Rework fetch-status recording. It ran inside the singleflight in-flight window, so every goroutine parked on the shared fetch waited for a DB write to commit on the public, unauthenticated subscription path — and because it was keyed on the row id, waiters and cache hits recorded nothing, leaving rows that lost the race stuck on "Not fetched yet" forever. fetchSubscriptionLinks now reports whether it did the network fetch and expandEntry records afterwards, off the serving path, keyed on kind+value so every row sharing the URL is stamped by the one fetch. Keying on value also closes the recycled-rowid hazard: saves delete and re-insert rows, and SQLite reuses rowids, so an in-flight write could land on an unrelated client's row. The write no longer discards its error either. Drop the inert id round-trip. The panel never sent it, and the byId branch was guarded by the exact kind+value equality that byKindValue already keys on, so it could not change an outcome. Matching on kind+value alone is what actually preserves fetch status across saves. Reject a negative expiryTime instead of storing a row that is silently invisible in every subscription — elsewhere a negative expiryTime means "a duration from first use", so an API caller reusing that convention got no error and no links. Drop the ~50 lines of .client-form-* / .client-inbounds-field CSS that no component renders; it is leftover from the WireGuard PR this one was split from. i18n: reuse the already-translated pages.inbounds.leaveBlankToNeverExpire instead of shipping an English duplicate under pages.clients, and translate namePrefix, lastFetchAt, lastFetchError and neverFetched into all 12 non-English locales. Cover the persistence path that had no test: the fetch-status writer over a real DB against a failing then a succeeding server, a cache hit writing nothing, and the negative-expiry rejection. --------- Co-authored-by: MHSanaei <ho3ein.sanaei@gmail.com>
2026-08-18 04:55:04 -07:00
return { type: mapType(v) };
}
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
function schemaFromParam(p) {
const schema = schemaFromType(p.type);
if (p.defaultValue !== undefined) schema.default = p.defaultValue;
if (p.minLength !== undefined) schema.minLength = p.minLength;
if (p.pattern !== undefined) schema.pattern = p.pattern;
if (p.enum !== undefined) schema.enum = [...p.enum];
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
return schema;
}
function requestBodyContentType(ep, bodyParams) {
const locations = new Set(bodyParams.map((p) => p.in));
if (locations.size > 1) {
throw new Error(
`${ep.method} ${ep.path}: request body mixes parameter locations: ${[...locations].join(', ')}`,
);
}
switch (bodyParams[0]?.in) {
case 'body (form)':
return 'application/x-www-form-urlencoded';
case 'body (multipart)':
return 'multipart/form-data';
default:
return 'application/json';
}
}
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
function tryParseJson(raw) {
if (typeof raw !== 'string') return undefined;
try {
return JSON.parse(raw);
} catch {
return undefined;
}
}
function paramToOpenApi(p) {
const out = {
name: p.name,
in: p.in,
required: p.in === 'path' ? true : !p.optional,
description: p.desc || '',
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
schema: schemaFromParam(p),
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
};
return out;
}
feat(sub): add read-only HWID device-slot status endpoint (#6380) * feat(sub): add read-only HWID device-slot status endpoint Closes #6357 A client with an HWID limit had no way to tell a subscriber how many device slots were left: /{subPath}/{subId} only exposes the gate as a boolean through X-Hwid-* headers on a 404, and ?format=info carries no limitHwid or registered count. Every "why can't I connect on my new phone" case therefore had to be answered by the operator by hand. GET /{subPath}/{subId}/hwid-status now returns the aggregate counters: {"active":true,"limit":2,"registered":1,"remaining":1,"full":false} - SELECT-only. It never registers an hwid, never touches last_seen and never calls the enforcement path, so asking about a slot cannot spend one. - Counters only: no hwid value or hash, no email, no device metadata, no IP, no User-Agent, and none of the X-Hwid-* gate headers. - The subscription id is already the bearer secret for /{subPath}/{subId}, so no admin token and no new auth mechanism. - Unknown and disabled subscriptions both answer a bare 404, with identical status, headers and body, so the route cannot be used to probe which subscription ids exist. - No HWID limit configured returns {"active":false,"limit":0,...}. - No schema change and no migration. Scoped to enabled clients exactly like effectiveHwidLimitForSubID, so the reported limit is always the limit the gate enforces on a shared sub_id, and remaining clamps at zero when the effective limit drops below the number of registered devices. A separate route leaves /{subPath}/{subId}, ?format=info and the JSON/Clash routes byte-for-byte unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(sub): document hwid-status as the bare object it returns The OpenAPI operation for GET /{subPath}/{subId}/hwid-status inherited the {success,msg,obj} panel envelope from build-openapi.mjs's default 200 response, while the handler writes the HwidSlotStatus struct bare. A client generated from the spec would read `obj` and never find the counters, and the description prose contradicted the schema with a hand-written example. HwidSlotStatus now sits in openapigen's StructAllow with example: tags, the entry references the generated schema through a `responses` block, and build-openapi.mjs attaches the generated example to any `responses` entry that $refs a generated schema, so no example is hand-written. The HEAD variant the controller registers is documented like its siblings, and the summary follows the "path prefix is configured by subPath" wording now that fresh panels randomise the prefix. Regenerated frontend/public/openapi.json, docs/public/openapi.json and the subscription-server MDX. openapi-runtime-contracts.test.ts pins the bare schema, the generated example and the HEAD operation. --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-11 02:59:35 -07:00
// A `responses` entry that $refs a generated schema takes its example from the
// Go `example:` tags, the same source responseSchema uses — never hand-written.
function withGeneratedExample(ep, code, res) {
const json = res.content?.['application/json'];
const name = json?.schema?.$ref?.replace('#/components/schemas/', '');
if (!name) return res;
if (SCHEMAS[name] === undefined || EXAMPLES[name] === undefined) {
throw new Error(`${ep.method} ${ep.path}: ${code} response schema "${name}" is not generated`);
}
return {
...res,
content: { ...res.content, 'application/json': { example: EXAMPLES[name], ...json } },
};
}
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
function buildOperation(ep, tag) {
const op = {
tags: [tag],
summary: ep.summary || '',
operationId: `${ep.method.toLowerCase()}_${ep.path.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_|_$/g, '')}`,
};
if (ep.description) op.description = ep.description;
if (ep.deprecated) op.deprecated = true;
const params = [];
const bodyParams = [];
for (const p of ep.params || []) {
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
if (p.in.startsWith('body')) {
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
bodyParams.push(p);
} else if (p.in === 'path' || p.in === 'query' || p.in === 'header') {
params.push(paramToOpenApi(p));
}
}
const openApiPath = ginPathToOpenApi(ep.path);
const declared = new Set(params.filter((x) => x.in === 'path').map((x) => x.name));
for (const name of extractPathParams(openApiPath)) {
if (declared.has(name)) continue;
params.push({
name,
in: 'path',
required: true,
description: '',
schema: { type: 'string' },
});
}
if (params.length > 0) op.parameters = params;
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
if (ep.body || bodyParams.length > 0 || ep.requestSchema) {
const contentType = requestBodyContentType(ep, bodyParams);
const example = contentType === 'application/json' ? tryParseJson(ep.body) : undefined;
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
const properties = {};
const required = [];
for (const bp of bodyParams) {
properties[bp.name] = {
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
...schemaFromParam(bp),
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
description: bp.desc || '',
};
if (!bp.optional) required.push(bp.name);
}
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
let schema;
if (ep.requestSchema) {
if (bodyParams.length > 0 || ep.bodyRequiredOneOf?.length) {
throw new Error(
`${ep.method} ${ep.path}: requestSchema cannot be combined with body parameters or bodyRequiredOneOf`,
);
}
schema = ep.requestSchema;
} else {
schema =
bodyParams.length > 0
? { type: 'object', properties, ...(required.length > 0 ? { required } : {}) }
: { type: 'object' };
if (ep.bodyRequiredOneOf?.length) {
schema = {
anyOf: ep.bodyRequiredOneOf.map((name) => {
if (!properties[name]) {
throw new Error(
`${ep.method} ${ep.path}: bodyRequiredOneOf "${name}" is not a declared body parameter`,
);
}
const branchProperties = { ...properties };
for (const other of ep.bodyRequiredOneOf) {
if (other === name || !branchProperties[other]) continue;
const { pattern: _pattern, minLength: _minLength, ...rest } = branchProperties[other];
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
branchProperties[other] = rest;
}
return {
type: 'object',
properties: branchProperties,
required: [...required, name],
};
}),
};
}
}
const encoding = {};
if (contentType === 'application/x-www-form-urlencoded') {
for (const bp of bodyParams) {
const kind = schemaFromType(bp.type).type;
if (kind === 'array') {
encoding[bp.name] = { style: 'form', explode: true };
} else if (kind === 'object') {
// The panel reads such a field with json.Unmarshal, so it must be sent
// as JSON text rather than form-style key/value pairs.
encoding[bp.name] = { contentType: 'application/json' };
}
}
}
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
op.requestBody = {
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
required:
Boolean(ep.requestSchema) ||
Boolean(ep.bodyRequiredOneOf?.length) ||
required.length > 0 ||
bodyParams.length === 0,
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
content: {
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
[contentType]: {
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
schema,
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
...(Object.keys(encoding).length > 0 ? { encoding } : {}),
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
...(example !== undefined ? { example } : {}),
},
},
};
}
const responses = {};
let successExample = tryParseJson(ep.response);
let objSchema = {};
if (ep.responseObjectSchema && ep.responseSchema) {
throw new Error(`${ep.method} ${ep.path}: responseObjectSchema cannot use responseSchema`);
}
if (ep.responseObjectSchema) objSchema = ep.responseObjectSchema;
if (ep.responseSchema) {
const obj = EXAMPLES[ep.responseSchema];
if (obj === undefined) {
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
throw new Error(
`${ep.method} ${ep.path}: responseSchema "${ep.responseSchema}" has no generated example`,
);
}
if (SCHEMAS[ep.responseSchema] === undefined) {
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
throw new Error(
`${ep.method} ${ep.path}: responseSchema "${ep.responseSchema}" has no generated schema`,
);
}
const ref = { $ref: `#/components/schemas/${ep.responseSchema}` };
objSchema = ep.responseSchemaArray
? {
type: 'array',
...(ep.responseSchemaArrayNullable ? { nullable: true } : {}),
items: ref,
}
: ref;
if (successExample === undefined) {
successExample = { success: true, obj: ep.responseSchemaArray ? [obj] : obj };
}
}
if (ep.responses) {
feat(sub): add read-only HWID device-slot status endpoint (#6380) * feat(sub): add read-only HWID device-slot status endpoint Closes #6357 A client with an HWID limit had no way to tell a subscriber how many device slots were left: /{subPath}/{subId} only exposes the gate as a boolean through X-Hwid-* headers on a 404, and ?format=info carries no limitHwid or registered count. Every "why can't I connect on my new phone" case therefore had to be answered by the operator by hand. GET /{subPath}/{subId}/hwid-status now returns the aggregate counters: {"active":true,"limit":2,"registered":1,"remaining":1,"full":false} - SELECT-only. It never registers an hwid, never touches last_seen and never calls the enforcement path, so asking about a slot cannot spend one. - Counters only: no hwid value or hash, no email, no device metadata, no IP, no User-Agent, and none of the X-Hwid-* gate headers. - The subscription id is already the bearer secret for /{subPath}/{subId}, so no admin token and no new auth mechanism. - Unknown and disabled subscriptions both answer a bare 404, with identical status, headers and body, so the route cannot be used to probe which subscription ids exist. - No HWID limit configured returns {"active":false,"limit":0,...}. - No schema change and no migration. Scoped to enabled clients exactly like effectiveHwidLimitForSubID, so the reported limit is always the limit the gate enforces on a shared sub_id, and remaining clamps at zero when the effective limit drops below the number of registered devices. A separate route leaves /{subPath}/{subId}, ?format=info and the JSON/Clash routes byte-for-byte unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(sub): document hwid-status as the bare object it returns The OpenAPI operation for GET /{subPath}/{subId}/hwid-status inherited the {success,msg,obj} panel envelope from build-openapi.mjs's default 200 response, while the handler writes the HwidSlotStatus struct bare. A client generated from the spec would read `obj` and never find the counters, and the description prose contradicted the schema with a hand-written example. HwidSlotStatus now sits in openapigen's StructAllow with example: tags, the entry references the generated schema through a `responses` block, and build-openapi.mjs attaches the generated example to any `responses` entry that $refs a generated schema, so no example is hand-written. The HEAD variant the controller registers is documented like its siblings, and the summary follows the "path prefix is configured by subPath" wording now that fresh panels randomise the prefix. Regenerated frontend/public/openapi.json, docs/public/openapi.json and the subscription-server MDX. openapi-runtime-contracts.test.ts pins the bare schema, the generated example and the HEAD operation. --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-11 02:59:35 -07:00
for (const [code, res] of Object.entries(ep.responses)) {
responses[code] = withGeneratedExample(ep, code, res);
}
} else {
responses['200'] = {
description: 'Successful response',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
success: { type: 'boolean' },
msg: { type: 'string' },
obj: objSchema,
},
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
},
...(successExample !== undefined ? { example: successExample } : {}),
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
},
},
};
}
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
const errExample = tryParseJson(ep.errorResponse);
if (errExample !== undefined || ep.errorStatus) {
const code = String(ep.errorStatus || 400);
responses[code] = {
description: 'Error response',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
success: { type: 'boolean' },
msg: { type: 'string' },
},
},
...(errExample !== undefined ? { example: errExample } : {}),
},
},
};
}
op.responses = responses;
if (ep.security !== undefined) op.security = ep.security;
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
return op;
}
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
export function buildSpec() {
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
const paths = {};
for (const section of sections) {
const tag = section.title;
for (const ep of section.endpoints) {
const openApiPath = ginPathToOpenApi(ep.path);
if (!paths[openApiPath]) paths[openApiPath] = {};
paths[openApiPath][ep.method.toLowerCase()] = buildOperation(ep, tag);
}
}
paths['/ws'].get['x-websocket-events'] = websocketEvents;
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
const tags = sections.map((s) => ({
name: s.title,
description: s.description || '',
}));
return {
openapi: '3.0.3',
info: {
title: '3X-UI Panel API',
version: PANEL_VERSION,
description:
'Programmatic interface to a 3X-UI panel. Authenticate either by logging in (cookie) or with an API token from Settings → Security → API Token (Bearer). All endpoints under /panel/api/* honour both modes — an API token is a full-admin credential, so treat it like the panel password.',
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
},
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
servers: [{ url: '/', description: 'Current panel (basePath aware)' }],
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
components: {
securitySchemes: SECURITY_SCHEMES,
schemas: { ...SCHEMAS, WebSocketEnvelope: websocketEnvelopeSchema },
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
},
security: [{ bearerAuth: [] }, { cookieAuth: [] }],
tags,
paths,
};
}
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
const spec = buildSpec();
writeFileSync(outPath, JSON.stringify(spec, null, 2) + '\n');
feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541) * feat(frontend): introduce TanStack Query with status polling Wires @tanstack/react-query into every entry and migrates useStatus to useStatusQuery as the foundation for the multi-page MPA → SPA migration. - QueryProvider wraps each entry inside ThemeProvider, with devtools gated on import.meta.env.DEV - Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry - useStatusQuery preserves the { status, fetched, refresh } shape so IndexPage swaps in without further changes - refetchIntervalInBackground:false stops the 2s status poll when the panel tab is hidden, cutting idle traffic against the server * feat(frontend): collapse panel pages into a single React Router SPA Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/ xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The Go backend now serves the same index.html for every authenticated panel route; React Router reads the URL and mounts the page from cache on subsequent navigation — no more full reloads between tabs. Frontend - main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider, QueryProvider, RouterProvider) replacing 7 near-duplicate entries - routes.tsx: declarative router with lazy()-loaded pages, basename derived from window.X_UI_BASE_PATH so panels at /secret/panel work - layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient bridge so connection survives navigation - api/websocketBridge.ts: subscribes the singleton WebSocketClient to queryClient and dispatches invalidate/outbounds events to cached queries (page-level useWebSocket handlers stay until Phase 3 hooks migrate) - AppSidebar: navigates via useNavigate + useLocation instead of window.location.href; drops basePath/requestUri props - Pages: drop the unused basePath/requestUri locals exposed only for the old sidebar Build - vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy bypass collapses /panel/* to index.html and skips API prefixes - vendor-tanstack + vendor-router chunks added to manualChunks Backend - xui.go: 7 per-page HTML handlers → one panelSPA handler serving index.html for /, /inbounds, /clients, /nodes, /settings, /xray, /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers are untouched * feat(frontend): migrate useNodes to TanStack Query Splits the hand-rolled useNodes hook into useNodesQuery (server data + NodeRecord type + derived totals) and useNodeMutations (add/update/del/ setEnable/probe/test). Mutations invalidate ['nodes'] on success, so the list refreshes without each call awaiting a manual refresh(). NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the WebSocket → query bridge now forwards the 'nodes' push to setQueryData(['nodes', 'list']) once at the SPA root. InboundsPage and the inbound form/list components import NodeRecord from its new home next to the query hook. * feat(frontend): migrate useAllSetting to TanStack Query Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings backed by useQuery + useMutation. The draft (current edits) is kept in local state and reset whenever query.data lands. saveAll posts the draft via a mutation; on success, invalidating ['settings'] refetches and the useEffect resets the draft so saveDisabled flips back to true. staleTime: Infinity prevents refetchOnWindowFocus from clobbering in-flight edits — settings only change in response to this user's own save. setSpinning stays as a pass-through to a local flag so the existing restartPanel flow in SettingsPage keeps showing its spinner. * feat(frontend): route useInbounds fetches through TanStack Query Rewrites useInbounds so its four server fetches (slim list, default settings, online clients, last-online map) live in useQuery with staleTime: Infinity. The in-place WS merge logic for traffic and client_stats is preserved — applyTrafficEvent / applyClientStatsEvent still mutate the locally-mirrored dbInbounds so the panel doesn't refetch every 1-2 seconds when stats stream in. refresh() becomes a thin invalidateQueries on the three list keys, which mutations in the page already call after add/edit/del. The bridge now forwards the WebSocket 'inbounds' push to setQueryData(['inbounds', 'slim']), and InboundsPage drops its useEffect(fetchDefaultSettings → refresh) plus the invalidate / inbounds wiring on useWebSocket — both are owned by the bridge now. * feat(frontend): migrate useClients to TanStack Query Replaces 12 hand-rolled mutation callbacks and a tangle of useState + useRef + useEffect with one useQuery (paged list) + nine useMutation wrappers. The list query uses keepPreviousData so paging/filter changes don't blank the table mid-fetch. The setQuery shallow-compare logic is preserved for backward compatibility with ClientsPage's effect that rebuilds the params on every render. Internally setQuery only updates state when the params actually differ — Query's queryKey equality handles the rest. WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the query cache via setQueryData(['clients', 'list', currentParams]) so per-second stats updates skip a full refetch. applyInvalidate is gone from the hook — the bridge owns coarse 'clients' invalidation. ClientsPage drops the invalidate handler from its useWebSocket subscription; auxiliary queries (inboundOptions, defaults, onlines) load via TanStack Query and are shared with useInbounds via the same query keys. * feat(frontend): route useXraySetting fetches through TanStack Query Keeps the bidirectional xraySetting ↔ templateSettings editor sync and the 1s dirty-tracking interval intact (those are local editor state, not server data). All seven server calls move: - config + traffic → useQuery on ['xray', 'config'] and ['xray', 'outboundsTraffic'] - saveAll → useMutation that invalidates the config query - resetOutboundsTraffic → useMutation that invalidates the traffic query - restartXray → useMutation (fires the restart, then reads the result string) - resetToDefault → useMutation (fetch default config, push it into the editor via setTemplateSettings) The WebSocket 'outbounds' event already lands in keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and the hook no longer exposes applyOutboundsEvent. A useEffect seeds xraySetting / templateSettings / tags / test URL from query data on first fetch and on every refetch, mirroring what the original fetchAll() did. * fix(frontend): restore per-route document titles in the SPA When the multi-entry MPA collapsed into a single index.html, every route inherited the static <title>3X-UI</title> from the shared shell, so every panel page showed "hostname - 3X-UI" instead of the original "hostname - Overview / Clients / Inbounds / ...". usePageTitle reads the current pathname and rewrites document.title on every navigation, matching the titles the deleted *.html files used to carry. Mounted in PanelLayout so it covers all panel routes without each page having to opt in. The startup applyDocumentTitle() call in main.tsx is gone — the hook sets the full "hostname - PageTitle" string itself. * feat(api-docs): expose OpenAPI spec + render Swagger UI in panel Replaces the hand-rolled API docs UI with industry-standard tooling so external integrations (Postman, Insomnia, openapi-generator) can consume the panel API without parsing endpoints.js by hand. Generator - frontend/scripts/build-openapi.mjs: walks the existing endpoints.js (still the single source of truth) and emits an OpenAPI 3.0.3 spec at frontend/public/openapi.json. Handles Gin :param → {param} path translation, body / query / path parameter splits, 200 + error response examples, and Bearer + cookie security schemes - npm run build now runs gen:api before vite build, so the spec is always in sync with what's documented Backend - web/controller/dist.go exposes ServeOpenAPISpec which streams the embedded dist/openapi.json with a short Cache-Control. Public endpoint (no auth) so Postman can fetch it without first logging in - web/web.go wires GET /panel/api/openapi.json before the auth-gated /panel/api router Panel - ApiDocsPage now renders swagger-ui-react fed by the basePath-aware openapi.json URL. Dark mode is overridden via CSS targeting the Swagger UI internals - CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui vendor chunk (134 KB gzipped) only loads on this lazy route, not on every panel page - vite.config: vendor-swagger manualChunk keeps the new dep out of the main vendor bundle For Postman: import http://<panel>/panel/api/openapi.json. Everything from /login + /panel/api/* shows up with auth, params, and examples. * style(api-docs): dark/ultra theme for Swagger UI Override every visual surface Swagger does not theme on its own: opblocks, tables, model boxes, form inputs, code blocks, modals, Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces Swagger's default light-arrow chevron on selects with a light-fill SVG positioned at the corner so the dark background-color is visible. Also disables deepLinking to silence the noisy v4 underscore warning; not used in our panel.
2026-05-24 12:34:52 -07:00
fix(api-docs): generate request bodies for all encodings (#6296) * fix(api-docs): generate request bodies for all encodings The OpenAPI generator only recognized generic body parameters, so JSON, form, and multipart declarations disappeared into empty application/json objects. Generate the declared media type and schema, preserve optionality and conditional requirements, and encode repeated form arrays the way Gin expects. Correct the request metadata exposed by the complete schemas and keep the panel and docs specifications synchronized. * fix(api-docs): align alternative request schemas Keep non-empty constraints on the selected request-body alternative without rejecting empty values for the alternatives that panel requests also include. Allow null client IP lists because model serialization emits them while cleared rows await pruning. * fix(api-docs): send object urlencoded fields as JSON, document the inbound update body Four defects the request-body rework exposed or left behind: - An object-typed field in an x-www-form-urlencoded body got no encoding entry, so OpenAPI 3.0 serialized it form-style. Swagger "Try it out" and generated clients sent memberWeights=3&memberWeights=0.2 to /panel/api/sub-balancers, and parseSubBalancerForm json.Unmarshals the raw field, so every such call failed with "invalid memberWeights". Emit encoding.<name>.contentType = application/json instead. - bodyRequiredOneOf names were never checked against the declared body params: a typo emitted an anyOf branch requiring a property that does not exist — unsatisfiable — and make gen still passed. Throw now, and extend the requestSchema guard to reject bodyRequiredOneOf as well. - /panel/api/inbounds/update/:id advertised no request body although its own summary says the shape mirrors /add and updateInbound binds one. Both entries now share an inboundBody const so they cannot drift. - The mixed-locations error was the only buildOperation throw without the method and path, aborting make gen without naming the offender. Regenerated frontend/public/openapi.json and copied it to docs/public/openapi.json. No MDX regeneration: no summary changed. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-03 12:20:38 -07:00
const pathCount = Object.keys(spec.paths).length;
let opCount = 0;
for (const ops of Object.values(spec.paths)) opCount += Object.keys(ops).length;
console.log(`[openapi] wrote ${outPath}`);
console.log(`[openapi] paths: ${pathCount}, operations: ${opCount}, tags: ${spec.tags.length}`);
}