Backups info

Backups¶

Backup commands expose control over configured backup endpoints and over local backup runs created by the server, including full runs and scoped participant runs.

The current full backup implementation is participant-based: BackupManager coordinates the run, while each module that owns data registers its own backup callback and produces its own artifacts. This keeps module storage behind module boundaries and lets each module flush pending runtime state before the dump is created.

Commands¶

Current Backup Coverage¶

The current full backup run includes these critical participants:

Participant	Artifact	Source module	Notes
`accounts`	`accounts.snapshot`	Account manager	Flushes account runtime state before backup
`symbols`	`symbols.snapshot`	Symbol manager	Flushes symbol state before backup
`staff`	`staff.snapshot`	Staff manager	Drains staff runtime state before backup
`trades`	`trades.snapshot`	Trade manager	Drains trade runtime state before backup

If any current participant fails, the full backup run is marked as failed because all current participants are critical.

Run Status Values¶

Status	Description
`running`	Run has started and manifest is being updated
`completed`	All critical and optional participants completed successfully
`failed`	At least one critical participant failed, or the run could not be created/published
`partial`	Critical participants completed, but at least one optional participant failed
`cancelled`	Reserved for cancellation support
`timeout`	Reserved for timeout support

Trigger Values¶

Trigger	Description
`manual`	Started through TCP API
`cron`	Started by the configured backup schedule
`pre_update`	Reserved for pre-update service backup
`shutdown`	Reserved for shutdown backup

Storage Layout¶

During execution, a run is created under:

backups/.running/<run_id>/

After completion, the directory is moved to:

backups/completed/<run_id>/

Failed and incomplete runs are moved to:

backups/failed/<run_id>/

Each run directory contains manifest.json and module artifacts for the selected participants.

Runtime Progress¶

Long-running backup runs expose runtime progress through two public contracts:

GetBackupProgress returns the latest known backup progress snapshot.
TCP/WS stream channel backup.progress pushes the same model while the run is active.

The progress model is intended for UI progress bars and operational monitoring. It reports the active run, current phase, current participant, overall percent, per-participant state, and remote publish counters.

StartFullBackup is synchronous, so a client that starts the run receives the final command response only after the run has completed. Use another TCP/WS session for backup.progress subscription or GetBackupProgress polling. After a successful run, polling returns an idle state; the final success state is delivered through the stream event.

Scoped Backups¶

StartFullBackup can receive participants, for example ["trades"], to create a scoped run for selected module artifacts only. Scoped runs are marked with type: "scoped" and include requested_participants. Use them for module-level operational snapshots; use full completed runs for disaster recovery.

Remote Backup Endpoints¶

Backup endpoint configuration is managed through GetBackupConfig, AddBackupConfig, UpdateBackupConfig, and DeleteBackupConfig.

Enabled endpoints with host in host:port format receive validated backup artifacts after the local run is published. The endpoint password is used as the backup server token. Remote upload uses timeout, retry_attempts, and retry_delay; upload failures are logged but do not change the local backup run status.

Remote runs can be inspected with GetRemoteBackupRuns and removed from remote storage with DeleteRemoteBackupRun. To restore from a remote backup server, first import the selected run with ImportRemoteBackupRun; then validate and restore it through the standard local restore flow.

Local runs can be removed with DeleteBackupRun after they are no longer needed. Active runs cannot be deleted.

Not Implemented Yet¶

The current API does not yet implement:

retention policies and automatic deletion of old runs;
runtime cancellation for an active run;
fast backup/history snapshots for individual business objects.

Restore State¶

Restore has a public contract through ValidateBackupRun and StartRestoreRun. BackupManager validates source artifacts and calls module restore callbacks. Current critical participants (accounts, symbols, staff, and trades) provide restore callbacks; future participants must register their own restore callback before they can be restored safely.