StartRestoreRun

StartRestoreRun

Description: Starts a restore flow from a validated backup run.

The current implementation validates the source backup first, then calls restore callbacks registered by backup participants. The source backup must have status completed. If a future participant does not implement restore yet, the run fails with restore callback is not registered.

Access Control

SESSION_ADMIN, SESSION_MANAGER

Request Parameters

Field	Type	Required	Description
run_id	string	Yes	Source backup run identifier
dry_run	bool	No	Validate and execute participant restore callbacks in dry-run mode when supported
participants	array	No	Optional participant names for module-scoped restore, for example ["staff"]
force	bool	No	Bypass maintenance/update mode guard for an actual restore

Request Example

{
  "command": "StartRestoreRun",
  "extID": "1",
  "data": {
    "run_id": "20260629-121045-000001",
    "dry_run": true,
    "participants": ["staff"],
    "force": false
  }
}

Response fields

The successful response data object contains every field below. The TCP transport wraps this data in its normal command response envelope.

Field	Type	Meaning
restore_id, source_run_id	string	Restore identifier and source backup identifier
dry_run, force	boolean	Effective request flags; both default to false
pre_restore_path	string	Directory reserved for the safety snapshot (also returned for a dry run)
status	string	running, completed, failed, partial, cancelled, or timeout; actual restore is successful only after runtime synchronization
started_at, finished_at	integer	Unix timestamps in seconds
error_summary	string	Failure details, empty on success
participants	array	Per-participant results described below

Each participant contains name (string), critical and ok (boolean), status (completed or failed), started_at and finished_at (Unix seconds), error (string), safety_snapshot_path (string), artifacts and safety_artifacts (arrays). Each artifact contains logical_name and path (string), size_bytes (integer), sha256 (string), integrity_ok and validation_ok (boolean), integrity_error and validation_error (string).

Response Example

{
  "restore_id": "20260629-122000-000002",
  "source_run_id": "20260629-121045-000001",
  "dry_run": true,
  "force": false,
  "pre_restore_path": "backups/pre-restore/20260629-122000-000002",
  "status": "completed",
  "started_at": 1782728400,
  "finished_at": 1782728401,
  "error_summary": "",
  "participants": [
    {
      "name": "staff",
      "critical": true,
      "ok": true,
      "status": "completed",
      "started_at": 1782728400,
      "finished_at": 1782728401,
      "error": "",
      "safety_snapshot_path": "",
      "artifacts": [
        {
          "logical_name": "staff.db",
          "path": "backups/completed/20260629-121045-000001/staff.db",
          "size_bytes": 327680,
          "sha256": "f2a1...",
          "integrity_ok": true,
          "integrity_error": "",
          "validation_ok": true,
          "validation_error": ""
        }
      ],
      "safety_artifacts": []
    }
  ]
}

Notes

• Only one backup or restore operation can run at a time.
• Restore must be implemented by each participant module. BackupManager must not directly replace module storage.
• If participants is omitted, the server attempts a full restore for all registered participants.
• Selected participants are restored in dependency order, not request order: symbols, groups, staff, accounts, customers, trades.
• The source backup must have status completed; partial, failed, running, cancelled, and timeout runs are not restorable.
• dry_run is allowed in any server mode.
• Actual restore requires maintenance/update mode (liveupdate_mode != 0) unless force is set to true.
• Before actual restore, the server creates a validated safety snapshot in backups/pre-restore/<restore_id>.
• If a selected critical participant fails safety snapshot creation, restore does not start.
• force should be used only for controlled maintenance operations.
• This command returns HTTP 409 when restore is blocked by the safety guard, validation fails, or a participant fails.

Runtime synchronization and admission

An actual restore closes mutating HTTP/TCP/FIX router admission and Core trading/account/group/symbol/quote admission, waits for admitted writers, and parks both calculation and pending-order loops between complete cycles. It drains the account/trade runtime queues before taking safety snapshots. If an in-flight trade request remains, restore fails before replacing data; wait for execution to finish before retrying. Read-only requests remain available but may observe intermediate state until restore completes.

Enabled routing (routing.execution_enabled=true) alone does not prevent restore. Internal execution routes can restore without disabling routing. Gateway dispatch and background dealer timeout execution participate in admission: already admitted operations retain their lease through gateway reply processing and Core application. Reply delivery itself remains available while the barrier drains; replies with unknown or expired correlations cannot apply trades.

After admission drains, restore refuses replacement if a gateway execution is still pending, its remote outcome is uncertain, or a dealer request is pending, claimed or executing. Complete dealer requests and retry. A timed-out, disconnected, malformed or otherwise indeterminate result after attempted gateway dispatch latches uncertainty for the server process lifetime, even if the gateway is restarted or deleted. Reconcile provider state before a controlled server restart and any restore; restarting alone does not reconcile external trades. This guard is in memory, not a persistent reconciliation ledger. Local restore does not roll back provider positions: when restoring accounts with external execution history, the operator must reconcile the selected snapshot with provider state.

force=true bypasses only the maintenance-mode guard, not runtime safety checks. Dry runs do not activate the barrier. A gateway safety rejection returns status 409 with this complete response data object:

{
  "error": "RESTORE_RUN_FAILED",
  "message": "gateway execution pending or outcome uncertain; reconcile external execution before restore"
}

After restoring storage, the server rebuilds ledger totals from TradeManager's loaded records, reloads calculation snapshots and pending indexes, and performs a valuation-only cycle using the normal finance rules. SL/TP, StopOut and rollover are not executed in this first cycle. Both loops must acknowledge the new runtime generation; queued account-margin application must finish and the applied values must match the calculated snapshots. Only then may status=completed be returned. Clients do not need to send a tick, poll for financial convergence or restart the server to finish a successful restore.

The pause and reload acknowledgement waits are each bounded to 30 seconds; account/trade queue-drain waits are also bounded to 30 seconds each. This is not a 30-second bound on the entire operation, including participant storage I/O. A failure before participant replacement reopens admission. A failure after replacement, including partial participant failure or missing runtime acknowledgement, leaves trading blocked; inspect the restore manifest and safety snapshot and resolve the inconsistent restore before restarting. Automatic rollback/resume is not performed.

Blocked mutating router requests return status 503 with this complete response data object:

{"error":"RESTORE_IN_PROGRESS"}

The same error is used while admission remains blocked after a failed restore. Direct Core mutation callers receive RET_TECH_PROBLEM. A restore safety/runtime failure returns status 409, for example:

{
  "error": "RESTORE_RUN_FAILED",
  "message": "restored runtime valuation was not confirmed; trading remains blocked; inspect safety snapshot and restart only after resolving restore failure"
}

Server/stcore deployment contract

This implementation requires matching STCORE_ABI_VERSION=8 and CORE_API_ABI_VERSION=8; rebuild and deploy server and stcore together. The host interface adds restoreCheckpoint() -> uint64_t (0: ordinary cycle; nonzero: restore generation requiring complete snapshot reload and valuation) and restoreApplied(uint64_t generation, bool ok) -> void (acknowledgement after host application; false fails the barrier). The pending-order loop participates in the same host-side barrier. There are no new client request fields or successful-response fields.