Harbor application state v1

GET /api/state is the canonical Harbor domain snapshot. Successful mutations return the same snapshot as state. The persisted owner is state.json schema v8; React keeps only drafts, disclosure, focus, animation and transport freshness.

An abbreviated snapshot:

{
  "apiVersion": 1,
  "revision": 42,
  "mode": "client",
  "profiles": [
    {
      "id": "profile_primary",
      "label": "Личный",
      "subscription": {
        "status": "ready",
        "host": "provider.example/…",
        "fetchedAt": "2026-08-11T12:00:00.000Z",
        "userInfo": {},
        "lastRefreshAttemptAt": null,
        "errorCode": null
      },
      "desiredServerId": "srv_amsterdam",
      "servers": [
        {
          "id": "srv_amsterdam",
          "label": "Amsterdam",
          "host": "nl.example.net",
          "port": 443,
          "protocol": "vless"
        }
      ]
    }
  ],
  "selection": {
    "desiredProfileId": "profile_primary",
    "desiredServerId": "srv_amsterdam",
    "appliedProfileId": "profile_primary",
    "appliedServerId": "srv_amsterdam",
    "appliedServerSnapshot": {
      "id": "srv_amsterdam",
      "label": "Amsterdam",
      "host": "nl.example.net",
      "port": 443,
      "protocol": "vless"
    }
  },
  "operation": {
    "kind": null,
    "status": "idle",
    "startedAt": null,
    "error": null,
    "profileId": null,
    "serverId": null
  }
}

Every profile owns one private provider URL/config, public metadata, server list and desired server. The URL/config never enters the public snapshot. subscription and top-level servers remain a one-release projection of the desired profile for older clients; they are not a second owner.

Revision rules

revision increases for every visible domain transition, including operation start, completion and failure. Commands carry expectedRevision; stale commands fail with STATE_CONFLICT. Duplicate profile labels are rejected by preflight without a provider request or revision change.

The frontend accepts only newer snapshots. Equal revisions preserve object identity, and older polling responses cannot overwrite mutation results. After a failed mutation the browser immediately synchronizes the authoritative snapshot before allowing another command or retry.

Browser boot/offline/stale state remains a transport envelope beside the domain snapshot. A transport failure retains the last accepted domain state.

Failover health and traffic observations are transient: they do not write state.json or increase the domain revision every few seconds. Each control-process lifetime publishes a new observationEpoch and increasing observationSequence. At the same domain revision the browser accepts only a newer sequence from the active epoch; after accepting a new epoch it retires the old one so a late response cannot restore stale health.

Desired and applied identity

desiredProfileId and each profile's desiredServerId record the next local choice. appliedProfileId, appliedServerId and appliedServerSnapshot describe the runtime that actually owns traffic. There is no third activeProfileId.

While stopped, selecting or activating a profile only updates desired state. While running, changing the applied profile/server builds a candidate config, starts it, then publishes desired and applied identity in one final state commit. Until that commit the old applied pair remains authoritative. A failure restores the previous config, runtime and state.

If refresh removes the applied server, the running process is not silently switched. The provider list and desired selection are cleared as needed, while appliedServerSnapshot retains the last applied label until explicit stop or a successful switch. Stop clears applied identity and keeps the desired pair.

Profile operations

The canonical API is scoped by profile:

POST /api/profiles adds a profile after one explicit provider fetch;
PATCH /api/profiles/:id renames it locally;
PUT /api/profiles/:id/server selects one of its servers;
POST /api/profiles/:id/activate activates/switches it;
POST /api/profiles/:id/refresh refreshes only that provider;
DELETE /api/profiles/:id deletes it, with explicit stop-and-delete for a running applied profile;
POST /api/profiles/:id/servers/ping performs bounded transient health checks.

Provider failure retains the last successful list and metadata, marks only the target profile stale and records the last successful timestamp. Refreshing, pinging or deleting an inactive profile does not mutate the applied config/runtime. Background refresh iterates profiles independently every 15 minutes.

Ordered routing rules

route.localRules is the desired ordered list. Every rule has an explicit outbound: "vpn" | "direct"; the first enabled matcher wins and disabled rules retain their position without entering the generated config. route.activeLocalRules is the exact canonical list used to generate the running rules-enabled config, not a second desired owner.

The route-rules mutation uses the whole-array PUT /api/route-rules/v2 with rulesContractVersion: 2 and expectedRulesRevision. Contract v2 requires an explicit outbound on every rule. The versioned path prevents a stale v2 tab from writing to a rolled-back v1 backend; the legacy path on a v2 backend rejects its payload without changing state, config or runtime. A client that receives a snapshot without capability version 2 can read legacy rules as direct but keeps the editor read-only.

In Connect gateway-direct, local user rules are intentionally omitted and the snapshot reports no active or pending local rules. Gateway device policy Напрямую bypasses sing-box before these rules; policy VPN and an ordinary local/Gateway VPN pipeline evaluate them.

Gateway failover and activity journal

failoverPolicy is the desired Gateway-only policy: master enable, primary/reserve profile and server, service checks with individual timeouts, health windows, active-traffic guard and flap protection. failoverRuntimeState stores switch history, hold and quarantine deadlines separately, so a runtime decision is not mistaken for a desired configuration change. appliedFailoverPolicy stores only the two loaded targets and safe configuration fingerprints.

Enabling failover while VPN is stopped validates a temporary dual-channel candidate but does not start VPN. The dual config is loaded only by the next explicit power-on. Enabling it over a running single-channel config remains pending until a later stop and power-on. Disabling automation stops its timer, probes and activity collector immediately, but does not restart sing-box or change the selected route; the already loaded dual config is reported as passive-loaded until the ordinary stop lifecycle clears it.

The dual config keeps one stable inbound and a sing-box selector with interrupt_exist_connections: false. A switch changes the outbound for new connections only. Before an automatic switch, the existing /connections observer measures VPN byte deltas over a bounded 10-second window. Active or unknown traffic blocks the switch; the public snapshot contains only aggregate speed, connection count and at most three safe device/service labels.

Failover mutations use PUT /api/failover, POST /api/failover/pause and POST /api/failover/switch. Important user events are stored separately in activity-journal.json and read through GET /api/activity-journal. The journal is not a second state owner, contains no provider URLs or raw diagnostics, uses stable ID cursors and prunes entries after 30 days.

Compatibility and migration

Schema v5 migrates the legacy singleton and subscription-cache.json into one profile named Основной. Stable endpoint identity preserves unambiguous desired/applied selection, including transport variants whose normalized IDs differ from old labels. An explicitly stopped legacy state does not resurrect an old applied target.

Schema v6 adds the routing-rule outbound. Rules read from schemas v0-v5 migrate to outbound: "direct" in their existing order and both desired/applied arrays are normalized together. A schema-v6 rule without a valid outbound is rejected rather than silently rewritten. Schema v7 adds canonical connectivity-diagnostics settings. Schema v8 adds a disabled failover policy, empty runtime history and no applied dual config, so upgrading does not start monitoring or change traffic.

Migration atomically backs up the previous state.json. After the embedded profile is committed, Harbor also backs up and removes the legacy subscription cache so there is one persisted owner. Invalid legacy cache/config returns to a truthful stopped first-run state instead of starting stale generated config.

The old HTTP projection remains bounded for one release. Schema v8 persistence is not downgrade-compatible: stop Harbor and restore the state.json.backup-v<fromVersion>-* matching the rollback binary instead of deploying old code over v8 data. Rolling back before profiles still also requires the matching legacy subscription-cache backup.

9.0 KiB Raw Blame History