droboticflow/docs/drosync/update-rollout.md

6.8 KiB

Signed updates and rollback — 1.0.7

Device entry points are update check/install/pin/unpin/pause/resume/rollback. Platform rollout controls software offers; it never installs on devices. The release workflow is POC-only and refuses refs other than refs/heads/poc.

Immutable signed payload and mutable rollout

Only manifest v2 is accepted. Ed25519 signs the following ordered JSON fields:

manifestVersion, id, version, kind, protocolVersion, minimumServerVersion, minimumStateSchema, maximumStateSchema, artifacts, sha256.

Map keys are lexically sorted. The four keys are exactly linux-x86_64, linux-arm64, macos-arm64, windows-x86_64. IDs are explicit ASCII; signed artifact URLs are stable ASCII HTTPS without credentials; encode paths before signing. No default can modify a signed field. channel, rolloutPercent, paused, server timestamps, owner and revision are outside this payload. A real Rust signer fixture is verified by the Go API regression test, including URLs containing ampersands.

POST /api/object-sync/client-releases only registers immutable releases. Signed registration starts at canary/5%/unpaused; preview uses preview/100%/unpaused and empty signature. Re-registering identical content returns the existing policy. A different ID cannot register the same v2 kind/version. Retained historical v1 database records are not accepted by the v2 distribution/update path.

PUT /api/object-sync/client-releases/{id}/rollout is the policy endpoint: channel, rolloutPercent, paused and expectedRevision. Only the owning organization can mutate it. Conflicting revisions return 409 and require refresh. Forward progression is canary 5% → pilot 20% → stable 100%, with 24 active hours at each preceding stage. Resume restarts the observation clock; reverting a stage is immediate. Policy changes leave signatures valid. Expand based on actual device/queue/error evidence, not just elapsed time.

Build and publish

.gitea/workflows/drosync-release.yml checks the committed version, format/lint/tests, and exact POC ref. It builds Linux x86_64/ARM64 DEB, macOS ARM64 signed/notarized PKG and Windows x86_64 Authenticode MSI. Every build emits drosync.build.json; the Cargo version and package version must agree. Public Ed25519 trust is compiled into each target. Native signing material remains in CI secrets.

The publish job aggregates all four artifacts, calculates their final hashes, publishes to immutable BOS keys, reads the public bytes back and rechecks hashes, invokes the Rust signer, then logs into the POC API, registers and reads the manifest back. The publisher is scripts/drosync-release-publisher; its fake-storage/API tests verify this sequence without publishing anything. Existing mismatched objects or registrations fail rather than being overwritten. Registration readback compares immutable fields and signature, so a retried run does not undo an operator's later rollout policy.

Configure the API's DROSYNC_UPDATE_SIGNING_PUBLIC_KEY to the same base64 Ed25519 public key compiled into clients. The Kubernetes renderer carries this public key into the API ConfigMap/environment. Missing API trust rejects signed registration. The manifest schema is update-manifest.schema.json.

Candidate, preparation and installation

update check verifies signed candidate metadata, platform, current server minimum and SQLite schema bounds; offers must be strictly newer SemVer than the running client. Pin selects that exact newer version; pause blocks preparation. Check returns effective policy and ledger. It downloads no artifact.

Preparation downloads into a unique temporary file, checks length/hash, and atomically publishes a verified cache entry under the update lock. It validates native signatures. Before the first replacement it fetches a trusted v2 manifest and package for the exact running version as the rollback baseline. If that baseline cannot be verified, installation does not proceed. A first migration from v1 signing therefore needs an explicit native bootstrap; there is no old-signature fallback.

The state ledger stores current/previous/pending/last attempt as one transactional record. Preparing/reserving installation interlocks upload scheduling and auth reconfiguration. Package availability is not installation success. The daemon never elevates or installs: CLI holds a single installer lock from plan acquisition through authorization, readiness and any recovery.

The privileged installer copies the artifact into a private directory, rechecks the fixed signed SHA256 and native signature, then invokes the OS package manager. Its stdout is kept out of CLI JSON. After installer success, CLI confirms the attempt and waits up to 90 seconds for the correct daemon version, binary build identities and committed attempt receipt. An authorization-pending attempt cannot be marked installed merely because files happen to match. An OS reboot-required result retains that state until a real restart.

If the target does not become ready, the CLI attempts one verified baseline recovery and reports the failed update with its recovery outcome. If the daemon cannot serve IPC, update check reads local recovery state and update rollback uses the verified offline recovery path. Late receipts cannot overwrite a newer attempt. Recovery failure remains visible and keeps the installation interlock; it is not reported as success.

Rollback and supported formats

update rollback requires the recorded previous/baseline package, valid v2 signature, expected platform, digest, native signature and compatible local state schema. It uses the same OS authorization and readiness path. Rollback/recovery pins the restored version. It does not roll back source files, uploaded objects or SQLite schema. A release whose schema may move beyond its baseline's supported maximum is refused for automatic update; perform an explicit backed-up migration instead.

Only installer-marked native packages self-update. Linux portable stays on its single portable installer; preview is manual test delivery. Windows user-startup and Linux user-service installation modes are removed. No package guesses an old path or converts install formats in the background.

Source tests and fake installers do not establish certificate trust, UAC/sudo approval, real service restart or BOS throughput. Real signed installation/update/rollback on all four targets remains release acceptance and must be recorded separately.

1.0.6 metadata, timeout and BOS recovery changes: repair and verification.

1.0.7 当前新增能力和配置迁移以 V1.1 需求逐项实现 和 运行配置完整清单 为准;本页引用的 1.0.6 验证数量仍仅代表历史版本。