Cross-server snapshot transfer

[sjmiller609]

Summary

• add a new snapshottransfer subsystem implementing source-initiated async push transfers with durable job/session state
• add sparse-aware manifest + chunk protocol with resumable destination import sessions
• add transfer/session APIs (source + destination protocol) and wire through config/providers/app startup
• add OpenAPI schemas/routes and generated server/client bindings
• add unit and API tests for transfer lifecycle, preflight, chunk ordering/idempotency, recovery, and end-to-end manager flow

Key behavior

• push-only v1 transfer initiation (POST /snapshots/{snapshotId}/transfers)
• synchronous destination preflight before async job acceptance
• strict standby compatibility gate in destination preflight
• resumable chunk upload + destination session progress query
• cancel propagation source->destination and cleanup of partial session data
• import-only destination finalization to snapshot store

Validation

• go test ./lib/snapshottransfer/...
• go test ./cmd/api/api -run 'SnapshotTransfer|SnapshotImportSession' -count=1
• remote (deft-kernel-dev) targeted suite:
  • go test ./lib/snapshottransfer/... -count=1
  • go test ./cmd/api/api -run "SnapshotTransfer|SnapshotImportSession" -count=1

(Repository-wide make test-linux currently has pre-existing unrelated integration instability on the host; targeted transfer suite passes.)

---

Note

Medium Risk
Introduces new authenticated data-transfer endpoints and a background manager, and adjusts hypervisor snapshot config rewriting and Linux netlink address querying, which could affect snapshot restore/fork and networking if edge cases were missed.

Overview
Adds cross-server snapshot transfer support to the API by wiring a new snapshottransfer.Manager into ApiService, starting it at app boot, and exposing endpoints to start/list/get/cancel transfers and to manage destination-side import sessions (preflight, create/get, chunk upload, complete, cancel).

Extends configuration with snapshot_transfer.max_concurrent (defaults + validation + example configs) and adds targeted API tests for transfer and import-session behaviors.

Improves snapshot fork path rewriting for both Cloud Hypervisor and QEMU by also rewriting references to the snapshot data root (e.g., /system, /images paths), and hardens Linux bridge state detection by retrying netlink.AddrList on intermittent dump interruptions; formatTcRate is moved into lib/network/rate.go for reuse.

^{Written by Cursor Bugbot for commit a1b03f0. This will update automatically on new commits. Configure here.}

[github-actions]

✱ Stainless preview builds

This PR will update the hypeman SDKs with the following commit message.

feat: Add push-based resumable cross-server snapshot transfer

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ hypeman-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅

New diagnostics (10 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshots/{snapshotId}/transfers`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /snapshot-transfers`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /snapshot-transfers/{transferId}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-transfers/{transferId}/cancel`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-import-sessions/preflight`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-import-sessions`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /snapshot-import-sessions/{sessionId}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `put /snapshot-import-sessions/{sessionId}/chunks/{chunkIndex}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-import-sessions/{sessionId}/complete`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-import-sessions/{sessionId}/cancel`

✅ hypeman-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/hypeman-typescript/54f54efde028603fa1ad3e6fc80895b0d21bee18/dist.tar.gz

New diagnostics (10 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshots/{snapshotId}/transfers`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /snapshot-transfers`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /snapshot-transfers/{transferId}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-transfers/{transferId}/cancel`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-import-sessions/preflight`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-import-sessions`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /snapshot-import-sessions/{sessionId}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `put /snapshot-import-sessions/{sessionId}/chunks/{chunkIndex}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-import-sessions/{sessionId}/complete`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-import-sessions/{sessionId}/cancel`

✅ hypeman-go studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

go get github.com/stainless-sdks/hypeman-go@27e294ec8ee374c4bca2dc98cd099b810f757685

New diagnostics (10 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshots/{snapshotId}/transfers`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /snapshot-transfers`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /snapshot-transfers/{transferId}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-transfers/{transferId}/cancel`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-import-sessions/preflight`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-import-sessions`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /snapshot-import-sessions/{sessionId}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `put /snapshot-import-sessions/{sessionId}/chunks/{chunkIndex}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-import-sessions/{sessionId}/complete`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /snapshot-import-sessions/{sessionId}/cancel`

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-03-17 18:06:26 UTC

[cursor]

Automated risk assessment: High risk.

Why this is high risk (from code diff evidence):

• Introduces a new cross-server snapshot transfer subsystem in lib/snapshottransfer with substantial new production logic (manager, store, manifest, session state, error handling).
• Adds new API handlers/routes and request flow in cmd/api/api/snapshot_transfers.go plus OpenAPI contract changes in openapi.yaml and regenerated bindings in lib/oapi/oapi.go.
• Wires new behavior through app startup/config/providers (cmd/api/main.go, cmd/api/config/config.go, lib/providers/providers.go, cmd/api/wire*.go) and touches hypervisor snapshot fork paths.
• Large multi-file behavioral change with async/resumable transfer semantics and broad blast radius.

Decision:

• Code review required.
• Not auto-approving (High-risk PRs are never auto-approved).
• Requested reviewers: @rgarcia, @hiroTamada.

---

  

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}