86 lines
6.1 KiB
Markdown
86 lines
6.1 KiB
Markdown
# Harbor application state v1
|
|
|
|
`GET /api/state` is the canonical Harbor domain snapshot. Successful POST and DELETE endpoints return the same snapshot as `state` while retaining their v0 response fields for compatibility.
|
|
|
|
```json
|
|
{
|
|
"apiVersion": 1,
|
|
"revision": 42,
|
|
"generatedAt": "2026-07-11T15:00:00.000Z",
|
|
"mode": "client",
|
|
"subscription": {
|
|
"status": "ready",
|
|
"host": "provider.example/…",
|
|
"fetchedAt": "2026-07-11T14:58:00.000Z",
|
|
"userInfo": {}
|
|
},
|
|
"selection": {
|
|
"desiredServerId": "srv_4d7c5d1bcd60d665",
|
|
"appliedServerId": "srv_4d7c5d1bcd60d665"
|
|
},
|
|
"connection": {
|
|
"desired": "running",
|
|
"process": "running",
|
|
"startedAt": "2026-07-11T14:59:10.000Z",
|
|
"lastError": null
|
|
},
|
|
"route": {
|
|
"mode": "local-vpn",
|
|
"gatewayAddress": null,
|
|
"lastVerifiedAt": null,
|
|
"reason": "auto"
|
|
},
|
|
"operation": {
|
|
"kind": null,
|
|
"status": "idle",
|
|
"startedAt": null,
|
|
"error": null
|
|
},
|
|
"servers": [
|
|
{
|
|
"id": "srv_4d7c5d1bcd60d665",
|
|
"label": "Amsterdam",
|
|
"host": "nl.example.net",
|
|
"port": 443,
|
|
"protocol": "vless"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
The backend owns subscription metadata, servers, desired/applied selection, desired/process connection state, route and current operation. React may keep only unsaved form values, pending selection and visual state. Browser transport freshness is not part of this contract.
|
|
|
|
## Revision rules
|
|
|
|
`revision` is persisted in the existing `state.json` and increases on externally visible transitions, including operation start/completion/failure, import, refresh, forget, apply, start, stop and Gateway Auto changes. `generatedAt` is response metadata and does not change revision by itself.
|
|
|
|
A consumer must eventually apply only snapshots whose revision is at least its current revision. The frontend comparison and stale/offline transport envelope are intentionally handled by TASK-002 and TASK-003.
|
|
|
|
The frontend keeps the accepted snapshot in one reducer and replaces it only when `incoming.revision` is greater. Equal revisions preserve object identity so background polling does not replay decorative transitions. Mutation responses are applied directly; polling requests started before a mutation are logically invalidated and cannot overwrite its result. A locally pending server choice remains local until a newer snapshot acknowledges it or removes that server.
|
|
|
|
Browser transport state lives beside, not inside, the domain snapshot. It records boot status, last successful sync time and consecutive failures. Three failed polls mark the retained snapshot stale; the next successful GET or mutation clears that marker. An initial failure shows `control-unreachable`, `incompatible-api` or `fatal` without inventing domain state.
|
|
|
|
Gateway discovery follows the same retain-and-mark-stale rule. Once a concrete default Gateway has been verified, transient presence failures or a briefly stale macOS route snapshot keep `gateway-direct` active and report `route.reason = gateway-stale`; they do not restart sing-box into `local-vpn`. Local routing resumes only after the user disables Gateway mode or macOS reports a different default Gateway identity.
|
|
|
|
## Desired and applied state
|
|
|
|
`selection.desiredServerId` records the user's requested server. `selection.appliedServerId` changes only after its sing-box configuration has been applied. Likewise, `connection.desired` records intent while `connection.process` reports the observed runtime. A failed operation can therefore leave desired and applied values different without pretending that the request succeeded.
|
|
|
|
Server IDs are deterministic from normalized protocol, host and port, while provider order and the human-readable `label` are separate. Duplicate labels remain separate servers; reorder and cosmetic rename keep the same ID. Ping results, React keys, persisted selection and apply commands use the ID. If the selected endpoint disappears, Harbor stops the active process, clears selection and requires an explicit new choice instead of silently switching traffic.
|
|
|
|
## Subscription import and refresh
|
|
|
|
The browser validates only the shape and `http`/`https` protocol of a subscription URL. The provider is contacted once, after explicit submit. The backend fetches and parses the complete response before entering the serialized commit.
|
|
|
|
Import and refresh share one commit path. It prepares the candidate server list and sing-box config first, then updates cache, config, runtime and canonical state. If provider fetch, parsing, config validation or runtime apply fails, the previous subscription cache, selected server, config and running process remain active. Refreshes for the saved URL share one in-flight Promise; a refresh that finishes after another import is rejected with `STATE_CONFLICT` instead of overwriting the newer subscription.
|
|
|
|
The existing background refresh remains every 15 minutes. Provider requests time out after 15 seconds by default (`SUBSCRIPTION_TIMEOUT_MS` may override it). A failed background refresh logs a redacted warning and keeps the last successful subscription snapshot.
|
|
|
|
## Compatibility and migration
|
|
|
|
No path, volume or file is renamed. A legacy `state.json` without stable IDs is migrated to schema v4. A unique `selectedTag` is matched to its normalized endpoint and stored as `selectedServerId`/`appliedServerId`; an ambiguous or missing tag explicitly clears selection. The raw provider config remains unchanged in subscription cache and is normalized only in memory, so an older Harbor build can still use its original tags after rollback. Existing unknown fields remain untouched.
|
|
|
|
During the v0 compatibility window, the snapshot also exposes `selectedTag`, `singboxRunning`, `servers[].tag`, `gatewayAuto` and the other previous GET fields. Mutation responses retain their previous result fields and add `state`. The canonical `subscription` object never contains the full subscription URL.
|
|
|
|
Rollback is code-only: deploy the previous build. The v4 state keeps `selectedTag`, `appliedTag` and server aliases for older builds, while subscription cache keeps raw provider tags. The added ID fields are ignored by the previous implementation.
|