286 lines
17 KiB
Markdown
286 lines
17 KiB
Markdown
# Windows Local Sing-Box Implementation Plan
|
|
|
|
**Intent:** Add an optional Windows-client Local sing-box block that mirrors the ProxiFyre block, installs and controls a real sing-box service, imports a subscription/link, lets the user pick and ping servers, and routes selected apps through the chosen local outbound.
|
|
**Current Behavior:** The Windows client supports an existing external SOCKS5 proxy and a ProxiFyre component block with setup details, install/start/stop/uninstall actions, animation, and generated config apply. `singbox` exists as an optional component in the model, but `install-singbox.ps1` is only a marker boundary, `main.rs` does not register sing-box commands, the frontend has no sing-box block, and subscription parsing lives only in the Node server.
|
|
**Expected Outcome:** A Windows user can keep using the external proxy path unchanged, or explicitly install optional Local sing-box, paste a subscription/VLESS link, fetch servers, ping them, choose one, generate a checked sing-box config, start/stop the sing-box service, and apply ProxiFyre routing to `local-singbox`.
|
|
**Target-Perspective Output:** In the Windows client, the user sees a second optional block styled and animated like ProxiFyre. It shows what will be installed, asks for clear confirmation before privileged work, displays subscription/server state, exposes server ping and selection, and makes it obvious whether selected apps route to an existing proxy or to Local sing-box.
|
|
**Truth Owner:** Rust/Tauri backend owns sing-box source state, subscription parsing/cache, generated sing-box config, component detection, and service operations. React owns only transient UI state. Generated configs and service files are derived artifacts.
|
|
**Contract Boundary:** React calls typed Tauri commands. Rust validates and persists source JSON under `C:\ProgramData\VpnProxy`, generates configs through the sing-box adapter, and invokes explicit elevated PowerShell only for install/uninstall/service actions. UI never parses raw PowerShell/stdout.
|
|
**Cutover:** Replace the current marker-only sing-box installer path with a real optional Local sing-box component while preserving `ComponentId::Singbox` and `local-singbox` target semantics. Keep external proxy as the default usable route when sing-box is absent.
|
|
**Displaced Path:** Displace `apps/windows-client/scripts/install-singbox.ps1` marker behavior and the current direct-only `adapters/singbox.rs` output. Do not create a parallel Node/server subscription path for the Windows client.
|
|
**Value Density:** The smallest high-value slice is a controlled Local sing-box block that can fetch a subscription, select an outbound, generate checked local sing-box config, and expose service controls without making sing-box mandatory.
|
|
**Evidence Gate:** Evidence must include target-perspective UI proof plus generated config proof, not just tests. Privileged Windows service behavior must be manually verified or explicitly marked `implemented but unproven`.
|
|
**Acceptance Evidence:** Rust tests for parser/config/service-command boundaries; frontend build; app state or screenshot showing ProxiFyre and Local sing-box blocks; generated `sing-box-config.json` containing the selected outbound and local mixed inbound; generated ProxiFyre config pointing to `127.0.0.1:1080`; Windows service checklist when elevated actions are run.
|
|
**Evidence Lane:** Record commands, selected app state, generated config summaries, and manual Windows results in `docs/goals/windows-local-singbox/EVIDENCE.md`.
|
|
**Kill Criteria:** No mandatory sing-box for external proxy flow; no hidden install during profile apply; no duplicate subscription source of truth in React or Node server; no raw PowerShell text as app logic; no permanent marker-only sing-box install path.
|
|
**Architecture Slice:** Extend `apps/windows-client` only: Rust domain/storage/commands/adapters/detection/scripts plus React UI/types/CSS. Avoid root `src/server` and root `src/web` except as read-only reference.
|
|
**Plan Review Gate:** Requires PRE review before execution.
|
|
|
|
## Terminology
|
|
|
|
The user-facing feature name is `Local sing-box` / `sing-box`. Do not use alternate feature names in UI, commands, docs, or files.
|
|
|
|
## Architecture Slice
|
|
|
|
Files to create:
|
|
- `apps/windows-client/src-tauri/src/subscription.rs`
|
|
- `apps/windows-client/src-tauri/src/singbox_service.rs`
|
|
- `apps/windows-client/src-tauri/tests/subscription_tests.rs`
|
|
- `apps/windows-client/src-tauri/tests/singbox_service_tests.rs`
|
|
- `apps/windows-client/src-tauri/tests/singbox_command_tests.rs`
|
|
|
|
Files to modify:
|
|
- `apps/windows-client/src-tauri/Cargo.toml`
|
|
- `apps/windows-client/src-tauri/src/main.rs`
|
|
- `apps/windows-client/src-tauri/src/models.rs`
|
|
- `apps/windows-client/src-tauri/src/storage.rs`
|
|
- `apps/windows-client/src-tauri/src/commands.rs`
|
|
- `apps/windows-client/src-tauri/src/component_detection.rs`
|
|
- `apps/windows-client/src-tauri/src/adapters/singbox.rs`
|
|
- `apps/windows-client/src-tauri/tests/singbox_adapter_tests.rs`
|
|
- `apps/windows-client/src-tauri/tests/command_tests.rs`
|
|
- `apps/windows-client/src/domain/types.ts`
|
|
- `apps/windows-client/src/api/tauriCommands.ts`
|
|
- `apps/windows-client/src/app/App.tsx`
|
|
- `apps/windows-client/src/styles/app.css`
|
|
- `apps/windows-client/scripts/install-singbox.ps1`
|
|
- `apps/windows-client/README.md`
|
|
- `docs/goals/windows-local-singbox/EVIDENCE.md`
|
|
|
|
Files to avoid:
|
|
- `src/server/*` except as read-only reference for subscription semantics.
|
|
- `src/web/*`
|
|
- Docker, compose, gateway, and macOS installer files.
|
|
- Existing ProxiFyre behavior except where it must consume the `local-singbox` target.
|
|
|
|
Source of truth:
|
|
- `C:\ProgramData\VpnProxy\config\profiles.json`
|
|
- `C:\ProgramData\VpnProxy\config\targets.json`
|
|
- `C:\ProgramData\VpnProxy\config\local-singbox.json`
|
|
- `C:\ProgramData\VpnProxy\state\singbox-subscription-cache.json`
|
|
- `C:\ProgramData\VpnProxy\state\activity.json`
|
|
|
|
Derived artifacts:
|
|
- `C:\ProgramData\VpnProxy\generated\sing-box-config.json`
|
|
- `C:\ProgramData\VpnProxy\generated\proxifyre-app-config.json`
|
|
- Installed `sing-box.exe` and WinSW wrapper under `C:\Program Files\VpnProxy\sing-box`
|
|
- Windows service `VpnProxySingBox`
|
|
|
|
Read path:
|
|
- React calls `get_components`, `get_singbox_status`, `get_singbox_setup_status`, and subscription/server commands.
|
|
- Rust reads source Local sing-box config and cache, detects installed `sing-box`/service/wrapper, and returns redacted DTOs.
|
|
|
|
Write path:
|
|
- React sends typed mutations for subscription URL, selected server, local endpoint, and service actions.
|
|
- Rust validates input, writes source JSON atomically, fetches/cache subscription data, generates `sing-box-config.json`, and runs `sing-box check` before service start/restart.
|
|
|
|
Contract boundary:
|
|
- `subscription.rs` owns fetch/parse/link normalization.
|
|
- `adapters/singbox.rs` owns conversion from selected outbound to local runtime config.
|
|
- `singbox_service.rs` owns install/service script generation and structured command parsing.
|
|
- `commands.rs` owns Tauri DTOs and activity entries.
|
|
- `App.tsx` owns layout/state orchestration only.
|
|
|
|
Integration points:
|
|
- ProxiFyre route remains `selected apps -> ProxiFyre -> target`.
|
|
- Local sing-box route uses target `local-singbox`, `kind=local`, `protocol=socks5`, `host=127.0.0.1`, `port=1080`, `requiresComponent=singbox`.
|
|
- Server ping uses TCP connect to the selected outbound host/port, like the existing server ping semantics.
|
|
- Install flow downloads/installs `sing-box` plus a WinSW Windows service wrapper, then writes machine-readable result JSON.
|
|
|
|
Migration/cutover:
|
|
- On first sing-box save/start, ensure `local-singbox` target exists or is updated from Local sing-box listen settings.
|
|
- Do not switch the user's profile target automatically unless the user chooses Local sing-box.
|
|
- Existing external proxy input remains the default path and must still build/apply without sing-box.
|
|
|
|
Displaced path:
|
|
- `install-singbox.ps1` must stop being a marker-only script.
|
|
- The old direct-only sing-box config in `adapters/singbox.rs` must be replaced by selected-subscription-outbound config generation.
|
|
- No Windows-client code should import or call the root Node server for subscription parsing.
|
|
|
|
Acceptance evidence gate:
|
|
- Automated evidence proves parser/config/ping/service-command boundaries.
|
|
- App-visible evidence proves the optional block, setup details, server selection, and route mode.
|
|
- Generated config evidence proves selected server is used by sing-box and ProxiFyre points to the local endpoint.
|
|
|
|
## Task Board
|
|
|
|
### Task 1: Add Local Sing-Box Domain And Storage Contract
|
|
|
|
Allowed files:
|
|
- `apps/windows-client/src-tauri/src/models.rs`
|
|
- `apps/windows-client/src-tauri/src/storage.rs`
|
|
- `apps/windows-client/src/domain/types.ts`
|
|
- `apps/windows-client/src-tauri/tests/storage_tests.rs`
|
|
|
|
Expected output:
|
|
- `LocalSingBoxConfig` source model with subscription URL, redacted display URL, selected server tag, listen host/port, service name, install root, and timestamps.
|
|
- `SubscriptionCache` model with parsed config, server summaries, user info, and fetched timestamp.
|
|
- Storage paths for `config/local-singbox.json` and `state/singbox-subscription-cache.json`.
|
|
|
|
Verification:
|
|
- `cd apps/windows-client/src-tauri && cargo test storage`
|
|
|
|
Acceptance evidence:
|
|
- Tests prove atomic roundtrip, default optional empty state, redacted URL DTO, and invalid cache fallback.
|
|
|
|
Parallel safe: no.
|
|
|
|
### Task 2: Port Subscription Parsing And Fetching To Rust
|
|
|
|
Allowed files:
|
|
- `apps/windows-client/src-tauri/Cargo.toml`
|
|
- `apps/windows-client/src-tauri/src/subscription.rs`
|
|
- `apps/windows-client/src-tauri/tests/subscription_tests.rs`
|
|
|
|
Expected output:
|
|
- Parser supports sing-box JSON configs, base64 subscription bodies, and VLESS REALITY links with the same supported outbound types as `src/server/subscription.js`.
|
|
- Fetch command support is implemented in Rust with HTTP/HTTPS only and structured errors.
|
|
- Subscription URL is never echoed unredacted in diagnostics or normal status DTOs.
|
|
|
|
Verification:
|
|
- `cd apps/windows-client/src-tauri && cargo test subscription`
|
|
|
|
Acceptance evidence:
|
|
- Tests cover JSON config, base64 VLESS list, invalid URL, unsupported outbound, and redaction.
|
|
|
|
Parallel safe: yes after Task 1 model names are stable.
|
|
|
|
### Task 3: Replace Sing-Box Adapter With Selected-Outbound Config Generation
|
|
|
|
Allowed files:
|
|
- `apps/windows-client/src-tauri/src/adapters/singbox.rs`
|
|
- `apps/windows-client/src-tauri/tests/singbox_adapter_tests.rs`
|
|
|
|
Expected output:
|
|
- Adapter builds local mixed inbound on the configured listen host/port.
|
|
- Adapter selects the cached outbound by tag, clones it, ensures a stable outbound tag, and adds `direct`/`block`.
|
|
- Adapter runs `sing-box check` when a binary path is available.
|
|
|
|
Verification:
|
|
- `cd apps/windows-client/src-tauri && cargo test singbox_adapter`
|
|
|
|
Acceptance evidence:
|
|
- Tests show selected VLESS outbound appears in generated config, missing selected tag blocks generation, and external-target ProxiFyre flow remains independent from Local sing-box.
|
|
|
|
Parallel safe: yes after Task 1.
|
|
|
|
### Task 4: Implement Sing-Box Detection, Setup Status, And Service Scripts
|
|
|
|
Allowed files:
|
|
- `apps/windows-client/src-tauri/src/component_detection.rs`
|
|
- `apps/windows-client/src-tauri/src/singbox_service.rs`
|
|
- `apps/windows-client/scripts/install-singbox.ps1`
|
|
- `apps/windows-client/src-tauri/tests/component_detection_tests.rs`
|
|
- `apps/windows-client/src-tauri/tests/singbox_service_tests.rs`
|
|
|
|
Expected output:
|
|
- Detection finds installed `sing-box.exe`, service `VpnProxySingBox`, service running state, version/path, and problems.
|
|
- Setup status lists exactly what will be installed: sing-box binary, WinSW service wrapper, service name, install root, generated config/log paths.
|
|
- Install script performs a real idempotent install/repair boundary using WinSW and returns structured JSON; uninstall is safe-scoped to the configured install root.
|
|
|
|
Verification:
|
|
- `cd apps/windows-client/src-tauri && cargo test component_detection singbox_service`
|
|
- Windows parser check for `install-singbox.ps1` when running on Windows.
|
|
|
|
Acceptance evidence:
|
|
- Tests prove missing/installed/running component merge and PowerShell result parsing. Manual service install/start evidence is recorded later.
|
|
|
|
Parallel safe: yes, but integrate with Task 6 before UI.
|
|
|
|
### Task 5: Add Tauri Sing-Box Commands
|
|
|
|
Allowed files:
|
|
- `apps/windows-client/src-tauri/src/commands.rs`
|
|
- `apps/windows-client/src-tauri/src/main.rs`
|
|
- `apps/windows-client/src/api/tauriCommands.ts`
|
|
- `apps/windows-client/src-tauri/tests/command_tests.rs`
|
|
- `apps/windows-client/src-tauri/tests/singbox_command_tests.rs`
|
|
|
|
Expected output:
|
|
- Commands: `get_singbox_status`, `get_singbox_setup_status`, `save_singbox_subscription`, `fetch_singbox_subscription`, `forget_singbox_subscription`, `select_singbox_server`, `ping_singbox_server`, `ping_all_singbox_servers`, `generate_singbox_config`, `start_singbox_service`, `stop_singbox_service`, `install_singbox`, `uninstall_singbox`.
|
|
- Commands update activity with structured entries.
|
|
- `generate_singbox_config` ensures/updates the `local-singbox` target but does not change profile targets without user choice.
|
|
- `start_singbox_service` regenerates and checks config from current source state before starting the service.
|
|
|
|
Verification:
|
|
- `cd apps/windows-client/src-tauri && cargo test command singbox_command`
|
|
|
|
Acceptance evidence:
|
|
- Tests prove fetch/cache/select/generate flow and ProxiFyre apply blocks only when a profile actually targets missing/stopped Local sing-box.
|
|
|
|
Parallel safe: no; depends on Tasks 1-4.
|
|
|
|
### Task 6: Build The Optional Local Sing-Box UI Block
|
|
|
|
Allowed files:
|
|
- `apps/windows-client/src/app/App.tsx`
|
|
- `apps/windows-client/src/domain/types.ts`
|
|
- `apps/windows-client/src/api/tauriCommands.ts`
|
|
- `apps/windows-client/src/styles/app.css`
|
|
|
|
Expected output:
|
|
- A second block appears beside/under ProxiFyre, visually matching `finder-card`, setup details, action menu, status light, and border animation behavior.
|
|
- UI shows Local sing-box as optional, not an error, when missing.
|
|
- User can paste subscription/link, fetch servers, select server, ping one/all, generate config, install/start/stop/uninstall Local sing-box, and choose whether the main profile uses existing proxy or Local sing-box.
|
|
- Loading/error/success states are visible and controlled by user action.
|
|
|
|
Verification:
|
|
- `cd apps/windows-client && npm run build`
|
|
|
|
Acceptance evidence:
|
|
- Screenshot or app state shows ProxiFyre block and Local sing-box block, expanded setup details, fetched server list with ping state, and route target toggle.
|
|
|
|
Parallel safe: no; depends on Task 5 DTOs.
|
|
|
|
### Task 7: Integrate Route Choice And ProxiFyre Apply
|
|
|
|
Allowed files:
|
|
- `apps/windows-client/src/app/App.tsx`
|
|
- `apps/windows-client/src-tauri/src/commands.rs`
|
|
- `apps/windows-client/src-tauri/src/adapters/proxifyre.rs`
|
|
- `apps/windows-client/src-tauri/tests/command_tests.rs`
|
|
- `apps/windows-client/src-tauri/tests/proxifyre_adapter_tests.rs`
|
|
|
|
Expected output:
|
|
- Main profile can target either external proxy or `local-singbox`.
|
|
- Switching to Local sing-box writes `targetId=local-singbox`; switching back writes external target.
|
|
- ProxiFyre generated config points to `127.0.0.1:1080` when Local sing-box is selected and still points to the entered external proxy otherwise.
|
|
|
|
Verification:
|
|
- `cd apps/windows-client/src-tauri && cargo test proxifyre_adapter command`
|
|
- `cd apps/windows-client && npm run build`
|
|
|
|
Acceptance evidence:
|
|
- Generated ProxiFyre config samples for both external proxy and Local sing-box routes are recorded.
|
|
|
|
Parallel safe: no.
|
|
|
|
### Task 8: Documentation, Evidence, And Windows Manual Gate
|
|
|
|
Allowed files:
|
|
- `apps/windows-client/README.md`
|
|
- `docs/goals/windows-local-singbox/EVIDENCE.md`
|
|
- `docs/goals/windows-modular-client/EVIDENCE.md`
|
|
|
|
Expected output:
|
|
- README explains separate ProxiFyre and Local sing-box install flows, data paths, service name, and rollback.
|
|
- Evidence file records tests/builds/UI proof/generated configs/manual Windows service checks.
|
|
- If elevated service install cannot be run in the current environment, record `implemented but unproven` for that lane with exact remaining manual steps.
|
|
|
|
Verification:
|
|
- `git status --short`
|
|
- Evidence commands listed in `EVIDENCE.md`.
|
|
|
|
Acceptance evidence:
|
|
- A target-perspective checklist proves the external proxy path still works and Local sing-box path works or is explicitly unproven only at the privileged Windows service lane.
|
|
|
|
Parallel safe: no.
|
|
|
|
## PRE Review Prompt
|
|
|
|
Use `C:\Users\PC\.agents\skills\krypton-planning\plan-reviewer-prompt.md` with:
|
|
|
|
- Plan file: `docs/goals/windows-local-singbox/PLAN.md`
|
|
- Original request: add an optional Windows-client Local sing-box block like ProxiFyre, with install/service management, connection link/subscription import, server selection, ping, animations, and user-controlled visibility of what will be installed.
|
|
- Unsafe paths or layers: root `src/server`, root `src/web`, hidden installer calls inside apply, raw PowerShell parsing in React, duplicate subscription state.
|