droboticflow/docs/drosync/conflicts-runbook.md

2.1 KiB

Conflict runbook

Normal client conflict

A tracked target with a different local MD5 is denied during planning. The client reports the conflicting path and preserves the existing cloud object; it does not upload the changed content. An existing untracked target is also rejected. A conditional create race can return HTTP 412; it never degrades to unconditional overwrite.

Historical or explicitly managed conflict objects may use {original}.__conflict__{UTC}_{shortItemId}. Do not assume that ordinary current-client synchronization creates such a copy. Distinguish these existing records from a new deny_archived_hash_change warning.

Administrator force overwrite

Force overwrite is disabled by default. It can only be enabled after the space is update_enabled, the administrator has confirmed exclusive ownership of the prefix, and allowForceOverwrite is explicitly set. The action creates a separate immutable operation item, copies from the preserved conflict object to the logical target with a fresh conditional ETag check, and keeps the conflict object. A concurrent write returns a precondition failure and must be reviewed again; it never degrades to an unconditional overwrite.

Operator procedure

  1. Open /object-sync → Conflicts and identify the session/item.
  2. Compare the original and conflict object using recorded MD5, size, source mtime, ETag, and versionId. Do not interpret multipart ETag as a full-file MD5.
  3. Decide outside drosync which business object should become canonical.
  4. If a manual BOS operation is required, record the change ticket and then run space reconciliation.
  5. Keep the space disabled if reconciliation reports drift. Re-run capability probe only on its dedicated temporary key.
  6. Re-enable create or update only after the gate is again satisfied.

Conflicts are never deleted automatically. Session abort and rollout rollback also do not delete them.

Lease incident

Force release only after verifying the owning daemon is stopped or its credential is revoked. The permanent fencing counter remains and increments on the next acquire; releasing a lease cannot validate an older token.